docs(architecture): ADR-008 — trait size probe, fleet GC, fs-tier engines; requirements anchor
- requirements.md (new): the three use cases pinned as REQ-1..4 with the node/pool/fleet/engine vocabulary defined once — ends per-session re-derivation of consumer facts. REQ-2 (replicator fleet over one shared pg pool, incl. large-blob serving) is recorded as a planning fact predating all POCs, on the operator's authority. - ADR-008: Backend trait gains size(key) length probe (before any backend ships data — ADR-002 one-way-door discipline); fleet GC mechanism (DB-backed pin rows committed atomically with entries, TTL+renewal semantics, liveness = embedder-owned table, protect callback is single-node-only, advisory-locked single sweeper, staged re-arbitrated delete window on both engines); fs tier becomes engine-selectable (local default; pg-lo named candidate) with the fleet locality contract (shared media or re-routing; mixed tiers are a documented deployment invariant, not a constructor-provable one). - poc-pglo-spec.md (new): POC #7 spec — pg Large Objects as the fs tier's pg-lo engine; instruments, decision gate, registered in phase-0.md OQ-BL-06. - ADR-003/005 status amendments point to ADR-008's extensions; specs ripple (backends/store-api/gc/ops/overview/README). - open-questions.md: deferral-policy header gains the decisions-vs- sequenced-work distinction; pg-lo's why-not-parked audit trail recorded. - research fixes: postgres POC renumbered #4->#5 to the canonical register (phase-0 OQ-BL-06), redb cross-refs fixed, thinking- artifact sentence in B1 replaced with the honest reading. Verification: docs-only change; reference-integrity sweep across the tree (ADR/REQ/POC refs resolve); architecture-reviewer pass on the delta — original 3 criticals addressed, its follow-up (fleet liveness form, pin TTL, staged-delete semantics, enforceability, shared-media caveats) fixed in this commit.
This commit is contained in:
1 parent
395d58cf3f
commit
281c37876e
16 files changed
+689
-88
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-10-02
|
||||
last_updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Pooling, namespaces, and GC
|
||||
@@ -16,11 +16,17 @@ price, and this document specifies the mechanism the POCs validated
|
||||
|
||||
## The pooled CAS
|
||||
|
||||
- **One pool per node.** Repos, workspaces, and appfile stores are all
|
||||
- **One pool per deployment; a node is one store instance** (the
|
||||
engine/vocabulary definitions live in requirements.md). Repos,
|
||||
workspaces, and appfile stores are all
|
||||
*sets of hash references* over the same CAS — never walled-off
|
||||
per-repo stores. Git's `alternates`/object-pool mechanism (GitLab
|
||||
object pools) is the same idea done awkwardly; the pool generalizes it
|
||||
to unrelated repos and to p2p replication.
|
||||
to unrelated repos and to p2p replication. **A fleet (REQ-2) — two or
|
||||
more nodes sharing one pool — is the one topology where the GC
|
||||
mechanism below extends beyond a node: ADR-008 pins, sweeper
|
||||
locking, and delete arbitration move into the shared engine;
|
||||
the invariants are unchanged.**
|
||||
- **One address space.** Under the canonical hash (ADR-002), the same
|
||||
file content has the same address whether it entered via a git oid or
|
||||
a workspace manifest — cross-consumer dedup is free by construction,
|
||||
@@ -116,16 +122,19 @@ existence flips atomically per key).
|
||||
| [005](decisions/005-pooled-cas-and-gc-mechanism.md) | Pooled CAS & GC | one pool, registered liveness, mark-and-sweep, delete windows, no ambient scheduling |
|
||||
| [003](decisions/003-backend-contract-and-dispatch.md) | list() contract | complete lists are the GC substrate |
|
||||
| [004](decisions/004-two-backends-no-third.md) | Structure-blindness | manifests/refs never sink into the store |
|
||||
| [008](decisions/008-trait-size-probe-fleet-gc-and-fs-engines.md) | Fleet GC extension | DB-backed pins, advisory-locked single sweeper, SQL delete arbitration — for shared-pool (fleet) topologies only; the in-process protocol is unchanged elsewhere |
|
||||
|
||||
## Open Questions
|
||||
|
||||
None owned by this document. The p2p replicator's cross-node GC
|
||||
coordination is a property of the replicator policy layer (above the
|
||||
crate), governed by the same seam — it raises a question here only
|
||||
when a consumer *names a requirement* (OQ-07/OQ-08 intake), which is
|
||||
re-entry via a new decision at a new ADR, not a parked question: no
|
||||
decision here waits on a consumer, and a future requirement does not
|
||||
create one retroactively.
|
||||
None owned by this document. Shared-pool GC coordination within a
|
||||
deployment is now in-crate (fleet mechanism: ADR-008). What remains a
|
||||
replicator-policy-layer property (above the crate) is *cross-pool*
|
||||
coordination — gossip sync between separately-pooled replicator nodes
|
||||
deciding what each keeps — governed by the same seam; it raises a
|
||||
question here only when a consumer *names a requirement*
|
||||
(OQ-07/OQ-08 intake), which is re-entry via a new decision at a new
|
||||
ADR, not a parked question: no decision here waits on a consumer, and
|
||||
a future requirement does not create one retroactively.
|
||||
|
||||
## References
|
||||
|
||||
|
||||
Reference in new issue
Block a user