litedbmodel 1.2.9 → 2.0.0

package/dist/scp/compile-sqlite.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — SQLite Backend Compile (WS1, #21).
+ *
+ * Lowers a structured CRUD operation description (a Component-graph Select/Insert/Update/
+ * Delete node with ports) into a {@link CompiledOperation}: SQLite dialect SQL text,
+ * a fragment tree (dynamic WHERE/SET with existence rules), and static param slots — the
+ * IR shape of spec §8. Placeholders are unified as `?` (the `?`→`$N` pass is PG-only and
+ * OUT OF SCOPE for WS1).
+ *
+ * The generated SQLite SQL is byte-identical to what litedbmodel v1's SqliteSqlBuilder /
+ * `DBModel._buildSelectSQL` produce for equivalent queries (the golden bar). In
+ * particular:
+ *   - SELECT: `SELECT <cols> FROM <t>[ WHERE <c>][ GROUP BY <g>][ ORDER BY <o>][ LIMIT ?][ OFFSET ?]`
+ *   - INSERT: `INSERT INTO <t> (<cols>) VALUES (<vals>)[ RETURNING <r>]`
+ *   - UPDATE: `UPDATE <t> SET <a = ?, …> WHERE <c>[ RETURNING <r>]`
+ *   - DELETE: `DELETE FROM <t> WHERE <c>[ RETURNING <r>]`
+ *   - WHERE parts joined by ` AND ` (or ` OR ` for an OR group), equality `col = ?`,
+ *     IN-list `col IN (?, …)`, empty array → `1 = 0`, NULL → `col IS NULL`.
+ *
+ * ## Hard rule: closed Expression IR only
+ *
+ * Every param slot this compiler emits is an Expression IR node from bc's closed set
+ * (`PORTABLE_EXPR_OPERATORS`). NO litedbmodel-local opcode is ever invented. An
+ * un-lowerable predicate is the Raw SQL escape hatch's concern (spec §13), not a fake
+ * opcode. {@link compileSelect} et al. only construct `ref` / `coalesce` / etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileSelect = compileSelect;
+exports.compileInsert = compileInsert;
+exports.compileUpdate = compileUpdate;
+exports.compileDelete = compileDelete;
+const ir_1 = require("./ir");
+const dialect_1 = require("./dialect");
+const compile_dialect_1 = require("./compile-dialect");
+// ── WHERE fragment-tree lowering (spec §8) ────────────────────────────────────
+/** Lower one condition to a fragment (leaf) or nested tree, without a leading connector. */
+function lowerCondition(c) {
+    if (c.kind === 'group') {
+        const tree = {
+            connector: c.connector,
+            fragments: c.conditions.map(lowerCondition),
+        };
+        // A group's own SKIP guard is carried by wrapping it — but a FragmentTree has no
+        // `when`; represent a conditional group as a single-fragment tree is not expressible,
+        // so a guarded group is lowered as a leaf-less tree whose presence is the OR/AND of
+        // its members' presence (renderTree already drops it when empty). A group with its
+        // own skipWhen is not part of WS1's representative surface; reject loudly if used.
+        if (c.skipWhen !== undefined) {
+            throw new Error('a conditional (SKIP) group is not supported in WS1; guard the member conditions individually');
+        }
+        return tree;
+    }
+    let f;
+    switch (c.kind) {
+        case 'eq':
+            f = { always: true, sql: `${c.column} = ?`, params: [c.value] };
+            break;
+        case 'cmp':
+            f = { always: true, sql: `${c.column} ${c.op} ?`, params: [c.value] };
+            break;
+        case 'isNull':
+            f = { always: true, sql: `${c.column} IS NULL`, params: [] };
+            break;
+        case 'in':
+            // IN-list: single `(?)` slot expands at render time (spec §5). golden text:
+            // `col IN (?, ?, …)` with `, ` separators; empty array degenerates to `(NULL)`.
+            f = { always: true, sql: `${c.column} IN (?)`, params: [c.value], expand: 0 };
+            break;
+    }
+    if (c.skipWhen !== undefined) {
+        delete f.always;
+        f.when = c.skipWhen;
+    }
+    return f;
+}
+/** Build a top-level AND fragment tree from a condition list (null when empty). */
+function lowerWhere(conditions) {
+    if (conditions === undefined || conditions.length === 0)
+        return null;
+    return { connector: 'AND', fragments: conditions.map(lowerCondition) };
+}
+// ── CRUD compilers ────────────────────────────────────────────────────────────
+const assembly = (shape) => ({ shape });
+/**
+ * Compile a SELECT. Static params (LIMIT / OFFSET) sit AFTER the `{where}` splice, so
+ * they are emitted after the fragment params (dynamic-expansion spec §6).
+ */
+function compileSelect(desc) {
+    const cols = desc.select.length === 1 && desc.select[0] === '*' ? '*' : desc.select.join(', ');
+    let sql = `SELECT ${cols} FROM ${desc.table}`;
+    const where = lowerWhere(desc.where);
+    // The WHERE splice marker is emitted whenever a fragment tree exists (even if all
+    // fragments may skip — degeneration is a render-time decision, spec §3).
+    if (where !== null)
+        sql += ir_1.WHERE_SLOT;
+    if (desc.group !== undefined)
+        sql += ` GROUP BY ${desc.group}`;
+    if (desc.order !== undefined)
+        sql += ` ORDER BY ${desc.order}`;
+    const params = [];
+    if (desc.limit !== undefined) {
+        sql += ` LIMIT ?`;
+        params.push(desc.limit);
+    }
+    if (desc.offset !== undefined) {
+        sql += ` OFFSET ?`;
+        params.push(desc.offset);
+    }
+    return { component: 'Select', sql, where, params, assembly: assembly('items') };
+}
+/**
+ * Compile an INSERT (SQLite). All params are static (no WHERE); order = column order. The
+ * dialect-specific conflict/verb rendering is delegated to the SQLite {@link SQLITE} strategy
+ * ({@link compileInsertFor}) — the SAME dialect-parameterized compile the PG/MySQL Backend
+ * Compile uses (WS6), so SQLite is byte-for-byte unchanged and the other dialects diverge only
+ * where the v1 SqlBuilders diverge.
+ */
+function compileInsert(desc) {
+    return (0, compile_dialect_1.compileInsertFor)(dialect_1.SQLITE, desc);
+}
+/** Compile an UPDATE. SET params (static) precede the `{where}` splice (spec §6). */
+function compileUpdate(desc) {
+    const setCols = Object.keys(desc.set);
+    if (setCols.length === 0)
+        throw new Error('UPDATE requires at least one SET column');
+    const setClauses = setCols.map((c) => `${c} = ?`);
+    const params = setCols.map((c) => desc.set[c]);
+    const where = lowerWhere(desc.where);
+    if (where === null)
+        throw new Error('UPDATE requires conditions');
+    // The ` WHERE ` keyword is emitted by render() (it prepends ` WHERE ` when the fragment
+    // tree renders non-empty). Splice the marker directly after the SET clause.
+    let sql = `UPDATE ${desc.table} SET ${setClauses.join(', ')}${ir_1.WHERE_SLOT}`;
+    if (desc.returning !== undefined)
+        sql += ` RETURNING ${desc.returning.join(', ')}`;
+    return { component: 'Update', sql, where, params, assembly: assembly('items') };
+}
+/** Compile a DELETE. No static params before the WHERE (all params are conditions). */
+function compileDelete(desc) {
+    const where = lowerWhere(desc.where);
+    if (where === null)
+        throw new Error('DELETE requires conditions');
+    let sql = `DELETE FROM ${desc.table}${ir_1.WHERE_SLOT}`;
+    if (desc.returning !== undefined)
+        sql += ` RETURNING ${desc.returning.join(', ')}`;
+    return { component: 'Delete', sql, where, params: [], assembly: assembly('items') };
+}
+//# sourceMappingURL=compile-sqlite.js.map

package/dist/scp/compile-sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-sqlite.js","sourceRoot":"","sources":["../../src/scp/compile-sqlite.ts"],"names":[],"mappings":"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"}

package/dist/scp/dialect.d.ts

@@ -0,0 +1,141 @@
+/**
+ * litedbmodel v2 SCP — dialect strategy table (WS6, #26; spec §4/§5/§8/§10).
+ *
+ * The SINGLE SOURCE OF TRUTH for every SQL-dialect difference the Backend Compile + render
+ * pipeline needs. The dialect axis is compiled ONCE, TS-side (spec §10: "方言軸はコンパイル時
+ * に TS 側で1回検証"). This module encodes the differences as a closed strategy record — NO
+ * scattered `?:` in the engine code (the hard rule). A backend compile / renderer asks the
+ * {@link Dialect} for the dialect-specific text and never branches on the dialect name inline.
+ *
+ * ## What actually differs (verified against the v1 SqlBuilders — the golden bar)
+ *
+ * For the CRUD + write-tx + relation SQL the SCP Backend Compile emits (single-row VALUES,
+ * `?` placeholders, `col = ?` WHERE, `col IN (?, …)`), the dialect surface is small and
+ * closed:
+ *
+ *   - **INSERT conflict clause**: SQLite `INSERT OR IGNORE … ` / `… ON CONFLICT (cols) DO
+ *     UPDATE SET c = excluded.c`; Postgres `… ON CONFLICT (cols) DO NOTHING` / `… DO UPDATE
+ *     SET c = EXCLUDED.c`; MySQL `INSERT IGNORE …` / `… ON DUPLICATE KEY UPDATE c = VALUES(c)`.
+ *     These are byte-identical to `SqliteSqlBuilder` / `PostgresSqlBuilder` / `MysqlSqlBuilder`
+ *     `buildInsert` for the single-record case (see the WS6 dialect-golden test).
+ *   - **Bare `ON CONFLICT DO NOTHING`** (no column list — the gate-first idempotency/unique
+ *     guard INSERTs of the write-tx plan, spec §6): SQLite/Postgres emit `ON CONFLICT DO
+ *     NOTHING`; MySQL emits `INSERT IGNORE`.
+ *   - **Placeholder style**: all dialects author with `?`; Postgres converts `?`→`$1,$2,…` in a
+ *     final left-to-right one-pass AFTER the SQL text is fully assembled (spec §8 — the
+ *     number-reassignment problem is designed out because the pass runs once over the final
+ *     flat text). SQLite/MySQL keep `?`.
+ *
+ * Everything else (SELECT/UPDATE/DELETE skeletons, `col = ?`, `col IN (?, …)` expansion, the
+ * fragment tree, RETURNING for SQLite/Postgres) is identical text across dialects, so it is
+ * NOT part of the strategy — only the genuine divergences live here.
+ *
+ * ## DB behavior differences beyond SQL text (spec §13) — closeable-by-convention line
+ *
+ * SQL-text identity does not guarantee identical DB behavior (NULL ordering, collation,
+ * timezone). Per spec §13, those are closed "by dialect-compile-time convention" only within
+ * the closeable line. WS6 encodes the ONE convention that is mechanically closeable in the
+ * compiled SQL text: deterministic NULL ordering for an `ORDER BY … NULLS` requirement
+ * ({@link Dialect.orderByNulls}). Collation / timezone / float semantics are OUT OF SCOPE
+ * (documented, not silently defaulted).
+ */
+/** The SQL dialects the Backend Compile targets (spec §4 breadth: PG/MySQL/SQLite). */
+export type DialectName = 'sqlite' | 'postgres' | 'mysql';
+/** An INSERT conflict action (dialect-neutral intent; the dialect renders the clause). */
+export type ConflictAction = 'ignore' | {
+    readonly updateColumns: readonly string[];
+};
+/**
+ * A dialect strategy: the closed set of dialect-specific renderings the Backend Compile +
+ * render pipeline consumes. One frozen record per dialect (the SSoT). Every method is a pure
+ * text producer — no side effects, no hidden fallback.
+ */
+export interface Dialect {
+    readonly name: DialectName;
+    /**
+     * Render an INSERT's optional conflict clause, appended after `… VALUES (…)`.
+     *
+     * @param conflictColumns the conflict-target columns (`ON CONFLICT (a, b)`), or an empty
+     *   array for a bare conflict target (the write-tx guard INSERTs — spec §6).
+     * @param action `'ignore'` (do-nothing) or an upsert with the update-column list.
+     * @param insertColumns the INSERT's column list (needed for the `VALUES(col)` / `EXCLUDED.col`
+     *   SET-clause rendering when `updateColumns` is `'all'` at the call site — the caller passes
+     *   the resolved list, so this only needs the resolved update columns).
+     */
+    insertConflictClause(conflictColumns: readonly string[], action: ConflictAction): string;
+    /**
+     * For MySQL, an `ignore` conflict is expressed on the INSERT VERB (`INSERT IGNORE INTO`),
+     * not as a trailing clause; SQLite uses `INSERT OR IGNORE INTO`; Postgres uses a plain
+     * `INSERT INTO` + a trailing `ON CONFLICT … DO NOTHING`. This returns the INSERT verb+prefix
+     * up to and including `INTO` for the `ignore` case, and the plain `INSERT INTO` otherwise.
+     */
+    insertVerb(action: ConflictAction | undefined): string;
+    /**
+     * Whether this dialect's conflict `ignore` is a trailing clause (Postgres) rather than an
+     * INSERT-verb modifier (SQLite `OR IGNORE`, MySQL `IGNORE`). Drives whether
+     * {@link insertConflictClause} emits text for the `ignore` case.
+     */
+    readonly ignoreIsTrailingClause: boolean;
+    /**
+     * Render a bare do-nothing GUARD INSERT — the gate-first idempotency/unique guard of the
+     * write-tx plan (spec §6): `INSERT INTO <t> (<cols>) VALUES (<ph>)` + a do-nothing conflict
+     * on ANY unique constraint (no column target). SQLite/Postgres emit a trailing
+     * `… ON CONFLICT DO NOTHING`; MySQL emits `INSERT IGNORE INTO … VALUES (…)`.
+     *
+     * This is DISTINCT from the CRUD `ignore` path ({@link insertVerb} + {@link insertConflictClause}),
+     * which mirrors the v1 SqlBuilders (SQLite uses the `INSERT OR IGNORE` verb there). The guard
+     * form is SCP-internal and its SQLite golden is the trailing `ON CONFLICT DO NOTHING` (WS5),
+     * so the two contexts render differently ON SQLITE and are kept as separate strategy methods
+     * rather than one branch.
+     *
+     * @param table the guard table.
+     * @param columns the guard row's columns (in order).
+     * @param placeholders the pre-joined placeholder list (`"?, ?, ?"`).
+     */
+    guardInsert(table: string, columns: readonly string[], placeholders: string): string;
+    /**
+     * Convert the fully-assembled, param-flattened SQL text's `?` placeholders to this dialect's
+     * final placeholder style. SQLite/MySQL: identity (keep `?`). Postgres: a single left-to-right
+     * pass replacing the Nth `?` with `$N` (spec §8 final one-pass). This runs ONCE over the final
+     * text, so there is no number-reassignment problem.
+     */
+    finalizePlaceholders(sql: string): string;
+    /**
+     * Deterministic NULL ordering for an `ORDER BY <expr> <dir>` term when the model requires it
+     * (spec §13 "`ORDER BY … NULLS` 強制"). Postgres supports `NULLS FIRST/LAST` natively; SQLite
+     * (3.30+) also supports it; MySQL does NOT, so the convention is emulated with a leading
+     * `<expr> IS NULL` sort key. Returns the full ORDER BY term text.
+     */
+    orderByNulls(expr: string, dir: 'ASC' | 'DESC', nulls: 'FIRST' | 'LAST'): string;
+}
+/**
+ * Replace each `?` placeholder in a fully-assembled SQL string with `$1, $2, …` left-to-right
+ * (Postgres). This is the spec §8 "最終1パス" conversion: it runs ONCE over the final flat SQL
+ * text, so placeholder numbering is a plain running counter — the number-reassignment problem
+ * cannot reappear (there is no per-fragment renumbering). Every `?` is a bound param position
+ * (the render pipeline never emits a literal `?` inside a string literal — values are always
+ * parameterized), so a naive scan is correct for the compiled surface.
+ */
+export declare function toDollarPlaceholders(sql: string): string;
+/**
+ * SQLite. `ignore` is an INSERT-verb modifier (`INSERT OR IGNORE INTO`); upsert uses
+ * `ON CONFLICT (cols) DO UPDATE SET c = excluded.c`. Placeholders stay `?`. NULL ordering uses
+ * the native `NULLS FIRST/LAST` (SQLite 3.30+).
+ */
+export declare const SQLITE: Dialect;
+/**
+ * Postgres. `ignore` is a TRAILING clause (`… ON CONFLICT (cols) DO NOTHING`); upsert uses
+ * `ON CONFLICT (cols) DO UPDATE SET c = EXCLUDED.c`. Placeholders are converted `?`→`$N` in the
+ * final one-pass. NULL ordering uses native `NULLS FIRST/LAST`.
+ */
+export declare const POSTGRES: Dialect;
+/**
+ * MySQL. `ignore` is an INSERT-verb modifier (`INSERT IGNORE INTO`); upsert uses
+ * `… ON DUPLICATE KEY UPDATE c = VALUES(c)` (no conflict-column target — MySQL keys off any
+ * unique index). Placeholders stay `?`. NULL ordering is emulated with a leading
+ * `<expr> IS NULL` sort key (MySQL has no `NULLS FIRST/LAST`).
+ */
+export declare const MYSQL: Dialect;
+/** Look up a dialect strategy by name (throws on an unknown dialect — no silent default). */
+export declare function dialectFor(name: DialectName): Dialect;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/scp/dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/scp/dialect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAE1D,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEtF;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B;;;;;;;;;OASG;IACH,oBAAoB,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC;IAEzF;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;IAEvD;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;IAEzC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAErF;;;;;OAKG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1C;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;CAClF;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYxD;AAwCD;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,OAoBnB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,OAkBrB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,OA0BlB,CAAC;AASH,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAMrD"}

package/dist/scp/dialect.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — dialect strategy table (WS6, #26; spec §4/§5/§8/§10).
+ *
+ * The SINGLE SOURCE OF TRUTH for every SQL-dialect difference the Backend Compile + render
+ * pipeline needs. The dialect axis is compiled ONCE, TS-side (spec §10: "方言軸はコンパイル時
+ * に TS 側で1回検証"). This module encodes the differences as a closed strategy record — NO
+ * scattered `?:` in the engine code (the hard rule). A backend compile / renderer asks the
+ * {@link Dialect} for the dialect-specific text and never branches on the dialect name inline.
+ *
+ * ## What actually differs (verified against the v1 SqlBuilders — the golden bar)
+ *
+ * For the CRUD + write-tx + relation SQL the SCP Backend Compile emits (single-row VALUES,
+ * `?` placeholders, `col = ?` WHERE, `col IN (?, …)`), the dialect surface is small and
+ * closed:
+ *
+ *   - **INSERT conflict clause**: SQLite `INSERT OR IGNORE … ` / `… ON CONFLICT (cols) DO
+ *     UPDATE SET c = excluded.c`; Postgres `… ON CONFLICT (cols) DO NOTHING` / `… DO UPDATE
+ *     SET c = EXCLUDED.c`; MySQL `INSERT IGNORE …` / `… ON DUPLICATE KEY UPDATE c = VALUES(c)`.
+ *     These are byte-identical to `SqliteSqlBuilder` / `PostgresSqlBuilder` / `MysqlSqlBuilder`
+ *     `buildInsert` for the single-record case (see the WS6 dialect-golden test).
+ *   - **Bare `ON CONFLICT DO NOTHING`** (no column list — the gate-first idempotency/unique
+ *     guard INSERTs of the write-tx plan, spec §6): SQLite/Postgres emit `ON CONFLICT DO
+ *     NOTHING`; MySQL emits `INSERT IGNORE`.
+ *   - **Placeholder style**: all dialects author with `?`; Postgres converts `?`→`$1,$2,…` in a
+ *     final left-to-right one-pass AFTER the SQL text is fully assembled (spec §8 — the
+ *     number-reassignment problem is designed out because the pass runs once over the final
+ *     flat text). SQLite/MySQL keep `?`.
+ *
+ * Everything else (SELECT/UPDATE/DELETE skeletons, `col = ?`, `col IN (?, …)` expansion, the
+ * fragment tree, RETURNING for SQLite/Postgres) is identical text across dialects, so it is
+ * NOT part of the strategy — only the genuine divergences live here.
+ *
+ * ## DB behavior differences beyond SQL text (spec §13) — closeable-by-convention line
+ *
+ * SQL-text identity does not guarantee identical DB behavior (NULL ordering, collation,
+ * timezone). Per spec §13, those are closed "by dialect-compile-time convention" only within
+ * the closeable line. WS6 encodes the ONE convention that is mechanically closeable in the
+ * compiled SQL text: deterministic NULL ordering for an `ORDER BY … NULLS` requirement
+ * ({@link Dialect.orderByNulls}). Collation / timezone / float semantics are OUT OF SCOPE
+ * (documented, not silently defaulted).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MYSQL = exports.POSTGRES = exports.SQLITE = void 0;
+exports.toDollarPlaceholders = toDollarPlaceholders;
+exports.dialectFor = dialectFor;
+// ── `?`→`$N` final one-pass (Postgres only) ───────────────────────────────────
+/**
+ * Replace each `?` placeholder in a fully-assembled SQL string with `$1, $2, …` left-to-right
+ * (Postgres). This is the spec §8 "最終1パス" conversion: it runs ONCE over the final flat SQL
+ * text, so placeholder numbering is a plain running counter — the number-reassignment problem
+ * cannot reappear (there is no per-fragment renumbering). Every `?` is a bound param position
+ * (the render pipeline never emits a literal `?` inside a string literal — values are always
+ * parameterized), so a naive scan is correct for the compiled surface.
+ */
+function toDollarPlaceholders(sql) {
+    let n = 0;
+    let out = '';
+    for (const ch of sql) {
+        if (ch === '?') {
+            n += 1;
+            out += `$${n}`;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+// ── Shared conflict-clause rendering (parameterized by the SET-assignment form) ─
+/**
+ * Render the trailing conflict clause for the "has a column target" upsert/ignore forms shared
+ * by SQLite and Postgres (`ON CONFLICT (cols) DO NOTHING | DO UPDATE SET …`). MySQL overrides
+ * with its `ON DUPLICATE KEY UPDATE` form. `excludedRef` produces the per-column right-hand side
+ * (`excluded.c` for SQLite, `EXCLUDED.c` for Postgres).
+ */
+function onConflictClause(conflictColumns, action, excludedRef) {
+    const target = conflictColumns.length > 0 ? ` (${conflictColumns.join(', ')})` : '';
+    if (action === 'ignore') {
+        return ` ON CONFLICT${target} DO NOTHING`;
+    }
+    const sets = action.updateColumns.map((c) => `${c} = ${excludedRef(c)}`);
+    return ` ON CONFLICT${target} DO UPDATE SET ${sets.join(', ')}`;
+}
+/**
+ * Render a bare do-nothing guard INSERT. `trailingDoNothing` dialects (SQLite/Postgres) emit
+ * `INSERT INTO … VALUES (…) ON CONFLICT DO NOTHING`; MySQL emits `INSERT IGNORE INTO … VALUES (…)`.
+ */
+function guardInsertText(table, columns, placeholders, form) {
+    const head = form === 'insertIgnore' ? 'INSERT IGNORE INTO' : 'INSERT INTO';
+    const tail = form === 'trailingDoNothing' ? ' ON CONFLICT DO NOTHING' : '';
+    return `${head} ${table} (${columns.join(', ')}) VALUES (${placeholders})${tail}`;
+}
+// ── The three frozen dialect strategies (SSoT) ─────────────────────────────────
+/**
+ * SQLite. `ignore` is an INSERT-verb modifier (`INSERT OR IGNORE INTO`); upsert uses
+ * `ON CONFLICT (cols) DO UPDATE SET c = excluded.c`. Placeholders stay `?`. NULL ordering uses
+ * the native `NULLS FIRST/LAST` (SQLite 3.30+).
+ */
+exports.SQLITE = Object.freeze({
+    name: 'sqlite',
+    ignoreIsTrailingClause: false,
+    insertVerb(action) {
+        return action === 'ignore' ? 'INSERT OR IGNORE INTO' : 'INSERT INTO';
+    },
+    insertConflictClause(conflictColumns, action) {
+        // `ignore` is handled by the verb (`INSERT OR IGNORE`), so no trailing clause for it.
+        if (action === 'ignore')
+            return '';
+        return onConflictClause(conflictColumns, action, (c) => `excluded.${c}`);
+    },
+    guardInsert(table, columns, placeholders) {
+        return guardInsertText(table, columns, placeholders, 'trailingDoNothing');
+    },
+    finalizePlaceholders(sql) {
+        return sql;
+    },
+    orderByNulls(expr, dir, nulls) {
+        return `${expr} ${dir} NULLS ${nulls}`;
+    },
+});
+/**
+ * Postgres. `ignore` is a TRAILING clause (`… ON CONFLICT (cols) DO NOTHING`); upsert uses
+ * `ON CONFLICT (cols) DO UPDATE SET c = EXCLUDED.c`. Placeholders are converted `?`→`$N` in the
+ * final one-pass. NULL ordering uses native `NULLS FIRST/LAST`.
+ */
+exports.POSTGRES = Object.freeze({
+    name: 'postgres',
+    ignoreIsTrailingClause: true,
+    insertVerb(_action) {
+        return 'INSERT INTO';
+    },
+    insertConflictClause(conflictColumns, action) {
+        return onConflictClause(conflictColumns, action, (c) => `EXCLUDED.${c}`);
+    },
+    guardInsert(table, columns, placeholders) {
+        return guardInsertText(table, columns, placeholders, 'trailingDoNothing');
+    },
+    finalizePlaceholders(sql) {
+        return toDollarPlaceholders(sql);
+    },
+    orderByNulls(expr, dir, nulls) {
+        return `${expr} ${dir} NULLS ${nulls}`;
+    },
+});
+/**
+ * MySQL. `ignore` is an INSERT-verb modifier (`INSERT IGNORE INTO`); upsert uses
+ * `… ON DUPLICATE KEY UPDATE c = VALUES(c)` (no conflict-column target — MySQL keys off any
+ * unique index). Placeholders stay `?`. NULL ordering is emulated with a leading
+ * `<expr> IS NULL` sort key (MySQL has no `NULLS FIRST/LAST`).
+ */
+exports.MYSQL = Object.freeze({
+    name: 'mysql',
+    ignoreIsTrailingClause: false,
+    insertVerb(action) {
+        return action === 'ignore' ? 'INSERT IGNORE INTO' : 'INSERT INTO';
+    },
+    insertConflictClause(_conflictColumns, action) {
+        if (action === 'ignore')
+            return ''; // handled by the `INSERT IGNORE` verb
+        const sets = action.updateColumns.map((c) => `${c} = VALUES(${c})`);
+        return ` ON DUPLICATE KEY UPDATE ${sets.join(', ')}`;
+    },
+    guardInsert(table, columns, placeholders) {
+        return guardInsertText(table, columns, placeholders, 'insertIgnore');
+    },
+    finalizePlaceholders(sql) {
+        return sql;
+    },
+    orderByNulls(expr, dir, nulls) {
+        // MySQL: emulate NULLS FIRST/LAST with a leading `IS NULL` key.
+        //   NULLS FIRST → `expr IS NULL DESC, expr <dir>` (nulls sort as 1, before 0... wait)
+        // In MySQL, NULL sorts LOWEST by default. `expr IS NULL` is 1 for null, 0 otherwise.
+        //   NULLS FIRST: nulls must come first → order the IS-NULL flag DESC (1 before 0).
+        //   NULLS LAST:  nulls must come last  → order the IS-NULL flag ASC  (0 before 1).
+        const flagDir = nulls === 'FIRST' ? 'DESC' : 'ASC';
+        return `${expr} IS NULL ${flagDir}, ${expr} ${dir}`;
+    },
+});
+/** Resolve a {@link DialectName} to its frozen {@link Dialect} strategy (fail-closed). */
+const DIALECTS = Object.freeze({
+    sqlite: exports.SQLITE,
+    postgres: exports.POSTGRES,
+    mysql: exports.MYSQL,
+});
+/** Look up a dialect strategy by name (throws on an unknown dialect — no silent default). */
+function dialectFor(name) {
+    const d = DIALECTS[name];
+    if (d === undefined) {
+        throw new Error(`scp dialect: unknown dialect '${String(name)}' (known: ${Object.keys(DIALECTS).join(', ')})`);
+    }
+    return d;
+}
+//# sourceMappingURL=dialect.js.map

package/dist/scp/dialect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.js","sourceRoot":"","sources":["../../src/scp/dialect.ts"],"names":[],"mappings":"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"}

package/dist/scp/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * litedbmodel v2 SCP — Error Mapping (WS3, #23; spec §11 item 5).
+ *
+ * Maps a SQLite driver error (better-sqlite3 `SqliteError`, carrying a `SQLITE_*` `code`)
+ * to an SCP {@link SqlFailure}: a structured Failure with a stable `kind` and the bc
+ * Execution-Plan {@link PolicyKind} the runtime honors (fail / retry / continue). The
+ * handler returns `{ error }` to bc's `runBehavior`; a `fail`-policy node re-throws through
+ * `runPlan` (`OP_FAILED`), so the driver surfaces this structured failure at the boundary.
+ *
+ * The mapping is closed and explicit (no silent catch-all that hides a driver error): an
+ * unrecognized SQLite code maps to `kind: 'driver_error'` with `policy: 'fail'` — loud, and
+ * carrying the original code + message for diagnosis.
+ */
+import type { PolicyKind } from 'behavior-contracts';
+/** The SCP failure kinds litedbmodel maps SQL driver errors to (spec §11 item 5). */
+export type SqlFailureKind = 'constraint_violation' | 'foreign_key_violation' | 'retryable' | 'driver_error';
+/**
+ * A mapped SCP failure: the SCP `kind`, the honored bc `PolicyKind`, the original SQLite
+ * `code`, and a human message. Thrown at the runtime boundary (or carried as `{error}`
+ * into `runBehavior` for Policy-Kind interpretation by `runPlan`).
+ */
+export declare class SqlFailure extends Error {
+    readonly kind: SqlFailureKind;
+    readonly policy: PolicyKind;
+    readonly sqliteCode: string | undefined;
+    constructor(kind: SqlFailureKind, policy: PolicyKind, sqliteCode: string | undefined, message: string);
+}
+/**
+ * Map a caught driver error to an {@link SqlFailure}. The `SQLITE_CONSTRAINT_*` family maps
+ * to constraint / FK kinds (Policy `fail` — a data conflict is not retryable); the
+ * `SQLITE_BUSY` / `SQLITE_LOCKED` family maps to `retryable` (Policy `retry`). Anything else
+ * (including a non-SQLite error) maps to `driver_error` (Policy `fail`), preserving the
+ * original message.
+ */
+export declare function mapSqliteError(e: unknown): SqlFailure;
+//# sourceMappingURL=errors.d.ts.map

package/dist/scp/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/scp/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,qFAAqF;AACrF,MAAM,MAAM,cAAc,GACtB,sBAAsB,GACtB,uBAAuB,GACvB,WAAW,GACX,cAAc,CAAC;AAEnB;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAEjC,QAAQ,CAAC,IAAI,EAAE,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;gBAF9B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,GAAG,SAAS,EACvC,OAAO,EAAE,MAAM;CAKlB;AAYD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,CAqBrD"}

package/dist/scp/errors.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — Error Mapping (WS3, #23; spec §11 item 5).
+ *
+ * Maps a SQLite driver error (better-sqlite3 `SqliteError`, carrying a `SQLITE_*` `code`)
+ * to an SCP {@link SqlFailure}: a structured Failure with a stable `kind` and the bc
+ * Execution-Plan {@link PolicyKind} the runtime honors (fail / retry / continue). The
+ * handler returns `{ error }` to bc's `runBehavior`; a `fail`-policy node re-throws through
+ * `runPlan` (`OP_FAILED`), so the driver surfaces this structured failure at the boundary.
+ *
+ * The mapping is closed and explicit (no silent catch-all that hides a driver error): an
+ * unrecognized SQLite code maps to `kind: 'driver_error'` with `policy: 'fail'` — loud, and
+ * carrying the original code + message for diagnosis.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqlFailure = void 0;
+exports.mapSqliteError = mapSqliteError;
+/**
+ * A mapped SCP failure: the SCP `kind`, the honored bc `PolicyKind`, the original SQLite
+ * `code`, and a human message. Thrown at the runtime boundary (or carried as `{error}`
+ * into `runBehavior` for Policy-Kind interpretation by `runPlan`).
+ */
+class SqlFailure extends Error {
+    kind;
+    policy;
+    sqliteCode;
+    constructor(kind, policy, sqliteCode, message) {
+        super(message);
+        this.kind = kind;
+        this.policy = policy;
+        this.sqliteCode = sqliteCode;
+        this.name = 'SqlFailure';
+    }
+}
+exports.SqlFailure = SqlFailure;
+/** True if `e` looks like a better-sqlite3 `SqliteError` (has a `SQLITE_*` string `code`). */
+function isSqliteError(e) {
+    return (typeof e === 'object' &&
+        e !== null &&
+        typeof e.code === 'string' &&
+        e.code.startsWith('SQLITE_'));
+}
+/**
+ * Map a caught driver error to an {@link SqlFailure}. The `SQLITE_CONSTRAINT_*` family maps
+ * to constraint / FK kinds (Policy `fail` — a data conflict is not retryable); the
+ * `SQLITE_BUSY` / `SQLITE_LOCKED` family maps to `retryable` (Policy `retry`). Anything else
+ * (including a non-SQLite error) maps to `driver_error` (Policy `fail`), preserving the
+ * original message.
+ */
+function mapSqliteError(e) {
+    if (!isSqliteError(e)) {
+        const message = e instanceof Error ? e.message : String(e);
+        return new SqlFailure('driver_error', 'fail', undefined, `non-SQLite driver error: ${message}`);
+    }
+    const { code, message } = e;
+    // The message embeds the `SQLITE_*` code so it survives being wrapped by bc's `runPlan`
+    // (`OP_FAILED: <handler message>`); the runtime re-maps from it to re-surface the
+    // structured SqlFailure (kind / policy / code) at the boundary.
+    const tagged = `[${code}] ${message}`;
+    if (code === 'SQLITE_CONSTRAINT_FOREIGNKEY') {
+        return new SqlFailure('foreign_key_violation', 'fail', code, tagged);
+    }
+    if (code.startsWith('SQLITE_CONSTRAINT')) {
+        // UNIQUE / PRIMARYKEY / CHECK / NOTNULL / … — a durable constraint conflict.
+        return new SqlFailure('constraint_violation', 'fail', code, tagged);
+    }
+    if (code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED') {
+        return new SqlFailure('retryable', 'retry', code, tagged);
+    }
+    return new SqlFailure('driver_error', 'fail', code, tagged);
+}
+//# sourceMappingURL=errors.js.map

package/dist/scp/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/scp/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AA6CH,wCAqBC;AAvDD;;;;GAIG;AACH,MAAa,UAAW,SAAQ,KAAK;IAExB;IACA;IACA;IAHX,YACW,IAAoB,EACpB,MAAkB,EAClB,UAA8B,EACvC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QALN,SAAI,GAAJ,IAAI,CAAgB;QACpB,WAAM,GAAN,MAAM,CAAY;QAClB,eAAU,GAAV,UAAU,CAAoB;QAIvC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAVD,gCAUC;AAED,8FAA8F;AAC9F,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,OAAQ,CAAwB,CAAC,IAAI,KAAK,QAAQ;QACjD,CAAsB,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CACnD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,CAAU;IACvC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC3D,OAAO,IAAI,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,4BAA4B,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAC5B,wFAAwF;IACxF,kFAAkF;IAClF,gEAAgE;IAChE,MAAM,MAAM,GAAG,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;IACtC,IAAI,IAAI,KAAK,8BAA8B,EAAE,CAAC;QAC5C,OAAO,IAAI,UAAU,CAAC,uBAAuB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACzC,6EAA6E;QAC7E,OAAO,IAAI,UAAU,CAAC,sBAAsB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,IAAI,KAAK,aAAa,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;QACvD,OAAO,IAAI,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC"}