docs: open Phase 1 — architecture spec set over the Phase 0 evidence

docs/architecture/ now exists: README index, overview, five component
specs (core-contract, engine-sqlite, engine-postgres, queues,
deployment), ADR-001..007 carrying the Phase 0 resolved decisions
(crate split, feature scope, per-engine drivers, dependency
ownership, wake contract, tx seam), and the centralized
open-questions tracker promotion: OQ-ST-01..08 mirror to OQ-01..08
one-to-one with statuses/resolutions carried; new Phase 1 questions
append (OQ-09 scheduler collapse, OQ-10 contract versioning).
Open Phase 1 work: OQ-04 contract pinning (high), OQ-05 queue
semantics depth (high), OQ-06 honker-core quality read (high;
fork-trigger gate), OQ-08 capability surface, OQ-09, OQ-10.

Erratum fixed in phase-0 OQ-ST-04 (thread-affinity friction is
SQLite-side, previously garbled as pg-side) and a stale scheduler-
boundary pointer corrected in consumer-inventory.md. Two review
passes run (findings: OQ-promotion numbering faithfulness, ADR
back-reference sync) — all critical/warning findings resolved.
This commit is contained in:
glm-5.3-flash committed 2026-10-04 18:13:10 +00:00
1 parent db73678090
commit 4391f6e879
17 files changed
+1812 -14

No files matched your search

+94
View File
@@ -0,0 +1,94 @@
---
status: draft
last_updated: 2026-10-04
---
# alkstore — Overview
One reactive store interface over SQLite and Postgres: durable
notify/subscribe signals, streams with per-consumer offsets, durable
queues with the transactional enqueue property, named locks, a
scheduler, and an outbox helper — with each engine using its own
native machinery underneath (SQLite: honker's watcher design;
Postgres: `pg_notify`/LISTEN and the pg-boss schema family).
## Why this crate exists
The alk* ecosystem's current shape is a repository pattern with a
default in-memory adapter, cache-invalidation wiring in hot paths, and
per-project approximations where a durable reactive substrate was
needed. alkblobs paused partly on that fuzziness. alkstore is the
substrate, made once: the answer to "how does a change in the database
become visible to other processes/connections?" that downstream stores
don't re-derive.
## Crate family
Per [ADR-001](decisions/001-crate-split.md):
| Crate | Contents | Driver dependencies |
|---|---|---|
| `alkstore` (core) | trait surface, types, error model, capability flags | none |
| `alkstore-sqlite` | SQLite engine ([ADR-003](decisions/003-sqlite-driver.md)) | rusqlite, honker-core |
| `alkstore-postgres` | Postgres engine ([ADR-004](decisions/004-postgres-driver.md)) | tokio-postgres, deadpool-postgres |
| (mem engine, optional) | test convenience, decided at implementation ([ADR-001](decisions/001-crate-split.md)) | none |
Downstream consumers depend on core + exactly one engine. Family
standards apply throughout: tokio async runtime, `thiserror` errors, no
panics in library code, no `unwrap()`/`expect()` outside tests,
lean base crate.
## Feature surface
Per [ADR-002](decisions/002-feature-scope.md):
- **First-class**: notify/listen; streams.
- **In scope**: named locks; queues + outbox helper; scheduler.
- **Cut-flag**: rate limits; result storage.
- **Out**: loadable-extension surface; DAGs/task
chains/chords/multi-writer replication/cross-machine locking.
## Document map
| Doc | Purpose |
|---|---|
| [core-contract.md](core-contract.md) | The unified trait surface: mechanisms, delivery guarantees, tx seam, naming |
| [engine-sqlite.md](engine-sqlite.md) | SQLite engine: mapping the contract onto honker-core/rusqlite |
| [engine-postgres.md](engine-postgres.md) | Postgres engine: mapping the contract onto tokio-postgres/LISTEN |
| [queues.md](queues.md) | Queue/scheduler/outbox semantics depth (OQ-05/OQ-09) |
| [deployment.md](deployment.md) | Host capabilities, connection budgets, deployment matrix (OQ-08) |
| [open-questions.md](open-questions.md) | OQ-01..NN tracker |
| [decisions/](decisions/) | ADRs |
## What is decided (ADR index)
| ADR | Decision | Status |
|---|---|---|
| [001](decisions/001-crate-split.md) | Reactive-core + per-engine crates | Accepted |
| [002](decisions/002-feature-scope.md) | Feature scope (inventory-confirmed) | Accepted |
| [003](decisions/003-sqlite-driver.md) | SQLite: rusqlite + honker-core, bridged seam | Accepted |
| [004](decisions/004-postgres-driver.md) | Postgres: 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) | Opaque wake + re-read; notify-vs-streams guarantee split | Accepted |
| [007](decisions/007-transactional-seam.md) | Caller-held `TxHandle` with `*_tx` methods | Accepted |
## Non-goals
- Not a database abstraction/ORM: the store covers the reactive
coordination surface, not general row storage (consumers keep their
own engines/schema for business data, sharing the connection when
appropriate — the outbox pattern).
- Not a network service: no transport; any networked ops surface rides
alkcall and is a separate future decision (store layer stays
substrate-free, the alkblobs store-layer precedent).
- Not multi-machine on SQLite: single-host honesty is inherited
([deployment.md](deployment.md)).
## Evidence base
Phase 0 (`docs/research/phase-0.md`) is complete: two POCs
(`poc-sqlite-posture-findings.md`, `poc-pg-posture-findings.md`) passed
all gate conditions; the consumer inventory
(`consumer-inventory.md`) graded every feature row. The Phase 1
architecture work runs over that complete evidence base; open Phase 1
work is tracked in [open-questions.md](open-questions.md).