---
id: ops-put
name: blobs/put — the verified Sink op, the pin hand-over, and the {token, digest} response
status: pending
depends_on: [ops-foundation, ops-call-harness]
scope: moderate
risk: high
impact: component
level: implementation
tags: [wave-7, ops, put, tokens, hand-over, verification]
---

## Description

`blobs/put` (ops-surface.md §Op family) — the client→server streaming
op: `{namespace, digest?, len?}` offer + the byte stream in; the
server verifies against the canonical derivation **before commit**;
the response is **`{token, digest}`** (ADR-012 §2).

- **The op shape**: the Sink handler kind (alkcall ADR-046's
  `Pub`/Sink — the client→server streaming shape) with the
  **`channel_open` marker** (alkcall ADR-047); the establishment
  phase carries the offer ack. The **write** action (ACL;
  closed-by-default).
- **Verification before commit** (ADR-006; ops-surface.md): the
  server hash-checks the received stream against the canonical
  derivation (`H("blob <len>\0" + content)`) before commit. A
  **known-length offer** (`len` present) is the encouraged one-pass
  path; an **unknown-length offer** rides the store's pre-threshold
  buffering path (ADR-003's option (d) semantics — the facade's
  `put(None, …)` form, the mid-stream stage flush and the
  restart-over-staged-bytes derivation pass riding unchanged). When
  the offer carries `digest?`, the derived key is checked against it
  — a mismatch rejects before commit (the offered digest is a
  claim; the derivation is the authority).
- **The pin hand-over** (ops-surface.md §Pin hand-over; ADR-010 §4):
  the put lands pinned (pin-before-publish — the facade's put
  returns the `Pin` guard); the handler owns the guard; the custody
  split is the foundation's design, realized here:
  - **fleet**: the guard **drops at response completion** — the pin
    row's expiry is the only protection from that moment (the TTL
    machinery stays live on the ops path); the token mints over the
    committed row (the token↔(key, owner) mapping, owner = the
    serving instance's id);
  - **non-fleet**: the token registry **takes custody** of the guard
    — the token is the in-process guard's handle; nothing expires;
    the guard's fate is the custody lifecycle (conversion on the
    embedder's confirmation, or process-lifetime hold).
  The response returns `{token, digest}` — **both fields always
  present** (ADR-012 §2): `digest` is the stored entry's canonical
  digest hex (the unknown-length putter cannot know it beforehand and
  needs it for every later op); `token` is the minted opaque handle.
  Known-length putters receive the same shape.
- **The fanout seam's producer side** (POC #3 finding A3): the put's
  stream reader is the canonical fanout producer — **one read** of
  the incoming stream (never polled twice), the **store arm**
  persists, **subscriber arms** serve concurrent fetchers of that
  digest while the put lands (serve-while-persisting); the wiring
  into the foundation's fanout registry. Backpressure: bounded
  subscriber channels — a slow subscriber stalls the broadcast,
  which is correct for a put (the put must land); the
  drop-and-late-join escape is the fetch side's policy.
- **The dedup re-put**: CAS dedup means no new entry — the re-put
  renews the pin row (fleet: the joint tx's upsert-renewal of
  `(key, owner)`) or re-mints the custody guard (non-fleet); the
  re-put backstop's mechanics ride the facade's CAS unchanged.
- **Tests through the harness**: the known-length round-trip (the
  response's digest matches the git derivation — the byte-exact
  standard); the unknown-length round-trip (the buffering path
  through the wire); the verification-failure shape (a
  byte-corrupted stream → no commit, the typed error, zero residue
  on both tiers); the offer-digest mismatch rejection; the hand-over
  custody split (fleet: the guard dropped at response — observable
  via the row's expiry path; non-fleet: the registry holds the guard
  — observable via have-present); the minted token renews via
  have's renewal form (the cross-task contract); the dedup re-put;
  the ACL denial (no write grant → denied).

## Acceptance Criteria

- [ ] put exported as a Sink spec/handler pair with the
      `channel_open` marker; the establishment reply fields carry the
      offer ack
- [ ] Server-side verification before commit; an offer-digest
      mismatch rejects before commit; a verification failure leaves
      zero residue on both tiers
- [ ] The response is `{token, digest}`, both fields always present;
      `digest` is the canonical hex (the unknown-length putter's
      later-op handle)
- [ ] The hand-over custody split implemented per ADR-010 §4 (fleet:
      the guard drops at response completion — the row is the
      signal; non-fleet: the registry holds the guard — nothing
      expires)
- [ ] The fanout producer side wired: one read of the incoming
      stream, the store arm + subscriber arms (serve-while-
      persisting)
- [ ] The dedup re-put renews (row upsert fleet-form / custody
      re-mint non-fleet)
- [ ] Harness tests green; `cargo test` (default) green;
      `cargo test --features ops` green; clippy/fmt green on both
      shapes; `cargo doc --no-deps` clean

## References

- docs/architecture/ops-surface.md (§Op family — the put bullet; §Pin
  hand-over for remote puts — the cross-wire contract)
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md
  §2 (the {token, digest} response; both fields always present)
- docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md
  §4 (the guard drops at response time — the TTL-machinery-alive
  rationale; the non-fleet custody)
- docs/architecture/decisions/006-verification-posture-and-transfer-encoding.md
  (verification before commit)
- docs/architecture/decisions/003-backend-contract-and-dispatch.md
  (the staged-put contract; the unknown-length path the wire rides)
- docs/research/poc-largeblob-findings.md finding A3 (the fanout
  producer shape)
- tasks/ops-foundation.md (the token layer, the custody design, the
  fanout registry), tasks/ops-call-harness.md (the harness),
  tasks/ops-json-ops.md (the renewal form the minted token rides)

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion