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

@@ -2,7 +2,12 @@
## Status
Accepted
Accepted (fleet-mode activation, the GC-state host, the sweep-abort
shape, and kv-only's put-time rejection point are ruled by
[ADR-012](012-pre-decomposition-consistency-rulings.md) — this ADR's
constructor table is closed under ADR-012 §4's host rule; §4's
"constructor-time error" wording reads as ADR-012 §6.2's put-time
rejection)
## Context
@@ -147,12 +152,17 @@ explicit shared-media assertion, ADR-008 §3, is what disambiguates).
Constructor modes (dispatch shapes) — pinned here (implied by
ADR-008 §3's re-routing bullet and the mem tests, but never named):
- **dual-tier** (the default): kv + large, size-threshold dispatch
between them (ADR-003).
between them (ADR-003). Engine pairs beyond the default
(`kv = mem` + `large = local`) are valid dual-tier constructions —
ADR-012 §6.3.
- **kv-only** (ADR-008's "kv-tier-only dispatch", now named): a
constructor mode with no large tier; over-threshold puts are a
constructor-time error (the client-node re-routing posture handles
them via the ops surface instead — its composition, not a store
mode).
constructor mode with no large tier; over-threshold puts reject at
**put time** — known-length immediately, unknown-length at
threshold overflow (the original "constructor-time error" wording
is corrected by ADR-012 §6.2: lengths are not known at
construction). The client-node re-routing posture handles
over-threshold content via the ops surface instead — its
composition, not a store mode.
- **mem-only** (test/embedder-ephemeral mode): the mem engine alone,
no dispatch threshold in effect (everything is local and small);
a testing posture, explicitly not a production story.
@@ -161,7 +171,9 @@ ADR-008 §3's re-routing bullet and the mem tests, but never named):
ADR-004's requirement (both tiers are load-bearing by measured
economics); "postgres-only" as in *one SQL instance serving both
tiers* already exists (kv=postgres + large=pg-lo — the ADR-009
consolidation), which is the dual-tier mode over one engine.
consolidation), which is the dual-tier mode over one engine —
under fleet mode that one instance is a requirement, not a
coincidence (ADR-012 §4).
### 5. Deferral-policy wording (README alignment)
@@ -216,7 +228,10 @@ this ADR's wording here rather than a silent edit).
and the fleet topology; the vocabulary it assumed is now pinned),
ADR-009 (pg-lo admission; the consolidation option whose
constructor mode this ADR names dual-tier), [ADR-010](010-backend-io-seams-and-fleet-state-home.md)
(the I/O seams and GC-state home this vocabulary must fit)
(the I/O seams and GC-state home this vocabulary must fit),
[ADR-012](012-pre-decomposition-consistency-rulings.md) (fleet-mode
activation + GC-state host + kv-only put-time rejection — the
constructor table's final closure)
- [requirements.md](../requirements.md) (the canonical vocabulary
copy, REQ-1..4); [backends-and-dispatch.md](../backends-and-dispatch.md)
(the tier/engine table's spec home)