docs(architecture): ADR-012 — pre-decomposition consistency rulings; tree verified single-valued

Full-tree review before task decomposition found five composition
defects (mechanisms specced correctly in isolation, composition
unruled) and a set of caller-facing gaps. ADR-012 rules each:

- Sweeps are never errors: aborts are GcAbortCause report data in
  Ok(SweepReport) (ProtectFailed / SweeperLock / NoLivenessSources);
  GcAborted retired from the error enum; direct-delete refusal is
  the GcRefuse error covering the full protection set
- Pin token gains its wire shape: blobs/put response {token, digest};
  blobs/have's token-renewal form (one digest + token); token
  validity domain = the minting serving node, process-lifetime
  mapping
- Fleet mode is an explicit constructor declaration (fleet: true),
  never inferred from engine choice
- All fleet GC state hosts on the fleet's kv engine (postgres) — one
  arbitration domain; large=pg-lo fleet nodes required onto the same
  pg instance (composite predicate's new clause); large=local fleet
  puts pin-row-first, publish-second
- Engine-state seam reduced: sqlite pin/sweep-lock bodies dropped
  (dead machinery); non-SQL engines stage delete-window candidates
  in-process; one-window-host rule per instance
- Facade clarifications: fall-through for all key-addressed ops,
  kv-only put-time rejection, mem+local dual-tier valid, error-model
  member/return-shape ruling (trait/facade family split), has ->
  bool, PinState variants, fleet liveness-table registration form,
  window executor = the next sweep

Alignment edits across all specs and ADR-005/008/009/010/011
(bracketed corrections per the established pattern); OQ-11 (pg-only-kv
feature graph) added to the parked index for auditability.

Verification: two independent review passes; all findings resolved;
verdict READY for task decomposition.
This commit is contained in:
glm-5.3-flash committed 2026-10-03 07:14:45 +00:00
1 parent abf8c5ae9c
commit 7b9d904b8a
13 files changed
+771 -184

No files matched your search

@@ -8,7 +8,13 @@ advisory-locked single sweeper, SQL-level delete arbitration under
shared-pool engines (REQ-2) — while keeping this ADR's invariants
and the in-process protocol unchanged everywhere else. The "one pool
per node" phrasing below reads as "per deployment" for fleets; the
vocabulary is pinned in requirements.md)
vocabulary is pinned in requirements.md. ADR-012 rules the abort
*carrier*: sweep aborts — including the protect callback's — are
`GcAbortCause` report data in `Ok(SweepReport)`, never a typed sweep
error (this ADR's "typed `GcAborted`" phrasing reads through that
ruling), and direct `delete()`'s refusal covers the full protection
set (this ADR's "pinned keys" wording reads as ADR-012 §6.4's
"protected keys"))
## Context
@@ -73,9 +79,11 @@ served by range reads).
observes the replacement (the local analog of the ops-layer pin
token contract).
3. **Protect callback** — consulted pre-sweep; may add known-live keys
or **abort the run** (typed `GcAborted`, nothing deleted). iroh's
`ProtectOutcome::Abort` conclusion adopted: a flaky protection
source skips the sweep rather than risk deletion.
or **abort the run** (nothing deleted; the abort is report data —
`GcAbortCause::ProtectFailed` in `Ok(SweepReport)` per ADR-012
§1, not a typed error; this ADR's original "typed `GcAborted`"
phrasing is superseded on the carrier only — the semantics iroh's
`ProtectOutcome::Abort` conclusion adopted stand).
### Sweep: mark → delete window → commit
@@ -133,10 +141,14 @@ served by range reads).
existence flips atomically per key).
- **Delete-then-recover is a re-put** (validated: byte-identical under
the same key); no tombstone layer exists.
- **Direct `delete(key)`:** refuses pinned keys with a typed error
(same arbitration); permitted for embedder correction flows on
unpinned entries. Outside-of-sweep deletion is unusual by posture —
most deletion should flow through sweeps.
- **Direct `delete(key)`:** refuses protected keys (pinned,
registered-source-live, or protect-callback-named — the full
protection set, ADR-012 §6.4; this ADR's original "refuses pinned
keys" wording is superseded upward; the refusal is the typed
`GcRefuse` error, ADR-012 §1) — same delete-time arbitration;
permitted for embedder correction flows on unprotected entries.
Outside-of-sweep deletion is unusual by posture — most deletion
should flow through sweeps.
### Traversal and scheduling
@@ -202,6 +214,6 @@ OQ-07's.
gix-odb (alternates/pool prior art)
- ADR-002 (one address space), ADR-003 (list contract, pins), ADR-004
(manifest layers above), ADR-006 (verification limits inform recover
semantics)
semantics), ADR-012 (abort carrier + direct-delete protection set)
- [gc-and-namespaces.md](../gc-and-namespaces.md);
[store-api.md](../store-api.md)