alkblobs/tasks/store-construction.md at 6bce301c558b53d680c8e9d73d960702e528be85

0 Fork 0

Files

T

glm-5.3-flash 6bce301c55 docs(tasks): decompose wave 2 — mem + local engines, facade, in-process GC, first suite columns

Nine tasks against the wave-1 contract surface as reviewed (no
amendments from the gate):

- engine-mem / engine-local (parallel, dependency-free): the two
  engines; local owns the stage-hygiene exact-count tests and the
  Drop-cancellation story the wave-1 review recorded
- store-construction: the Store type, constructor modes, size-threshold
  dispatch; binds the conformance factory's Store associated type
- store-read-paths ∥ gc-protocol: read ops with the ADR-012 §6.1
  fall-through rule; the ADR-005 in-process protocol (pins, liveness,
  delete windows, abort-as-data, GcRefuse with the full protection set)
- store-put-paths: the two put paths behind one signature, ADR-003's
  three numbered rules, pin-before-publish, Batch, kv-only rejection
- suite-column-mem → suite-column-local: the reference column, then the
  dual-tier dispatch-coverage shape mirroring it
- review-wave-2: the gate (facade/dispatch/GC vs ADR-003/005/012)

Verification: dependency graph validated (all ids resolve, no cycles,
topological order clean); docs-only change.

Refs: docs/plans/implementation.md §Wave 2

2026-10-11 21:39:28 +00:00

4.5 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level, tags

name

status

depends_on

scope

risk

impact

level

Description

Introduce the Store facade type (store-api.md §What this is) — the public surface consumers program against — with its constructor modes and the size-threshold dispatch. This task builds the skeleton and routing: the ops methods land in store-read-paths, gc-protocol, and store-put-paths against this type.

The Store type (public, src/facade.rs or a new module — implementer's call, one module per file): holds the kv-tier engine and the large-tier engine (or none, per mode) plus the GC state home the gc-protocol task fills. Named design point — engine representation: a concrete Store with a crate-internal enum dispatching over the closed five-engine set, vs a generic Store<Kv: Backend, Large: Backend>. The conformance factory's binding note (tests/conformance/factory.rs) anticipates the concrete type ("most plausibly the associated type collapsing to the concrete facade type across all factories"); engines are statically known and in-crate (no dyn anywhere, wave-1 design point 3). Decide, record, and keep the public surface engine-blind (ADR-007/008/010: which engines a node runs changes nothing here).
Constructor modes (ADR-011 §4; ADR-012 §6.3):
- dual-tier (the default): kv + large, size-threshold dispatch. Wave-2 constructible shape: kv = mem + large = local — the dispatch-coverage test shape ADR-012 §6.3 names (both tiers load-bearing).
- kv-only: no large tier; over-threshold puts reject at put time (ADR-012 §6.2 — the rejection behavior itself lands in store-put-paths; this task carries the mode and its validation).
- mem-only: the mem engine alone, no dispatch threshold in effect; never production.
- Mode machinery is built so the wave-3–5 engine constructors slot in without reshaping (sqlite/postgres/pg-lo constructors are later waves; only feature-gated constructors exist when their feature is on).
Size-threshold dispatch (ADR-003): routing as a pure function of content length — same content ⇒ same length ⇒ same tier, no content ever migrates. Default threshold 128 KiB (constructor-tunable; the conservative edge of the measured ~128–256 KiB crossover zone, POC #3 A4). The dispatch function is pure and unit-tested (boundary values: exactly-at-threshold routing).
The dispatch seam the ops tasks program through: tier selection for a given length, and the fall-through order (kv first, then large) the read paths and delete consume (ADR-012 §6.1's general rule).
Conformance factory binding: bind StoreFactory::Store to the real facade type (the skeleton's anticipated collapse to the concrete type); if binding reveals a shape correction, make it and record it in factory.rs + tests/conformance/README.md per the skeleton's note.

Acceptance Criteria

Public Store type with the three constructor modes; engine representation decided and recorded (enum-dispatch vs generic) with the public surface engine-blind
Size-threshold dispatch: pure function of length, default 128 KiB, constructor-tunable; boundary-value unit tests (at/below/above threshold route deterministically)
kv = mem + large = local dual-tier construction works (the ADR-012 §6.3 dispatch-coverage shape); kv-only and mem-only modes construct and validate
StoreFactory::Store bound to the real facade; any shape correction recorded in factory.rs + README
cargo test green (default build: local ungated); cargo test --features mem and cargo test --all-features green; clippy/fmt gates green in all three feature shapes

References

docs/architecture/store-api.md (§What this is; §Public surface)
docs/architecture/backends-and-dispatch.md (§Size-threshold dispatch; §Constructor modes)
docs/architecture/decisions/003-backend-contract-and-dispatch.md (§Dispatch policy)
docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md §4
docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.2/§6.3
tests/conformance/factory.rs (the binding note)

Notes

To be filled by implementation agent

Summary

To be filled on completion

4.5 KiB Raw Blame History Unescape Escape