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. Promoted, one-to-one, from Phase 0's OQ-ST register. Resolution order so far: OQ-04 resolved (2026-10-05, ADR-008 — the contract surface everything else hangs off); OQ-09 + OQ-05 resolved (2026-10-05, ADR-009 and ADR-010 — the queue semantics track and the scheduler collapse/guarantee row). Next: OQ-06 (the SQLite dependency gate — now carrying two concrete fork candidates from the queue-depth design), 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) — RESOLVED

• Origin: queues.md
• Status: resolved (2026-10-05, Phase 1 — ADR-010)
• Priority: high
• Resolution: Pinned by ADR-010: (1) job state machine — three states (pending/processing/dead), delete-on-ack, move-to-dead (honker's model, pg-boss's seven-state enum not inherited), get_job sees dead rows (last_error/died_at — post-mortem by API; cancel unconditional, not an interrupt). (2) Visibility/heartbeat — renewal semantics (absolute reset), late-heartbeat refusal (dual-execution window is contract-honest), reclaim-consumes-an-attempt stated as contract text. (3) Retry/backoff — retry(err, None) computes the queue's equal-jitter exponential curve (range definitionally pinned, not a labeled distribution; base backoff_base_s, cap 1 h, attempt index = row attempts at retry), Some(d) overrides; queue-level QueueOpts { visibility_timeout_s, max_attempts, backoff_base_s, dead_letter_retention_s } stamped onto each job row at enqueue (§3a — no per-queue registry; two handles with different opts for one queue name don't fight). (4) Dead-letter — move-to-table, retention forever by default, no redrive API (recipe: get_job + fresh enqueue). (5) sweep_expired — the no-stranded-rows property (every past-expiry row in any state moves to dead; honker's expired-processing zombie hole fails this — fixed at contract level, SQLite-side realization rides OQ-06). (6) Sweep cadence — no ambient sweeper; the recipe is the collapse machinery (schedule + runner). (7) Result-storage cut-flag reconsidered and stands (delete-on-ack; pg-boss's completed-row model is result storage under another name). (8) Table layout — pg engine-owned schema (alkstore default), queues are rows not tables; SQLite rides _honker_*. No new error variants (ADR-008 §5's rule).
• Cross-references: OQ-09, OQ-06.

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

• Origin: queues.md (spin-out of OQ-05's Phase 0 framing, where the scheduler's boundary question lived)
• Status: resolved (2026-10-05, Phase 1 — ADR-009)
• Priority: medium
• Resolution: Collapse confirmed, decided against the inventory rows (alkblobs sweep cadence, alkfs orphan reaping — both intervals; no row names schedule objects or wall-clock cron): the contract surface is schedule(name, spec, queue, payload, opts) (upsert by name), unschedule(name), and the opt-in run_schedules(stop) runner — no Scheduler handle, no schedule objects; update = re-register, pause = unregister + re-register. Spec grammar v1: @every <n><unit> only — cron strings rejected (InvalidSpec), dissolving the timezone question honker's local-time cron brittleness poses (extension path requires a consumer-inventory row). Boundary guarantee row pinned (the transfer from ADR-008 §7 resolved): at-least-once per elapsed boundary while a leader runs, fire+advance commit atomically under a row lock on the schedule row (engine-generic no-double-fire floor; the leadership lock is the efficiency layer), bounded catch-up (fixed contract-constant cap 64) with skip-forward; leadership lock is the reserved __alkstore_scheduler name; run_schedules returns Err(LeadershipLost) on lock loss, Ok(()) on clean stop. Schedule storage engine-internal; schedules never fire without a runner (no ambient timers).
• 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 (the queue-depth read handed it two concrete fork candidates: the expired- processing-row zombie fix and dead-row get_job visibility — complement-over-machinery vs fork is exactly its calculus).

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 the now-pinned contract shape (ADR-008): the trait 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 — now including its first post-v1 extensions, ADR-009/ADR-010), OQ-02.

Deferred / Blocked

None currently. Every open OQ above is actionable Phase 1 architecture work (quality read, capability-surface shape, versioning discipline) with its evidence base complete — no external arrivals are being waited on.