alkstore/docs/architecture

status, last_updated

status	last_updated
draft	2026-10-06 (ADR-019/020 — second review round resolved)

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

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

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. With the question set closed (and the 2026-10-06 second review round resolving its findings directly as ADR-019/ADR-020 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.