alkstore/docs/architecture

status, last_updated

status	last_updated
stable	2026-10-11 (the wave-8 review gate passed — pre-release freeze: the release-facing spec set flipped stable, Current State refreshed through wave 8; the class-1 window's dispositions complete, the window terminates at first publish)

alkstore — Architecture

Architecture documentation for the alkstore project: one reactive store interface (notify, streams, queues, locks, scheduler, outbox) over SQLite, Postgres, and the in-process mem engine, with each engine native underneath (see overview.md).

Current State

Phase 1 (Implementation) — waves 1–8 implemented and reviewed; the pre-release gate passed (2026-10-11). 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. All open questions are resolved (through ADR-023), and the engine specs flipped stable at the wave-5 review gate, the mem spec at wave 6. Waves 1–7 (core, substrate fork, SQLite engine, Postgres engine, contract suite, mem engine, fuzzing) are implemented and reviewed; wave 8 (release readiness: crate docs, the deployment matrix's final pass, the README, publish prep — with N-1's growth-posture acceptance, review 003 Findings 2–3, the flake investigation, and the class-1 window's last dispositions riding it) passed its review gate on 2026-10-11. ADR-024 adopted the mem engine as a third engine (2026-10-10, ADR-024). The class-1 amend-in-place window (ADR-017 §2) dispositions are complete; the window terminates permanently at the first cargo publish of alkstore — the gate's blessing covers publishing.

Architecture Documents

Doc	Status	Purpose	Key OQs
overview.md	stable	Crate family, feature surface, non-goals, evidence base	—
core-contract.md	stable	The unified trait surface, delivery guarantees, tx seam	OQ-10 (resolved)
engine-sqlite.md	stable	SQLite engine: forked-substrate/rusqlite mapping	OQ-06 (resolved), OQ-12 (resolved), OQ-13 (resolved)
engine-postgres.md	stable	Postgres engine: tokio-postgres/LISTEN mapping	OQ-08 (resolved), OQ-12 (resolved), OQ-13 (resolved)
engine-mem.md	stable	Mem engine: in-process ephemeral mapping of the contract (ADR-024)	—
queues.md	stable	Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010)	OQ-05 (resolved), OQ-09 (resolved), OQ-06 (resolved)
deployment.md	stable	Host semantics, connection budgets, knobs, matrix	OQ-08 (resolved)
open-questions.md	draft	OQ tracker (promoted from OQ-ST register) — the register's own lifecycle; the question set is closed	—

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
022	Contract-suite layout — shared internal suite crate, properties parameterized over a store factory (discharges ADR-017 §4.2's deferral)	Accepted
023	Fourth review round — encode_payload typed (Codec), numeric-argument domains by kind (extents clamp empty, durations reject, boundaries total), plain-path SQLite open (URI flag dropped), watcher cadence 1 ms default + SqliteOpts knob	Accepted
024	The mem engine — a third engine (alkstore-mem), full contract v1, honest-ephemeral posture (collapses + amends ADR-001 §4's deferral)	Accepted
025	Log facade — tracing adopted in the engine crates, silent by default, subscriber wiring on the consumer/binary; core stays dep- and emit-free (review 004 item 7's family-level decision)	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, the 2026-10-07 third review round, and the 2026-10-08 fourth review round (the waves-1–2 general review) resolved their findings directly as ADR-019/ADR-020 and ADR-021 and ADR-023 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.