litedbmodel 2.0.2 → 2.2.0

package/dist/scp/exec-context.d.ts

@@ -0,0 +1,390 @@
+/**
+ * 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).
+ */
+import { type TransactionOptions } from './tx-options';
+import { type RoutingConfig, WriterStickyClock } from './connection-routing';
+import type { Dialect } from './makesql/handler';
+/**
+ * What a statement needs from the connection provider (§3): whether it writes (so it must go to a
+ * writer / the tx-owned connection, never a read replica) and an optional named DB (multi-DB
+ * routing, Phase B). Phase A resolves only `write` (tx-owned vs. primary) and ignores `db` (single
+ * DB); the field is in the contract now so the native ports declare the SAME shape and B/C/D extend
+ * the resolver — not the seam.
+ */
+export interface StatementIntent {
+    /** The statement writes (INSERT/UPDATE/DELETE or BEGIN/COMMIT/ROLLBACK) ⇒ writer / tx connection. */
+    readonly write: boolean;
+    /** Named-DB routing key (multi-DB, Phase B). Absent ⇒ the primary DB. */
+    readonly db?: string;
+}
+/** A SELECT / RETURNING result: the raw driver rows. */
+export type Rows = Record<string, unknown>[];
+/** A non-returning write summary (INSERT/UPDATE/DELETE affected + last insert id). */
+export interface RunInfo {
+    readonly changes: number;
+    readonly lastInsertRowid: number | bigint;
+}
+/**
+ * The ONE driver contact point (§5) — a single owned SQLite connection (better-sqlite3 `Database`,
+ * or one pooled handle). The seam is the ONLY caller; the runtime SQL path never touches a driver
+ * directly. `prepareRaw` is escape-hatched ONLY for the read path's `safeIntegers` toggle (a
+ * better-sqlite3 statement-level knob the #59 BIGINT de-box needs) — it is NOT a general driver door.
+ */
+export interface SyncConnection {
+    /** Run a SELECT / RETURNING statement; resolve the raw rows. */
+    execute(sql: string, params: readonly unknown[]): Rows;
+    /**
+     * Run a SELECT in better-sqlite3 `safeIntegers` mode (the #59 BIGINT-exact read: int8 comes back
+     * as an EXACT `bigint`, not a rounded JS number). A backend with no such toggle falls back to a
+     * plain {@link SyncConnection.execute}. Kept BEHIND the seam so the read walker never touches a
+     * raw prepared statement — the `safeIntegers` knob is a driver detail, not a runtime-path concern.
+     */
+    executeSafeIntegers(sql: string, params: readonly unknown[]): Rows;
+    /** Run a non-returning write / DDL / tx-control statement; resolve the affected summary. */
+    run(sql: string, params: readonly unknown[]): RunInfo;
+}
+/** The minimal better-sqlite3 prepared statement the read path drives (with the `safeIntegers` knob). */
+export interface RawStmt {
+    all(...params: unknown[]): unknown[];
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    safeIntegers?(v: boolean): unknown;
+}
+/** The async twin: one OWNED pooled connection (PG client / mysql2 connection). */
+export interface AsyncConnection {
+    execute(sql: string, params: readonly unknown[]): Promise<Rows>;
+    run(sql: string, params: readonly unknown[]): Promise<RunInfo>;
+}
+/** The terminal of a middleware chain: resolve the connection + execute (the seam's ②③). */
+export type SeamNext<T> = (sql: string, params: readonly unknown[]) => T;
+/** One middleware: wrap a statement, delegating to `next` (Phase D supplies the registration API). */
+export type Middleware<T> = (sql: string, params: readonly unknown[], next: SeamNext<T>) => T;
+/**
+ * A source of the CURRENT SQL-level middleware stack, resolved at `wrap` time (§4, Phase D). A ctx
+ * built by the backward-compat factories carries a source that reads the ambient/global
+ * {@link import('./middleware').MiddlewareRegistry} — so a middleware registered AFTER the ctx was
+ * built (the normal `DBModel.use(...)`-then-query order) is still seen, and a per-context registry
+ * override (concurrent-request isolation) is honored. Absent ⇒ a fixed (possibly empty) stack.
+ */
+export type MiddlewareStackSource = () => readonly Middleware<unknown>[];
+/**
+ * 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.
+ */
+export declare class MiddlewareChain {
+    /** Resolve the CURRENT registered SQL-level middlewares, outermost first, at `wrap` time. */
+    private readonly source;
+    constructor(stackOrSource?: readonly Middleware<unknown>[] | MiddlewareStackSource);
+    /** Is the chain empty RIGHT NOW (⇒ this `wrap` is a guaranteed passthrough)? */
+    get isEmpty(): boolean;
+    /** Fold the chain around `next`, then invoke it. Empty chain ⇒ `next(sql, params)` verbatim. */
+    wrap<T>(sql: string, params: readonly unknown[], next: SeamNext<T>): T;
+}
+/**
+ * The SYNC execution context (better-sqlite3). Carries the connection provider, the middleware
+ * chain, and `withConnection` to derive a tx-scoped ctx. The runtime passes THIS (not a raw driver)
+ * to `executeBundle` / `executeReadGraph` / `executeTransaction`.
+ */
+export interface ExecutionContext {
+    /** Resolve WHICH connection a statement runs on (§3). Phase A: the tx-owned conn, else the primary. */
+    connectionFor(intent: StatementIntent): SyncConnection;
+    /** The middleware chain wrapping every SQL (§4). Empty in Phase A. */
+    readonly middleware: MiddlewareChain;
+    /** Derive a tx-scoped ctx pinning `conn` (every statement resolves it while `tx` is true). */
+    withConnection(conn: SyncConnection, tx: boolean): ExecutionContext;
+}
+/** The ASYNC execution context (live PG / MySQL) — the same contract, async connections. */
+export interface AsyncExecutionContext {
+    connectionFor(intent: StatementIntent): AsyncConnection;
+    readonly middleware: MiddlewareChain;
+    withConnection(conn: AsyncConnection, tx: boolean): AsyncExecutionContext;
+}
+/**
+ * Central READ seam (sync): ① middleware chain, ② resolve the connection, ③ execute. Every read
+ * (primary read node, relation batch) funnels through here.
+ */
+export declare function execute(ctx: ExecutionContext, sql: string, params: readonly unknown[], intent?: StatementIntent): Rows;
+/**
+ * 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}.
+ */
+export declare function executeSafe(ctx: ExecutionContext, sql: string, params: readonly unknown[], intent?: StatementIntent): Rows;
+/**
+ * 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`).
+ */
+export declare function run(ctx: ExecutionContext, sql: string, params: readonly unknown[], intent?: StatementIntent): RunInfo;
+/** Central READ seam (async) — the live PG / MySQL twin of {@link execute}. */
+export declare function executeAsync(ctx: AsyncExecutionContext, sql: string, params: readonly unknown[], intent?: StatementIntent): Promise<Rows>;
+/** Central WRITE seam (async) — the live PG / MySQL twin of {@link run}. */
+export declare function runAsync(ctx: AsyncExecutionContext, sql: string, params: readonly unknown[], intent?: StatementIntent): Promise<RunInfo>;
+/**
+ * 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.
+ */
+export declare function runGuarded(ctx: ExecutionContext, sql: string, params: readonly unknown[], operation: string, modelName?: string): RunInfo;
+/**
+ * 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).
+ */
+export declare function runGuardedAsync(ctx: AsyncExecutionContext, sql: string, params: readonly unknown[], operation: string, modelName?: string): Promise<RunInfo>;
+/** The minimal synchronous SQLite driver surface (better-sqlite3 `Database`) the runtime accepts. */
+export interface SqliteDriver {
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+        run(...params: unknown[]): {
+            changes: number;
+            lastInsertRowid: number | bigint;
+        };
+        safeIntegers?(v: boolean): unknown;
+    };
+}
+/** Adapt a better-sqlite3 `Database` to the {@link SyncConnection} seam (the ONE driver contact). */
+export declare function connectionForDriver(driver: SqliteDriver): SyncConnection;
+/**
+ * **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).
+ */
+export declare function contextForDriver(driver: SqliteDriver): ExecutionContext;
+/**
+ * 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}.
+ */
+export declare function contextForConnection(conn: SyncConnection): ExecutionContext;
+/**
+ * A pool that hands out an OWNED connection per acquire and takes it back on release. This is the
+ * substrate for per-execution connection ownership: a transaction `acquire()`s ONE connection,
+ * runs its whole body on it, then `release()`s it. Concurrent transactions acquire DISTINCT
+ * connections ⇒ isolation. (`pg.Pool.connect()` / `mysql2 pool.getConnection()` fit this shape.)
+ */
+export interface AsyncConnectionPool {
+    /** Check out one owned connection for the caller's exclusive use. */
+    acquire(): Promise<AsyncConnection>;
+    /** Return a connection to the pool. `destroy` ⇒ drop it (a poisoned/aborted connection). */
+    release(conn: AsyncConnection, destroy?: boolean): Promise<void>;
+}
+/**
+ * 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.
+ */
+export declare class PooledAsyncContext implements AsyncExecutionContext {
+    readonly middleware: MiddlewareChain;
+    /**
+     * 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.
+     */
+    private readonly 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: AsyncConnectionPool | RoutingConfig, middleware?: MiddlewareChain);
+    connectionFor(intent: StatementIntent): AsyncConnection;
+    withConnection(_conn: AsyncConnection, _tx: boolean): AsyncExecutionContext;
+    /**
+     * 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?: StatementIntent): AsyncConnectionPool;
+    /** The default connection's writer pool (backward-compat accessor for the single-DB tx path). */
+    get connectionPool(): AsyncConnectionPool;
+    /** The writer-sticky clock (the tx runtime `.mark()`s it on a successful write/commit). */
+    get stickyClock(): WriterStickyClock;
+}
+/**
+ * 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.
+ */
+export declare function runWithPinnedAsyncConnection<R>(conn: AsyncConnection, fn: () => Promise<R>): Promise<R>;
+/**
+ * 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.
+ */
+export declare function currentPinnedAsyncConnection(): AsyncConnection | undefined;
+/**
+ * Transaction options for {@link withTransactionAsync}. The full Phase B contract (isolation / retry
+ * / rollbackOnly) lives in {@link import('./tx-options').TransactionOptions}; this re-exports it so
+ * exec-context stays the single tx entry while the option shape + defaults + isolation-SQL mapping +
+ * retryable-error classification are defined ONCE in `tx-options.ts` (the file the 4 native ports
+ * mirror). `TxOptions` is the historical alias kept for callers; it IS `TransactionOptions`.
+ */
+export type TxOptions = TransactionOptions;
+/**
+ * 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.
+ */
+export declare function withTransactionAsync<R>(ctx: PooledAsyncContext, fn: (txCtx: AsyncExecutionContext) => Promise<R>, opts?: TransactionOptions, dialect?: Dialect, isConnectionError?: (e: Error) => boolean, connection?: string): Promise<R>;
+/**
+ * **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.
+ */
+export declare function transaction<R>(ctx: PooledAsyncContext, fn: () => Promise<R>, options?: TransactionOptions, dialect?: Dialect, isConnectionError?: (e: Error) => boolean, connection?: string): Promise<R>;
+/**
+ * **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.
+ */
+export declare function withTransactionSync<R>(outer: ExecutionContext, fn: (txCtx: ExecutionContext) => {
+    commit: boolean;
+    value: R;
+}, dialect?: Dialect, isolation?: TransactionOptions['isolation']): R;
+//# sourceMappingURL=exec-context.d.ts.map

package/dist/scp/exec-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-context.d.ts","sourceRoot":"","sources":["../../src/scp/exec-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,EACL,KAAK,kBAAkB,EAOxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,aAAa,EAElB,iBAAiB,EAElB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAKjD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wDAAwD;AACxD,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;AAE7C,sFAAsF;AACtF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IACvD;;;;;OAKG;IACH,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IACnE,4FAA4F;IAC5F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;CACvD;AAED,yGAAyG;AACzG,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACjF,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;CACpC;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChE;AAID,4FAA4F;AAC5F,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,KAAK,CAAC,CAAC;AAEzE,sGAAsG;AACtG,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;AAEzE;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe;IAC1B,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;gBAEnC,aAAa,GAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,qBAA0B;IAItF,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,gGAAgG;IAChG,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;CAWvE;AAID;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uGAAuG;IACvG,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,CAAC;IACvD,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,8FAA8F;IAC9F,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,OAAO,GAAG,gBAAgB,CAAC;CACrE;AAED,4FAA4F;AAC5F,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,OAAO,GAAG,qBAAqB,CAAC;CAC3E;AAID;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,GAAE,eAAkC,GAAG,IAAI,CAExI;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,GAAE,eAAkC,GAAG,IAAI,CAE5I;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,GAAE,eAAiC,GAAG,OAAO,CAEtI;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,GAAG,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,GAAE,eAAkC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3J;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,GAAE,eAAiC,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzJ;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAGzI;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGlK;AAID,qGAAqG;AACrG,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QACjF,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;KACpC,CAAC;CACH;AAED,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAiBxE;AA+BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAE3E;AAID;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,4FAA4F;IAC5F,OAAO,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE;AAKD;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,qBAAqB;IAC9D,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC;;;;OAIG;gBACS,aAAa,EAAE,mBAAmB,GAAG,aAAa,EAAE,UAAU,GAAE,eAA2D;IASvI,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe;IA8BvD,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,OAAO,GAAG,qBAAqB;IAO3E;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,GAAE,eAAiC,GAAG,mBAAmB;IAIjF,iGAAiG;IACjG,IAAI,cAAc,IAAI,mBAAmB,CAExC;IAED,2FAA2F;IAC3F,IAAI,WAAW,IAAI,iBAAiB,CAEnC;CACF;AAOD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvG;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,GAAG,SAAS,CAE1E;AAID;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAwB3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,GAAG,EAAE,kBAAkB,EACvB,EAAE,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,IAAI,GAAE,kBAAuB,EAC7B,OAAO,GAAE,OAAoB,EAC7B,iBAAiB,GAAE,CAAC,CAAC,EAAE,KAAK,KAAK,OAAkC,EACnE,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC,CAoEZ;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,GAAG,EAAE,kBAAkB,EACvB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,kBAAuB,EAChC,OAAO,GAAE,OAAoB,EAC7B,iBAAiB,GAAE,CAAC,CAAC,EAAE,KAAK,KAAK,OAAkC,EACnE,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC,CAKZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,gBAAgB,EACvB,EAAE,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,EAC9D,OAAO,GAAE,OAAkB,EAC3B,SAAS,CAAC,EAAE,kBAAkB,CAAC,WAAW,CAAC,GAC1C,CAAC,CAeH"}