querylens 0.1.0

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

@@ -0,0 +1,38 @@
+import { node, valuesOf } from "./btree.js";
+function formatValue(value) {
+    if (value === null)
+        return 'NULL';
+    return typeof value === 'string' ? `'${value}'` : String(value);
+}
+/** A key as the tree draws it: a table index's entry shows its value(s) — the row address it also carries is not drawn. */
+function formatKey(key) {
+    const values = valuesOf(key);
+    return values.length === 1 ? formatValue(values[0]) : `(${values.map(formatValue).join(', ')})`;
+}
+/** An index key as the write narration says it: `2`, `'ada'`, or `(2, 'ada')` for a composite index's. */
+export function keyText(values) {
+    return values.length === 1 ? JSON.stringify(values[0]) : `(${values.map((v) => JSON.stringify(v)).join(', ')})`;
+}
+export function keyList(keys) {
+    return keys.length === 0 ? '·' : keys.map(formatKey).join(' ');
+}
+/** The whole tree, as the UI draws it. */
+export function toIndexDisplay(tree, id = tree.rootId) {
+    const n = node(tree, id);
+    if (n.kind === 'leaf') {
+        return {
+            id: n.id,
+            kind: 'leaf',
+            label: keyList(n.keys),
+            pageId: n.pageId,
+            ...(n.next === null ? {} : { next: n.next }),
+        };
+    }
+    return {
+        id: n.id,
+        kind: 'internal',
+        label: keyList(n.keys),
+        pageId: n.pageId,
+        children: n.children.map((childId) => toIndexDisplay(tree, childId)),
+    };
+}

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

@@ -0,0 +1,9 @@
+export { allKeys, childIndexFor, compareKeys, createTree, DEFAULT_MAX_KEYS, deleteKey, descend, entryKey, entryWidth, height, highKey, insert, leafChain, leftmostPath, lowerBound, node, probe, search, valuesOf, } from "./btree.js";
+export { bulkLoad, DEFAULT_FILL_FACTOR, MIN_FILL_FACTOR } from "./bulk.js";
+export { buildIndex, buildIndexes, entryFor, keyValuesOf, pageCountFor } from "./build.js";
+export { columnsOfIndex, findIndexSpec, indexNameOf, indexSpecsOf, isClusteringIndex, joinIndexFor } from "./spec.js";
+export { keyList, keyText, toIndexDisplay } from "./display.js";
+export { describeKeys, emitIndexLookup, resolveClustered } from "./lookup.js";
+export { emitRangeStart, nextInRange } from "./rangeLookup.js";
+export { validate } from "./validate.js";
+export { describeUniqueKey, uniqueViolation } from "./unique.js";

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

@@ -0,0 +1,213 @@
+/**
+ * A point lookup, narrated. Each node on the root-to-leaf path is fetched
+ * through the buffer pool first — index pages are pages, so a traversal costs
+ * real reads and shows up in the frame grid alongside the heap.
+ *
+ * On a table's index the key may repeat (plan.md §25.4 B3): the lookup descends
+ * toward the *first* entry with that key, then reads along the leaf for as
+ * long as the key holds, hopping to the next leaf only when the run reaches the
+ * end of one *and* the leaf's high key says the key continues. A unique key is
+ * the same walk that happens to stop after one entry.
+ *
+ * On a composite index the lookup key may be a *leftmost prefix* — one value of
+ * an index over two, say. An entry matches when its first columns equal the
+ * prefix, so the run it reads is every entry that starts that way.
+ */
+import { childIndexFor, compareKeys, descend, entryWidth, height, highKey, lowerBound, node, probe, valuesOf, } from "./btree.js";
+import { keyList, toIndexDisplay } from "./display.js";
+import { traversalPrompt } from "../predict.js";
+function describe(key) {
+    return typeof key === 'string' ? `'${key}'` : String(key);
+}
+/** A lookup key as text: `3`, or `(3, 'ada')` for a composite one. */
+export function describeKeys(keys) {
+    return keys.length === 1 ? describe(keys[0]) : `(${keys.map(describe).join(', ')})`;
+}
+/** Does `key`'s leading values equal `keys`? — an entry (or a separator) that starts with the lookup prefix. */
+function startsWith(key, keys) {
+    const values = valuesOf(key);
+    return keys.every((k, i) => i < values.length && compareKeys(values[i], k) === 0);
+}
+export function emitIndexLookup(emit, tree, 
+/** The key to find: one value for a plain index, or the leading values (a leftmost prefix) of a composite one. */
+keys, pool, 
+/** The index's name — its column, or its columns joined — for the narration. */
+column, locks, 
+/**
+ * Every existing caller wants the row, so this defaults to `true`. An
+ * index-only scan (plan.md §22.2) passes `false`: the leaf already holds
+ * everything the query needs, so fetching and locking the heap page the
+ * pointer names would be pure theatre — real disk I/O the query never
+ * actually required, which is exactly the discount §12 rules out claiming.
+ *
+ * With `true`, only the *first* match's heap page is fetched here; the caller
+ * fetches each later one as it pulls that row, so a `LIMIT` that stops early
+ * never pays for the rest.
+ */
+touchHeap = true, 
+/** Replaces the "Found …" sentence when the lookup is not answering a query — a `UNIQUE` check's own words. */
+foundNote) {
+    const label = describeKeys(keys);
+    const wide = tree.tiebreak === true && entryWidth(tree) > 1;
+    emit(`Open the B+Tree on \`${column}\`: ${height(tree)} levels, so any key is at most ${height(tree)} node reads away — however many rows the table holds.`, { stage: 'index', action: 'open', tree: toIndexDisplay(tree), nodeId: tree.rootId, height: height(tree) });
+    // A table's index orders entries by (values, row address); the lowest entry that could carry this key is what
+    // the descent aims for. A sandbox tree just holds the value.
+    const target = tree.tiebreak ? probe(keys, 'low') : keys[0];
+    const path = descend(tree, target);
+    const pagesRead = [];
+    let parentPage = null;
+    // Ask once, at the first branch. Asking at every level is repetition, not
+    // practice — the rule is the same each time.
+    let traversalAsked = false;
+    for (const nodeId of path) {
+        const n = node(tree, nodeId);
+        /**
+         * Latch crabbing: take the child's lock *before* releasing the parent's,
+         * so the subtree cannot be restructured out from under the descent. For a
+         * moment two locks are held at once — that overlap is the whole technique.
+         */
+        locks.acquire(n.pageId, 'shared', parentPage === null
+            ? `Lock the root page ${String(n.pageId)} before reading it.`
+            : `Lock child page ${String(n.pageId)} before letting go of page ${String(parentPage)} — "crabbing" down the tree, so the branch cannot move while we are following it.`);
+        const fetched = pool.fetch(n.pageId);
+        if (fetched) {
+            pagesRead.push(n.pageId);
+            pool.unpin(fetched.frameId);
+        }
+        if (parentPage !== null) {
+            locks.release(parentPage, 'shared', `Now that page ${String(n.pageId)} is locked, page ${String(parentPage)} can be released. The descent never holds the whole path at once.`);
+        }
+        parentPage = n.pageId;
+        if (n.kind === 'internal') {
+            const internal = n;
+            const childIndex = childIndexFor(internal, target);
+            // Equal values can sit on both sides of a separator, so a separator that *starts with* this key sends the search left of it.
+            const straddles = tree.tiebreak === true && childIndex < internal.keys.length && startsWith(internal.keys[childIndex], keys);
+            // A plain index's separators are single values, which read as "below / between / at or above"; a composite
+            // index's are tuples, and the sentence says where the search lands without pretending they are numbers.
+            const where = wide
+                ? `The first entry starting with ${label} can be no further left than child ${String(childIndex)}, so follow child ${String(childIndex)}.`
+                : (() => {
+                    const separators = internal.keys.map((k) => valuesOf(k)[0]);
+                    return `${label} ${childIndex === 0
+                        ? `is below ${describe(separators[0])}`
+                        : childIndex === separators.length
+                            ? `is at or above ${describe(separators[separators.length - 1])}`
+                            : `falls between ${describe(separators[childIndex - 1])} and ${describe(separators[childIndex])}`}, so follow child ${String(childIndex)}.`;
+                })();
+            emit(`Node ${nodeId} separates on ${keyList(internal.keys)}. ${straddles
+                ? `${label} matches a separator, and a run of equal keys can straddle one — so go left of it, to child ${String(childIndex)}, to reach the first ${label} there is.`
+                : where}`, { stage: 'index', action: 'traverse', nodeId, key: keys[0], childIndex }, traversalAsked || straddles || wide
+                ? undefined
+                : (() => {
+                    traversalAsked = true;
+                    const prompt = traversalPrompt(nodeId, internal.keys.map((k) => valuesOf(k)[0]), keys[0], childIndex);
+                    return prompt ? { predictable: prompt } : undefined;
+                })());
+        }
+        else {
+            emit(`Reach leaf ${nodeId}, which holds keys ${keyList(n.keys)}.`, {
+                stage: 'index',
+                action: 'traverse',
+                nodeId,
+                key: keys[0],
+            });
+        }
+    }
+    let leaf = node(tree, path[path.length - 1]);
+    const pointers = [];
+    const entries = [];
+    // Only a clustered table's secondary index ever fills this in (plan.md §25.4 B3e) — parallel to `pointers`.
+    const clusterKeys = [];
+    let foundLeaf = leaf.id;
+    if (tree.tiebreak) {
+        // Read along the leaves while the key holds. A hop is taken only when the run reached the end of a leaf and the
+        // leaf's high key (its parent's separator) still starts with this key — otherwise the next leaf starts above it.
+        let at = lowerBound(leaf.keys, target);
+        // A UNIQUE index holds at most one entry per whole key, so the first match is the only one — no run to read, and
+        // no reason to look at the next leaf even when the match is the last entry of this one.
+        const single = tree.unique === true && keys.length >= entryWidth(tree);
+        for (;;) {
+            while (at < leaf.keys.length && startsWith(leaf.keys[at], keys) && !(single && pointers.length > 0)) {
+                if (pointers.length === 0)
+                    foundLeaf = leaf.id;
+                pointers.push(leaf.pointers[at]);
+                entries.push([...valuesOf(leaf.keys[at])]);
+                if (tree.clusteredVia !== undefined)
+                    clusterKeys.push(leaf.keys[at].clusterKey ?? []);
+                at += 1;
+            }
+            if (single && pointers.length > 0)
+                break;
+            if (at < leaf.keys.length || leaf.next === null)
+                break;
+            const high = highKey(tree, leaf);
+            if (high === null || !startsWith(high, keys))
+                break;
+            const next = node(tree, leaf.next);
+            emit(`Leaf ${leaf.id} ends, and its high key starts with ${label} too — more entries for it continue in the next leaf. Follow the sibling pointer to leaf ${next.id}.`, { stage: 'index', action: 'chain-next', fromNodeId: leaf.id, toNodeId: next.id });
+            locks.acquire(next.pageId, 'shared', `Lock the sibling leaf, page ${String(next.pageId)}, before letting go of page ${String(leaf.pageId)}.`);
+            const hopped = pool.fetch(next.pageId);
+            if (hopped) {
+                pagesRead.push(next.pageId);
+                pool.unpin(hopped.frameId);
+            }
+            locks.release(leaf.pageId, 'shared');
+            parentPage = next.pageId;
+            leaf = next;
+            at = 0;
+        }
+    }
+    else {
+        const at = leaf.keys.findIndex((k) => compareKeys(k, keys[0]) === 0);
+        if (at !== -1) {
+            pointers.push(leaf.pointers[at]);
+            entries.push([keys[0]]);
+        }
+    }
+    const clustered = tree.clusteredVia !== undefined;
+    const pointer = pointers[0];
+    if (pointer === undefined) {
+        emit(`${label} is not in this leaf, so it is not in the table at all — the search stops here.`, {
+            stage: 'index',
+            action: 'not-found',
+            nodeId: leaf.id,
+            key: keys[0],
+        });
+        if (parentPage !== null)
+            locks.release(parentPage, 'shared');
+        return { pointer: null, pointers, entries, pagesRead, ...(clustered ? { clusterKeys } : {}) };
+    }
+    const also = pointers.length > 1
+        ? ` ${String(pointers.length - 1)} more ${pointers.length === 2 ? 'entry' : 'entries'} for the same ${wide ? 'key prefix' : 'value'} follow it — a non-unique index keeps one entry per row, ordered by where the row lives, so a repeated ${wide ? 'key' : 'value'} is ${String(pointers.length)} pointers, not one.`
+        : '';
+    const partial = wide && keys.length < entryWidth(tree) ? ` (a leftmost prefix of the ${String(entryWidth(tree))}-column key)` : '';
+    emit(foundNote ??
+        (clustered && touchHeap
+            ? `Found ${label}${partial}. This table is clustered on \`${tree.clusteredVia}\`, so the leaf holds that key, not the row's address — finding the row costs a second descent, through the clustered index itself.${also}`
+            : touchHeap
+                ? `Found ${label}${partial}. The leaf stores a pointer to the row, not the row itself: heap page ${pointer.pageId}, slot ${pointer.slot}.${also}`
+                : `Found ${label}${partial}. This query only needs \`${column}\` itself, which the leaf already holds — the heap page the pointer names is never read.${also}`), { stage: 'index', action: 'found', nodeId: foundLeaf, key: keys[0] });
+    // A clustered table's secondary entry has no address to fetch — `resolveClustered` does the real work, as a
+    // second, honest descent, and only the caller knows which of `pointers` it still needs (a `LIMIT` may not need them all).
+    if (touchHeap && !clustered) {
+        locks.acquire(pointer.pageId, 'shared', `Lock heap page ${String(pointer.pageId)}, where the row itself lives.`);
+        const heapFetch = pool.fetch(pointer.pageId);
+        if (heapFetch) {
+            pagesRead.push(pointer.pageId);
+            pool.unpin(heapFetch.frameId);
+        }
+        locks.release(pointer.pageId, 'shared');
+    }
+    if (parentPage !== null)
+        locks.release(parentPage, 'shared');
+    return { pointer, pointers, entries, pagesRead, ...(clustered ? { clusterKeys } : {}) };
+}
+/**
+ * The real row address for one of a clustered table's secondary-index matches (plan.md §25.4 B3e): a second, real
+ * descent through the clustered index itself, narrated and costed exactly like any other lookup — because that is
+ * exactly what it is. `null` only if the row genuinely is not there, which a correctly maintained index never shows.
+ */
+export function resolveClustered(emit, clusteredTree, clusteringColumn, clusterKey, pool, locks) {
+    return emitIndexLookup(emit, clusteredTree, clusterKey, pool, clusteringColumn, locks).pointer;
+}

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

@@ -0,0 +1,158 @@
+/**
+ * A range scan, narrated. `emitRangeStart` descends the B+Tree once, the same
+ * crabbing-locks pattern `lookup.ts`'s point lookup uses, to find the leaf a
+ * range's lower bound would start at (or the leftmost leaf, with no lower
+ * bound) — the vertical half of plan.md §23.1's leaf-chaining range scan.
+ * `nextInRange` is the horizontal half: it walks forward from a position
+ * inside that leaf, across `next` sibling pointers as leaves run out, one
+ * matching key at a time — so the executor can pull rows through the buffer
+ * pool exactly as lazily as every other operator does, rather than
+ * materialising the whole range up front.
+ */
+import { childIndexFor, compareKeys, descend, height, isEntry, leftmostPath, lowerBound, node, probe, } from "./btree.js";
+import { keyList, toIndexDisplay } from "./display.js";
+import { describeKeys } from "./lookup.js";
+/**
+ * Is `key` still inside the range? An entry carries its row address as well as its values, so it is never *equal* to a
+ * bare bound — the bound becomes a probe instead: just after every entry with this value (an inclusive `<=`) or just
+ * before them all (`<`). Within a composite index's equality `prefix` the probe carries the prefix too, and with no
+ * upper bound the end of the range is the end of the prefix's run — the first entry that no longer starts with it.
+ */
+function withinHigh(key, high, prefix) {
+    if (isEntry(key)) {
+        const upper = high ? probe([...prefix, high.value], high.inclusive ? 'high' : 'low') : probe(prefix, 'high');
+        return compareKeys(key, upper) < 0;
+    }
+    if (!high)
+        return true;
+    const c = compareKeys(key, high.value);
+    return high.inclusive ? c <= 0 : c < 0;
+}
+/**
+ * Where the walk begins. A plain index descends toward the lower bound (an inclusive `>= v` starts at the first entry
+ * *for* v, an exclusive `> v` just past the last). Inside a composite index's equality `prefix` the target carries
+ * the prefix; with no lower bound it is the first entry *after the NULLs* of the range column — NULL sorts first,
+ * and a range never matches one, so there is no reason to read them.
+ */
+function startTarget(tree, low, prefix) {
+    if (!tree.tiebreak)
+        return low?.value;
+    if (low)
+        return probe([...prefix, low.value], low.inclusive ? 'low' : 'high');
+    return prefix.length > 0 ? probe([...prefix, null], 'high') : undefined;
+}
+/**
+ * Descends to the range's starting leaf and narrates it. Unlike a point
+ * lookup there is no found/not-found here — the boundary itself is the
+ * answer, not a specific key, so `startIndex` may land one past the leaf's
+ * last key (an empty range) without that being an error.
+ */
+export function emitRangeStart(emit, tree, column, low, pool, locks, 
+/** A composite index's equality values for the columns before the range one — the range runs *within* them. */
+prefix = []) {
+    const h = height(tree);
+    const within = prefix.length > 0 ? ` within ${describeKeys(prefix)}` : '';
+    emit(`Open the B+Tree on \`${column}\`: ${String(h)} level${h === 1 ? '' : 's'}. ${low
+        ? `Descend once toward ${describeKeys([...prefix, low.value])} — not to find that exact key, but to find where the range begins${within}.`
+        : prefix.length > 0
+            ? `This range has no lower bound${within}, so descend toward where the entries starting ${describeKeys(prefix)} begin.`
+            : "This range has no lower bound, so descend to the tree's leftmost leaf instead."}`, { stage: 'index', action: 'open', tree: toIndexDisplay(tree), nodeId: tree.rootId, height: h });
+    const target = startTarget(tree, low, prefix);
+    const path = target !== undefined ? descend(tree, target) : leftmostPath(tree);
+    let parentPage = null;
+    for (const nodeId of path) {
+        const n = node(tree, nodeId);
+        locks.acquire(n.pageId, 'shared', parentPage === null
+            ? `Lock the root page ${String(n.pageId)} before reading it.`
+            : `Lock child page ${String(n.pageId)} before letting go of page ${String(parentPage)} — "crabbing" down the tree, so the branch cannot move while we are following it.`);
+        const fetched = pool.fetch(n.pageId);
+        if (fetched)
+            pool.unpin(fetched.frameId);
+        if (parentPage !== null) {
+            locks.release(parentPage, 'shared', `Now that page ${String(n.pageId)} is locked, page ${String(parentPage)} can be released.`);
+        }
+        parentPage = n.pageId;
+        if (n.kind === 'internal') {
+            const childIndex = target !== undefined ? childIndexFor(n, target) : 0;
+            emit(`Node ${nodeId} separates on ${keyList(n.keys)}. ${low
+                ? `${describeKeys([...prefix, low.value])} routes to child ${String(childIndex)}.`
+                : prefix.length > 0
+                    ? `The entries starting ${describeKeys(prefix)} route to child ${String(childIndex)}.`
+                    : 'With no lower bound, follow the leftmost child.'}`, { stage: 'index', action: 'traverse', nodeId, ...(low ? { key: low.value } : {}), childIndex });
+        }
+        else {
+            emit(`Reach leaf ${nodeId}, which holds keys ${keyList(n.keys)} — the scan starts here.`, {
+                stage: 'index',
+                action: 'traverse',
+                nodeId,
+                ...(low ? { key: low.value } : {}),
+            });
+        }
+    }
+    if (parentPage !== null)
+        locks.release(parentPage, 'shared');
+    const leafId = path[path.length - 1];
+    const leaf = node(tree, leafId);
+    const at = target !== undefined ? lowerBound(leaf.keys, target) : 0;
+    // `lowerBound` finds the first key >= the target — exactly right for an
+    // inclusive `>=` bound. In a sandbox tree an exclusive `>` on a key that
+    // happens to be present has to skip one further, past the exact match; a
+    // table's index already aimed at a probe just past the whole run.
+    const startIndex = low && !low.inclusive && !tree.tiebreak && at < leaf.keys.length && compareKeys(leaf.keys[at], low.value) === 0
+        ? at + 1
+        : at;
+    return { leafId, startIndex };
+}
+/**
+ * The next matching key from `(leafId, index)` onward, following sibling
+ * pointers as leaves run out and narrating each hop. Returns `null` once the
+ * chain ends or a key exceeds `high` — a sorted leaf chain means every key
+ * past that point is out of range too, so the walk can stop rather than
+ * checking the rest.
+ *
+ * Each hop *reads the sibling leaf through the buffer pool* (`io`): a leaf is a
+ * page, and a range that spans ten of them costs ten reads — the same figure
+ * the cost model prices (`extraLeaves`), so an `EXPLAIN ANALYZE` estimate and
+ * its actual agree on how many leaves the walk touched.
+ */
+export function nextInRange(emit, tree, leafId, index, high, io, 
+/** A composite index's equality values before the range column — see `emitRangeStart`. */
+prefix = []) {
+    let currentLeafId = leafId;
+    let currentIndex = index;
+    for (;;) {
+        if (currentLeafId === null)
+            return null;
+        const leaf = node(tree, currentLeafId);
+        if (currentIndex >= leaf.keys.length) {
+            if (!leaf.next)
+                return null;
+            emit(`Leaf ${currentLeafId} is exhausted; follow its sibling pointer to leaf ${leaf.next}.`, {
+                stage: 'index',
+                action: 'chain-next',
+                fromNodeId: currentLeafId,
+                toNodeId: leaf.next,
+            });
+            if (io) {
+                const sibling = node(tree, leaf.next);
+                io.locks.acquire(sibling.pageId, 'shared', `Lock the sibling leaf, page ${String(sibling.pageId)}, to read it.`);
+                const fetched = io.pool.fetch(sibling.pageId);
+                if (fetched)
+                    io.pool.unpin(fetched.frameId);
+                io.locks.release(sibling.pageId, 'shared');
+            }
+            currentLeafId = leaf.next;
+            currentIndex = 0;
+            continue;
+        }
+        const key = leaf.keys[currentIndex];
+        if (!withinHigh(key, high, prefix))
+            return null;
+        return {
+            key,
+            pointer: leaf.pointers[currentIndex],
+            leafId: currentLeafId,
+            nextIndex: currentIndex + 1,
+        };
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * What indexes a table has, as one list (plan.md §25.4 B3).
+ *
+ * A table declares them two ways: `indexedColumns`, the shorthand for one plain single-column index per name, and
+ * `indexes`, for anything richer — today a composite index over several columns. Everything downstream (building
+ * the trees, maintaining them on a write, choosing one in the optimizer, pricing a scan of it) wants a single list of
+ * indexes, each with a stable name to find its tree by, so this is the one place that reads the two.
+ *
+ * An index's **name** is its columns joined with `, ` — `id` for a plain one, `lastName, firstName` for a composite
+ * one. Column names are identifiers, so the name is unambiguous, and it is what a `Plan` node and `ExecContext.trees`
+ * use to say *which* index.
+ */
+export const INDEX_NAME_SEPARATOR = ', ';
+export const indexNameOf = (columns) => columns.join(INDEX_NAME_SEPARATOR);
+/** The columns an index name stands for, in key order. */
+export const columnsOfIndex = (name) => name.split(INDEX_NAME_SEPARATOR);
+/** Every index `table` declares: the single-column shorthand first, in declared order, then the richer ones. */
+export function indexSpecsOf(table) {
+    const byName = new Map();
+    for (const column of table.indexedColumns ?? [])
+        byName.set(column, { columns: [column] });
+    for (const spec of table.indexes ?? []) {
+        byName.set(indexNameOf(spec.columns), { columns: [...spec.columns], ...(spec.unique ? { unique: true } : {}) });
+    }
+    return [...byName.values()];
+}
+export function findIndexSpec(table, name) {
+    return indexSpecsOf(table).find((spec) => indexNameOf(spec.columns) === name);
+}
+/**
+ * Is `columns` a table's own CLUSTERING key (plan.md §25.4 B3e)? Only that index's own tree holds real row
+ * addresses; every other index on a clustered table indirects through it instead, one extra descent at a time.
+ */
+export function isClusteringIndex(clusteredKey, columns) {
+    return !!clusteredKey && clusteredKey.length === columns.length && clusteredKey.every((c, i) => c === columns[i]);
+}
+/**
+ * The index a `JOIN` can probe for its inner side's join column: one whose *leading* column is that column — a plain
+ * index on it, or a composite one that starts with it (a leftmost prefix of one column is enough to enter it).
+ * A plain index wins over a composite one, since its entries are narrower. A clustered table's SECONDARY index is
+ * never offered (plan.md §25.4 B3e): the extra descent it costs is only built for an equality lookup, not a probe
+ * run once per outer row — the clustering key's own index is still offered, since it needs no second descent at all.
+ */
+export function joinIndexFor(table, column) {
+    const specs = indexSpecsOf(table).filter((spec) => spec.columns[0] === column && (!table.clusteredKey || isClusteringIndex(table.clusteredKey, spec.columns)));
+    return specs.find((spec) => spec.columns.length === 1) ?? specs[0];
+}

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

@@ -0,0 +1,31 @@
+/**
+ * `UNIQUE` (plan.md §25.4 B3c), as a fact about a table's rows rather than about a tree.
+ *
+ * An index is unique when no two rows hold the same key — and, as SQL says, a key with a NULL in it never counts:
+ * NULL is not equal to NULL, so any number of rows may hold one. The write path enforces it through the index
+ * (`exec/unique.ts` looks the new key up first); this is the same rule applied to a whole table at once, for
+ * whoever has to decide whether a set of rows may sit under a unique index at all (the Custom database editor).
+ */
+import { indexNameOf, indexSpecsOf } from "./spec.js";
+/** The first pair of rows that break a unique index of `table` — in `rows` (default: its own) — or `null`. */
+export function uniqueViolation(table, rows) {
+    for (const spec of indexSpecsOf(table)) {
+        if (!spec.unique)
+            continue;
+        const seen = new Set();
+        for (const row of rows) {
+            const values = spec.columns.map((c) => row[c] ?? null);
+            if (values.some((v) => v === null))
+                continue; // NULL never conflicts
+            const key = JSON.stringify(values);
+            if (seen.has(key))
+                return { index: indexNameOf(spec.columns), columns: spec.columns, values };
+            seen.add(key);
+        }
+    }
+    return null;
+}
+/** `(email) = ('a@x')` — a key the way PostgreSQL's constraint errors write it. */
+export function describeUniqueKey(columns, values) {
+    return `(${columns.join(', ')}) = (${values.map((v) => (typeof v === 'string' ? `'${v}'` : String(v))).join(', ')})`;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Structural invariants of a B+Tree. plan.md §7.6 requires these to be tested
+ * before anything is drawn: a tree with the split rules subtly wrong still
+ * *looks* plausible, and silently returns wrong rows.
+ *
+ * Returns a list of violations — empty means the tree is sound.
+ */
+import { compareKeys, leafChain, node } from "./btree.js";
+export function validate(tree) {
+    const problems = [];
+    const root = node(tree, tree.rootId);
+    const minLeafKeys = Math.ceil(tree.maxKeys / 2);
+    const minInternalChildren = Math.ceil((tree.maxKeys + 1) / 2);
+    const depths = [];
+    const visited = new Set();
+    function walk(id, depth, low, high) {
+        if (visited.has(id)) {
+            problems.push(`node ${id} is reachable by more than one path`);
+            return;
+        }
+        visited.add(id);
+        const n = node(tree, id);
+        const isRoot = id === tree.rootId;
+        // Keys within a node are strictly ascending.
+        for (let i = 1; i < n.keys.length; i++) {
+            if (compareKeys(n.keys[i - 1], n.keys[i]) >= 0) {
+                problems.push(`node ${id} keys are not strictly ascending`);
+                break;
+            }
+        }
+        // Every key must fall inside the range its ancestors promised.
+        for (const key of n.keys) {
+            if (low !== null && compareKeys(key, low) < 0) {
+                problems.push(`node ${id} holds key below its separator bound`);
+                break;
+            }
+            if (high !== null && compareKeys(key, high) >= 0) {
+                problems.push(`node ${id} holds key at or above its separator bound`);
+                break;
+            }
+        }
+        if (n.kind === 'leaf') {
+            depths.push(depth);
+            if (n.keys.length !== n.pointers.length) {
+                problems.push(`leaf ${id} has ${n.keys.length} keys but ${n.pointers.length} pointers`);
+            }
+            // (d) every node except the root is at least half full
+            if (!isRoot && n.keys.length < minLeafKeys) {
+                problems.push(`leaf ${id} is under half full (${n.keys.length} < ${minLeafKeys})`);
+            }
+            if (n.keys.length > tree.maxKeys) {
+                problems.push(`leaf ${id} overflows (${n.keys.length} > ${tree.maxKeys})`);
+            }
+            return;
+        }
+        if (n.children.length !== n.keys.length + 1) {
+            problems.push(`internal ${id} has ${n.keys.length} keys but ${n.children.length} children`);
+            return;
+        }
+        if (n.keys.length > tree.maxKeys) {
+            problems.push(`internal ${id} overflows (${n.keys.length} > ${tree.maxKeys})`);
+        }
+        if (!isRoot && n.children.length < minInternalChildren) {
+            problems.push(`internal ${id} is under half full (${n.children.length} < ${minInternalChildren})`);
+        }
+        if (isRoot && n.children.length < 2) {
+            problems.push(`root ${id} has fewer than two children`);
+        }
+        n.children.forEach((childId, i) => {
+            walk(childId, depth + 1, i === 0 ? low : n.keys[i - 1], i === n.keys.length ? high : n.keys[i]);
+        });
+    }
+    walk(root.id, 0, null, null);
+    // (c) all leaves at equal depth
+    if (new Set(depths).size > 1) {
+        problems.push(`leaves sit at differing depths: ${[...new Set(depths)].sort().join(', ')}`);
+    }
+    // (b) the sibling chain is sorted and reaches every leaf
+    const chain = leafChain(tree);
+    const chainKeys = chain.flatMap((id) => node(tree, id).keys);
+    for (let i = 1; i < chainKeys.length; i++) {
+        if (compareKeys(chainKeys[i - 1], chainKeys[i]) >= 0) {
+            problems.push('the leaf sibling chain is not in ascending key order');
+            break;
+        }
+    }
+    const leavesInTree = [...visited].filter((id) => node(tree, id).kind === 'leaf');
+    if (chain.length !== leavesInTree.length) {
+        problems.push(`the sibling chain reaches ${chain.length} leaves but the tree has ${leavesInTree.length}`);
+    }
+    // Every separator in an internal node must actually exist as a leaf key
+    // (the copy-up rule) — a pushed-up leaf separator would break lookups.
+    const leafKeySet = new Set(chainKeys.map((k) => JSON.stringify(k)));
+    for (const id of visited) {
+        const n = node(tree, id);
+        if (n.kind !== 'internal')
+            continue;
+        for (const key of n.keys) {
+            if (!leafKeySet.has(JSON.stringify(key))) {
+                problems.push(`separator ${JSON.stringify(key)} in ${id} is not present in any leaf`);
+            }
+        }
+    }
+    return problems;
+}

package/dist/src/engine/index.js

@@ -0,0 +1,16 @@
+export { runQuery } from "./runQuery.js";
+export { MAX_REFERENCES, parseReferenceString, randomReferenceString, runBufferTrace, } from "./bufferTrace.js";
+export { createJoinCompareDatabase, createJoinDemoDatabase, createJoinOrderDemoDatabase, createSeedDatabase, } from "./seed.js";
+export { DATASETS, DATASET_IDS, DEFAULT_DATASET, isDatasetId, } from "./datasets.js";
+export { createTracer } from "./trace.js";
+export { parse, toDisplayTree, columnsIn, tokenize } from "./parser/index.js";
+export { buildPlan, estimatePlan, exprToSql, optimize, OPTIMIZER_RULES, rootEstimate, selectivityOf, toPlanDisplay, } from "./planner/index.js";
+export { costOfOrder, isReorderableChain, joinGraphFromAst, rebuildJoinsForOrder, reorderJoinsIfCheaper, runJoinOrderDP, writtenOrderFromAst, } from "./planner/joinOrder.js";
+export { buildHeap, createBufferPool, policyFor, REPLACEMENT_POLICY_LABELS, REPLACEMENT_POLICY_NAMES, USAGE_COUNT_CAP, } from "./storage/index.js";
+export { allKeys, buildIndex, createTree, DEFAULT_MAX_KEYS, deleteKey, descend, height, columnsOfIndex, indexNameOf, indexSpecsOf, insert, keyList, search, toIndexDisplay, uniqueViolation, validate, } from "./index/index.js";
+export { evaluatePredicate, externalMergeSort, passes, sortPassCount, sortTempPageCount } from "./exec/index.js";
+export { createLockManager } from "./locks/index.js";
+export { applyEvent, createTraceProjector, initialViewState, stateAt, } from "./viewState.js";
+export { DEFAULT_ENGINE_OPTIONS, IMPLEMENTED_STAGES, STAGES } from "./types.js";
+export { analyzeTable, statsToRows } from "./stats.js";
+export { finalPlan, nodeKey } from "./explain.js";

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

@@ -0,0 +1 @@
+export { createLockManager } from "./lockManager.js";