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:
1 parent
abf8c5ae9c
commit
7b9d904b8a
13 files changed
+771
-184
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-10-03 (ADR-010/011 — I/O seams + GC-state home; vocabulary pinned, fs → large, mem joins kv)
|
||||
last_updated: 2026-10-03 (ADR-012 — pre-decomposition consistency rulings: sweep-abort shape, token wire shape, fleet activation, GC-state host)
|
||||
---
|
||||
|
||||
# alkblobs — Architecture
|
||||
@@ -88,6 +88,24 @@ there — not inherited as hedges:
|
||||
`large`** (feature `fs` → `large`) — its routing criterion is
|
||||
length, not medium — with constructor modes (dual-tier default,
|
||||
kv-only, mem-only) pinned in the same ADR's table.
|
||||
- **ADR-012** (2026-10-03) is the pre-decomposition consistency round:
|
||||
the full-tree review found five composition defects and this ADR
|
||||
rules each — sweeps are **never errors** (`Ok(SweepReport)` with
|
||||
`aborted: Option<GcAbortCause>`; `GcAborted` retired from the error
|
||||
enum, direct-delete refusal renamed `GcRefuse`;
|
||||
`NoLivenessSources` added as the third cause variant); the pin
|
||||
token gains its **wire shape** (`blobs/put` response `{token,
|
||||
digest}`; `blobs/have`'s token-renewal form; token validity domain
|
||||
= the minting serving node); **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 — with `large=pg-lo` fleet
|
||||
nodes required onto the same pg instance (the composite predicate's
|
||||
new clause) and `large=local` fleet puts pinned pin-row-first,
|
||||
publish-second; and the engine-state seam's sqlite rows are
|
||||
repaired (pin/sweep-lock bodies dropped; window staging for
|
||||
non-SQL engines is in-process). The tree is now single-valued on
|
||||
every implementation-facing signature.
|
||||
|
||||
## Architecture Documents
|
||||
|
||||
@@ -97,7 +115,7 @@ there — not inherited as hedges:
|
||||
| [requirements.md](requirements.md) | Consumer requirements REQ-1..4, pinned vocabulary (tier/engine/instance/node/fleet) | draft |
|
||||
| [hashing-and-keys.md](hashing-and-keys.md) | Canonical hash, key encoding (the one-way door) | draft |
|
||||
| [store-api.md](store-api.md) | Store facade: put/get/stat/range/pin/batch/sweep surface, errors, invariants | draft |
|
||||
| [backends-and-dispatch.md](backends-and-dispatch.md) | Backend trait contract, tiers + engines table, size-threshold dispatch, constructor modes | draft |
|
||||
| [backends-and-dispatch.md](backends-and-dispatch.md) | Backend trait contract, tiers + engines table, size-threshold dispatch, constructor modes, fleet-validity | draft |
|
||||
| [gc-and-namespaces.md](gc-and-namespaces.md) | Pooled CAS, liveness seams, mark-and-sweep, delete windows | draft |
|
||||
| [ops-surface.md](ops-surface.md) | alkcall-backed have/need + fetch/put ops, ACL mapping | draft |
|
||||
| [open-questions.md](open-questions.md) | Centralized OQ tracker (incl. promoted Phase 0 register) | draft |
|
||||
@@ -116,14 +134,17 @@ there — not inherited as hedges:
|
||||
| [008](decisions/008-trait-size-probe-fleet-gc-and-large-engines.md) | Trait `size` probe; fleet GC (DB-backed pins, advisory-locked sweeper); large-tier engines | Accepted |
|
||||
| [009](decisions/009-pg-lo-large-tier-engine.md) | pg-lo — postgres Large Objects as the large tier's second engine (admitted on POC #7) | Accepted |
|
||||
| [010](decisions/010-backend-io-seams-and-fleet-state-home.md) | Backend I/O seams (read cursor, staged put); GC state store-core-owned via the engine-state seam; kv fleet-validity; pin-token renewal | Accepted |
|
||||
| [012](decisions/012-pre-decomposition-consistency-rulings.md) | Pre-decomposition rulings: sweep aborts are report data (`GcAborted` retired); pin-token wire shape; fleet-mode constructor declaration; GC state hosts on the kv engine; sqlite seam reduction | Accepted |
|
||||
| [011](decisions/011-vocabulary-tiers-engines-and-fleet-state.md) | Vocabulary: tier/engine/instance/node/fleet; mem joins kv; large tier renamed `large`; constructor modes | Accepted |
|
||||
|
||||
## Open Questions
|
||||
|
||||
Tracked in [open-questions.md](open-questions.md). The Phase 0 register
|
||||
(OQ-BL-01..06) is promoted there with its resolutions; two questions
|
||||
remain parked — OQ-07/OQ-08 externally-owned (alkgit seam mapping,
|
||||
alkfs intake; carried for visibility, gating nothing here). OQ-09
|
||||
(OQ-BL-01..06) is promoted there with its resolutions; three questions
|
||||
are parked — OQ-07/OQ-08 externally-owned (alkgit seam mapping,
|
||||
alkfs intake; carried for visibility, gating nothing here) and
|
||||
OQ-11 `deferred(scope)` (the pg-only-kv feature graph; a named
|
||||
requirement from outside this crate decides it). OQ-09
|
||||
(namespace-visibility default) resolved closed-by-default; OQ-10
|
||||
(second kv engine) resolved by ADR-007. The pg-lo large-engine question
|
||||
resolved to *sequenced work*, not a parked question: REQ-2/ADR-008
|
||||
|
||||
Reference in new issue
Block a user