@harperfast/harper 5.2.0-alpha.6 → 5.2.0-beta.1

package/dist/sqlEngine/binder/bind.js

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * Binder.
+ *
+ * Resolves the table references in a SelectNode to concrete Table classes via
+ * core/resources/databases.ts.
+ *
+ * Single-table SELECT (phase 1-2): fills `boundTable` with primaryKey +
+ * attribute names so downstream rules can validate columns. Column references
+ * keep their bare names and rows flow through the pipeline keyed by bare
+ * attribute name.
+ *
+ * Multi-table SELECT (phase 3, joins): additionally binds every joined table
+ * into an ordered `scope`, and resolves every column reference to the canonical
+ * alias of its owning table (mutating `column.table` in place). Ambiguous or
+ * unknown qualified references throw EngineUnsupportedError. Join rows flow
+ * through the pipeline keyed by `<alias>.<attribute>` (see expressions/compile
+ * `qualified` mode and physical/PhysicalQualify).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = void 0;
+exports._setDatabasesLoader = _setDatabasesLoader;
+exports.bind = bind;
+exports.bindSelect = bindSelect;
+const errors_ts_1 = require("../errors.js");
+let _databasesLoader = null;
+/**
+ * Override hook for tests. Restored to default by passing null.
+ */
+function _setDatabasesLoader(loader) {
+    _databasesLoader = loader;
+}
+function loadDatabases() {
+    if (_databasesLoader)
+        return _databasesLoader();
+    const mod = require('../../resources/databases.js');
+    return mod.getDatabases();
+}
+function bind(stmt, _ctx) {
+    switch (stmt.kind) {
+        case 'select':
+            return bindSelect(stmt);
+        case 'insert':
+            return bindInsert(stmt);
+        case 'update':
+            return bindUpdate(stmt);
+        case 'delete':
+            return bindDelete(stmt);
+        default:
+            throw new errors_ts_1.EngineUnsupportedError(`bind: unsupported statement kind`);
+    }
+}
+/**
+ * Mutations are single-table. We resolve the target table to a BoundTable (the
+ * Resource class plus primaryKey/attributes) and leave column refs bare — the
+ * write executor evaluates assignment/value expressions against bare-keyed rows,
+ * exactly like the single-table SELECT path.
+ */
+function bindInsert(stmt) {
+    const boundTable = bindTableRef(stmt.table, loadDatabases());
+    return { ...stmt, table: { ...stmt.table, database: boundTable.database }, boundTable };
+}
+function bindUpdate(stmt) {
+    const boundTable = bindTableRef(stmt.table, loadDatabases());
+    // SET on the primary key can't be honored by Table.patch (identity is the call
+    // argument, not the payload) — reporting the row as updated would be a false
+    // success. Reject so `auto` falls back to legacy, which declines the re-key.
+    if (boundTable.primaryKey && stmt.assignments.some((a) => a.column === boundTable.primaryKey)) {
+        throw new errors_ts_1.EngineUnsupportedError(`UPDATE cannot change the primary key column "${boundTable.primaryKey}"`);
+    }
+    return { ...stmt, table: { ...stmt.table, database: boundTable.database }, boundTable };
+}
+function bindDelete(stmt) {
+    const boundTable = bindTableRef(stmt.table, loadDatabases());
+    return { ...stmt, table: { ...stmt.table, database: boundTable.database }, boundTable };
+}
+function bindSelect(stmt) {
+    const databases = loadDatabases();
+    const fromTable = bindTableRef(stmt.from, databases);
+    const scope = [fromTable];
+    for (const join of stmt.joins) {
+        scope.push(bindTableRef(join.table, databases));
+    }
+    const qualified = stmt.joins.length > 0;
+    if (qualified) {
+        // Distinct effective aliases are required: the join row model keys columns
+        // by `<alias>.<attr>`, so two tables sharing an alias would collide and
+        // overwrite each other on merge.
+        const seen = new Set();
+        for (const t of scope) {
+            if (seen.has(t.effectiveAlias)) {
+                throw new errors_ts_1.EngineUnsupportedError(`duplicate table alias "${t.effectiveAlias}" in join; give each joined table a distinct alias`);
+            }
+            seen.add(t.effectiveAlias);
+        }
+    }
+    if (qualified) {
+        // Resolve every column reference to a canonical alias, in place.
+        resolveColumnsInSelect(stmt, scope);
+    }
+    return {
+        ...stmt,
+        from: { ...stmt.from, database: fromTable.database },
+        boundTable: fromTable,
+        scope,
+        qualified,
+    };
+}
+function bindTableRef(ref, databases) {
+    const databaseName = ref.database || pickDefaultDatabase(databases, ref.table);
+    const dbEntry = databases[databaseName];
+    if (!dbEntry) {
+        throw new errors_ts_1.EngineUnsupportedError(`database "${databaseName}" not found`);
+    }
+    const resource = dbEntry[ref.table];
+    if (!resource) {
+        throw new errors_ts_1.EngineUnsupportedError(`table "${databaseName}.${ref.table}" not found`);
+    }
+    const r = resource;
+    const primaryKey = r.primaryKey;
+    const indices = r.indices ?? {};
+    // indexNulls lives on both the attribute descriptor and the index dbi
+    // (databases.ts sets each) — honor either.
+    const attributes = (r.attributes ?? []).map((a) => ({
+        name: a.name,
+        indexed: !!a.indexed || !!indices[a.name] || a.name === primaryKey,
+        isPrimaryKey: a.name === primaryKey,
+        indexNulls: a.name !== primaryKey &&
+            (!!a.indexNulls || !!indices[a.name]?.indexNulls),
+    }));
+    return {
+        database: databaseName,
+        table: ref.table,
+        alias: ref.alias,
+        effectiveAlias: ref.alias ?? ref.table,
+        primaryKey,
+        attributes,
+        resource,
+    };
+}
+function pickDefaultDatabase(databases, tableName) {
+    const matches = [];
+    for (const dbName of Object.keys(databases)) {
+        if (databases[dbName]?.[tableName])
+            matches.push(dbName);
+    }
+    if (matches.length === 0) {
+        throw new errors_ts_1.EngineUnsupportedError(`table "${tableName}" not found in any database`);
+    }
+    if (matches.length > 1) {
+        throw new errors_ts_1.EngineUnsupportedError(`table "${tableName}" exists in multiple databases (${matches.join(', ')}); qualify the schema`);
+    }
+    return matches[0];
+}
+// ---------------------------------------------------------------------------
+// Column resolution for join queries
+// ---------------------------------------------------------------------------
+function resolveColumnsInSelect(stmt, scope) {
+    for (const p of stmt.projections)
+        resolveColumns(p.expr, scope);
+    // Each join's ON sees only the tables in scope at that point: FROM plus the
+    // joins up to and including this one (scope[0..i+1]). Resolving against the
+    // full scope would let an ON reference a not-yet-joined table or be falsely
+    // flagged ambiguous against one.
+    for (let i = 0; i < stmt.joins.length; i++) {
+        const j = stmt.joins[i];
+        if (j.on)
+            resolveColumns(j.on, scope.slice(0, i + 2));
+    }
+    if (stmt.where)
+        resolveColumns(stmt.where, scope);
+    if (stmt.groupBy)
+        for (const g of stmt.groupBy)
+            resolveColumns(g, scope);
+    if (stmt.having)
+        resolveColumns(stmt.having, scope);
+    if (stmt.orderBy)
+        for (const o of stmt.orderBy)
+            resolveColumns(o.expr, scope);
+}
+/** Resolves a qualifier string (alias or table name) to the canonical alias. */
+function resolveQualifier(qualifier, scope) {
+    // Exact effective-alias match always wins (it is unique — duplicates are
+    // rejected at bind time).
+    const byAlias = scope.find((t) => t.effectiveAlias === qualifier);
+    if (byAlias)
+        return byAlias;
+    // Fall back to base-table-name qualification (e.g. `dev.user.col` where the
+    // table is unaliased). In a self-join the same base name appears more than
+    // once; matching the first silently mis-binds, so reject as ambiguous.
+    const byTable = scope.filter((t) => t.table === qualifier);
+    if (byTable.length > 1) {
+        throw new errors_ts_1.EngineUnsupportedError(`table qualifier "${qualifier}" is ambiguous across ${byTable
+            .map((t) => t.effectiveAlias)
+            .join(', ')}; qualify columns by alias`);
+    }
+    return byTable[0];
+}
+function resolveColumns(expr, scope) {
+    switch (expr.kind) {
+        case 'column': {
+            if (expr.table) {
+                const t = resolveQualifier(expr.table, scope);
+                if (!t) {
+                    throw new errors_ts_1.EngineUnsupportedError(`unknown table qualifier "${expr.table}" for column "${expr.name}"`);
+                }
+                expr.table = t.effectiveAlias;
+                return;
+            }
+            // Unqualified: bind to the unique table that declares this attribute.
+            const owners = scope.filter((t) => t.attributes.some((a) => a.name === expr.name));
+            if (owners.length === 1) {
+                expr.table = owners[0].effectiveAlias;
+            }
+            else if (owners.length > 1) {
+                throw new errors_ts_1.EngineUnsupportedError(`column "${expr.name}" is ambiguous across ${owners.map((o) => o.effectiveAlias).join(', ')}; qualify it`);
+            }
+            else if (scope.length === 1) {
+                // Single-table query: an undeclared attribute (Harper tables are
+                // schemaless) binds to the only table.
+                expr.table = scope[0].effectiveAlias;
+            }
+            else {
+                // Multi-table query: we cannot know which table an undeclared
+                // attribute belongs to. Defaulting to the FROM table would silently
+                // yield nulls when it actually lives on a joined table, so reject
+                // and let 'auto' mode fall back to legacy.
+                throw new errors_ts_1.EngineUnsupportedError(`column "${expr.name}" is not declared on any joined table; qualify it with a table alias`);
+            }
+            return;
+        }
+        case 'star':
+            // `t.*` qualifier is validated at star-expansion time; bare `*` spans all.
+            if (expr.table) {
+                const t = resolveQualifier(expr.table, scope);
+                if (!t)
+                    throw new errors_ts_1.EngineUnsupportedError(`unknown table qualifier "${expr.table}" in "${expr.table}.*"`);
+                expr.table = t.effectiveAlias;
+            }
+            return;
+        case 'binop':
+            resolveColumns(expr.left, scope);
+            resolveColumns(expr.right, scope);
+            return;
+        case 'logical':
+            expr.args.forEach((a) => resolveColumns(a, scope));
+            return;
+        case 'in':
+            resolveColumns(expr.expr, scope);
+            if (Array.isArray(expr.list))
+                expr.list.forEach((e) => resolveColumns(e, scope));
+            return;
+        case 'between':
+            resolveColumns(expr.expr, scope);
+            resolveColumns(expr.low, scope);
+            resolveColumns(expr.high, scope);
+            return;
+        case 'like':
+            resolveColumns(expr.expr, scope);
+            resolveColumns(expr.pattern, scope);
+            return;
+        case 'isNull':
+            resolveColumns(expr.expr, scope);
+            return;
+        case 'funcCall':
+            expr.args.forEach((a) => resolveColumns(a, scope));
+            return;
+        case 'aggCall':
+            if (expr.arg.kind !== 'star')
+                resolveColumns(expr.arg, scope);
+            return;
+        case 'case':
+            for (const c of expr.cases) {
+                resolveColumns(c.when, scope);
+                resolveColumns(c.then, scope);
+            }
+            if (expr.else)
+                resolveColumns(expr.else, scope);
+            return;
+        case 'cast':
+            resolveColumns(expr.expr, scope);
+            return;
+        default:
+            return;
+    }
+}
+// Surfaced for unit tests.
+exports._internal = { resolveColumns, resolveQualifier };
+//# sourceMappingURL=bind.js.map

package/dist/sqlEngine/binder/bind.js.map

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

package/dist/sqlEngine/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reads the SQL engine feature flag and runtime caps.
+ *
+ * sql.engine selects which engine handles a SQL request:
+ *   'legacy' — existing AlaSQL-based path.
+ *   'new'    — new Resource-API-based path; throws EngineUnsupportedError for
+ *              queries it can't plan.
+ *   'auto'   — try the new path first; fall back to legacy on
+ *              EngineUnsupportedError (default).
+ *
+ * The flag is read from the HARPER_SQL_ENGINE environment variable, then
+ * harperConfig.sql?.engine, then defaults to 'auto'. We deliberately keep
+ * this resolution lazy and lightweight so the router can be invoked without a
+ * fully booted Harper config (e.g., in unit tests).
+ *
+ * Phase 5 cutover: the default is now 'auto' — the new engine handles every SQL
+ * request it can plan and silently falls back to legacy on anything it can't, so
+ * no query changes behavior unless the new engine produces an identical result.
+ * The gate for this flip was full parity of the new engine (run in 'auto') against
+ * the existing SQL suite: the cutover-readiness differential (46/46 identical) plus
+ * the existing behavioral suites under 'auto' — northwind (575 SQL ops) and
+ * delete.test.mjs (76) — at 0 failures. Both trial-flip blockers (IN literal
+ * coercion, LIKE-predicate DELETE 403) and the northwind gaps (attribute-name
+ * validation, quoted-boolean coercion, != / NULL three-valued logic) are fixed.
+ * The remaining cutover work is burn-in (watch `sql-engine v2 fallback:` logs) then
+ * flipping to 'new' and deleting the legacy path. See PLAN.md phase-5 notes.
+ */
+export type SqlEngineMode = 'legacy' | 'new' | 'auto';
+export interface SqlEngineConfig {
+    engine: SqlEngineMode;
+    allowFullScan: boolean;
+    maxSortRows: number;
+    maxHashRows: number;
+}
+export declare function getSqlEngineConfig(): SqlEngineConfig;

package/dist/sqlEngine/config.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Reads the SQL engine feature flag and runtime caps.
+ *
+ * sql.engine selects which engine handles a SQL request:
+ *   'legacy' — existing AlaSQL-based path.
+ *   'new'    — new Resource-API-based path; throws EngineUnsupportedError for
+ *              queries it can't plan.
+ *   'auto'   — try the new path first; fall back to legacy on
+ *              EngineUnsupportedError (default).
+ *
+ * The flag is read from the HARPER_SQL_ENGINE environment variable, then
+ * harperConfig.sql?.engine, then defaults to 'auto'. We deliberately keep
+ * this resolution lazy and lightweight so the router can be invoked without a
+ * fully booted Harper config (e.g., in unit tests).
+ *
+ * Phase 5 cutover: the default is now 'auto' — the new engine handles every SQL
+ * request it can plan and silently falls back to legacy on anything it can't, so
+ * no query changes behavior unless the new engine produces an identical result.
+ * The gate for this flip was full parity of the new engine (run in 'auto') against
+ * the existing SQL suite: the cutover-readiness differential (46/46 identical) plus
+ * the existing behavioral suites under 'auto' — northwind (575 SQL ops) and
+ * delete.test.mjs (76) — at 0 failures. Both trial-flip blockers (IN literal
+ * coercion, LIKE-predicate DELETE 403) and the northwind gaps (attribute-name
+ * validation, quoted-boolean coercion, != / NULL three-valued logic) are fixed.
+ * The remaining cutover work is burn-in (watch `sql-engine v2 fallback:` logs) then
+ * flipping to 'new' and deleting the legacy path. See PLAN.md phase-5 notes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSqlEngineConfig = getSqlEngineConfig;
+const DEFAULTS = {
+    engine: 'auto',
+    allowFullScan: false,
+    maxSortRows: 1_000_000,
+    maxHashRows: 1_000_000,
+};
+function envEngine() {
+    const v = process.env.HARPER_SQL_ENGINE;
+    if (v === 'legacy' || v === 'new' || v === 'auto')
+        return v;
+    return undefined;
+}
+function harperConfigEngine() {
+    try {
+        const harperConfig = globalThis.harperConfig;
+        return harperConfig?.sql ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function getSqlEngineConfig() {
+    const fromConfig = harperConfigEngine();
+    const fromEnv = envEngine();
+    return {
+        engine: fromEnv ?? fromConfig.engine ?? DEFAULTS.engine,
+        allowFullScan: fromConfig.allowFullScan ?? DEFAULTS.allowFullScan,
+        maxSortRows: fromConfig.maxSortRows ?? DEFAULTS.maxSortRows,
+        maxHashRows: fromConfig.maxHashRows ?? DEFAULTS.maxHashRows,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/sqlEngine/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../sqlEngine/config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;AAiCH,gDASC;AA/BD,MAAM,QAAQ,GAAoB;IACjC,MAAM,EAAE,MAAM;IACd,aAAa,EAAE,KAAK;IACpB,WAAW,EAAE,SAAS;IACtB,WAAW,EAAE,SAAS;CACtB,CAAC;AAEF,SAAS,SAAS;IACjB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IACxC,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,kBAAkB;IAC1B,IAAI,CAAC;QACJ,MAAM,YAAY,GAAI,UAAoE,CAAC,YAAY,CAAC;QACxG,OAAO,YAAY,EAAE,GAAG,IAAI,EAAE,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,CAAC;IACX,CAAC;AACF,CAAC;AAED,SAAgB,kBAAkB;IACjC,MAAM,UAAU,GAAG,kBAAkB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;IAC5B,OAAO;QACN,MAAM,EAAE,OAAO,IAAI,UAAU,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM;QACvD,aAAa,EAAE,UAAU,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa;QACjE,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW;QAC3D,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW;KAC3D,CAAC;AACH,CAAC"}

package/dist/sqlEngine/diff/differential.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Differential test harness.
+ *
+ * Runs a SQL query through both the legacy and new engines and deep-equals the
+ * results modulo:
+ *   - row order when no ORDER BY is present (sorted by JSON serialization),
+ *   - undefined → null translation (legacy returns both; we normalize),
+ *   - object key order.
+ *
+ * Used by the parity test suite under core/unitTests/sqlEngine/.
+ */
+export interface DifferentialOptions {
+    hdb_user?: unknown;
+    preserveOrder?: boolean;
+    bypass_auth?: boolean;
+}
+export interface DifferentialResult {
+    legacy: unknown;
+    v2: unknown;
+    equal: boolean;
+    v2Unsupported?: string;
+}
+export declare function runDifferential(sql: string, opts?: DifferentialOptions): Promise<DifferentialResult>;

package/dist/sqlEngine/diff/differential.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Differential test harness.
+ *
+ * Runs a SQL query through both the legacy and new engines and deep-equals the
+ * results modulo:
+ *   - row order when no ORDER BY is present (sorted by JSON serialization),
+ *   - undefined → null translation (legacy returns both; we normalize),
+ *   - object key order.
+ *
+ * Used by the parity test suite under core/unitTests/sqlEngine/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDifferential = runDifferential;
+const errors_ts_1 = require("../errors.js");
+function loadLegacy() {
+    return require('../../sqlTranslator/index.js');
+}
+function runLegacy(sql, opts) {
+    const translator = loadLegacy();
+    return new Promise((resolve, reject) => {
+        translator.evaluateSQL({ sql, hdb_user: opts.hdb_user, bypass_auth: opts.bypass_auth ?? true }, (err, data) => {
+            if (err)
+                reject(err);
+            else
+                resolve(data);
+        });
+    });
+}
+async function runV2(sql, opts) {
+    const previous = process.env.HARPER_SQL_ENGINE;
+    process.env.HARPER_SQL_ENGINE = 'new';
+    try {
+        return await runLegacy(sql, opts);
+    }
+    finally {
+        if (previous === undefined)
+            delete process.env.HARPER_SQL_ENGINE;
+        else
+            process.env.HARPER_SQL_ENGINE = previous;
+    }
+}
+function normalize(value) {
+    if (value === undefined)
+        return null;
+    if (value === null)
+        return null;
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = normalize(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+function sortRows(rows) {
+    if (!Array.isArray(rows))
+        return rows;
+    return [...rows].sort((a, b) => {
+        const sa = JSON.stringify(a);
+        const sb = JSON.stringify(b);
+        return sa < sb ? -1 : sa > sb ? 1 : 0;
+    });
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+async function runDifferential(sql, opts = {}) {
+    const legacy = await runLegacy(sql, opts);
+    let v2;
+    let v2Unsupported;
+    try {
+        v2 = await runV2(sql, opts);
+    }
+    catch (err) {
+        if (err instanceof errors_ts_1.EngineUnsupportedError) {
+            return { legacy, v2: undefined, equal: false, v2Unsupported: err.reason };
+        }
+        throw err;
+    }
+    const normalizedLegacy = normalize(legacy);
+    const normalizedV2 = normalize(v2);
+    const a = opts.preserveOrder ? normalizedLegacy : sortRows(normalizedLegacy);
+    const b = opts.preserveOrder ? normalizedV2 : sortRows(normalizedV2);
+    return { legacy, v2, equal: deepEqual(a, b), v2Unsupported };
+}
+//# sourceMappingURL=differential.js.map

package/dist/sqlEngine/diff/differential.js.map

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

package/dist/sqlEngine/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Engine-specific error types for the new SQL engine.
+ *
+ * EngineUnsupportedError is thrown when a query cannot be handled by the new
+ * engine — either at plan time (a shape that can't map to the Resource API) or
+ * at execution time (an in-memory operator exceeding its row cap, before any
+ * result is emitted). The router catches this in 'auto' mode and falls back to
+ * the legacy AlaSQL engine.
+ *
+ * EngineRuntimeError is thrown for genuine runtime failures that are NOT
+ * recoverable by falling back (e.g., a mutation target with no primary key).
+ * The router does not fall back on it — it surfaces to the caller.
+ */
+import { ClientError } from '../utility/errors/hdbError.js';
+export declare class EngineUnsupportedError extends ClientError {
+    reason: string;
+    astSnippet?: unknown;
+    constructor(reason: string, astSnippet?: unknown);
+}
+export declare class EngineRuntimeError extends ClientError {
+    constructor(message: string);
+}

package/dist/sqlEngine/errors.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Engine-specific error types for the new SQL engine.
+ *
+ * EngineUnsupportedError is thrown when a query cannot be handled by the new
+ * engine — either at plan time (a shape that can't map to the Resource API) or
+ * at execution time (an in-memory operator exceeding its row cap, before any
+ * result is emitted). The router catches this in 'auto' mode and falls back to
+ * the legacy AlaSQL engine.
+ *
+ * EngineRuntimeError is thrown for genuine runtime failures that are NOT
+ * recoverable by falling back (e.g., a mutation target with no primary key).
+ * The router does not fall back on it — it surfaces to the caller.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineRuntimeError = exports.EngineUnsupportedError = void 0;
+const hdbError_js_1 = require("../utility/errors/hdbError.js");
+class EngineUnsupportedError extends hdbError_js_1.ClientError {
+    reason;
+    astSnippet;
+    constructor(reason, astSnippet) {
+        super(`SQL engine v2: unsupported query — ${reason}`);
+        this.name = 'EngineUnsupportedError';
+        this.reason = reason;
+        this.astSnippet = astSnippet;
+    }
+}
+exports.EngineUnsupportedError = EngineUnsupportedError;
+class EngineRuntimeError extends hdbError_js_1.ClientError {
+    constructor(message) {
+        super(`SQL engine v2: ${message}`);
+        this.name = 'EngineRuntimeError';
+    }
+}
+exports.EngineRuntimeError = EngineRuntimeError;
+//# sourceMappingURL=errors.js.map

package/dist/sqlEngine/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../sqlEngine/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,+DAA4D;AAE5D,MAAa,sBAAuB,SAAQ,yBAAW;IACtD,MAAM,CAAS;IACf,UAAU,CAAW;IAErB,YAAY,MAAc,EAAE,UAAoB;QAC/C,KAAK,CAAC,sCAAsC,MAAM,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;CACD;AAVD,wDAUC;AAED,MAAa,kBAAmB,SAAQ,yBAAW;IAClD,YAAY,OAAe;QAC1B,KAAK,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,CAAC;CACD;AALD,gDAKC"}

package/dist/sqlEngine/executor/runMutation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Phase 4 mutation executors: INSERT / UPDATE / DELETE.
+ *
+ * Writes go through the Resource API exactly as production code does: the
+ * `databases`-resolved entry is the Table class, whose static
+ * `create`/`put`/`patch`/`delete`/`get` methods each call `transaction(context,
+ * …)` internally and *join* an already-open transaction on the context
+ * (resources/Resource.ts). So the whole mutation runs inside a single
+ * `transaction(context, …)`; every per-row write joins it and the batch commits
+ * (or aborts) atomically.
+ *
+ * UPDATE/DELETE find their target rows by running the ordinary SELECT pipeline
+ * (a synthetic `SELECT … FROM target WHERE …`) inside the same transaction, so
+ * the read sees a consistent snapshot with the writes.
+ *
+ * Response shapes match the legacy SQL path (dataLayer/insert.ts,
+ * dataLayer/delete.ts) so callers see no difference:
+ *   INSERT → { message: "inserted N of M records", inserted_hashes, skipped_hashes }
+ *   UPDATE → { message: "updated N of M records",  update_hashes,  skipped_hashes }
+ *   DELETE → { message: "N of M records successfully deleted", deleted_hashes, skipped_hashes }
+ */
+import type { BoundInsert, BoundUpdate, BoundDelete } from '../binder/bind.ts';
+import type { SqlEngineContext } from '../types.ts';
+/** A minimal context carrying the user; `transaction()` attaches `.transaction`. */
+interface WriteContext {
+    user?: unknown;
+    transaction?: unknown;
+}
+type TransactionRunner = <T>(context: WriteContext, callback: () => Promise<T>) => Promise<T>;
+/** Test hook: override the transaction runner. Pass null to restore the default. */
+export declare function _setTransactionRunner(runner: TransactionRunner | null): void;
+export declare function runInsert(bound: BoundInsert, ctx: SqlEngineContext): Promise<unknown>;
+export declare function runUpdate(bound: BoundUpdate, ctx: SqlEngineContext): Promise<unknown>;
+export declare function runDelete(bound: BoundDelete, ctx: SqlEngineContext): Promise<unknown>;
+export {};