docs: OQ-ST-03 gains the explicit SQLite option space (three postures)
Operator-named options, verified against the honker checkout @ f4e53c6: (1) honker-core on our own rusqlite connection (attach_honker_functions, the alknet-filesystem POC's usage); (2) honker-rs as the SQLite substrate (max reuse, least control — own connections, mutex-pinned transactions, sync-under-async-core); (3) raw SQL over sqlx-sqlite with the honker loadable extension — CI-proven in the checkout's own ORM proof suite (scripts/proof/orm/rust: transactional enqueue natively async, rollback-drops-job asserted), which dissolves most of the async tension on the SQLite side at the cost of a runtime .so dependency and watcher ownership moving in-crate. Options 1/3 are compatible with tokio-postgres on the postgres side under the OQ-ST-02 split. First-POC candidate named: options-1-vs-3 comparison on the same surface.
This commit is contained in:
1 parent
69fd5f4eda
commit
8331a96817
1 file changed
+62
-3
@@ -5,9 +5,12 @@ per-feature from the paused consumers' documents; phase-0 plan step 1
|
|||||||
done; streams upgraded to in-scope by operator-authority record; OQ-ST-02
|
done; streams upgraded to in-scope by operator-authority record; OQ-ST-02
|
||||||
resolved: reactive-core + engine crates, operator decision; alktty
|
resolved: reactive-core + engine crates, operator decision; alktty
|
||||||
REQ-TTY-01's async-facing-trait + sync-bridge posture recorded as family
|
REQ-TTY-01's async-facing-trait + sync-bridge posture recorded as family
|
||||||
precedent bearing on OQ-ST-03's async sub-question. OQ-ST-03/04/05
|
precedent bearing on OQ-ST-03; OQ-ST-03's SQLite option space expanded
|
||||||
remain the open research. Interface finding and driver tension from
|
to three named postures (honker-core on our rusqlite / honker-rs as
|
||||||
2026-10-03 remain trusted-but-unverified working input.)
|
substrate / honker extension over sqlx — the last CI-proven in the
|
||||||
|
honker checkout's own ORM proof suite). OQ-ST-03/04/05 remain open
|
||||||
|
research. Interface finding and driver tension from 2026-10-03 remain
|
||||||
|
trusted-but-unverified working input.)
|
||||||
---
|
---
|
||||||
|
|
||||||
# alkstore — Phase 0 (Exploration)
|
# alkstore — Phase 0 (Exploration)
|
||||||
@@ -416,6 +419,62 @@ Genuinely open; needs research rounds (library capabilities vs the
|
|||||||
unified-trait shape) and possibly a POC. Not deferred — this is the
|
unified-trait shape) and possibly a POC. Not deferred — this is the
|
||||||
central Phase 0 research question.
|
central Phase 0 research question.
|
||||||
|
|
||||||
|
**The SQLite option space, named explicitly (2026-10-04, operator +
|
||||||
|
verified against the checkout @ f4e53c6):** three distinct postures, not
|
||||||
|
one "rusqlite vs sqlx" axis —
|
||||||
|
|
||||||
|
1. **honker-core on our own rusqlite connection** (the
|
||||||
|
`attach_honker_functions` shape — the alknet-filesystem POC's actual
|
||||||
|
usage): we own the connection, the schema bootstrap, and the
|
||||||
|
watcher; honker supplies the SQL-function machinery.
|
||||||
|
2. **honker-rs as the crate's SQLite substrate** (`Database::open`,
|
||||||
|
typed Queue/Stream/Transaction primitives; the guide's "it *is* the
|
||||||
|
integration" posture): the trade is ownership — honker-rs opens and
|
||||||
|
holds its own connections, its `Database` wraps a connection mutex
|
||||||
|
(transactions pin the mutex; same-thread `*_tx` methods only,
|
||||||
|
deadlock-by-mutex on cross-thread reuse), and the whole engine is
|
||||||
|
sync under OUR async core (bridge at every seam). Maximum reuse,
|
||||||
|
least control; the transactional seam inherits honker-rs's
|
||||||
|
mutex-pinned transaction model rather than ours.
|
||||||
|
3. **raw SQL over sqlx-sqlite with the honker loadable extension**
|
||||||
|
(guides/orm/rust §sqlx: `SqliteConnectOptions::extension(ext)` +
|
||||||
|
`SELECT honker_bootstrap()`, then every feature is plain SQL —
|
||||||
|
`honker_enqueue`, `notify`, ... — callable through
|
||||||
|
`SqliteExecutor<'e>`, satisfied by pool, connection, AND
|
||||||
|
Transaction alike). **Verified in-harness**: the pattern is CI-proven
|
||||||
|
in the honker checkout itself (scripts/proof/orm/rust — async
|
||||||
|
business-write + `honker_enqueue` inside a `conn.begin()` tx,
|
||||||
|
commit-visibility + rollback-drops-job asserted), so the
|
||||||
|
transactional property holds *natively async* here — no sync bridge
|
||||||
|
on the call path at all.
|
||||||
|
|
||||||
|
Option 3 is the genuinely interesting one: it dissolves most of the
|
||||||
|
async tension for the SQLite engine (native-async calls, sqlx-owned
|
||||||
|
pooling, transactional enqueue proven in the checkout's own proof
|
||||||
|
suite), keeps honker's machinery as a library-free extension artifact
|
||||||
|
we don't own code-wise, and moves ALL our custom logic (watcher
|
||||||
|
ownership, stream cursors, extra SQL) into our own crate. The cost
|
||||||
|
side: a runtime-loaded .so (build-or-download per the guide) is a
|
||||||
|
packaging/deployment dependency the other options don't have; sqlx's
|
||||||
|
load-then-disable extension discipline is worth pinning at the source
|
||||||
|
(the guide documents it — `SqliteConnectOptions::extension` loads
|
||||||
|
during connect only, then disables the C load-extension API); and the
|
||||||
|
watcher (whose machinery otherwise rides option 1/2's honker-core
|
||||||
|
library linkage) becomes OUR component watching a sqlx-managed pool —
|
||||||
|
`PRAGMA data_version` re-read design (OQ-ST-04's SQLite wake side)
|
||||||
|
lands in our lap either way, but under option 3 we can't lean on
|
||||||
|
honker-core's `SharedUpdateWatcher` thread shape as-is. Options are not
|
||||||
|
mutually exclusive across engines: option 3 (or 1) for SQLite is
|
||||||
|
compatible with tokio-postgres for the Postgres engine under the
|
||||||
|
OQ-ST-02 split.
|
||||||
|
|
||||||
|
This expands OQ-ST-03's option list; the comparison matrix ("honker's
|
||||||
|
machinery as a linked library on our connection" vs "honker's machinery
|
||||||
|
as a loaded extension under sqlx") is now the concrete research round,
|
||||||
|
and a POC comparing options 1 and 3 directly (same queue/stream/notify
|
||||||
|
surface both ways, incl. watcher wiring) is the natural first POC for
|
||||||
|
the register.
|
||||||
|
|
||||||
### OQ-ST-04: The reactive abstraction — what does the unified notify surface look like?
|
### OQ-ST-04: The reactive abstraction — what does the unified notify surface look like?
|
||||||
|
|
||||||
The two engines' mechanisms are structurally different: SQLite =
|
The two engines' mechanisms are structurally different: SQLite =
|
||||||
|
|||||||
Reference in new issue
Block a user