docs: open Phase 1 — architecture spec set over the Phase 0 evidence

docs/architecture/ now exists: README index, overview, five component
specs (core-contract, engine-sqlite, engine-postgres, queues,
deployment), ADR-001..007 carrying the Phase 0 resolved decisions
(crate split, feature scope, per-engine drivers, dependency
ownership, wake contract, tx seam), and the centralized
open-questions tracker promotion: OQ-ST-01..08 mirror to OQ-01..08
one-to-one with statuses/resolutions carried; new Phase 1 questions
append (OQ-09 scheduler collapse, OQ-10 contract versioning).
Open Phase 1 work: OQ-04 contract pinning (high), OQ-05 queue
semantics depth (high), OQ-06 honker-core quality read (high;
fork-trigger gate), OQ-08 capability surface, OQ-09, OQ-10.

Erratum fixed in phase-0 OQ-ST-04 (thread-affinity friction is
SQLite-side, previously garbled as pg-side) and a stale scheduler-
boundary pointer corrected in consumer-inventory.md. Two review
passes run (findings: OQ-promotion numbering faithfulness, ADR
back-reference sync) — all critical/warning findings resolved.
This commit is contained in:
glm-5.3-flash committed 2026-10-04 18:13:10 +00:00
1 parent db73678090
commit 4391f6e879
17 files changed
+1812 -14

No files matched your search

+22 -13
View File
@@ -1,10 +1,11 @@
---
status: draft
last_updated: 2026-10-04 (Phase 0 research complete. Both POCs ran, passed,
and are folded into the register; the register itself was restructured
after the findings review for consistency. OQ-ST-01/02/03/07 resolved;
OQ-ST-04/05/06 de-risked with only contract/design work remaining;
OQ-ST-08 open. Convergence recorded in §Convergence. Next: Phase 1.)
last_updated: 2026-10-04 (Phase 0 complete and the register promoted:
docs/architecture/ opened with ADR-001..007 carrying the resolved
decisions and the OQ tracker mirroring OQ-ST-01..08 1:1. Phase 0
research itself is closed; remaining work is in docs/architecture/
open-questions.md. One erratum fixed in OQ-ST-04's tx-friction line —
thread-affinity is SQLite-side, previously garbled as "pg-side".)
---
# alkstore — Phase 0 (Exploration)
@@ -370,7 +371,10 @@ convention in the contract.
## Open Questions
Register in `docs/research/phase-0.md`; IDs OQ-ST-NN (stable, append
only). Promotion target: Phase 1 `docs/architecture/open-questions.md`.
only). Promotion target: Phase 1 `docs/architecture/open-questions.md`
— **promoted 2026-10-04**: OQ-ST-01..08 mirror 1:1 to OQ-01..08 there
(their statuses and resolutions carried; resolved decisions carried
into ADRs 001–007), and new Phase 1 questions append from OQ-09.
Status conventions: `resolved` (evidence recorded here); `open —
<work-type>` where the work-type names the remaining work and the
entry is de-risked (the remainder is Phase 1 architecture work, not
@@ -591,11 +595,14 @@ Evidence now in hand (both POCs, 2026-10-04):
caller-held tx handle (`*_tx` methods on the handle); pg's instance
is async-native (tokio-postgres Client is Send+Sync — the handle
holds the pooled connection directly, no spawn_blocking), SQLite's
is a bridged writer-slot lease. The core-crate `TxHandle` trait
from POC #1's sketch stands unchanged; the per-engine difference is
bridging mechanism, not trait shape. Phase 1 starts from that shape
plus its two recorded frictions (the `as_any_mut` downcast and the
thread-affinity of rusqlite tx ops — the latter pg-side only).
is a bridged writer-slot lease. The core-crate `TxHandle` trait
from POC #1's sketch stands unchanged; the per-engine difference is
bridging mechanism, not trait shape. Phase 1 starts from that shape
plus its two recorded frictions (the `as_any_mut` downcast and the
thread-affinity of rusqlite tx ops — the latter SQLite-side only;
erratum 2026-10-04, this line previously said "pg-side only," which
garbled POC #2's finding that the affinity friction does not carry
over to pg).
### OQ-ST-05: Queue semantics — adopt, fork, or re-derive?
@@ -743,8 +750,10 @@ The expected sequence, with what actually happened:
with the POCs; per-subsystem votes recorded at the OQs. Remaining:
the semantics-depth design inputs (OQ-ST-05) and the Phase-1
quality read (OQ-ST-06's fork trigger).
5. **Converge** — done (§Convergence). Phase 1 opens with the ADR
backlog this register becomes.
5. **Converge** — done (§Convergence). Phase 1 opened 2026-10-04:
`docs/architecture/` now exists (README index, seven ADRs
001–007 carrying this register's resolved decisions, spec docs,
and the promoted open-questions tracker).
## References