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:
1 parent
db73678090
commit
4391f6e879
17 files changed
+1812
-14
No files matched your search
+22
-13
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user