querylens 0.1.0

package/dist/src/engine/exec/run.js

@@ -0,0 +1,35 @@
+import { resultPrompt } from "../predict.js";
+import { rootEstimate } from "../planner/cost.js";
+import { buildOperator } from "./operators.js";
+/** Pulls the operator tree to exhaustion and emits the result. */
+export function execute(plan, ctx) {
+    const root = buildOperator(plan, ctx);
+    const rows = [];
+    root.open();
+    for (;;) {
+        const row = root.next();
+        if (!row)
+            break;
+        rows.push(row);
+    }
+    root.close();
+    const { hits, misses, evictions } = ctx.pool.stats;
+    // Every table this query names, including `ctx.table` itself — a chain's own cost-model recursion (plan.md
+    // §25.4 C3 slice b) needs to resolve it by name again once it reaches the bottom of the chain, not just at the
+    // top (see emit.ts's identical build for the fuller explanation).
+    const otherTables = ctx.joinPartners
+        ? {
+            ...Object.fromEntries(Object.entries(ctx.joinPartners).map(([name, partner]) => [name, partner.table])),
+            [ctx.table.name]: ctx.table,
+        }
+        : undefined;
+    const estimate = rootEstimate(plan, ctx.table, ctx.options.rowsPerPage, otherTables);
+    const reconcile = estimate.estRows === rows.length
+        ? ` The cost model guessed ~${estimate.estRows} — on the nose (${estimate.basis}).`
+        : ` The cost model guessed ~${estimate.estRows} (${estimate.basis}); the count is exact, the estimate is a heuristic.`;
+    ctx.emit(`${rows.length} row${rows.length === 1 ? '' : 's'} returned, from ${misses} disk read${misses === 1 ? '' : 's'}, ${hits} buffer hit${hits === 1 ? '' : 's'} and ${evictions} eviction${evictions === 1 ? '' : 's'}.${reconcile}`, { stage: 'result', rows }, (() => {
+        const prompt = resultPrompt(rows.length, ctx.table.rows.length);
+        return prompt ? { predictable: prompt } : undefined;
+    })());
+    return rows;
+}

package/dist/src/engine/exec/sort.js

@@ -0,0 +1,171 @@
+/**
+ * The `Sort` operator's own driver: external merge sort over real `Row[]`,
+ * with every page it writes or re-reads flowing through the real buffer pool
+ * (plan.md §22.2) — competing for the same frames a heap scan uses, which is
+ * the whole point of building this rather than calling `Array.prototype.sort`
+ * with a comment.
+ *
+ * The algorithm mirrors the worked example already built for `/tools/sort`
+ * (`src/ui/externalSort.ts`, Ramakrishnan & Gehrke §13.3): `memPages` pages
+ * of records sorted in memory become one run each (pass 0), then every later
+ * pass merges `memPages − 1` runs at a time until one remains.
+ *
+ * Page ids are never reused: each pass writes into its own fresh block, so a
+ * page a later step still needs to read is never silently overwritten by an
+ * earlier one — the property a real spill file gets for free by simply being
+ * a different file. `sortTempPageCount` sizes that reservation; `runQuery.ts`
+ * adds it to the buffer pool's page count before the pool is built, so every
+ * id this module hands out is valid.
+ */
+/** Runs merged per merge step — one buffer page is reserved for the output. */
+function fanInFor(memPages) {
+    return Math.max(2, memPages - 1);
+}
+/** Passes a sort of `pageCount` pages needs: run generation, then merges until one run remains. */
+export function sortPassCount(pageCount, memPages) {
+    const fanIn = fanInFor(memPages);
+    let runCount = Math.max(1, Math.ceil(pageCount / memPages));
+    let passes = 1;
+    while (runCount > 1) {
+        runCount = Math.ceil(runCount / fanIn);
+        passes += 1;
+    }
+    return passes;
+}
+/**
+ * Distinct page ids to reserve for sorting `rowCount` rows: a fresh block per
+ * pass, sized generously above the perfectly-packed page count. Merging
+ * several runs whose own last page is only partly full needs a handful more
+ * once each merge group repacks its own output — the same last-page waste a
+ * real spill file has — so the block leaves `memPages` pages of slack rather
+ * than claim an exact figure it cannot defend (plan.md §12).
+ */
+export function sortTempPageCount(rowCount, rowsPerPage, memPages) {
+    const pageCount = Math.max(1, Math.ceil(rowCount / rowsPerPage));
+    const passes = sortPassCount(pageCount, memPages);
+    return (pageCount + memPages) * passes;
+}
+/**
+ * Total order over `SqlValue`, ascending: numbers numerically, everything
+ * else lexicographically, NULLs last — Postgres's own default, and the
+ * reason `direction: 'desc'` below just negates this rather than re-deriving
+ * a second rule (negating "NULLs last" gives "NULLs first", Postgres's
+ * default there too).
+ */
+function compareAsc(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;
+    const sa = typeof a === 'boolean' ? String(Number(a)) : String(a);
+    const sb = typeof b === 'boolean' ? String(Number(b)) : String(b);
+    return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+/** Writes `rows` to a fresh page, through the pool for the frame bookkeeping and narration. */
+function spillPage(io, spill, nextId, rows) {
+    const pageId = nextId();
+    const result = io.pool.write(pageId);
+    if (result)
+        io.pool.unpin(result.frameId);
+    spill.set(pageId, rows);
+    return pageId;
+}
+/** Reads a spilled page's rows back, through the pool for the same reason. */
+function readPage(io, spill, pageId) {
+    const result = io.pool.fetch(pageId);
+    if (result)
+        io.pool.unpin(result.frameId);
+    return spill.get(pageId) ?? [];
+}
+/** Writes one run's already-sorted rows out, `rowsPerPage` at a time (at least one page, even if empty). */
+function writeRun(io, spill, nextId, id, rows) {
+    if (rows.length === 0)
+        return { id, pages: [spillPage(io, spill, nextId, [])] };
+    const pages = [];
+    for (let i = 0; i < rows.length; i += io.rowsPerPage) {
+        pages.push(spillPage(io, spill, nextId, rows.slice(i, i + io.rowsPerPage)));
+    }
+    return { id, pages };
+}
+/** k-way merge of already-sorted runs, read back page by page through the pool. */
+function mergeRuns(sources, spill, io, cmp) {
+    const rows = sources.map((run) => run.pages.flatMap((pid) => readPage(io, spill, pid)));
+    const heads = rows.map(() => 0);
+    const merged = [];
+    for (;;) {
+        let pick = -1;
+        for (let i = 0; i < rows.length; i++) {
+            if (heads[i] >= rows[i].length)
+                continue;
+            if (pick === -1 || cmp(rows[i][heads[i]], rows[pick][heads[pick]]) < 0)
+                pick = i;
+        }
+        if (pick === -1)
+            break;
+        merged.push(rows[pick][heads[pick]]);
+        heads[pick] += 1;
+    }
+    return merged;
+}
+/**
+ * Runs a full external merge sort and returns the rows in final order. Runs
+ * to completion before returning a single row — `Sort` is the one operator
+ * in this engine that cannot stream, and the narration says so.
+ *
+ * `keyOf` returns a *tuple* — compared lexicographically, left column first —
+ * rather than a single `SqlValue`, so this same driver serves `Sort`'s
+ * one-column `ORDER BY` (a one-element tuple) and `SortAggregate`'s
+ * potentially multi-column `GROUP BY` key without duplicating the algorithm.
+ * `subject` and `op` name the caller in the narration and in the emitted
+ * `execute` events (`'Sort'` by default; `SortAggregate` passes its own name
+ * so its internal sort phase is not mistaken for a top-level `Sort` node).
+ * `table` is `sortMergeJoin`'s own disambiguator (its `Join`'s `rightTable`) passed through so these internal,
+ * zero-row progress pings carry the same `table` as that `Join`'s real `execute` events — otherwise one of these
+ * could land in `explain.ts`'s per-node lookup without the table that identifies which `Join`, in a chain with
+ * more than one, it belongs to. `undefined` for `Sort`/`SortAggregate`/`SortDistinct`, which never repeat.
+ */
+export function externalMergeSort(rows, keyOf, direction, io, subject = 'Sort', op = 'Sort', table) {
+    const cmp = (a, b) => {
+        const ka = keyOf(a);
+        const kb = keyOf(b);
+        for (let i = 0; i < ka.length; i++) {
+            const c = compareAsc(ka[i] ?? null, kb[i] ?? null);
+            if (c !== 0)
+                return direction === 'desc' ? -c : c;
+        }
+        return 0;
+    };
+    const spill = new Map();
+    let cursor = io.base;
+    const nextId = () => cursor++;
+    const fanIn = fanInFor(io.memPages);
+    const chunk = io.memPages * io.rowsPerPage;
+    io.emit(`${subject} has to see every row before it can produce one — the one operator here that cannot stream. ${plural(rows.length, 'row')} to sort, ${plural(io.memPages, 'page')} of memory at a time.`, { stage: 'execute', op, rowsProduced: 0, ...(table === undefined ? {} : { table }) });
+    let runs = [];
+    let runId = 0;
+    for (let i = 0; i < rows.length; i += chunk) {
+        const sorted = [...rows.slice(i, i + chunk)].sort(cmp);
+        runs.push(writeRun(io, spill, nextId, runId++, sorted));
+    }
+    if (runs.length === 0)
+        runs.push(writeRun(io, spill, nextId, runId++, []));
+    const pagesWritten = runs.reduce((n, r) => n + r.pages.length, 0);
+    io.emit(`Run generation: ${plural(runs.length, 'sorted run')} written, ${plural(pagesWritten, 'page')} total.`, { stage: 'execute', op, rowsProduced: 0, ...(table === undefined ? {} : { table }) });
+    let passIndex = 1;
+    while (runs.length > 1) {
+        const next = [];
+        for (let g = 0; g < runs.length; g += fanIn) {
+            const merged = mergeRuns(runs.slice(g, g + fanIn), spill, io, cmp);
+            next.push(writeRun(io, spill, nextId, runId++, merged));
+        }
+        io.emit(`Merge pass ${String(passIndex)}: ${plural(runs.length, 'run')} become ${plural(next.length, 'run')}.`, { stage: 'execute', op, rowsProduced: 0, ...(table === undefined ? {} : { table }) });
+        runs = next;
+        passIndex += 1;
+    }
+    return runs[0].pages.flatMap((pid) => readPage(io, spill, pid));
+}
+const plural = (n, noun) => `${String(n)} ${noun}${n === 1 ? '' : 's'}`;

package/dist/src/engine/exec/unique.js

@@ -0,0 +1,79 @@
+/**
+ * Enforcing `UNIQUE` (plan.md §25.4 B3c). A unique constraint is not a rule checked somewhere else — it *is* an
+ * index lookup: before a new key goes in, the index is asked whether it is already there, and if it is the statement
+ * is rejected. That is why every unique constraint is backed by an index, and why an `INSERT` into a table with one
+ * reads index pages even though it never scans anything. Each check below narrates that lookup, real page reads and
+ * all; on a violation it throws, and `runQuery` turns the throw into the statement's error — no change is made,
+ * because a write's rows only reach the table when the whole statement succeeds.
+ */
+import { rowAt } from "./operators.js";
+import { describeUniqueKey, emitIndexLookup, indexNameOf, indexSpecsOf, keyValuesOf, resolveClustered } from "../index/index.js";
+/** A statement tried to put a key into a unique index that already holds it. */
+export class UniqueViolation extends Error {
+    index;
+    columns;
+    values;
+    holder;
+    constructor(index, columns, values, holder) {
+        super(`duplicate key value violates unique index ${index}`);
+        this.index = index;
+        this.columns = columns;
+        this.values = values;
+        this.holder = holder;
+    }
+}
+/** Asks the unique index whether `values` is already there; throws `UniqueViolation` if it is. */
+function checkKey(ctx, spec, values, statement) {
+    const name = indexNameOf(spec.columns);
+    const tree = ctx.trees[name];
+    if (!tree)
+        return;
+    // A NULL in the key is never equal to another NULL, so it can conflict with nothing: there is nothing to look up.
+    if (values.some((v) => v === null)) {
+        ctx.emit(`The UNIQUE index on \`${name}\` has a NULL in this key, and NULL is not equal to NULL, so it cannot conflict with any entry — no lookup is needed.`, {
+            stage: 'execute',
+            op: statement === 'INSERT' ? 'Insert' : 'Update',
+            rowsProduced: 0,
+        });
+        return;
+    }
+    const key = describeUniqueKey(spec.columns, values);
+    ctx.emit(`${statement} checks the UNIQUE index on \`${name}\` before it changes anything: is there already an entry for ${key}?`, {
+        stage: 'execute',
+        op: statement === 'INSERT' ? 'Insert' : 'Update',
+        rowsProduced: 0,
+    });
+    const outcome = emitIndexLookup(ctx.emit, tree, values, ctx.pool, name, ctx.locks, false, `Found ${key} — the key is already taken, so ${statement} will be rejected.`);
+    if (outcome.pointer) {
+        // On a clustered table's secondary UNIQUE index, `pointer` is a sentinel — the row that has the key needs the
+        // same second descent any other match through this index would (plan.md §25.4 B3e), so the error can still say
+        // which row holds it, not just that one does.
+        const clusterKey = outcome.clusterKeys?.[0];
+        const clusteredTree = tree.clusteredVia !== undefined ? ctx.trees[tree.clusteredVia] : undefined;
+        const holder = clusterKey && clusteredTree
+            ? (resolveClustered(ctx.emit, clusteredTree, tree.clusteredVia, clusterKey, ctx.pool, ctx.locks) ?? outcome.pointer)
+            : outcome.pointer;
+        throw new UniqueViolation(name, spec.columns, values, holder);
+    }
+    ctx.emit(`No entry for ${key}, so the key is free and ${statement} goes on.`, {
+        stage: 'execute',
+        op: statement === 'INSERT' ? 'Insert' : 'Update',
+        rowsProduced: 0,
+    });
+}
+/** Every unique index of the table, checked for the row an `INSERT` is about to add. */
+export function enforceUniqueOnInsert(ctx, row) {
+    for (const spec of indexSpecsOf(ctx.table)) {
+        if (spec.unique)
+            checkKey(ctx, spec, keyValuesOf(row, spec.columns), 'INSERT');
+    }
+}
+/** The one unique index `spec`, checked for the values an `UPDATE` is about to give a row (its old entry is already out of the tree). */
+export function enforceUniqueOnUpdate(ctx, spec, values) {
+    if (spec.unique)
+        checkKey(ctx, spec, values, 'UPDATE');
+}
+/** What the row holding a taken key looks like, for the error's hint. */
+export function holderOf(ctx, violation) {
+    return rowAt(ctx, violation.holder);
+}

package/dist/src/engine/exec/update.js

@@ -0,0 +1,124 @@
+/**
+ * Executes an `UPDATE`'s access plan (`SeqScan` or `IndexScan`, from
+ * `emitUpdatePlanEvents`) against the real heap and index: finds every
+ * matching row exactly the way `DELETE` does, applies the SET assignments to
+ * produce its replacement, and — if any assignment touches the indexed
+ * column — drops the old key and adds the new one through the real
+ * `deleteKey`/`insert` algorithms. Delete-then-reinsert is the only honest
+ * way to keep a B+Tree's keys in order when the value they index changes;
+ * there is no in-place "rekey" (plan.md §22.2, the write path's last
+ * statement).
+ *
+ * Like `DELETE`, this finds every match before it changes anything — a
+ * `SELECT`'s Volcano operators pull one row at a time, but an update mid-scan
+ * could shift what a later step reads. It narrates through the same
+ * `execute`-stage shape (`SeqScan`/`IndexScan` while finding, then `Update`
+ * while applying) that `DELETE` and `INSERT` already use.
+ */
+import { enforceUniqueOnUpdate } from "./unique.js";
+import { indexLookupMatches, indexRangeMatches } from "./writeScan.js";
+import { evaluateValue, passes } from "./evaluate.js";
+import { deleteKey, entryFor, height, indexNameOf, indexSpecsOf, insert, keyText, keyValuesOf } from "../index/index.js";
+import { summarizeSteps } from "./delete.js";
+import { summarizeInsert } from "./insert.js";
+const UPDATE = { name: 'UPDATE', does: 'modify' };
+/**
+ * `row` with every SET assignment applied — a new object; `row` itself is
+ * untouched. Every value is evaluated against the row *as it was*, so
+ * `SET a = b, b = a` swaps the two rather than copying one over the other
+ * (standard SQL, and what plan.md §25.4 B1b's `SET n = n + 1` relies on).
+ */
+function applyAssignments(row, assignments) {
+    const next = { ...row };
+    for (const a of assignments)
+        next[a.column] = evaluateValue(a.value, row);
+    return next;
+}
+/**
+ * Moves the row's entry from its old values to its new ones in each index whose own columns actually changed.
+ * A NULL leading column is never indexed, so on either side it just drops the delete or the insert half. A table
+ * can have several indexes; an assignment only reindexes the ones whose columns it touched, one sentence each.
+ */
+function reindexRow(ctx, before, after, pointer) {
+    const sentences = [];
+    for (const spec of indexSpecsOf(ctx.table)) {
+        const name = indexNameOf(spec.columns);
+        const tree = ctx.trees[name];
+        if (!tree)
+            continue;
+        const beforeValues = keyValuesOf(before, spec.columns);
+        const afterValues = keyValuesOf(after, spec.columns);
+        if (beforeValues.every((v, i) => v === afterValues[i]))
+            continue; // none of this index's columns changed
+        const parts = [];
+        if (beforeValues[0] !== null) {
+            const { key } = entryFor(spec.columns, before, pointer, ctx.table.clusteredKey);
+            const removed = deleteKey(tree, key);
+            if (removed.found) {
+                parts.push(`drops key ${keyText(beforeValues)} — ${summarizeSteps(removed.steps)}`);
+            }
+        }
+        if (afterValues[0] !== null) {
+            // Its old entry is out, so what remains is everyone else's: a UNIQUE index must not already hold the new key.
+            enforceUniqueOnUpdate(ctx, spec, afterValues);
+            const nodesBefore = Object.keys(tree.nodes).length;
+            const heightBefore = height(tree);
+            const { key, pointer: stored } = entryFor(spec.columns, after, pointer, ctx.table.clusteredKey);
+            insert(tree, key, stored);
+            const nodesAfter = Object.keys(tree.nodes).length;
+            const heightAfter = height(tree);
+            parts.push(`adds key ${keyText(afterValues)} — ${summarizeInsert(nodesBefore, nodesAfter, heightBefore, heightAfter)}`);
+        }
+        if (parts.length > 0) {
+            sentences.push(`Because \`${name}\` changed, its B+Tree ${parts.join(', then ')}.`);
+        }
+    }
+    return sentences.length > 0 ? sentences.join(' ') : null;
+}
+/** Every heap page, filtered by `filter` if present — the SeqScan half of an update. */
+function scanForMatches(ctx, filter) {
+    const matched = [];
+    let produced = 0;
+    for (const page of ctx.heap.pages) {
+        ctx.locks.acquire(page.pageId, 'exclusive', `Take an exclusive lock on page ${String(page.pageId)} — UPDATE may modify a row on it, so a shared lock is not enough.`);
+        const fetched = ctx.pool.fetch(page.pageId);
+        if (fetched)
+            ctx.pool.unpin(fetched.frameId);
+        let touchedPage = false;
+        page.rows.forEach((row, slot) => {
+            if (!passes(filter, row))
+                return;
+            matched.push({ row, pointer: { pageId: page.pageId, slot } });
+            touchedPage = true;
+            produced += 1;
+            ctx.emit(`SeqScan finds a matching row on page ${page.pageId} — UPDATE will modify it.`, {
+                stage: 'execute',
+                op: 'SeqScan',
+                rowsProduced: produced,
+            });
+        });
+        if (touchedPage)
+            ctx.pool.markDirty(page.pageId);
+        ctx.locks.release(page.pageId, 'exclusive');
+    }
+    return matched;
+}
+export function executeUpdate(plan, assignments, ctx) {
+    const matches = plan.op === 'IndexScan'
+        ? indexLookupMatches(ctx, plan, UPDATE)
+        : plan.op === 'IndexRangeScan'
+            ? indexRangeMatches(ctx, plan, UPDATE)
+            : scanForMatches(ctx, plan.op === 'SeqScan' ? plan.filter : undefined);
+    const before = [];
+    const after = [];
+    let produced = 0;
+    for (const { row, pointer } of matches) {
+        const updated = applyAssignments(row, assignments);
+        before.push(row);
+        after.push(updated);
+        produced += 1;
+        const indexDetail = reindexRow(ctx, row, updated, pointer);
+        ctx.emit(`Update changes row ${JSON.stringify(row)} to ${JSON.stringify(updated)}.${indexDetail ? ` ${indexDetail}` : ''}`, { stage: 'execute', op: 'Update', rowsProduced: produced });
+    }
+    return { before, after };
+}

package/dist/src/engine/exec/writeScan.js

@@ -0,0 +1,88 @@
+/**
+ * How a `DELETE` or `UPDATE` finds its rows through an index (plan.md §22.2's write path; ranges since §25.4 B3b).
+ *
+ * A write cannot stream: it has to find *every* match before it changes anything, or a change mid-scan could shift what
+ * a later step reads (an `UPDATE` that moves a row's key would find it again). So each of these walks the index to
+ * the end, takes an exclusive lock on the heap page of every row it will touch, marks that page dirty, and hands back
+ * the rows with their addresses — the address is what lets the executor drop and re-add exactly *that* row's index entry.
+ * `exec/delete.ts` and `exec/update.ts` share them, and differ only in the verb the narration uses.
+ */
+import { lookupKeysOf } from "../planner/index.js";
+import { fetchHeapPage, rangeHolds, rowAt } from "./operators.js";
+import { passes } from "./evaluate.js";
+import { emitIndexLookup, emitRangeStart, nextInRange, resolveClustered } from "../index/index.js";
+/** Takes the exclusive lock a write needs on the row's heap page, marks it dirty, and narrates the find. */
+function claim(ctx, match, verb, op, found, of) {
+    ctx.locks.acquire(match.pointer.pageId, 'exclusive', `Upgrade to an exclusive lock on heap page ${String(match.pointer.pageId)} — ${verb.name} is about to ${verb.does} the row it holds.`);
+    ctx.pool.markDirty(match.pointer.pageId);
+    ctx.emit(of, { stage: 'execute', op, rowsProduced: found });
+    ctx.locks.release(match.pointer.pageId, 'exclusive');
+}
+const rejected = (ctx, verb, op, found) => {
+    ctx.emit(`The row the index found fails the rest of the predicate, so ${verb.name} leaves it alone.`, {
+        stage: 'execute',
+        op,
+        rowsProduced: found,
+    });
+};
+/** Every row an equality lookup points at that passes any residual predicate — one, or one per index entry. */
+export function indexLookupMatches(ctx, plan, verb) {
+    const tree = ctx.trees[plan.column];
+    if (!tree)
+        return [];
+    const outcome = emitIndexLookup(ctx.emit, tree, lookupKeysOf(plan), ctx.pool, plan.column, ctx.locks);
+    const { pointers, clusterKeys } = outcome;
+    const clusteredTree = tree.clusteredVia !== undefined ? ctx.trees[tree.clusteredVia] : undefined;
+    const matched = [];
+    pointers.forEach((pointer, at) => {
+        // A clustered table's secondary entry has no address (plan.md §25.4 B3e): every match costs a real second
+        // descent, through the clustered index. Otherwise the lookup already fetched the first match's page, and the
+        // rest are read now, as their rows are examined.
+        const clusterKey = clusterKeys?.[at];
+        const real = clusterKey && clusteredTree ? resolveClustered(ctx.emit, clusteredTree, tree.clusteredVia, clusterKey, ctx.pool, ctx.locks) : pointer;
+        if (!real)
+            return;
+        if (!clusterKey && at > 0)
+            fetchHeapPage(ctx, pointer);
+        const row = rowAt(ctx, real);
+        if (!row)
+            return;
+        if (!passes(plan.residual, row)) {
+            rejected(ctx, verb, 'IndexScan', matched.length);
+            return;
+        }
+        matched.push({ row, pointer: real });
+        claim(ctx, { row, pointer: real }, verb, 'IndexScan', matched.length, pointers.length === 1
+            ? `IndexScan finds the one row ${verb.name} will ${verb.does}.`
+            : `IndexScan finds a row ${verb.name} will ${verb.does} — ${String(matched.length)} so far, of ${String(pointers.length)} entries for this value.`);
+    });
+    return matched;
+}
+/** Every row a range walk of the index reaches that passes the range and any residual predicate. */
+export function indexRangeMatches(ctx, plan, verb) {
+    const tree = ctx.trees[plan.column];
+    if (!tree)
+        return [];
+    const start = emitRangeStart(ctx.emit, tree, plan.column, plan.low, ctx.pool, ctx.locks, plan.prefix);
+    let leafId = start.leafId;
+    let index = start.startIndex;
+    const matched = [];
+    while (leafId !== null) {
+        const found = nextInRange(ctx.emit, tree, leafId, index, plan.high, { pool: ctx.pool, locks: ctx.locks }, plan.prefix);
+        if (!found)
+            break;
+        leafId = found.leafId;
+        index = found.nextIndex;
+        fetchHeapPage(ctx, found.pointer);
+        const row = rowAt(ctx, found.pointer);
+        if (!row || !rangeHolds(row, plan))
+            continue;
+        if (!passes(plan.residual, row)) {
+            rejected(ctx, verb, 'IndexRangeScan', matched.length);
+            continue;
+        }
+        matched.push({ row, pointer: found.pointer });
+        claim(ctx, { row, pointer: found.pointer }, verb, 'IndexRangeScan', matched.length, `IndexRangeScan finds a row ${verb.name} will ${verb.does} via leaf ${found.leafId} — ${String(matched.length)} so far.`);
+    }
+    return matched;
+}

package/dist/src/engine/explain.js

@@ -0,0 +1,114 @@
+/**
+ * `EXPLAIN [ANALYZE] SELECT …` as a statement (plan.md §25.4 B6) — the in-app
+ * EXPLAIN that used to be only a button, now something you can *type*, and
+ * whose answer is a result you can read, copy and share like any other.
+ *
+ *   EXPLAIN          plans and optimises the query and shows the plan with the
+ *                    cost model's estimate for every operator. **Nothing is
+ *                    read** — the trace stops before the executor, exactly as
+ *                    a real EXPLAIN never touches the data.
+ *   EXPLAIN ANALYZE  runs the query for real (the trace *is* that run) and puts
+ *                    the executor's actual row count beside each estimate, then
+ *                    the buffer pool's hits, misses and evictions. It reports
+ *                    no timings: this engine makes no claim about latency (§12).
+ *
+ * Built on the ordinary run of the inner query, so the plan shown is exactly
+ * the plan that would execute. The `EXPLAIN [ANALYZE]` prefix is replaced by
+ * spaces before that run, which keeps every span the inner statement reports
+ * (the editor's squiggles, the parse tree's highlights) pointing at the text
+ * the user actually typed.
+ */
+import { createTracer } from "./trace.js";
+export const EXPLAIN_COLUMN = 'QUERY PLAN';
+/** The optimizer's final plan: the last rewrite's `after`, or the canonical plan if nothing rewrote it. */
+export function finalPlan(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.stage === 'optimize')
+            return e.after;
+        if (e.stage === 'plan')
+            return e.planTree;
+    }
+    return null;
+}
+/**
+ * `max(est/act, act/est)`, Leis et al.'s own metric for cardinality-estimation error (plan.md §25.4 C2;
+ * RESEARCH.md §41) — `1` is a perfect guess, `10` an estimate ten times too high or too low, whichever direction
+ * it missed. Both sides get the literature's own `+1` smoothing, so a `0` estimate or a `0` actual row count is
+ * still a real, finite number rather than a division by zero.
+ */
+function qError(estRows, actualRows) {
+    return Math.max((estRows + 1) / (actualRows + 1), (actualRows + 1) / (estRows + 1));
+}
+/**
+ * The key `actual` (below) is built and read by: `op` alone collides whenever a plan has two nodes of the same
+ * kind — a multi-join chain's several `SeqScan`s or several `Join`s (plan.md §25.4 C3 slice b flagged this as a
+ * real, pre-existing bug) — so every row this engine ever produces for one of them would be misreported onto
+ * all the others sharing that `op`. `table` (a scan's own table, or a `Join`'s `rightTable`) is always enough to
+ * tell them apart, since the parser never lets a query name the same table twice.
+ */
+export function nodeKey(op, table) {
+    return table === undefined ? op : `${op}:${table}`;
+}
+/** One line per operator, PostgreSQL-shaped: the root, then `->` for each level beneath it. */
+function planLines(root, actual) {
+    const lines = [];
+    const walk = (node, depth) => {
+        const parts = [];
+        if (node.estRows !== undefined)
+            parts.push(`est ~${String(node.estRows)} rows`);
+        const rows = actual?.get(nodeKey(node.op, node.table));
+        if (rows !== undefined) {
+            parts.push(`actual ${String(rows)} rows`);
+            // Below 2× is well within the noise a real optimizer lives with every day — naming it would just be clutter.
+            if (node.estRows !== undefined) {
+                const q = qError(node.estRows, rows);
+                if (q >= 2)
+                    parts.push(`q-error ${q.toFixed(1)}×`);
+            }
+        }
+        const indent = depth === 0 ? '' : `${'      '.repeat(depth - 1)}  ->  `;
+        const text = node.detail ? `${node.label}  ${node.detail}` : node.label;
+        lines.push(`${indent}${text}${parts.length > 0 ? `  (${parts.join('; ')})` : ''}`);
+        (node.children ?? []).forEach((child) => { walk(child, depth + 1); });
+    };
+    walk(root, 0);
+    return lines;
+}
+export function explainResult(sql, ast, run) {
+    const inner = run(' '.repeat(ast.select.span.from) + sql.slice(ast.select.span.from));
+    if (inner.error)
+        return inner;
+    const plan = finalPlan(inner.events);
+    if (!plan)
+        return { events: inner.events, rows: [] };
+    // What ran, per operator: the largest count it reported. Bookkeeping events (a discarded candidate, a hash build
+    // announcement) can carry a 0 that lands after the real count has grown, so the last event is not always the total.
+    const actual = new Map();
+    for (const e of inner.events) {
+        if (e.stage !== 'execute')
+            continue;
+        const key = nodeKey(e.op, e.table);
+        actual.set(key, Math.max(actual.get(key) ?? 0, e.rowsProduced));
+    }
+    const lines = planLines(plan, ast.analyze ? actual : null);
+    if (ast.analyze) {
+        const count = (action) => inner.events.filter((e) => e.stage === 'buffer' && e.action === action).length;
+        lines.push(`Result: ${String(inner.rows.length)} row${inner.rows.length === 1 ? '' : 's'}`, `Buffer pool: ${String(count('hit'))} hit${count('hit') === 1 ? '' : 's'}, ${String(count('miss'))} miss${count('miss') === 1 ? '' : 'es'}, ${String(count('evict'))} eviction${count('evict') === 1 ? '' : 's'}`);
+    }
+    const rows = lines.map((line) => ({ [EXPLAIN_COLUMN]: line }));
+    // Plain EXPLAIN stops before the executor; EXPLAIN ANALYZE keeps the whole run but replaces its result.
+    const kept = inner.events.filter((e) => ast.analyze ? e.stage !== 'result' : e.stage === 'parse' || e.stage === 'plan' || e.stage === 'optimize');
+    const { emit, drain } = createTracer();
+    for (const e of kept) {
+        const { id: _id, label, predictable, dwell, ...body } = e;
+        emit(label, body, {
+            ...(predictable ? { predictable } : {}),
+            ...(dwell === undefined ? {} : { dwell }),
+        });
+    }
+    emit(ast.analyze
+        ? `EXPLAIN ANALYZE ran the query for real — the trace above is that run — and reports the cost model's estimate next to the executor's actual row count for every operator, then what the buffer pool did.`
+        : `EXPLAIN shows the plan the optimizer chose and the cost model's estimate for each operator. Nothing was executed and no page was read — that is what separates EXPLAIN from EXPLAIN ANALYZE.`, { stage: 'result', rows });
+    return { events: drain(), rows };
+}