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:
1 parent
db73678090
commit
4391f6e879
17 files changed
+1812
-14
No files matched your search
@@ -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).
|
||||
Reference in new issue
Block a user