litedbmodel 2.0.2 → 2.2.0

package/dist/scp/exec-context.js

@@ -0,0 +1,540 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — the **ExecutionContext + central execute/run seam** (Phase A / #75).
+ *
+ * This module is the CONTRACT-DEFINING artifact for Phase A: it fixes the shape every runtime
+ * (TS here; rust #76 / go #77 / py #78 / php #79 port it) follows. It replaces the raw `driver`
+ * parameter threaded through `executeBundle` / `executeReadGraph` / `executeTransaction` with an
+ * {@link ExecutionContext} that carries:
+ *
+ *   1. a **connection provider** — {@link ExecutionContext.connectionFor}`(intent)` resolves WHICH
+ *      connection a statement runs on (tx-owned / reader / writer / named-DB; Phase A only wires the
+ *      tx-owned + single-DB cases, the rest are B/C/D on this same seam);
+ *   2. a **middleware chain** — {@link ExecutionContext.middleware}, wrapping every SQL (empty in
+ *      Phase A = passthrough; the registration API is Phase D — this is only the hook point);
+ *   3. {@link ExecutionContext.withConnection}`(conn, tx)` — derive a tx-scoped ctx that pins ONE
+ *      connection so every statement in a transaction body runs on it.
+ *
+ * ## The central seam (§2 of the design) — ALL SQL funnels through here
+ *
+ * ```
+ *   execute(ctx, sql, params) -> Rows      // SELECT / RETURNING reads
+ *   run(ctx, sql, params)     -> RunInfo   // INSERT/UPDATE/DELETE, BEGIN/COMMIT/ROLLBACK
+ * ```
+ *
+ * Both do the SAME three things, in order:
+ *   ① run the middleware chain (empty ⇒ passthrough, behavior unchanged);
+ *   ② resolve the connection via `ctx.connectionFor(intent)`;
+ *   ③ execute on that connection (the ONLY driver contact point).
+ *
+ * Every direct `driver.prepare(sql).all()/run()` in the read / tx / relation path is replaced by a
+ * call through this seam. A `grep` for `.prepare(` outside this file's connection adapters must come
+ * up empty in the runtime SQL path — that is the AC.
+ *
+ * ## Two flavors — sync (SQLite) and async (live PG / MySQL)
+ *
+ * The in-process better-sqlite3 path is **synchronous** (and must stay byte-identical to the frozen
+ * conformance corpus), so it uses a {@link SyncConnection} and the {@link execute} / {@link run}
+ * seam. The live PG / MySQL path is **async + pooled**, where per-execution connection ownership is
+ * what actually fixes the concurrent-tx isolation bug; it uses an {@link AsyncConnection} and the
+ * {@link executeAsync} / {@link runAsync} seam plus {@link withTransactionAsync}.
+ *
+ * Both flavors implement the SAME contract shape (`connectionFor` / `middleware` / `withConnection`
+ * / a central seam / `withTransaction`); the native ports mirror whichever their runtime needs
+ * (rust/go = the owned-connection async model; py = contextvars; php = the single-connection sync
+ * model — same contract, no ALS since PHP is 1-request-1-process).
+ *
+ * ## Per-execution connection ownership (§3) — the concurrent-tx fix
+ *
+ * A transaction acquires ONE connection, scopes it into an {@link AsyncLocalStorage} ctx, runs its
+ * body (every statement resolves that connection via `connectionFor`), COMMITs/ROLLBACKs, and
+ * releases it. Concurrent transactions each run in their own ALS ctx with their own connection —
+ * **isolated**. There is NO driver-global single-slot writer (the shared-slot model — `pool.query`
+ * per statement, or a `Mutex<Option<writer>>` — is what corrupts concurrent transactions; see the
+ * `test/integration/tx-isolation` proof).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PooledAsyncContext = exports.MiddlewareChain = void 0;
+exports.execute = execute;
+exports.executeSafe = executeSafe;
+exports.run = run;
+exports.executeAsync = executeAsync;
+exports.runAsync = runAsync;
+exports.runGuarded = runGuarded;
+exports.runGuardedAsync = runGuardedAsync;
+exports.connectionForDriver = connectionForDriver;
+exports.contextForDriver = contextForDriver;
+exports.contextForConnection = contextForConnection;
+exports.runWithPinnedAsyncConnection = runWithPinnedAsyncConnection;
+exports.currentPinnedAsyncConnection = currentPinnedAsyncConnection;
+exports.withTransactionAsync = withTransactionAsync;
+exports.transaction = transaction;
+exports.withTransactionSync = withTransactionSync;
+const node_async_hooks_1 = require("node:async_hooks");
+const tx_options_1 = require("./tx-options");
+const connection_routing_1 = require("./connection-routing");
+const middleware_1 = require("./middleware");
+/**
+ * The ordered middleware chain a ctx carries (§4). `wrap` folds the middlewares around `next`
+ * (the connection-resolve + execute terminal). An EMPTY chain is a pure passthrough — `wrap`
+ * returns `next(sql, params)` verbatim, so an unregistered chain is byte-identical. The chain is
+ * generic over the seam result type `T` so ONE shape serves both the sync (`Rows`/`RunInfo`) and
+ * async (`Promise<…>`) seams.
+ *
+ * The stack is resolved by a {@link MiddlewareStackSource} at EACH `wrap` (Phase D) rather than
+ * captured at construction, so registration (`DBModel.use`) that happens after the ctx is built is
+ * still honored and per-execution-scope registries (concurrent isolation) resolve correctly. A chain
+ * constructed with an explicit fixed stack (or none) still works — that stack is its constant source.
+ */
+class MiddlewareChain {
+    /** Resolve the CURRENT registered SQL-level middlewares, outermost first, at `wrap` time. */
+    source;
+    constructor(stackOrSource = []) {
+        this.source = typeof stackOrSource === 'function' ? stackOrSource : () => stackOrSource;
+    }
+    /** Is the chain empty RIGHT NOW (⇒ this `wrap` is a guaranteed passthrough)? */
+    get isEmpty() {
+        return this.source().length === 0;
+    }
+    /** Fold the chain around `next`, then invoke it. Empty chain ⇒ `next(sql, params)` verbatim. */
+    wrap(sql, params, next) {
+        const stack = this.source();
+        if (stack.length === 0)
+            return next(sql, params);
+        let fn = next;
+        for (let i = stack.length - 1; i >= 0; i--) {
+            const mw = stack[i];
+            const inner = fn;
+            fn = (s, p) => mw(s, p, inner);
+        }
+        return fn(sql, params);
+    }
+}
+exports.MiddlewareChain = MiddlewareChain;
+// ── The central seam (§2) — the ONLY place SQL meets a connection ─────────────
+/**
+ * Central READ seam (sync): ① middleware chain, ② resolve the connection, ③ execute. Every read
+ * (primary read node, relation batch) funnels through here.
+ */
+function execute(ctx, sql, params, intent = { write: false }) {
+    return ctx.middleware.wrap(sql, params, (s, p) => ctx.connectionFor(intent).execute(s, p));
+}
+/**
+ * Central READ seam (sync) in `safeIntegers` mode (§2 + the #59 BIGINT-exact read). Same
+ * middleware → connectionFor → execute path, but the terminal runs the SELECT in exact-integer mode
+ * so int8/BIGINT columns materialize without rounding. Used by the read walker for a BIGINT-
+ * projecting node; a non-BIGINT node uses the plain {@link execute}.
+ */
+function executeSafe(ctx, sql, params, intent = { write: false }) {
+    return ctx.middleware.wrap(sql, params, (s, p) => ctx.connectionFor(intent).executeSafeIntegers(s, p));
+}
+/**
+ * Central WRITE seam (sync): ① middleware chain, ② resolve the connection, ③ run. Every write and
+ * every tx-control statement (BEGIN/COMMIT/ROLLBACK) funnels through here (writes ⇒ `intent.write`).
+ */
+function run(ctx, sql, params, intent = { write: true }) {
+    return ctx.middleware.wrap(sql, params, (s, p) => ctx.connectionFor(intent).run(s, p));
+}
+/** Central READ seam (async) — the live PG / MySQL twin of {@link execute}. */
+function executeAsync(ctx, sql, params, intent = { write: false }) {
+    return ctx.middleware.wrap(sql, params, (s, p) => ctx.connectionFor(intent).execute(s, p));
+}
+/** Central WRITE seam (async) — the live PG / MySQL twin of {@link run}. */
+function runAsync(ctx, sql, params, intent = { write: true }) {
+    return ctx.middleware.wrap(sql, params, (s, p) => ctx.connectionFor(intent).run(s, p));
+}
+/**
+ * GUARDED write seam (sync): enforce the write=tx guard ({@link checkWriteAllowed}) for a
+ * DATA-mutating statement, then delegate to {@link run}. A write issued OUTSIDE a transaction throws
+ * {@link WriteOutsideTransactionError}; a write in a {@link withReadOnly} scope throws
+ * {@link WriteInReadOnlyContextError}. Tx-control statements (BEGIN/COMMIT/ROLLBACK/SET) are NOT
+ * guarded — the tx runtime issues them to OPEN the very scope the guard checks. This is the seam a
+ * bare model-level write (create/update/delete/upsert/batch) goes through.
+ */
+function runGuarded(ctx, sql, params, operation, modelName) {
+    (0, tx_options_1.checkWriteAllowed)(operation, modelName);
+    return run(ctx, sql, params, { write: true });
+}
+/**
+ * GUARDED write seam (async) — the live PG / MySQL twin of {@link runGuarded}. The guard is enforced
+ * inside the returned promise (an async caller gets a REJECTED promise, never a synchronous throw).
+ */
+async function runGuardedAsync(ctx, sql, params, operation, modelName) {
+    (0, tx_options_1.checkWriteAllowed)(operation, modelName);
+    return runAsync(ctx, sql, params, { write: true });
+}
+/** Adapt a better-sqlite3 `Database` to the {@link SyncConnection} seam (the ONE driver contact). */
+function connectionForDriver(driver) {
+    return {
+        execute(sql, params) {
+            return driver.prepare(sql).all(...params);
+        },
+        executeSafeIntegers(sql, params) {
+            const stmt = driver.prepare(sql);
+            // better-sqlite3: run in exact-integer mode so int8/BIGINT arrives as a bigint (the #59 hole:
+            // a JS number would round it). A driver without the toggle degrades to a plain `.all` (its
+            // rows come back in whatever exact form it natively uses — pg/mysql string BIGINT).
+            if (typeof stmt.safeIntegers === 'function')
+                stmt.safeIntegers(true);
+            return stmt.all(...params);
+        },
+        run(sql, params) {
+            return driver.prepare(sql).run(...params);
+        },
+    };
+}
+/**
+ * A thin, single-DB, middleware-free {@link ExecutionContext} over ONE connection. A tx-scoped ctx
+ * (`withConnection(conn, true)`) pins that connection for every `connectionFor` — this is the
+ * per-execution connection ownership (§3). Absent a pinned tx connection, it returns the base
+ * connection (the single-DB Phase A case; reader/writer/named-DB routing is B/C/D on this seam).
+ */
+class BasicContext {
+    middleware;
+    base;
+    /** The pinned tx connection (present ⇒ this is a tx-scoped ctx; every statement uses it). */
+    pinned;
+    constructor(base, middleware, pinned) {
+        this.base = base;
+        this.middleware = middleware;
+        this.pinned = pinned;
+    }
+    connectionFor(_intent) {
+        // Phase A resolution: the tx-owned (pinned) connection wins; else the single base connection.
+        // Reader/writer split (§3-2/3) + named-DB routing (§3-4) extend HERE in B/C/D.
+        return this.pinned ?? this.base;
+    }
+    withConnection(conn, tx) {
+        return new BasicContext(this.base, this.middleware, tx ? conn : null);
+    }
+}
+/**
+ * **Backward-compat wrapper (§6).** Wrap a raw better-sqlite3 `Database` in a thin
+ * {@link ExecutionContext}: reader = writer = the same driver, a single DB. Its middleware chain
+ * resolves the ambient/global SQL-level {@link import('./middleware').MiddlewareRegistry} at wrap
+ * time (Phase D), so a middleware registered via `DBModel.use(...)` intercepts the SQL — and, when
+ * NO middleware is registered, the chain is empty and the seam is a pure passthrough to
+ * `driver.prepare(...).all()/run()`, i.e. **byte-identical** (the conformance/livedb runners
+ * register none, so they are unchanged).
+ */
+function contextForDriver(driver) {
+    return new BasicContext(connectionForDriver(driver), new MiddlewareChain(middleware_1.activeSqlMiddlewares), null);
+}
+/**
+ * Build a sync ctx directly over a {@link SyncConnection} (for a caller that already owns a
+ * connection adapter — e.g. a non-better-sqlite3 sync backend). Same single-DB / ambient-middleware
+ * shape as {@link contextForDriver}.
+ */
+function contextForConnection(conn) {
+    return new BasicContext(conn, new MiddlewareChain(middleware_1.activeSqlMiddlewares), null);
+}
+/** Per-async-execution ambient ctx: the ALS slot carrying the tx-scoped connection (§3). */
+const asyncCtxStore = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * A pooled async {@link AsyncExecutionContext}. Outside a transaction, `connectionFor` acquires a
+ * fresh pooled connection per statement (the existing read fan-out model — each concurrent sibling
+ * on its own connection). Inside a transaction, {@link withTransactionAsync} pins ONE acquired
+ * connection into the ALS store; `connectionFor` returns THAT for every statement in the body, so
+ * the whole tx runs on one owned connection — isolated from concurrent transactions.
+ *
+ * NB: outside a tx, `connectionFor` returns a **per-statement** owned connection wrapper that
+ * acquires-runs-releases; the read walker issues one statement per `executeAsync`, matching the
+ * existing `SqlExecutorAsync` "acquire per exec" semantics byte-for-byte.
+ */
+class PooledAsyncContext {
+    middleware;
+    /**
+     * The full routing config (§3 steps 2-4): the multi-DB {@link ConnectionRegistry} + the
+     * {@link WriterStickyClock}. A ctx built from a single `pool` synthesizes a default-only registry
+     * (reader === writer) + an always-false sticky clock, so its resolution is byte-identical to the
+     * Phase A/B single-pool path. A ctx built with a {@link RoutingConfig} (via {@link setConfig})
+     * gets reader/writer separation, writer-sticky, and named-DB routing.
+     */
+    routing;
+    /**
+     * Construct from EITHER a single {@link AsyncConnectionPool} (backward-compat: default connection,
+     * reader === writer, sticky disabled — byte-identical to Phase A/B) OR a full {@link RoutingConfig}
+     * (Phase C: reader/writer separation + writer-sticky + named-DB routing).
+     */
+    constructor(poolOrRouting, middleware = new MiddlewareChain(middleware_1.activeSqlMiddlewares)) {
+        this.middleware = middleware;
+        this.routing = isRoutingConfig(poolOrRouting)
+            ? poolOrRouting
+            : // Single-pool backward-compat: default-only registry (reader === writer) + a sticky clock
+                // that is NEVER marked (so `isSticky()` stays false) ⇒ every intent lands on the one pool.
+                { registry: connection_routing_1.ConnectionRegistry.singleDefault(poolOrRouting), sticky: new connection_routing_1.WriterStickyClock({ useWriterAfterTransaction: false }) };
+    }
+    connectionFor(intent) {
+        // STEP 1 (§3): inside a tx, the ALS-pinned owned connection wins — every statement on the SAME
+        // conn (the per-execution ownership the concurrent-tx fix depends on). The tx pin is a per-scope
+        // fact only the ctx's ALS holds, so it is resolved HERE, before the pool-selection steps.
+        const pinned = asyncCtxStore.getStore();
+        if (pinned !== undefined)
+            return pinned;
+        // STEPS 2-4 (§3): named-DB → reader/writer split → writer-sticky/withWriter. `resolvePool`
+        // returns WHICH pool serves this intent; the returned wrapper acquires/runs/releases one owned
+        // connection per statement (the read fan-out: each concurrent sibling on its own connection).
+        const pool = (0, connection_routing_1.resolvePool)(intent, this.routing);
+        return {
+            async execute(sql, params) {
+                const c = await pool.acquire();
+                try {
+                    return await c.execute(sql, params);
+                }
+                finally {
+                    await pool.release(c);
+                }
+            },
+            async run(sql, params) {
+                const c = await pool.acquire();
+                try {
+                    return await c.run(sql, params);
+                }
+                finally {
+                    await pool.release(c);
+                }
+            },
+        };
+    }
+    withConnection(_conn, _tx) {
+        // Deriving a tx-scoped ctx pins the connection via the ALS run in withTransactionAsync (not by
+        // mutating this object); the derived ctx shares the routing + middleware and is never used to
+        // acquire (the ALS-pinned connection wins in `connectionFor`).
+        return this;
+    }
+    /**
+     * The WRITER pool of the connection a transaction runs against (so `withTransactionAsync` acquires
+     * the tx's owned connection from the right pool). A transaction is a write ⇒ the writer pool of the
+     * named connection (`intent.db`). Absent `db` ⇒ the default connection's writer.
+     */
+    connectionPoolFor(intent = { write: true }) {
+        return this.routing.registry.pairFor(intent.db).writer;
+    }
+    /** The default connection's writer pool (backward-compat accessor for the single-DB tx path). */
+    get connectionPool() {
+        return this.routing.registry.pairFor(undefined).writer;
+    }
+    /** The writer-sticky clock (the tx runtime `.mark()`s it on a successful write/commit). */
+    get stickyClock() {
+        return this.routing.sticky;
+    }
+}
+exports.PooledAsyncContext = PooledAsyncContext;
+/** Narrow the {@link PooledAsyncContext} ctor arg: is it a {@link RoutingConfig} (vs. a bare pool)? */
+function isRoutingConfig(x) {
+    return typeof x === 'object' && x !== null && 'registry' in x && 'sticky' in x;
+}
+/**
+ * Run `fn` inside the ALS scope with `conn` pinned as the ambient tx connection (§3). Every
+ * `connectionFor` inside `fn` (async boundaries included) returns `conn`. This is the TS
+ * per-execution ownership mechanism (v1 `DBModel.ts` `txContext.run`); the native ports use
+ * task-local (rust) / `context.Context` (go) / contextvars (py) / an explicit arg (php) for the
+ * SAME effect.
+ */
+function runWithPinnedAsyncConnection(conn, fn) {
+    return asyncCtxStore.run(conn, fn);
+}
+/**
+ * The tx-owned connection pinned in the CURRENT async scope, or `undefined` if not inside a
+ * transaction. {@link withTransactionAsync} reads this to detect a NESTED transaction (an inner
+ * `withTransactionAsync` running inside an outer's ALS scope joins the outer instead of opening a
+ * new physical transaction). The native ports read their task-local / contextvar / `context.Context`
+ * for the SAME nested detection.
+ */
+function currentPinnedAsyncConnection() {
+    return asyncCtxStore.getStore();
+}
+/**
+ * Is `err` a broken/stale connection (retryable via reconnect)? Defaulted here to a message/-code
+ * heuristic matching `src/connection-errors.ts` so exec-context needs no cross-module import; the
+ * runtime passes the shared {@link import('../connection-errors').isConnectionError} in explicitly.
+ */
+function defaultIsConnectionError(err) {
+    const message = err.message || '';
+    const code = err.code || '';
+    return (message.includes('Connection terminated') ||
+        message.includes('Client has encountered a connection error') ||
+        message.includes('ECONNRESET') ||
+        message.includes('ECONNREFUSED') ||
+        message.includes('Connection lost') ||
+        message.includes('This socket has been ended by the other party') ||
+        code === 'ECONNRESET' ||
+        code === 'ECONNREFUSED' ||
+        code === 'EPIPE' ||
+        code === 'PROTOCOL_CONNECTION_LOST');
+}
+/**
+ * Run a transaction with **per-execution connection ownership** (§3, the concurrent-tx fix) plus the
+ * full Phase B tx-completeness contract (#81): isolation level, nested-tx join, rollbackOnly, and
+ * whole-tx retry with per-attempt connection acquisition.
+ *
+ * **Per attempt** (up to `retryLimit`):
+ *   1. acquire ONE fresh connection from the pool (a retry after a connection error thus RECONNECTS);
+ *   2. pin it into the ALS ctx (`runWithPinnedAsyncConnection`) so EVERY statement `fn` issues
+ *      resolves THAT connection — never a fresh pooled one;
+ *   3. issue the isolation-aware BEGIN ({@link beginStatements}: PG `BEGIN ISOLATION LEVEL …`;
+ *      MySQL a preceding `SET TRANSACTION ISOLATION LEVEL …` then `BEGIN`);
+ *   4. run `fn(txCtx)` → `COMMIT` (or `ROLLBACK` if `rollbackOnly`, still returning the body result);
+ *   5. on a body/commit error `ROLLBACK` and either RETRY (retryable error + attempts remain, with
+ *      exponential backoff `retryDuration·2^(k-1)`) or re-raise;
+ *   6. release the connection back to the pool (DESTROYED if the ROLLBACK itself failed, or the whole
+ *      tx errored non-cleanly — a poisoned connection must not re-enter the pool).
+ *
+ * **Nested**: if a tx-owned connection is ALREADY pinned in the ALS (an outer `withTransactionAsync`
+ * on this async chain), the inner call JOINS the outer — it runs `fn` directly on the outer's ctx
+ * with NO new BEGIN/COMMIT/acquire, so the whole nested body is one physical transaction (an inner
+ * error propagates and rolls back the WHOLE tx). Mirrors v1 `DBModel.transaction` :2794-2797.
+ *
+ * Concurrent (non-nested) `withTransactionAsync` calls each acquire a DISTINCT connection and pin it
+ * in their OWN ALS scope, so their writes never cross-talk — the isolation the shared-slot model
+ * violates. This is the reference the native ports (#82-85) mirror.
+ */
+async function withTransactionAsync(ctx, fn, opts = {}, dialect = 'postgres', isConnectionError = defaultIsConnectionError, connection) {
+    // NESTED-TX JOIN (§ mirror v1 :2794): already inside a tx on this async chain ⇒ join the outer.
+    // No new connection, no BEGIN/COMMIT — the inner body is part of the outer physical transaction.
+    const outerConn = currentPinnedAsyncConnection();
+    if (outerConn !== undefined) {
+        // Reuse the outer's ctx (the pinned conn already wins in `connectionFor`). Isolation/retry/
+        // rollbackOnly options on a NESTED call are ignored — the outer transaction owns them.
+        return fn(ctx.withConnection(outerConn, true));
+    }
+    const resolved = (0, tx_options_1.resolveTxOptions)(opts);
+    const begins = (0, tx_options_1.beginStatements)(dialect, resolved.isolation);
+    // Named-DB routing (§3-4): a transaction is a write ⇒ acquire from the WRITER pool of the target
+    // connection (`connection` name, or the default). Single-DB ⇒ the one default writer pool.
+    const pool = ctx.connectionPoolFor({ write: true, ...(connection !== undefined ? { db: connection } : {}) });
+    let attempt = 0;
+    for (;;) {
+        attempt++;
+        const conn = await pool.acquire();
+        const txCtx = ctx.withConnection(conn, true);
+        // One attempt: BEGIN…body…COMMIT/ROLLBACK on the pinned conn. Returns `{ ok, value }` on success
+        // or `{ ok:false, error }` on failure — so the release + retry decision happens OUTSIDE the ALS
+        // run and the connection is released EXACTLY once per attempt.
+        let poisoned = false;
+        const attemptResult = await runWithPinnedAsyncConnection(conn, async () => {
+            for (const begin of begins)
+                await runAsync(txCtx, begin, []);
+            try {
+                // Mark the body as "inside a transaction" so a nested write's guard (`checkWriteAllowed`)
+                // and nested-tx detection see an active tx. The connection pin (above) and this marker share
+                // the SAME async scope.
+                const r = await (0, tx_options_1.runInTransactionScope)(() => fn(txCtx));
+                // rollbackOnly (dry-run): ROLLBACK but still return the body result — no committed change.
+                await runAsync(txCtx, resolved.rollbackOnly ? 'ROLLBACK' : 'COMMIT', []);
+                return { ok: true, value: r };
+            }
+            catch (error) {
+                try {
+                    await runAsync(txCtx, 'ROLLBACK', []);
+                }
+                catch {
+                    poisoned = true; // ROLLBACK failed ⇒ the connection is in an unknown state; drop it.
+                }
+                return { ok: false, error };
+            }
+        });
+        // An errored attempt saw a failed statement — destroy the (possibly poisoned) conn so a retry
+        // reconnects on a fresh one; a clean success returns the conn to the pool.
+        await pool.release(conn, poisoned || !attemptResult.ok);
+        if (attemptResult.ok) {
+            // WRITER-STICKY (§3-2, read-your-writes): a committed tx marks the sticky clock so subsequent
+            // reads within `writerStickyDuration` route to the writer pool (v1 `_lastTransactionTime`). A
+            // rollbackOnly (dry-run) tx committed NOTHING ⇒ it does NOT arm stickiness, and a tx that opted
+            // OUT per-transaction (`useWriterAfterTransaction: false`) does not arm it either — mirror v1
+            // `DBModel.transaction` :3126. The GLOBAL setting still has the last word: `mark()` is a no-op
+            // on a clock the deployment disabled, so a per-tx `true` cannot force stickiness on (v1 :487).
+            if (!resolved.rollbackOnly && resolved.useWriterAfterTransaction)
+                ctx.stickyClock.mark();
+            return attemptResult.value;
+        }
+        const { error } = attemptResult;
+        if (resolved.retryOnError && attempt < resolved.retryLimit && (0, tx_options_1.isRetryableTxError)(error, isConnectionError)) {
+            await (0, tx_options_1.sleep)(resolved.retryDuration * Math.pow(2, attempt - 1));
+            continue; // RETRY the whole transaction on a fresh connection
+        }
+        throw error;
+    }
+}
+// ── The PUBLIC user-controlled transaction boundary (§ Phase B-core / #86) ─────
+/**
+ * **The public user-controlled transaction boundary** (#86) — the REAL transaction feature v2 was
+ * missing. `transaction(ctx, fn, options?)` opens ONE boundary the caller wraps around MULTIPLE
+ * arbitrary operations so they commit or roll back TOGETHER:
+ *
+ * ```ts
+ * await transaction(ctx, async () => {
+ *   await A.create(...);   // ← every op inside joins this ONE boundary:
+ *   await B.update(...);   //    one connection, one BEGIN…COMMIT, all-or-nothing.
+ * }, { isolation: 'serializable' });
+ * ```
+ *
+ * ## What it does (v1 `DBModel.transaction` :2787 parity, on the SCP seam)
+ *
+ * It acquires ONE pooled connection, issues the isolation-aware `BEGIN`
+ * ({@link import('./tx-options').beginStatements}), PINS that connection into the ALS ctx, runs
+ * `fn`, then `COMMIT` (or `ROLLBACK` on a body error / `options.rollbackOnly`), with the #81 retry
+ * loop (deadlock / serialization / connection error) wrapped around the WHOLE boundary. It is a thin
+ * façade over {@link withTransactionAsync}: the ONE mechanism — the same acquire → pin → BEGIN →
+ * body → COMMIT/ROLLBACK → release + retry — powers both.
+ *
+ * ## The ambient-tx JOIN — how operations participate (the core #86 fix)
+ *
+ * `fn` takes NO connection argument. Instead the pinned connection lives in the ALS
+ * ({@link currentPinnedAsyncConnection}) + the "inside a transaction" marker
+ * ({@link import('./tx-options').runInTransactionScope}). Every operation `fn` issues — a live-DB
+ * write via {@link import('./makesql/tx').executeTransactionAsync}, a read via the async read seam —
+ * detects that ambient pinned connection and runs its statements on THAT connection **without opening
+ * its own BEGIN/COMMIT** (`withTransactionAsync`'s nested-join, :495). So N operations inside one
+ * `transaction(fn)` produce exactly ONE BEGIN + ONE COMMIT on ONE connection. Outside a
+ * `transaction(fn)` the ambient pin is absent, so a bare write's own `executeTransactionAsync` sees
+ * no ambient tx and the write=tx guard fires ({@link WriteOutsideTransactionError}).
+ *
+ * NESTED `transaction()` joins the outer (one physical BEGIN/COMMIT; an inner error rolls back the
+ * WHOLE tx) — again via `withTransactionAsync`'s nested-join. Isolation/retry/rollbackOnly options on
+ * a nested call are ignored (the outer owns them). This is the API REFERENCE the native ports
+ * (#82-85) mirror.
+ */
+function transaction(ctx, fn, options = {}, dialect = 'postgres', isConnectionError = defaultIsConnectionError, connection) {
+    // The boundary is `withTransactionAsync` with a body that ignores the tx ctx — ambient operations
+    // resolve the pinned connection through the ALS, not an explicit arg (v1 `txContext.run(func)`).
+    // `connection` (Phase C-2) routes the tx to a NAMED connection's writer pool (default when absent).
+    return withTransactionAsync(ctx, () => fn(), options, dialect, isConnectionError, connection);
+}
+/**
+ * **The SYNC transaction boundary (#141)** — the sync twin of {@link withTransactionAsync} for the
+ * in-process better-sqlite3 runtime. Pins ONE connection for the whole transaction (BEGIN…COMMIT on
+ * the same conn — the per-execution ownership the async path gets from the pool), issues the
+ * isolation-aware `BEGIN` ({@link beginStatements}), runs `fn(txCtx)` inside the tx scope marker
+ * (`runInTransactionScope` — so a nested write's guard/detection sees an active tx), then COMMITs or
+ * ROLLBACKs by the body's signal:
+ *   - `{ commit: true, value }`  → `COMMIT`, return `value`;
+ *   - `{ commit: false, value }` → `ROLLBACK`, return `value` (a gate short-circuit / rollbackOnly —
+ *     no committed change, but the body result is still returned, e.g. the short-circuit reason);
+ *   - a THROW from `fn`           → best-effort `ROLLBACK`, re-raise (the caller maps the driver error).
+ *
+ * Every statement `fn` issues resolves the pinned tx connection via `connectionFor` (the tx-owned
+ * conn), so the whole body runs atomically on one connection. This is the boundary the write/tx leaf
+ * path runs inside; the tx-control statements (BEGIN/COMMIT/ROLLBACK) go through the seam here, while
+ * the body's data statements ride the `executeSQL` transport leaf.
+ */
+function withTransactionSync(outer, fn, dialect = 'sqlite', isolation) {
+    const ctx = outer.withConnection(outer.connectionFor({ write: true }), true);
+    for (const begin of (0, tx_options_1.beginStatements)(dialect, isolation))
+        run(ctx, begin, []);
+    try {
+        const r = (0, tx_options_1.runInTransactionScope)(() => fn(ctx));
+        run(ctx, r.commit ? 'COMMIT' : 'ROLLBACK', []);
+        return r.value;
+    }
+    catch (e) {
+        try {
+            run(ctx, 'ROLLBACK', []);
+        }
+        catch {
+            /* ROLLBACK best-effort; the caller surfaces the original failure */
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=exec-context.js.map

package/dist/scp/exec-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-context.js","sourceRoot":"","sources":["../../src/scp/exec-context.ts"],"names":[],"mappings":"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"}

package/dist/scp/grouping.d.ts

@@ -0,0 +1,32 @@
+/**
+ * litedbmodel v2 SCP — the SHARED relation-grouping core (#141).
+ *
+ * The ONE implementation of relation key-identity + dedupe + parent grouping, used by BOTH surfaces
+ * so there is a single source of truth (no duplicated grouping logic):
+ *
+ *   - the EAGER graph — the op-independent `pluck` / `group` leaves (`./leaves`), run by bc
+ *     `bindBehaviors` (N+1-free: `parents → pluck → executeSQL(WHERE fk = ANY(keys)) → group`);
+ *   - the RUNTIME lazy / declarative path — `./relation` `runRelationOp` / `distributeToParent`, the
+ *     typed-object lazy prototype getters + declarative `with` (a lazy relation can't be a baked
+ *     graph — it fires on property access — so it keeps this grouping at runtime, over the SAME core).
+ *
+ * Nothing here touches SQL or a driver: it is pure in-memory grouping over already-fetched rows.
+ */
+/** The stringified key identity for dedupe/grouping. Single scalar → `String(v)`; tuple → joined. */
+export declare function keyIdentity(values: readonly unknown[]): string;
+/**
+ * The deduped, non-null key TUPLES of `rows` over `keyCols` (insertion order preserved —
+ * deterministic). A tuple is dropped if ANY of its key columns is null/undefined (no partial keys);
+ * deduped on the stringified tuple identity (so `1` and `"1"` collapse exactly as `String(v)`).
+ */
+export declare function dedupeKeyTuples(rows: readonly Record<string, unknown>[], keyCols: readonly string[]): unknown[][];
+/** Group `children` by their `fkCols` tuple identity (a null/undefined key drops the child). */
+export declare function groupByKey(children: readonly Record<string, unknown>[], fkCols: readonly string[]): Map<string, Record<string, unknown>[]>;
+/**
+ * Distribute grouped children onto ONE parent per cardinality: `single === false` (hasMany) → the
+ * child list (`[]` when none); `single === true` (belongsTo/hasOne) → the single child (or `null`).
+ * Keyed by the parent's `pkCols` tuple identity. `null`/`[]` is the declared cardinality's empty
+ * representation, not an ad-hoc default.
+ */
+export declare function attachToParent(parent: Record<string, unknown>, pkCols: readonly string[], byKey: Map<string, Record<string, unknown>[]>, single: boolean): Record<string, unknown>[] | Record<string, unknown> | null;
+//# sourceMappingURL=grouping.d.ts.map

package/dist/scp/grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.d.ts","sourceRoot":"","sources":["../../src/scp/grouping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAO9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,CAYjH;AAED,gGAAgG;AAChG,wBAAgB,UAAU,CACxB,QAAQ,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC5C,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAWxC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAC7C,MAAM,EAAE,OAAO,GACd,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK5D"}

package/dist/scp/grouping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping.js","sourceRoot":"","sources":["../../src/scp/grouping.ts"],"names":[],"mappings":"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"}