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

+92
View File
@@ -0,0 +1,92 @@
---
status: draft
last_updated: 2026-10-04
---
# alkstore — Architecture
Architecture documentation for the alkstore project: one reactive
store interface (notify, streams, queues, locks, scheduler, outbox)
over SQLite and Postgres, with each engine native underneath
(see [overview.md](overview.md)).
## Current State
**Phase 1 (Architecture) — in progress.** Phase 0 is complete
(`docs/research/phase-0.md`): both POCs ran and passed, the scope
inventory is confirmed, and the crate split, drivers, and ownership
postures are decided. This directory carries the architecture spec
build-out over that evidence base; all spec documents are `draft`
pending architecture review and OQ resolution.
## Architecture Documents
| Doc | Status | Purpose | Key OQs |
|---|---|---|---|
| [overview.md](overview.md) | draft | Crate family, feature surface, non-goals, evidence base | — |
| [core-contract.md](core-contract.md) | draft | The unified trait surface, delivery guarantees, tx seam | OQ-04, OQ-08, OQ-09, OQ-10 |
| [engine-sqlite.md](engine-sqlite.md) | draft | SQLite engine: honker-core/rusqlite mapping | OQ-05, OQ-06, OQ-09 |
| [engine-postgres.md](engine-postgres.md) | draft | Postgres engine: tokio-postgres/LISTEN mapping | OQ-05, OQ-08, OQ-09 |
| [queues.md](queues.md) | draft | Queue/scheduler/outbox semantics depth frame | OQ-05, OQ-09 |
| [deployment.md](deployment.md) | draft | Host semantics, connection budgets, knobs, matrix | OQ-04, OQ-08 |
| [open-questions.md](open-questions.md) | draft | OQ tracker (promoted from OQ-ST register) | — |
## Architecture Decision Records
| ADR | Title | Status |
|---|---|---|
| [001](decisions/001-crate-split.md) | Reactive-core crate + per-engine crates | Accepted |
| [002](decisions/002-feature-scope.md) | Feature scope — inventory-confirmed surface | Accepted |
| [003](decisions/003-sqlite-driver.md) | SQLite engine — rusqlite + honker-core, bridged seam | Accepted |
| [004](decisions/004-postgres-driver.md) | Postgres engine — tokio-postgres + deadpool, hand-rolled LISTEN | Accepted |
| [005](decisions/005-dependency-ownership.md) | Published libraries by default, named fork triggers | Accepted |
| [006](decisions/006-wake-and-delivery-contract.md) | Wake contract — opaque wake + re-read; notify-vs-streams split | Accepted |
| [007](decisions/007-transactional-seam.md) | Transactional seam — caller-held `TxHandle`, `*_tx` methods | Accepted |
## Open Questions
Tracked in [open-questions.md](open-questions.md) (OQ-01..NN; the
Phase 0 register's OQ-ST-01..08 promote one-to-one — OQ-NN mirrors
OQ-ST-NN — with new Phase 1 questions appended after). Highlights,
in suggested resolution order (OQ-04 first):
- **OQ-04** (high): contract pinning — exact trait shape, handle
representation, error taxonomy, reserved strings, guarantee rows
for locks/scheduler.
- **OQ-05** (high): queue semantics depth — retry/backoff/dead-letter/
sweep design.
- **OQ-06** (high): honker-core quality read — fork-trigger gate.
- **OQ-09** (medium): scheduler as first-class mechanism vs queues +
`schedule()`.
- **OQ-08** (medium): capability-surface shape.
- **OQ-10** (medium): contract versioning across engine crates.
Resolved (Phase 0, kept with resolutions): OQ-01 (feature scope),
OQ-02 (crate split), OQ-03 (drivers), OQ-07 (extension surface cut).
No deferred OQs: all open questions are actionable Phase 1 work with
complete evidence bases.
## Document Lifecycle
| Status | Meaning | Transitions |
|---|---|---|
| `draft` | Under active development; may change significantly | → `reviewed` when the doc's OQs are resolved |
| `reviewed` | Architecture final; implementation may begin | → `stable` when implementation verified |
| `stable` | Locked; changes need review, may warrant an ADR | → `deprecated` when superseded |
| `deprecated` | Superseded; kept for reference | Removed when unreferenced |
All spec documents carry YAML frontmatter (`status`, `last_updated`);
ADRs carry a `## Status` section (Accepted/Proposed/Superseded).
## Provenance of decisions
Phase 1 inherits its decisions from Phase 0's evidence base — every
Accepted ADR above cites its POC findings and register record. The
research documents remain the deep background:
- `docs/research/phase-0.md` — vision, prior art, OQ-ST register,
convergence.
- `docs/research/consumer-inventory.md` — per-feature scope evidence.
- `docs/research/poc-sqlite-posture-findings.md` /
`docs/research/poc-pg-posture-findings.md` — measured ground.