litedbmodel 2.0.0 → 2.0.1

package/dist/scp/runtime.js

@@ -1,417 +1,179 @@
 "use strict";
 /**
- * litedbmodel v2 SCP — the thin TS runtime (WS3, #23; spec §3 / §10 / §11).
+ * litedbmodel v2 SCP — the thin TS runtime on the STATIC makeSQL bundle (WS3, #23; makeSQL
+ * flip, epic #43/#45 Phase B; spec §3 / §10 / §11).
  *
- * Consumes bc's runtime-core (`runBehavior` = plan stage execution + map/wire/skip
- * propagation + Φ output assembly) and adds ONLY the SQL-backend concerns (spec §11):
- * Backend-Compile bridge (WS1↔WS3), per-Catalog Handlers (render → driver execute →
- * row→model assembly), and Error Mapping. It re-implements NO generic execution.
+ * makeSQL is the SOLE SCP compile/execute path. A behavior method compiles (SYMBOLICALLY — no
+ * concrete input) to a {@link SqlBundle}:
+ *   - a READ bundle carries a {@link ReadGraph} — the surrogate bc `ComponentGraphIR` (each SQL
+ *     node → a `makeSQL` node) + per-node static statement templates. bc `runBehavior` drives
+ *     map iteration / wire binding / Φ output; the makeSQL handler renders each node's statements
+ *     (value-specs + skip evaluated per-input) and executes real SQL ("bc composes, makeSQL
+ *     executes"). Read-relation batch ops ride the bundle too.
+ *   - a WRITE bundle carries a single `makeSQL` statement (the base write) + the derived gate-first
+ *     {@link TransactionPlan} for a Command with write-time relations.
  *
- * ## Execution pipeline (spec §3)
- *
- *   validate → fragment select (SKIP) → array expand → Expression eval → bind → SQL execute
- *   → assembly
- *
- * bc's `runBehavior` owns the orchestration (which node runs when, map iteration, wire
- * binding, output merge). But the SQL-structural ports (`where` fragment tree, `limit`, …)
- * MUST NOT go through bc's generic port evaluation — a `where` `{arr:[…]}` of comparison
- * Expressions would evaluate to bare booleans (losing the SQL structure), and a SKIP guard
- * over an ABSENT optional input would fail-closed with `UNKNOWN_BINDING`. So the runtime:
- *
- *  1. Backend-Compiles every SQL node up front ({@link import('./bridge').compileNode}) to a
- *     WS1 `CompiledOperation` (SQL text + fragment tree + closed-set param slots).
- *  2. Rewrites the IR into a SURROGATE graph: each SQL node keeps its `id` / wiring / `map`
- *     shape, but its ports collapse to ONE synthetic `__scope` port — a bc `{obj:…}` that
- *     re-exports every binding head the op references (`input` names, wire node ids, the
- *     `map` element `as`). bc evaluates `__scope` in ITS scope (so `input`, sibling results
- *     and the map element all resolve through bc's own machinery) and hands the plain scope
- *     to the handler. No SQL-structural port is ever evaluated by bc.
- *  3. Each handler renders its pre-compiled op against `ports.__scope` via WS1's normative
- *     {@link renderOperation} (fragment select + array expand + Expression eval), binds the
- *     params through the driver, executes REAL SQL, and returns the row list (assembly).
+ * The reduced spine (`CompiledOperation` + `FragmentTree` + `renderOperation`) is RETIRED — this
+ * module carries no reduced IR. Reads execute via {@link import('./makesql/static-bundle')} (bc
+ * `runBehavior` + makeSQL handler); writes via {@link import('./makesql/tx')} (gate-first tx-DAG).
  *
  * ## Input normalization (SSoT — defaults live in the schema, not code)
  *
- * An OPTIONAL Input Port that the caller omits is normalized to `null` (present-as-null) so
- * a SKIP guard `{ne:[{refOpt:[port]}, null]}` evaluates to `false` and drops its fragment —
- * absent-key SKIP via `refOpt`. This is driven by the component's `inputPorts` schema
- * (`required !== true` ⇒ optional), NOT an ad-hoc `?? null` in engine code: the schema is
- * the single source of truth for which ports are optional.
+ * An OPTIONAL input head the caller omits is normalized to `null` (present-as-null) so a SKIP
+ * presence expression drops its fragment (absent-key SKIP). "Optional" comes from the bundle's
+ * `optionalHeads` (schema-optional + SKIP-guarded + every `refOpt` head) — the SSoT.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqlFailure = void 0;
-exports.buildHandlers = buildHandlers;
-exports.normalizeInput = normalizeInput;
 exports.executeBehavior = executeBehavior;
 exports.compileBundle = compileBundle;
 exports.executeBundle = executeBundle;
+exports.executeBundleAsync = executeBundleAsync;
+exports.executeBehaviorAsync = executeBehaviorAsync;
 exports.compileWriteBundle = compileWriteBundle;
 exports.compileCompositeWriteBundle = compileCompositeWriteBundle;
+exports.compileCreateManyBundle = compileCreateManyBundle;
+exports.compileUpdateManyBundle = compileUpdateManyBundle;
+exports.compileDeleteManyBundle = compileDeleteManyBundle;
 exports.executeCompositeCommand = executeCompositeCommand;
 exports.executeCommand = executeCommand;
 exports.executeTransactionBundle = executeTransactionBundle;
 exports.read = read;
 exports.readBundle = readBundle;
-exports.resolveRelationViaPlan = resolveRelationViaPlan;
-const behavior_contracts_1 = require("behavior-contracts");
-const bridge_1 = require("./bridge");
-const render_1 = require("./render");
 const errors_1 = require("./errors");
 Object.defineProperty(exports, "SqlFailure", { enumerable: true, get: function () { return errors_1.SqlFailure; } });
 const relation_1 = require("./relation");
 const typed_object_1 = require("./typed-object");
-const bridge_2 = require("./bridge");
-const write_plan_1 = require("./write-plan");
-const write_runtime_1 = require("./write-runtime");
+const static_bundle_1 = require("./makesql/static-bundle");
+const tx_1 = require("./makesql/tx");
+const compile_crud_1 = require("./makesql/compile-crud");
+const makesql_1 = require("./makesql/makesql");
 const writes_1 = require("./writes");
-const dialect_1 = require("./dialect");
-/** The synthetic port that carries a SQL node's render scope (see module doc). */
-const SCOPE_PORT = '__scope';
-// ── Value normalization at the SQL boundary ───────────────────────────────────
-/**
- * bc evaluates integers to `bigint`. Convert a rendered param to a driver-bindable value:
- * a safe-range `bigint` → JS `number` (v1 uses numbers; keeps result parity), an
- * out-of-safe-range `bigint` stays `bigint` (better-sqlite3 binds it losslessly). Arrays /
- * objects are IN-list elements / already-flat scalars; strings / booleans / null pass
- * through. This mirrors graphddb's `toPlain` boundary conversion.
- */
-function toDriverParam(v) {
-    if (typeof v === 'bigint') {
-        if (v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER))
-            return Number(v);
-        return v; // better-sqlite3 binds a BigInt losslessly for i64-range values
-    }
-    return v;
-}
-// ── Ref-head collection (build the surrogate `__scope` port) ──────────────────
-/** Collect every ref/refOpt path HEAD used inside an Expression IR node. */
-function collectHeads(node, heads) {
-    if (node === null || typeof node !== 'object')
-        return;
-    if (Array.isArray(node)) {
-        for (const el of node)
-            collectHeads(el, heads);
-        return;
-    }
-    const keys = Object.keys(node);
-    if (keys.length === 1 && (keys[0] === 'ref' || keys[0] === 'refOpt')) {
-        const path = node[keys[0]];
-        if (Array.isArray(path) && typeof path[0] === 'string')
-            heads.add(path[0]);
-        return;
-    }
-    for (const k of keys)
-        collectHeads(node[k], heads);
-}
-/**
- * Collect every path HEAD accessed via `refOpt` in an Expression IR node. A `refOpt` head
- * is OPTIONAL by construction — the author reached for `opt(…)` / `refOpt` precisely because
- * the binding may be absent (a `coalesce`-defaulted LIMIT, a SKIP presence guard). It is
- * therefore normalized to present-as-null (SSoT: the `refOpt` is the optionality
- * declaration, not an ad-hoc code default).
- */
-function collectRefOptHeads(node, heads) {
-    if (node === null || typeof node !== 'object')
-        return;
-    if (Array.isArray(node)) {
-        for (const el of node)
-            collectRefOptHeads(el, heads);
-        return;
-    }
-    const keys = Object.keys(node);
-    if (keys.length === 1 && keys[0] === 'refOpt') {
-        const path = node.refOpt;
-        if (Array.isArray(path) && typeof path[0] === 'string')
-            heads.add(path[0]);
-        return;
-    }
-    for (const k of keys)
-        collectRefOptHeads(node[k], heads);
-}
-/** Collect ref heads from a whole fragment tree (its `when` guards + param slots). */
-function collectFragmentHeads(node, heads) {
-    if ('connector' in node) {
-        for (const f of node.fragments)
-            collectFragmentHeads(f, heads);
-        return;
-    }
-    if (node.when !== undefined)
-        collectHeads(node.when, heads);
-    for (const p of node.params)
-        collectHeads(p, heads);
-}
-/** Every binding head a compiled op references (static params + fragment tree). */
-function operationHeads(op) {
-    const heads = new Set();
-    for (const p of op.params)
-        collectHeads(p, heads);
-    if (op.where !== null)
-        collectFragmentHeads(op.where, heads);
-    return heads;
-}
-/**
- * Collect the binding heads that live UNDER a SKIP guard: every head in a `when`-guarded
- * fragment's guard OR its params. A SKIP guard is the structural declaration that its
- * driving input is OPTIONAL (spec §7: `cond ? [...] : SKIP`) — so an absent such head is
- * normalized to null (present-as-null), letting `refOpt` drop the fragment. This is
- * schema/structure-driven, not an ad-hoc code default: the SKIP fragment IS the SSoT that
- * the input is optional.
- */
-function skipGuardedHeads(node, heads) {
-    if ('connector' in node) {
-        for (const f of node.fragments)
-            skipGuardedHeads(f, heads);
-        return;
-    }
-    if (node.when !== undefined) {
-        collectHeads(node.when, heads);
-        for (const p of node.params)
-            collectHeads(p, heads);
-    }
-}
-/** Collect every `refOpt` head across a compiled op (static params + fragment tree). */
-function operationRefOptHeads(op, heads) {
-    for (const p of op.params)
-        collectRefOptHeads(p, heads);
-    if (op.where !== null)
-        collectFragmentRefOptHeads(op.where, heads);
-}
-/** Collect `refOpt` heads from a whole fragment tree (guards + param slots). */
-function collectFragmentRefOptHeads(node, heads) {
-    if ('connector' in node) {
-        for (const f of node.fragments)
-            collectFragmentRefOptHeads(f, heads);
-        return;
-    }
-    if (node.when !== undefined)
-        collectRefOptHeads(node.when, heads);
-    for (const p of node.params)
-        collectRefOptHeads(p, heads);
-}
-/**
- * All OPTIONAL heads across a set of compiled ops: the SKIP-guarded heads (a `when`-guarded
- * fragment declares its driving input optional) plus every `refOpt`-accessed head (the
- * author declared it optional via `opt(…)`). These are normalized to present-as-null so
- * `refOpt` drops/defaults cleanly instead of failing on an absent head.
- */
-function optionalHeadsOf(compiled) {
-    const heads = new Set();
-    for (const op of Object.values(compiled)) {
-        if (op.where !== null)
-            skipGuardedHeads(op.where, heads);
-        operationRefOptHeads(op, heads);
-    }
-    return heads;
-}
-/**
- * Build the surrogate `__scope` port for a SQL node: a bc `{obj:{…}}` re-exporting each
- * referenced head as `{ref:[head]}`. Excludes the IN-sentinel head (`@in` is a column
- * marker, never a real binding). bc evaluates this in its own scope, so `input` names,
- * wire node ids, and the `map` element `as` all resolve; the handler then renders the op
- * against the resulting plain scope. A head that is genuinely absent surfaces as bc's
- * `UNKNOWN_BINDING` — the runtime pre-normalizes OPTIONAL input heads to null so only a
- * real wiring bug reaches that fail-closed path.
- */
-function scopePort(op) {
-    const obj = {};
-    for (const head of operationHeads(op)) {
-        if (head === '@in')
-            continue; // IN-list sentinel column marker, not a binding
-        obj[head] = { ref: [head] };
-    }
-    return { obj };
-}
-/** Rewrite one body node to its surrogate (SQL nodes → single `__scope` port). */
-function surrogateNode(node, compiled) {
-    if ('cond' in node)
-        return node; // pure Expression — bc evaluates it unchanged
-    if ('map' in node) {
-        const op = compiled[node.id];
-        if (op === undefined)
-            return node;
-        return { ...node, map: { ...node.map, ports: { [SCOPE_PORT]: scopePort(op) } } };
+/** The primary catalog node of a component (the first non-cond, non-map body node). */
+function primaryNodeOf(component) {
+    for (const n of component.body) {
+        if ('cond' in n)
+            continue;
+        if ('map' in n)
+            continue;
+        return n;
     }
-    const op = compiled[node.id];
-    if (op === undefined)
-        return node;
-    return { ...node, ports: { [SCOPE_PORT]: scopePort(op) } };
+    return undefined;
 }
-/** Rewrite a whole component to its surrogate graph (structure + wiring preserved). */
-function surrogateComponent(component, compiled) {
-    return { ...component, body: component.body.map((n) => surrogateNode(n, compiled)) };
+/** Is a component's primary catalog node a write (Insert/Update/Delete)? */
+function isWriteComponent(component) {
+    const p = primaryNodeOf(component);
+    if (p === undefined || 'map' in p)
+        return false;
+    const c = p.component;
+    return c === 'Insert' || c === 'Update' || c === 'Delete';
 }
-// ── Handlers (render → execute → assembly) ────────────────────────────────────
 /**
- * Execute one rendered SQL statement against the driver and return the row list (assembly).
- * A SELECT / RETURNING statement returns its rows; a non-returning write returns a
- * single-row summary `[{ changes, lastInsertRowid }]` (the RETURNING-less write shape). A
- * driver error is mapped ({@link mapSqliteError}) and returned as bc `{ error }` so the
- * node's Policy Kind governs propagation.
- */
-function executeRendered(db, op, scope, dialect) {
-    const rendered = (0, render_1.renderOperation)(op, scope, dialect);
-    const params = rendered.params.map(toDriverParam);
-    let stmt;
-    try {
-        stmt = db.prepare(rendered.sql);
-    }
-    catch (e) {
-        return { error: (0, errors_1.mapSqliteError)(e).message };
-    }
-    const hasReturn = op.component === 'Select' || /\breturning\b/i.test(rendered.sql);
-    try {
-        if (hasReturn) {
-            const rows = stmt.all(...params);
-            return { ok: rows };
-        }
-        const info = stmt.run(...params);
-        return {
-            ok: [{ changes: info.changes, lastInsertRowid: toDriverParam(BigInt(info.lastInsertRowid)) }],
-        };
-    }
-    catch (e) {
-        return { error: (0, errors_1.mapSqliteError)(e).message };
-    }
-}
-/**
- * Build the SQL handler registry: one handler per SQL Catalog name (spec §11 item 4).
+ * Execute a published behavior contract (WS2 {@link BehaviorModelContract}) end-to-end via the
+ * static makeSQL bundle. Returns the component's output (a read Φ output / row list, or a write's
+ * RETURNING rows / `[{changes, lastInsertRowid}]` summary).
  *
- * Exported so the mode-3 codegen path (WS7f) binds the IDENTICAL SQL handlers into bc's
- * generated `bind(handlers)` accessor — the generated module bakes the surrogate IR literal and
- * calls the SAME `runBehavior`, so pairing it with THIS handler builder makes the codegen output
- * byte-identical to {@link executeBundle} by construction (not a parallel reimplementation).
- */
-function buildHandlers(db, compiled, dialect) {
-    const handle = (ports, ctx) => {
-        const op = compiled[ctx.nodeId];
-        if (op === undefined) {
-            return { error: `scp runtime: no compiled operation for node '${ctx.nodeId}' (${ctx.component})` };
-        }
-        const scope = ports[SCOPE_PORT];
-        if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) {
-            return { error: `scp runtime: node '${ctx.nodeId}' surrogate scope did not evaluate to an object` };
-        }
-        return executeRendered(db, op, scope, dialect);
-    };
-    // One binding per SQL CRUD Catalog name (all share the render→execute handler; the
-    // pre-compiled op keyed by nodeId already encodes the per-node operation).
-    return { Select: handle, Insert: handle, Update: handle, Delete: handle };
-}
-// ── Input normalization (schema-driven — SSoT) ────────────────────────────────
-/**
- * Normalize the caller input to `null` (present-as-null) for every OPTIONAL binding the
- * caller omitted, so a SKIP guard using `refOpt` evaluates to `false` and drops its
- * fragment (absent-key SKIP). "Optional" is determined from the SSoT, NOT an ad-hoc code
- * default — a head is optional iff EITHER (a) the component's Input Port schema marks the
- * port `required !== true`, OR (b) the head is SKIP-guarded in a compiled fragment (the
- * SKIP fragment declares its driving input optional — spec §7). A REQUIRED, non-SKIP head
- * that is missing is left absent so a real wiring bug surfaces loudly as bc's
- * `UNKNOWN_BINDING` rather than being silently defaulted.
- */
-function normalizeInput(component, optionalHeads, input) {
-    const out = { ...input };
-    for (const [port, schema] of Object.entries(component.inputPorts)) {
-        if (schema.required !== true && !(port in out))
-            out[port] = null;
-    }
-    for (const head of optionalHeads) {
-        if (!(head in out))
-            out[head] = null;
-    }
-    return out;
-}
-/**
- * Execute a published behavior contract (WS2 {@link BehaviorModelContract}) end-to-end:
- * Backend-Compile every SQL node → surrogate IR → bc `runBehavior` (plan / map / wire /
- * output) with SQL handlers → REAL SQLite execution → assembled Φ output.
- *
- * This is α's vertical slice: authoring → IR → Backend-Compile → thin runtime → real
- * SQLite → assembly. The returned Value is the component's `output` (Φ merge) with each SQL
- * node's slot filled by its executed row list.
- *
- * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary (a `fail`-policy
- *   node re-throws through `runPlan` as `OP_FAILED`; the runtime unwraps it back to the
- *   structured {@link SqlFailure} so the caller sees `kind` / `policy` / `sqliteCode`).
+ * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary.
  */
 function executeBehavior(contract, input, options) {
     return executeBundle(compileBundle(contract, options.entry, options.relations, options.dialect), input, options);
 }
 /**
- * Backend-Compile ONE behavior method of a contract into the serializable {@link SqlBundle}
- * (spec §8) — the published multi-language artifact. This runs the WS1↔WS3 bridge and the
- * surrogate rewrite ONCE, on the TS side (spec §10: the dialect axis is compiled once), and
- * emits pure JSON: no TS runtime state is captured, so `JSON.stringify(bundle)` round-trips
- * losslessly and a thin per-language runtime can execute it with bc runtime-core + a SQL
- * handler alone (proven by the bundle round-trip test).
+ * Compile ONE behavior method into the serializable STATIC {@link SqlBundle} (spec §8) — the
+ * published multi-language artifact. SYMBOLIC (no concrete input). A read method compiles to a
+ * {@link ReadGraph}; a single-write method to a `makeSQL` statement. Pure JSON throughout.
  */
 function compileBundle(contract, entry, relations = [], dialectName = 'sqlite') {
-    const dialect = (0, dialect_1.dialectFor)(dialectName);
-    const component = entry
-        ? contract.components.find((c) => c.name === entry)
-        : contract.components[0];
-    if (component === undefined) {
+    const component = entry ? contract.components.find((c) => c.name === entry) : contract.components[0];
+    if (component === undefined)
         throw new Error(`scp runtime: entry component '${entry ?? '<first>'}' not found in contract`);
-    }
-    const operations = {};
-    for (const [id, op] of (0, bridge_1.compileComponentNodes)(component, dialect))
-        operations[id] = op;
-    const surrogate = surrogateComponent(component, operations);
-    // Backend-Compile every relation declaration ONCE into a pure-JSON relation op (spec §8),
-    // dialect-aware (the relation batch SELECTs carry no dialect-divergent text today, but the
-    // decl is compiled through the SAME dialect-parameterized path for uniformity/WS7).
     const relationOps = {};
     for (const decl of relations) {
         if (relationOps[decl.name] !== undefined) {
             throw new Error(`scp runtime: duplicate relation declaration '${decl.name}'`);
         }
-        relationOps[decl.name] = (0, relation_1.compileRelationOp)(decl);
+        relationOps[decl.name] = (0, relation_1.compileRelationOp)({ ...decl, dialect: decl.dialect ?? dialectName });
+    }
+    if (isWriteComponent(component)) {
+        const writeNode = primaryNodeOf(component);
+        const op = (0, tx_1.compileWriteNode)(writeNode);
+        return {
+            dialect: dialectName,
+            name: component.name,
+            statement: { sql: op.sql, params: op.params },
+            optionalHeads: [],
+            relations: relationOps,
+        };
     }
+    const readGraph = (0, static_bundle_1.compileReadGraph)(contract, dialectName, entry);
     return {
-        irVersion: contract.ir.irVersion,
-        exprVersion: contract.ir.exprVersion,
         dialect: dialectName,
-        component: surrogate,
-        operations,
-        optionalHeads: [...optionalHeadsOf(operations)],
+        name: readGraph.name,
+        readGraph,
+        optionalHeads: readGraph.optionalHeads,
         relations: relationOps,
     };
 }
 /**
- * Execute a {@link SqlBundle} (the §8 published artifact) end-to-end: feed bc `runBehavior`
- * the bundle's surrogate component (plan / map / wire / output orchestration) with SQL
- * handlers that render the bundle's `CompiledOperation`s and run REAL SQLite. This is the
- * SAME code path a thin per-language runtime follows — it consumes ONLY the serialized
- * bundle + bc runtime-core, never re-running litedbmodel's Backend-Compile. The bundle
- * round-trip test parses this from JSON (no TS state) to prove self-sufficiency (WS7).
+ * Execute a {@link SqlBundle} (the §8 published artifact) end-to-end via the static makeSQL
+ * runtime + REAL SQLite. Read bundles run the read graph via bc `runBehavior`; single-statement
+ * write bundles run the write (RETURNING rows / summary). The SAME code path a thin per-language
+ * runtime follows — it consumes ONLY the serialized bundle + bc, never re-running the compile.
  *
  * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary.
  */
 function executeBundle(bundle, input, options) {
-    const surrogate = bundle.component;
-    const ir = {
-        irVersion: bundle.irVersion,
-        exprVersion: bundle.exprVersion,
-        components: [surrogate],
-    };
-    const handlers = buildHandlers(options.db, bundle.operations, (0, dialect_1.dialectFor)(bundle.dialect));
-    const optionalHeads = new Set(bundle.optionalHeads);
-    const normalized = normalizeInput(surrogate, optionalHeads, input);
-    try {
-        return (0, behavior_contracts_1.runBehavior)(ir, handlers, normalized, surrogate.name);
+    if (bundle.statement !== undefined && bundle.transaction === undefined) {
+        const view = {
+            dialect: bundle.dialect,
+            name: bundle.name,
+            statements: [bundle.statement],
+            optionalHeads: bundle.optionalHeads,
+        };
+        return (0, static_bundle_1.executeStaticWrite)(view, input, options.db);
     }
-    catch (e) {
-        // A `fail`-policy node's `{error}` re-throws through runPlan as `OP_FAILED` carrying the
-        // mapped-failure message. Re-surface the structured SqlFailure from the message-embedded
-        // code if present; otherwise re-throw verbatim.
-        throw reErrorToSqlFailure(e);
+    if (bundle.readGraph === undefined) {
+        throw new Error(`scp runtime: bundle '${bundle.name}' carries neither a read graph nor a write statement`);
     }
+    return (0, static_bundle_1.executeReadGraph)(bundle.readGraph, input, options.db);
+}
+/**
+ * Execute a READ {@link SqlBundle} end-to-end via the ASYNC PG / MySQL execution model (#40): bc
+ * `runBehaviorAsync` drives map iteration / wire binding / Φ output and dispatches independent
+ * sibling read nodes in bounded parallel against the pooled async executor. This is the PRODUCTION
+ * live-DB read entry point — the async twin of {@link executeBundle} for read bundles.
+ *
+ * Byte-identical composition (SAME IR, SAME per-node SQL text + params, SAME Φ output) to the
+ * serial `executeBundle`; concurrency changes only the wall-clock. A single-relation (zero-sibling)
+ * read graph runs exactly one query, so it is identical to the serial path either way.
+ *
+ * A single-statement WRITE bundle is NOT accepted here — the write-tx path stays sync + serial
+ * (`executeBundle` / `executeTransactionBundle`); this async path is READ-only.
+ *
+ * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary.
+ */
+async function executeBundleAsync(bundle, input, options) {
+    if (bundle.readGraph === undefined) {
+        throw new Error(`scp runtime: executeBundleAsync requires a READ bundle ('${bundle.name}' carries no read graph); ` +
+            `the write-tx path stays synchronous + serial (use executeBundle / executeTransactionBundle).`);
+    }
+    return (0, static_bundle_1.executeReadGraphAsync)(bundle.readGraph, input, options.exec);
+}
+/**
+ * Compile + execute a READ behavior method via the ASYNC PG / MySQL execution model (#40). The
+ * async twin of {@link executeBehavior} for reads: compile the contract to a {@link SqlBundle}
+ * (SYMBOLIC), then run its read graph through {@link executeBundleAsync}.
+ *
+ * @throws {SqlFailure} a mapped driver failure re-surfaced at the boundary.
+ */
+async function executeBehaviorAsync(contract, input, options) {
+    return executeBundleAsync(compileBundle(contract, options.entry, options.relations, options.dialect), input, options);
 }
 // ── Write-time relations: Command bundle + 1-tx execution (WS5, #25 — spec §6) ──
 /**
  * Find the single base-write catalog node (`Insert`/`Update`/`Delete`) of a Command component.
- * WS5 initial scope is a single-statement Command (spec §6/§13): exactly one write node whose
- * `onWrite` lifecycle the transaction plan wraps. More than one write node ⇒ the multi-write DAG
- * derivation deferred to WS8 (rejected loudly, never half-built).
+ * WS5 initial scope is a single-statement Command (spec §6/§13). More than one write node ⇒ the
+ * multi-write DAG derivation (WS8, rejected loudly here).
  */
 function baseWriteNodeOf(component) {
     const writes = component.body.filter((n) => !('cond' in n) && !('map' in n) && (n.component === 'Insert' || n.component === 'Update' || n.component === 'Delete'));
@@ -425,98 +187,139 @@ function baseWriteNodeOf(component) {
     return writes[0];
 }
 /**
- * Backend-Compile a Command method + its `entityWrites` save contract into a {@link SqlBundle}
- * that carries the derived, gate-first write-time-relations {@link TransactionPlan} (spec §6/§8).
- * The base write op is Backend-Compiled ONCE (the same {@link compileNode} bridge), and
- * {@link deriveTransactionPlan} lowers the lifecycle's §6 effect arrays around it into the ordered
- * statement list. The whole plan is pure JSON (it round-trips inside the bundle), so a WS7 runtime
- * honors the SAME plan via {@link executeTransactionBundle} — no re-derivation.
- *
- * @throws if the method is not a Command, the phase lifecycle is not declared, the scope is not a
- *   single base write, or a `$.entity.*` reference lacks a RETURNING body (all fail-closed).
+ * Compile a Command method + its `entityWrites` save contract into a {@link SqlBundle} carrying
+ * the derived, gate-first write-time-relations {@link TransactionPlan} (spec §6/§8). The base
+ * write op is compiled ONCE (the SAME `compileWriteNode` — complete tuned SQL + deferred
+ * Expression-IR params); {@link deriveTransactionPlan} lowers the lifecycle's §6 effect arrays
+ * around it into the ordered statement list. Pure JSON; a WS7 runtime honors the SAME plan.
  */
 function compileWriteBundle(contract, entry, writes, phase, dialectName = 'sqlite') {
-    const dialect = (0, dialect_1.dialectFor)(dialectName);
     const component = contract.components.find((c) => c.name === entry);
-    if (component === undefined) {
+    if (component === undefined)
         throw new Error(`scp write: entry component '${entry}' not found in contract`);
-    }
     const lifecycle = (0, writes_1.lifecycleFor)(writes, phase);
     if (lifecycle === undefined) {
         throw new Error(`scp write: the '${phase}' lifecycle is not declared in the entityWrites save contract`);
     }
     const writeNode = baseWriteNodeOf(component);
-    const baseOp = (0, bridge_2.compileNode)(writeNode, dialect);
-    const base = { op: baseOp, label: `${baseOp.component} ${writeNode.component}` };
-    const plan = (0, write_plan_1.deriveTransactionPlan)(phase, [base], lifecycle, dialect);
-    // The bundle still carries the surrogate component/operations for structural parity with a read
-    // bundle (WS7 uniformity), but the write path executes via the transaction plan, not runBehavior.
-    const operations = {};
-    for (const [id, op] of (0, bridge_1.compileComponentNodes)(component, dialect))
-        operations[id] = op;
-    const surrogate = surrogateComponent(component, operations);
+    // MySQL has no native RETURNING; when the base write is an INSERT…RETURNING carrying a PK
+    // descriptor, annotate it with the strip-before-execute PK hint so the mysql emulation re-selects
+    // by the REAL PK (not a hardcoded `id`). PG/SQLite keep the op verbatim (native RETURNING).
+    const baseOp = dialectName === 'mysql' ? (0, tx_1.mysqlPkHint)((0, tx_1.compileWriteNode)(writeNode)) : (0, tx_1.compileWriteNode)(writeNode);
+    const base = { op: baseOp, label: `${writeNode.component}` };
+    const plan = (0, tx_1.deriveTransactionPlan)(phase, [base], lifecycle, dialectName);
     return {
-        irVersion: contract.ir.irVersion,
-        exprVersion: contract.ir.exprVersion,
         dialect: dialectName,
-        component: surrogate,
-        operations,
-        optionalHeads: [...optionalHeadsOf(operations)],
+        name: component.name,
+        statement: { sql: baseOp.sql, params: baseOp.params },
+        optionalHeads: [],
         relations: {},
         transaction: plan,
     };
 }
 /**
- * Backend-Compile a COMPOSITE (multi-write) Command into a {@link SqlBundle} carrying ONE derived,
- * gate-first, TOPOLOGICALLY-ORDERED transaction plan (spec §6 nested write / §14 "write-time tx DAG
- * 導出"). Each {@link CompositeWriteEntry} contributes a named base write + its effects; a later
- * member depends on an earlier via `$.ref.<name>.*` (e.g. a child INSERT keyed by the parent's
- * RETURNING id). {@link deriveTransactionPlan} builds the data-dependency graph + gate-first
- * constraint and derives the correct ordered plan (deterministic, stable tie-break; a cycle or
- * dangling ref is ESCALATED). The plan is pure JSON — the 5 language runtimes execute it verbatim
- * (they already bind each statement's `binds` row into scope for downstream `$.ref` resolution).
- *
- * @throws if an entry is missing/not a single-write node, or the DAG cannot be derived (cycle /
- *   dangling `$.ref` / missing RETURNING on a referenced write) — all fail-closed.
+ * Compile a COMPOSITE (multi-write) Command into a {@link SqlBundle} carrying ONE derived,
+ * gate-first, TOPOLOGICALLY-ORDERED transaction plan (spec §6 nested write / §14). Each entry
+ * contributes a named base write + its effects; a later member depends on an earlier via
+ * `$.ref.<name>.*`. {@link deriveTransactionPlan} builds the DAG + gate-first constraint and
+ * derives the ordered plan; a cycle / dangling ref is ESCALATED. Pure JSON.
  */
 function compileCompositeWriteBundle(contract, entries, phase, dialectName = 'sqlite') {
     if (entries.length < 2) {
         throw new Error('scp write: a composite write bundle needs at least 2 named write members (use compileWriteBundle for a single write).');
     }
-    const dialect = (0, dialect_1.dialectFor)(dialectName);
     const bases = [];
-    const operations = {};
-    let firstComponent;
+    let firstBaseOp;
+    let firstName = '';
     for (const e of entries) {
         const component = contract.components.find((c) => c.name === e.entry);
         if (component === undefined)
             throw new Error(`scp write: entry component '${e.entry}' not found in contract`);
-        if (firstComponent === undefined)
-            firstComponent = component;
+        if (firstBaseOp === undefined)
+            firstName = component.name;
         const writeNode = baseWriteNodeOf(component);
-        const baseOp = (0, bridge_2.compileNode)(writeNode, dialect);
+        const baseOp = (0, tx_1.compileWriteNode)(writeNode);
+        if (firstBaseOp === undefined)
+            firstBaseOp = baseOp;
         bases.push({ op: baseOp, label: `${writeNode.component} ${e.name}`, name: e.name, effects: e.lifecycle.effects });
-        for (const [id, op] of (0, bridge_1.compileComponentNodes)(component, dialect))
-            operations[`${e.name}.${id}`] = op;
     }
-    // The lifecycle arg is unused in composite scope (each base carries its own effects); pass empty.
-    const plan = (0, write_plan_1.deriveTransactionPlan)(phase, bases, { effects: {} }, dialect);
-    const surrogate = surrogateComponent(firstComponent, operations);
+    const plan = (0, tx_1.deriveTransactionPlan)(phase, bases, { effects: {} }, dialectName);
     return {
-        irVersion: contract.ir.irVersion,
-        exprVersion: contract.ir.exprVersion,
         dialect: dialectName,
-        component: surrogate,
-        operations,
-        optionalHeads: [...optionalHeadsOf(operations)],
+        name: firstName,
+        statement: { sql: firstBaseOp.sql, params: firstBaseOp.params },
+        optionalHeads: [],
         relations: {},
         transaction: plan,
     };
 }
+// ── Batch writes: createMany / updateMany / deleteMany (a v1→v2 regression fix) ──
+//
+// A batch write is ONE LOGICAL operation that produces N grouped SQL statements (createMany with a
+// heterogeneous column-set groups records into one INSERT per group, mirroring `DBModel._insert`;
+// updateMany is one UNNEST/JSON/CASE statement; deleteMany is a PK-set IN-list DELETE). This is
+// DISTINCT from the deferred composite multi-write DAG (`baseWriteNodeOf` still rejects >1 authored
+// base write). The batch compilers (`compileInsertMany`/`compileUpdateMany`/`compileDeleteMany`) copy
+// the v1 builders byte-for-byte; here they are lowered into a gate-free {@link TransactionPlan} of
+// body statements ({@link deriveBatchPlan}), so ALL FIVE runtimes execute the multi-statement batch
+// through the SAME per-statement tx loop with no runtime change (concrete params are literalized to
+// bc IR so they survive the render pass — see `deriveBatchPlan`/`literalize`).
+/** Flatten a batch compiler's `MakeSQL` component to a concrete `{ sql, params }` op. */
+function flattenBatchOp(node, label) {
+    const assembled = (0, makesql_1.assembleMakeSQL)(node);
+    return { sql: assembled.sql, params: assembled.params, label };
+}
+/**
+ * Compile a `createMany` into a batch write {@link SqlBundle} carrying a gate-free
+ * {@link TransactionPlan}. Heterogeneous column-set groups become MULTIPLE ordered INSERT
+ * statements — byte-identical to what `DBModel._insert` emits per group (via `compileInsertMany`).
+ *
+ * `pk` (the target PK descriptor) is REQUIRED when the createMany carries a RETURNING clause on the
+ * MySQL dialect: a batch INSERT persists N rows, so the MySQL RETURNING emulation must re-select ALL
+ * N (a range on the AUTO_INCREMENT column, or the client-supplied PK values), not a single `id`.
+ */
+function compileCreateManyBundle(name, options, dialectName = 'sqlite') {
+    const components = (0, compile_crud_1.compileInsertMany)(dialectName, options);
+    const ops = components.map((c, i) => {
+        const flat = flattenBatchOp(c, `createMany group ${i}`);
+        // On MySQL, annotate a RETURNING batch INSERT with the PK hint so the driver emulation
+        // re-selects every inserted row of the group by the real PK.
+        if (dialectName === 'mysql' && options.pk !== undefined && options.returning !== undefined) {
+            return { ...flat, ...(0, tx_1.mysqlPkHint)({ sql: flat.sql, params: flat.params, pk: options.pk }) };
+        }
+        return flat;
+    });
+    const plan = (0, tx_1.deriveBatchPlan)('create', ops);
+    return { dialect: dialectName, name, statement: { sql: ops[0]?.sql ?? '', params: (ops[0]?.params ?? []) }, optionalHeads: [], relations: {}, transaction: plan };
+}
+/**
+ * Compile an `updateMany` into a batch write {@link SqlBundle} (one UNNEST/JSON/CASE statement,
+ * byte-identical to `compileUpdateMany` driving the v1 `buildUpdateMany` / JSON-batch builder).
+ */
+function compileUpdateManyBundle(name, options, dialectName = 'sqlite') {
+    const op = flattenBatchOp((0, compile_crud_1.compileUpdateMany)(dialectName, options), 'updateMany');
+    const plan = (0, tx_1.deriveBatchPlan)('update', [op]);
+    return { dialect: dialectName, name, statement: { sql: op.sql, params: op.params }, optionalHeads: [], relations: {}, transaction: plan };
+}
+/**
+ * Compile a `deleteMany` into a batch write {@link SqlBundle} — a PK-set IN-list DELETE (single-key)
+ * or one DELETE per composite-key group, driven by the v1 `DBConditions` builder (`compileDeleteMany`).
+ */
+function compileDeleteManyBundle(name, options, dialectName = 'sqlite') {
+    const components = (0, compile_crud_1.compileDeleteMany)({ dialect: dialectName, ...options });
+    const ops = components.map((c, i) => flattenBatchOp(c, `deleteMany group ${i}`));
+    if (ops.length === 0) {
+        // Empty key set: nothing to delete. Emit a no-op plan (zero statements is rejected by
+        // deriveBatchPlan, so surface a single always-false DELETE keyed by the v1 empty IN-list is
+        // NOT needed — an empty deleteMany simply has no statements). Represent as an empty transaction.
+        return { dialect: dialectName, name, statement: { sql: '', params: [] }, optionalHeads: [], relations: {}, transaction: { phase: 'remove', entityFrom: null, statements: [], onIdempotentHit: 'rollback' } };
+    }
+    const plan = (0, tx_1.deriveBatchPlan)('remove', ops);
+    return { dialect: dialectName, name, statement: { sql: ops[0].sql, params: ops[0].params }, optionalHeads: [], relations: {}, transaction: plan };
+}
 /**
  * Execute a COMPOSITE (multi-write) Command end-to-end as ONE real SQLite transaction with gate-
- * first short-circuit + DAG-ordered statements (spec §6 / §14): Backend-Compile the members into a
- * bundle with the derived tx-DAG plan, then run {@link executeTransactionBundle}.
+ * first short-circuit + DAG-ordered statements (spec §6 / §14).
  */
 function executeCompositeCommand(contract, entries, phase, input, options) {
     const bundle = compileCompositeWriteBundle(contract, entries, phase, options.dialect);
@@ -524,9 +327,8 @@ function executeCompositeCommand(contract, entries, phase, input, options) {
 }
 /**
  * Execute a Command end-to-end as ONE real SQLite transaction with gate-first short-circuit
- * (spec §6): Backend-Compile the Command + its save contract into a {@link SqlBundle} with a
- * transaction plan, then run {@link executeTransactionBundle}. This is the v2 public write path
- * ("write-time relations が自動導出 → 1 tx", spec §2.3).
+ * (spec §6): compile the Command + its save contract into a {@link SqlBundle} with a transaction
+ * plan, then run {@link executeTransactionBundle}. The v2 public write path.
  *
  * @throws {SqlFailure} a mapped driver failure (the transaction ROLLBACKs first).
  */
@@ -536,40 +338,28 @@ function executeCommand(contract, writes, phase, input, options) {
 }
 /**
  * Execute a {@link SqlBundle}'s derived transaction plan (spec §6/§8) as ONE real SQLite
- * transaction. This is the SAME code path a thin per-language runtime follows: it consumes ONLY
- * the serialized {@link TransactionPlan} (pure JSON) + the render pipeline + a SQL driver, never
- * re-deriving the plan. The bundle round-trip test parses this from JSON (no TS state) to prove
- * WS7 self-sufficiency.
+ * transaction. The SAME code path a thin per-language runtime follows: it consumes ONLY the
+ * serialized {@link TransactionPlan} (pure JSON) + a SQL driver, never re-deriving the plan.
  *
- * @throws if the bundle carries no transaction plan (it is not a write-time-relations Command
- *   bundle), or {@link SqlFailure} on a mapped driver failure.
+ * @throws if the bundle carries no transaction plan, or {@link SqlFailure} on a driver failure.
  */
 function executeTransactionBundle(bundle, input, options) {
     if (bundle.transaction === undefined) {
         throw new Error('scp write: this bundle carries no transaction plan (not a write-time-relations Command bundle)');
     }
-    return (0, write_runtime_1.executeTransaction)(options.db, bundle.transaction, input, (0, dialect_1.dialectFor)(bundle.dialect));
+    return (0, tx_1.executeTransaction)(options.db, bundle.transaction, input, bundle.dialect);
 }
 /**
- * The v2 typed-object read surface (spec §4/§5/§12): run a read behavior whose output is a
- * row list (a Select), then wrap each raw row in a plain TYPED-OBJECT (own props = data only,
- * NOT a DBModel instance) with read relations attached.
- *
- * - A relation named in `options.with` is DECLARATIVELY selected: batch-prefetched ONCE over
- *   the whole page (staged, no N+1) and attached as an OWN prop.
- * - Every OTHER declared relation is LAZY: a prototype getter that, on `await result.author`,
- *   fires the SAME compiled relation op over the sibling set (batched — still no N+1).
- * - `options.hydrate` recovers host objects (`(raw) => new Domain(raw)`) — the consumer-side
- *   method-UX recovery. It stays in the runtime and never enters the bundle.
+ * The v2 typed-object read surface (spec §4/§5/§12): run a read behavior whose output is a row
+ * list (a Select), then wrap each raw row in a plain TYPED-OBJECT with read relations attached.
+ * A relation named in `options.with` is declaratively batch-prefetched; every other declared
+ * relation is lazy (a prototype getter firing the SAME compiled op over the sibling set). Both
+ * surfaces share the ONE compiled relation op in the bundle.
  *
- * Both surfaces share the ONE compiled relation op in the bundle (spec §5). The base row list
- * is produced by the SAME {@link executeBundle} path (bc runtime-core + SQL handlers), so the
- * read query itself is fully IR-driven; relations are the runtime's staged-batch concern.
- *
- * @throws if the behavior output is not a row list (the typed-object surface is for reads).
+ * @throws if the behavior output is not a row list (the typed-object read surface is for reads).
  */
 function read(contract, input, options) {
-    return readBundle(compileBundle(contract, options.entry, options.relations), input, options);
+    return readBundle(compileBundle(contract, options.entry, options.relations, options.dialect), input, options);
 }
 /** {@link read} against an already-compiled {@link SqlBundle} (the published §8 artifact). */
 function readBundle(bundle, input, options) {
@@ -582,84 +372,10 @@ function readBundle(bundle, input, options) {
     const readOpts = {
         ...(options.with !== undefined ? { with: options.with } : {}),
         ...(options.hydrate !== undefined ? { hydrate: options.hydrate } : {}),
+        // CROSS-DB relations (V0 R1): forward the connection registry so a tagged relation routes to
+        // its target DB. Absent for a single-DB read (every relation runs on the primary `db`).
+        ...(options.connections !== undefined ? { connections: options.connections } : {}),
     };
     return (0, typed_object_1.buildResultSet)(rawRows, bundle.relations, options.db, readOpts);
 }
-// ── Staged-batch relation resolution THROUGH bc's plan (spec §5) ──────────────
-/** The synthetic catalog name of a batched-relation map node (runtime-internal, not authored). */
-const RELATION_BATCH_COMPONENT = '__RelationBatch';
-/** The port a batched-relation map element evaluates to: the parent's batch-key value. */
-const RELATION_KEY_PORT = '__key';
-/**
- * Resolve ONE relation for a page of parent rows by driving bc's PLAN mechanism (spec §5:
- * `deriveExecutionPlan` — result path → stage groups + concurrency). This is the staged-batch
- * path: it builds a bc component with a single `map.batched` node over the parent rows and
- * runs it through {@link runBehavior} (the SAME multi-language execution core WS7 languages
- * use). Because the map is `batched`, bc evaluates every parent's key port and invokes the
- * relation handler EXACTLY ONCE with `{items:[…]}` — so the relation op fires ONE batched
- * query for the whole page (structurally no N+1, enforced by bc's batch contract). The
- * handler runs the IDENTICAL compiled {@link RelationOp} the declarative-select and lazy
- * surfaces use, and `into` attaches each parent's resolved child(ren).
- *
- * Returns the parent rows augmented with the relation under `op.name` (per cardinality).
- */
-function resolveRelationViaPlan(op, parents, db) {
-    // One batched map node over the parent list. Each element evaluates its batch-key port
-    // (`{ref:[<elemAs>, parentKey]}`); the batched handler receives all keys at once.
-    const elemAs = '$p';
-    const node = {
-        id: 'rel',
-        map: {
-            over: { ref: ['__parents'] },
-            as: elemAs,
-            component: RELATION_BATCH_COMPONENT,
-            ports: { [RELATION_KEY_PORT]: { ref: [elemAs, op.parentKey] } },
-            into: op.name,
-            batched: true,
-        },
-    };
-    const component = {
-        name: '__resolveRelation',
-        inputPorts: { __parents: { required: true } },
-        body: [node],
-        output: { ref: ['rel'] },
-    };
-    const ir = {
-        irVersion: 1,
-        exprVersion: 1,
-        components: [component],
-    };
-    // The batched-relation handler: bc calls it ONCE with every parent's evaluated key port.
-    // It runs the relation op's batch query a SINGLE time and returns per-parent results aligned
-    // to `items` (bc's MAP_BATCH_RESULT_MISMATCH enforces the 1:1 alignment).
-    const handlers = {
-        [RELATION_BATCH_COMPONENT]: (portsOrItems) => {
-            const items = portsOrItems.items;
-            if (!Array.isArray(items)) {
-                return { error: `${RELATION_BATCH_COMPONENT}: expected a batched {items:[…]} invocation` };
-            }
-            // Reconstruct the parent-key-bearing rows from the evaluated key ports, run the op ONCE.
-            const keyRows = items.map((it) => ({ [op.parentKey]: it[RELATION_KEY_PORT] }));
-            const { batch } = (0, relation_1.runRelationOp)(op, keyRows, db);
-            const aligned = keyRows.map((r) => (0, relation_1.distributeToParent)(op, r, batch));
-            return { ok: aligned };
-        },
-    };
-    const out = (0, behavior_contracts_1.runBehavior)(ir, handlers, { __parents: parents }, '__resolveRelation');
-    return out;
-}
-/**
- * If a `runPlan` `OP_FAILED` carries a mapped-failure message, re-surface the structured
- * {@link SqlFailure} (the message embeds the original SQLite code). Non-driver errors are
- * re-thrown verbatim.
- */
-function reErrorToSqlFailure(e) {
-    const message = e instanceof Error ? e.message : String(e);
-    const m = /(SQLITE_[A-Z_]+)/.exec(message);
-    if (m) {
-        // Reconstruct a minimal driver-error shape and re-map to preserve kind/policy/code.
-        return (0, errors_1.mapSqliteError)({ code: m[1], message });
-    }
-    return e;
-}
 //# sourceMappingURL=runtime.js.map