litedbmodel 2.0.0 → 2.0.2

package/dist/scp/makesql/tx.js

@@ -0,0 +1,788 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — write-time relations → ordered SQL transaction plan, re-expressed on
+ * the `makeSQL` model (epic #43/#45 Phase B; spec §6 / §14). This REPLACES the reduced-spine
+ * `../write-plan.ts` + `../write-runtime.ts` (`CompiledOperation` + `renderOperation` +
+ * FragmentTree). No reduced IR is emitted anywhere: every statement's SQL is COMPLETE tuned
+ * text (byte-identical to what the v1 write path sends — `SELECT 1 …`, `INSERT … ON CONFLICT
+ * DO NOTHING`, `UPDATE … SET c = c + ?`, the outbox INSERT), and its `params` are closed-set
+ * bc Expression IR refs resolved at execute time against the accumulated transaction scope.
+ *
+ * A statement op is exactly a `makeSQL` template: `{ sql, params }` where `sql` carries `?`
+ * placeholders and `params` are Expression IR (`{ref:[…]}` / a literal / a `{obj:{…}}` payload)
+ * that bc evaluates per statement — then the concrete values assemble + render + bind through
+ * the SAME `assembleMakeSQL` / `renderPlaceholders` the read path uses.
+ *
+ * ## Gate-first is a real execution behavior (spec §6 "Gate First")
+ *
+ * Each gate statement carries a {@link GateRule} the runtime evaluates AFTER executing it: a
+ * failing gate short-circuits — the remaining statements never execute and the tx ROLLBACKs.
+ *
+ * ## Path lowering (spec §6) — `$.input.*` / `$.entity.*` / `$.ref.<w>.*` → closed-set refs
+ *
+ *   `$.input.<f>`       → `{ref:['<f>']}`             (bc flat input scope)
+ *   `$.entity.<f>`      → `{ref:['__entity','<f>']}`  (the sole body write's RETURNING row)
+ *   `$.ref.<w>.<f>`     → `{ref:['<w>','<f>']}`        (a named upstream write's RETURNING row)
+ *
+ * ## tx-DAG derivation (spec §6 / §14) — gate-first + data-dependency topo order
+ *
+ * Statements form a data-dependency DAG (`$.ref.<w>.*` consumes an earlier write's RETURNING
+ * row via `TxStatement.binds`) with a gate-first constraint. A deterministic Kahn topo sort
+ * (stable ascending declaration `seq` tie-break) orders them into a single-transaction plan.
+ * Underivable shapes (cycle, dangling `$.ref`, referenced write without RETURNING, duplicate
+ * bind, composite `$.entity`) are LOUD rejects — never a silently mis-ordered plan.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IN_SENTINEL = void 0;
+exports.literalize = literalize;
+exports.mysqlPkHint = mysqlPkHint;
+exports.stripMysqlPkHint = stripMysqlPkHint;
+exports.compileWriteNode = compileWriteNode;
+exports.deriveTransactionPlan = deriveTransactionPlan;
+exports.deriveBatchPlan = deriveBatchPlan;
+exports.executeTransaction = executeTransaction;
+exports.countingDriver = countingDriver;
+exports.renderTxStatement = renderTxStatement;
+const behavior_contracts_1 = require("behavior-contracts");
+const makesql_1 = require("./makesql");
+const handler_1 = require("./handler");
+const compile_1 = require("./compile");
+const errors_1 = require("../errors");
+const DBConditions_1 = require("../../DBConditions");
+const writes_1 = require("../writes");
+/**
+ * Encode a CONCRETE value into a bc Expression IR node that `evaluateExpression` returns VERBATIM.
+ *
+ * A batch-write op (createMany / updateMany / deleteMany) is compiled by driving the v1 builders
+ * (compile-crud), so its `params` are already CONCRETE grouped values — NOT deferred Expression IR.
+ * But the tx runtime renders every statement param through bc `evaluateExpression` (spec §6 /
+ * `renderStatement`), which fail-closes on a BARE array ("bare array is not an expression") and on a
+ * multi-key plain object. The batch INSERT on Postgres binds REAL arrays as single params
+ * (`UNNEST($1::int[], …)` → `[[7,8], …]`), so those concrete params must be wrapped in the bc
+ * literal-carrier ops so they survive evaluation unchanged:
+ *   - array   → `{arr:[literalize(e)…]}`   (bc evaluates each element, so wrap recursively)
+ *   - object  → `{obj:{k:literalize(v)…}}`  (a plain map, e.g. a JSON payload object)
+ *   - scalar  → the value itself (null/bool/string/number pass through evaluateExpression verbatim;
+ *               an integral number becomes a bigint, normalized back at the driver boundary).
+ * This reuses ONLY vocabulary every language runtime's bc already implements (`{arr}`/`{obj}` — the
+ * emit outbox payload already rides `{obj}` on live PG+MySQL), so a batch write executes through the
+ * SAME per-statement tx loop in all five runtimes with NO runtime change.
+ */
+function literalize(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (Array.isArray(value))
+        return { arr: value.map((e) => literalize(e)) };
+    if (typeof value === 'object') {
+        const obj = {};
+        for (const [k, v] of Object.entries(value))
+            obj[k] = literalize(v);
+        return { obj };
+    }
+    return value;
+}
+// ── Path → Expression IR ref (closed-set only) ────────────────────────────────
+function pathToRef(value) {
+    const p = (0, writes_1.parseEffectPath)(value);
+    if (p.root === 'input')
+        return { ref: [p.field] };
+    if (p.root === 'entity')
+        return { ref: [writes_1.ENTITY_ROOT, p.field] };
+    return { ref: [p.writeName, p.field] };
+}
+// ── Per-dialect guard INSERT text (the ON CONFLICT DO NOTHING / INSERT IGNORE SSoT) ──
+/**
+ * The tuned guard INSERT text for a gate-first `idempotency`/`unique` statement — byte-identical
+ * to the v1 write path: SQLite/Postgres emit `INSERT INTO … VALUES (…) ON CONFLICT DO NOTHING`;
+ * MySQL emits `INSERT IGNORE INTO … VALUES (…)`.
+ */
+function guardInsert(dialect, table, columns, placeholders) {
+    const cols = `(${columns.join(', ')})`;
+    if (dialect === 'mysql')
+        return `INSERT IGNORE INTO ${table} ${cols} VALUES (${placeholders})`;
+    return `INSERT INTO ${table} ${cols} VALUES (${placeholders}) ON CONFLICT DO NOTHING`;
+}
+function makeIdGen() {
+    let n = 0;
+    return (role) => `tx_${role}_${n++}`;
+}
+/** `requires` → a gate-first existence probe: `SELECT 1 FROM <table> WHERE k1 = ? AND …`. */
+function compileRequires(e, nextId) {
+    const cols = Object.keys(e.keys);
+    if (cols.length === 0)
+        throw new Error(`write-plan: requires on '${e.table}' declares no keys`);
+    const whereSql = v1EqualityWhereText(cols);
+    const op = {
+        sql: `SELECT 1 FROM ${e.table} WHERE ${whereSql}`,
+        params: cols.map((c) => pathToRef(e.keys[c])),
+    };
+    return { id: nextId('requires'), role: 'gate:requires', op, gate: 'existsElseRollback', label: `requires ${e.table}` };
+}
+/** `idempotency` → a gate-first token INSERT ON CONFLICT DO NOTHING (duplicate short-circuits). */
+function compileIdempotency(e, nextId, dialect) {
+    const op = {
+        sql: guardInsert(dialect, e.table, [e.column], '?'),
+        params: [pathToRef(e.token)],
+    };
+    return { id: nextId('idem'), role: 'gate:idempotency', op, gate: 'insertedElseNoop', label: `idempotency ${e.table}` };
+}
+/** `unique` → a gate-first guard-row INSERT ON CONFLICT DO NOTHING (collision → ROLLBACK). */
+function compileUnique(e, nextId, dialect) {
+    const scopeCols = e.scope.map((_, i) => `s${i}`);
+    const fieldCols = e.fields.map((_, i) => `f${i}`);
+    const cols = ['name', ...scopeCols, ...fieldCols];
+    const placeholders = cols.map(() => '?').join(', ');
+    const params = [
+        e.name, // literal discriminator (a closed-set string literal)
+        ...e.scope.map(pathToRef),
+        ...e.fields.map(pathToRef),
+    ];
+    const op = { sql: guardInsert(dialect, e.guardTable, cols, placeholders), params };
+    return { id: nextId('unique'), role: 'gate:unique', op, gate: 'insertedElseRollback', label: `unique ${e.name}` };
+}
+/** `derive` → a cascade counter update: `UPDATE <table> SET <attr> = <attr> + ? WHERE k = ?`. */
+function compileDerive(e, nextId) {
+    const keyCols = Object.keys(e.keys);
+    if (keyCols.length === 0)
+        throw new Error(`write-plan: derive on '${e.table}' declares no keys`);
+    const whereSql = v1EqualityWhereText(keyCols);
+    const op = {
+        sql: `UPDATE ${e.table} SET ${e.attribute} = ${e.attribute} + ? WHERE ${whereSql}`,
+        // SET amount is the first param (before the WHERE keys), matching the v1 param order.
+        params: [e.amount, ...keyCols.map((c) => pathToRef(e.keys[c]))],
+    };
+    return { id: nextId('derive'), role: 'derive', op, label: `derive ${e.table}.${e.attribute}` };
+}
+/** `edges` → M:N intermediate INSERT/DELETE or 1:N FK UPDATE (spec §6 table row `edges`). */
+function compileEdge(e, nextId) {
+    if (e.relation === 'm2m') {
+        const cols = Object.keys(e.columns);
+        if (e.action === 'set') {
+            const placeholders = cols.map(() => '?').join(', ');
+            const op = {
+                sql: `INSERT INTO ${e.table} (${cols.join(', ')}) VALUES (${placeholders})`,
+                params: cols.map((c) => pathToRef(e.columns[c])),
+            };
+            return { id: nextId('edge'), role: 'edge', op, label: `edge m2m link ${e.table}` };
+        }
+        const whereSql = v1EqualityWhereText(cols);
+        const op = {
+            sql: `DELETE FROM ${e.table} WHERE ${whereSql}`,
+            params: cols.map((c) => pathToRef(e.columns[c])),
+        };
+        return { id: nextId('edge'), role: 'edge', op, label: `edge m2m unlink ${e.table}` };
+    }
+    // fk: UPDATE <related> SET <fkCol> = ? (or NULL) WHERE <where keys…>
+    const setCols = Object.keys(e.columns);
+    const whereCols = Object.keys(e.where);
+    const setClauses = setCols.map((c) => (e.action === 'set' ? `${c} = ?` : `${c} = NULL`));
+    const setParams = e.action === 'set' ? setCols.map((c) => pathToRef(e.columns[c])) : [];
+    const whereSql = v1EqualityWhereText(whereCols);
+    const op = {
+        sql: `UPDATE ${e.table} SET ${setClauses.join(', ')} WHERE ${whereSql}`,
+        params: [...setParams, ...whereCols.map((c) => pathToRef(e.where[c]))],
+    };
+    return { id: nextId('edge'), role: 'edge', op, label: `edge fk ${e.action} ${e.table}` };
+}
+/** `emits` → an outbox INSERT (same tx): `INSERT INTO <outbox>(type, payload) VALUES(?, ?)`. */
+function compileEmit(e, nextId) {
+    const payloadObj = {};
+    for (const [k, v] of Object.entries(e.payload))
+        payloadObj[k] = pathToRef(v);
+    const op = {
+        sql: `INSERT INTO ${e.outboxTable} (type, payload) VALUES (?, ?)`,
+        params: [e.name, { obj: payloadObj }],
+    };
+    return { id: nextId('emit'), role: 'emit', op, label: `emit ${e.name}` };
+}
+// ============================================================================
+// Authored write node → makeSQL TxOp (the makeSQL re-expression of the bridge's
+// `compileNode` for the write path — reads ports STRUCTURALLY, emits complete SQL
+// text + DEFERRED Expression-IR params resolved at tx execute time).
+// ============================================================================
+/** The reserved column-ref path head that marks an IN-list membership (mirrors the bridge). */
+exports.IN_SENTINEL = '@in';
+function stringPort(ports, name) {
+    const v = ports[name];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'string')
+        throw new Error(`compileWriteNode: port '${name}' must be a literal string in the IR (got ${JSON.stringify(v)})`);
+    return v;
+}
+/** `<prefix>.<field>` ports → an ordered `Record<field, ExprNode>` (declaration order). */
+function collectFamily(ports, prefix) {
+    const out = {};
+    for (const k of Object.keys(ports)) {
+        if (k.startsWith(`${prefix}.`))
+            out[k.slice(prefix.length + 1)] = ports[k];
+    }
+    return out;
+}
+/**
+ * Collect the `sqlCast.<field>` port family → `Map<column, sqlCastType>` (the PG per-column cast
+ * types, e.g. `jsonb`/`uuid`/`int[]`). This mirrors the `sqlCastMap` v1 `DBModel._insert`/`_update`
+ * read from the column metadata (`getSqlCastMap`) to emit `?::<sqlCast>` on Postgres. A write node
+ * that declares no cast ports yields an empty map (no cast columns — the common case).
+ */
+function collectSqlCast(ports) {
+    const map = new Map();
+    for (const k of Object.keys(ports)) {
+        if (!k.startsWith('sqlCast.'))
+            continue;
+        const v = ports[k];
+        if (typeof v !== 'string') {
+            throw new Error(`compileWriteNode: port '${k}' (a sqlCast type) must be a literal string in the IR (got ${JSON.stringify(v)})`);
+        }
+        map.set(k.slice('sqlCast.'.length), v);
+    }
+    return map;
+}
+/**
+ * The placeholder text for one written column's value, applying the v1 PER-COLUMN cast on Postgres.
+ * Byte-identical to v1 `DBModel._insert` (`src/drivers/PostgresSqlBuilder.ts:289-296`) and `_update`
+ * (`src/DBModel.ts:1058-1063`): a PG cast column emits `?::<sqlCast>` via the SAME dialect cast
+ * formatter (`formatterFor('postgres')`), SKIPPING `timestamp`/`date` (the pg driver serializes Date
+ * objects itself — an explicit cast interferes). MySQL/SQLite emit a bare `?` (v1's dialect-aware
+ * `SqlCastFormatter` is identity there — the .rs `::type` leak is NOT reproduced). The tx-write path
+ * targets a single dialect at compile, so the cast is resolved here, not deferred.
+ */
+function castPlaceholder(dialect, sqlCastMap, column) {
+    const sqlCast = sqlCastMap.get(column);
+    if (dialect !== 'postgres' || sqlCast === undefined || sqlCast === 'timestamp' || sqlCast === 'date')
+        return '?';
+    return (0, compile_1.formatterFor)('postgres')('?', sqlCast);
+}
+function opKey(node) {
+    if (node === null || typeof node !== 'object' || Array.isArray(node))
+        return undefined;
+    const keys = Object.keys(node);
+    return keys.length === 1 ? keys[0] : undefined;
+}
+function columnOf(node, ctx) {
+    const op = opKey(node);
+    if (op !== 'ref' && op !== 'refOpt')
+        throw new Error(`compileWriteNode: ${ctx}: the column operand must be a {ref:[…]} path`);
+    const path = node[op];
+    if (!Array.isArray(path) || path.length === 0 || typeof path[path.length - 1] !== 'string') {
+        throw new Error(`compileWriteNode: ${ctx}: column ref path must be a non-empty string path`);
+    }
+    return path[path.length - 1];
+}
+function binOperands(node, op, at) {
+    const args = node[op];
+    if (!Array.isArray(args) || args.length !== 2)
+        throw new Error(`compileWriteNode: ${at}: '${op}' expects exactly 2 operands`);
+    return [args[0], args[1]];
+}
+/** The comparison-operator SQL symbols, keyed by the bc operator name (drives the v1 custom-op key). */
+const CMP_OPS = { lt: '<', le: '<=', gt: '>', ge: '>=', ne: '<>' };
+/** A probe placeholder value fed to the v1 builder so it emits one `?` per bound slot. */
+const PROBE = '__probe__';
+/**
+ * Produce a bare condition body's TEXT by driving the ORIGINAL v1 `DBConditions.compile()` — the
+ * SAME builder the eager write path and `compile-crud` use, so the WHERE text is byte-identical
+ * to v1 by construction (a v2 hand-roll would make the corpus tautological). The throwaway
+ * `probe` array absorbs the probe values; the real runtime values are the caller's deferred
+ * Expression-IR params. The write path targets a single dialect at render but the WHERE `= ?` /
+ * `<op> ?` / `IS NULL` / `IS NOT NULL` forms are dialect-invariant in `DBConditions`.
+ */
+function v1ConditionText(conditions) {
+    const probe = [];
+    return new DBConditions_1.DBConditions(conditions).compile(probe);
+}
+/**
+ * The tuned WHERE-body TEXT for a set of PK-equality columns (`k1 = ? AND k2 = ?`), produced by
+ * driving the ORIGINAL v1 `DBConditions.compile()` (via {@link v1ConditionText}) — the SAME
+ * builder the read path uses — so the write-tx predicate text is byte-identical to v1 by
+ * construction (a v1 predicate regression now moves a tx golden). The throwaway probe params are
+ * discarded; the real runtime values are the caller's deferred Expression-IR params, bound 1:1
+ * with the `?` placeholders. `DBConditions.compile` iterates the condition object in insertion
+ * order and joins with ` AND `, so the `?`/param order matches the caller's column order.
+ */
+function v1EqualityWhereText(columns) {
+    const conditions = {};
+    for (const c of columns)
+        conditions[c] = PROBE;
+    return v1ConditionText(conditions);
+}
+/** Lower one where-member Expression node → a `<sql, params>` WHERE fragment (deferred params). */
+function lowerWhereMember(node, at) {
+    const op = opKey(node);
+    if (op === undefined)
+        throw new Error(`compileWriteNode: ${at}: a where member must be a single-operator Expression node`);
+    if (op === 'eq') {
+        const [col, val] = binOperands(node, op, at);
+        const column = columnOf(col, at);
+        if (val === null)
+            return { sql: v1ConditionText({ [column]: null }), params: [] };
+        return { sql: v1ConditionText({ [column]: PROBE }), params: [val] };
+    }
+    if (op in CMP_OPS) {
+        const [col, val] = binOperands(node, op, at);
+        const column = columnOf(col, at);
+        if (op === 'ne' && val === null)
+            return { sql: v1ConditionText({ [`${column} IS NOT NULL`]: true }), params: [] };
+        return { sql: v1ConditionText({ [`${column} ${CMP_OPS[op]} ?`]: PROBE }), params: [val] };
+    }
+    throw new Error(`compileWriteNode: ${at}: unsupported where operator '${op}' (write path supports eq/ne/lt/le/gt/ge)`);
+}
+function lowerWherePort(ports, at) {
+    const v = ports.where;
+    if (v === undefined)
+        return { sql: '', params: [] };
+    if (typeof v !== 'object' || v === null || !('arr' in v) || !Array.isArray(v.arr)) {
+        throw new Error(`compileWriteNode: ${at}: 'where' must be an {arr:[…]} literal`);
+    }
+    const members = v.arr;
+    const parts = [];
+    const params = [];
+    members.forEach((m, i) => {
+        const f = lowerWhereMember(m, `${at}.where[${i}]`);
+        parts.push(f.sql);
+        params.push(...f.params);
+    });
+    // Join with the SAME ` AND ` connector `DBConditions.compile` uses (parts.join(' AND ')).
+    return { sql: parts.join(' AND '), params };
+}
+function returningTail(ports) {
+    const r = stringPort(ports, 'returning');
+    return r === undefined ? '' : ` RETURNING ${r}`;
+}
+/**
+ * Read the optional PRIMARY KEY descriptor ports of an Insert node (for the MySQL RETURNING
+ * emulation). `pk` is a comma-separated column list (`'doc_id'` / `'order_id,line_no'`); `autoInc`
+ * names the single AUTO_INCREMENT column, or is absent for a client-supplied PK. Absent `pk`
+ * defaults to null (the emulation then keeps its legacy `WHERE id`/`LAST_INSERT_ID` path, so the
+ * existing auto-increment-`id` corpus is unchanged).
+ */
+function pkPort(ports) {
+    const pk = stringPort(ports, 'pk');
+    if (pk === undefined)
+        return undefined;
+    const columns = pk.split(',').map((c) => c.trim()).filter((c) => c.length > 0);
+    if (columns.length === 0)
+        return undefined;
+    const ai = stringPort(ports, 'autoInc');
+    return { columns, autoInc: ai ?? null };
+}
+/** The strip-before-execute PK-hint comment marker the MySQL RETURNING emulation reads. */
+const MYSQL_PK_HINT_RE = /\s*\/\*scp:pk=[^*]*\*\//;
+/**
+ * Serialize a {@link TxOp.pk} descriptor into a strip-before-execute SQL comment appended to an
+ * INSERT…RETURNING op, so the MySQL driver emulation can re-select by the REAL primary key. The
+ * comment is STRIPPED (with the RETURNING clause) before the INSERT executes, so the executed SQL
+ * stays byte-clean; it is emitted ONLY into the mysql-dialect bundle (PG/SQLite keep native
+ * RETURNING and never see it). Format: ` /*scp:pk=col1,col2;ai=<autoIncCol|>* /`.
+ */
+function mysqlPkHint(op) {
+    if (op.pk === undefined)
+        return op;
+    if (!/\breturning\b/i.test(op.sql))
+        return op;
+    const hint = ` /*scp:pk=${op.pk.columns.join(',')};ai=${op.pk.autoInc ?? ''}*/`;
+    return { ...op, sql: op.sql + hint };
+}
+/** Strip a trailing MySQL PK-hint comment from a rendered SQL (defensive; runtimes strip too). */
+function stripMysqlPkHint(sql) {
+    return sql.replace(MYSQL_PK_HINT_RE, '');
+}
+/**
+ * Compile ONE authored catalog write node (`Insert`/`Update`/`Delete`) into a makeSQL {@link TxOp}
+ * — complete tuned SQL text + DEFERRED Expression-IR params. This is the makeSQL re-expression of
+ * the reduced bridge's `compileNode` for the write path (the tx-DAG base writes). INSERT columns
+ * are CANONICAL (alphabetical) sorted — the v2 write-path SSoT (matches `DBModel._insert`).
+ */
+function compileWriteNode(node, dialect = 'sqlite') {
+    const { component, ports } = node;
+    const table = stringPort(ports, 'table');
+    if (table === undefined)
+        throw new Error(`compileWriteNode: ${component} node requires a literal 'table' port`);
+    // Per-column PG cast types (`sqlCast.<field>` ports) — drive the v1 `?::<sqlCast>` on Postgres.
+    const sqlCastMap = collectSqlCast(ports);
+    switch (component) {
+        case 'Insert': {
+            const values = collectFamily(ports, 'values');
+            const cols = Object.keys(values);
+            if (cols.length === 0)
+                throw new Error(`compileWriteNode: Insert requires at least one 'values.<field>' port`);
+            const sorted = [...cols].sort();
+            // v1 `DBModel._insert` emits `?::<sqlCast>` PER COLUMN on Postgres (skipping timestamp/date);
+            // the placeholder list is thus per-column, NOT a uniform `?` join (the latent H1 divergence).
+            const placeholders = sorted.map((c) => castPlaceholder(dialect, sqlCastMap, c)).join(', ');
+            const sql = `INSERT INTO ${table} (${sorted.join(', ')}) VALUES (${placeholders})${returningTail(ports)}`;
+            const pk = pkPort(ports);
+            return { sql, params: sorted.map((c) => values[c]), ...(pk !== undefined ? { pk } : {}) };
+        }
+        case 'Update': {
+            const set = collectFamily(ports, 'set');
+            const setCols = Object.keys(set);
+            if (setCols.length === 0)
+                throw new Error(`compileWriteNode: Update requires at least one 'set.<field>' port`);
+            const where = lowerWherePort(ports, 'Update');
+            if (where.sql === '')
+                throw new Error(`compileWriteNode: Update requires a 'where' port`);
+            // v1 `DBModel._update` emits `<c> = ?::<sqlCast>` PER COLUMN on Postgres (skipping timestamp/date).
+            const setClauses = setCols.map((c) => `${c} = ${castPlaceholder(dialect, sqlCastMap, c)}`).join(', ');
+            const sql = `UPDATE ${table} SET ${setClauses} WHERE ${where.sql}${returningTail(ports)}`;
+            return { sql, params: [...setCols.map((c) => set[c]), ...where.params] };
+        }
+        case 'Delete': {
+            const where = lowerWherePort(ports, 'Delete');
+            if (where.sql === '')
+                throw new Error(`compileWriteNode: Delete requires a 'where' port`);
+            const sql = `DELETE FROM ${table} WHERE ${where.sql}${returningTail(ports)}`;
+            return { sql, params: where.params };
+        }
+        default:
+            throw new Error(`compileWriteNode: catalog component '${component}' has no write compile (SQL writes: Insert/Update/Delete)`);
+    }
+}
+function compileWriteGroup(base, lifecycle, nextId, dialect, seqRef) {
+    const e = lifecycle.effects;
+    const nodes = [];
+    const mk = (stmt, isGate) => {
+        const consumes = refHeadsOf(stmt).filter((h) => h !== writes_1.ENTITY_ROOT && !isInputHead(h, stmt));
+        return { stmt, seq: seqRef.n++, consumes, produces: stmt.binds ?? null, isGate };
+    };
+    for (const r of e.requires ?? [])
+        nodes.push(mk(compileRequires(r, nextId), true));
+    if (e.idempotency !== undefined)
+        nodes.push(mk(compileIdempotency(e.idempotency, nextId, dialect), true));
+    for (const u of e.unique ?? [])
+        nodes.push(mk(compileUnique(u, nextId, dialect), true));
+    const bodyId = nextId('body');
+    const bodyStmt = {
+        id: bodyId,
+        role: 'body',
+        op: base.op,
+        label: base.label,
+        ...(base.name !== undefined ? { binds: base.name } : {}),
+    };
+    nodes.push(mk(bodyStmt, false));
+    for (const d of e.derive ?? [])
+        nodes.push(mk(compileDerive(d, nextId), false));
+    for (const ed of e.edges ?? [])
+        nodes.push(mk(compileEdge(ed, nextId), false));
+    for (const em of e.emits ?? [])
+        nodes.push(mk(compileEmit(em, nextId), false));
+    return { nodes, bodyId };
+}
+function topoOrder(nodes) {
+    const byName = new Map();
+    for (const n of nodes) {
+        if (n.produces !== null) {
+            if (byName.has(n.produces)) {
+                throw new Error(`write-plan: two writes both bind the name '${n.produces}' — write names must be unique in a composite Command.`);
+            }
+            byName.set(n.produces, n);
+        }
+    }
+    const succ = new Map();
+    const indeg = new Map();
+    const nodeById = new Map();
+    for (const n of nodes) {
+        nodeById.set(n.stmt.id, n);
+        succ.set(n.stmt.id, new Set());
+        indeg.set(n.stmt.id, 0);
+    }
+    const addEdge = (fromId, toId) => {
+        if (fromId === toId)
+            return;
+        const s = succ.get(fromId);
+        if (!s.has(toId)) {
+            s.add(toId);
+            indeg.set(toId, indeg.get(toId) + 1);
+        }
+    };
+    for (const n of nodes) {
+        for (const dep of n.consumes) {
+            const producer = byName.get(dep);
+            if (producer === undefined) {
+                throw new Error(`write-plan: statement '${n.stmt.label}' references '$.ref.${dep}.*' but no write in this ` +
+                    `Command binds the name '${dep}' — a dangling write reference (fail-closed; no silent skip).`);
+            }
+            addEdge(producer.stmt.id, n.stmt.id);
+        }
+    }
+    const gates = nodes.filter((n) => n.isGate);
+    const nonGates = nodes.filter((n) => !n.isGate);
+    for (const g of gates)
+        for (const b of nonGates)
+            addEdge(g.stmt.id, b.stmt.id);
+    const ordered = [];
+    const ready = nodes.filter((n) => indeg.get(n.stmt.id) === 0).sort((a, b) => a.seq - b.seq);
+    while (ready.length > 0) {
+        const n = ready.shift();
+        ordered.push(n.stmt);
+        for (const depId of succ.get(n.stmt.id)) {
+            indeg.set(depId, indeg.get(depId) - 1);
+            if (indeg.get(depId) === 0) {
+                const dn = nodeById.get(depId);
+                let lo = 0;
+                while (lo < ready.length && ready[lo].seq < dn.seq)
+                    lo++;
+                ready.splice(lo, 0, dn);
+            }
+        }
+    }
+    if (ordered.length !== nodes.length) {
+        const stuck = nodes.filter((n) => !ordered.includes(n.stmt)).map((n) => n.stmt.label);
+        throw new Error(`write-plan: the write-time transaction DAG has a CYCLE (unresolvable ordering among ` +
+            `[${stuck.join(', ')}]). This is either a mutual '$.ref' data dependency or a gate that ` +
+            `depends on a body row (a gate cannot depend on a not-yet-written row). ESCALATE: the ` +
+            `Command's write dependencies are contradictory — no order satisfies both the data ` +
+            `dependencies and gate-first. (Fail-closed; the derivation never guesses an order.)`);
+    }
+    return ordered;
+}
+/**
+ * Derive the ORDERED, gate-first {@link TransactionPlan} from a Command's base write(s) + its
+ * lifecycle save contract (spec §6 / §14). Single base write = fixed §6 group; multiple named
+ * base writes = a topologically-ordered gate-first tx DAG (`$.ref.<name>.*` data dependencies).
+ */
+function deriveTransactionPlan(phase, bases, lifecycle, dialect = 'sqlite') {
+    if (bases.length === 0) {
+        throw new Error('write-plan: a Command must declare at least one base write (Insert/Update/Delete).');
+    }
+    const nextId = makeIdGen();
+    const seqRef = { n: 0 };
+    const composite = bases.length > 1;
+    const allNodes = [];
+    const bodyIds = [];
+    bases.forEach((base, i) => {
+        const lc = base.effects !== undefined ? { effects: base.effects } : i === 0 ? lifecycle : { effects: {} };
+        const { nodes, bodyId } = compileWriteGroup(base, lc, nextId, dialect, seqRef);
+        allNodes.push(...nodes);
+        bodyIds.push(bodyId);
+    });
+    const statements = topoOrder(allNodes);
+    const soleBody = bases[0];
+    const soleBodyId = bodyIds[0];
+    const usesEntity = referencesHead(statements, writes_1.ENTITY_ROOT);
+    const soleBodyReturns = /\breturning\b/i.test(soleBody.op.sql);
+    if (usesEntity && composite) {
+        throw new Error(`write-plan: a composite (multi-write) Command uses '$.entity.*' — ambiguous which write it ` +
+            `denotes. Address each write's row by name via '$.ref.<writeName>.<field>' (fail-closed).`);
+    }
+    if (usesEntity && !soleBodyReturns) {
+        throw new Error(`write-plan: a derive/edges/emits stage references '$.entity.*' but the body write ` +
+            `('${soleBody.label}') has no RETURNING clause — the written row cannot be exposed to later ` +
+            `stages. Add a RETURNING to the base write (fail-closed; no absent-entity default).`);
+    }
+    const entityFrom = usesEntity || (!composite && soleBodyReturns) ? soleBodyId : null;
+    for (const base of bases) {
+        if (base.name === undefined)
+            continue;
+        if (referencesHead(statements, base.name) && !/\breturning\b/i.test(base.op.sql)) {
+            throw new Error(`write-plan: write '${base.name}' is referenced as '$.ref.${base.name}.*' by a later ` +
+                `statement but its op has no RETURNING clause — its row cannot be bound for downstream ` +
+                `writes. Add a RETURNING to write '${base.name}' (fail-closed; no absent-row default).`);
+        }
+    }
+    return { phase, entityFrom, statements, onIdempotentHit: 'rollback' };
+}
+/**
+ * Lower a list of CONCRETE batch-write ops (createMany / updateMany / deleteMany — each already
+ * compiled by driving the v1 builders in `compile-crud`, so its `sql` is byte-identical to v1 and
+ * its `params` are concrete grouped values) into a gate-free {@link TransactionPlan} of `body`
+ * statements, run IN THE DECLARED ORDER as ONE transaction. This is the makeSQL re-expression of a
+ * BATCH write: createMany with heterogeneous column-set groups is exactly a composition of several
+ * INSERT statements (`_insert:928-975` grouping), and each group's SQL is one v1-copied statement.
+ *
+ * Each op's concrete params are {@link literalize}d into bc literal-carrier IR so they survive the
+ * tx runtime's `evaluateExpression` render pass unchanged (a PG batch binds real arrays). The plan
+ * carries NO gates and NO `$.entity`/`$.ref` bindings — a batch write is N independent grouped
+ * statements, executed in order (the last statement's RETURNING rows, if any, are the `entity`).
+ */
+function deriveBatchPlan(phase, ops) {
+    if (ops.length === 0) {
+        throw new Error('write-plan: a batch write must declare at least one statement (createMany/updateMany/deleteMany produced none).');
+    }
+    const nextId = makeIdGen();
+    const statements = ops.map((op, i) => ({
+        id: nextId('body'),
+        role: 'body',
+        op: { sql: op.sql, params: op.params.map((p) => literalize(p)) },
+        label: op.label ?? `batch[${i}]`,
+    }));
+    // A batch write has NO single `$.entity` row — it is N grouped statements, each possibly RETURNING
+    // its own rows. `entityFrom` stays null; the runtime accumulates EVERY body statement's RETURNING
+    // rows into `TransactionResult.returnedRows` (ordered by group), reproducing v1 `createMany`'s
+    // "all created rows" result while `expectedDbState` proves the persisted state.
+    return { phase, entityFrom: null, statements, onIdempotentHit: 'rollback' };
+}
+/** Collect the ref-heads (`ref[0]`) a statement's params reference. */
+function refHeadsOf(stmt) {
+    const heads = new Set();
+    collectRefHeads(stmt.op.params, heads);
+    return [...heads];
+}
+/** True if a ref-head is an INPUT head (a bare `$.input.<f>` → 1-element `{ref:['<f>']}`). */
+function isInputHead(head, stmt) {
+    return refPathLengthFor(stmt.op.params, head) === 1;
+}
+function refPathLengthFor(node, head) {
+    let maxLen = 0;
+    const walk = (n) => {
+        if (n === null || typeof n !== 'object')
+            return;
+        if (Array.isArray(n)) {
+            for (const el of n)
+                walk(el);
+            return;
+        }
+        const keys = Object.keys(n);
+        if (keys.length === 1 && keys[0] === 'ref') {
+            const path = n.ref;
+            if (Array.isArray(path) && path[0] === head)
+                maxLen = Math.max(maxLen, path.length);
+            return;
+        }
+        for (const k of keys)
+            walk(n[k]);
+    };
+    walk(node);
+    return maxLen;
+}
+function referencesHead(statements, head) {
+    const heads = new Set();
+    for (const s of statements)
+        collectRefHeads(s.op.params, heads);
+    return heads.has(head);
+}
+function collectRefHeads(node, heads) {
+    if (node === null || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const el of node)
+            collectRefHeads(el, heads);
+        return;
+    }
+    const keys = Object.keys(node);
+    if (keys.length === 1 && keys[0] === 'ref') {
+        const path = node.ref;
+        if (Array.isArray(path) && typeof path[0] === 'string')
+            heads.add(path[0]);
+        return;
+    }
+    for (const k of keys)
+        collectRefHeads(node[k], heads);
+}
+/** bc evaluates ints to bigint; convert a rendered param to a driver-bindable value. */
+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;
+    }
+    // An emit payload evaluates to a plain object (`{obj:{…}}`); serialize it to the outbox JSON text.
+    if (v !== null && typeof v === 'object' && !Array.isArray(v))
+        return JSON.stringify(v);
+    return v;
+}
+/**
+ * Render a statement's makeSQL op against the tx scope: evaluate each deferred Expression-IR
+ * param to a concrete value (bc `evaluateExpression`), build a concrete `makeSQL`, then
+ * assemble + render to the dialect placeholder form. This is the SAME assemble/render the read
+ * path uses — only the param values come from the tx scope, not a compile-time input.
+ */
+function renderStatement(op, scope, dialect) {
+    const concrete = op.params.map((p) => (0, behavior_contracts_1.evaluateExpression)(p, scope));
+    const node = { sql: op.sql, params: concrete };
+    const assembled = (0, makesql_1.assembleMakeSQL)(node);
+    return { sql: (0, handler_1.renderPlaceholders)(assembled.sql, dialect), params: assembled.params.map((p) => toDriverParam(p)) };
+}
+function execStatement(db, op, scope, dialect) {
+    const { sql, params } = renderStatement(op, scope, dialect);
+    const stmt = db.prepare(sql);
+    const hasReturn = /\bselect\b/i.test(sql.slice(0, 8)) || /\breturning\b/i.test(sql);
+    if (hasReturn) {
+        const rows = stmt.all(...params);
+        return { rows, changes: rows.length };
+    }
+    const info = stmt.run(...params);
+    return { rows: [], changes: info.changes };
+}
+function gateShortCircuit(gate, result) {
+    switch (gate) {
+        case 'existsElseRollback':
+            return result.rows.length === 0 ? 'requires_absent' : null;
+        case 'insertedElseRollback':
+            return result.changes === 0 ? 'unique_collision' : null;
+        case 'insertedElseNoop':
+            return result.changes === 0 ? 'idempotent_duplicate' : null;
+        default:
+            // Fail-CLOSED on an unknown / forward-incompatible gate rule (aligned with Python + Rust): a
+            // corrupt or unrecognized gate MUST NOT silently continue (fail-open would let a malformed gate
+            // be skipped and the write COMMIT). Throwing here aborts the tx (the caller's catch ROLLBACKs).
+            throw new Error(`scp write: unknown gate rule '${String(gate)}'`);
+    }
+}
+/** Execute a derived {@link TransactionPlan} as ONE real SQLite transaction with gate-first. */
+function executeTransaction(db, plan, input, dialect = 'sqlite') {
+    db.prepare('BEGIN').run();
+    const executed = [];
+    const scope = { ...input };
+    let entity = null;
+    // Batch mode (createMany/updateMany/deleteMany): a gate-free, ref-free plan (no `$.entity`, no
+    // gates, no `$.ref` binds) — a pure list of body statements. Only THEN accumulate each body
+    // statement's RETURNING rows in order (a composite Command also has `entityFrom:null` but carries
+    // `binds`/gates and is NOT batch — its written rows flow via scope refs, not `returnedRows`).
+    const isBatch = plan.entityFrom === null &&
+        plan.statements.every((s) => s.gate === undefined && s.binds === undefined && s.role === 'body');
+    const returnedRows = [];
+    try {
+        for (const stmt of plan.statements) {
+            const result = execStatement(db, stmt.op, scope, dialect);
+            executed.push(stmt.id);
+            if (stmt.gate !== undefined) {
+                const reason = gateShortCircuit(stmt.gate, result);
+                if (reason !== null) {
+                    db.prepare('ROLLBACK').run();
+                    return { committed: false, shortCircuit: { statementId: stmt.id, reason }, entity: null, executed };
+                }
+            }
+            if (stmt.id === plan.entityFrom) {
+                entity = result.rows.length > 0 ? result.rows[0] : null;
+                if (entity !== null)
+                    scope[writes_1.ENTITY_ROOT] = entity;
+            }
+            if (stmt.binds !== undefined && result.rows.length > 0) {
+                scope[stmt.binds] = result.rows[0];
+            }
+            if (isBatch && stmt.role === 'body' && result.rows.length > 0)
+                returnedRows.push(result.rows);
+        }
+        db.prepare('COMMIT').run();
+        return { committed: true, entity, executed, ...(returnedRows.length > 0 ? { returnedRows } : {}) };
+    }
+    catch (e) {
+        try {
+            db.prepare('ROLLBACK').run();
+        }
+        catch {
+            /* ROLLBACK best-effort; surface the original failure below */
+        }
+        throw (0, errors_1.mapSqliteError)(e);
+    }
+}
+/**
+ * A counting {@link SqliteDb} wrapper: forwards every call to the wrapped driver but records
+ * each PREPARED SQL string. Tests use it to PROVE gate-first short-circuit.
+ */
+function countingDriver(db) {
+    const prepared = [];
+    const wrapped = {
+        prepare(sql) {
+            prepared.push(sql);
+            return db.prepare(sql);
+        },
+    };
+    return { db: wrapped, prepared };
+}
+/** Render one statement op to its dialect SQL text + params (exposed for golden tests). */
+function renderTxStatement(op, scope, dialect = 'sqlite') {
+    return renderStatement(op, scope, dialect);
+}
+//# sourceMappingURL=tx.js.map