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
@@ -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.
|
||||
Reference in new issue
Block a user