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).

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	draft	Crate family, feature surface, non-goals, evidence base	—
core-contract.md	draft	The unified trait surface, delivery guarantees, tx seam	OQ-08, OQ-10, OQ-12
engine-sqlite.md	draft	SQLite engine: forked-substrate/rusqlite mapping	OQ-06 (resolved), OQ-12
engine-postgres.md	draft	Postgres engine: tokio-postgres/LISTEN mapping	OQ-05 (resolved), OQ-08, OQ-12
queues.md	draft	Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010)	OQ-06 (resolved)
deployment.md	draft	Host semantics, connection budgets, knobs, matrix	OQ-08
open-questions.md	draft	OQ tracker (promoted from OQ-ST register)	—

Architecture Decision Records

ADR	Title	Status
001	Reactive-core crate + per-engine crates	Accepted
002	Feature scope — inventory-confirmed surface	Accepted
003	SQLite engine — rusqlite + honker-core lineage, bridged seam (ownership: ADR-011)	Accepted
004	Postgres engine — tokio-postgres + deadpool, hand-rolled LISTEN	Accepted
005	Published libraries by default, named fork triggers	Accepted
006	Wake contract — opaque wake + re-read; notify-vs-streams split	Accepted
007	Transactional seam — caller-held `TxHandle`, `*_tx` methods	Accepted
008	Contract v1 surface pinning — surface partition, `TxHandle` shape, wake type, reserved strings, error taxonomy	Accepted
009	Scheduler collapse — queues + `schedule()`/`run_schedules`, `@every`-only v1, boundary guarantee row	Accepted
010	Queue semantics depth — visibility/renewal, backoff curve, dead-letter, no-stranded-rows sweep, schema layout	Accepted
011	SQLite substrate — fork honker-core into owned code	Accepted
012	Forked substrate design — contract-blind boundary, fidelity posture, port deltas	Accepted
013	Fold the forked substrate into `alkstore-sqlite` — no fourth crate	Accepted
014	Transactional outbox enqueue — `outbox_enqueue_tx` on the `TxHandle` trait	Accepted

Open Questions

Tracked in 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). Open, in suggested resolution order:

OQ-12 (high): streams depth — key semantics, StreamEvent shape, ordering guarantee row, retention (Phase 1 review find; evidence gathered in the OQ; check consumer rows for a per-key-ordering need before choosing among its options).
OQ-08 (medium): capability-surface shape.
OQ-10 (medium): contract versioning across engine crates.
OQ-11 (medium): forked-substrate follow-through (provenance register format, cherry-pick procedure; item (1) dissolved by ADR-013).

Resolved (kept with resolutions): OQ-01 (feature scope), OQ-02 (crate split), OQ-03 (drivers), OQ-07 (extension surface cut), ~~OQ-04~~ (contract v1 pinning — ADR-008), ~~OQ-09~~ (scheduler collapse — ADR-009; scheduler guarantee row pinned), ~~OQ-05~~ (queue semantics depth — ADR-010), ~~OQ-06~~ (honker-core quality read — fork fired, ADR-011), ~~OQ-13~~ (transactional outbox enqueue shape — ADR-014).

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.