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.

docs/architecture/requirements.md

@@ -0,0 +1,103 @@
+---
+status: draft
+last_updated: 2026-10-03
+---
+
+# Requirements
+
+The deployment-relevant facts each use case forces on this crate.
+Specs and ADRs reference these by ID (REQ-n); a future session must be
+able to read this document and never re-derive a requirement from
+conversation or vision prose. **This document is the anchor: when a
+consumer fact changes, it changes here first, with a dated note, and
+the ADRs re-derive from it.**
+
+## Vocabulary (defined once; used everywhere)
+
+- **Engine** — a concrete storage implementation of one tier's
+  contract: the kv tier's engines are sqlite and postgres (ADR-007);
+  the fs tier's engines are `local` (default) and `pg-lo` (candidate —
+  see REQ-2, ADR-008).
+- **Pool** — the flat content-addressed namespace of one deployment
+  (`hash → bytes` everywhere; ADR-005).
+- **Node** — one running store instance (one process embedder; its fs
+  tier is its own media). Node is the GC arbitration domain for
+  single-node topologies (ADR-005's pins, liveness locks, and delete
+  windows live inside a node); under a fleet, arbitration moves into
+  the shared engine (ADR-008).
+- **Fleet** — two or more nodes over **one shared pool** (e.g. via one
+  postgres instance). A fleet is the only topology in which
+  cross-node GC and fs-locality questions exist (ADR-008).
+- **Deployment** — one operator's whole system: typically one fleet
+  (multi-node) or one node; consumer tables, op registrations, and
+  sweep cadence are deployment choices.
+
+## The use cases and their requirements
+
+### UC-1: Self-hosted git serving (gitea-replacement scale)
+
+Git repos for a user/team on one machine. Small-object regime dominated
+by loose objects in the kv tier; packs and large artifacts (git-lfs
+shape) on the fs tier.
+
+- **REQ-1 (traces: ADR-007, POC #3 A4)** — single-machine economics:
+  sqlite is the default kv engine; single-writer WAL ceiling (~1.2k
+  objects/s under contention) is comfortably above single-node push
+  rates. **Zero-ops is a requirement**: no daemon beyond the node
+  process itself.
+
+### UC-2: Distributed git with replicator nodes hosting repos for many users
+
+The p2p/OSS sketch (phase-0 §p2p shape): replicators are push/clone
+endpoints serving many concurrent users; gossip-style sync between
+replicators; ACL/ownership above (alkcall layer).
+
+- **REQ-2 (traces: ADR-007, ADR-008)** — **a replicator node may run
+  multiple store instances (a fleet) sharing one pool** via a shared
+  postgres kv engine, including serving large (>threshold) pool
+  content from that fleet. This is stated as a requirement, dated
+  2026-10-03 (recording a planning fact from the use case's origin
+  discussion; it predates all POCs and architecture docs, recorded
+  here on the operator's authority as the use case's stated shape).
+  Consequences are derived in ADR-008: fleet GC (DB-backed pins,
+  advisory-locked sweeper, SQL delete arbitration), the fs-tier
+  engine concept with its locality contract, and the pg-lo candidate
+  engine (POC #7).
+- **REQ-3 (traces: ADR-007, POC #5 B3/B4)** — concurrency scale-out:
+  the fleet's hub-class nodes need put throughput that *increases*
+  under concurrency (pg: near-linear to ~37k puts/s at 24 conns);
+  sqlite's WAL ceiling (~1.2k/s, latency-climbs-unbounded) bounds
+  single-node sustained write pressure regardless of client count.
+  This is the measured basis for the per-node engine split.
+
+### UC-3: Agent workspaces (many agents, near-identical content)
+
+Agents working simultaneously in mostly-identical workspaces, each
+making small edits; a shared pool dedups by construction; per-workspace
+path→hash manifests above.
+
+- **REQ-4 (traces: ADR-005, ADR-002)** — pooling and one address space
+  across workspaces; dedup must be structural (not configured). Small
+  edits mean the small-blob regime dominates: sqlite-class kv
+  performance is what matters; the fs tier is hit rarely (large
+  workspace artifacts).
+
+## What this document is not
+
+- **Not consumer architecture**: how alkgit maps refs/manifests onto
+  the store remains OQ-07 (externally-owned); how alkfs shapes
+  workspaces remains OQ-08. This document records what each use case
+  *forces on this crate*, not what each consumer *is*.
+- **Not a requirements-change process substitute**: a new or changed
+  REQ arrives here with a dated note and owner; ADRs that depended on
+  the old fact state their reopen conditions and reopen when this
+  file changes.
+
+## Decision trace
+
+| REQ | Introduced | Source | ADRs |
+|---|---|---|---|
+| REQ-1 | 2026-10-03 (fact: phase-0 §deployment posture) | POC #3 A4 | ADR-007 |
+| REQ-2 | 2026-10-03 (fact: use case origin discussion, pre-POC) | user/planning record | ADR-007, ADR-008 |
+| REQ-3 | 2026-10-03 (fact: phase-0 §deployment posture) | POC #5 B3/B4 | ADR-007 |
+| REQ-4 | 2026-10-03 (fact: phase-0 §vision) | POC #1, ADR-002 | ADR-005 |