Module diagnostics 

Read-only-by-intent database-integrity and WAL/checkpoint diagnostics. Non-mutating-by-intent database, WAL, and checkpoint diagnostics (read-only operator surface).

Answers “is a reader pinning the checkpoint / why is the WAL at 64MiB” without raw SQL against a production store.

NOT read-only. checkpoint_probe issues a real PRAGMA wal_checkpoint(PASSIVE), and a PASSIVE checkpoint that succeeds BACKFILLS WAL frames into the main database — ordinary database-page writes, on the happy path. That I/O is the point: the busy/log_frames/ checkpointed_frames triple reports a one-row backfill gap; a sustained pinned-frame report additionally requires a matching checkpoint run. SQLite exposes no read-only API for those counters. The guarantee is that nothing here changes logical state or destroys evidence, not that nothing touches the disk.

What IS guaranteed, and what the narrowings below buy:

• never creates a missing database file,
• never escalates to TRUNCATE,
• never perturbs the counters it reports,
• never increments write-traffic acquisition counters,
• never deletes a walpin sidecar entry.

Deliberate narrowings make those claims true rather than aspirational:

1. checkpoint_probe runs a single PRAGMA wal_checkpoint(PASSIVE) — which never blocks readers or writers — and does NOT route through crate::checkpoint::checkpoint_once: that path mutates TruncateState, may escalate to TRUNCATE, and double-counts the ADR-091 process-global counters. A verb that reports state must not perturb the state it reports.
2. The probe’s connection comes from ConnectionPool::open_standalone_writer_untracked, opened without SQLITE_OPEN_CREATE. A missing database yields checkpoint_probe: null plus a checkpoint_probe_error, never a freshly created file.
3. WAL-pin attribution combines the read-only OS holder census with walpin::inspect_live, a separate bounded sidecar enumerator whose purpose flag prohibits every unlink. It applies the same descriptor- bound trust and liveness checks as checkpoint attribution, but reports stale cleanup candidates rather than consuming them. A complete census plus a complete, conclusive sidecar walk can therefore report complete; truncation, unknown entries, or holders absent from the sidecar degrade explicitly.
4. Graph-edge integrity uses three scalar SELECTs on the same guarded standalone connection. It exposes the exact pre-V14 duplicate-ID group count plus raw live-edge/list-ledger counts and never repairs or deletes data.
5. FTS5 segment diagnostics decode each index’s documented one-row structure record (%_data.id = 10). They never run COUNT(*) over or scan a %_idx table, so observing segment health is bounded even when the corpus itself is large.

Checkpoint counters are process-global, while reader and writer acquisition counters belong to the supplied pool and can reset when it is reconstructed. Every payload carries BuildIdentity and ProcessIdentity for the process producing the reading. The PID, OS start time, and main-pool generation identify the main pool’s counter window; a secondary pool’s reader/writer counters have their own reconstruction window. Checkpoint counters remain global.

Structs

BuildIdentity

Which build produced this reading.

CheckpointCounters

ADR-091 checkpoint counters, read as one snapshot.

CheckpointPinDiagnostics

Checkpoint-row evidence used to report a sustained backfill ceiling.

CheckpointProbe

Raw PRAGMA wal_checkpoint(PASSIVE) return row.

CollectionCost

What this report cost to assemble, per section, in milliseconds.

DatabaseObjectSize

DatabaseSizeComposition

Page-accounted file-size composition from SQLite’s read-only dbstat virtual table in aggregate mode.

DbDiagnostics

DiskGuardDiagnostics

The configured write-admission reserve and the volume metadata used to sample it. The reserve is an admission floor, not reserved disk capacity.

GraphEdgeIntegrity

Live graph-edge rows compared with the durable list-cursor ledger.

ProcessIdentity

The serving OS process and the main pool’s reader/writer counter generation.

ReaderContentionDiagnostics

One typed snapshot of reader route, saturation, and hold-lifecycle signals.

RuntimeAuditBatchMetrics

Process-wide audit-batch health counters, supplied by the runtime layer that owns the audit-batch control. khive-db never produces these itself — a direct khive-db caller always sees the corresponding WriterContentionDiagnostics fields as None plus an explicit reason.

WalCeilingDiagnostics

The full database-integrity, reader/writer-contention, and WAL/checkpoint payload.

WalFileState

Absolute-free WAL file state for one database path.

WalPinAttribution

WAL-pin attribution: who currently holds the database open, and how complete that answer is.

WalPinCensusProcessStart

OS-reported start time for one holder confirmed by the process census.

WalPinHolder

One PID’s live heartbeat as reported to an operator.

WriterContentionDiagnostics

One typed snapshot of writer-contention signals.

Enums

DatabaseObjectKind

SQLite b-tree role reported by the size-composition diagnostic.

DatabaseStorageClass

Operational storage grouping. mixed_row_and_embedding is deliberately separate: SQLite cannot attribute bytes within a table page to one column, so counting all of knowledge_sections as pure vector bytes would be a false precision claim.

WalPinAttributionStatus

Overall quality of the WAL-pin attribution answer.

WalPinCensus

Tagged OS holder-census result.

Functions

checkpoint_counters

Snapshot the process-global ADR-091 counters.

checkpoint_probe

Issue one PASSIVE checkpoint on conn and return the raw triple.

collect

Assemble the report for pool’s database.

collect_with_audit_append_failures

Assemble the report with the runtime’s process-wide count of swallowed best-effort audit append failures.

collect_with_audit_append_failures_interruptibly

Assemble diagnostics without allowing request abandonment to leave the graph SELECT or OS holder census running detached.

collect_with_runtime_audit_metrics_for_process_interruptibly

Collect one already-open pool while retaining the main pool’s process and generation identity. A secondary pool must not claim or advance the main pool generation when its pool-scoped counters are inspected.

collect_with_runtime_audit_metrics_interruptibly

Like collect_with_audit_append_failures_interruptibly, additionally threading through the runtime’s audit-batch health counters. None when no audit-batch control is registered with the calling runtime instance — the corresponding writer_contention fields then report unavailable with a reason, exactly like audit_append_failures does for a direct khive-db caller.

wal_file_state

Stat <db_path>-wal and report its size in bytes.

wal_pin_attribution

Build the WAL-pin attribution for db_path.