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

package/dist/sqlEngine/optimizer/rules/predicateNormalize.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Rule R3: predicate normalization.
+ *
+ * Maps AlaSQL operator forms to a canonical shape ahead of pushdown:
+ *   - LIKE 'foo%'   ->  starts_with(foo)
+ *   - LIKE '%foo'   ->  ends_with(foo)
+ *   - LIKE '%foo%'  ->  contains(foo)
+ *   - BETWEEN a AND b -> binop chain (col >= a AND col <= b)  with semantic
+ *                       hint kept via marker for the pushdown rule
+ *   - NOT (a > b)   ->  a <= b (NULL semantics preserved by leaving NOT in
+ *                       place when the operand is anything other than a
+ *                       comparable binop on a single column ref)
+ *   - IS NULL / IS NOT NULL: left as-is (rule output for downstream).
+ *
+ * No change-of-meaning rewrites at this stage; the rule is conservative.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePredicate = normalizePredicate;
+const NOT_OP_INVERSE = {
+    '=': '!=',
+    '!=': '=',
+    '<>': '=',
+    '<': '>=',
+    '<=': '>',
+    '>': '<=',
+    '>=': '<',
+};
+function normalizePredicate(expr) {
+    switch (expr.kind) {
+        case 'logical': {
+            if (expr.op === 'not' && expr.args.length === 1) {
+                const inner = normalizePredicate(expr.args[0]);
+                if (inner.kind === 'binop' && NOT_OP_INVERSE[inner.op]) {
+                    return {
+                        kind: 'binop',
+                        op: NOT_OP_INVERSE[inner.op],
+                        left: inner.left,
+                        right: inner.right,
+                    };
+                }
+                if (inner.kind === 'isNull') {
+                    return { ...inner, negated: !inner.negated };
+                }
+                if (inner.kind === 'between') {
+                    return { ...inner, negated: !inner.negated };
+                }
+                if (inner.kind === 'in') {
+                    return { ...inner, negated: !inner.negated };
+                }
+                if (inner.kind === 'like') {
+                    return { ...inner, negated: !inner.negated };
+                }
+                return { kind: 'logical', op: 'not', args: [inner] };
+            }
+            return { kind: 'logical', op: expr.op, args: expr.args.map(normalizePredicate) };
+        }
+        case 'binop':
+            return { ...expr, left: normalizeChild(expr.left), right: normalizeChild(expr.right) };
+        case 'between':
+            return {
+                ...expr,
+                expr: normalizeChild(expr.expr),
+                low: normalizeChild(expr.low),
+                high: normalizeChild(expr.high),
+            };
+        case 'in':
+            return { ...expr, expr: normalizeChild(expr.expr) };
+        case 'like':
+            return { ...expr, expr: normalizeChild(expr.expr), pattern: normalizeChild(expr.pattern) };
+        case 'isNull':
+            return { ...expr, expr: normalizeChild(expr.expr) };
+        default:
+            return expr;
+    }
+}
+function normalizeChild(expr) {
+    return expr;
+}
+//# sourceMappingURL=predicateNormalize.js.map

package/dist/sqlEngine/optimizer/rules/predicateNormalize.js.map

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

package/dist/sqlEngine/optimizer/rules/predicatePushdown.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Rule R1: predicate pushdown.
+ *
+ * Pushes Filter into the Scan immediately below it. The portion that maps to
+ * Resource API conditions is stored on Scan.pushedFilter (consumed by the
+ * physical planner's whereToConditions). Anything that can't be expressed as
+ * a condition is left as Scan.residualFilter and applied by a wrapping
+ * PhysicalFilter at execution time.
+ */
+import type { LogicalPlan } from '../../logical/op.ts';
+export declare function predicatePushdown(plan: LogicalPlan): LogicalPlan | null;

package/dist/sqlEngine/optimizer/rules/predicatePushdown.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Rule R1: predicate pushdown.
+ *
+ * Pushes Filter into the Scan immediately below it. The portion that maps to
+ * Resource API conditions is stored on Scan.pushedFilter (consumed by the
+ * physical planner's whereToConditions). Anything that can't be expressed as
+ * a condition is left as Scan.residualFilter and applied by a wrapping
+ * PhysicalFilter at execution time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.predicatePushdown = predicatePushdown;
+function predicatePushdown(plan) {
+    return rewrite(plan);
+}
+function rewrite(plan) {
+    switch (plan.kind) {
+        case 'Filter': {
+            const child = rewrite(plan.input);
+            if (child.kind === 'Scan') {
+                const merged = child.pushedFilter
+                    ? { kind: 'logical', op: 'and', args: [child.pushedFilter, plan.predicate] }
+                    : plan.predicate;
+                return { ...child, pushedFilter: merged };
+            }
+            return { ...plan, input: child };
+        }
+        case 'Project':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Sort':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Limit':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Distinct':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Aggregate':
+            // Recurse into input so WHERE filters below get pushed to the scan.
+            // HAVING (a Filter above us) must NOT be pushed through the Aggregate.
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Join':
+            // Per-table WHERE conjuncts were attached as Filters directly above each
+            // base scan by logical/build; push them in on both sides.
+            return { ...plan, left: rewrite(plan.left), right: rewrite(plan.right) };
+        default:
+            return plan;
+    }
+}
+//# sourceMappingURL=predicatePushdown.js.map

package/dist/sqlEngine/optimizer/rules/predicatePushdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"predicatePushdown.js","sourceRoot":"","sources":["../../../../sqlEngine/optimizer/rules/predicatePushdown.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAIH,8CAEC;AAFD,SAAgB,iBAAiB,CAAC,IAAiB;IAClD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,OAAO,CAAC,IAAiB;IACjC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACf,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY;oBAChC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAkB,EAAE,EAAE,EAAE,KAAc,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE;oBAC9F,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;gBAClB,OAAO,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;YAC3C,CAAC;YACD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QACD,KAAK,SAAS;YACb,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,MAAM;YACV,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,OAAO;YACX,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,UAAU;YACd,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,WAAW;YACf,oEAAoE;YACpE,uEAAuE;YACvE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,MAAM;YACV,yEAAyE;YACzE,0DAA0D;YAC1D,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1E;YACC,OAAO,IAAI,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/sqlEngine/optimizer/rules/projectionPushdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Rule R2: projection pushdown.
+ *
+ * Walks the plan from the root and computes the minimal set of attributes
+ * each Scan must produce. The set is stored on Scan.projection and is mapped
+ * to Resource API target.select by the physical planner.
+ *
+ * If any projection includes a `*`, we leave the scan's projection
+ * unrestricted (undefined → fetch all attributes). This keeps semantics
+ * matching legacy SQL. We can tighten this later by binding `*` to the
+ * concrete attribute list at plan time.
+ */
+import type { ExprNode, ProjectionNode, SortNode } from '../../parser/ast.ts';
+import type { LogicalPlan } from '../../logical/op.ts';
+export declare function projectionPushdown(plan: LogicalPlan): LogicalPlan | null;
+declare function containsStar(projections: ProjectionNode[]): boolean;
+declare function collectColumns(expr: ExprNode, out: Set<string>): void;
+export declare const _internal: {
+    collectColumns: typeof collectColumns;
+    containsStar: typeof containsStar;
+};
+export declare function collectRequiredColumnsFromKeys(keys: SortNode[]): Set<string>;
+export {};

package/dist/sqlEngine/optimizer/rules/projectionPushdown.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Rule R2: projection pushdown.
+ *
+ * Walks the plan from the root and computes the minimal set of attributes
+ * each Scan must produce. The set is stored on Scan.projection and is mapped
+ * to Resource API target.select by the physical planner.
+ *
+ * If any projection includes a `*`, we leave the scan's projection
+ * unrestricted (undefined → fetch all attributes). This keeps semantics
+ * matching legacy SQL. We can tighten this later by binding `*` to the
+ * concrete attribute list at plan time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = void 0;
+exports.projectionPushdown = projectionPushdown;
+exports.collectRequiredColumnsFromKeys = collectRequiredColumnsFromKeys;
+function projectionPushdown(plan) {
+    return rewrite(plan, undefined);
+}
+function rewrite(plan, required) {
+    switch (plan.kind) {
+        case 'Project': {
+            if (containsStar(plan.projections)) {
+                return { ...plan, input: rewrite(plan.input, undefined) };
+            }
+            const need = new Set();
+            for (const p of plan.projections)
+                collectColumns(p.expr, need);
+            return { ...plan, input: rewrite(plan.input, need) };
+        }
+        case 'Filter': {
+            if (required) {
+                const merged = new Set(required);
+                collectColumns(plan.predicate, merged);
+                return { ...plan, input: rewrite(plan.input, merged) };
+            }
+            return { ...plan, input: rewrite(plan.input, undefined) };
+        }
+        case 'Sort': {
+            if (required) {
+                const merged = new Set(required);
+                for (const k of plan.keys)
+                    collectColumns(k.expr, merged);
+                return { ...plan, input: rewrite(plan.input, merged) };
+            }
+            return { ...plan, input: rewrite(plan.input, undefined) };
+        }
+        case 'Limit':
+            return { ...plan, input: rewrite(plan.input, required) };
+        case 'Distinct':
+            return { ...plan, input: rewrite(plan.input, required) };
+        case 'Aggregate': {
+            // `required` from above contains synthetic __agg_N__ names that don't
+            // exist in the input. Compute the actual columns the input must supply.
+            const need = new Set();
+            for (const k of plan.groupKeys)
+                collectColumns(k, need);
+            for (const a of plan.aggs) {
+                if (a.arg.kind !== 'star')
+                    collectColumns(a.arg, need);
+            }
+            return { ...plan, input: rewrite(plan.input, need.size > 0 ? need : undefined) };
+        }
+        case 'Scan': {
+            if (!required)
+                return { ...plan, projection: undefined };
+            if (plan.pushedFilter)
+                collectColumns(plan.pushedFilter, required);
+            if (plan.pushedSort)
+                for (const k of plan.pushedSort)
+                    collectColumns(k.expr, required);
+            if (plan.residualFilter)
+                collectColumns(plan.residualFilter, required);
+            return { ...plan, projection: [...required].sort() };
+        }
+        default:
+            return plan;
+    }
+}
+function containsStar(projections) {
+    for (const p of projections) {
+        if (containsStarExpr(p.expr))
+            return true;
+    }
+    return false;
+}
+function containsStarExpr(expr) {
+    if (expr.kind === 'star')
+        return true;
+    if (expr.kind === 'binop')
+        return containsStarExpr(expr.left) || containsStarExpr(expr.right);
+    if (expr.kind === 'logical')
+        return expr.args.some(containsStarExpr);
+    if (expr.kind === 'funcCall')
+        return expr.args.some(containsStarExpr);
+    return false;
+}
+function collectColumns(expr, out) {
+    switch (expr.kind) {
+        case 'column':
+            out.add(expr.name);
+            return;
+        case 'binop':
+            collectColumns(expr.left, out);
+            collectColumns(expr.right, out);
+            return;
+        case 'logical':
+            expr.args.forEach((a) => collectColumns(a, out));
+            return;
+        case 'in':
+            collectColumns(expr.expr, out);
+            if (Array.isArray(expr.list)) {
+                expr.list.forEach((e) => collectColumns(e, out));
+            }
+            return;
+        case 'between':
+            collectColumns(expr.expr, out);
+            collectColumns(expr.low, out);
+            collectColumns(expr.high, out);
+            return;
+        case 'like':
+            collectColumns(expr.expr, out);
+            collectColumns(expr.pattern, out);
+            return;
+        case 'isNull':
+            collectColumns(expr.expr, out);
+            return;
+        case 'funcCall':
+            expr.args.forEach((a) => collectColumns(a, out));
+            return;
+        case 'aggCall':
+            if (expr.arg.kind !== 'star')
+                collectColumns(expr.arg, out);
+            return;
+        case 'case':
+            for (const c of expr.cases) {
+                collectColumns(c.when, out);
+                collectColumns(c.then, out);
+            }
+            if (expr.else)
+                collectColumns(expr.else, out);
+            return;
+        case 'star':
+        case 'literal':
+            return;
+        default:
+            return;
+    }
+}
+// Surface a helper for unit tests / external rules.
+exports._internal = { collectColumns, containsStar };
+// Helper that other rules can use without re-walking plans.
+function collectRequiredColumnsFromKeys(keys) {
+    const out = new Set();
+    for (const k of keys)
+        collectColumns(k.expr, out);
+    return out;
+}
+//# sourceMappingURL=projectionPushdown.js.map

package/dist/sqlEngine/optimizer/rules/projectionPushdown.js.map

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

package/dist/sqlEngine/optimizer/rules/sortFromIndex.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Rule R7: sort-from-index detection.
+ *
+ * If a Sort's keys all reference indexed attributes on a leaf Scan and the
+ * Sort sits directly above the Scan (with no Filter that would change row
+ * order), push the sort into Scan.pushedSort so Table.search returns rows in
+ * the requested order. The Resource API only supports a single primary sort
+ * with an optional `next` chain; phase 1 only handles the single-key case.
+ *
+ * If pushdown is not possible the Sort stays in place and the executor sorts
+ * in memory (capped by config.maxSortRows).
+ */
+import type { LogicalPlan } from '../../logical/op.ts';
+export declare function sortFromIndex(plan: LogicalPlan): LogicalPlan | null;

package/dist/sqlEngine/optimizer/rules/sortFromIndex.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Rule R7: sort-from-index detection.
+ *
+ * If a Sort's keys all reference indexed attributes on a leaf Scan and the
+ * Sort sits directly above the Scan (with no Filter that would change row
+ * order), push the sort into Scan.pushedSort so Table.search returns rows in
+ * the requested order. The Resource API only supports a single primary sort
+ * with an optional `next` chain; phase 1 only handles the single-key case.
+ *
+ * If pushdown is not possible the Sort stays in place and the executor sorts
+ * in memory (capped by config.maxSortRows).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortFromIndex = sortFromIndex;
+function sortFromIndex(plan) {
+    return rewrite(plan);
+}
+function rewrite(plan) {
+    switch (plan.kind) {
+        case 'Sort': {
+            const child = rewrite(plan.input);
+            if (child.kind === 'Scan' && !child.pushedSort) {
+                if (plan.keys.length !== 1)
+                    return { ...plan, input: child };
+                const key = plan.keys[0];
+                if (key.expr.kind !== 'column')
+                    return { ...plan, input: child };
+                const attribute = key.expr.name;
+                const indexed = child.boundTable?.attributes.some((a) => a.name === attribute && a.indexed);
+                if (!indexed)
+                    return { ...plan, input: child };
+                return { ...child, pushedSort: [key] };
+            }
+            return { ...plan, input: child };
+        }
+        case 'Project':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Filter':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Limit':
+            return { ...plan, input: rewrite(plan.input) };
+        case 'Distinct':
+            return { ...plan, input: rewrite(plan.input) };
+        default:
+            return plan;
+    }
+}
+//# sourceMappingURL=sortFromIndex.js.map

package/dist/sqlEngine/optimizer/rules/sortFromIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortFromIndex.js","sourceRoot":"","sources":["../../../../sqlEngine/optimizer/rules/sortFromIndex.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAIH,sCAEC;AAFD,SAAgB,aAAa,CAAC,IAAiB;IAC9C,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,OAAO,CAAC,IAAiB;IACjC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,MAAM,CAAC,CAAC,CAAC;YACb,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBAChD,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACzB,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBACjE,MAAM,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;gBAChC,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC;gBAC5F,IAAI,CAAC,OAAO;oBAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAC/C,OAAO,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,CAAC;YACD,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAClC,CAAC;QACD,KAAK,SAAS;YACb,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,QAAQ;YACZ,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,OAAO;YACX,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,KAAK,UAAU;YACd,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD;YACC,OAAO,IAAI,CAAC;IACd,CAAC;AACF,CAAC"}

package/dist/sqlEngine/optimizer/rules/validateScannable.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rule R8: scan validation.
+ *
+ * After all pushdowns, we walk every Scan in the plan and check that the
+ * Resource API will accept the resulting target. Specifically: if no usable
+ * index condition was pushed (and `allowFullScan` is off in config), we
+ * throw EngineUnsupportedError naming the offending scan so the router can
+ * fall back to legacy in 'auto' mode.
+ *
+ * Phase 1 keeps the check loose: any pushedFilter that maps to at least one
+ * Resource API condition with an indexed attribute is sufficient. Filtering
+ * decisions sit in optimizer/whereToConditions.ts.
+ */
+import type { LogicalPlan } from '../../logical/op.ts';
+export declare function validateScannable(plan: LogicalPlan): LogicalPlan | null;

package/dist/sqlEngine/optimizer/rules/validateScannable.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Rule R8: scan validation.
+ *
+ * After all pushdowns, we walk every Scan in the plan and check that the
+ * Resource API will accept the resulting target. Specifically: if no usable
+ * index condition was pushed (and `allowFullScan` is off in config), we
+ * throw EngineUnsupportedError naming the offending scan so the router can
+ * fall back to legacy in 'auto' mode.
+ *
+ * Phase 1 keeps the check loose: any pushedFilter that maps to at least one
+ * Resource API condition with an indexed attribute is sufficient. Filtering
+ * decisions sit in optimizer/whereToConditions.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateScannable = validateScannable;
+const errors_ts_1 = require("../../errors.js");
+const whereToConditions_ts_1 = require("../whereToConditions.js");
+const config_ts_1 = require("../../config.js");
+function validateScannable(plan) {
+    const cfg = (0, config_ts_1.getSqlEngineConfig)();
+    walk(plan, cfg.allowFullScan);
+    return null;
+}
+function walk(plan, allowFullScan) {
+    if (plan.kind === 'Scan') {
+        validateScan(plan, allowFullScan);
+        return;
+    }
+    if ('input' in plan)
+        walk(plan.input, allowFullScan);
+    if ('left' in plan)
+        walk(plan.left, allowFullScan);
+    if ('right' in plan)
+        walk(plan.right, allowFullScan);
+}
+function validateScan(scan, allowFullScan) {
+    if (allowFullScan)
+        return;
+    // Inner side of an index-nested-loop join: served by a per-outer-row indexed
+    // equality probe, not a standalone scan.
+    if (scan.joinProbe)
+        return;
+    // whereToConditions, given the table's attributes, pushes only conditions on
+    // indexed attributes (unindexed predicates are residualized into a post-scan
+    // Filter). The scan is valid only if at least one pushed condition can drive
+    // an index seek/range — a lone full-scan comparator (e.g. LIKE→contains) or a
+    // pushed sort is treated by Table.search as needFullScan and rejected under
+    // allowFullScan:false, so reject here too and let 'auto' fall back to legacy.
+    const { conditions } = (0, whereToConditions_ts_1.whereToConditions)(scan.pushedFilter, scan.boundTable?.attributes);
+    if (conditions.some((c) => (0, whereToConditions_ts_1.conditionUsesIndex)(c, scan.boundTable?.attributes)))
+        return;
+    // A sort pushed onto an indexed attribute drives the scan via the index's
+    // natural order (D-219): rows stream ordered from the index and a pushed LIMIT
+    // early-terminates, so it's a valid scan even with no index-driving predicate.
+    if ((0, whereToConditions_ts_1.sortDrivesIndex)(scan.pushedSort, scan.boundTable?.attributes))
+        return;
+    throw new errors_ts_1.EngineUnsupportedError(`scan on "${scan.table.database}.${scan.table.table}" has no usable index condition`, scan.pushedFilter);
+}
+//# sourceMappingURL=validateScannable.js.map

package/dist/sqlEngine/optimizer/rules/validateScannable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateScannable.js","sourceRoot":"","sources":["../../../../sqlEngine/optimizer/rules/validateScannable.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAOH,8CAIC;AARD,+CAAyD;AACzD,kEAAiG;AACjG,+CAAqD;AAErD,SAAgB,iBAAiB,CAAC,IAAiB;IAClD,MAAM,GAAG,GAAG,IAAA,8BAAkB,GAAE,CAAC;IACjC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;IAC9B,OAAO,IAAI,CAAC;AACb,CAAC;AAED,SAAS,IAAI,CAAC,IAAiB,EAAE,aAAsB;IACtD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC1B,YAAY,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAClC,OAAO;IACR,CAAC;IACD,IAAI,OAAO,IAAI,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACrD,IAAI,MAAM,IAAI,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACnD,IAAI,OAAO,IAAI,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,YAAY,CAAC,IAAiB,EAAE,aAAsB;IAC9D,IAAI,aAAa;QAAE,OAAO;IAC1B,6EAA6E;IAC7E,yCAAyC;IACzC,IAAI,IAAI,CAAC,SAAS;QAAE,OAAO;IAC3B,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,MAAM,EAAE,UAAU,EAAE,GAAG,IAAA,wCAAiB,EAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACzF,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,yCAAkB,EAAC,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAAE,OAAO;IACvF,0EAA0E;IAC1E,+EAA+E;IAC/E,+EAA+E;IAC/E,IAAI,IAAA,sCAAe,EAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC;QAAE,OAAO;IAC1E,MAAM,IAAI,kCAAsB,CAC/B,YAAY,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,iCAAiC,EACpF,IAAI,CAAC,YAAY,CACjB,CAAC;AACH,CAAC"}

package/dist/sqlEngine/optimizer/whereToConditions.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Converts a (normalized) WHERE predicate into a Resource API condition tree
+ * plus an optional residual expression that the engine must apply as a
+ * post-scan Filter.
+ *
+ * The Resource API condition shape (see core/resources/search.ts:581):
+ *   { attribute, value, comparator? }
+ *   { conditions: Condition[], operator: 'and'|'or' }
+ *
+ * Comparator names use the canonical forms in
+ * core/resources/search.ts:204 (equals, ne, lt, le, gt, ge, between, gele,
+ * gelt, gtlt, gtle, starts_with, ends_with, contains).
+ *
+ * Anything that can't be represented as a condition (e.g., comparing two
+ * columns, function calls in WHERE, OR mixed with non-attribute predicates)
+ * is left in the residual.
+ */
+import type { ExprNode } from '../parser/ast.ts';
+export interface DirectCondition {
+    attribute?: string;
+    value?: unknown;
+    comparator?: string;
+}
+export interface CompoundCondition {
+    conditions: ConditionNode[];
+    operator: 'and' | 'or';
+}
+export type ConditionNode = DirectCondition | CompoundCondition;
+export interface ConvertResult {
+    conditions: ConditionNode[];
+    operator: 'and' | 'or';
+    residual?: ExprNode;
+}
+export type IndexedAttribute = {
+    name: string;
+    indexed: boolean;
+    isPrimaryKey?: boolean;
+    indexNulls?: boolean;
+};
+export declare function whereToConditions(predicate: ExprNode | undefined, attributes?: IndexedAttribute[]): ConvertResult;
+/**
+ * Whether a condition can be pushed into Table.search at all: every attribute it
+ * references must be indexed, because search runs searchByIndex per condition and
+ * throws on an unindexed attribute. Comparator-agnostic — a full-scan comparator
+ * on an indexed attribute is still pushable (it becomes a filter once another
+ * condition drives the index). Null-valued conditions (IS [NOT] NULL and the
+ * `!=`/NOT IN not-null guards) are pushable only when the index actually indexes
+ * nulls — search throws "not indexed for nulls" otherwise (F-145), even when a
+ * different condition drives the scan. Unpushable conditions become a residual
+ * Filter (the expression evaluator's three-valued logic keeps NULL exclusion
+ * correct on the residual path).
+ */
+export declare function conditionIsPushable(cond: ConditionNode, attributes: IndexedAttribute[] | undefined): boolean;
+/**
+ * Whether a condition can *drive* an index scan (seek/range), and therefore make
+ * the scan valid without a full-table traversal. Stricter than pushability:
+ * excludes full-scan comparators and unseekable inequalities. Shared with the R8
+ * validateScannable rule so scannability and pushdown decisions can't drift.
+ */
+export declare function conditionUsesIndex(cond: ConditionNode, attributes: IndexedAttribute[] | undefined): boolean;
+/**
+ * Whether a pushed sort can itself drive an index-ordered scan: its primary key
+ * is a single column on the table's PRIMARY KEY. Table.search aligns such a sort
+ * to the index's natural order (resources/Table.ts — it adds a `comparator:
+ * 'sort'` condition), so the rows stream from the index already ordered and a
+ * pushed LIMIT early-terminates (O(window)) — no separate in-memory sort. Shared
+ * by the R8 validateScannable rule and the physical scan builder so scannability
+ * and the `allowFullScan` flag can't drift. NOTE: because Table.search flags the
+ * sort scan as `needFullScan`, the physical scan must pass `allowFullScan: true`
+ * for it — see physicalIndexScan.
+ *
+ * Restricted to the PRIMARY KEY, because only there does index order provably
+ * equal legacy's full-scan-then-stable-sort order. A non-PK secondary index
+ * diverges from legacy in two ways (D-219): (1) a DESC sort reverses the whole
+ * composite `[value, primaryKey]` entry, so rows tying on `value` come back in
+ * primary-key-DESC order, whereas legacy's stable sort preserves primary-key-ASC
+ * order for ties; and (2) the secondary index omits rows whose sort attribute is
+ * null (they were never indexed), whereas a legacy full scan includes them. The
+ * PK is unique (no ties) and always present (no null keys), so its ordered scan
+ * matches legacy in both directions. Secondary-index sort streaming can be a
+ * follow-up once those two divergences are handled.
+ */
+export declare function sortDrivesIndex(pushedSort: {
+    expr: ExprNode;
+}[] | undefined, attributes: IndexedAttribute[] | undefined): boolean;