ITER-0002: compressed postings codecs (DeltaVarint + BlockDelta)

[nnunley]

Summary

Phase 2 compressed-postings codec layer — the third iteration in the Phase 2 stack (after #10 wind tunnel and #11 decisions + core IDs). Adds a Codec trait with two implementations over a stable v1 block format, plus the layout decisions that govern it.

Stacked on #11 (phase2-decisions). Until #10/#11 merge, this PR's diff against main includes their commits; review only the leit_postings codec + leit_core TermFreq + DEC-11/12 changes here.

What's in it

• Codec trait + CodecId marker + structured CodecError (crates/leit_postings/src/codec.rs).
• DeltaVarintCodec (CodecId 0): single-stream delta-encoded doc IDs + LEB128 varint TFs.
• BlockDeltaCodec (CodecId 1): fixed 128-doc blocks (DEC-11), each self-contained (first doc absolute) and independently decodable via a per-block header (doc_count, first_doc, last_doc, doc_bytes_len); the header doc-range is validated on decode.
• Hand-rolled LEB128 varint into a type-enforced [u8; 5] buffer. no_std + alloc, no new deps.
• API speaks named segment-resident types SegmentLocalDocId + new leit_core::TermFreq (no anonymous u32); the generic EntityId stays the in-memory abstraction and lowers to SegmentLocalDocId at the segment-write boundary.
• Decode writes into caller-provided &mut Vec<…> buffers — scratch-ownership-agnostic, so the DecodeScratch ownership decision is left to the cursor iteration (marked TODO(ITER-0003)).
• Doc-sorted precondition enforced via checked_sub (deterministic panic, no silent corruption).
• Decisions of record DEC-11 (block boundary strategy) and DEC-12 (v1 layout), grounded in the wind-tunnel Zipfian baseline.

Evidence

• 36 leit_postings tests (cargo test -p leit_postings codec): lossless round-trip for both codecs incl. multi-block (128/129/256/300 docs), byte-size reduction, varint edge cases (u32::MAX, truncation, over-long), bad-marker / corrupt-header rejection, unsorted-input panic.
• no_std verified on aarch64-unknown-none; workspace clippy/fmt clean.

Deferred (carried forward, not dropped)

• advance_to block-skip (cursor layer) and the e2e ranking-equivalence proof → ITER-0003.
• Segment-format reservation of the CodecId marker field → ITER-0004.

🤖 Generated with Claude Code

[waywardmonkeys]

Should Fix

• crates/leit_postings/src/codec.rs:460-494 and :547-579: block decode mutates out_docs before full validation finishes. On malformed input, callers can observe partially decoded docs or non-parallel docs/tfs after Err. That is risky with reusable decode scratch. Either document that output buffers are unspecified on error, or decode a block into temporary lengths and truncate/clear on error.

• crates/leit_postings/src/codec.rs:447 and :543: prefer checked arithmetic for pos + doc_bytes_len. The decoded length is attacker-controlled. On 64-bit this is mostly theoretical due slice-size limits, but this is a malformed-input hardening patch in a no_std crate, so checked_add(...).filter(|end| *end <= bytes.len()) is the calmer invariant.

Could Improve

• decode_block_doc_count is a good extraction, but it advances pos before validating the count. It is only local state today, so fine. A future helper that validates before committing the cursor position would be easier to reason about.

• Add a short doc note to Codec::decode / BlockDecoder::decode_block: “on error, output buffers are unspecified” or “on error, output buffers are cleared.” Pick one and enforce it.

[nnunley]

Addressed the requested malformed-input invariants: checked section arithmetic, block-count and varint hardening, full doc-stream consumption, and transactional decode outputs. Codec and BlockDecoder APIs now guarantee both output buffers are empty on error.