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-10 (resolved)
engine-sqlite.md	draft	SQLite engine: forked-substrate/rusqlite mapping	OQ-06 (resolved), OQ-12 (resolved), OQ-13 (resolved)
engine-postgres.md	draft	Postgres engine: tokio-postgres/LISTEN mapping	OQ-08 (resolved), OQ-12 (resolved), OQ-13 (resolved)
queues.md	draft	Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010)	OQ-05 (resolved), OQ-09 (resolved), OQ-06 (resolved)
deployment.md	draft	Host semantics, connection budgets, knobs, matrix	OQ-08 (resolved)
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
015	Streams depth — carried-metadata keys, global-FIFO ordering row, `StreamEvent` shape, `publish_with_key_tx`, `trim_to`	Accepted
016	Deployment honesty — no runtime capability surface; compile-time engine identity + documented matrix	Accepted
017	Contract versioning — core crate's semver is the contract version; change classes, pairing carriers, lockstep duties	Accepted
018	Substrate provenance register and cherry-pick procedure — `PROVENANCE.md` in-tree, per-delta category-tagged entries, five-step adoption discipline	Accepted
019	Mechanism-handle surfaces — handle traits (`Queue`/`StreamHandle`/`Outbox`/`Lock`/`JobHandle`), `Job`/`Schedule` shapes, `worker_id` identity, core `StopToken`	Accepted
020	Enqueue-option semantics — delay/run_at precedence, relative `expires`, scheduler stamp source, serde_json payload encoding	Accepted
021	Third review round — tx-read methods on `TxHandle`, `Job.claimed_at`, `schedule()` queue-argument validation, drop = rollback, receiver close/error arms	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). The open question set is empty — all thirteen OQs are resolved (2026-10-04 through 2026-10-06, ADR-001 through ADR-018).

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-08~~ (capability-surface shape — none, by default ever; ADR-016), ~~OQ-13~~ (transactional outbox enqueue shape — ADR-014), ~~OQ-12~~ (streams depth — ADR-015), ~~OQ-10~~ (contract versioning — ADR-017), ~~OQ-11~~ (fork follow-through — provenance register + cherry-pick procedure, ADR-018).

No deferred OQs. The question set closed with OQ-11 (2026-10-06); the 2026-10-06 second review round and the 2026-10-07 third review round resolved their findings directly as ADR-019/ADR-020 and ADR-021 respectively, rather than as new OQs. Phase 1 moves to architecture review closure and the implementation-phase gates.

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.