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.
4.8 KiB
status, last_updated
| status | last_updated |
|---|---|
| draft | 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:
| 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) | rusqlite, honker-core |
alkstore-postgres |
Postgres engine (ADR-004) | tokio-postgres, deadpool-postgres |
| (mem engine, optional) | test convenience, decided at implementation (ADR-001) | 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:
- 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 | The unified trait surface: mechanisms, delivery guarantees, tx seam, naming |
| engine-sqlite.md | SQLite engine: mapping the contract onto honker-core/rusqlite |
| engine-postgres.md | Postgres engine: mapping the contract onto tokio-postgres/LISTEN |
| queues.md | Queue/scheduler/outbox semantics depth (ADR-009/ADR-010 resolved) |
| deployment.md | Host capabilities, connection budgets, deployment matrix (OQ-08) |
| open-questions.md | OQ-01..NN tracker |
| decisions/ | ADRs |
What is decided (ADR index)
| ADR | Decision | Status |
|---|---|---|
| 001 | Reactive-core + per-engine crates | Accepted |
| 002 | Feature scope (inventory-confirmed) | Accepted |
| 003 | SQLite: rusqlite + honker-core, bridged seam | Accepted |
| 004 | Postgres: tokio-postgres + deadpool, hand-rolled LISTEN | Accepted |
| 005 | Published libraries by default, named fork triggers | Accepted |
| 006 | Opaque wake + re-read; notify-vs-streams guarantee split | Accepted |
| 007 | Caller-held TxHandle with *_tx methods |
Accepted |
| 008 | Contract v1 surface pinning (partition, TxHandle shape, wake type, reserved strings, error taxonomy) | Accepted |
| 009 | Scheduler collapse (queues + schedule(), @every-only) |
Accepted |
| 010 | 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).
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.