Wave-3 decomposition: SQLite engine tasks (open/opts, seam+tx, mechanisms, integration, review gate) + core value-constructor pre-work; plan synced for waves-1-2 review + ADR-023 follow-through

tasks/sqlite-engine-open-opts.md

@@ -0,0 +1,86 @@
+---
+id: sqlite-engine-open-opts
+name: SQLite engine — `open` constructor, `SqliteOpts`, connection architecture
+status: pending
+depends_on: [core-engine-value-constructors]
+scope: moderate
+risk: medium
+impact: component
+level: implementation
+tags: [wave-3, sqlite-engine]
+---
+
+## Description
+
+Stand up the engine crate's public surface: the `open` constructor,
+`SqliteOpts`, and the connection architecture of engine-sqlite.md's
+"Connection architecture" section — the first wiring of the ported
+substrate.
+
+- `SqliteOpts` (engine-crate type, ADR-008 §6's config split — engine
+  opts live engine-side): at minimum `poll_interval:
+  Option<Duration>` (`None` = the substrate's 1 ms default,
+  ADR-023 §4 — the shipping default stands; the knob is wiring onto
+  `WatcherConfig::with_poll_interval`, which rejects zero) and
+  reader-pool size. `#[non_exhaustive]` policy does NOT apply (opts
+  structs consumers construct — ADR-017 §3's exemption; this is an
+  engine opts struct, same posture). Derive/`Default` it.
+- `open(path: &str, opts: SqliteOpts) -> Result<Box<dyn Store>>` (or
+  a concrete `SqliteStore` re-exported as the trait — implementer's
+  choice, but the trait is what consumers hold). The path is a **plain
+  filesystem path** (ADR-023 §3 — `open_conn` already dropped the URI
+  flag; do not re-add it; `:memory:` works without URI mode).
+- Connection architecture per engine-sqlite.md: one `Writer` slot
+  (substrate's `Writer`), a `Readers` pool (substrate's `Readers`),
+  and the `SharedUpdateWatcher` spawned against the db path — watcher
+  spawn is fallible (W-2): map the substrate's `Result<_, String>`
+  into `Error::Database` (the wave-2 review's watch-item; the mapping
+  is engine-layer work). Open fails if the watcher cannot start.
+- Each connection runs the substrate's bootstrap at open
+  (`open_conn` → pragmas, `attach_notify`, `attach_alkstore_functions`,
+  `bootstrap_schema`) — the writer and each pooled reader.
+- The store struct holds the shared machinery (writer slot, readers,
+  watcher handle, db path) behind the `Store` trait; `Drop`/close
+  stops the watcher and closes connections.
+- `spawn_blocking` seam posture established here for all later tasks:
+  a private helper the trait methods use (tokio dep added to the
+  engine crate — dev-dep today; make it a real dep).
+
+This task does NOT implement any trait method beyond what's needed to
+compile (the trait impls come in the mechanism tasks) — but the store
+struct, opts, and constructor are real and tested (open a temp file,
+verify bootstrap ran, verify the watcher is up, verify opts flow).
+
+## Acceptance Criteria
+
+- [ ] `SqliteOpts` exists with `poll_interval: Option<Duration>`
+      (None = 1 ms default) and reader-pool sizing; documented
+- [ ] `open(path, opts)` boots the full connection architecture:
+      writer slot, reader pool, watcher (fallible spawn mapped to
+      `Database`), substrate bootstrap on every connection
+- [ ] Plain-path posture holds: no URI flag re-introduced anywhere in
+      the open path (pinning test: a `?name=value`-suffixed path
+      creates a file with that literal name — ADR-023 §3's backlog row)
+- [ ] `poll_interval` flows to the watcher config (config-surface
+      accounting test — assert the watcher's configured cadence, not
+      wall-clock timing; ADR-023 §4's backlog row)
+- [ ] Watcher death handling wired: subscribers' receivers close
+      (mechanism lands with `listen`, but the death-guard plumbing
+      exists here)
+- [ ] `cargo test -p alkstore-sqlite`, clippy `-D warnings`, fmt clean
+
+## References
+
+- docs/architecture/engine-sqlite.md (Connection architecture)
+- docs/architecture/decisions/023-fourth-review-round.md §3, §4
+- docs/architecture/decisions/008-contract-v1-pinning.md §6
+- docs/architecture/decisions/007-transactional-seam.md (SQLite arm)
+- alkstore-sqlite/src/substrate/schema.rs, watcher.rs
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion