litedbmodel 1.2.9 → 2.0.0

package/dist/scp/runtime.js

@@ -0,0 +1,665 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — the thin TS runtime (WS3, #23; 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.
+ *
+ * ## 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).
+ *
+ * ## 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.
+ */
+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.compileWriteBundle = compileWriteBundle;
+exports.compileCompositeWriteBundle = compileCompositeWriteBundle;
+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 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) } } };
+    }
+    const op = compiled[node.id];
+    if (op === undefined)
+        return node;
+    return { ...node, ports: { [SCOPE_PORT]: scopePort(op) } };
+}
+/** 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)) };
+}
+// ── 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).
+ *
+ * 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`).
+ */
+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).
+ */
+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) {
+        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);
+    }
+    return {
+        irVersion: contract.ir.irVersion,
+        exprVersion: contract.ir.exprVersion,
+        dialect: dialectName,
+        component: surrogate,
+        operations,
+        optionalHeads: [...optionalHeadsOf(operations)],
+        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).
+ *
+ * @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);
+    }
+    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);
+    }
+}
+// ── 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).
+ */
+function baseWriteNodeOf(component) {
+    const writes = component.body.filter((n) => !('cond' in n) && !('map' in n) && (n.component === 'Insert' || n.component === 'Update' || n.component === 'Delete'));
+    if (writes.length === 0) {
+        throw new Error(`scp write: Command '${component.name}' has no base write (Insert/Update/Delete) node`);
+    }
+    if (writes.length > 1) {
+        throw new Error(`scp write: Command '${component.name}' has ${writes.length} base write nodes; WS5 initial ` +
+            `scope is a SINGLE-statement Command + write-time relations (multi-write DAG is WS8, spec §6/§13).`);
+    }
+    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).
+ */
+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) {
+        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);
+    return {
+        irVersion: contract.ir.irVersion,
+        exprVersion: contract.ir.exprVersion,
+        dialect: dialectName,
+        component: surrogate,
+        operations,
+        optionalHeads: [...optionalHeadsOf(operations)],
+        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.
+ */
+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;
+    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;
+        const writeNode = baseWriteNodeOf(component);
+        const baseOp = (0, bridge_2.compileNode)(writeNode, dialect);
+        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);
+    return {
+        irVersion: contract.ir.irVersion,
+        exprVersion: contract.ir.exprVersion,
+        dialect: dialectName,
+        component: surrogate,
+        operations,
+        optionalHeads: [...optionalHeadsOf(operations)],
+        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}.
+ */
+function executeCompositeCommand(contract, entries, phase, input, options) {
+    const bundle = compileCompositeWriteBundle(contract, entries, phase, options.dialect);
+    return executeTransactionBundle(bundle, 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).
+ *
+ * @throws {SqlFailure} a mapped driver failure (the transaction ROLLBACKs first).
+ */
+function executeCommand(contract, writes, phase, input, options) {
+    const bundle = compileWriteBundle(contract, options.entry, writes, phase, options.dialect);
+    return executeTransactionBundle(bundle, 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.
+ *
+ * @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.
+ */
+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));
+}
+/**
+ * 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.
+ *
+ * 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).
+ */
+function read(contract, input, options) {
+    return readBundle(compileBundle(contract, options.entry, options.relations), input, options);
+}
+/** {@link read} against an already-compiled {@link SqlBundle} (the published §8 artifact). */
+function readBundle(bundle, input, options) {
+    const out = executeBundle(bundle, input, options);
+    if (!Array.isArray(out)) {
+        throw new Error(`scp read: the read behavior output is not a row list (got ${out === null ? 'null' : typeof out}); ` +
+            `the typed-object read surface expects a Select-shaped output`);
+    }
+    const rawRows = out;
+    const readOpts = {
+        ...(options.with !== undefined ? { with: options.with } : {}),
+        ...(options.hydrate !== undefined ? { hydrate: options.hydrate } : {}),
+    };
+    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