---
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.