glm-5.3-flash
befbe2e714
Quality read of honker-core's watcher/transactional core cross-checked against the published crates.io artifact: the core itself is clean (Writer/Readers, polling-watcher failure handling, WatcherDeathGuard all verified), but published 0.5.0 predates upstream's unreleased fix train carrying the issue-#133 savepoint hardening (silent job loss in the dead-letter paths) and five .ok() error swallows — and ADR-010's queue depth requires engine-owned queue SQL in any posture. Resolution: fork honker-core at the reference revision, inherit the clean machinery and test suites, re-derive queue ops on contract v1, rename tables to __alkstore_*. - docs/research/quality-read-honker-core.md — full evidence - docs/architecture/decisions/011-sqlite-substrate-fork.md — decision - OQ-06 resolved in open-questions.md; ADR-003/005/008, engine-sqlite, queues, README annotated for consistency
status, last_updated
| status | last_updated |
|---|---|
| draft | 2026-10-05 |
alkstore — Architecture
Architecture documentation for the alkstore project: one reactive store interface (notify, streams, queues, locks, scheduler, outbox) over SQLite and Postgres, with each engine native underneath (see overview.md).
Current State
Phase 1 (Architecture) — in progress. 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. This directory carries the architecture spec
build-out over that evidence base; all spec documents are draft
pending architecture review and OQ resolution.
Architecture Documents
| Doc | Status | Purpose | Key OQs |
|---|---|---|---|
| overview.md | draft | Crate family, feature surface, non-goals, evidence base | — |
| core-contract.md | draft | The unified trait surface, delivery guarantees, tx seam | OQ-08, OQ-10 |
| engine-sqlite.md | draft | SQLite engine: forked-substrate/rusqlite mapping | OQ-05, OQ-06, OQ-09 (all resolved) |
| engine-postgres.md | draft | Postgres engine: tokio-postgres/LISTEN mapping | OQ-05 (resolved), OQ-08, OQ-09 (resolved) |
| queues.md | draft | Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010) | OQ-06 (resolved) |
| deployment.md | draft | Host semantics, connection budgets, knobs, matrix | OQ-08 |
| open-questions.md | draft | OQ tracker (promoted from OQ-ST register) | — |
Architecture Decision Records
| ADR | Title | Status |
|---|---|---|
| 001 | Reactive-core crate + per-engine crates | Accepted |
| 002 | Feature scope — inventory-confirmed surface | Accepted |
| 003 | SQLite engine — rusqlite + honker-core, bridged seam | Accepted |
| 004 | Postgres engine — tokio-postgres + deadpool, hand-rolled LISTEN | Accepted |
| 005 | Published libraries by default, named fork triggers | Accepted |
| 006 | Wake contract — opaque wake + re-read; notify-vs-streams split | Accepted |
| 007 | Transactional seam — caller-held TxHandle, *_tx methods |
Accepted |
| 008 | Contract v1 surface pinning — surface partition, TxHandle shape, wake type, reserved strings, error taxonomy |
Accepted |
| 009 | Scheduler collapse — queues + schedule()/run_schedules, @every-only v1, boundary guarantee row |
Accepted |
| 010 | Queue semantics depth — visibility/renewal, backoff curve, dead-letter, no-stranded-rows sweep, schema layout | Accepted |
Open Questions
Tracked in 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). Highlights, in suggested resolution order (OQ-04, OQ-09, OQ-05, OQ-06 resolved):
- OQ-06 (high): honker-core quality read — resolved (2026-10-05, ADR-011): the fork trigger fired; SQLite substrate is owned code forked from honker-core's lineage, queue ops re-derived on contract v1.
- OQ-08 (medium): capability-surface shape.
- OQ-10 (medium): contract versioning across engine crates.
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), OQ-09
(scheduler collapse — ADR-009;
scheduler guarantee row pinned), OQ-05 (queue semantics depth —
ADR-010).
No deferred OQs: all open questions are actionable Phase 1 work with complete evidence bases.
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.