glm-5.3-flash
b18521a0e6
- OQ-09 resolved closed-by-default (deny-unlisted), decided on risk asymmetry in hand, not on a first deployment the crate itself must create; named reopen condition instead of a parked wait - delete oq-09-ops-visibility-tracker.md (watch-task for an event the crate itself gates — never collapses) - fix doc-lifecycle circularity: externally-owned OQs no longer block a spec's `reviewed` promotion - gc-and-namespaces: "until a consumer names a requirement" reframed as re-entry via a new ADR, not a parked question - README: state the corollary explicitly — facts this crate must create (its own first deployment/consumer) are never deciding inputs Verified: full-text sweep for stale OQ-09 deferral/tracker references comes up clean across docs/ and tasks/.
83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 2026-10-02
|
|
---
|
|
|
|
# alkblobs — Architecture
|
|
|
|
## Current State
|
|
|
|
**Phase 1 (Architecture).** Phase 0 (Exploration) converged — see
|
|
`docs/research/phase-0.md` for the vision, the evidence trail, and the
|
|
POC register (all POCs passed or were absorbed; POC code lives in
|
|
standalone crates (`/workspace/alkblobs-trait-poc`,
|
|
`/workspace/alkblobs-largeblob-poc`); findings live in
|
|
`docs/research/`). No implementation exists yet (`src/lib.rs` is a
|
|
placeholder).
|
|
|
|
The converged Phase 0 posture has been promoted into the specs and ADRs
|
|
below. Two framing corrections from the convergence review are captured
|
|
there — not inherited as hedges:
|
|
|
|
- **ADR-001** makes the substrate posture explicit: the store layer
|
|
carries no alkcall dependency *by design* — which is conformance to
|
|
the family pattern, not deviation from it — and the ops surface rides
|
|
alkcall, feature-gated.
|
|
- **ADR-004** fixes the "two backends" framing: the crate ships exactly
|
|
two backends (kv small / fs large — both required by measured scale
|
|
economics); the path→hash mapping layer (the alkfs/alknet "vfs" shape)
|
|
is a consumer-layer concern and must never become a third backend.
|
|
|
|
## Architecture Documents
|
|
|
|
| Document | Scope | Status |
|
|
|---|---|---|
|
|
| [overview.md](overview.md) | Purpose, consumers, layer map, dependency posture | 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, shipped backends, size-threshold dispatch | 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 |
|
|
|
|
## Decision Records
|
|
|
|
| ADR | Decision | Status |
|
|
|---|---|---|
|
|
| [001](decisions/001-substrate-posture-and-ops-placement.md) | Substrate posture & ops-surface placement (conformance, not deviation) | Accepted |
|
|
| [002](decisions/002-canonical-hash-and-key-encoding.md) | Canonical hash + key encoding (the wire-format ADR; precedes any consumer) | Accepted |
|
|
| [003](decisions/003-backend-contract-and-dispatch.md) | Backend contract, shipped backends, dispatch policy | Accepted |
|
|
| [004](decisions/004-two-backends-no-third.md) | Exactly two backends; manifest layers stay above | Accepted |
|
|
| [005](decisions/005-pooled-cas-and-gc-mechanism.md) | Pooled CAS, liveness seams, mark-and-sweep, delete windows | Accepted |
|
|
| [006](decisions/006-verification-posture-and-transfer-encoding.md) | Whole-blob verification; transfer encoding excluded by scoping | 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
|
|
(namespace-visibility default) resolved closed-by-default. **Deferral
|
|
policy (the "Schrödinger's code" rule):** a *decision this crate needs
|
|
before shipping* may not be deferred on a dependency that is itself
|
|
waiting for this crate to exist. Two parking kinds remain legitimate:
|
|
`deferred(scope)` on a deciding fact that exists independently of this
|
|
crate, and externally-owned questions (how a consumer maps onto this
|
|
crate) that gate no decision here — full definitions in the header of
|
|
[open-questions.md](open-questions.md). A corollary worth restating,
|
|
because it recurs: a fact this crate must create (its own first
|
|
deployment, its own first consumer) is never a deciding input —
|
|
decisions stand on evidence in hand, and future needs reopen via named
|
|
requirements, not via waiting.
|
|
|
|
## Lifecycle
|
|
|
|
Spec docs: `draft` → `reviewed` → `stable` → `deprecated`. A doc moves
|
|
`reviewed` when every *crate-owned* open question it references
|
|
resolves and an architecture review pass clears it — externally-owned
|
|
OQs (OQ-07/OQ-08) gate nothing here by definition and do not block the
|
|
lifecycle; their outcomes arrive through their owners' processes.
|
|
`stable` when implementation verifies against it; `deprecated` when
|
|
superseded (kept for reference). ADRs use a separate status set
|
|
(Accepted | Proposed | Deprecated | Superseded), defined per ADR file.
|
|
This tree is in `draft` pending the first architecture review cycle. |