querylens 0.1.0

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

@@ -0,0 +1,481 @@
+/**
+ * A B+Tree. All data lives in the leaves; internal nodes hold only separator
+ * keys. Leaves are chained left-to-right so a range scan can walk them.
+ *
+ * THE SPLIT RULE (plan.md §7.6) — this is where implementations go wrong:
+ *
+ *   leaf split     → COPY up.  The separator goes to the parent *and stays in
+ *                              the leaf*, because leaves must hold every key.
+ *   internal split → PUSH up.  The middle key moves to the parent and is
+ *                              *removed* from the node.
+ *
+ * Applying one where the other belongs yields a tree that looks plausible and
+ * silently returns wrong rows. The property tests exist for exactly that.
+ *
+ * Fan-out is deliberately tiny (4 keys). Real fan-out is in the hundreds and
+ * would never split on a demo dataset — a case where the simplified model
+ * teaches better than the faithful one.
+ */
+import { compareValues } from "../value.js";
+export const isProbe = (key) => typeof key === 'object' && key !== null && 'bound' in key;
+export const isEntry = (key) => typeof key === 'object' && key !== null && 'page' in key;
+/** The entry an index over `values` holds for the row at `pointer` — or, on a clustered table's secondary index, for `clusterKey` instead (plan.md §25.4 B3e). */
+export function entryKey(values, pointer, clusterKey) {
+    return { values, page: pointer.pageId, slot: pointer.slot, ...(clusterKey ? { clusterKey } : {}) };
+}
+/** The bound just before every entry with these leading values (`'low'`) or just after them all (`'high'`). */
+export function probe(values, bound) {
+    return { values, bound };
+}
+/** The column values of a key: a scalar is its own one value, an entry or probe carries its list. */
+export function valuesOf(key) {
+    return typeof key === 'object' && key !== null ? key.values : [key];
+}
+export const DEFAULT_MAX_KEYS = 4;
+// NULL sorts before everything and equals only NULL. A NULL never reaches a plain index's leading column (it is
+// not indexed), but a composite index's *later* columns can hold one — and `(0, NULL)` must not read as `(0, '')`.
+// The shared order every index-shaped structure in this engine uses (`value.ts`'s own doc comment names the rest).
+const compareScalar = compareValues;
+/**
+ * Orders numbers numerically, strings lexicographically, booleans as 0/1 — and,
+ * for a table's index, entries by their values (column by column) and then by
+ * the row's address. A probe sorts before (`'low'`) or after (`'high'`) every
+ * entry that shares its leading values; a shorter list of values is a prefix.
+ */
+export function compareKeys(a, b) {
+    const aObj = typeof a === 'object' && a !== null;
+    const bObj = typeof b === 'object' && b !== null;
+    if (!aObj && !bObj)
+        return compareScalar(a, b);
+    const av = valuesOf(a);
+    const bv = valuesOf(b);
+    const shared = Math.min(av.length, bv.length);
+    for (let i = 0; i < shared; i++) {
+        const c = compareScalar(av[i], bv[i]);
+        if (c !== 0)
+            return c;
+    }
+    // Equal on every shared value: a probe decides by its bound, otherwise the shorter list is smaller.
+    const rank = (key) => (isProbe(key) ? (key.bound === 'low' ? -1 : 1) : 0);
+    if (isProbe(a) || isProbe(b)) {
+        if (isProbe(a) && isProbe(b))
+            return rank(a) - rank(b);
+        return isProbe(a) ? rank(a) : -rank(b);
+    }
+    if (av.length !== bv.length)
+        return av.length - bv.length;
+    const ea = a;
+    const eb = b;
+    // A clustered table's secondary entry has no address to break the tie with (plan.md §25.4 B3e) — its clustering
+    // key does the job instead, exactly the way the row address does everywhere else: it is unique per row.
+    if (ea.clusterKey || eb.clusterKey) {
+        const ak = ea.clusterKey ?? [];
+        const bk = eb.clusterKey ?? [];
+        const shared2 = Math.min(ak.length, bk.length);
+        for (let i = 0; i < shared2; i++) {
+            const c = compareScalar(ak[i], bk[i]);
+            if (c !== 0)
+                return c;
+        }
+        return ak.length - bk.length;
+    }
+    return ea.page - eb.page || ea.slot - eb.slot;
+}
+/** A key as text for a step's detail: the value for a scalar, `value @page.slot` for an entry — or, on a clustered
+ *  table's secondary index, `value → clustering key` (plan.md §25.4 B3e), since it holds no address at all. */
+function describeKey(key) {
+    if (isEntry(key)) {
+        return key.clusterKey
+            ? `${key.values.map(String).join(', ')} → (${key.clusterKey.map(String).join(', ')})`
+            : `${key.values.map(String).join(', ')} @${String(key.page)}.${String(key.slot)}`;
+    }
+    if (isProbe(key))
+        return key.values.map(String).join(', ');
+    return String(key);
+}
+export function node(tree, id) {
+    const n = tree.nodes[id];
+    if (!n)
+        throw new Error(`B+Tree node ${id} is missing`);
+    return n;
+}
+export function createTree(maxKeys = DEFAULT_MAX_KEYS, firstPageId = 0, tiebreak = false) {
+    const root = {
+        kind: 'leaf',
+        id: 'n0',
+        pageId: firstPageId,
+        keys: [],
+        pointers: [],
+        next: null,
+    };
+    return {
+        ...(tiebreak ? { tiebreak } : {}),
+        rootId: root.id,
+        nodes: { [root.id]: root },
+        maxKeys,
+        nextNodeId: 1,
+        nextPageId: firstPageId + 1,
+    };
+}
+function allocate(tree, make) {
+    const created = make(`n${tree.nextNodeId}`, tree.nextPageId);
+    tree.nextNodeId += 1;
+    tree.nextPageId += 1;
+    tree.nodes[created.id] = created;
+    return created;
+}
+/** Index of the first key >= `key`. Exported for `index/rangeLookup.ts` — a range scan's own starting position within its first leaf. */
+export function lowerBound(keys, key) {
+    let lo = 0;
+    let hi = keys.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (compareKeys(keys[mid], key) < 0)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** Which child of an internal node covers `key`. */
+export function childIndexFor(internal, key) {
+    let i = 0;
+    while (i < internal.keys.length && compareKeys(key, internal.keys[i]) >= 0)
+        i += 1;
+    return i;
+}
+/** Root-to-leaf node ids for `key`. The last entry is always the leaf. */
+export function descend(tree, key) {
+    const path = [tree.rootId];
+    let current = node(tree, tree.rootId);
+    while (current.kind === 'internal') {
+        const childId = current.children[childIndexFor(current, key)];
+        path.push(childId);
+        current = node(tree, childId);
+    }
+    return path;
+}
+/** How many values an entry of this tree holds: one for a plain index, more for a composite one. */
+export function entryWidth(tree) {
+    const first = node(tree, leftmostPath(tree).at(-1));
+    const key = first.keys[0];
+    return key === undefined ? 1 : valuesOf(key).length;
+}
+/**
+ * The lowest key of the leaf to the right of `leaf` — what its parent's separator says, and what a real engine keeps on the
+ * page itself as its "high key" (PostgreSQL does) so a scan can tell the run of equal values has ended *without reading the
+ * next page*. `null` for the rightmost leaf, and for an empty one. Pure bookkeeping: it touches no buffer-pool page.
+ */
+export function highKey(tree, leaf) {
+    const first = leaf.keys[0];
+    if (first === undefined)
+        return null;
+    let bound = null;
+    let current = node(tree, tree.rootId);
+    while (current.kind === 'internal') {
+        const at = childIndexFor(current, first);
+        if (at < current.keys.length)
+            bound = current.keys[at];
+        current = node(tree, current.children[at]);
+    }
+    return bound;
+}
+/**
+ * Root-to-leaf node ids along the tree's leftmost edge — always child 0 at
+ * every internal node. The starting point for a range scan with no lower
+ * bound (`age < 30`, with nothing to descend *toward*), mirroring `descend`'s
+ * shape exactly so `index/rangeLookup.ts` can narrate either the same way.
+ */
+export function leftmostPath(tree) {
+    const path = [tree.rootId];
+    let current = node(tree, tree.rootId);
+    while (current.kind === 'internal') {
+        const childId = current.children[0];
+        path.push(childId);
+        current = node(tree, childId);
+    }
+    return path;
+}
+/**
+ * Finds `key`. Given a plain value on a table's index — which holds entries, not bare values — it finds the *first*
+ * entry for that value (the one lowest in row-address order); `emitIndexLookup` is the narrated version that also
+ * returns the rest of the run.
+ */
+export function search(tree, key) {
+    const target = tree.tiebreak && !isEntry(key) && !isProbe(key) ? probe([key], 'low') : key;
+    const path = descend(tree, target);
+    let leaf = node(tree, path[path.length - 1]);
+    let at = lowerBound(leaf.keys, target);
+    // The first entry for a value can start the *next* leaf (the probe routed left of a separator that equals it).
+    if (at >= leaf.keys.length && leaf.next !== null && tree.tiebreak) {
+        leaf = node(tree, leaf.next);
+        at = 0;
+    }
+    const matches = (candidate) => target === key ? compareKeys(candidate, key) === 0 : compareKeys(valuesOf(candidate)[0], key) === 0;
+    const found = at < leaf.keys.length && matches(leaf.keys[at]);
+    return {
+        path,
+        leafId: leaf.id,
+        slotInLeaf: found ? at : -1,
+        pointer: found ? leaf.pointers[at] : null,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Insert                                                                      */
+/* -------------------------------------------------------------------------- */
+export function insert(tree, key, pointer) {
+    const path = descend(tree, key);
+    const leaf = node(tree, path[path.length - 1]);
+    const at = lowerBound(leaf.keys, key);
+    if (at < leaf.keys.length && compareKeys(leaf.keys[at], key) === 0) {
+        // The same key again — for a table's index that is the same *row* (the address is part of the key), so
+        // there is nothing new to hold; for a scalar sandbox tree, last writer wins.
+        leaf.pointers[at] = pointer;
+        return;
+    }
+    leaf.keys.splice(at, 0, key);
+    leaf.pointers.splice(at, 0, pointer);
+    if (leaf.keys.length <= tree.maxKeys)
+        return;
+    splitLeaf(tree, path, leaf);
+}
+function splitLeaf(tree, path, leaf) {
+    const mid = Math.ceil(leaf.keys.length / 2);
+    const right = allocate(tree, (id, pageId) => ({
+        kind: 'leaf',
+        id,
+        pageId,
+        keys: leaf.keys.slice(mid),
+        pointers: leaf.pointers.slice(mid),
+        next: leaf.next,
+    }));
+    leaf.keys = leaf.keys.slice(0, mid);
+    leaf.pointers = leaf.pointers.slice(0, mid);
+    leaf.next = right.id;
+    // COPY up: the separator also remains as the right leaf's first key.
+    const separator = right.keys[0];
+    insertIntoParent(tree, path.slice(0, -1), leaf.id, separator, right.id);
+}
+function insertIntoParent(tree, ancestors, leftId, separator, rightId) {
+    if (ancestors.length === 0) {
+        const root = allocate(tree, (id, pageId) => ({
+            kind: 'internal',
+            id,
+            pageId,
+            keys: [separator],
+            children: [leftId, rightId],
+        }));
+        tree.rootId = root.id;
+        return;
+    }
+    const parent = node(tree, ancestors[ancestors.length - 1]);
+    const at = parent.children.indexOf(leftId);
+    parent.keys.splice(at, 0, separator);
+    parent.children.splice(at + 1, 0, rightId);
+    if (parent.keys.length <= tree.maxKeys)
+        return;
+    const mid = Math.floor(parent.keys.length / 2);
+    // PUSH up: the middle key leaves this node entirely.
+    const pushed = parent.keys[mid];
+    const right = allocate(tree, (id, pageId) => ({
+        kind: 'internal',
+        id,
+        pageId,
+        keys: parent.keys.slice(mid + 1),
+        children: parent.children.slice(mid + 1),
+    }));
+    parent.keys = parent.keys.slice(0, mid);
+    parent.children = parent.children.slice(0, mid + 1);
+    insertIntoParent(tree, ancestors.slice(0, -1), parent.id, pushed, right.id);
+}
+/* -------------------------------------------------------------------------- */
+/* Delete                                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * THE DELETE RULE (plan.md §7.6) — the mirror of the split rule, and just as
+ * easy to get subtly wrong:
+ *
+ *   leaf underflow     → borrow a key from a sibling, or MERGE with one. The
+ *                        separator between the two in the parent is *rewritten*
+ *                        to the new boundary (borrow) or *removed* (merge).
+ *   internal underflow → borrow, or merge — and the parent's separator is
+ *                        *pulled down* into the merged node, because internal
+ *                        nodes hold no data and must not duplicate a key.
+ *   deleted key was a separator → the copy in every ancestor that routes into
+ *                        this leaf's subtree is replaced with the leaf's new
+ *                        minimum, so `validate`'s "every separator exists as a
+ *                        leaf key" invariant still holds after any delete.
+ *
+ * "Under half full" is `ceil(maxKeys / 2)` keys for a leaf and
+ * `ceil((maxKeys + 1) / 2)` children for an internal node — the same floors
+ * `validate` enforces. The root is exempt: it may hold as little as one key
+ * (leaf) or two children (internal), and collapses into its only child when it
+ * drops below that.
+ */
+const minLeafKeys = (tree) => Math.ceil(tree.maxKeys / 2);
+const minInternalChildren = (tree) => Math.ceil((tree.maxKeys + 1) / 2);
+export function deleteKey(tree, key) {
+    const steps = [];
+    const path = descend(tree, key);
+    const leaf = node(tree, path[path.length - 1]);
+    const at = lowerBound(leaf.keys, key);
+    if (at >= leaf.keys.length || compareKeys(leaf.keys[at], key) !== 0) {
+        return { found: false, steps };
+    }
+    leaf.keys.splice(at, 1);
+    leaf.pointers.splice(at, 1);
+    steps.push({ kind: 'remove', node: leaf.id, detail: describeKey(key) });
+    // The deleted key can only be a separator if it was this leaf's minimum.
+    // Rewrite it wherever an ancestor routes right into this leaf's subtree.
+    if (at === 0 && leaf.keys.length > 0) {
+        updateSeparators(tree, path, key, leaf.keys[0], steps);
+    }
+    // The root leaf is allowed to sit below the floor, empty included.
+    if (path.length === 1 || leaf.keys.length >= minLeafKeys(tree)) {
+        return { found: true, steps };
+    }
+    rebalanceLeaf(tree, path, steps);
+    return { found: true, steps };
+}
+function updateSeparators(tree, path, oldKey, newKey, steps) {
+    for (let i = 0; i < path.length - 1; i++) {
+        const parent = node(tree, path[i]);
+        const childIndex = parent.children.indexOf(path[i + 1]);
+        if (childIndex > 0 && compareKeys(parent.keys[childIndex - 1], oldKey) === 0) {
+            parent.keys[childIndex - 1] = newKey;
+            steps.push({
+                kind: 'update-separator',
+                node: parent.id,
+                detail: `${describeKey(oldKey)} → ${describeKey(newKey)}`,
+            });
+        }
+    }
+}
+function rebalanceLeaf(tree, path, steps) {
+    const leaf = node(tree, path[path.length - 1]);
+    const parent = node(tree, path[path.length - 2]);
+    const idx = parent.children.indexOf(leaf.id);
+    const floor = minLeafKeys(tree);
+    const left = idx > 0 ? node(tree, parent.children[idx - 1]) : null;
+    const right = idx < parent.children.length - 1
+        ? node(tree, parent.children[idx + 1])
+        : null;
+    if (left && left.keys.length > floor) {
+        leaf.keys.unshift(left.keys.pop());
+        leaf.pointers.unshift(left.pointers.pop());
+        parent.keys[idx - 1] = leaf.keys[0];
+        steps.push({ kind: 'borrow-left', node: leaf.id, detail: `from ${left.id}` });
+        return;
+    }
+    if (right && right.keys.length > floor) {
+        leaf.keys.push(right.keys.shift());
+        leaf.pointers.push(right.pointers.shift());
+        parent.keys[idx] = right.keys[0];
+        steps.push({ kind: 'borrow-right', node: leaf.id, detail: `from ${right.id}` });
+        return;
+    }
+    // No sibling has a key to spare — merge, and drop the separator between them.
+    if (left) {
+        left.keys.push(...leaf.keys);
+        left.pointers.push(...leaf.pointers);
+        left.next = leaf.next;
+        delete tree.nodes[leaf.id];
+        parent.keys.splice(idx - 1, 1);
+        parent.children.splice(idx, 1);
+        steps.push({ kind: 'merge', node: left.id, detail: `absorbed ${leaf.id}` });
+    }
+    else if (right) {
+        leaf.keys.push(...right.keys);
+        leaf.pointers.push(...right.pointers);
+        leaf.next = right.next;
+        delete tree.nodes[right.id];
+        parent.keys.splice(idx, 1);
+        parent.children.splice(idx + 1, 1);
+        steps.push({ kind: 'merge', node: leaf.id, detail: `absorbed ${right.id}` });
+    }
+    rebalanceInternal(tree, path.slice(0, -1), steps);
+}
+function rebalanceInternal(tree, path, steps) {
+    const target = node(tree, path[path.length - 1]);
+    if (path.length === 1) {
+        // The root may thin all the way to a single child; then it *is* that child.
+        if (target.children.length === 1) {
+            tree.rootId = target.children[0];
+            delete tree.nodes[target.id];
+            steps.push({ kind: 'root-collapse', node: tree.rootId, detail: `dropped ${target.id}` });
+        }
+        return;
+    }
+    if (target.children.length >= minInternalChildren(tree))
+        return;
+    const parent = node(tree, path[path.length - 2]);
+    const idx = parent.children.indexOf(target.id);
+    const left = idx > 0 ? node(tree, parent.children[idx - 1]) : null;
+    const right = idx < parent.children.length - 1
+        ? node(tree, parent.children[idx + 1])
+        : null;
+    const floor = minInternalChildren(tree);
+    // Borrow: rotate a child across, threading it through the parent separator.
+    if (left && left.children.length > floor) {
+        target.children.unshift(left.children.pop());
+        target.keys.unshift(parent.keys[idx - 1]);
+        parent.keys[idx - 1] = left.keys.pop();
+        steps.push({ kind: 'borrow-left', node: target.id, detail: `from ${left.id}` });
+        return;
+    }
+    if (right && right.children.length > floor) {
+        target.children.push(right.children.shift());
+        target.keys.push(parent.keys[idx]);
+        parent.keys[idx] = right.keys.shift();
+        steps.push({ kind: 'borrow-right', node: target.id, detail: `from ${right.id}` });
+        return;
+    }
+    // Merge: the parent separator comes down between the two nodes' children.
+    if (left) {
+        left.keys.push(parent.keys[idx - 1], ...target.keys);
+        left.children.push(...target.children);
+        delete tree.nodes[target.id];
+        parent.keys.splice(idx - 1, 1);
+        parent.children.splice(idx, 1);
+        steps.push({ kind: 'merge', node: left.id, detail: `absorbed ${target.id}` });
+    }
+    else if (right) {
+        target.keys.push(parent.keys[idx], ...right.keys);
+        target.children.push(...right.children);
+        delete tree.nodes[right.id];
+        parent.keys.splice(idx, 1);
+        parent.children.splice(idx + 1, 1);
+        steps.push({ kind: 'merge', node: target.id, detail: `absorbed ${right.id}` });
+    }
+    rebalanceInternal(tree, path.slice(0, -1), steps);
+}
+/* -------------------------------------------------------------------------- */
+/* Reading                                                                     */
+/* -------------------------------------------------------------------------- */
+/** Leaf ids left to right, following the sibling chain from the leftmost leaf. */
+export function leafChain(tree) {
+    let current = node(tree, tree.rootId);
+    while (current.kind === 'internal')
+        current = node(tree, current.children[0]);
+    const ids = [];
+    let cursor = current;
+    const seen = new Set();
+    while (cursor && !seen.has(cursor.id)) {
+        seen.add(cursor.id);
+        ids.push(cursor.id);
+        cursor = cursor.next ? node(tree, cursor.next) : null;
+    }
+    return ids;
+}
+export function allKeys(tree) {
+    return leafChain(tree).flatMap((id) => node(tree, id).keys);
+}
+export function height(tree) {
+    let h = 1;
+    let current = node(tree, tree.rootId);
+    while (current.kind === 'internal') {
+        current = node(tree, current.children[0]);
+        h += 1;
+    }
+    return h;
+}

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

@@ -0,0 +1,99 @@
+import { createTree, entryKey, insert } from "./btree.js";
+import { bulkLoad, DEFAULT_FILL_FACTOR } from "./bulk.js";
+import { DEFAULT_MAX_KEYS } from "./btree.js";
+import { indexNameOf, isClusteringIndex } from "./spec.js";
+/** A sentinel — never dereferenced — for a clustered table's secondary entries (plan.md §25.4 B3e): they carry a
+ *  `clusterKey` instead of an address, so `page`/`slot` are meaningless and must never be fetched as a heap page. */
+const NO_ADDRESS = { pageId: -1, slot: -1 };
+/**
+ * The entry `columns`'s index holds for `row`, and the pointer to store alongside it. Ordinarily that pointer *is*
+ * the row's real heap address — `pointer`, unchanged. On a CLUSTERED table (plan.md §25.4 B3e), the clustering key's
+ * own index still gets that real address (its whole point: no second structure is needed to find a row by it), but
+ * every OTHER index gets the row's clustering key instead, behind the sentinel `NO_ADDRESS` — a clustered leaf can
+ * split and move rows between pages, and the clustering key never goes stale the way a physical pointer would.
+ */
+export function entryFor(columns, row, pointer, clusteredKey) {
+    if (!clusteredKey || isClusteringIndex(clusteredKey, columns)) {
+        return { key: entryKey(keyValuesOf(row, columns), pointer), pointer };
+    }
+    const clusterKey = keyValuesOf(row, clusteredKey);
+    return { key: entryKey(keyValuesOf(row, columns), NO_ADDRESS, clusterKey), pointer: NO_ADDRESS };
+}
+/**
+ * Builds one index over the heap. Index nodes are numbered starting at
+ * `firstPageId` (the last heap page by default), so it competes for the same
+ * buffer frames as the heap — which is the honest arrangement, and the
+ * reason an index lookup shows up in the pool at all. `firstPageId` is a
+ * parameter, not always `heap.pages.length`, so `buildIndexes` below can
+ * chain several trees over the same heap without any two ever claiming the
+ * same page id.
+ *
+ * Building is setup, not query execution, so it emits nothing: the trace
+ * describes running your query, not preparing the database.
+ */
+export function buildIndex(heap, 
+/** A column name (the plain, single-column index) or a full spec (a composite one). */
+index, maxKeys = DEFAULT_MAX_KEYS, firstPageId = heap.pages.length, 
+/** How to build it — one entry at a time (the default), or bulk-loaded and packed to a fill factor (plan.md §25.4 B3d). */
+build = { method: 'incremental' }, 
+/** The table's clustering key (plan.md §25.4 B3e), if it has one. */
+clusteredKey) {
+    const columns = typeof index === 'string' ? [index] : index.columns;
+    const entries = [];
+    heap.pages.forEach((page) => {
+        page.rows.forEach((row, slot) => {
+            const values = keyValuesOf(row, columns);
+            // A NULL *leading* column is not indexed — an equality on it never matches, so a lookup has nothing to
+            // find and NULL-keyed rows fall back to a scan. A NULL further along (`(1, NULL)`) is an ordinary entry:
+            // the row must still be found by an equality on the columns before it.
+            if (values[0] === null)
+                return;
+            entries.push(entryFor(columns, row, { pageId: page.pageId, slot }, clusteredKey));
+        });
+    });
+    // Entry keys (values + row address, or a clustered secondary's clustering key), so the key may repeat: two rows
+    // with the same values are two distinct entries, adjacent in the leaves, and neither overwrites the other.
+    let tree;
+    if (build.method === 'bulk') {
+        tree = bulkLoad(entries, maxKeys, firstPageId, build.fillFactor ?? DEFAULT_FILL_FACTOR, true);
+    }
+    else {
+        tree = createTree(maxKeys, firstPageId, true);
+        for (const { key, pointer } of entries)
+            insert(tree, key, pointer);
+    }
+    if (typeof index !== 'string' && index.unique)
+        tree.unique = true;
+    if (clusteredKey && !isClusteringIndex(clusteredKey, columns))
+        tree.clusteredVia = indexNameOf(clusteredKey);
+    return tree;
+}
+/** The values of `columns` in `row`, in key order — what an index entry for that row holds. */
+export function keyValuesOf(row, columns) {
+    return columns.map((column) => row[column] ?? null);
+}
+/**
+ * One independent B+Tree per index — a plain single-column one for each bare name, or a composite one for a
+ * spec — plan.md §22.2's "candidate indexes." Trees are keyed by the index's name (`indexNameOf`). Each is built in
+ * turn, starting where the previous one's own page ids left off (`heap.pages.length` for the first), so however
+ * many indexes a table declares, none of their page ids ever collide with the heap's or each other's.
+ */
+export function buildIndexes(heap, indexes, maxKeys = DEFAULT_MAX_KEYS, 
+/** Where the first tree's pages begin — the heap's end by default; a join's *inner* table starts past the outer's. */
+firstPageId = heap.pages.length, build, 
+/** The table's clustering key (plan.md §25.4 B3e), if it has one. */
+clusteredKey) {
+    const trees = {};
+    for (const index of indexes) {
+        const name = indexNameOf(typeof index === 'string' ? [index] : index.columns);
+        const tree = buildIndex(heap, index, maxKeys, firstPageId, build, clusteredKey);
+        trees[name] = tree;
+        firstPageId = tree.nextPageId;
+    }
+    return trees;
+}
+/** Total pages in the database: heap pages, then every index's own pages. */
+export function pageCountFor(heap, trees) {
+    const nextPageIds = Object.values(trees).map((t) => t.nextPageId);
+    return nextPageIds.length > 0 ? Math.max(...nextPageIds) : heap.pages.length;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Bulk-loading a B+Tree (plan.md §25.4 B3d) — the other way to build an index.
+ *
+ * `insert` builds one entry at a time, splitting a node whenever it overflows. Fed keys in ascending order that
+ * leaves every left leaf a fixed fraction full — three keys of four at the default fan-out: a full leaf splits, and
+ * nothing is ever inserted into its left half again.
+ * A **bulk load** knows all the entries up front. It sorts them, packs them into leaves left to right up to a
+ * **fill factor** — 100% leaves no room to grow, 70% leaves 30% free so the next inserts do not split at once — and
+ * builds each level above from the one below, bottom-up, with no splits at all. It is how a database builds an index
+ * over data that already exists (`CREATE INDEX`), and why that is much faster and yields a smaller, shallower tree
+ * than inserting the rows one by one.
+ *
+ * The result is an ordinary tree — the same node shapes, the same invariants (`validate`), the same `insert` and
+ * `deleteKey` afterwards. Only its *packing* differs, and packing is what decides the height and how many pages a
+ * lookup reads.
+ */
+import { compareKeys, createTree, DEFAULT_MAX_KEYS } from "./btree.js";
+/** How full each node is packed: a fraction of its capacity. Below one half a node would break the tree's minimum occupancy. */
+export const MIN_FILL_FACTOR = 0.5;
+export const DEFAULT_FILL_FACTOR = 1;
+/** Splits `count` items into groups of about `size`, each at least `min` and at most `max` — the last group is the only one that can fall short, and is topped up from (or merged into) the one before. */
+function groupSizes(count, size, min, max) {
+    const sizes = [];
+    let left = count;
+    while (left > 0) {
+        const take = Math.min(size, left);
+        sizes.push(take);
+        left -= take;
+    }
+    const last = sizes.length - 1;
+    if (last > 0 && sizes[last] < min) {
+        const together = sizes[last - 1] + sizes[last];
+        if (together <= max) {
+            sizes.splice(last - 1, 2, together);
+        }
+        else {
+            // Too many for one node, so share them: each gets at least `min` because together > max ≥ 2·min − 1.
+            sizes[last - 1] = Math.ceil(together / 2);
+            sizes[last] = together - sizes[last - 1];
+        }
+    }
+    return sizes;
+}
+/**
+ * Builds a tree over `entries` — sorted here, so callers need not — packing every node to `fillFactor`.
+ * `tiebreak` says the keys are entry keys (a table's index) rather than plain values.
+ */
+export function bulkLoad(entries, maxKeys = DEFAULT_MAX_KEYS, firstPageId = 0, fillFactor = DEFAULT_FILL_FACTOR, tiebreak = true) {
+    const tree = createTree(maxKeys, firstPageId, tiebreak);
+    const sorted = [...entries].sort((a, b) => compareKeys(a.key, b.key));
+    const fill = Math.min(1, Math.max(MIN_FILL_FACTOR, fillFactor));
+    // Everything fits in one leaf: the root, as `createTree` already made it.
+    if (sorted.length <= maxKeys) {
+        const root = tree.nodes[tree.rootId];
+        root.keys = sorted.map((e) => e.key);
+        root.pointers = sorted.map((e) => e.pointer);
+        return tree;
+    }
+    const nodes = {};
+    let nextId = 0;
+    let nextPage = firstPageId;
+    const idFor = () => ({ id: `n${String(nextId++)}`, pageId: nextPage++ });
+    // Leaves: as full as the fill factor allows, but never below the half-full floor.
+    const minLeaf = Math.ceil(maxKeys / 2);
+    const leafSize = Math.max(minLeaf, Math.floor(maxKeys * fill));
+    let level = [];
+    let cursor = 0;
+    let previous = null;
+    for (const size of groupSizes(sorted.length, leafSize, minLeaf, maxKeys)) {
+        const chunk = sorted.slice(cursor, cursor + size);
+        cursor += size;
+        const leaf = {
+            kind: 'leaf',
+            ...idFor(),
+            keys: chunk.map((e) => e.key),
+            pointers: chunk.map((e) => e.pointer),
+            next: null,
+        };
+        if (previous)
+            previous.next = leaf.id;
+        previous = leaf;
+        nodes[leaf.id] = leaf;
+        level.push({ id: leaf.id, min: leaf.keys[0] });
+    }
+    // Each level above groups the one below into nodes of up to `maxKeys + 1` children, packed to the same fill factor.
+    const minChildren = Math.ceil((maxKeys + 1) / 2);
+    const childSize = Math.max(minChildren, Math.floor((maxKeys + 1) * fill));
+    while (level.length > 1) {
+        const above = [];
+        let at = 0;
+        for (const size of groupSizes(level.length, childSize, minChildren, maxKeys + 1)) {
+            const group = level.slice(at, at + size);
+            at += size;
+            const internal = {
+                kind: 'internal',
+                ...idFor(),
+                // A separator is the lowest key of the subtree to its right.
+                keys: group.slice(1).map((child) => child.min),
+                children: group.map((child) => child.id),
+            };
+            nodes[internal.id] = internal;
+            above.push({ id: internal.id, min: group[0].min });
+        }
+        level = above;
+    }
+    return { ...tree, rootId: level[0].id, nodes, nextNodeId: nextId, nextPageId: nextPage };
+}