ci: deny rustdoc breakage — workspace lints + a cargo doc job

.github/workflows/ci.yml

@@ -36,6 +36,23 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo clippy --all-targets --all-features -- -D warnings
 
+  docs:
+    name: cargo doc
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # The [workspace.lints.rustdoc] levels are the single source of
+      # truth: the deny-level lints (broken intra-doc links etc.,
+      # #124) fail this build on their own; no RUSTDOCFLAGS override,
+      # so `bare_urls = "warn"` stays advisory in CI too.
+      - run: cargo doc --workspace --no-deps --all-features
+
   test:
     name: cargo test
     runs-on: ubuntu-latest
@@ -155,7 +172,7 @@ jobs:
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
-    needs: [fmt, clippy, test, book, semconv]
+    needs: [fmt, clippy, docs, test, book, semconv]
     if: always()
     steps:
       - name: Verify required checks

.gitignore

@@ -22,6 +22,10 @@
 # scheduled-task lock file is per-machine ephemera that leaked into
 # PR #62 once and shouldn't again.
 /.claude/scheduled_tasks.lock
+# Per-machine permission allowlist — same leak class (swept into a
+# PR by `git add -A` once); the tracked `.claude/` content above is
+# unaffected.
+/.claude/settings.json
 
 # Cargo.lock is NOT ignored — Ourios is a binary (CLAUDE.md §1) and its
 # lockfile is part of the reproducible-build contract.

Cargo.toml

@@ -22,5 +22,16 @@ repository = "https://github.com/jensholdgaard/ourios"
 [workspace.lints.rust]
 unsafe_code = "deny"
 
+# Rustdoc breakage (broken intra-doc links etc.) kept reaching review
+# as Copilot comments the compiler could have raised first (#124).
+# All member crates declare `[lints] workspace = true`, so this
+# propagates without per-crate edits; `cargo doc --workspace
+# --no-deps --all-features` is the local check.
+[workspace.lints.rustdoc]
+broken_intra_doc_links = "deny"
+private_intra_doc_links = "deny"
+invalid_rust_codeblocks = "deny"
+bare_urls = "warn"
+
 [workspace.lints.clippy]
 pedantic = { level = "warn", priority = -1 }

crates/ourios-bench/src/store.rs

@@ -3,7 +3,7 @@
 //! The A1 path measures the bytes a corpus compresses to; the B1/B2
 //! latency benches need to *query* the same corpus, so they need the
 //! mined records laid down as a real partitioned Parquet store they
-//! can point a [`ourios_querier::Querier`] at. Both public builders
+//! can point a `ourios_querier::Querier` at. Both public builders
 //! reuse the same corpus loader and miner harness the gates run on
 //! (so the store matches what A1 measured), then write every emitted
 //! record via per-partition [`Writer`]s (the same streaming write A1
@@ -32,7 +32,7 @@ const ERROR_BAND: std::ops::RangeInclusive<u8> = 17..=20;
 #[derive(Debug, Clone, Copy)]
 pub struct BuiltStore {
     /// Tenant every record was written under (the corpus loader is
-    /// single-tenant — [`crate::corpus`]'s `BENCH_TENANT`). A query must
+    /// single-tenant — `crate::corpus`'s `BENCH_TENANT`). A query must
     /// use this tenant or it scans nothing (RFC0007.5 isolation).
     pub tenant: &'static str,
     /// Total rows written across all partitions.
@@ -55,7 +55,7 @@ pub struct BuiltStore {
 
 /// Load the corpus at `corpus_dir`, mine it, and write the emitted
 /// records as a partitioned RFC 0005 Parquet store under
-/// `bucket_root` (which a [`ourios_querier::Querier`] can then be
+/// `bucket_root` (which a `ourios_querier::Querier` can then be
 /// rooted at). Returns a [`BuiltStore`] summary.
 ///
 /// # Errors

crates/ourios-core/src/audit.rs

@@ -368,7 +368,7 @@ pub struct SlotExpansion {
 /// The byte layout is private; the public surface is value-based
 /// (`singleton`, `insert`, `contains`, `iter`, `is_empty`, `union`)
 /// so the layout can change without breaking callers. A new
-/// `ParamType` variant forces an update to [`SlotTypes::bit`] —
+/// `ParamType` variant forces an update to `SlotTypes::bit` —
 /// the compiler enforces totality via the exhaustive match. Eight
 /// variants fit a `u8`; if the alphabet grows past eight, widen the
 /// backing integer here (the same exhaustive match will fail to
@@ -478,7 +478,7 @@ pub struct AuditEvent {
     pub payload: AuditPayload,
 }
 
-/// Truncated blake3 of `bytes` for [`AuditEvent::triggering_line_hash`].
+/// Truncated blake3 of `bytes` for `AuditEvent::triggering_line_hash`.
 ///
 /// Returns the first 16 bytes of the blake3 digest. Centralised here
 /// so every producer (and the future WAL-side joiner) uses the same
@@ -495,7 +495,7 @@ pub fn hash_triggering_line(bytes: &[u8]) -> [u8; 16] {
 /// First 256 *bytes* of `raw`, truncated at the nearest preceding
 /// UTF-8 char boundary so the result is always valid `String`.
 ///
-/// Helper for populating [`AuditEvent::triggering_line_sample`] per
+/// Helper for populating `AuditEvent::triggering_line_sample` per
 /// the RFC §6.4 "first 256 B of `L_raw`" rule. Bytes — not chars —
 /// so the bound on the audit-stream's per-event size is predictable
 /// regardless of the input's multibyte content.
@@ -599,7 +599,7 @@ impl AuditSink for InMemoryAuditSink {
 /// still has a handle for inspection.
 ///
 /// `Clone` yields another handle to the *same* buffer — that's the
-/// whole point: hand one clone to [`MinerCluster::with_audit_sink`]
+/// whole point: hand one clone to `MinerCluster::with_audit_sink`
 /// and keep another to drain after the act. `InMemoryAuditSink`
 /// alone would require `&mut self` to drain, which the trait-object
 /// indirection on the producer side rules out.

crates/ourios-miner/src/cluster.rs

@@ -1,6 +1,6 @@
 //! Per-tenant template cluster.
 //!
-//! Holds one [`TenantState`] per [`TenantId`] (`[CLAUDE.md §3.7]`):
+//! Holds one `TenantState` per [`TenantId`] (`[CLAUDE.md §3.7]`):
 //! every ingested record is keyed on its tenant, and per-tenant
 //! template *stores* are isolated — no template ever crosses
 //! tenants. The `template_id` allocator, by contrast, is
@@ -91,7 +91,7 @@ pub const NO_TEMPLATE: u64 = 0;
 
 /// A multi-tenant in-memory miner.
 ///
-/// Holds one [`TenantState`] per [`TenantId`]; per-tenant state
+/// Holds one `TenantState` per [`TenantId`]; per-tenant state
 /// is allocated lazily on the first `ingest` call for that
 /// tenant. Tenant deprovisioning (`TenantPaused`,
 /// `TenantDeleted`) is RFC 0001 §9 territory and not in this
@@ -306,7 +306,7 @@ impl MinerCluster {
     }
 
     /// Register a per-tenant [`MinerConfig`] override per RFC 0004
-    /// §3.4. The override is captured by [`TenantState`] at lazy
+    /// §3.4. The override is captured by `TenantState` at lazy
     /// allocation (i.e. on the first ingest for `tenant_id`); set
     /// it before the tenant is first observed.
     ///
@@ -1750,7 +1750,7 @@ impl MinerCluster {
     /// (tree leaves + structured-template entries). Returns 0 for
     /// a tenant the cluster has never seen.
     ///
-    /// O(1): served from the [`TenantState::template_count`]
+    /// O(1): served from the `TenantState::template_count`
     /// cache rather than walking the tree.
     #[must_use]
     pub fn template_count(&self, tenant_id: &TenantId) -> usize {

crates/ourios-miner/src/overflow.rs

@@ -14,7 +14,7 @@
 //! cardinality destroys Parquet's dictionary encoding and bloats
 //! files. The byte-limit + spill-to-body contract is the answer
 //! to the canonical "stack trace in a `params` slot" hazard
-//! ([`docs/hazards.md`] H2).
+//! (`docs/hazards.md` H2).
 
 use sha2::{Digest, Sha256};
 

crates/ourios-parquet/src/audit_record_batch.rs

@@ -497,7 +497,7 @@ fn append_slots(builder: &mut GenericListBuilder<i32, StructBuilder>, slots: &[S
 ///
 /// # Panics
 ///
-/// Structurally impossible. The inner [`ReasonPayload`] is two
+/// Structurally impossible. The inner `ReasonPayload` is two
 /// owned-or-borrowed scalars; `serde_json::to_string` only fails
 /// when the `Serialize` impl produces an error (e.g. an
 /// invalid-UTF-8 map key) which neither field can ever do.

crates/ourios-parquet/src/audit_writer.rs

@@ -169,7 +169,7 @@ impl AuditWriter {
     ///
     /// `append_events` is **not all-or-nothing** across the
     /// sub-batches it issues internally. The slice is chunked
-    /// into [`SUB_BATCH_ROWS`]-sized pieces; if chunk *N* writes
+    /// into `SUB_BATCH_ROWS`-sized pieces; if chunk *N* writes
     /// successfully and chunk *N+1*'s `audit_events_to_batch`
     /// then errors with `Batch`, the events from chunks `0..N`
     /// have already landed in the in-progress row group. Callers

crates/ourios-parquet/src/writer.rs

@@ -208,7 +208,7 @@ impl Writer {
     /// a `RecordBatch`, and forwards to `ArrowWriter::write`.
     ///
     /// **Row-group sizing.** Internally chunks `records` into
-    /// sub-batches of [`SUB_BATCH_ROWS`] (1024) rows and runs a
+    /// sub-batches of `SUB_BATCH_ROWS` (1024) rows and runs a
     /// flush-when-over-threshold check before each sub-batch
     /// write. RFC 0005 §3.5 pins the row-group target at 128 MiB
     /// – 1 GiB uncompressed; chunking + per-sub-batch flush
@@ -230,7 +230,7 @@ impl Writer {
     ///
     /// `append_records` is **not all-or-nothing** across the
     /// sub-batches it issues internally. The slice is chunked
-    /// into [`SUB_BATCH_ROWS`]-sized pieces; if chunk *N* writes
+    /// into `SUB_BATCH_ROWS`-sized pieces; if chunk *N* writes
     /// successfully and chunk *N+1*'s `mined_records_to_batch`
     /// then errors with `Batch`, the rows from chunks `0..N` have
     /// already landed in the in-progress row group. Callers that
@@ -467,7 +467,7 @@ pub enum WriterError {
         op: &'static str,
         /// The primary path the operation was acting on. For
         /// `rename`, this is the *destination*; the source
-        /// path lives in [`Self::source_path`] (when set).
+        /// path lives in `Self::source_path` (when set).
         path: PathBuf,
         /// Secondary path for two-path operations (only
         /// populated for `rename`, where it carries the source