litedbmodel 2.0.2 → 2.2.0

package/dist/scp/emit/emitter.js

@@ -0,0 +1,782 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — the decorator/metadata → SCP-restricted TS LOWERING EMITTER.
+ *
+ * This is the middle of the settled model (CLAUDE.md §1):
+ *
+ * ```
+ * ORM user: decorated models + DECLARED endpoints (no SQL)      ← src/decorators.ts + ./endpoint
+ *    ↓  emitBehaviorModule — THIS module
+ * SCP-restricted TS: `@behavior static` methods calling the ONE `@leaf` catalog (`Db`), with the
+ * dialect SQL already baked in by `makesql`
+ *    ↓  bc generate --from
+ * go / rust / py / php / ts native modules — bc wires the leaves automatically
+ * ```
+ *
+ * ## It compiles nothing of its own
+ *
+ * Every artifact the emitter puts in the emitted source comes from an EXISTING aggregation point —
+ * the emitter only RENDERS them as TypeScript:
+ *
+ *  | emitted thing                | comes from                                                      |
+ *  |------------------------------|-----------------------------------------------------------------|
+ *  | read SQL + param order       | `makesql/compile-select.compileSelect`                           |
+ *  | WHERE text (whole / fragment)| `makesql/compile.compileWhere` → `DBConditions`                  |
+ *  | static IN-list membership    | `makesql/json-array.inListPredicate` (PG `= ANY(?)`, #46)        |
+ *  | write SQL + param order      | `makesql/tx.compileWriteNode` (INSERT/UPDATE/DELETE + batch)     |
+ *  | relation batch SQL + keys    | `relation.compileRelationOp` (+ `parentKeyCols`/`targetKeyCols`) |
+ *  | relation hard-limit guard    | `relation.relationGuard` (the compiled op's resolved cap)         |
+ *  | row types                    | `makesql/outtype.deriveReadRow` over the model's `@column` SoT   |
+ *  | column SQL types             | `decorator-adapter.deriveModelColumns` / `modelColumnResolver`   |
+ *  | relation declarations        | `decorator-adapter.relationDeclOf`                               |
+ *  | find hard-limit cap          | `limit-config.resolveFindHardLimit`                              |
+ *  | the leaf catalog             | `leaf-transport.Db` (imported by the emitted module)             |
+ *
+ * ## How a parameter reaches the SQL
+ *
+ * The builders bind VALUES: they push whatever value a condition/port carried into `params` in the
+ * exact order the `?`s appear. The emitter therefore hands them a {@link ParamRef} SENTINEL instead
+ * of a value and reads the sentinels back out of `params` — so the emitted `params` array is the
+ * builders' own binding order, with each slot rendered as the method parameter it stands for. A slot
+ * that came back as a plain value (a QUERY view's own fragment params) renders as a literal.
+ *
+ * ## SKIP / dynamic WHERE (CLAUDE.md §2 — settled)
+ *
+ * A predicate declared `optional` is present-or-absent PER CALL, so the final SQL can only be
+ * determined at execution time. The emitter therefore does NOT bake it: it passes the WHERE as
+ * FRAGMENTS — SQL text + params, and a skipped fragment is simply omitted — and the `executeSQL`
+ * leaf assembles the survivors when it runs ({@link import('../leaves').assembleDynamicWhere}); the
+ * `?`→`$N` render happens after that, on the final SQL. There is no intermediate IR vocabulary: a
+ * fragment is `{sql, params}` and nothing else, and a skipped one evaluates to `null` (bc's `cond` is
+ * lazy, so a dropped fragment's params are never evaluated).
+ *
+ * A statement with NO optional predicate carries no plan at all — its WHERE is lowered into the
+ * static `sql` at emit time (native-clean). One path, chosen per statement.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitBehaviorModule = emitBehaviorModule;
+const DBValues_1 = require("../../DBValues");
+const compile_select_1 = require("../makesql/compile-select");
+const compile_1 = require("../makesql/compile");
+const json_array_1 = require("../makesql/json-array");
+const tx_1 = require("../makesql/tx");
+const outtype_1 = require("../makesql/outtype");
+const coltype_1 = require("../coltype");
+const compile_relation_1 = require("../makesql/compile-relation");
+const relation_1 = require("../relation");
+const limit_config_1 = require("../limit-config");
+const decorator_adapter_1 = require("../decorator-adapter");
+const decorators_1 = require("../../decorators");
+// ── parameter sentinels (what the builders bind instead of a value) ───────────────────────────
+/**
+ * A stand-in for a bound VALUE that renders as a TS expression in the emitted `params` array. The
+ * builders treat it as an opaque scalar (it is not `null`, not an array, not a `DBToken`, not a
+ * `DBConditions`), so every builder emits its ordinary single-`?` form and pushes this object into
+ * `params` at exactly the slot the `?` occupies.
+ */
+class ParamRef {
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+}
+// ── entry point ───────────────────────────────────────────────────────────────────────────────
+/**
+ * Lower a set of declared endpoints to SCP-restricted TypeScript. The result's `source` is ordinary
+ * `tsc --strict` TypeScript (that is bc's authoring requirement) whose only imports are bc's
+ * authoring markers and the library's ONE leaf catalog.
+ */
+function emitBehaviorModule(spec) {
+    const names = Object.keys(spec.endpoints);
+    if (names.length === 0)
+        throw new Error(`emit: behavior '${spec.behavior}' declares no endpoints`);
+    const ctx = new EmitContext(spec);
+    const methods = names.map((name) => ctx.method(name, spec.endpoints[name]));
+    return { source: ctx.render(methods), endpoints: ctx.contracts };
+}
+class EmitContext {
+    spec;
+    /** Emitted row interfaces, in declaration order (`name → body text`). */
+    interfaces = new Map();
+    /** The per-endpoint call contracts, in emission order. */
+    contracts = [];
+    constructor(spec) {
+        this.spec = spec;
+    }
+    // ── model metadata (all of it from the decorator SoT) ───────────────────────────────────────
+    resolver(model) {
+        const r = (0, decorator_adapter_1.modelColumnResolver)(model, this.spec.columnOptions);
+        if (r === undefined) {
+            throw new Error(`emit: model '${model.name}' declares no @column metadata — the emitter types every projection ` +
+                `and every bound parameter from the column SoT (no-assume, no-fallback).`);
+        }
+        return r;
+    }
+    /** The model's declared columns (`column → SQL type`) — the ONE type SoT. */
+    columnsOf(model) {
+        const table = (0, decorator_adapter_1.tableNameOf)(model);
+        const cols = (0, decorator_adapter_1.deriveModelColumns)(model, this.spec.columnOptions)[table];
+        if (cols === undefined) {
+            throw new Error(`emit: model '${model.name}' declares no @column metadata (table '${table}')`);
+        }
+        return cols;
+    }
+    sqlTypeOf(model, column) {
+        const t = this.columnsOf(model)[column];
+        if (t === undefined) {
+            throw new Error(`emit: model '${model.name}' has no @column '${column}' — a declared endpoint may only name ` +
+                `columns the model declares (no-assume, no-fallback).`);
+        }
+        return t;
+    }
+    /** The TS type a BOUND parameter carries for a column (the bc scalar of its declared SQL type). */
+    bindTypeOf(model, column) {
+        return tsScalar((0, coltype_1.sqlTypeToBcScalar)(this.sqlTypeOf(model, column)));
+    }
+    // ── methods ────────────────────────────────────────────────────────────────────────────────
+    method(name, endpoint) {
+        assertIdentifier(name, `endpoint name '${name}'`);
+        const m = this.lower(name, endpoint);
+        const cap = endpoint.kind === 'read' ? this.bakedFindCap(endpoint) : null;
+        this.contracts.push({
+            name,
+            params: m.params.map((p) => ({ name: p.name, type: p.type })),
+            returnType: m.returnType,
+            ...(cap !== null ? { findHardLimit: cap } : {}),
+        });
+        return m;
+    }
+    lower(name, endpoint) {
+        switch (endpoint.kind) {
+            case 'read':
+                return this.read(name, endpoint);
+            case 'create':
+            case 'update':
+            case 'delete':
+                return this.write(name, endpoint);
+            case 'createMany':
+            case 'updateMany':
+            case 'deleteMany':
+                return this.batch(name, endpoint);
+        }
+    }
+    // ── READ ───────────────────────────────────────────────────────────────────────────────────
+    /**
+     * The `findHardLimit` cap this read bakes: the configured cap when the endpoint declares NO explicit
+     * limit (an authored LIMIT governs — v1's skip rule; a BOUND limit is authored too, the author
+     * declared that this endpoint is paged), else `null`. Read from the config SSoT
+     * ({@link resolveFindHardLimit}) at EMIT time, exactly as the retired compile-time bake did.
+     */
+    bakedFindCap(endpoint) {
+        if (endpoint.limit !== undefined)
+            return null;
+        return (0, limit_config_1.resolveFindHardLimit)();
+    }
+    /**
+     * Lower ONE declared page position to the `compileSelect` tail. A static count passes straight
+     * through and inlines as the literal it always was; a `{ param }` position declares an `Int` method
+     * parameter and binds through the SAME tail as a {@link BoundCount} sentinel, so the paged and the
+     * bounded read are one statement builder and one param list.
+     *
+     * A count is an `Int` by SQL's own definition of `LIMIT` / `OFFSET` — it names no model column, so
+     * there is no column type to resolve it from.
+     */
+    page(p, params) {
+        if (p === undefined || typeof p === 'number')
+            return p;
+        assertIdentifier(p.param, `parameter '${p.param}'`);
+        params.push({ name: p.param, type: tsScalar('int') });
+        return { bind: new ParamRef(p.param) };
+    }
+    read(name, endpoint) {
+        const model = endpoint.model;
+        const resolve = this.resolver(model);
+        const baseTable = (0, decorator_adapter_1.tableNameOf)(model);
+        // A QUERY view-model reads from the derived CTE alias; the projection types resolve against the
+        // model's declared columns either way (the CTE projects the model's own columns).
+        const alias = endpoint.view?.alias ?? 'derived';
+        const table = endpoint.view !== undefined ? alias : baseTable;
+        const projection = endpoint.select ?? Object.keys(this.columnsOf(model));
+        const readResolve = endpoint.view !== undefined ? (t, c) => resolve(t === alias ? baseTable : t, c) : resolve;
+        const cap = this.bakedFindCap(endpoint);
+        const where = endpoint.where ?? [];
+        const dynamic = where.some(isOptional);
+        if (dynamic && endpoint.view !== undefined) {
+            throw new Error(`emit: endpoint '${name}': a QUERY view-model binds its own CTE params BEFORE the WHERE, and a ` +
+                `dynamic (SKIP) WHERE is assembled at execution time — the two cannot share one param order. ` +
+                `Declare the view's own predicate inside the view query, or drop the optional predicate.`);
+        }
+        const params = [];
+        for (const p of where)
+            this.declareWhereParams(model, p, params);
+        // The page tail binds AFTER the WHERE — the order its `?`s occupy in the finished statement, and
+        // therefore the order the parameters are declared in.
+        const limit = this.page(endpoint.limit ?? (cap !== null ? cap + 1 : undefined), params);
+        const offset = this.page(endpoint.offset, params);
+        // A read with ANY optional predicate carries its WHOLE WHERE as fragments (the leaf assembles the
+        // survivors at execution time); a fully-bounded read lowers its WHERE into the static `sql` here.
+        const compiled = (0, compile_select_1.compileSelect)({
+            dialect: this.spec.dialect,
+            tableName: table,
+            select: projection.join(', '),
+            ...(dynamic ? {} : { conditions: this.conditions(model, where) }),
+            ...(endpoint.view !== undefined ? { cte: cteOf(endpoint.view) } : {}),
+            ...(endpoint.order !== undefined ? { order: endpoint.order } : {}),
+            ...(limit !== undefined ? { limit } : {}),
+            ...(offset !== undefined ? { offset } : {}),
+            ...(endpoint.lock === 'update' ? { forUpdate: true } : endpoint.lock === 'share' ? { forShare: true } : {}),
+        });
+        const bigint = endpoint.bigint === true;
+        const call = `${quote(compiled.sql)}, [${compiled.params.map(renderSlot).join(', ')}], false, false, ${bigint}${dynamic ? `, ${this.dynamicWherePlan(model, where)}` : ''}`;
+        const rowObj = objOf((0, outtype_1.deriveReadRow)(table, projection, readResolve, `endpoint '${name}'`).outType, name);
+        const selections = normalizeSelections(endpoint.with ?? []);
+        const fresh = freshNames(params.map((p) => p.name));
+        if (selections.length === 0) {
+            const rowType = this.declareInterface(`${cap1(name)}Row`, rowObj);
+            const out = fresh('rows');
+            return {
+                name,
+                params,
+                returnType: `${rowType}[]`,
+                lines: [`const ${out}: ${rowType}[] = Db.executeSQL(${call}) as ${rowType}[];`, `return ${out};`],
+            };
+        }
+        // Relation graph: parents → (pluck → child executeSQL → group)*, ONE query per level (N+1-free).
+        const lines = [];
+        const parentVar = fresh('rows');
+        lines.push(`const ${parentVar}: WireValue[] = Db.executeSQL(${call});`);
+        const graph = this.relations(model, parentVar, rowObj, selections, lines, fresh, bigint, `endpoint '${name}'`);
+        const rowType = this.declareInterface(`${cap1(name)}Row`, graph.obj);
+        // The terminal binding is the SINGLE de-box point: the annotation is what bc reads, the one
+        // assertion is what narrows the opaque wire value for tsc.
+        lines[lines.length - 1] = `const ${graph.terminalVar}: ${rowType}[] = ${graph.terminalCall} as ${rowType}[];`;
+        lines.push(`return ${graph.terminalVar};`);
+        return { name, params, returnType: `${rowType}[]`, lines };
+    }
+    /**
+     * The DYNAMIC WHERE plan expression: one fragment per declared predicate — `{sql, params}` from the
+     * SAME `compileWhere` that produces a bounded WHERE — with an optional one wrapped in a conditional
+     * that yields `null` when its parameter is absent. That is the whole fragment vocabulary.
+     */
+    dynamicWherePlan(model, where) {
+        const frags = where.map((p) => {
+            const w = (0, compile_1.compileWhere)(this.conditions(model, [p]), this.spec.dialect);
+            const frag = `{ sql: ${quote(w.sql)}, params: [${w.params.map(renderSlot).join(', ')}] }`;
+            return isParameterised(p) && p.optional === true ? `${p.param} !== null ? ${frag} : null` : frag;
+        });
+        return `{ frags: [${frags.join(', ')}] }`;
+    }
+    /**
+     * Emit ONE relation LEVEL: for each selected relation, pluck the parent key set, run the ONE batched
+     * child SELECT (`compileRelationOp`'s static SQL) and nest the children under the parent. A nested
+     * selection recurses FIRST, so a grandchild level is grouped into its own parent before that parent
+     * is grouped into ours (one query per depth — never one per parent).
+     */
+    relations(model, parentVar, parentObj, selections, lines, fresh, bigint, at) {
+        let acc = parentVar;
+        const obj = { ...parentObj };
+        let terminalCall = '';
+        let terminalVar = '';
+        for (const sel of selections) {
+            const { decl, targetModel } = this.relationDecl(model, sel.name, at);
+            const op = (0, relation_1.compileRelationOp)(decl, this.resolver(targetModel));
+            const keysVar = fresh(`${sel.name}Keys`);
+            lines.push(`const ${keysVar}: WireValue[] = Db.pluck(${acc}, ${jsonArray((0, relation_1.parentKeyCols)(op))});`);
+            const childVar = fresh(sel.name);
+            // The runaway guard the compiled op resolved (`hasManyHardLimit` / the per-relation override):
+            // baked onto the child fetch so the `executeSQL` transport asserts the RAW child row count —
+            // the only point they are visible, since `group` receives an already-nested graph. A relation
+            // batch never carries a dynamic WHERE (its SQL is fully static), so the `whereDynamic` slot is
+            // an honest `null`. Uncapped ⇒ the ports stop at `bigint` and the call is byte-unchanged.
+            const guard = (0, relation_1.relationGuard)(op);
+            const guardPorts = guard !== null ? `, null, ${JSON.stringify(guard)}` : '';
+            lines.push(`const ${childVar}: WireValue[] = Db.executeSQL(${quote(op.sql)}, [${keysVar}], false, false, ${bigint}${guardPorts});`);
+            let childRows = childVar;
+            let childObj = objOf((0, outtype_1.deriveReadRow)(decl.targetTable, decl.select, this.resolver(targetModel), `${at} relation '${sel.name}'`).outType, `${at} relation '${sel.name}'`);
+            if (sel.with.length > 0) {
+                const nested = this.relations(targetModel, childVar, childObj, normalizeSelections(sel.with), lines, fresh, bigint, `${at}.${sel.name}`);
+                childObj = nested.obj;
+                childRows = nested.terminalVar;
+            }
+            const single = decl.kind !== 'hasMany';
+            obj[sel.name] = single ? { opt: { obj: childObj } } : { arr: { obj: childObj } };
+            terminalVar = fresh(`${sel.name}Graph`);
+            terminalCall = `Db.group(${acc}, ${childRows}, ${jsonArray((0, relation_1.parentKeyCols)(op))}, ${jsonArray((0, relation_1.targetKeyCols)(op))}, ${quote(sel.name)}, ${single})`;
+            lines.push(`const ${terminalVar}: WireValue[] = ${terminalCall};`);
+            acc = terminalVar;
+        }
+        return { obj, terminalCall, terminalVar };
+    }
+    /** The model's `@hasMany`/`@belongsTo`/`@hasOne` declaration for `name` (the decorator SoT). */
+    relationDecl(model, name, at) {
+        const rel = (0, decorators_1.getRelationMeta)(model).find((r) => r.propertyKey === name);
+        if (rel === undefined) {
+            throw new Error(`emit: ${at}: model '${model.name}' declares no relation '${name}' (@hasMany/@belongsTo/@hasOne)`);
+        }
+        const models = this.spec.models;
+        if (models === undefined) {
+            throw new Error(`emit: ${at}: relation '${name}' needs the model registry (EmitSpec.models) to resolve its target model`);
+        }
+        return (0, decorator_adapter_1.relationDeclOf)(rel, models, this.spec.dialect);
+    }
+    // ── WRITE (single-row INSERT / UPDATE / DELETE) ─────────────────────────────────────────────
+    write(name, endpoint) {
+        const model = endpoint.model;
+        const table = (0, decorator_adapter_1.tableNameOf)(model);
+        const params = [];
+        const returning = endpoint.returning;
+        const ports = { table };
+        this.returningPorts(model, returning, ports);
+        let component;
+        if (endpoint.kind === 'create') {
+            component = 'Insert';
+            this.valuePorts(model, endpoint.values, 'values', ports, params);
+            if (endpoint.onConflict !== undefined) {
+                ports.onConflict = endpoint.onConflict.join(', ');
+                ports.onConflictAction = endpoint.onConflictAction ?? 'update';
+            }
+        }
+        else if (endpoint.kind === 'update') {
+            component = 'Update';
+            this.valuePorts(model, endpoint.set, 'set', ports, params);
+            ports.where = this.wherePort(model, endpoint.where, params, `endpoint '${name}'`);
+        }
+        else {
+            component = 'Delete';
+            ports.where = this.wherePort(model, endpoint.where, params, `endpoint '${name}'`);
+        }
+        const op = (0, tx_1.compileWriteNode)({ component, ports }, this.spec.dialect, this.resolver(model));
+        const rowType = this.writeRowType(name, model, returning);
+        const out = freshNames(params.map((p) => p.name))('rows');
+        return {
+            name,
+            params,
+            returnType: `${rowType}[]`,
+            lines: [
+                `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${op.params.map(renderSlot).join(', ')}], true, ${returning !== undefined}, false) as ${rowType}[];`,
+                `return ${out};`,
+            ],
+        };
+    }
+    /** Declare the `<family>.<column>` ports for a VALUES / SET list, binding each to a method parameter. */
+    valuePorts(model, bindings, family, ports, params) {
+        if (bindings.length === 0)
+            throw new Error(`emit: a write needs at least one '${family}' binding`);
+        for (const b of bindings) {
+            assertIdentifier(b.param, `parameter '${b.param}'`);
+            params.push({ name: b.param, type: this.bindTypeOf(model, b.column) });
+            ports[`${family}.${b.column}`] = new ParamRef(b.param);
+        }
+    }
+    /**
+     * The write path's `where` port — the `{arr:[…]}` Expression-IR member list `compileWriteNode`
+     * lowers (`lowerWherePort`). Only that compiler's declared vocabulary is lowerable there; anything
+     * else is a loud reject rather than a second WHERE compiler.
+     */
+    wherePort(model, where, params, at) {
+        if (where.length === 0)
+            throw new Error(`emit: ${at}: an UPDATE / DELETE endpoint must declare a WHERE`);
+        const members = where.map((p) => {
+            if (p.kind === 'isNull')
+                return { eq: [{ ref: [p.column] }, null] };
+            if (p.kind === 'isNotNull')
+                return { ne: [{ ref: [p.column] }, null] };
+            if (p.kind !== undefined && p.kind !== 'compare') {
+                throw new Error(`emit: ${at}: the write compiler's WHERE vocabulary is eq/ne/lt/le/gt/ge and IS [NOT] NULL ` +
+                    `(compileWriteNode.lowerWhereMember) — '${p.kind}' is not lowerable on a write.`);
+            }
+            const cmp = p;
+            if (cmp.optional === true) {
+                throw new Error(`emit: ${at}: a SKIP (optional) predicate is a READ construct — a write's WHERE is fixed.`);
+            }
+            if (cmp.op === 'like')
+                throw new Error(`emit: ${at}: LIKE is not part of the write compiler's WHERE vocabulary`);
+            assertIdentifier(cmp.param, `parameter '${cmp.param}'`);
+            params.push({ name: cmp.param, type: this.bindTypeOf(model, cmp.column) });
+            return { [cmp.op]: [{ ref: [cmp.column] }, new ParamRef(cmp.param)] };
+        });
+        return { arr: members };
+    }
+    // ── BATCH writes ───────────────────────────────────────────────────────────────────────────
+    batch(name, endpoint) {
+        if (endpoint.kind === 'deleteMany')
+            return this.deleteMany(name, endpoint);
+        const model = endpoint.model;
+        assertIdentifier(endpoint.param, `parameter '${endpoint.param}'`);
+        const pg = this.spec.dialect === 'postgres';
+        const params = [];
+        const ports = { table: (0, decorator_adapter_1.tableNameOf)(model), batch: 'true' };
+        this.returningPorts(model, endpoint.returning, ports);
+        // The bind SHAPE is the builder's own: PG's `UNNEST(?::t[], …)` binds ONE ARRAY PER COLUMN, so each
+        // column gets its own array parameter; MySQL/SQLite expand ONE record-array JSON param server-side.
+        const columnParam = (column) => {
+            if (!pg)
+                return new ParamRef(endpoint.param);
+            const p = `${endpoint.param}_${column}`;
+            params.push({ name: p, type: `${this.bindTypeOf(model, column)}[]` });
+            return new ParamRef(p);
+        };
+        const columns = endpoint.kind === 'createMany' ? endpoint.columns : [...endpoint.keyColumns, ...endpoint.columns];
+        if (endpoint.kind === 'createMany') {
+            for (const c of endpoint.columns)
+                ports[`values.${c}`] = columnParam(c);
+            if (endpoint.onConflict !== undefined) {
+                ports.onConflict = endpoint.onConflict.join(', ');
+                ports.onConflictAction = endpoint.onConflictAction ?? 'update';
+            }
+        }
+        else {
+            for (const c of endpoint.keyColumns)
+                ports[`key.${c}`] = columnParam(c);
+            for (const c of endpoint.columns)
+                ports[`set.${c}`] = columnParam(c);
+        }
+        if (!pg)
+            params.push({ name: endpoint.param, type: `${this.recordType(name, model, columns)}[]` });
+        const component = endpoint.kind === 'createMany' ? 'Insert' : 'Update';
+        const op = (0, tx_1.compileWriteNode)({ component, ports }, this.spec.dialect, this.resolver(model));
+        const rowType = this.writeRowType(name, model, endpoint.returning);
+        const slots = op.params.map((p) => (isBatchRowsMarker(p) ? endpoint.param : renderSlot(p)));
+        const out = freshNames(params.map((p) => p.name))('rows');
+        return {
+            name,
+            params,
+            returnType: `${rowType}[]`,
+            lines: [
+                `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${slots.join(', ')}], true, ${endpoint.returning !== undefined}, false) as ${rowType}[];`,
+                `return ${out};`,
+            ],
+        };
+    }
+    /**
+     * `deleteMany` — a key-set DELETE. Its WHERE is the `in` member of the write compiler's own WHERE
+     * vocabulary, which lowers to the SAME static single-param membership predicate a read IN-list uses
+     * (`json-array.inListPredicate`) — so the statement text, the RETURNING tail and the mysql pk hint
+     * all come from `compileWriteNode`, not from here.
+     */
+    deleteMany(name, endpoint) {
+        const model = endpoint.model;
+        assertIdentifier(endpoint.param, `parameter '${endpoint.param}'`);
+        const params = [{ name: endpoint.param, type: `${this.bindTypeOf(model, endpoint.keyColumn)}[]` }];
+        const ports = {
+            table: (0, decorator_adapter_1.tableNameOf)(model),
+            where: { arr: [{ in: [{ ref: [endpoint.keyColumn] }, new ParamRef(endpoint.param)] }] },
+        };
+        this.returningPorts(model, endpoint.returning, ports);
+        const op = (0, tx_1.compileWriteNode)({ component: 'Delete', ports }, this.spec.dialect, this.resolver(model));
+        const rowType = this.writeRowType(name, model, endpoint.returning);
+        const out = freshNames(params.map((p) => p.name))('rows');
+        return {
+            name,
+            params,
+            returnType: `${rowType}[]`,
+            lines: [
+                `const ${out}: ${rowType}[] = Db.executeSQL(${quote(op.sql)}, [${op.params.map(renderSlot).join(', ')}], true, ${endpoint.returning !== undefined}, false) as ${rowType}[];`,
+                `return ${out};`,
+            ],
+        };
+    }
+    /**
+     * Declare the `returning` + `pk` ports a RETURNING write needs. The key is the model's DECLARATION
+     * (`@column({ primaryKey, autoIncrement })`) — a dialect with no native RETURNING recovers the
+     * written rows from it. ONE place, shared by the single-row and batch write paths.
+     */
+    returningPorts(model, returning, ports) {
+        if (returning === undefined)
+            return;
+        ports.returning = returning.join(', ');
+        const pkey = (0, decorators_1.getPrimaryKey)(model);
+        ports.pk = pkey.columns.join(',');
+        if (pkey.autoInc !== null)
+            ports.autoInc = pkey.autoInc;
+    }
+    /** A write's row type: the uniform transport summary, or the declared RETURNING projection. */
+    writeRowType(name, model, returning) {
+        if (returning === undefined)
+            return this.writeSummaryType();
+        return this.declareInterface(`${cap1(name)}Row`, objOf((0, outtype_1.deriveReadRow)((0, decorator_adapter_1.tableNameOf)(model), returning, this.resolver(model), `endpoint '${name}' RETURNING`).outType, name));
+    }
+    /** The record type a MySQL/SQLite batch write's JSON param carries (one field per bound column). */
+    recordType(name, model, columns) {
+        const obj = {};
+        for (const c of columns)
+            obj[c] = (0, coltype_1.sqlTypeToBcScalar)(this.sqlTypeOf(model, c));
+        return this.declareInterface(`${cap1(name)}Record`, obj);
+    }
+    // ── WHERE → the builders' ConditionObject ──────────────────────────────────────────────────
+    /** Declare the method parameters ONE predicate contributes (in declaration order). */
+    declareWhereParams(model, p, params) {
+        if (p.kind === 'exists' || p.kind === 'subquery') {
+            for (const m of p.match) {
+                if (m.param === undefined)
+                    continue;
+                assertIdentifier(m.param, `parameter '${m.param}'`);
+                params.push({ name: m.param, type: this.bindTypeOf(p.model, m.column) });
+            }
+            return;
+        }
+        if (p.kind === 'tupleIn') {
+            params.push(...this.tupleInParams(model, p));
+            return;
+        }
+        if (!isParameterised(p))
+            return; // IS [NOT] NULL binds nothing
+        assertIdentifier(p.param, `parameter '${p.param}'`);
+        const base = this.bindTypeOf(model, p.column);
+        const type = p.kind === 'in' ? `${base}[]` : base;
+        params.push({ name: p.param, type: p.optional === true ? `${type} | null` : type });
+    }
+    /**
+     * Build the `ConditionObject` the surviving compilers consume. Every member is v1 condition
+     * vocabulary — a bare column key (equality / IS NULL), a custom-operator key carrying its own `?`
+     * (the comparison + membership forms), or a `DBExists` / `DBSubquery` token — so the WHERE text is
+     * produced by `DBConditions` exactly as the imperative path produces it.
+     */
+    conditions(model, where) {
+        const out = {};
+        let n = 0;
+        const put = (key, value) => {
+            // The condition object is keyed BY THE SQL FRAGMENT, so two identical fragments would collapse
+            // into one. A repeat gets trailing spaces, which `DBConditions` emits verbatim (SQL-insignificant).
+            let k = key;
+            while (k in out)
+                k = `${key}${' '.repeat(++n)}`;
+            out[k] = value;
+        };
+        for (const p of where) {
+            if (p.kind === 'isNull') {
+                put(p.column, null);
+                continue;
+            }
+            if (p.kind === 'isNotNull') {
+                put(`${p.column} IS NOT NULL`, true);
+                continue;
+            }
+            if (p.kind === 'exists') {
+                put('__exists__', new DBValues_1.DBExists((0, decorator_adapter_1.tableNameOf)(p.model), this.correlation(p, model), p.not === true));
+                continue;
+            }
+            if (p.kind === 'subquery') {
+                const parentTable = (0, decorator_adapter_1.tableNameOf)(model);
+                const sub = new DBValues_1.DBSubquery(p.columns.map((c) => ({ tableName: parentTable, columnName: c })), (0, decorator_adapter_1.tableNameOf)(p.model), p.select.map((c) => ({ tableName: (0, decorator_adapter_1.tableNameOf)(p.model), columnName: c })), this.correlation(p, model), p.not === true ? 'NOT IN' : 'IN');
+                put('__subquery__', sub);
+                continue;
+            }
+            if (p.kind === 'in') {
+                put((0, json_array_1.inListPredicate)(this.spec.dialect, p.column), new ParamRef(p.param));
+                continue;
+            }
+            if (p.kind === 'tupleIn') {
+                // The predicate carries its own `?`s (one per array param on PG, one JSON param elsewhere), so
+                // it rides `DBConditions`' custom-operator route: the value list fills them positionally.
+                put((0, json_array_1.tupleInPredicate)(this.spec.dialect, (0, decorator_adapter_1.tableNameOf)(model), p.columns, this.pgElementTypes(model, p.columns)), this.tupleInParams(model, p).map((d) => new ParamRef(d.name)));
+                continue;
+            }
+            const cmp = p;
+            const ref = new ParamRef(cmp.param);
+            if (cmp.op === 'eq')
+                put(cmp.column, ref);
+            else
+                put(`${cmp.column} ${SQL_OPS[cmp.op]} ?`, ref);
+        }
+        return out;
+    }
+    /**
+     * The PG `UNNEST` element type of each key column, derived from the model's DECLARED column type via
+     * the SAME schema specimen the batch writes use (`pgTypeSpecimen` → `inferPgArrayType`) — never from
+     * the values, which are unknown at emit time and empty at call time often enough to matter.
+     */
+    pgElementTypes(model, columns) {
+        if (this.spec.dialect !== 'postgres')
+            return undefined;
+        return columns.map((c) => (0, compile_relation_1.inferPgArrayType)([(0, tx_1.pgTypeSpecimen)(this.sqlTypeOf(model, c))]));
+    }
+    /**
+     * A composite `tupleIn`'s parameters, in bind order — the ONE derivation both the signature and the
+     * condition value consume. PostgreSQL's `UNNEST(?::T1, ?::T2)` binds ONE ARRAY PER KEY COLUMN;
+     * MySQL / SQLite bind ONE JSON array of tuples.
+     */
+    tupleInParams(model, p) {
+        assertIdentifier(p.param, `parameter '${p.param}'`);
+        if (p.columns.length < 2) {
+            throw new Error(`emit: a 'tupleIn' predicate needs at least two key columns (got ${p.columns.length}) — use 'in' for a single column`);
+        }
+        if (this.spec.dialect === 'postgres') {
+            return p.columns.map((c) => ({ name: `${p.param}_${c}`, type: `${this.bindTypeOf(model, c)}[]` }));
+        }
+        const elements = [...new Set(p.columns.map((c) => this.bindTypeOf(model, c)))];
+        const element = elements.length === 1 ? elements[0] : `(${elements.join(' | ')})`;
+        return [{ name: p.param, type: `${element}[][]` }];
+    }
+    /** The subquery / EXISTS correlation terms: a parent-column ref (`parentRef` sugar) or a bound param. */
+    correlation(p, parent) {
+        const subTable = (0, decorator_adapter_1.tableNameOf)(p.model);
+        const parentTable = (0, decorator_adapter_1.tableNameOf)(parent);
+        return p.match.map((m) => {
+            const column = { tableName: subTable, columnName: m.column };
+            // Fail closed on an unknown column on either side (the correlation must name declared columns).
+            this.sqlTypeOf(p.model, m.column);
+            if (m.parentColumn !== undefined) {
+                this.sqlTypeOf(parent, m.parentColumn);
+                return { column, value: new DBValues_1.DBParentRef({ tableName: parentTable, columnName: m.parentColumn }) };
+            }
+            return { column, value: new ParamRef(m.param) };
+        });
+    }
+    // ── type declarations ──────────────────────────────────────────────────────────────────────
+    /** The uniform non-RETURNING write summary the `executeSQL` transport returns. */
+    writeSummaryType() {
+        return this.declareInterface('WriteSummary', { changes: 'int', lastInsertRowid: 'int' });
+    }
+    /** Declare (or reuse) a row interface. Two declarations of the same name must be structurally equal. */
+    declareInterface(name, obj) {
+        const body = Object.entries(obj)
+            .map(([k, t]) => `  ${propName(k)}: ${this.tsType(t, `${name}_${k}`)};`)
+            .join('\n');
+        const existing = this.interfaces.get(name);
+        if (existing !== undefined && existing !== body) {
+            throw new Error(`emit: two different row shapes both want the interface name '${name}'`);
+        }
+        this.interfaces.set(name, body);
+        return name;
+    }
+    /** A `PortableType` → its TS type text, declaring a nested interface for an embedded object. */
+    tsType(t, nameHint) {
+        if (typeof t === 'string')
+            return tsScalar(t);
+        if ('opt' in t)
+            return `${this.tsType(t.opt, nameHint)} | null`;
+        if ('arr' in t)
+            return `${this.tsType(t.arr, nameHint)}[]`;
+        if ('obj' in t)
+            return this.declareInterface(cap1(nameHint), t.obj);
+        throw new Error(`emit: portable type ${JSON.stringify(t)} has no TS rendering`);
+    }
+    // ── module rendering ───────────────────────────────────────────────────────────────────────
+    render(methods) {
+        const text = [...this.interfaces.values(), ...methods.flatMap((m) => [...m.lines, ...m.params.map((p) => p.type)])].join('\n');
+        const typeImports = ['Int', 'Float', 'WireValue'].filter((s) => new RegExp(`\\b${s}\\b`).test(text));
+        const head = [
+            `// GENERATED by litedbmodel \`emitBehaviorModule\` — the decorator → SCP lowering. DO NOT EDIT.`,
+            `//`,
+            `// Read by \`bc generate --from\`: each \`@behavior static\` method is one declared endpoint, its`,
+            `// parameters are the input ports and its return type is the output contract. The SQL is the`,
+            `// ${this.spec.dialect} text the litedbmodel \`makesql\` builders produced; the transports are the`,
+            `// library's ONE \`@leaf\` catalog (\`Db\`).`,
+            `import { behavior${typeImports.length > 0 ? `, type ${typeImports.join(', type ')}` : ''} } from 'behavior-contracts';`,
+            `import { Db } from ${quote(this.spec.leafImport)};`,
+            ``,
+        ];
+        const decls = [...this.interfaces].map(([name, body]) => `interface ${name} {\n${body}\n}`);
+        const body = methods.map((m) => {
+            const sig = m.params.map((p) => `${p.name}: ${p.type}`).join(', ');
+            return `  @behavior static ${m.name}(${sig}): ${m.returnType} {\n${m.lines.map((l) => `    ${l}`).join('\n')}\n  }`;
+        });
+        return `${head.join('\n')}${decls.join('\n\n')}\n\nexport class ${this.spec.behavior} {\n${body.join('\n\n')}\n}\n`;
+    }
+}
+// ── helpers ───────────────────────────────────────────────────────────────────────────────────
+/** The SQL comparison text of each declared comparison operator (the v1 custom-operator key form). */
+const SQL_OPS = {
+    ne: '!=',
+    lt: '<',
+    le: '<=',
+    gt: '>',
+    ge: '>=',
+    like: 'LIKE',
+};
+/** A predicate that BINDS a parameter of its own (so it can be a SKIP member). */
+function isParameterised(p) {
+    return p.kind === undefined || p.kind === 'compare' || p.kind === 'in';
+}
+/** A predicate is a SKIP member when it declares `optional` (only a parameterised member can be one). */
+function isOptional(p) {
+    return isParameterised(p) && p.optional === true;
+}
+/**
+ * Render ONE bound slot: a parameter sentinel becomes its identifier, anything else a TS literal.
+ *
+ * A batch write's slot is one of `compileWriteNode`'s BATCH MARKERS rather than a bare sentinel: the
+ * PostgreSQL `UNNEST` form binds one `{__batchArray:{column, ref}}` per column (the sentinel is its
+ * `ref`), the MySQL/SQLite JSON form binds the SAME `{__batchRows:{…}}` to every `?` (see
+ * {@link batchRowsSlot}). Both are unwrapped to the parameter they stand for.
+ */
+function renderSlot(slot) {
+    if (slot instanceof ParamRef)
+        return slot.expr;
+    const ref = slot?.__batchArray?.ref;
+    if (ref instanceof ParamRef)
+        return ref.expr;
+    return JSON.stringify(slot);
+}
+/** The MySQL/SQLite batch marker `compileWriteNode` binds to every `?` of a batch statement. */
+function isBatchRowsMarker(p) {
+    return typeof p === 'object' && p !== null && '__batchRows' in p;
+}
+/** A QUERY view-model's CTE (v1 `WITH <alias> AS (<query>)`, its own params bound FIRST). */
+function cteOf(view) {
+    const alias = view.alias ?? 'derived';
+    const q = view.query;
+    return typeof q === 'string' ? { name: alias, sql: q, params: [] } : { name: alias, sql: q.sql, params: [...q.params] };
+}
+/** The row `obj` of a `{arr:{obj:…}}` read row type. */
+function objOf(t, at) {
+    const arr = typeof t === 'object' && t !== null && 'arr' in t ? t.arr : undefined;
+    const obj = arr !== undefined && typeof arr === 'object' && arr !== null && 'obj' in arr ? arr.obj : undefined;
+    if (obj === undefined)
+        throw new Error(`emit: ${at}: expected a row type {arr:{obj:…}}, got ${JSON.stringify(t)}`);
+    if (Object.keys(obj).length === 0) {
+        throw new Error(`emit: ${at}: the projection resolved to an EMPTY row type — every projected column must be a declared @column`);
+    }
+    return obj;
+}
+/** bc scalar → TS type text (`Int`/`Float` are bc's branded numeric declarations). */
+function tsScalar(s) {
+    switch (s) {
+        case 'int':
+            return 'Int';
+        case 'float':
+            return 'Float';
+        case 'bool':
+            return 'boolean';
+        case 'null':
+            return 'null';
+        case 'string':
+            return 'string';
+    }
+}
+function normalizeSelections(sels) {
+    return sels.map((s) => (typeof s === 'string' ? { name: s, with: [] } : { name: s.name, with: s.with ?? [] }));
+}
+/**
+ * A body-binding name allocator. `reserved` holds the method's PARAMETER names: a `const` that shadowed
+ * a parameter would be a TDZ error the moment the parameter is also bound (`const rows = f(rows)`), so
+ * the allocator never hands one out.
+ */
+function freshNames(reserved = []) {
+    const used = new Map(reserved.map((r) => [r, 1]));
+    return (base) => {
+        const n = (used.get(base) ?? 0) + 1;
+        used.set(base, n);
+        return n === 1 ? base : `${base}${n}`;
+    };
+}
+function quote(s) {
+    return JSON.stringify(s);
+}
+function jsonArray(items) {
+    return `[${items.map(quote).join(', ')}]`;
+}
+function cap1(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1).replace(/[^A-Za-z0-9_]/g, '_');
+}
+/** An object-literal property name: bare when it is an identifier, quoted otherwise. */
+function propName(k) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(k) ? k : quote(k);
+}
+function assertIdentifier(name, at) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`emit: ${at} is not a valid TypeScript identifier`);
+    }
+}
+//# sourceMappingURL=emitter.js.map