alkblobs/tasks/store-put-paths.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
store-put-paths	Store put seam — two internal paths, the three numbered rules, Batch, kv-only rejection	completed	gc-protocol	moderate	medium	component	implementation	wave-2 facade write-path

Description

Implement the facade's put seam on the Store type (store-api.md §Write path): put(len: Option<u64>, stream) → (Key, Pin) — two internal paths behind one signature, with pin-before-publish from the gc-protocol registry.

• Known-length path (encouraged, documented as such on the API): the preamble ("blob <len>\0") is known before content flows, so the hash initializes with it and one pass suffices — no staging needed for hashing. Routing by the dispatch seam: ≤ threshold → the kv tier's whole-value put; > threshold → the large tier's staged put (content streams into the staging cursor while hashing; the derivation completes at stream end; commit-rename publishes).
• Unknown-length path: content buffers in memory up to the dispatch threshold. ADR-003's three numbered rules (option (d)), each a test-asserted behavior:
  1. Threshold exceeded mid-stream (non-restartable sources are normal): the buffered prefix flushes into a fresh stage file and the stream continues appending into it — there is no "restart the stream" requirement anywhere.
  2. Verification runs over the eventual stored artifact as a whole: the memory buffer for the sub-threshold kv commit; the complete staged bytes for the large commit — the derivation pass restarts over preamble + staged bytes (forced by the preamble being inside the hashed input, ADR-002), reading the staged artifact back through the StagingCursor: ReadCursor seam (the wave-1 design-led extension). There is no stitched-input case left ambiguous.
  3. Stream error before commit: no entry lands and no stage file remains — buffer discard on the failure path, exactly like stage discard (the stage-hygiene invariant extends to the buffered case).
• Pin-before-publish (ADR-005): the pin refcount is acquired under the arbitration lock before the entry becomes visible — publish and protection are one step; an entry cannot appear in a sweep's list() without already carrying its pin.
• Dedup: a re-put of existing content acquires no new pool entry — the returned Pin refcounts the existing one under the same lock.
• Batch (store-api.md §Write path): the batching put seam — multi-put writes group under one batch-scoped pin; member puts publish pin-before-publish exactly as lone puts do; the batch's pins drop together on commit or drop (the gc-protocol machinery drives).
• kv-only mode rejection (ADR-012 §6.2): known-length puts exceeding the threshold reject immediately; unknown-length puts reject at mid-stream threshold overflow — lengths are not known at construction, so put time is the only possible rejection point. Zero residue on either rejection.
• Named design points: (a) the stream parameter shape (impl AsyncRead + Unpin + Send vs a boxed trait object — the family's no-dyn posture vs ergonomics); (b) the declared-len mismatch case (a known-length stream that yields fewer/more bytes than len — which error family member carries it, and zero residue either way). Record both for the review gate.

Acceptance Criteria

• put(len, stream) → (Key, Pin) with both internal paths behind the one signature; routing is the pure length function (no content ever migrates tiers)
• The three numbered rules each behavior-tested: mid-stream overflow flushes into a fresh stage and the stream continues; the derivation pass runs over the eventual stored artifact as a whole (buffer form and staged-bytes form); stream error leaves no entry and no stage file
• Pin-before-publish holds on both paths and both tiers; dedup re-puts refcount the existing entry
• Batch groups multi-put writes; member pins drop together
• kv-only mode: known-length over-threshold rejects immediately; unknown-length rejects at mid-stream overflow; zero residue on both
• Stream-shape and len-mismatch design points decided and recorded
• cargo test green; cargo test --features mem and cargo test --all-features green; clippy/fmt gates green

References

• docs/architecture/store-api.md (§Write path — the put seam, stage hygiene invariant)
• docs/architecture/decisions/003-backend-contract-and-dispatch.md (§Dispatch policy — the three numbered rules, option (d))
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.2 (kv-only put-time rejection)
• docs/architecture/decisions/005-pooled-cas-and-gc-mechanism.md (pin-before-publish, dedup refcount)
• docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md §1 (the staged-put contract)
• src/backend.rs (StagingCursor: ReadCursor — the verification-pass seam)

Notes

• The staged-put seam was amended: the key resolves at commit, not at handout. Implementing the two large-tier flows surfaced a contradiction in the wave-1 pin: put_staged(key) hands the staging cursor out with the key, but both large-tier put paths only know the canonical key when the derivation completes — at stream end (the preamble covers a length, and the digest covers content that has not streamed yet). Content streams once (non-restartable sources are the normal case), so commit(self) publishing under the handout key cannot express the specced flow ("the derivation completes at stream end; commit-rename publishes"). Amended with operator sign-off: put_staged() is a keyless handout and StagingCursor::commit(self, key) publishes under the store-core-resolved key (CAS first-writer-wins as the whole-value put). No ADR text pins the key's arrival point (ADR-003/010 pin handout/commit/discard mechanics only); the wave-1 task notes' put_staged(key) shape was pre-flow realism. Recorded for review-wave-2. Engines updated in place (mem, local, the wave-1 test double) with their hygiene suites re-run green.
• Put-path named design points (recorded in src/store.rs module docs, for review-wave-2):
  • Stream parameter shape: `put(len, stream: impl AsyncRead + Unpin
    • Send) — generic, no boxing; the family's no-dynposture carried to the write seam (a boxed reader is itselfAsyncRead + Unpin + Sendunder tokio's blanket impl, so callers needing erasure box at their call site).Sendkeeps spawn-site bounds resolvable for the ops wave; no'static` (nothing spawns).
  • Declared-len mismatch: a known-length stream yielding fewer or more bytes than len rejects Error::Verification on either tier, zero residue either side — the preamble carries the declared length, so a mismatched artifact's canonical address can never equal the stored key (storing it would break pool integrity by construction; Verification is the put-path content-≠-key family member, ADR-006's whole-blob posture applied at put time).
  • kv-only rejection carrier (a named decision beyond the two the task listed): Error::Io(String) with a descriptive message — the ADR-pinned family (ADR-012 §6.5) holds no dedicated variant and the rejection is an operational/capability fact about the medium posture, the bucket Io(String) covers. A dedicated variant for typed matchability would be a new failure family — a new ADR.
• Flows as implemented (src/store.rs, write-path impl Store): known-length initializes the derivation with the preamble before content flows and streams once (kv: buffer + hash in one pass → mint pin → whole-value put; large: stream into the staging cursor while hashing → mint pin → commit(key)). Unknown-length buffers to the threshold; a mid-stream overflow (strictly past it — exactly-at stays kv) flushes the buffered prefix into a fresh stage and the stream continues into it; at EOF the derivation pass runs over the eventual stored artifact as a whole — the buffer (kv form) or preamble + staged bytes read back through the StagingCursor: ReadCursor seam (staged form) — then pin, then commit. Every failure path (read error, mismatch, under-read) discards: no entry, no stage file.
• API shapes: Store::put(&self, len: Option<u64>, stream) → Result<(Key, Pin), Error>; the batching seam is Store::batch() → Batch + Store::put_in_batch(&mut Batch, len, stream) → Result<Key, Error> (members run the lone-put flow; the minted guard is contributed to the group via crate-internal Batch::add); a public Batch::commit() was added consuming the batch with the same one-step release as drop (store-api.md's "pins drop together on batch commit or drop", as a named verb). hashing.rs gained crate-internal BlobHasher — the same derivation driven incrementally, pinned byte-equal to Algorithm::derive by tests (chunk-boundary invariance, both algorithms, the git vectors).
• git-interop leg added (tests/git_interop.rs): the put seam keys entries git-identically through both put paths on both tiers against live git hash-object (INV-1's source-of-truth posture extended from the derivation constructor to the facade seam).
• Wave-1 note updates: put_staged/commit doc text in backend.rs, mem.rs, local.rs now carries the key-at-commit design point; the store.rs module doc's remaining-deferral note shrunk to the actual remaining gaps (fleet clauses, wave-3 kv engine).

Summary

Implemented the facade's put seam (src/store.rs): put(len: Option<u64>, stream: impl AsyncRead + Unpin + Send) → Result<(Key, Pin), Error> with the two internal paths behind the one signature — the known-length one-pass flow and the unknown-length buffer-then-maybe-flush flow implementing ADR-003's option (d) three numbered rules — plus batch()/put_in_batch() (ADR-005 §Marks 2's batch-scoped pin group) and kv-only's put-time rejection at its two pinned points (ADR-012 §6.2). Pin-before-publish rides gc().acquire under the arbitration lock before both tiers' publishes; dedup re-puts refcount the existing entry; every failure path converges on discard with zero stage files. The staged-put seam was amended (keyless handout; commit(self, key)) after operator sign-off — the one blocking finding of the task. Supporting changes: staging-cursor dispatch enum AnyStaging beside the read path's AnyCursor; incremental BlobHasher in hashing.rs; public Batch::commit; a Pin/Debug impl; the git-interop put-seam leg. Eleven put-path tests in src/store.rs (plus four fixtures) pin the three rules, both-tier round-trips, the threshold boundary, pin- before-publish under a racing sweep, dedup refcounting across paths and tiers, batch grouping/commit/failure, kv-only's two rejection points, len-mismatch zero-residue, mem-only's threshold-free posture, and the empty-content degenerate.

Verification: cargo test (default), cargo test --features mem, cargo test --all-features all green (97 lib tests under mem plus conformance and git-interop); cargo clippy --all-targets -- -D warnings green in all three feature shapes; cargo fmt --check green; cargo doc --no-deps at the pre-existing 24-warning baseline.