querylens 0.1.0

package/dist/src/engine/runQuery.js

@@ -0,0 +1,393 @@
+/**
+ * The engine entry point, and the whole of the engine's public surface.
+ *
+ *   pure · synchronous · no DOM · no React · fully serializable output
+ *
+ * Kept worker-ready on purpose (plan.md §5) but deliberately run on the main
+ * thread in v0: step-back needs the full event history regardless, so once the
+ * UI holds the whole array a worker boundary buys nothing.
+ */
+import { emitAnalyzeParseEvents, emitDeleteParseEvents, emitInsertParseEvents, emitParseEvents, emitUpdateParseEvents, parseStatement, } from "./parser/index.js";
+import { analyzeTable, statsToRows } from "./stats.js";
+import { emitDeletePlanEvents, emitPlanEvents, emitUpdatePlanEvents, findIndexNestedLoopJoins, findSortDistinct, isReorderableChain, joinsIn, needsSortSpill, reorderJoinsIfCheaper, } from "./planner/index.js";
+import { buildHeap, createBufferPool } from "./storage/index.js";
+import { buildIndexes, describeUniqueKey, findIndexSpec, indexSpecsOf, pageCountFor } from "./index/index.js";
+import { walkExpr } from "./parser/index.js";
+import { execute } from "./exec/index.js";
+import { executeDelete } from "./exec/delete.js";
+import { executeInsert } from "./exec/insert.js";
+import { executeUpdate } from "./exec/update.js";
+import { UniqueViolation } from "./exec/unique.js";
+import { sortTempPageCount } from "./exec/sort.js";
+import { createLockManager } from "./locks/index.js";
+import { explainResult } from "./explain.js";
+import { resolveWhereSubqueries } from "./subquery.js";
+import { createTracer } from "./trace.js";
+import { DEFAULT_ENGINE_OPTIONS } from "./types.js";
+/** The error a rejected `INSERT` or `UPDATE` reports: which key is taken, by which row, and that nothing changed. */
+function uniqueError(violation, heap, span) {
+    const holder = heap.pages.find((p) => p.pageId === violation.holder.pageId)?.rows[violation.holder.slot];
+    return {
+        message: `Duplicate key — the UNIQUE index on \`${violation.index}\` already holds ${describeUniqueKey(violation.columns, violation.values)}.`,
+        hint: `A UNIQUE index allows one row per key (NULLs excepted: NULL is not equal to NULL).${holder ? ` The row that has it: ${JSON.stringify(holder)}.` : ''} Use a different value, or change or delete that row first. Nothing was changed.`,
+        from: span.from,
+        to: span.to,
+    };
+}
+/**
+ * `ast`, with its `JOIN`s reordered to the cheapest sequence `reorderJoinsIfCheaper` finds, alongside the order it
+ * was actually *typed* in (`writtenOrder`) — present only when reordering genuinely changed something, which is
+ * also the signal `emitPlanEvents` uses to narrate it. Otherwise `ast` comes back completely unchanged. Tolerant
+ * of a table that turns out not to exist: resolving `db.tables` here is a *look*, not the real validation (that
+ * happens right after, against whichever `ast` this returns), so a missing name just means "nothing to reorder,"
+ * never a different error than the query would have gotten anyway.
+ */
+function applyCostOrder(ast, db, rowsPerPage) {
+    if (!isReorderableChain(ast))
+        return { ast };
+    const names = [ast.from.name, ...(ast.joins ?? []).map((j) => j.table.name)];
+    const tables = {};
+    for (const name of names) {
+        const t = db.tables[name];
+        if (!t)
+            return { ast };
+        tables[name] = t;
+    }
+    const reordered = reorderJoinsIfCheaper(ast, tables, rowsPerPage);
+    return reordered ? { ast: { ...ast, from: reordered.from, joins: reordered.joins }, writtenOrder: names } : { ast };
+}
+export function runQuery(sql, db, options = DEFAULT_ENGINE_OPTIONS, hooks = {}) {
+    const { emit, drain } = createTracer();
+    const parsed = parseStatement(sql);
+    if (!parsed.ok) {
+        return { events: drain(), rows: [], error: parsed.error };
+    }
+    const parsedAst = parsed.ast;
+    // EXPLAIN [ANALYZE] SELECT (plan.md §25.4 B6): the inner query, run and then reported as a plan.
+    if (parsedAst.kind === 'explain') {
+        return explainResult(sql, parsedAst, (inner) => runQuery(inner, db, options, hooks));
+    }
+    // A chain of 2+ plain inner JOINs may cost less in a different order (plan.md §25.4 C5 slice 3) — resolved here,
+    // before any table is looked up for real, so every later step (table/column validation, the heap, the plan
+    // itself) already sees whichever order will actually run. Left exactly as written when it is not eligible (a
+    // LEFT JOIN anywhere, fewer than two JOINs), already optimal, or names a table that turns out not to exist —
+    // the ordinary "no table called X" error just below is exactly as useful either way. `writtenJoinOrder` is only
+    // ever set alongside a real change, and is threaded through to `emitPlanEvents` so the trace can say so.
+    const { ast, writtenOrder: writtenJoinOrder } = parsedAst.kind === 'select'
+        ? applyCostOrder(parsedAst, db, options.rowsPerPage)
+        : { ast: parsedAst, writtenOrder: undefined };
+    const tableRef = ast.kind === 'insert' ? ast.into : ast.kind === 'update' || ast.kind === 'analyze' ? ast.table : ast.from;
+    const table = db.tables[tableRef.name];
+    if (!table) {
+        const known = Object.keys(db.tables);
+        return {
+            events: drain(),
+            rows: [],
+            error: {
+                message: `There is no table called \`${tableRef.name}\`.`,
+                hint: known.length === 1 ? `The only table is \`${known[0]}\`.` : `Tables: ${known.join(', ')}.`,
+                from: tableRef.span.from,
+                to: tableRef.span.to,
+            },
+        };
+    }
+    // ANALYZE (plan.md §25.4 C1): a real scan, nothing to plan or optimize, and no join/column checks below apply.
+    if (ast.kind === 'analyze') {
+        emitAnalyzeParseEvents(emit, ast);
+        const stats = analyzeTable(table);
+        const rows = statsToRows(stats);
+        emit(`ANALYZE scanned all ${String(table.rows.length)} row${table.rows.length === 1 ? '' : 's'} of \`${table.name}\` and built statistics for ${String(table.columns.length)} column${table.columns.length === 1 ? '' : 's'}. The next query against \`${table.name}\` reads these instead of scanning the live rows to estimate a plan.`, { stage: 'result', rows });
+        return { events: drain(), rows, analyze: { table: table.name, stats } };
+    }
+    // Every JOIN's own table (plan.md §25.4 C3 slice b: 0 or more, left-deep) — resolved here, alongside the
+    // FROM/INTO table above, so all of them go through the same "no table called X" shape.
+    const joins = ast.kind === 'select' ? (ast.joins ?? []) : [];
+    const joinTables = {};
+    for (const j of joins) {
+        const t = db.tables[j.table.name];
+        if (!t) {
+            const known = Object.keys(db.tables);
+            return {
+                events: drain(),
+                rows: [],
+                error: {
+                    message: `There is no table called \`${j.table.name}\`.`,
+                    hint: known.length === 1 ? `The only table is \`${known[0]}\`.` : `Tables: ${known.join(', ')}.`,
+                    from: j.table.span.from,
+                    to: j.table.span.to,
+                },
+            };
+        }
+        joinTables[j.table.name] = t;
+    }
+    const unknownColumn = referencedColumns(ast).find((c) => {
+        const named = c.table ? db.tables[c.table] : table;
+        return !named || !named.columns.includes(c.name);
+    });
+    if (unknownColumn) {
+        const named = (unknownColumn.table ? db.tables[unknownColumn.table] : table);
+        return {
+            events: drain(),
+            rows: [],
+            error: {
+                message: `\`${named.name}\` has no column called \`${unknownColumn.name}\`.`,
+                hint: `Columns: ${named.columns.join(', ')}.`,
+                from: unknownColumn.span.from,
+                to: unknownColumn.span.to,
+            },
+        };
+    }
+    if (ast.kind === 'insert' && !ast.columns && ast.values.items.length !== table.columns.length) {
+        return {
+            events: drain(),
+            rows: [],
+            error: {
+                message: `\`${table.name}\` has ${table.columns.length} column${table.columns.length === 1 ? '' : 's'}, but this INSERT gives ${ast.values.items.length} value${ast.values.items.length === 1 ? '' : 's'}.`,
+                hint: `Columns: ${table.columns.join(', ')}. Name the columns you're setting if you don't want to supply all of them, e.g. INSERT INTO ${table.name} (${table.columns[0]}) VALUES (...).`,
+                from: ast.values.span.from,
+                to: ast.values.span.to,
+            },
+        };
+    }
+    const heap = buildHeap(table, options.rowsPerPage);
+    const trees = buildIndexes(heap, indexSpecsOf(table), undefined, undefined, options.indexBuild, table.clusteredKey);
+    const locks = createLockManager(emit);
+    if (ast.kind === 'insert') {
+        emitInsertParseEvents(emit, ast);
+        const row = buildInsertRow(ast, table);
+        const lastPage = heap.pages[heap.pages.length - 1];
+        const insertNeedsNewPage = lastPage.rows.length >= options.rowsPerPage;
+        const pool = createBufferPool(pageCountFor(heap, trees) + (insertNeedsNewPage ? 1 : 0), options, emit);
+        let inserted;
+        try {
+            inserted = executeInsert(row, { emit, pool, locks, heap, trees, table, options }).row;
+        }
+        catch (e) {
+            if (e instanceof UniqueViolation) {
+                const error = uniqueError(e, heap, ast.values.span);
+                emit(`INSERT is rejected — ${error.message} Nothing was changed.`, { stage: 'result', rows: [] });
+                return { events: drain(), rows: [], error };
+            }
+            throw e;
+        }
+        hooks.afterWrite?.(trees);
+        const rows = [...table.rows, inserted];
+        emit(`1 row inserted, from ${pool.stats.misses} disk read${pool.stats.misses === 1 ? '' : 's'} and ${pool.stats.writes} write${pool.stats.writes === 1 ? '' : 's'}. ${table.name} now has ${rows.length} row${rows.length === 1 ? '' : 's'}.`, { stage: 'result', rows: [inserted] });
+        return {
+            events: drain(),
+            rows: [inserted],
+            write: { kind: 'insert', table: table.name, insertedCount: 1, rows },
+        };
+    }
+    if (ast.kind === 'delete') {
+        emitDeleteParseEvents(emit, ast);
+        // Any `IN (subquery)` in the WHERE clause (plan.md §25.4 C3 slice c) runs exactly once here, before planning —
+        // the parse-stage narration above already showed the query exactly as written.
+        const resolved = resolveWhereSubqueries(ast.where, sql, (s) => runQuery(s, db, options));
+        if (!resolved.ok)
+            return { events: drain(), rows: [], error: resolved.error };
+        const deleteAst = { ...ast, ...(resolved.where ? { where: resolved.where } : {}) };
+        const plan = emitDeletePlanEvents(emit, deleteAst, table, options.rowsPerPage);
+        const pool = createBufferPool(pageCountFor(heap, trees), options, emit);
+        const { deleted } = executeDelete(plan, { emit, pool, locks, heap, trees, table, options });
+        hooks.afterWrite?.(trees);
+        const removed = new Set(deleted);
+        const rows = table.rows.filter((r) => !removed.has(r));
+        emit(`${deleted.length} row${deleted.length === 1 ? '' : 's'} deleted, from ${pool.stats.misses} disk read${pool.stats.misses === 1 ? '' : 's'} and ${pool.stats.evictions} eviction${pool.stats.evictions === 1 ? '' : 's'}. ${table.name} now has ${rows.length} row${rows.length === 1 ? '' : 's'}.`, { stage: 'result', rows: deleted });
+        return {
+            events: drain(),
+            rows: deleted,
+            write: { kind: 'delete', table: table.name, deletedCount: deleted.length, rows },
+        };
+    }
+    if (ast.kind === 'update') {
+        emitUpdateParseEvents(emit, ast);
+        // Any `IN (subquery)` in the WHERE clause (plan.md §25.4 C3 slice c) runs exactly once here, before planning —
+        // the parse-stage narration above already showed the query exactly as written.
+        const resolved = resolveWhereSubqueries(ast.where, sql, (s) => runQuery(s, db, options));
+        if (!resolved.ok)
+            return { events: drain(), rows: [], error: resolved.error };
+        const updateAst = { ...ast, ...(resolved.where ? { where: resolved.where } : {}) };
+        const plan = emitUpdatePlanEvents(emit, updateAst, table, options.rowsPerPage);
+        const pool = createBufferPool(pageCountFor(heap, trees), options, emit);
+        let changed;
+        try {
+            changed = executeUpdate(plan, ast.set.assignments, { emit, pool, locks, heap, trees, table, options });
+        }
+        catch (e) {
+            if (e instanceof UniqueViolation) {
+                const error = uniqueError(e, heap, ast.set.span);
+                emit(`UPDATE is rejected — ${error.message} Nothing was changed.`, { stage: 'result', rows: [] });
+                return { events: drain(), rows: [], error };
+            }
+            throw e;
+        }
+        const { before, after } = changed;
+        hooks.afterWrite?.(trees);
+        const replacements = new Map(before.map((row, i) => [row, after[i]]));
+        const rows = table.rows.map((r) => replacements.get(r) ?? r);
+        emit(`${after.length} row${after.length === 1 ? '' : 's'} updated, from ${pool.stats.misses} disk read${pool.stats.misses === 1 ? '' : 's'} and ${pool.stats.evictions} eviction${pool.stats.evictions === 1 ? '' : 's'}.`, { stage: 'result', rows: after });
+        return {
+            events: drain(),
+            rows: after,
+            write: { kind: 'update', table: table.name, updatedCount: after.length, rows },
+        };
+    }
+    // Always the query exactly as typed — `ast` may already be the cost-reordered version by this point (plan.md
+    // §25.4 C5 slice 3), but the parse stage narrates source text, never a planning decision; `parsedAst` never was.
+    emitParseEvents(emit, parsedAst.kind === 'select' ? parsedAst : ast);
+    // Any `IN (subquery)` in the WHERE clause (plan.md §25.4 C3 slice c) runs exactly once here, before planning —
+    // the parse-stage narration above already showed the query exactly as written.
+    const resolvedWhere = resolveWhereSubqueries(ast.where, sql, (s) => runQuery(s, db, options));
+    if (!resolvedWhere.ok)
+        return { events: drain(), rows: [], error: resolvedWhere.error };
+    const selectAst = { ...ast, ...(resolvedWhere.where ? { where: resolvedWhere.where } : {}) };
+    const plan = emitPlanEvents(emit, selectAst, table, options.rowsPerPage, options.aggregateStrategy ?? 'hash', joinTables, options.joinStrategy, writtenJoinOrder);
+    // Every joined table gets its own heap, its pages numbered right after whatever came before it — so all of them
+    // compete for the same buffer frames, the same way a Sort's spill pages do (plan.md §25.4 C3 slice b generalizes
+    // this from one join partner to a whole left-deep chain). Nested-loop, hash and sort-merge never consult any
+    // side's own index, so there is no B+Tree to build for a join partner unless that particular step runs
+    // index-nested-loop (plan.md §25.4 B4) — each one that does gets its one needed index built next, past every
+    // heap and every earlier probe index, so nothing collides.
+    const joinHeaps = {};
+    let pageBase = pageCountFor(heap, trees);
+    for (const j of joins) {
+        const jHeap = buildHeap(joinTables[j.table.name], options.rowsPerPage, pageBase);
+        joinHeaps[j.table.name] = jHeap;
+        pageBase += jHeap.pages.length;
+    }
+    const joinTrees = {};
+    for (const ij of findIndexNestedLoopJoins(plan)) {
+        if (ij.right.op !== 'IndexProbe')
+            continue; // unreachable: an index-nested-loop Join's own inner side is always a probe
+        const jTable = joinTables[ij.rightTable];
+        const probeIndex = findIndexSpec(jTable, ij.right.column);
+        if (!probeIndex)
+            continue; // unreachable: effectiveJoinAlgorithm already confirmed this index exists
+        const jTrees = buildIndexes(joinHeaps[ij.rightTable], [probeIndex], undefined, pageBase, options.indexBuild, jTable.clusteredKey);
+        joinTrees[ij.rightTable] = jTrees;
+        pageBase = pageCountFor(joinHeaps[ij.rightTable], jTrees);
+    }
+    const heapsEnd = pageBase;
+    // Every `sort-merge` Join in the chain needs its own two-block reservation — one per side, since each sorts
+    // independently — placed in chain order (the innermost join's scratch first, mirroring the order joins actually
+    // execute in) right after every table's heap and any probe index. A single join's worst-case left input is just
+    // the FROM table itself (`table.rows.length`, unchanged from before chains existed); a later step's worst case is
+    // the product of every earlier table's row count, since no join can ever produce more rows than that.
+    const sortMergeBases = new Map();
+    let worstCaseLeftRows = table.rows.length;
+    for (const j of joinsIn(plan)) {
+        const jTable = joinTables[j.rightTable];
+        if (j.algorithm === 'sort-merge') {
+            const leftSize = sortTempPageCount(worstCaseLeftRows, options.rowsPerPage, options.bufferFrames);
+            const leftBase = pageBase;
+            pageBase += leftSize;
+            const rightSize = sortTempPageCount(jTable.rows.length, options.rowsPerPage, options.bufferFrames);
+            const rightBase = pageBase;
+            pageBase += rightSize;
+            sortMergeBases.set(j, { leftBase, rightBase });
+        }
+        worstCaseLeftRows *= jTable.rows.length;
+    }
+    // A Sort's (or a SortAggregate's own internal sort's) spill needs its own page ids, reserved up front — sized
+    // against the whole table (the worst case; a WHERE clause can only shrink what actually reaches it) so the
+    // reservation is never too small to discover only at runtime. This and the sort-merge reservation above never
+    // both apply: ORDER BY/GROUP BY still can't combine with JOIN at all.
+    const sortTemp = needsSortSpill(plan)
+        ? sortTempPageCount(table.rows.length, options.rowsPerPage, options.bufferFrames)
+        : pageBase - heapsEnd;
+    // A sort-based DISTINCT (plan.md §25.4 B2) sorts what the projection produced, which after a JOIN can be as many
+    // rows as every joined table's product (capped — these are teaching-sized tables) — and it gets its own block of
+    // scratch pages *after* whichever other sort the plan has, so no two sorts share a page id.
+    const distinctRows = joins.length > 0
+        ? Math.min(joins.reduce((product, j) => product * joinTables[j.table.name].rows.length, table.rows.length), 20_000)
+        : table.rows.length;
+    const distinctSpill = findSortDistinct(plan)
+        ? sortTempPageCount(distinctRows, options.rowsPerPage, options.bufferFrames)
+        : 0;
+    const distinctBase = heapsEnd + sortTemp;
+    const pool = createBufferPool(distinctBase + distinctSpill, options, emit);
+    const rows = execute(plan, {
+        emit,
+        pool,
+        locks,
+        heap,
+        trees,
+        table,
+        options,
+        distinctBase,
+        ...(joins.length > 0
+            ? {
+                joinPartners: Object.fromEntries(joins.map((j) => [
+                    j.table.name,
+                    { table: joinTables[j.table.name], heap: joinHeaps[j.table.name], trees: joinTrees[j.table.name] ?? {} },
+                ])),
+            }
+            : {}),
+        ...(sortMergeBases.size > 0 ? { sortMergeBases } : {}),
+    });
+    return { events: drain(), rows };
+}
+function referencedColumns(ast) {
+    const refs = [];
+    const push = (ref) => refs.push({ name: ref.name, ...(ref.table === undefined ? {} : { table: ref.table }), span: ref.span });
+    if (ast.kind === 'select' && ast.select.kind === 'columns') {
+        for (const item of ast.select.items) {
+            if (item.kind === 'column')
+                push(item);
+            else if (item.kind === 'expression')
+                walkExpr(item.expr, (e) => { if (e.kind === 'column')
+                    push(e); });
+            else if (item.arg.kind === 'column')
+                push(item.arg);
+        }
+    }
+    if (ast.kind !== 'insert' && ast.kind !== 'analyze' && ast.where) {
+        walkExpr(ast.where, (e) => {
+            if (e.kind === 'column')
+                push(e);
+        });
+    }
+    if (ast.kind === 'select') {
+        for (const join of ast.joins ?? []) {
+            if (join.on.left.kind === 'column')
+                push(join.on.left);
+            if (join.on.right.kind === 'column')
+                push(join.on.right);
+        }
+    }
+    if (ast.kind === 'select' && ast.groupBy)
+        refs.push(...ast.groupBy.columns);
+    if (ast.kind === 'select' && ast.having) {
+        // A HAVING predicate names grouped columns and aggregate arguments — each must exist.
+        walkExpr(ast.having, (e) => {
+            if (e.kind === 'column')
+                push(e);
+            else if (e.kind === 'aggregate' && e.arg.kind === 'column')
+                push(e.arg);
+        });
+    }
+    if (ast.kind === 'select' && ast.orderBy)
+        refs.push({ name: ast.orderBy.column, span: ast.orderBy.span });
+    if (ast.kind === 'insert' && ast.columns)
+        refs.push(...ast.columns.names);
+    if (ast.kind === 'update') {
+        refs.push(...ast.set.assignments.map((a) => ({ name: a.column, span: a.columnSpan })));
+        // A SET value can read columns (`SET n = n + 1`), and each must exist.
+        for (const a of ast.set.assignments)
+            walkExpr(a.value, (e) => { if (e.kind === 'column')
+                push(e); });
+    }
+    return refs;
+}
+/** Builds the new row: every table column defaults to `null`, then the given values overwrite it. */
+function buildInsertRow(ast, table) {
+    const row = {};
+    for (const column of table.columns)
+        row[column] = null;
+    const names = ast.columns ? ast.columns.names.map((c) => c.name) : table.columns;
+    names.forEach((name, i) => {
+        row[name] = ast.values.items[i].value;
+    });
+    return row;
+}

package/dist/src/engine/seed.js

@@ -0,0 +1,165 @@
+/**
+ * 48 rows at 4 rows per page is 12 pages against 8 buffer frames, so a full
+ * sequential scan evicts. That contrast is the point: plan.md §9 wants the
+ * scan's eviction storm shown next to an index lookup that touches almost
+ * nothing. A table small enough to never evict would make the buffer pool —
+ * the product's best differentiator — look inert.
+ */
+const NAMES = [
+    'ada', 'alan', 'barbara', 'brendan', 'carmack', 'carol', 'dennis', 'dijkstra',
+    'donald', 'edsger', 'engelbart', 'fowler', 'frances', 'grace', 'guido', 'hamilton',
+    'hedy', 'hopper', 'iverson', 'james', 'jean', 'john', 'katherine', 'ken',
+    'knuth', 'lamport', 'larry', 'leslie', 'linus', 'lynn', 'margaret', 'mary',
+    'matz', 'niklaus', 'radia', 'richard', 'ritchie', 'rob', 'robert', 'shafi',
+    'stephen', 'thompson', 'tim', 'tony', 'torvalds', 'turing', 'vint', 'yukihiro',
+];
+function seedRows() {
+    return NAMES.map((name, i) => ({
+        id: i + 1,
+        name,
+        email: `${name}@example.com`,
+        age: 20 + ((i * 7) % 45),
+    }));
+}
+/**
+ * The starting dataset. The user can edit these rows and re-run (plan.md §4).
+ */
+export function createSeedDatabase() {
+    return {
+        tables: {
+            users: {
+                name: 'users',
+                columns: ['id', 'name', 'email', 'age'],
+                rows: seedRows(),
+                indexedColumns: ['id'],
+            },
+        },
+    };
+}
+const AUTHOR_NAMES = ['ada', 'alan', 'grace', 'donald', 'barbara'];
+// `authorId` is a real foreign key shape: two authors with several posts,
+// one with exactly one, and one with none at all — the ordinary distribution
+// a real join produces, not every row matching neatly. Small on purpose: v1
+// JOIN is nested-loop only, so every row on one side rescans the *other*
+// side whole — small tables keep that honest even before an index-aware join
+// strategy exists to speed it up.
+const POST_AUTHORS = [1, 1, 1, 2, 2, 3, 3, 3, 3, 4];
+/**
+ * A small second table, joinable against a small first one (plan.md §22.2) —
+ * `authors`/`posts` rather than reusing the 48-row `users`, so a full,
+ * unfiltered join stays small enough to read as a trace. Not part of
+ * `datasets.ts`'s preset library: those are each one table by design (§22.7);
+ * this pair exists to give `/tools/planner` something to JOIN against.
+ */
+export function createJoinDemoDatabase() {
+    return {
+        tables: {
+            authors: {
+                name: 'authors',
+                columns: ['id', 'name'],
+                rows: AUTHOR_NAMES.map((name, i) => ({ id: i + 1, name })),
+                indexedColumns: ['id'],
+            },
+            posts: {
+                name: 'posts',
+                columns: ['id', 'authorId', 'title'],
+                rows: POST_AUTHORS.map((authorId, i) => ({
+                    id: i + 1,
+                    authorId,
+                    title: `${AUTHOR_NAMES[authorId - 1]}'s post ${String(i + 1)}`,
+                })),
+                // Three indexes on purpose. `id` and `title` give `/tools/planner`'s index-selection rule a second
+                // candidate to weigh (plan.md §22.2); `authorId` is the foreign key, and it *repeats* — 4 distinct
+                // values among 10 rows — so `WHERE authorId = 1` walks an index that holds three entries for one value
+                // and returns all three rows (plan.md §25.4 B3). Until then a B+Tree here was unique-only, and
+                // indexing this column would have silently returned one row instead of three.
+                indexedColumns: ['id', 'title', 'authorId'],
+            },
+        },
+    };
+}
+/**
+ * Four tables, shaped as a tree rather than a chain — `departments` is the hub, connecting to both `employees`
+ * and `projects`; `timesheets` hangs off `employees` alone (plan.md §25.4 C4, `/tools/join-order` + the
+ * Playground's own join-order note). Sized so join *order* has a real, measured answer rather than an obvious
+ * one: `timesheets` is the one genuinely large table (5,000 rows against the other three's tens or hundreds), so
+ * whichever join brings it in pays a real cost — but *when* that happens (how large the accumulated join is by
+ * the time it does) is what actually separates a good order from a bad one, not simply "big table first" or
+ * "big table last." Tuned empirically (the project's own "measure, don't guess" convention) rather than derived:
+ * `FROM departments JOIN projects ON departments.id = projects.deptId JOIN employees ON departments.id =
+ * employees.deptId JOIN timesheets ON employees.id = timesheets.employeeId` — a natural-looking "hub, then each
+ * branch" order — costs 5× the DP-optimal `departments → employees → timesheets → projects`, because visiting
+ * `projects` before drilling into `employees` → `timesheets` lets the *other* branch's join happen against an
+ * already-larger intermediate. Every foreign key is uniform (rows divide evenly across parents), so the only
+ * lever is order, not skew.
+ */
+export function createJoinOrderDemoDatabase() {
+    const DEPARTMENT_COUNT = 5;
+    const EMPLOYEES_PER_DEPARTMENT = 40;
+    const PROJECTS_PER_DEPARTMENT = 6;
+    const TIMESHEETS_PER_EMPLOYEE = 25;
+    const employeeCount = DEPARTMENT_COUNT * EMPLOYEES_PER_DEPARTMENT;
+    return {
+        tables: {
+            departments: {
+                name: 'departments',
+                columns: ['id', 'name'],
+                rows: Array.from({ length: DEPARTMENT_COUNT }, (_, i) => ({ id: i + 1, name: `dept-${String(i + 1)}` })),
+                indexedColumns: ['id'],
+            },
+            employees: {
+                name: 'employees',
+                columns: ['id', 'deptId', 'name'],
+                rows: Array.from({ length: employeeCount }, (_, i) => ({
+                    id: i + 1,
+                    deptId: Math.floor(i / EMPLOYEES_PER_DEPARTMENT) + 1,
+                    name: `employee-${String(i + 1)}`,
+                })),
+                indexedColumns: ['id', 'deptId'],
+            },
+            projects: {
+                name: 'projects',
+                columns: ['id', 'deptId', 'name'],
+                rows: Array.from({ length: DEPARTMENT_COUNT * PROJECTS_PER_DEPARTMENT }, (_, i) => ({
+                    id: i + 1,
+                    deptId: Math.floor(i / PROJECTS_PER_DEPARTMENT) + 1,
+                    name: `project-${String(i + 1)}`,
+                })),
+                indexedColumns: ['id', 'deptId'],
+            },
+            timesheets: {
+                name: 'timesheets',
+                columns: ['id', 'employeeId', 'hours'],
+                rows: Array.from({ length: employeeCount * TIMESHEETS_PER_EMPLOYEE }, (_, i) => ({
+                    id: i + 1,
+                    employeeId: Math.floor(i / TIMESHEETS_PER_EMPLOYEE) + 1,
+                    hours: 1 + (i % 8),
+                })),
+                indexedColumns: ['id', 'employeeId'],
+            },
+        },
+    };
+}
+/**
+ * `createJoinDemoDatabase`'s pair plus a larger third table, for `/compare`'s JOIN mode (plan.md §25.4 B4). Ten
+ * posts on three pages cannot show what an index join is *for* — a probe of `posts` costs more than one scan
+ * of it. `comments` is the inner table that can: 120 rows on 30 pages, twelve per post and scattered across them
+ * (every tenth row is one post's), indexed on `postId` (a foreign key, so it repeats). One outer row probing that
+ * index reads a few tree pages and the pages holding its own twelve comments — well under the thirty a scan reads —
+ * while ten outer rows probing it cost more than one scan of the lot, which is the other half of the lesson.
+ */
+export function createJoinCompareDatabase() {
+    const base = createJoinDemoDatabase();
+    return {
+        tables: {
+            ...base.tables,
+            comments: {
+                name: 'comments',
+                columns: ['id', 'postId', 'body'],
+                // `i * 7 mod 10` visits every post id in a scrambled order, so one post's comments sit on many pages.
+                rows: Array.from({ length: 120 }, (_, i) => ({ id: i + 1, postId: ((i * 7) % 10) + 1, body: `comment ${String(i + 1)}` })),
+                indexedColumns: ['postId'],
+            },
+        },
+    };
+}