docs(architecture): Phase 1 spec tree — 7 specs, ADRs 001-006, OQ tracker

- overview/hashing/store-api/backends/gc/ops specs + README index,
  all draft status with YAML frontmatter and cross-referenced ADR/OQ
- ADR-001: substrate posture (store layer alkcall-free = family
  conformance, not deviation) + ops placement decided (feature-gated
  module, no consumer-waited deferral)
- ADR-002: canonical git-blob-sha-256 + key encoding — the declared
  wire-format ADR (one-way door)
- ADR-003: backend contract, sqlite/fs/mem tiers, pure-function
  dispatch, no migration, unknown-length buffering semantics pinned
- ADR-004: exactly two production backends; manifest/path-tree layers
  are consumer-side (the corrected two-vs-three-backends framing)
- ADR-005: pooled CAS, three liveness sources, delete windows with
  pin-before-publish + delete-time arbitration (race closed), no
  ambient scheduling
- ADR-006: whole-blob verification; chunk-tree encodings excluded by
  scoping, not deferred on a paused consumer
- open-questions.md: OQ-BL-01..06 resolved with ADR cross-refs; OQ-07
  /08 externally-owned, OQ-09 deferred(scope) with SDD tracker task
- AGENTS.md: status updated to Phase 1, gix-odb path corrected

Verification: cargo test / clippy -D warnings / fmt --check clean
This commit is contained in:
glm-5.3-flash committed 2026-10-01 14:45:32 +00:00
1 parent 7d9ac8a6ec
commit 4b5009d85a
16 files changed
+1953 -8

No files matched your search

+9 -8
View File
@@ -51,10 +51,10 @@ alk* family, inspired by iroh-blobs' store work but deliberately not a
fork of it. It sits downstream of alkcall (the call + channels substrate
its network operations ride, when they exist) and its first planned
consumer is alkgit (git object storage, where the iroh-blobs hashing
story collides with git's own object hashes). Status: **Phase 0
(Exploration)** — `docs/research/` is the working state of the repo;
`docs/architecture/` does not exist yet and no wire format, API shape,
or backend trait is decided. The conventions below apply to all work in
story collides with git's own object hashes). Status: **Phase 1
(Architecture)** — Phase 0 converged (see `docs/research/phase-0.md`);
`docs/architecture/` is the working state of the repo (specs, ADRs
001-006, open-questions tracker). The conventions below apply to all work in
`src/` and `tests/`. They mirror
`.opencode/agents/implementation-specialist.md` §Project Conventions and
are repeated here so they apply to every session.
@@ -152,16 +152,17 @@ corpus replay on stable) is expected — until then ignore fuzzing.
research findings, POC records, and `phase-0.md` (vision, prior art,
open questions, converged recommendation). Read it before non-trivial
work. The SDD process lives in `docs/sdd_process.md`.
- `docs/architecture/` — does not exist yet (Phase 1 output). When it
lands, the SDD process applies: specs describe WHAT, `decisions/`
ADRs explain WHY, `open-questions.md` tracks what's unresolved.
- `docs/architecture/` — exists (Phase 1 in progress: specs draft,
ADRs 001-006 accepted, open-questions tracker active). The SDD
process applies: specs describe WHAT, `decisions/` ADRs explain WHY,
`open-questions.md` tracks what's unresolved.
- Key prior art (read-only, in the global workspace):
- **iroh-blobs** — `/workspace/iroh-blobs` (fresh upstream checkout):
the shape inspiration, specifically its store work (kv + flat file
backends, bao verification, chunking). Its wire-surface choices
(tickets, postcard, BLAKE3-only) are the ones we are deliberately
diverging from.
- **gix-odb** — `/workspace/git-oxide/gix-odb`: git's own object
- **gix-odb** — `/workspace/gitoxide/gix-odb`: git's own object
database; the backend alkgit currently plans against and the
hashing-algorithm baseline git actually uses.
- **alknet's blobs research** —