From 7ddd4e472b2d5473a98d580f85792754f074b134 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Sun, 4 Oct 2026 09:13:50 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20resolve=20OQ-ST-02=20=E2=80=94=20reacti?= =?UTF-8?q?ve-core=20+=20engine=20crates=20(operator=20decision)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Supersedes the inventory's single-crate lean (which was inductive from 'feature sets do not diverge'). Reason recorded: the split isolates the engines' real asymmetry of work — sqlite rides honker's machinery as the baseline; postgres is the build-heavy side (LISTEN/NOTIFY + pg-boss-family schema work) — and makes future engines additive rather than feature-graph edits. The inventory's uniform-feature-family fact stands, re-read as 'the core contract stays small'; correction noted in both documents. Phase-0 plan updated (step 2 resolved, step 3 references the core-crate trait surface). --- docs/research/consumer-inventory.md | 18 ++++++++---- docs/research/phase-0.md | 43 +++++++++++++++++++---------- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/docs/research/consumer-inventory.md b/docs/research/consumer-inventory.md index bbfc7c6..e79c2f2 100644 --- a/docs/research/consumer-inventory.md +++ b/docs/research/consumer-inventory.md @@ -188,12 +188,18 @@ none of them yet. keep-with-flag), and the exclusion lines (DAGs/chains/chords, multi-writer replication, cross-machine locking — no consumer names these either; they stay out unless a consumer document grows one). -- **OQ-ST-02** gains a data point: the confirmed features (notify, - locks, queues, outbox, scheduler) are the same feature family on - both engines, which argues for the single-crate-with-feature-gated- - engines shape rather than a reactive-core + per-engine crates split - (the split buys something only if the engines' feature sets diverge - sharply, and this inventory says they don't). +- **OQ-ST-02** gained a data point here, now superseded: the + confirmed features are one feature family on both engines — read at + inventory-draft time as arguing for a single-crate shape. Resolved + **for the reactive-core + engine-crate split** on operator authority + (2026-10-04, phase-0 OQ-ST-02): the split isolates the engines' real + asymmetry of work (SQLite rides honker's existing machinery as the + baseline; Postgres is the build-heavy side under the + LISTEN/NOTIFY + pg-boss-family design brief) and makes any future + engine additive rather than a feature-graph edit. The inventory's + uniform-feature-family fact still holds — it now says the *core + contract* can stay small (one family, both engines), not that the + crates should merge. - **OQ-ST-07** sharpens: no consumer needs the *loadable extension* surface (every consumer is in-process Rust attaching to its own connection, the `honker-core`/`attach_honker_functions` shape per diff --git a/docs/research/phase-0.md b/docs/research/phase-0.md index 93a331b..986c125 100644 --- a/docs/research/phase-0.md +++ b/docs/research/phase-0.md @@ -1,10 +1,11 @@ --- status: draft last_updated: 2026-10-04 (consumer inventory landed — OQ-ST-01 answered -per-feature from the paused consumers' documents; OQ-ST-02/07 -sharpened; phase-0 plan step 1 done; streams upgraded to in-scope by -operator-authority record same day. Interface finding and driver -tension from 2026-10-03 remain trusted-but-unverified working input.) +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 +resolved: reactive-core + engine crates, operator decision. OQ-ST-03/04/05 +remain the open research. Interface finding and driver tension from +2026-10-03 remain trusted-but-unverified working input.) --- # alkstore — Phase 0 (Exploration) @@ -343,15 +344,25 @@ feature-gate pattern); a core trait crate + per-engine crates; engine crates consuming a thin core. The answer constrains the driver decision (OQ-ST-03) and the base-crate-lean invariant. -Input from the inventory (2026-10-04): the confirmed features -(notify/locks/queues/outbox/scheduler) are the same feature family on -both engines — the feature sets do not diverge sharply, which argues -for the single-crate-with-feature-gated-engines shape; a reactive-core -+ per-engine-crate split buys something only when engines' surfaces -diverge. Not yet decidable without the first engine implementation -forcing the shape; the inventory removed the "no concrete use case" -half of the deferral, the remaining half is real. Deferred(scope), -narrowed. +**Resolved (2026-10-04, operator decision): reactive-core + engine +crates — a core crate carrying the trait surface/types, per-engine +crates implementing it (sqlite, postgres; mem-shaped test engine as a +third impl if useful).** The reasoning, recorded because it overrode +the inventory's lean: the split isolates the engines' real asymmetry of +work — the SQLite engine rides honker's existing machinery as the +baseline (port-and-adapt sync→async), the Postgres engine is the +build-heavy side (LISTEN/NOTIFY wiring + pg-boss-family schema work, +OQ-ST-05) — and it makes any future engine (alkfs's in-tree needs, an +ops-surface engine) additive rather than a feature-graph edit to one +crate. More future-proof by construction; the base-crate-lean +invariant becomes structural rather than a feature-discipline. + +The inventory's uniform-feature-family fact (2026-10-04) still stands +and is not contradicted: it now reads as "the core contract can stay +small — one feature family, both engines" instead of "the crates should +merge." Its single-crate lean was inductive from that fact; the +structural reasoning above supersedes it (correction recorded in +consumer-inventory.md too). ### OQ-ST-03: Driver story — sqlx, tokio-postgres, or per-engine drivers? @@ -503,13 +514,17 @@ Expected sequence (deliberately rough): consumers' documents (alkfs phase-0, alkgit architecture, alkblobs architecture + the alknet-filesystem POC). OQ-ST-01 answered down to named per-feature rows; OQ-ST-02/07 sharpened by it. +1. ~~Crate scope (OQ-ST-02)~~ — **resolved (2026-10-04, operator + decision)**: reactive-core + engine crates. Reasoning and the + superseded inventory lean recorded at the OQ and in the inventory. 2. Research rounds on OQ-ST-03/04 (drivers + reactive shape) — library capability matrices, then a POC if the unified-trait shape needs validation (likely, given the structural mismatch noted in OQ-ST-04). The honker-rs surface (§Interface finding) is the concrete starting artifact for the OQ-ST-04 work: pinning its contract costs less and is more honest than inventing a parallel shape — now scoped against - the inventory's confirmed features rather than the full honker menu. + the inventory's confirmed features rather than the full honker menu, + and shaped as the core-crate trait surface per OQ-ST-02's split. 3. Ownership decisions (OQ-ST-05/06) — adopt/fork/derive per subsystem, after the driver and shape questions narrow the option space. 4. Converge; Phase 1 opens with the ADR backlog this register becomes.