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

package/dist/sqlEngine/physical/PhysicalProject.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * PhysicalProject: per-row evaluation of the SELECT clause.
+ *
+ * Single-table (`qualified = false`): star expansion forwards the row's keys
+ * intact and layers projected columns on top, matching the Resource API's
+ * natural record shape.
+ *
+ * Join queries (`qualified = true`): rows arrive keyed by `<alias>.<name>`.
+ * Output columns are renamed to clean, unqualified names (or the SELECT `AS`
+ * alias). When two output columns collide on the same name the later one is
+ * suffixed `_2`, `_3`, … in SELECT order (legacy AlaSQL instead emitted
+ * `[name]`/`[name1]`; the differential harness normalizes between the two).
+ * `SELECT *` expands every column across all joined tables; `SELECT t.*`
+ * expands only table `t`'s columns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.physicalProject = physicalProject;
+const compile_ts_1 = require("../expressions/compile.js");
+function physicalProject(child, projections, qualified = false) {
+    if (qualified)
+        return qualifiedProject(child, projections);
+    const slots = projections.map((p) => buildSlot(p));
+    const schema = slots.flatMap((s) => s.schema);
+    return {
+        schema,
+        async *execute(ctx) {
+            for await (const row of child.execute(ctx)) {
+                const out = {};
+                for (const slot of slots)
+                    slot.apply(row, out);
+                yield out;
+            }
+        },
+    };
+}
+function buildSlot(p) {
+    if (p.expr.kind === 'star') {
+        return {
+            schema: [],
+            apply(row, out) {
+                for (const k of Object.keys(row))
+                    out[k] = row[k];
+            },
+        };
+    }
+    const compiled = (0, compile_ts_1.compileExpr)(p.expr);
+    const name = p.alias ?? p.label ?? expressionLabel(p);
+    return {
+        schema: [{ name, type: compiled.type, nullable: true }],
+        apply(row, out) {
+            out[name] = compiled.eval(row);
+        },
+    };
+}
+function expressionLabel(p) {
+    if (p.expr.kind === 'column')
+        return p.expr.name;
+    return p.alias ?? 'expr';
+}
+function qualifiedProject(child, projections) {
+    const slots = projections.map((p) => buildQualifiedSlot(p));
+    return {
+        schema: [],
+        async *execute(ctx) {
+            for await (const row of child.execute(ctx)) {
+                const pairs = [];
+                for (const slot of slots)
+                    slot.emit(row, pairs);
+                yield dedupeIntoRow(pairs);
+            }
+        },
+    };
+}
+function buildQualifiedSlot(p) {
+    if (p.expr.kind === 'star') {
+        const prefix = p.expr.table ? `${p.expr.table}.` : undefined;
+        return {
+            emit(row, acc) {
+                for (const k of Object.keys(row)) {
+                    if (prefix) {
+                        if (k.startsWith(prefix))
+                            acc.push([k.slice(prefix.length), row[k]]);
+                    }
+                    else {
+                        // strip the alias qualifier for clean output
+                        const dot = k.indexOf('.');
+                        acc.push([dot >= 0 ? k.slice(dot + 1) : k, row[k]]);
+                    }
+                }
+            },
+        };
+    }
+    const compiled = (0, compile_ts_1.compileExpr)(p.expr, true);
+    const name = p.alias ?? p.label ?? qualifiedLabel(p);
+    return {
+        emit(row, acc) {
+            acc.push([name, compiled.eval(row)]);
+        },
+    };
+}
+function qualifiedLabel(p) {
+    if (p.expr.kind === 'column')
+        return p.expr.name; // bare name, alias dropped
+    return p.alias ?? 'expr';
+}
+function dedupeIntoRow(pairs) {
+    const out = {};
+    const counts = new Map();
+    for (const [name, value] of pairs) {
+        const n = counts.get(name) ?? 0;
+        counts.set(name, n + 1);
+        out[n === 0 ? name : `${name}_${n + 1}`] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=PhysicalProject.js.map

package/dist/sqlEngine/physical/PhysicalProject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicalProject.js","sourceRoot":"","sources":["../../../sqlEngine/physical/PhysicalProject.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAOH,0CAgBC;AAlBD,0DAAwD;AAExD,SAAgB,eAAe,CAAC,KAAiB,EAAE,WAA6B,EAAE,SAAS,GAAG,KAAK;IAClG,IAAI,SAAS;QAAE,OAAO,gBAAgB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAE3D,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,MAAM,MAAM,GAAmB,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAE9D,OAAO;QACN,MAAM;QACN,KAAK,CAAC,CAAC,OAAO,CAAC,GAAqB;YACnC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5C,MAAM,GAAG,GAAQ,EAAE,CAAC;gBACpB,KAAK,MAAM,IAAI,IAAI,KAAK;oBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC/C,MAAM,GAAG,CAAC;YACX,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC;AAOD,SAAS,SAAS,CAAC,CAAiB;IACnC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO;YACN,MAAM,EAAE,EAAE;YACV,KAAK,CAAC,GAAG,EAAE,GAAG;gBACb,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACnD,CAAC;SACD,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,IAAA,wBAAW,EAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO;QACN,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACvD,KAAK,CAAC,GAAG,EAAE,GAAG;YACb,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;KACD,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,CAAiB;IACzC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;IACjD,OAAO,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC;AAC1B,CAAC;AAWD,SAAS,gBAAgB,CAAC,KAAiB,EAAE,WAA6B;IACzE,MAAM,KAAK,GAAoB,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7E,OAAO;QACN,MAAM,EAAE,EAAE;QACV,KAAK,CAAC,CAAC,OAAO,CAAC,GAAqB;YACnC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5C,MAAM,KAAK,GAA6B,EAAE,CAAC;gBAC3C,KAAK,MAAM,IAAI,IAAI,KAAK;oBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBAChD,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,CAAiB;IAC5C,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,OAAO;YACN,IAAI,CAAC,GAAG,EAAE,GAAG;gBACZ,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;oBAClC,IAAI,MAAM,EAAE,CAAC;wBACZ,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;4BAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBACtE,CAAC;yBAAM,CAAC;wBACP,6CAA6C;wBAC7C,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;wBAC3B,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBACrD,CAAC;gBACF,CAAC;YACF,CAAC;SACD,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,IAAA,wBAAW,EAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC;IACrD,OAAO;QACN,IAAI,CAAC,GAAG,EAAE,GAAG;YACZ,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC;KACD,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,CAAiB;IACxC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,2BAA2B;IAC7E,OAAO,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC;AAC1B,CAAC;AAED,SAAS,aAAa,CAAC,KAA+B;IACrD,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/sqlEngine/physical/PhysicalQualify.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PhysicalQualify: re-keys a base scan's bare records into the join row model.
+ *
+ * In a join query every column flows through the pipeline under a
+ * `<alias>.<attribute>` key so that same-named columns from different tables
+ * never collide. The base PhysicalIndexScan yields plain records keyed by bare
+ * attribute name (and Resource API conditions/projection operate on bare
+ * names); this operator wraps that scan and qualifies every key with the
+ * scan's alias. Residual single-table filters are applied *below* this operator
+ * (in bare space) so only join-level operators see qualified rows.
+ */
+import type { PhysicalOp } from './op.ts';
+export declare function physicalQualify(child: PhysicalOp, alias: string): PhysicalOp;

package/dist/sqlEngine/physical/PhysicalQualify.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * PhysicalQualify: re-keys a base scan's bare records into the join row model.
+ *
+ * In a join query every column flows through the pipeline under a
+ * `<alias>.<attribute>` key so that same-named columns from different tables
+ * never collide. The base PhysicalIndexScan yields plain records keyed by bare
+ * attribute name (and Resource API conditions/projection operate on bare
+ * names); this operator wraps that scan and qualifies every key with the
+ * scan's alias. Residual single-table filters are applied *below* this operator
+ * (in bare space) so only join-level operators see qualified rows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.physicalQualify = physicalQualify;
+function physicalQualify(child, alias) {
+    const prefix = `${alias}.`;
+    return {
+        schema: child.schema,
+        async *execute(ctx) {
+            for await (const row of child.execute(ctx)) {
+                const out = {};
+                for (const k of Object.keys(row))
+                    out[prefix + k] = row[k];
+                yield out;
+            }
+        },
+    };
+}
+//# sourceMappingURL=PhysicalQualify.js.map

package/dist/sqlEngine/physical/PhysicalQualify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicalQualify.js","sourceRoot":"","sources":["../../../sqlEngine/physical/PhysicalQualify.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAKH,0CAYC;AAZD,SAAgB,eAAe,CAAC,KAAiB,EAAE,KAAa;IAC/D,MAAM,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC;IAC3B,OAAO;QACN,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAqB;YACnC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5C,MAAM,GAAG,GAAQ,EAAE,CAAC;gBACpB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC3D,MAAM,GAAG,CAAC;YACX,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/sqlEngine/physical/PhysicalSort.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PhysicalSort: in-memory sort with a configurable row cap.
+ *
+ * Used only when the optimizer's sort-from-index rule could not push the
+ * sort into Table.search. Buffers up to maxSortRows rows; throws
+ * EngineUnsupportedError if the input exceeds that cap so the router falls
+ * back to legacy in 'auto' mode (runSelect fully materializes before
+ * returning, so nothing has been emitted to the client when the cap trips).
+ */
+import type { SortNode } from '../parser/ast.ts';
+import type { PhysicalOp } from './op.ts';
+export declare function physicalSort(child: PhysicalOp, keys: SortNode[], qualified?: boolean): PhysicalOp;

package/dist/sqlEngine/physical/PhysicalSort.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * PhysicalSort: in-memory sort with a configurable row cap.
+ *
+ * Used only when the optimizer's sort-from-index rule could not push the
+ * sort into Table.search. Buffers up to maxSortRows rows; throws
+ * EngineUnsupportedError if the input exceeds that cap so the router falls
+ * back to legacy in 'auto' mode (runSelect fully materializes before
+ * returning, so nothing has been emitted to the client when the cap trips).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.physicalSort = physicalSort;
+const compile_ts_1 = require("../expressions/compile.js");
+const errors_ts_1 = require("../errors.js");
+const config_ts_1 = require("../config.js");
+function physicalSort(child, keys, qualified = false) {
+    const compiled = keys.map((k) => ({ get: (0, compile_ts_1.compileExpr)(k.expr, qualified).eval, descending: k.descending }));
+    return {
+        schema: child.schema,
+        async *execute(ctx) {
+            const cap = (0, config_ts_1.getSqlEngineConfig)().maxSortRows;
+            const buf = [];
+            for await (const row of child.execute(ctx)) {
+                if (buf.length >= cap) {
+                    throw new errors_ts_1.EngineUnsupportedError(`in-memory sort exceeded maxSortRows (${cap})`);
+                }
+                buf.push(row);
+            }
+            buf.sort((a, b) => {
+                for (const k of compiled) {
+                    const av = k.get(a);
+                    const bv = k.get(b);
+                    const cmp = compareValues(av, bv);
+                    if (cmp !== 0)
+                        return k.descending ? -cmp : cmp;
+                }
+                return 0;
+            });
+            for (const row of buf)
+                yield row;
+        },
+    };
+}
+function compareValues(a, b) {
+    if (a == null && b == null)
+        return 0;
+    if (a == null)
+        return -1;
+    if (b == null)
+        return 1;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : a > b ? 1 : 0;
+    const as = String(a);
+    const bs = String(b);
+    return as < bs ? -1 : as > bs ? 1 : 0;
+}
+//# sourceMappingURL=PhysicalSort.js.map

package/dist/sqlEngine/physical/PhysicalSort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicalSort.js","sourceRoot":"","sources":["../../../sqlEngine/physical/PhysicalSort.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AASH,oCAyBC;AA7BD,0DAAwD;AACxD,4CAAsD;AACtD,4CAAkD;AAElD,SAAgB,YAAY,CAAC,KAAiB,EAAE,IAAgB,EAAE,SAAS,GAAG,KAAK;IAClF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAA,wBAAW,EAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC3G,OAAO;QACN,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,CAAC,CAAC,OAAO,CAAC,GAAqB;YACnC,MAAM,GAAG,GAAG,IAAA,8BAAkB,GAAE,CAAC,WAAW,CAAC;YAC7C,MAAM,GAAG,GAAU,EAAE,CAAC;YACtB,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5C,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;oBACvB,MAAM,IAAI,kCAAsB,CAAC,wCAAwC,GAAG,GAAG,CAAC,CAAC;gBAClF,CAAC;gBACD,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBACjB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;oBAC1B,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACpB,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACpB,MAAM,GAAG,GAAG,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;oBAClC,IAAI,GAAG,KAAK,CAAC;wBAAE,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBACjD,CAAC;gBACD,OAAO,CAAC,CAAC;YACV,CAAC,CAAC,CAAC;YACH,KAAK,MAAM,GAAG,IAAI,GAAG;gBAAE,MAAM,GAAG,CAAC;QAClC,CAAC;KACD,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,CAAU,EAAE,CAAU;IAC5C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtF,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrB,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/sqlEngine/physical/op.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Physical operator interface.
+ *
+ * Volcano-style with AsyncIterable. Each operator's execute() yields rows
+ * lazily; backpressure is implicit in `await`.
+ */
+import type { ColumnSchema, Row, SqlEngineContext } from '../types.ts';
+export interface PhysicalOp {
+    schema: ColumnSchema[];
+    execute(ctx: SqlEngineContext): AsyncIterable<Row>;
+}

package/dist/sqlEngine/physical/op.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Physical operator interface.
+ *
+ * Volcano-style with AsyncIterable. Each operator's execute() yields rows
+ * lazily; backpressure is implicit in `await`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=op.js.map

package/dist/sqlEngine/physical/op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.js","sourceRoot":"","sources":["../../../sqlEngine/physical/op.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/sqlEngine/physical/plan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lowers a logical plan to a physical plan.
+ *
+ *   Scan      -> PhysicalIndexScan (+ residual PhysicalFilter); wrapped in
+ *                PhysicalQualify for join queries so rows are keyed `alias.attr`.
+ *   Filter    -> PhysicalFilter
+ *   Project   -> PhysicalProject
+ *   Sort      -> PhysicalSort
+ *   Limit     -> PhysicalLimit
+ *   Distinct  -> PhysicalDistinct
+ *   Aggregate -> PhysicalHashAggregate
+ *   Join      -> PhysicalIndexNestedLoopJoin | PhysicalHashJoin |
+ *                PhysicalNestedLoopJoin (chosen by optimizer/rules/planJoins)
+ *
+ * `qualified` is computed once from whether the plan contains any Join and
+ * threaded through every operator: join queries resolve columns by their
+ * `<alias>.<attr>` key, single-table queries by bare name.
+ *
+ * Insert/Update/Delete are rejected until phase 4.
+ */
+import type { LogicalPlan } from '../logical/op.ts';
+import type { PhysicalOp } from './op.ts';
+export declare function compileToPhysical(plan: LogicalPlan): PhysicalOp;

package/dist/sqlEngine/physical/plan.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Lowers a logical plan to a physical plan.
+ *
+ *   Scan      -> PhysicalIndexScan (+ residual PhysicalFilter); wrapped in
+ *                PhysicalQualify for join queries so rows are keyed `alias.attr`.
+ *   Filter    -> PhysicalFilter
+ *   Project   -> PhysicalProject
+ *   Sort      -> PhysicalSort
+ *   Limit     -> PhysicalLimit
+ *   Distinct  -> PhysicalDistinct
+ *   Aggregate -> PhysicalHashAggregate
+ *   Join      -> PhysicalIndexNestedLoopJoin | PhysicalHashJoin |
+ *                PhysicalNestedLoopJoin (chosen by optimizer/rules/planJoins)
+ *
+ * `qualified` is computed once from whether the plan contains any Join and
+ * threaded through every operator: join queries resolve columns by their
+ * `<alias>.<attr>` key, single-table queries by bare name.
+ *
+ * Insert/Update/Delete are rejected until phase 4.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileToPhysical = compileToPhysical;
+const PhysicalIndexScan_ts_1 = require("./PhysicalIndexScan.js");
+const PhysicalFilter_ts_1 = require("./PhysicalFilter.js");
+const PhysicalProject_ts_1 = require("./PhysicalProject.js");
+const PhysicalSort_ts_1 = require("./PhysicalSort.js");
+const PhysicalLimit_ts_1 = require("./PhysicalLimit.js");
+const PhysicalHashAggregate_ts_1 = require("./PhysicalHashAggregate.js");
+const PhysicalDistinct_ts_1 = require("./PhysicalDistinct.js");
+const PhysicalQualify_ts_1 = require("./PhysicalQualify.js");
+const PhysicalHashJoin_ts_1 = require("./PhysicalHashJoin.js");
+const PhysicalNestedLoopJoin_ts_1 = require("./PhysicalNestedLoopJoin.js");
+const PhysicalIndexNestedLoopJoin_ts_1 = require("./PhysicalIndexNestedLoopJoin.js");
+const whereToConditions_ts_1 = require("../optimizer/whereToConditions.js");
+const joinAnalysis_ts_1 = require("../optimizer/joinAnalysis.js");
+const config_ts_1 = require("../config.js");
+const errors_ts_1 = require("../errors.js");
+function compileToPhysical(plan) {
+    return lower(plan, planHasJoin(plan));
+}
+function lower(plan, qualified) {
+    switch (plan.kind) {
+        case 'Scan': {
+            const { conditions, operator, residual } = (0, whereToConditions_ts_1.whereToConditions)(plan.pushedFilter, plan.boundTable?.attributes);
+            // A scan with no index-driving predicate but a pushed sort on an indexed
+            // attribute is driven by the index's natural order — Table.search flags it
+            // needFullScan, so it must run with allowFullScan (D-219). validateScannable
+            // has already blessed exactly this shape.
+            const indexDriven = conditions.some((c) => (0, whereToConditions_ts_1.conditionUsesIndex)(c, plan.boundTable?.attributes));
+            const allowFullScan = !indexDriven && (0, whereToConditions_ts_1.sortDrivesIndex)(plan.pushedSort, plan.boundTable?.attributes);
+            let op = (0, PhysicalIndexScan_ts_1.physicalIndexScan)(plan, { conditions, operator, allowFullScan });
+            const combinedResidual = mergeResidual(residual, plan.residualFilter);
+            // Residual is single-table; compile it in bare space before qualifying.
+            if (combinedResidual)
+                op = (0, PhysicalFilter_ts_1.physicalFilter)(op, combinedResidual, false);
+            if (qualified && plan.alias)
+                op = (0, PhysicalQualify_ts_1.physicalQualify)(op, plan.alias);
+            return op;
+        }
+        case 'Filter':
+            return (0, PhysicalFilter_ts_1.physicalFilter)(lower(plan.input, qualified), plan.predicate, qualified);
+        case 'Project':
+            return (0, PhysicalProject_ts_1.physicalProject)(lower(plan.input, qualified), plan.projections, qualified);
+        case 'Sort':
+            return (0, PhysicalSort_ts_1.physicalSort)(lower(plan.input, qualified), plan.keys, qualified);
+        case 'Limit':
+            return (0, PhysicalLimit_ts_1.physicalLimit)(lower(plan.input, qualified), plan.limit, plan.offset);
+        case 'Distinct':
+            return (0, PhysicalDistinct_ts_1.physicalDistinct)(lower(plan.input, qualified));
+        case 'Aggregate': {
+            const { maxHashRows } = (0, config_ts_1.getSqlEngineConfig)();
+            return (0, PhysicalHashAggregate_ts_1.physicalHashAggregate)(lower(plan.input, qualified), plan.groupKeys, plan.aggs, maxHashRows, qualified);
+        }
+        case 'Join':
+            return lowerJoin(plan);
+        case 'Insert':
+        case 'Update':
+        case 'Delete':
+            throw new errors_ts_1.EngineUnsupportedError('mutations are not supported until phase 4');
+    }
+}
+function lowerJoin(join) {
+    const { maxHashRows } = (0, config_ts_1.getSqlEngineConfig)();
+    const analysis = (0, joinAnalysis_ts_1.analyzeJoin)(join);
+    if (!analysis) {
+        throw new errors_ts_1.EngineUnsupportedError('join right side is not a single base table');
+    }
+    const left = lower(join.left, true);
+    const rightNullKeys = qualifiedAttrKeys(analysis.rightScan);
+    const joinType = join.type === 'left' ? 'left' : 'inner';
+    if (join.strategy === 'indexNL') {
+        const probe = (0, joinAnalysis_ts_1.pickIndexedProbe)(analysis);
+        if (!probe)
+            throw new errors_ts_1.EngineUnsupportedError('indexNL join lost its indexed probe key');
+        const inner = analysis.rightScan;
+        const { conditions, operator, residual } = (0, whereToConditions_ts_1.whereToConditions)(inner.pushedFilter, inner.boundTable?.attributes);
+        const innerResidual = mergeResidual(residual, inner.residualFilter);
+        // Equi-pairs other than the probe + non-equi ON remainder → merged-row residual.
+        const otherEqui = analysis.equiPairs
+            .filter((p) => p !== probe.pair)
+            .map((p) => ({ kind: 'binop', op: '=', left: p.outer, right: p.inner }));
+        const residualOn = mergeAll([...otherEqui, ...(analysis.residualOn ? [analysis.residualOn] : [])]);
+        return (0, PhysicalIndexNestedLoopJoin_ts_1.physicalIndexNestedLoopJoin)(left, {
+            innerResource: inner.boundTable?.resource,
+            innerAlias: analysis.rightAlias,
+            innerAttribute: probe.attribute,
+            outerKey: probe.pair.outer,
+            innerBaseConditions: conditions,
+            innerOperator: operator,
+            innerSelect: inner.projection,
+            innerResidual,
+            residualOn,
+            type: joinType,
+            rightNullKeys,
+        });
+    }
+    const right = lower(join.right, true);
+    if (join.strategy === 'hash') {
+        return (0, PhysicalHashJoin_ts_1.physicalHashJoin)(left, right, {
+            leftKeys: analysis.equiPairs.map((p) => p.outer),
+            rightKeys: analysis.equiPairs.map((p) => p.inner),
+            residual: analysis.residualOn,
+            type: joinType,
+            rightNullKeys,
+            maxHashRows,
+        });
+    }
+    // nestedLoop (CROSS / non-equi)
+    return (0, PhysicalNestedLoopJoin_ts_1.physicalNestedLoopJoin)(left, right, {
+        on: join.on,
+        type: join.type === 'left' ? 'left' : join.type === 'cross' ? 'cross' : 'inner',
+        rightNullKeys,
+        maxHashRows,
+    });
+}
+function qualifiedAttrKeys(scan) {
+    const alias = scan.alias ?? '';
+    return (scan.boundTable?.attributes ?? []).map((a) => `${alias}.${a.name}`);
+}
+function planHasJoin(plan) {
+    if (plan.kind === 'Join')
+        return true;
+    if ('input' in plan)
+        return planHasJoin(plan.input);
+    return false;
+}
+function mergeResidual(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return { kind: 'logical', op: 'and', args: [a, b] };
+}
+function mergeAll(exprs) {
+    if (exprs.length === 0)
+        return undefined;
+    if (exprs.length === 1)
+        return exprs[0];
+    return { kind: 'logical', op: 'and', args: exprs };
+}
+//# sourceMappingURL=plan.js.map

package/dist/sqlEngine/physical/plan.js.map

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

package/dist/sqlEngine/router.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Router that dispatches a SQL request to either the new engine or the legacy
+ * AlaSQL-based path based on the sql.engine config flag.
+ *
+ * 'legacy' — always run the legacy handler.
+ * 'new'    — always run the new engine; if it throws EngineUnsupportedError,
+ *            propagate that error (callers can catch).
+ * 'auto'   — try the new engine; on EngineUnsupportedError, fall back to
+ *            legacy and log the fallback.
+ *
+ * The router preserves the legacy entry's (statement, callback) signature so
+ * core/sqlTranslator/index.js can plug it in without other changes.
+ */
+export type SqlVariant = 'select' | 'insert' | 'update' | 'delete';
+export type LegacyHandler = (statement: unknown, callback: (err: unknown, data?: unknown) => void) => void;
+export interface RouteOptions {
+    variant: SqlVariant;
+    jsonMessage: {
+        hdb_user?: unknown;
+        sql?: string;
+        parsed_sql_object?: unknown;
+    };
+    statement: unknown;
+    legacy: LegacyHandler;
+}
+export declare function route(opts: RouteOptions, callback: (err: unknown, data?: unknown) => void): void;

package/dist/sqlEngine/router.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Router that dispatches a SQL request to either the new engine or the legacy
+ * AlaSQL-based path based on the sql.engine config flag.
+ *
+ * 'legacy' — always run the legacy handler.
+ * 'new'    — always run the new engine; if it throws EngineUnsupportedError,
+ *            propagate that error (callers can catch).
+ * 'auto'   — try the new engine; on EngineUnsupportedError, fall back to
+ *            legacy and log the fallback.
+ *
+ * The router preserves the legacy entry's (statement, callback) signature so
+ * core/sqlTranslator/index.js can plug it in without other changes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.route = route;
+const errors_ts_1 = require("./errors.js");
+const config_ts_1 = require("./config.js");
+const index_ts_1 = require("./index.js");
+function getLogger() {
+    try {
+        const harperLogger = require('../utility/logging/harper_logger.js');
+        return harperLogger.loggerWithTag ? harperLogger.loggerWithTag('sql-engine') : harperLogger;
+    }
+    catch {
+        return { info: () => { }, warn: () => { } };
+    }
+}
+function route(opts, callback) {
+    const config = (0, config_ts_1.getSqlEngineConfig)();
+    if (config.engine === 'legacy') {
+        opts.legacy(opts.statement, callback);
+        return;
+    }
+    (0, index_ts_1.runStatement)({
+        variant: opts.variant,
+        jsonMessage: opts.jsonMessage,
+        statement: opts.statement,
+    }).then((result) => callback(null, result), (err) => {
+        if (config.engine === 'auto' && err instanceof errors_ts_1.EngineUnsupportedError) {
+            getLogger().info(`SQL engine v2 fallback: ${err.reason}`);
+            opts.legacy(opts.statement, callback);
+            return;
+        }
+        callback(err);
+    });
+}
+//# sourceMappingURL=router.js.map

package/dist/sqlEngine/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../sqlEngine/router.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AA0BH,sBAuBC;AA/CD,2CAAqD;AACrD,2CAAiD;AACjD,yCAA0C;AAa1C,SAAS,SAAS;IACjB,IAAI,CAAC;QACJ,MAAM,YAAY,GAAG,OAAO,CAAC,qCAAqC,CAAC,CAAC;QACpE,OAAO,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IAC7F,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAC3C,CAAC;AACF,CAAC;AAED,SAAgB,KAAK,CAAC,IAAkB,EAAE,QAAgD;IACzF,MAAM,MAAM,GAAG,IAAA,8BAAkB,GAAE,CAAC;IAEpC,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACtC,OAAO;IACR,CAAC;IAED,IAAA,uBAAY,EAAC;QACZ,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;KACzB,CAAC,CAAC,IAAI,CACN,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,CAAC,GAAY,EAAE,EAAE;QAChB,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,YAAY,kCAAsB,EAAE,CAAC;YACvE,SAAS,EAAE,CAAC,IAAI,CAAC,2BAA2B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACtC,OAAO;QACR,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,CAAC;IACf,CAAC,CACD,CAAC;AACH,CAAC"}

package/dist/sqlEngine/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Common types for the SQL engine.
+ *
+ * Row is the unit of data flowing through the operator pipeline. It is a plain
+ * object whose keys are column names (or projected aliases) and values are SQL
+ * values coerced to JS primitives.
+ *
+ * SqlType is the engine's internal type tag. It does not need to be exhaustive
+ * with the SQL standard — it is used for coercion and function dispatch.
+ */
+export type Row = Record<string, unknown>;
+export type SqlType = 'null' | 'boolean' | 'int' | 'bigint' | 'number' | 'string' | 'date' | 'timestamp' | 'json' | 'blob' | 'array' | 'unknown';
+export interface ColumnSchema {
+    name: string;
+    type: SqlType;
+    nullable: boolean;
+    source?: {
+        table: string;
+        attribute: string;
+    };
+}
+export interface SqlEngineContext {
+    user?: unknown;
+    signal?: AbortSignal;
+    rowBudget?: number;
+    /**
+     * Set when a scan is locating rows for a subsequent UPDATE/DELETE, not serving
+     * a user-facing SELECT. A row whose TTL has passed but hasn't been swept by the
+     * background eviction scan yet is still physically present, and every other
+     * write surface (REST PUT/PATCH, ops update) still finds and overwrites it —
+     * they load by id without the freshness check a normal read applies. Without
+     * this, the scan that locates a mutation's target rows would silently drop one
+     * that's crossed its TTL between being written and being matched, so the
+     * mutation touches nothing and the TTL never resets (QA-269).
+     */
+    includeExpiredRows?: boolean;
+}

package/dist/sqlEngine/types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Common types for the SQL engine.
+ *
+ * Row is the unit of data flowing through the operator pipeline. It is a plain
+ * object whose keys are column names (or projected aliases) and values are SQL
+ * values coerced to JS primitives.
+ *
+ * SqlType is the engine's internal type tag. It does not need to be exhaustive
+ * with the SQL standard — it is used for coercion and function dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/sqlEngine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../sqlEngine/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG"}

package/dist/sqlTranslator/index.js

@@ -56,6 +56,7 @@ const hdbUtils = __importStar(require("../utility/common_utils.js"));
 const terms = __importStar(require("../utility/hdbTerms.js"));
 const hdbError_ts_1 = require("../utility/errors/hdbError.js");
 const commonErrors_ts_1 = require("../utility/errors/commonErrors.js");
+const sqlEngineRouter = __importStar(require("../sqlEngine/router.js"));
 //here we call to define and import custom functions to alasql
 (0, alasqlFunctionImporter_ts_1.default)(alasql);
 let UNAUTHORIZED_RESPONSE = 403;
@@ -177,7 +178,12 @@ function processAST(jsonMessage, parsedSqlObject, callback) {
             default:
                 throw new Error(`unsupported SQL type ${parsedSqlObject.variant} in SQL: ${jsonMessage}`);
         }
-        sqlFunction(statement, (err, data) => {
+        sqlEngineRouter.route({
+            variant: parsedSqlObject.variant,
+            jsonMessage,
+            statement,
+            legacy: sqlFunction,
+        }, (err, data) => {
             if (err) {
                 callback(err);
                 return;