querylens 0.1.0

package/dist/src/engine/planner/emit.js

@@ -0,0 +1,267 @@
+import { buildAggregatePlan, buildJoinPlan, buildPlan, distinctNodeFor, isAggregateQuery, projectListFor } from "./buildPlan.js";
+import { estimatePlan, rootEstimate } from "./cost.js";
+import { costOfOrder, joinGraphFromAst, runJoinOrderDP, writtenOrderFromAst } from "./joinOrder.js";
+import { OPTIMIZER_RULES, leftmostPrefixNote, optimize } from "./optimize.js";
+import { exprToSql, joinsIn, subqueryResolutionNotes, toPlanDisplay } from "./plan.js";
+/**
+ * Emits the planner and optimizer stages, and returns the final plan for the
+ * executor to run. The plan is built bottom-up one operator at a time so the
+ * tree can be watched growing, the same way the AST was.
+ *
+ * Every emitted tree carries the cost model's per-node estimates (plan.md
+ * §22.2), which is also why `rowsPerPage` is threaded down: a scan's estimated
+ * page count depends on it. `joinTables` is every `JOIN`'d table's own data,
+ * keyed by name, needed only so the cost model can estimate that side of each
+ * `Join` too — `undefined` for every query without one.
+ */
+/** Does any node of `plan` read through an index? */
+function usesIndex(plan) {
+    if (plan.op === 'IndexScan' || plan.op === 'IndexRangeScan' || plan.op === 'IndexOnlyScan' || plan.op === 'IndexProbe')
+        return true;
+    if (plan.op === 'Join')
+        return usesIndex(plan.left) || usesIndex(plan.right);
+    return 'child' in plan ? usesIndex(plan.child) : false;
+}
+/** A join algorithm as a phrase for the "nothing to rewrite" note. */
+function describeJoin(algorithm, outer, inner) {
+    switch (algorithm) {
+        case 'hash':
+            return 'a hash join over two full scans';
+        case 'sort-merge':
+            return 'a sort-merge join over two full scans';
+        case 'index-nested-loop':
+            return `an index nested-loop join — a full scan of ${outer}, then a B+Tree probe of ${inner} for each row`;
+        case 'nested-loop':
+            return 'a nested-loop join over two full scans';
+    }
+}
+export function emitPlanEvents(emit, ast, table, rowsPerPage, aggregateStrategy = 'hash', joinTables, 
+/**
+ * `undefined` (the shipped default, plan.md §25.4 C5 slice 2) means every `JOIN`'s algorithm is chosen by
+ * cost — `join-algorithm-selection` runs in the optimize stage below. An explicit value means the caller is
+ * forcing one, `/compare`'s and `/tools/planner`'s whole reason for setting this at all, and that rule is left
+ * out of `enabled` entirely so it can never override the forced choice. Either way the plan stage below still
+ * builds every step structurally as `nested-loop` first, the same cost-oblivious starting point a bare `SeqScan`
+ * already is for `index-selection` — only `structuralJoinStrategy` (the resolved, concrete value) drives it.
+ */
+joinStrategy, 
+/**
+ * The table order this query was actually *typed* in — passed only when real execution (plan.md §25.4 C5
+ * slice 3) chose a different one, in which case `ast.from`/`ast.joins` below already reflect the chosen order,
+ * not the written one; `runQuery.ts`'s `applyCostOrder` is the only caller that ever sets this.
+ */
+writtenJoinOrder) {
+    const structuralJoinStrategy = joinStrategy ?? 'nested-loop';
+    // Every table this query names, keyed by name — including `table` itself. A single join only ever needed the
+    // *other* one (the recursion's own `table` param always being the right one to check first), but a chain
+    // (plan.md §25.4 C3 slice b) re-derives that check at every nesting level against whatever table THAT level's
+    // own `Join` node concerns — which is `table` (the original FROM table) again once the recursion reaches the
+    // bottom of the chain — so `table.name` has to resolve through this same map at every depth, not just the top.
+    const otherTables = joinTables && Object.keys(joinTables).length > 0 ? { ...joinTables, [table.name]: table } : undefined;
+    const display = (plan, changed) => toPlanDisplay(plan, changed, estimatePlan(plan, table, rowsPerPage, otherTables));
+    const leftScan = { op: 'SeqScan', table: ast.from.name };
+    // Said up front, before the trace below starts naming a different FROM table than the one typed (plan.md
+    // §25.4 C5 slice 3): real execution reordered this chain because it was honestly cheaper to.
+    if (writtenJoinOrder && writtenJoinOrder.length >= 2 && joinTables) {
+        const allTables = { ...joinTables, [table.name]: table };
+        const { nodes, edges } = joinGraphFromAst(ast, allTables, rowsPerPage);
+        const chosenOrder = [ast.from.name, ...(ast.joins ?? []).map((j) => j.table.name)];
+        const writtenCost = costOfOrder(nodes, edges, writtenJoinOrder);
+        const chosenCost = costOfOrder(nodes, edges, chosenOrder);
+        const ratio = writtenCost.pages / Math.max(1, chosenCost.pages);
+        emit(`This query's JOINs run in a different order than written (plan.md §25.4 C5 slice 3): a cost-based join-order search chose \`${chosenOrder.join(' → ')}\` over the written \`${writtenJoinOrder.join(' → ')}\` — an estimated ${String(chosenCost.pages)} pages against ${String(writtenCost.pages)}, about ${ratio.toFixed(1)}× cheaper. Unlike the algorithm each step runs (plan.md §25.4 C5 slice 2), there is no "declines but stays" version of this: every left-deep order of the same tables returns the same rows, so the cheaper one always wins.`, {
+            stage: 'plan',
+            planTree: display(leftScan),
+            whyNot: {
+                chosen: { label: chosenOrder.join(' → '), estPages: chosenCost.pages },
+                runnerUp: { label: writtenJoinOrder.join(' → '), estPages: writtenCost.pages },
+            },
+        });
+    }
+    emit(`Start at the bottom: every plan begins by reading a table, so the base of the tree is a sequential scan of \`${ast.from.name}\`.`, { stage: 'plan', planTree: display(leftScan) });
+    let current = leftScan;
+    const allJoins = ast.joins ?? [];
+    for (let i = 0; i < allJoins.length; i++) {
+        const join = allJoins[i];
+        // Rebuilt from scratch each step (cheap — a handful of tables at most) rather than grown incrementally, so this
+        // stays the one place that knows how to fold a JOIN chain and never drifts from `buildJoinPlan` itself.
+        current = buildJoinPlan(allJoins.slice(0, i + 1), ast.from.name, structuralJoinStrategy, joinTables);
+        const j = current;
+        const algorithm = j.algorithm;
+        // Asked for an index join, but this step's inner table has no index on the join column: say so, and run the plain one.
+        const fallback = structuralJoinStrategy === 'index-nested-loop' && algorithm !== 'index-nested-loop'
+            ? `You asked for an index nested-loop join, but \`${join.table.name}\` has no index on \`${j.rightColumn}\` for it to probe — so this runs as an ordinary nested-loop. `
+            : '';
+        const mechanism = algorithm === 'index-nested-loop'
+            ? `for every row \`${j.leftTable}\` produces, it descends \`${j.rightTable}\`'s B+Tree on \`${j.rightColumn}\` with that row's \`${j.leftColumn}\` — a few page reads per outer row instead of a rescan of the whole inner table, which is why a small outer over a big indexed inner is where this algorithm wins`
+            : algorithm === 'hash'
+                ? `it builds an in-memory hash table over all of \`${j.rightTable}\`, keyed on \`${j.rightColumn}\`, once — then probes it with each \`${j.leftTable}\` row's \`${j.leftColumn}\`, reading \`${j.rightTable}\` exactly once regardless of how many rows \`${j.leftTable}\` has`
+                : algorithm === 'sort-merge'
+                    ? `it sorts both \`${j.leftTable}\` and \`${j.rightTable}\` on the join key, then merges the two sorted lists in a single pass — no per-row rescan and no table held in memory, at the cost of sorting both sides first`
+                    : `for every row \`${j.leftTable}\` produces, it rescans all of \`${j.rightTable}\` looking for a match on \`${j.leftColumn}\` = \`${j.rightColumn}\` — nested-loop, the simplest join algorithm, and the most expensive once neither side has an index to speed the inner scan up`;
+        const outer = join.joinType === 'left'
+            ? ` This is a LEFT JOIN: every row from \`${j.leftTable}\` survives even when nothing on \`${j.rightTable}\` matches it, with \`${j.rightTable}\`'s columns NULL.`
+            : '';
+        emit(`${fallback}JOIN adds ${algorithm === 'index-nested-loop' ? 'an index probe on' : 'a second scan of'} \`${j.rightTable}\` and a Join above ${i === 0 ? 'that' : 'the chain so far'}: ${mechanism}.${outer}`, { stage: 'plan', planTree: display(current) });
+    }
+    // A second opinion on join *order* (plan.md §25.4 C4), for two or more JOINs only — a single one has no other
+    // order to consider, and a chain `writtenJoinOrder` already reordered for real has nothing left to say here
+    // (the note above already said it). Otherwise informational: this never changes `current` or what actually
+    // executes, only what gets said about it — the same "estimate beside the real plan, never a decision" stance
+    // C1's stats and C2's q-error already take, and (plan.md §25.4 C5 slice 3) still the only stance a chain with a
+    // `LEFT JOIN` in it ever gets, since that is never reordered for real. `/tools/join-order` is the same search,
+    // with the whole subset lattice visible.
+    if (allJoins.length >= 2 && joinTables && !writtenJoinOrder) {
+        const allTables = { ...joinTables, [table.name]: table };
+        const { nodes, edges } = joinGraphFromAst(ast, allTables, rowsPerPage);
+        const dp = runJoinOrderDP(nodes, edges);
+        const written = writtenOrderFromAst(ast);
+        const writtenCost = costOfOrder(nodes, edges, written);
+        const ratio = writtenCost.pages / dp.winner.pages;
+        const hasLeftJoin = allJoins.some((j) => j.joinType === 'left');
+        emit(ratio >= 1.05
+            ? `A cost-based join-order search (plan.md §25.4 C4) would instead join these ${String(nodes.length)} tables as ${dp.winner.tables.join(' → ')}: an estimated ${String(dp.winner.pages)} pages, against the ${String(writtenCost.pages)} the order actually written above costs — about ${ratio.toFixed(1)}× cheaper.${hasLeftJoin
+                ? ' This chain is never reordered for real (plan.md §25.4 C5 slice 3): a LEFT JOIN is not commutative or associative in general, so the order above is what actually runs.'
+                : ' This query still runs in the order it was written; nothing here changes that.'}`
+            : `A cost-based join-order search (plan.md §25.4 C4) agrees with the order written above — among left-deep orderings of these ${String(nodes.length)} tables, this is already about as cheap as it gets.`, {
+            stage: 'plan',
+            planTree: display(current),
+            ...(ratio >= 1.05
+                ? {
+                    whyNot: {
+                        chosen: { label: written.join(' → '), estPages: writtenCost.pages },
+                        runnerUp: { label: dp.winner.tables.join(' → '), estPages: dp.winner.pages },
+                    },
+                }
+                : {}),
+        });
+    }
+    if (ast.where) {
+        current = { op: 'Filter', predicate: ast.where, child: current };
+        const subqueryNotes = subqueryResolutionNotes(ast.where);
+        emit(`The WHERE clause becomes a Filter sitting above the scan: \`${exprToSql(ast.where)}\`.${subqueryNotes.length > 0 ? ` ${subqueryNotes.map((n) => `${n[0].toUpperCase()}${n.slice(1)}.`).join(' ')}` : ''}`, { stage: 'plan', planTree: display(current) });
+    }
+    if (isAggregateQuery(ast)) {
+        current = buildAggregatePlan(ast, current, aggregateStrategy);
+        const groupBy = ast.groupBy?.columns.map((c) => c.name) ?? [];
+        const aggregateLabels = current.op === 'HashAggregate' || current.op === 'SortAggregate'
+            ? current.aggregates.map((a) => a.key).join(', ')
+            : '';
+        const nodeName = aggregateStrategy === 'sort' ? 'SortAggregate' : 'HashAggregate';
+        const mechanism = aggregateStrategy === 'sort'
+            ? `by sorting on ${groupBy.join(', ') || 'nothing'} first — spilling through the buffer pool exactly as ORDER BY's Sort does — then collapsing runs of equal keys in one pass`
+            : 'with a hash table keyed on the group';
+        emit(groupBy.length > 0
+            ? `GROUP BY becomes a ${nodeName} above that: rows are grouped by ${groupBy.join(', ')}${aggregateLabels ? `, computing ${aggregateLabels} per group` : ''}, ${mechanism}. Like Sort, it cannot produce a row until it has seen every one — the last group is not known to be complete until the input runs out.`
+            : `${aggregateLabels} becomes a ${nodeName} above that: with no GROUP BY, the whole table is one group, so it collapses every row into one${aggregateStrategy === 'sort' ? ', sorting first even though there is only ever one group to produce' : ''}. Like Sort, it cannot produce a row until it has seen all of them.`, { stage: 'plan', planTree: display(current) });
+    }
+    if (ast.having) {
+        current = { op: 'Having', predicate: ast.having, child: current };
+        emit(`HAVING becomes a Having filter above the aggregate: \`${exprToSql(ast.having)}\` is tested on each finished group, after its aggregates are computed. That is the difference from WHERE, which filters rows *before* they are grouped and so can never mention an aggregate.`, { stage: 'plan', planTree: display(current) });
+    }
+    if (ast.orderBy) {
+        current = {
+            op: 'Sort',
+            column: ast.orderBy.column,
+            direction: ast.orderBy.direction,
+            child: current,
+        };
+        emit(`ORDER BY becomes a Sort above that: every row, ordered by \`${ast.orderBy.column}\` ${ast.orderBy.direction === 'asc' ? 'ascending' : 'descending'}. Unlike everything below it, Sort cannot produce a row until it has seen all of them.`, { stage: 'plan', planTree: display(current) });
+    }
+    const columns = projectListFor(ast.select);
+    current = { op: 'Project', columns, child: current };
+    emit(columns.kind === 'star'
+        ? 'The SELECT list becomes a Project on top. `*` keeps every column, so it passes rows through unchanged.'
+        : columns.kind === 'columns'
+            ? `The SELECT list becomes a Project on top, keeping ${columns.names.join(', ')}.`
+            : `The SELECT list becomes a Project on top that *computes* each item for every row: ${columns.items
+                .map((i) => `\`${i.sql}\``)
+                .join(', ')}. Arithmetic on a NULL is NULL, and dividing by zero gives NULL.`, { stage: 'plan', planTree: display(current) });
+    if (ast.distinct) {
+        current = distinctNodeFor(ast, current, aggregateStrategy);
+        emit(aggregateStrategy === 'sort'
+            ? `DISTINCT becomes a SortDistinct above the Project: it sorts every projected row${ast.orderBy ? ` (by \`${ast.orderBy.column}\` first, so your ORDER BY survives)` : ''} — spilling through the buffer pool exactly as ORDER BY's Sort does — so equal rows sit next to each other, then keeps one of each run. Like Sort it cannot produce a row until it has seen all of them.`
+            : 'DISTINCT becomes a HashDistinct above the Project: it remembers every row it has passed in an in-memory hash set and drops a repeat the moment it sees one. It streams — the first new row comes out immediately, and a LIMIT above it can stop the scan early.', { stage: 'plan', planTree: display(current) });
+    }
+    if (ast.limit !== undefined) {
+        const count = ast.limit.value;
+        const offset = ast.limit.offset ?? 0;
+        current = { op: 'Limit', count, ...(offset > 0 ? { offset } : {}), child: current };
+        emit(offset > 0
+            ? `LIMIT ... OFFSET becomes a Limit on top: it discards the first ${plural(offset, 'row')} that come through, then passes ${plural(count, 'row')} and stops. The discarded rows are still produced by everything beneath — an OFFSET saves the client nothing, only the network.`
+            : `LIMIT becomes a Limit on top: it stops pulling rows once ${plural(count, 'row')} ${count === 1 ? 'has' : 'have'} come through — whatever is beneath it is never asked for the rest.`, { stage: 'plan', planTree: display(current) });
+    }
+    // The canonical plan is a direct translation of the query text. Everything
+    // below is the optimizer earning its keep.
+    const canonical = buildPlan(ast, aggregateStrategy, structuralJoinStrategy, joinTables);
+    let optimised = canonical;
+    let before = canonical;
+    // `join-algorithm-selection` is the one rule left out when the caller forced a specific `joinStrategy` — see
+    // this function's own parameter doc above.
+    const enabledRules = joinStrategy === undefined ? new Set(OPTIMIZER_RULES) : new Set(OPTIMIZER_RULES.filter((r) => r !== 'join-algorithm-selection'));
+    for (const step of optimize(canonical, table, rowsPerPage, otherTables ?? {}, enabledRules)) {
+        emit((step.rule === 'index-selection' ||
+            step.rule === 'range-index-selection' ||
+            step.rule === 'index-only-scan') &&
+            step.changed.size > 0
+            ? withCostJustification(step.label, step.plan)
+            : step.label, {
+            stage: 'optimize',
+            rule: step.rule,
+            before: display(before),
+            after: display(step.plan, step.changed),
+            ...(step.whyNot ? { whyNot: step.whyNot } : {}),
+        }, step.prompt ? { predictable: step.prompt } : undefined);
+        before = step.plan;
+        optimised = step.plan;
+    }
+    if (optimised === canonical) {
+        const rows = rootEstimate(canonical, table, rowsPerPage, otherTables).estRows;
+        const chainJoins = joinsIn(canonical);
+        const note = chainJoins.length === 1
+            ? `No rewrite rule applies to this JOIN — ${describeJoin(chainJoins[0].algorithm, chainJoins[0].leftTable, chainJoins[0].rightTable)} is what runs.`
+            : chainJoins.length > 1
+                ? `No rewrite rule applies to this chain of ${String(chainJoins.length)} JOINs — ${chainJoins
+                    .map((j) => `\`${j.leftTable}\` × \`${j.rightTable}\` runs as ${describeJoin(j.algorithm, j.leftTable, j.rightTable)}`)
+                    .join('; ')}.`
+                : ast.where
+                    ? `The cost model estimates about ${plural(rows, 'row')} out of ${String(table.rows.length)}, and no access path beats reading the table.${leftmostPrefixNote(table, ast.where) ? ` ${leftmostPrefixNote(table, ast.where)}` : ''}`
+                    : 'With no WHERE there is nothing to narrow the scan — every row is returned.';
+        emit(`No rewrite rule fires on this plan — the optimizer leaves it exactly as written. ${note}`, {
+            stage: 'optimize',
+            rule: 'none',
+            before: display(canonical),
+            after: display(canonical),
+        });
+    }
+    // Rules fired, but none of them could use an index the table has: if that is because a composite index cannot be
+    // entered, say so here — the "nothing fired" note above never runs once, say, predicate pushdown has.
+    if (optimised !== canonical && allJoins.length === 0 && !usesIndex(optimised)) {
+        const unusable = leftmostPrefixNote(table, ast.where);
+        if (unusable) {
+            emit(`No index is used. ${unusable}`, {
+                stage: 'optimize',
+                rule: 'none',
+                before: display(optimised),
+                after: display(optimised),
+            });
+        }
+    }
+    return optimised;
+    /**
+     * Appends the scan-vs-index page estimate that makes an accepted rewrite's cost visible, not just asserted. Only
+     * ever called for a step that actually changed the plan: `index-selection` and `range-index-selection` already
+     * decline anything that would not be cheaper (plan.md §25.4 C5 — see their own doc comments in `optimize.ts`), and
+     * `index-only-scan` only ever narrows an `IndexScan` the gate already accepted, never chosen on its own, so it can
+     * only be cheaper still. The comparison below is therefore always a confirmation, never a surprise — a second,
+     * independent read of the same numbers `optimize.ts`'s own gate already compared, not a competing judgment.
+     */
+    function withCostJustification(label, chosen) {
+        const scanPages = Math.max(1, Math.ceil(table.rows.length / rowsPerPage));
+        const rows = rootEstimate(canonical, table, rowsPerPage, otherTables).estRows;
+        const indexPages = rootEstimate(chosen, table, rowsPerPage, otherTables).estPages;
+        const facts = `the sequential scan reads all ${String(scanPages)} pages to return about ${plural(rows, 'row')}; the index lookup reads about ${String(indexPages)}`;
+        return `${label} Estimated cost agrees: ${facts}.`;
+    }
+}
+const plural = (n, noun) => `${String(n)} ${noun}${n === 1 ? '' : 's'}`;

package/dist/src/engine/planner/emitDelete.js

@@ -0,0 +1,57 @@
+import { buildDeletePlan } from "./buildPlan.js";
+import { estimatePlan } from "./cost.js";
+import { optimize, WRITE_PATH_RULES } from "./optimize.js";
+import { exprToSql, subqueryResolutionNotes, toPlanDisplay } from "./plan.js";
+/** Strips the throwaway `Project *` wrapper `emitDeletePlanEvents` builds around a delete's scan. */
+function unwrap(plan) {
+    return plan.op === 'Project' ? plan.child : plan;
+}
+/**
+ * Emits the plan/optimize stages for a `DELETE`, and returns the final access
+ * plan (`SeqScan` or `IndexScan`, whichever the optimizer chose) the executor
+ * uses to find the rows to remove.
+ *
+ * Reuses the same rules a `SELECT` uses — they are written against
+ * `Project → …`, so the scan is wrapped in a throwaway `Project *` for the
+ * optimizer's sake, and every tree shown to the reader has that wrapper
+ * stripped again: nothing about a `DELETE` cares what columns a `Project`
+ * would keep. `WRITE_PATH_RULES` excludes `range-index-selection` specifically
+ * — see its own doc comment in `optimize.ts` — so the plan this returns is
+ * always a `SeqScan` or a single-row `IndexScan`, the two shapes
+ * `executeDelete` (`exec/delete.ts`) knows how to run.
+ */
+export function emitDeletePlanEvents(emit, ast, table, rowsPerPage) {
+    const display = (plan, changed) => toPlanDisplay(unwrap(plan), changed, estimatePlan(unwrap(plan), table, rowsPerPage));
+    const scan = { op: 'SeqScan', table: ast.from.name };
+    emit(`Start at the bottom: every plan begins by reading a table, so the base of the tree is a sequential scan of \`${ast.from.name}\`.`, { stage: 'plan', planTree: display(scan) });
+    let current = scan;
+    if (ast.where) {
+        current = { op: 'Filter', predicate: ast.where, child: current };
+        const subqueryNotes = subqueryResolutionNotes(ast.where);
+        emit(`The WHERE clause becomes a Filter sitting above the scan: \`${exprToSql(ast.where)}\` — the rows it passes are the rows DELETE removes.${subqueryNotes.length > 0 ? ` ${subqueryNotes.map((n) => `${n[0].toUpperCase()}${n.slice(1)}.`).join(' ')}` : ''}`, { stage: 'plan', planTree: display(current) });
+    }
+    const canonical = buildDeletePlan(ast);
+    const wrapped = { op: 'Project', columns: { kind: 'star' }, child: canonical };
+    let optimisedWrapped = wrapped;
+    let before = wrapped;
+    for (const step of optimize(wrapped, table, rowsPerPage, {}, WRITE_PATH_RULES)) {
+        emit(step.label, {
+            stage: 'optimize',
+            rule: step.rule,
+            before: display(before),
+            after: display(step.plan, step.changed),
+            ...(step.whyNot ? { whyNot: step.whyNot } : {}),
+        }, step.prompt ? { predictable: step.prompt } : undefined);
+        before = step.plan;
+        optimisedWrapped = step.plan;
+    }
+    if (optimisedWrapped === wrapped) {
+        emit('No rewrite rule fires on this plan — the optimizer leaves it exactly as written.', {
+            stage: 'optimize',
+            rule: 'none',
+            before: display(wrapped),
+            after: display(wrapped),
+        });
+    }
+    return unwrap(optimisedWrapped);
+}

package/dist/src/engine/planner/emitUpdate.js

@@ -0,0 +1,51 @@
+import { buildUpdatePlan } from "./buildPlan.js";
+import { estimatePlan } from "./cost.js";
+import { optimize, WRITE_PATH_RULES } from "./optimize.js";
+import { exprToSql, subqueryResolutionNotes, toPlanDisplay } from "./plan.js";
+/** Strips the throwaway `Project *` wrapper `emitUpdatePlanEvents` builds around an update's scan. */
+function unwrap(plan) {
+    return plan.op === 'Project' ? plan.child : plan;
+}
+/**
+ * Emits the plan/optimize stages for an `UPDATE`, and returns the final
+ * access plan (`SeqScan` or `IndexScan`) the executor uses to find the rows
+ * to modify — the mirror of `emitDeletePlanEvents`, since only the WHERE
+ * clause is planned; the SET clause has nothing for a plan or an optimizer
+ * rule to act on. Uses `WRITE_PATH_RULES` for the same reason
+ * `emitDeletePlanEvents` does — see its own doc comment.
+ */
+export function emitUpdatePlanEvents(emit, ast, table, rowsPerPage) {
+    const display = (plan, changed) => toPlanDisplay(unwrap(plan), changed, estimatePlan(unwrap(plan), table, rowsPerPage));
+    const scan = { op: 'SeqScan', table: ast.table.name };
+    emit(`Start at the bottom: every plan begins by reading a table, so the base of the tree is a sequential scan of \`${ast.table.name}\`.`, { stage: 'plan', planTree: display(scan) });
+    let current = scan;
+    if (ast.where) {
+        current = { op: 'Filter', predicate: ast.where, child: current };
+        const subqueryNotes = subqueryResolutionNotes(ast.where);
+        emit(`The WHERE clause becomes a Filter sitting above the scan: \`${exprToSql(ast.where)}\` — the rows it passes are the rows UPDATE modifies.${subqueryNotes.length > 0 ? ` ${subqueryNotes.map((n) => `${n[0].toUpperCase()}${n.slice(1)}.`).join(' ')}` : ''}`, { stage: 'plan', planTree: display(current) });
+    }
+    const canonical = buildUpdatePlan(ast);
+    const wrapped = { op: 'Project', columns: { kind: 'star' }, child: canonical };
+    let optimisedWrapped = wrapped;
+    let before = wrapped;
+    for (const step of optimize(wrapped, table, rowsPerPage, {}, WRITE_PATH_RULES)) {
+        emit(step.label, {
+            stage: 'optimize',
+            rule: step.rule,
+            before: display(before),
+            after: display(step.plan, step.changed),
+            ...(step.whyNot ? { whyNot: step.whyNot } : {}),
+        }, step.prompt ? { predictable: step.prompt } : undefined);
+        before = step.plan;
+        optimisedWrapped = step.plan;
+    }
+    if (optimisedWrapped === wrapped) {
+        emit('No rewrite rule fires on this plan — the optimizer leaves it exactly as written.', {
+            stage: 'optimize',
+            rule: 'none',
+            before: display(wrapped),
+            after: display(wrapped),
+        });
+    }
+    return unwrap(optimisedWrapped);
+}

package/dist/src/engine/planner/index.js

@@ -0,0 +1,8 @@
+export { buildAggregatePlan, buildDeletePlan, buildJoinPlan, distinctNodeFor, effectiveJoinAlgorithm, buildPlan, buildUpdatePlan, isAggregateQuery, } from "./buildPlan.js";
+export { boundedRangeSelectivity, estimateIndexLevels, estimatePlan, ndistinct, NO_STATS_EQ_SELECTIVITY, OPEN_RANGE_SELECTIVITY, rootEstimate, selectivityOf, } from "./cost.js";
+export { emitPlanEvents } from "./emit.js";
+export { emitDeletePlanEvents } from "./emitDelete.js";
+export { emitUpdatePlanEvents } from "./emitUpdate.js";
+export { costOfOrder, isReorderableChain, joinGraphFromAst, rebuildJoinsForOrder, reorderJoinsIfCheaper, runJoinOrderDP, writtenOrderFromAst, } from "./joinOrder.js";
+export { optimize, OPTIMIZER_RULES, scanPredicate, WRITE_PATH_RULES } from "./optimize.js";
+export { childOf, conjoin, conjuncts, equalityOn, exprToSql, findIndexNestedLoopJoins, findSort, findSortDistinct, findSortMergeJoins, formatRangeBounds, indexLabel, joinsIn, lookupKeysOf, lookupText, needsSortSpill, rangeOn, toPlanDisplay, } from "./plan.js";

package/dist/src/engine/planner/joinOrder.js

@@ -0,0 +1,252 @@
+/**
+ * Selinger-style join ordering by dynamic programming (plan.md §25.4 C4), over the **subset lattice**: for `n`
+ * tables there are `2^n - 1` non-empty subsets, and the cheapest way to join every table in a subset is built up
+ * from the cheapest way to join every smaller subset one table down — bottom-up, smallest subsets first, exactly
+ * the textbook System R algorithm (Selinger et al., 1979).
+ *
+ * Restricted to **left-deep** orderings on purpose: the engine's own `Join` operator (plan.md §25.4 C3 slice b)
+ * only ever executes a left-deep chain, so a bushy plan this module might otherwise consider is one the engine
+ * could never actually run. That restriction is also what keeps this simple — a subset's own best plan is just
+ * "which table was added last," not "which two smaller subsets were merged," so there is no need to search which
+ * way to *split* a subset, only which single table to peel off it.
+ *
+ * A **cross join is never forbidden**, only costed honestly: when two tables share no join predicate, joining
+ * them anyway (`rows(a) × rows(b)`, no selectivity) is a real, always-available option — it just loses the cost
+ * comparison so badly that the DP never picks it unless the graph genuinely offers nothing better. Nothing here
+ * needs to reason about the join graph's connectivity to avoid a cross join; the real cost already does that.
+ *
+ * The cost formula mirrors `cost.ts`'s own `Join` case exactly (nested-loop, the engine's default and the one
+ * algorithm every join order is meaningful for): `pages = left.pages + left.rows × right.pages`, and
+ * `rows = left.rows × right.rows / ndistinct(right's join column)` — see `cost.ts:358-426` for the source this
+ * is kept consistent with. Ordering is deliberately scored on **page cost**, not row count: row count alone
+ * cannot tell two orders with the same output size but very different rescan cost apart.
+ *
+ * Visualization-only when it was built (plan.md §25.4 C4's own scoping decision) — `/tools/join-order` and the
+ * Playground's informational note only ever *showed* what this function would have chosen. **Plan.md §25.4 C5
+ * slice 3 changes that for one well-scoped case**: `runQuery.ts` now actually reorders a chain of 2+ `JOIN`s
+ * before running it, *when every one is a plain inner join* — `reorderJoinsIfCheaper` below, and
+ * `rebuildJoinsForOrder`, which it's built on. A chain with any `LEFT JOIN` is never reordered: `LEFT JOIN` is
+ * not commutative or associative in general (`A LEFT JOIN B` keeps every `A` row regardless of `B`; flipping it,
+ * or moving another join between them, can change which rows get NULL-padded and when), and generalizing this
+ * DP to respect that would mean tracking a partial order among the steps, not just their cost — a materially
+ * different, harder problem this module does not attempt. For an eligible chain, this is the real, final order,
+ * not a second opinion — `/tools/join-order` and the note both still exist, but only ever have something to
+ * *show* (rather than something that already ran) when a `LEFT JOIN` keeps a chain out of scope.
+ */
+import { ndistinct } from "./cost.js";
+const clampRows = (value) => Math.max(0, Math.round(value));
+const popcount = (mask) => {
+    let count = 0;
+    for (let m = mask; m !== 0; m >>>= 1)
+        count += m & 1;
+    return count;
+};
+/**
+ * Runs the DP. `nodes` must be non-empty; a single table has nothing to order and returns immediately with one
+ * singleton subset. Capped implicitly by `2^nodes.length` states — teaching-sized graphs only (plan.md's own
+ * datasets never approach the twenty-ish tables where this would start to matter).
+ */
+export function runJoinOrderDP(nodes, edges) {
+    const n = nodes.length;
+    if (n === 0)
+        throw new Error('unreachable: runJoinOrderDP needs at least one table');
+    const nodeNames = nodes.map((t) => t.name);
+    const indexOf = new Map(nodeNames.map((name, i) => [name, i]));
+    // An edge is undirected for lookup purposes — keyed by the pair of bit indices, lowest first.
+    const edgeFor = new Map();
+    for (const e of edges) {
+        const ia = indexOf.get(e.a);
+        const ib = indexOf.get(e.b);
+        if (ia === undefined || ib === undefined)
+            continue; // an edge naming a table outside `nodes` is simply unusable
+        edgeFor.set(`${String(Math.min(ia, ib))}-${String(Math.max(ia, ib))}`, e);
+    }
+    const subsets = new Map();
+    for (let i = 0; i < n; i++) {
+        const t = nodes[i];
+        const mask = 1 << i;
+        subsets.set(mask, { mask, tables: [t.name], rows: t.rows, pages: t.pages, candidates: [] });
+    }
+    const masksBySize = Array.from({ length: n + 1 }, () => []);
+    for (let mask = 1; mask < 1 << n; mask++)
+        masksBySize[popcount(mask)].push(mask);
+    for (let size = 2; size <= n; size++) {
+        for (const mask of masksBySize[size]) {
+            const candidates = [];
+            for (let i = 0; i < n; i++) {
+                const bit = 1 << i;
+                if (!(mask & bit))
+                    continue;
+                const prevMask = mask & ~bit;
+                const prev = subsets.get(prevMask);
+                if (!prev)
+                    continue; // unreachable: every smaller mask is filled before this size runs
+                const t = nodes[i];
+                // The cheapest real join predicate connecting `t` to anything already in `prevMask` — there may be
+                // several (a star-shaped graph can have `t` adjacent to more than one table already joined in).
+                let viaEdge = null;
+                for (let j = 0; j < n; j++) {
+                    if (!(prevMask & (1 << j)))
+                        continue;
+                    const edge = edgeFor.get(`${String(Math.min(i, j))}-${String(Math.max(i, j))}`);
+                    if (!edge)
+                        continue;
+                    const tDistinct = edge.a === t.name ? edge.aNdistinct : edge.bNdistinct;
+                    const rows = clampRows((prev.rows * t.rows) / Math.max(1, tDistinct));
+                    if (!viaEdge || rows < viaEdge.rows)
+                        viaEdge = { rows };
+                }
+                const rows = viaEdge ? viaEdge.rows : clampRows(prev.rows * t.rows);
+                const pages = prev.pages + prev.rows * t.pages;
+                candidates.push({ addedTable: t.name, viaEdge: viaEdge !== null, rows, pages });
+            }
+            candidates.sort((a, b) => a.pages - b.pages);
+            const winner = candidates[0];
+            const winnerBit = 1 << indexOf.get(winner.addedTable);
+            const prevPlan = subsets.get(mask & ~winnerBit);
+            subsets.set(mask, {
+                mask,
+                tables: [...prevPlan.tables, winner.addedTable],
+                rows: winner.rows,
+                pages: winner.pages,
+                candidates,
+            });
+        }
+    }
+    const fullMask = (1 << n) - 1;
+    return { nodeNames, subsets, winner: subsets.get(fullMask) };
+}
+/**
+ * The same cost formula `runJoinOrderDP` searches with, applied to one *specific* order instead of searching for
+ * the cheapest one — how much a query's own, as-written join order actually costs, for comparison against the
+ * DP's own suggestion. `order` must name every one of `nodes` exactly once; the first is the base scan.
+ */
+export function costOfOrder(nodes, edges, order) {
+    const byName = new Map(nodes.map((t) => [t.name, t]));
+    const edgeFor = new Map();
+    for (const e of edges) {
+        edgeFor.set(`${e.a}-${e.b}`, e);
+        edgeFor.set(`${e.b}-${e.a}`, e);
+    }
+    const first = byName.get(order[0]);
+    let rows = first.rows;
+    let pages = first.pages;
+    const soFar = [order[0]];
+    for (let k = 1; k < order.length; k++) {
+        const t = byName.get(order[k]);
+        let bestRows = null;
+        for (const prevName of soFar) {
+            const edge = edgeFor.get(`${prevName}-${t.name}`);
+            if (!edge)
+                continue;
+            const tDistinct = edge.a === t.name ? edge.aNdistinct : edge.bNdistinct;
+            const candidateRows = clampRows((rows * t.rows) / Math.max(1, tDistinct));
+            if (bestRows === null || candidateRows < bestRows)
+                bestRows = candidateRows;
+        }
+        pages = pages + rows * t.pages;
+        rows = bestRows ?? clampRows(rows * t.rows);
+        soFar.push(t.name);
+    }
+    return { rows, pages };
+}
+/**
+ * Builds the join graph `runJoinOrderDP` needs straight from a parsed, already-resolved multi-join query — the
+ * same table/column resolution `buildJoinPlan` (`buildPlan.ts`) already does per step, just collecting it into a
+ * graph instead of folding it into a left-deep `Plan`. `tables` must have an entry for `ast.from.name` and every
+ * `ast.joins` table name (`runQuery.ts` already resolves exactly this map before planning).
+ */
+export function joinGraphFromAst(ast, tables, rowsPerPage) {
+    const heapPages = (t) => Math.max(1, Math.ceil(t.rows.length / rowsPerPage));
+    const nodeFor = (name) => {
+        const t = tables[name];
+        return { name, rows: t.rows.length, pages: heapPages(t) };
+    };
+    const nodes = [nodeFor(ast.from.name)];
+    const edges = [];
+    for (const join of ast.joins ?? []) {
+        const { left, right } = join.on;
+        if (left.kind !== 'column' || right.kind !== 'column')
+            continue; // unreachable: checkJoinOn guarantees this
+        const newTable = join.table.name;
+        // checkJoinChain already guarantees exactly one side names newTable and the other a table already in scope.
+        const newTableIsLeftOperand = left.table === newTable;
+        const bColumn = newTableIsLeftOperand ? left.name : right.name;
+        const aColumn = newTableIsLeftOperand ? right.name : left.name;
+        const aTable = (newTableIsLeftOperand ? right.table : left.table);
+        nodes.push(nodeFor(newTable));
+        edges.push({
+            a: aTable,
+            aColumn,
+            aNdistinct: ndistinct(tables[aTable], aColumn),
+            b: newTable,
+            bColumn,
+            bNdistinct: ndistinct(tables[newTable], bColumn),
+        });
+    }
+    return { nodes, edges };
+}
+/** The table order a multi-join query was actually *written* in — `FROM`'s table, then each `JOIN` in source order. */
+export function writtenOrderFromAst(ast) {
+    return [ast.from.name, ...(ast.joins ?? []).map((j) => j.table.name)];
+}
+/** A chain real execution may reorder (plan.md §25.4 C5 slice 3): 2+ `JOIN`s, none of them `LEFT`. */
+export function isReorderableChain(ast) {
+    const joins = ast.joins ?? [];
+    return joins.length >= 2 && joins.every((j) => j.joinType !== 'left');
+}
+/**
+ * Rebuilds a valid left-deep `{from, joins}` pair for `order` — normally the DP's own winning order — reusing
+ * every original `JoinClause` exactly as parsed (same `on` expression, same span), just reassigning which table
+ * each one is considered to *introduce*. Sound because the graph `joinGraphFromAst` builds is always a spanning
+ * tree, one edge per non-`FROM` table, drawn straight from that table's own `ON` clause: `buildJoinPlan` only
+ * ever needs, for each step, *some* earlier-known table on the other side of a real equality — never that it be
+ * the immediately preceding one (`leftJoinValue`/`leftJoinKeyOf` already resolve a qualified reference against
+ * the whole chain so far, plan.md §25.4 C3 slice b) — so swapping which side of an unchanged predicate counts as
+ * "newly introduced" is all a reordering ever needs to do. `edges[i]` is `(ast.joins ?? [])[i]`'s own edge,
+ * the exact parallel `joinGraphFromAst` builds them in.
+ *
+ * Returns `null` if some step in `order` has no real edge back to anything earlier in it — this engine's grammar
+ * has no way to express a `JOIN` with no `ON` clause, so an order that would need a cross join can never be built
+ * here. The DP's own cost-minimizing search should never actually choose one on a connected graph (routing
+ * through the real tree is always cheaper), so this is a defensive check, not an expected outcome.
+ */
+export function rebuildJoinsForOrder(ast, edges, order) {
+    const joinList = ast.joins ?? [];
+    const edgeClause = new Map(edges.map((e, i) => [e, joinList[i]]));
+    const edgesByTable = new Map();
+    for (const e of edges) {
+        edgesByTable.set(e.a, [...(edgesByTable.get(e.a) ?? []), e]);
+        edgesByTable.set(e.b, [...(edgesByTable.get(e.b) ?? []), e]);
+    }
+    const refFor = (name) => (name === ast.from.name ? ast.from : edgeClause.get(edgesByTable.get(name)[0]).table);
+    // ^ any of `name`'s own edges names it the same way (every original clause's `table` is that same table's own
+    //   ref, regardless of which edge produced it), so the first is as good as any for recovering its `TableRef`.
+    const visited = new Set([order[0]]);
+    const joins = [];
+    for (let k = 1; k < order.length; k++) {
+        const name = order[k];
+        const edge = (edgesByTable.get(name) ?? []).find((e) => visited.has(e.a === name ? e.b : e.a));
+        if (!edge)
+            return null;
+        joins.push({ ...edgeClause.get(edge), table: refFor(name) });
+        visited.add(name);
+    }
+    return { from: refFor(order[0]), joins };
+}
+/**
+ * The one entry point `runQuery.ts` needs: for an eligible chain (`isReorderableChain`) whose cost-optimal order
+ * differs from how it was written, an `{from, joins}` pair to run instead — `null` when reordering does not apply
+ * (a `LEFT JOIN` somewhere, fewer than two `JOIN`s) or would not actually change anything (the written order is
+ * already the DP's own answer, or — defensively — `rebuildJoinsForOrder` found no real edge for it).
+ */
+export function reorderJoinsIfCheaper(ast, tables, rowsPerPage) {
+    if (!isReorderableChain(ast))
+        return null;
+    const { nodes, edges } = joinGraphFromAst(ast, tables, rowsPerPage);
+    const winner = runJoinOrderDP(nodes, edges).winner;
+    const written = writtenOrderFromAst(ast);
+    if (winner.tables.join('\u0000') === written.join('\u0000'))
+        return null;
+    return rebuildJoinsForOrder(ast, edges, winner.tables);
+}