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

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 {};