128 lines
9.1 KiB
Markdown
128 lines
9.1 KiB
Markdown
---
|
||
status: draft
|
||
last_updated: "2026-10-10 (ADR-024: the mem engine adopted as a third
|
||
engine — engine-mem.md added, ADR table row, index updated for the
|
||
implementation phase)"
|
||
---
|
||
|
||
# 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](overview.md)).
|
||
|
||
## Current State
|
||
|
||
**Phase 1 (Implementation) — waves 1–5 implemented and reviewed.**
|
||
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. Waves 1–5 (core, substrate fork, SQLite
|
||
engine, Postgres engine, contract suite) are implemented and reviewed
|
||
per `docs/plans/implementation.md`. The mem engine was adopted as a
|
||
third engine by [ADR-024](decisions/024-mem-engine.md) (2026-10-10,
|
||
wave 6 — release readiness renumbered to wave 7).
|
||
|
||
## 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-10 (resolved) |
|
||
| [engine-sqlite.md](engine-sqlite.md) | stable | SQLite engine: forked-substrate/rusqlite mapping | OQ-06 (resolved), OQ-12 (resolved), OQ-13 (resolved) |
|
||
| [engine-postgres.md](engine-postgres.md) | stable | Postgres engine: tokio-postgres/LISTEN mapping | OQ-08 (resolved), OQ-12 (resolved), OQ-13 (resolved) |
|
||
| [engine-mem.md](engine-mem.md) | draft | Mem engine: in-process ephemeral mapping of the contract ([ADR-024](decisions/024-mem-engine.md)) | — |
|
||
| [queues.md](queues.md) | draft | Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010) | OQ-05 (resolved), OQ-09 (resolved), OQ-06 (resolved) |
|
||
| [deployment.md](deployment.md) | draft | Host semantics, connection budgets, knobs, matrix | OQ-08 (resolved) |
|
||
| [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 lineage, bridged seam (ownership: ADR-011) | 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 |
|
||
| [008](decisions/008-contract-v1-pinning.md) | Contract v1 surface pinning — surface partition, `TxHandle` shape, wake type, reserved strings, error taxonomy | Accepted |
|
||
| [009](decisions/009-scheduler-collapse.md) | Scheduler collapse — queues + `schedule()`/`run_schedules`, `@every`-only v1, boundary guarantee row | Accepted |
|
||
| [010](decisions/010-queue-semantics-depth.md) | Queue semantics depth — visibility/renewal, backoff curve, dead-letter, no-stranded-rows sweep, schema layout | Accepted |
|
||
| [011](decisions/011-sqlite-substrate-fork.md) | SQLite substrate — fork honker-core into owned code | Accepted |
|
||
| [012](decisions/012-forked-substrate-design.md) | Forked substrate design — contract-blind boundary, fidelity posture, port deltas | Accepted |
|
||
| [013](decisions/013-fold-substrate-into-sqlite.md) | Fold the forked substrate into `alkstore-sqlite` — no fourth crate | Accepted |
|
||
| [014](decisions/014-outbox-tx-enqueue.md) | Transactional outbox enqueue — `outbox_enqueue_tx` on the `TxHandle` trait | Accepted |
|
||
| [015](decisions/015-streams-depth.md) | Streams depth — carried-metadata keys, global-FIFO ordering row, `StreamEvent` shape, `publish_with_key_tx`, `trim_to` | Accepted |
|
||
| [016](decisions/016-deployment-honesty.md) | Deployment honesty — no runtime capability surface; compile-time engine identity + documented matrix | Accepted |
|
||
| [017](decisions/017-contract-versioning.md) | Contract versioning — core crate's semver is the contract version; change classes, pairing carriers, lockstep duties | Accepted |
|
||
| [018](decisions/018-provenance-register-and-cherry-picks.md) | Substrate provenance register and cherry-pick procedure — `PROVENANCE.md` in-tree, per-delta category-tagged entries, five-step adoption discipline | Accepted |
|
||
| [019](decisions/019-mechanism-handle-surfaces.md) | Mechanism-handle surfaces — handle traits (`Queue`/`StreamHandle`/`Outbox`/`Lock`/`JobHandle`), `Job`/`Schedule` shapes, `worker_id` identity, core `StopToken` | Accepted |
|
||
| [020](decisions/020-enqueue-opt-semantics-and-bridges.md) | Enqueue-option semantics — delay/run_at precedence, relative `expires`, scheduler stamp source, serde_json payload encoding | Accepted |
|
||
| [021](decisions/021-tx-reads-and-value-shape-fixes.md) | Third review round — tx-read methods on `TxHandle`, `Job.claimed_at`, `schedule()` queue-argument validation, drop = rollback, receiver close/error arms | Accepted |
|
||
| [022](decisions/022-contract-suite-layout.md) | Contract-suite layout — shared internal suite crate, properties parameterized over a store factory (discharges ADR-017 §4.2's deferral) | Accepted |
|
||
| [023](decisions/023-fourth-review-round.md) | 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](decisions/024-mem-engine.md) | The mem engine — a third engine (`alkstore-mem`), full contract v1, honest-ephemeral posture (collapses + amends ADR-001 §4's deferral) | 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). **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](decisions/008-contract-v1-pinning.md)), ~~OQ-09~~
|
||
(scheduler collapse — [ADR-009](decisions/009-scheduler-collapse.md);
|
||
scheduler guarantee row pinned), ~~OQ-05~~ (queue semantics depth —
|
||
[ADR-010](decisions/010-queue-semantics-depth.md)), ~~OQ-06~~
|
||
(honker-core quality read — fork fired,
|
||
[ADR-011](decisions/011-sqlite-substrate-fork.md)), ~~OQ-08~~
|
||
(capability-surface shape — none, by default ever;
|
||
[ADR-016](decisions/016-deployment-honesty.md)), ~~OQ-13~~
|
||
(transactional outbox enqueue shape —
|
||
[ADR-014](decisions/014-outbox-tx-enqueue.md)), ~~OQ-12~~ (streams
|
||
depth — [ADR-015](decisions/015-streams-depth.md)), ~~OQ-10~~
|
||
(contract versioning —
|
||
[ADR-017](decisions/017-contract-versioning.md)), ~~OQ-11~~
|
||
(fork follow-through — provenance register + cherry-pick procedure,
|
||
[ADR-018](decisions/018-provenance-register-and-cherry-picks.md)).
|
||
|
||
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](decisions/021-tx-reads-and-value-shape-fixes.md) and
|
||
[ADR-023](decisions/023-fourth-review-round.md)
|
||
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. |