glm-5.3-flash
281c37876e
- 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.
4.8 KiB
4.8 KiB
status, last_updated
| status | last_updated |
|---|---|
| draft | 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) andpg-lo(candidate — see REQ-2, ADR-008). - Pool — the flat content-addressed namespace of one deployment
(
hash → byteseverywhere; 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 |