glm-5.3-flash
79a135c934
ADR-009: scheduler collapses into queues — schedule()/unschedule()/ run_schedules (opt-in, no ambient timers), @every-only v1 grammar (dissolves honker's local-TZ cron brittleness), boundary guarantee row (at-least-once per boundary, fixed 64-cap catch-up with skip-forward, row-locked fire tx as engine-generic no-double-fire floor), __alkstore_scheduler leadership lock, InvalidSpec + LeadershipLost taxonomy additions. ADR-010: queue depth pinned engine-uniformly — three-state machine (pending/processing/dead) with delete-on-ack, get_job sees dead rows, heartbeat = renewal with late-heartbeat refusal, reclaim-consumes- an-attempt stated as contract text, equal-jitter exponential backoff (range definitionally pinned, 1 h cap), QueueOpts stamped onto job rows at enqueue (no per-queue registry), move-to-dead dead-letter with retention-sweep support and no redrive API, sweep_expired carries the no-stranded-rows property (fixes honker's expired- processing zombie hole — SQLite-side realization rides OQ-06 as a concrete fork candidate), one engine-owned pg schema, queues are rows not tables, result-storage cut-flag stands. Also: full honker-machinery and pgboss-rs reference reads persisted (docs/research/reference-*.md — the honker defect list pre-stages the OQ-06 quality read), queues.md rewritten from design-space frame to resolved-depth spec, core-contract/engines/README/overview/deployment/ ADR-002 propagated.
97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
---
|
|
status: draft
|
|
last_updated: 2026-10-05
|
|
---
|
|
|
|
# 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 | none (capability flags, if ever, are OQ-08's to add) |
|
|
| `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 (ADR-009/ADR-010 resolved) |
|
|
| [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 |
|
|
| [008](decisions/008-contract-v1-pinning.md) | Contract v1 surface pinning (partition, TxHandle shape, wake type, reserved strings, error taxonomy) | Accepted |
|
|
| [009](decisions/009-scheduler-collapse.md) | Scheduler collapse (queues + `schedule()`, `@every`-only) | Accepted |
|
|
| [010](decisions/010-queue-semantics-depth.md) | Queue semantics depth (visibility, backoff, dead-letter, sweep, layout) | 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). |