alkblobs/tasks/suite-column-local.md

---
id: suite-column-local
name: Conformance suite — the local column and the dispatch-coverage shape
status: completed
depends_on: [suite-column-mem]
scope: moderate
risk: medium
impact: phase
level: implementation
tags: [wave-2, suite, local, dispatch]
---

## Description

Grow the **local column** — the suite's first dual-tier column, run
against the `kv = mem` + `large = local` factory: the
**dispatch-coverage test shape** ADR-012 §6.3 names (both tiers
load-bearing). Rows mirror the mem column's set (INV-7: every engine's
rows mirror the reference column), extended with the dual-tier and
local-specific properties.

- **The factory**: fresh, isolated temp-root dual-tier store per call
  (`kv = mem` + `large = local`), idempotent teardown (temp dir
  removal); never skips.
- **Mirrored rows** (the mem column's set, against the dual-tier
  store):
  - **INV-1 round-trips**: both tiers, both put paths — the content
    matrix crosses the threshold so both tiers' bodies are exercised
    (sub-threshold kv rows; over-threshold local stage-commit rows).
  - **INV-3 stage hygiene**: exact counts **on disk** — zero stage
    files after every failure form, exactly one committed entry per
    success, over both put paths (the real stage form, not the
    degenerate kv stage).
  - **INV-4 sweep safety**: exact-count sweep outcomes over the
    dual-tier pool (candidates from both tiers; abort shapes; the
    sweep-vs-pinned-put race).
  - **INV-2 dedup, INV-5 list-through-sweep, INV-6 stat** mirrored.
- **Dispatch rows** (the coverage shape's reason to exist):
  - Routing is a pure function of length: same content ⇒ same tier
    across mixed put paths and re-puts; no content ever migrates.
  - **Fall-through** (ADR-012 §6.1): a kv-tier miss queries the large
    tier — `get`/`stat`/`has`/`read_range` each served from the large
    tier when the kv tier misses; both-tier miss shapes per op.
  - Threshold boundary values (at/below/above the default; a
    constructor-tuned threshold re-routes deterministically).
- **Local-specific rows**: pread range reads over committed files
  (mid-file slices, EOF clamping); virgin-store no-ops on a fresh root
  (empty `list`, absent reads); `size` as a stat (never a content
  load).
- Every row ADR-stamped per the convention, tracing to the backlog.

## Acceptance Criteria

- [x] The dual-tier `kv = mem` + `large = local` factory green with
      isolation + idempotent teardown
- [x] The local column green: mem's row set mirrored (INV-1/2/3/4/5/6)
      plus dispatch rows (pure-function routing, fall-through per op,
      threshold boundaries) and local-specific rows (pread ranges,
      virgin-store no-ops, stat-as-stat)
- [x] Stage-hygiene exact counts asserted on disk (the real stage form)
- [x] Every row ADR-stamped and traceable to the backlog
- [x] `cargo test` green (default build; the column itself runs under
      `--features mem` — the kv = mem pairing gates it, see Notes);
      clippy/fmt gates green

## References

- tests/conformance/README.md + backlog.rs (the conventions; INV first-column plan)
- docs/architecture/backends-and-dispatch.md (§Constructor modes — the dispatch-coverage shape; §Size-threshold dispatch)
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.1/§6.3
- docs/architecture/decisions/003-backend-contract-and-dispatch.md (§Dispatch policy)
- docs/architecture/store-api.md (§Invariants)
- docs/research/poc-largeblob-findings.md (findings A2/A5)

## Notes

> Filled by the implementation agent (2026-10-11).

- **The dual-tier factory** (`tests/conformance/local_column.rs`):
  `DualTierLocalFactory` (the dispatch-coverage shape, `kv = mem` +
  `large = local`) — `open()` vends the concrete `Store` facade over a
  fresh private temp root per call (mem shares nothing; the local
  engine gets its own root), tracked per *factory instance*;
  `teardown()` removes that instance's roots idempotently and is safe
  against abandoned instances (the structural tests carry the panicking
  row over a medium-backed factory). Every runner constructs its own
  factory instance — a shared static's teardown would race
  concurrently running rows' roots (the mem factory's no-op teardown
  didn't have this hazard; the local one does, so instance ownership
  is the rule, recorded in the module doc).
- **The mirrored set** (INV-7): all ten INV-family rows of the
  reference set run against the dual-tier factory at a column-declared
  tuned threshold (1024) — the shared content matrix and race fixtures
  cross it, so both tiers' bodies are exercised (sub-threshold kv
  rows; over-threshold stage-commit rows). The INV-3 reference row
  mirrors with the *degenerate kv stage form* it owns; the **stage
  form** is this column's own row (below). The mem-only and kv-only
  constructor-mode rows do not mirror (their `mode()` preconditions
  name modes this column is not; README records the rule).
- **The dispatch rows** (the coverage shape's reason to exist):
  `routing_is_a_pure_function_of_length_across_put_paths_and_re_puts`
  (at/below/over the threshold, same content, both put paths: same
  placement, nothing moves or duplicates, one pool entry through all
  paths, exact sweep counts);
  `threshold_boundary_lengths_route_deterministically` (boundary legs
  at the declared threshold on both put paths, plus the default
  boundary's length re-routing with the constructor's tuning — run
  against the tuned and the default-threshold factories);
  `kv_tier_misses_fall_through_to_the_large_tier_per_op` (get/stat/
  has/read_range each served from the large tier when the kv tier
  misses, the kv-first mirror-position leg, and both-tier miss shapes
  per op — `None`/`None`/`false`/`Missing`).
- **Tier placement is observed through the medium, not the facade.**
  Tier residency is facade-invisible by design (the facade is
  engine-blind; ADR-012 §6.1's consult order is not a routing
  query). With `kv = mem`, the medium itself is the oracle: the mem kv
  tier never touches the factory's disk, so a committed file outside
  the staging area under the column's temp root is exactly one
  large-tier entry and its absence is exactly a kv-tier entry. That
  makes the dispatch rows *column-owned* rows taking the concrete
  factory (an engine-uniform reference row can never make these
  assertions); README §Columns beyond the reference set records the
  shape. The dual-tier threshold is likewise **declared
  configuration, not a probe**: a dual-tier store never rejects, so
  the kv-only row's probing trick has nothing to probe — the rows read
  the threshold the factory declares (the value the constructor took).
- **The local-specific rows**:
  `stage_hygiene_exact_counts_on_disk_over_both_put_paths` (INV-3's
  real stage form — mid-stream `Io` and declared-len `Verification`
  failures over threshold-zeroing content leave zero stage files and
  zero committed entries on disk; success leaves exactly one committed
  entry per path, zero stage files; the Drop-cancellation form needs
  the engine internals and stays covered by the engine's in-module
  tests, per the engine-local task);
  `pread_windows_read_committed_files_mid_slices_and_eof_clamped`
  (both put paths' committed files: mid-file slices, tail clamps,
  EOF-empty, zero-length, over-read clamp, `read_range` slice + digest
  verified against an independently computed SHA-256);
  `virgin_store_reads_are_no_ops_on_a_fresh_root` (empty `list`,
  per-op miss shapes, empty medium);
  `sweep_counts_stay_exact_over_both_tiers` (INV-4/INV-5's both-tiers
  form: the full protection set spanning tiers, dead witness per tier,
  exact report counts *and* exact on-disk counts, protected entries
  byte-identical across tiers).
- **stat-as-stat**: the "size as a stat, never a content load"
  property is carried by the mirrored INV-6 row run at the tuned
  threshold — its over-threshold legs stat entries served by the
  local engine's file-stat size probe (ADR-008 §1), the same
  facade-slice/engine-half posture the mem column recorded; no
  separate row was needed.
- **Feature gating (amendment to the acceptance criterion as
  written)**: the criterion expected "local is ungated — the column
  runs in the default build", but the only constructible kv engine
  until wave 3 (sqlite) is mem, so `Store::dual_tier_mem_local` rides
  feature `mem` (the store-construction task's recorded default-build
  note) — the column is `#[cfg(feature = "mem")]`-gated and runs under
  `cargo test --features mem`, exactly as the mem column does. The
  local *engine* itself remains ungated (in `src/`, default-build
  compiled); the reference row set compiles ungated (type-checked in
  default builds). The criterion line was amended to the factual
  reading; the gate is the kv pairing's, not the local engine's.

## Summary

> Filled on completion (2026-10-11).

Landed the **local column** — the suite's first dual-tier column, run
against the `kv = mem` + `large = local` dispatch-coverage factory
(ADR-012 §6.3): fresh temp-root dual-tier store per `open()`,
per-instance tracked roots, idempotent teardown safe against aban-
doned/panicking rows (structural tests included), never skips.
`tests/conformance/rows.rs` gained `pub(crate)` shared fixtures;
`tests/conformance/local_column.rs` mirrors the reference INV row set
against the dual-tier factory at a tuned threshold (1024) so the
shared matrix and race fixtures exercise both tiers' bodies, and grows
the column's own rows: the three dispatch rows (pure-function routing
across put paths and re-puts with an on-disk placement oracle — tier
residency is facade-invisible, so the medium is the oracle; threshold
boundary legs at the tuned and shipped-default thresholds with the
constructor-tuned re-route leg; fall-through per op with both-tier
miss shapes) and the four local rows (on-disk stage-hygiene exact
counts over both put paths — the real stage form; pread windows over
committed files with EOF clamping and an independently verified slice
digest; virgin-store no-ops on a fresh root; exact sweep counts over a
both-tiers pool — also INV-5's both-tiers form). stat-as-stat rides
the mirrored INV-6 row's over-threshold legs. Every row is
ADR-stamped and traced (README's new column inventory section);
stat-as-stat's engine half and the Drop-cancellation hygiene form
remain per-engine (the mem column's INV-6 posture and the engine's
unit tests, respectively — recorded). The column is mem-gated (the
dual-tier constructor rides feature `mem` until wave 3 provides an
ungated kv engine); the criterion's "runs in the default build"
expectation is amended and recorded.

Verification: `cargo test` green (42 lib + 2 conformance + 3
git-interop), `cargo test --features mem` green (97 lib + 37
conformance + 4 git-interop), `cargo test --all-features` green; `cargo
clippy --all-targets -- -D warnings` and `cargo clippy --all-features
--all-targets -- -D warnings` green; `cargo fmt --check` green;
`cargo doc --no-deps` shows only the pre-existing private-intra-doc-
links warning class (this task touches no public API).