Hotblocks behavioral spec + implementation audit (GAP-1..34)

[mo4islona]

The implementation-free behavioral specification of hotblocks — 15 documents under crates/hotblocks/spec/: state model (DEF-), write/read paths (WP-/RP-), consistency & durability (CN-), the invariant catalog (INV-1..44), liveness (LIV-1..12), failure model (FM-), retention/space (RS-), performance (SLI-/HZ-), observability (OB-), the conformance/TDD plan (CT-1..9, reference-model oracle, traceability matrix, gap register), the HTTP binding (IB-), and the parameter registry (P-*).

Also included: audit-2026-07-12.md — a full spec↔implementation audit (every layer read against the spec: service, data-source/client, storage, query). Its outcomes are already folded into the normative text and the register:

Spec fixed where the implementation was right:

• RP-5b — an anchored query at from == head+1 (fin+1 for finalized-only) with a mismatched parent gets an immediate 409, before the head-wait; generalizing above the boundary would false-conflict merely-ahead clients.
• RP-9 — the coverage carrier is emission itself: the coverage-end block is always emitted (header-only when unmatched); extra boundary markers are layout-dependent and exempt from INV-22 determinism (with the matching CN-13/INV-17/INV-22 carve-outs and model changes).
• WP §2.5 — a downward retention bound is legalized as an explicit, alarmed RESET (the code's "dropping everything by design"), with boot-time Pinned refusal; finality note clarifies this is not a rollback below fin.
• WP-6 — rollback may be batch-granular (chunk-boundary hint matching).

Register (now GAP-1..34):

• GAP-22 → P1: a deep fork on a Window dataset can silently replace the finalized prefix (fallback ignores fin + composed-finality guard bypass in new_chunk + anchor hash dropped on trims = GAP-23); otherwise the epoch parks on the blind 60 s loop.
• GAP-6 → P2: runtime reclaim landed in Reclaim hotblocks disk: point-delete cleanup + startup DeleteFilesInRange #79 (10 s point-delete sweep + compaction); the residue purge / file unlink remain boot-gated.
• New GAP-23..34: boot containment (one dataset's failure kills the service), ingest crash-loop on out-of-range block timestamp, finality accepted below the window, non-durable Api retention, zombie-client snapshot pinning, missing strike/quarantine substrate, and more — each with violated IDs and a first failing test.
• GAP-2/4/8/9/11/20/21 corrected with exact mechanisms and code references.

Harness README: first four CT-4 scripts planned (shallow-reorg fin-stability first — pins that a fork can never blip /finalized-head; then GAP-22/GAP-3/GAP-4 failing-first cases); the "header-only records" open question is resolved (it is the RP-9 carrier).

Stacked on #84 (touches the harness README) — retarget to master after #84 merges. Docs only, no code changes.

🤖 Generated with Claude Code