alkstore/docs/architecture/open-questions.md

status, last_updated

status	last_updated
draft	2026-10-05

alkstore — Open Questions

Centralized tracker. IDs OQ-NN are stable — never renumber; append. The Phase 0 register's questions (OQ-ST-01..08 in docs/research/phase-0.md) are promoted here faithfully: OQ-01..08 mirror OQ-ST-01..08 one-to-one, keeping their Phase 0 statuses (a resolved register question stays listed here as resolved, with the ADR that carries its decision). New Phase 1 questions append from OQ-09. Resolution order so far: OQ-04 resolved (2026-10-05, ADR-008 — the contract surface everything else hangs off). Next: OQ-05/OQ-09 (the queue semantics track; OQ-09 also owns the scheduler guarantee row), OQ-06 (the SQLite dependency gate), OQ-08 (rides the now-pinned trait shape), OQ-10 (versioning discipline for contract extensions).

Resolved questions stay listed with their resolution; they are not deleted.

Theme: Scope

OQ-01: Scope boundary — which honker features are in-scope? (== OQ-ST-01)

• Origin: consumer-inventory.md, ADR-002
• Status: resolved (2026-10-04, Phase 0)
• Priority: medium
• Resolution: Answered by the consumer inventory — scope votes shrink to named rows, not the whole honker feature list. First-class: notify/listen (pinned), streams (operator-authority record). In scope: named locks, queues + outbox (documented), scheduler (documented-thin). Cut-flags: rate limits, result storage. Out: honker's exclusion lines. Decision recorded in ADR-002.
• Cross-references: OQ-07, OQ-04.

OQ-02: Crate scope — one store crate, or reactive-core + engines? (== OQ-ST-02)

• Origin: overview.md
• Status: resolved (2026-10-04, operator decision; Phase 0)
• Priority: medium
• Resolution: Reactive-core crate + per-engine engine crates; the split isolates the engines' asymmetry of work and keeps engine binaries single-driver (which the libsqlite3-sys collision effectively requires). Decision recorded in ADR-001 — including the reasoning that superseded the inventory's single-crate lean.
• Cross-references: OQ-03, OQ-10.

OQ-03: Driver story — sqlx, tokio-postgres, or per-engine drivers? (== OQ-ST-03)

• Origin: overview.md
• Status: resolved (2026-10-04, POC-backed both engines; Phase 0)
• Priority: medium
• Resolution: Per-engine drivers — rusqlite + honker-core 0.5.0 (SQLite; bridged seam), tokio-postgres 0.7.18 + deadpool-postgres 0.14.2 (Postgres), under OQ-02's crate split. Decisions recorded in ADR-003 and ADR-004; measurements in docs/research/poc-sqlite-posture-findings.md and docs/research/poc-pg-posture-findings.md.
• Cross-references: OQ-02, OQ-05, OQ-06.

OQ-07: SQLite-side scope — loadable extension? (== OQ-ST-07)

• Origin: ADR-002
• Status: resolved (cut-only, 2026-10-04; Phase 0)
• Priority: low
• Resolution: The loadable-extension surface is out: every identified consumer is in-process Rust attaching to its own connection (the honker-core attach_honker_functions shape). Folded into OQ-01's scope resolution and ADR-002 (explicitly, so the slot's disposition is visible — the Phase 0 register carried it as its own entry).
• Cross-references: OQ-01.

Theme: Core contract

OQ-04: Contract pinning — the exact trait surface and its semantics (== OQ-ST-04) — RESOLVED

(Retitled in promotion: OQ-ST-04's framing — "the reactive abstraction — what does the unified notify surface look like?" — narrowed to the pinning work its own record already scoped.)

• Origin: core-contract.md, ADR-006, ADR-007
• Status: resolved (2026-10-05, Phase 1 — ADR-008)
• Priority: high
• Resolution: Pinned as contract v1 by ADR-008: (1) the v1 surface partition — notify/streams/queue-skeleton/locks/outbox/tx seam are contract; queue depth rides OQ-05, scheduler shape rides OQ-09, capabilities ride OQ-08, claim_waker stays engine-internal, cut-flag rows stay out. (2) TxHandle: the *_tx methods live on the handle trait — boxed dyn handle, no downcast, no enum (the enum would invert ADR-001's dependency direction); the POCs' as_any_mut friction dissolves by construction. (3) listen() returns a WakeReceiver delivering opaque Wake { channel } — honker's payload transport is not surfaced (uniformity with the opaque contract, ADR-006). (4) Reserved prefix __alkstore_, with __alkstore_listener_reconnected__ as the one v1-reserved string (the POC's ad-hoc __listener_reconnected__ renamed at implementation). (5) Error taxonomy: PayloadTooLarge / ReservedName / InvalidName / Closed / Codec / Database, pinned by the act-differently rule. (6) Store::open is engine-crate surface; the contract is the trait it returns. (7) Locks guarantee row added to ADR-006's table (TTL-bounded mutual exclusion, silent expiry); the scheduler row is explicitly transferred to OQ-09's resolution. A verification backlog (core-contract.md §Verification backlog) tracks the one-engine-pinned properties.
• Cross-references: OQ-01, OQ-10, OQ-09, OQ-08.

Theme: Queues and scheduling

OQ-05: Queue semantics depth — retry/backoff/dead-letter/sweep design (== OQ-ST-05)

• Origin: queues.md
• Status: open (posture resolved: re-derived on both engines with the pg-boss schema family as design reference and honker's queue design as the SQLite-side one — ADR-004/ADR-005)
• Priority: high
• Resolution: open. The transactional and claim properties (the hard driver-coupled part) are POC-pinned on both engines. Remaining: the semantics-depth design — retry policy shape (attempts, backoff curve), visibility-timeout/renewal mechanics, dead-letter move-vs-flag and retention, sweep/maintenance design (sweep_expired cadence and owner), and whether result-storage's cut-flag gets reconsidered as part of this surface (it is queue-adjacent tooling).
• Cross-references: OQ-09, OQ-06.

OQ-09: Is the scheduler a first-class mechanism, or queues + schedule()?

• Origin: queues.md (spin-out of OQ-05's Phase 0 framing, where the scheduler's boundary question lived)
• Status: open
• Priority: medium
• Resolution: open. The inventory found the scheduler need real but thin (the family-wide "who sweeps/renews/reaps" problem), and mechanically scheduler = cron/@every enqueueing into named queues
  • leader election + a tick. If design confirms the collapse, the contract surface is queues + store.schedule(cron, queue) with the scheduler mechanism absorbed; if consumers need inspectable/pausable schedule objects (add/pause/resume/update/ list/remove), it stays a first-class mechanism (the full honker shape). Decided against the inventory rows, not the whole honker menu. Also owns the delivery-guarantee table's scheduler row (transferred by ADR-008 §7: under collapse the scheduler inherits the queues row; otherwise a dedicated row is pinned with the surface decision). The scheduler surface is not part of contract v1 (ADR-008 §1).
• Cross-references: OQ-05, OQ-04.

Theme: Engines and dependencies

OQ-06: honker-core quality read — does the default posture hold? (== OQ-ST-06)

• Origin: ADR-005, engine-sqlite.md
• Status: open
• Priority: high (fork trigger is a gate on the SQLite engine's dependency posture)
• Resolution: open. ADR-005 fixed the calculus and the trigger: the Phase 1 quality read of honker-core 0.5's watcher/transactional core (Writer/Readers/SharedUpdateWatcher/attach_*) — looking for defects the POCs wouldn't surface, unsafe assumptions in the watcher failure-handling, and schema-migration brittleness. Outcomes: posture holds (no ADR change), or a fork/patch need is named (fork is normal work per ADR-005).
• Cross-references: ADR-003, ADR-005, OQ-05 (if the read forces a fork, queue-on-honker-machinery work changes shape).

Theme: Deployment and capabilities

OQ-08: Where does the honest single-host/multi-host boundary live in the trait surface? (== OQ-ST-08)

• Origin: deployment.md
• Status: open
• Priority: medium
• Resolution: open. The pg engine is natively multi-host (POC #2 verified — no single-host assumption to remove); SQLite is single-machine by nature (file-backed, NFS-two-writers unsupported — honker's honesty posture, inherited). The unified surface must not pretend SQLite is multi-host. Options: per-engine capability flags (Store::capabilities()), a documented deployment matrix only (deployment.md carries the facts), or compile-time knowledge only (a consumer choosing the SQLite engine knows). Rides OQ-04: the trait's shape constrains where capability differences can surface.
• Cross-references: OQ-04, ADR-006.

OQ-10: How do engine crates track core-contract version changes?

• Origin: overview.md, ADR-001
• Status: open
• Priority: medium
• Resolution: open. The core crate's trait surface is a contract the engine crates must track (ADR-001 negative consequence). What is the versioning/sync discipline — semver-bump-only-when- contract-changes, engines pin core ranges, a contract-compatibility test suite the engines run against the core's trait definitions? What happens to a released engine crate when core makes a contract breaking change?
• Cross-references: OQ-04 (the contract being versioned), OQ-02.

Deferred / Blocked

None currently. Every open OQ above is actionable Phase 1 architecture work (contract pinning, design, quality read) with its evidence base complete — no external arrivals are being waited on.