querylens 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boddepalli Naveen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# querylens
+
+Trace a SQL query through [QueryLens](https://query-lens.1234naveenboddepalli.workers.dev)'s toy database engine, on
+the terminal. Every step the engine takes is printed, one line each: parse, plan, optimize, the buffer pool's hits
+and misses, the B+Tree's descent, and the result.
+
+```sh
+npx querylens "SELECT * FROM users WHERE id = 5"
+```
+
+```
+querylens — trace a SQL query through the QueryLens engine
+
+Usage:
+  querylens "<SQL>" [options]
+
+Options:
+  --policy <name>     buffer replacement policy: lru, clock, fifo, second-chance, optimal, midpoint, lru-k, two-q (default: lru)
+  --dataset <name>    preset table: users, orders, logins, employees, transactions (default: users)
+  --json             emit the trace as JSON instead of text
+  --no-color         disable ANSI colour (also respects the NO_COLOR env var)
+  -h, --help         show this help
+```
+
+It runs the same engine as the website, with no network access and nothing else to install. Its numbers are true to
+this engine, and not to PostgreSQL, MySQL or any production system.
+
+## Stability
+
+This is a `0.x` release. The flags and the `--json` trace shape may change between minor versions; pin an exact
+version if a script parses the output.
+
+## Licence
+
+MIT. See `LICENSE`.

package/dist/bin/querylens.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * `querylens` — trace a SQL query through the QueryLens engine, on the terminal.
+ *
+ * plan.md §22.8: the engine is a pure, synchronous, React-free function
+ * (`runQuery`), so a CLI is a thin wrapper over it. This replaces the old
+ * `scripts/trace.ts` debug dumper with a packaged shape: named flags, the three
+ * preset datasets (§22.7), a `--json` mode for scripting, and `NO_COLOR` support.
+ * `pnpm trace` and `pnpm querylens` both run it.
+ *
+ *   querylens "SELECT * FROM users WHERE id = 5"
+ *   querylens "SELECT * FROM orders WHERE total > 500" --dataset orders --policy clock
+ *   querylens "SELECT * FROM users WHERE age > 30" --json
+ *
+ * Publishing it to npm (a `dist/` build so it runs without --experimental-strip-types,
+ * a `files` allow-list, `npm publish`) is the one remaining step and a deliberate
+ * one — this file is the whole implementation.
+ */
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { runQuery, DATASETS, DATASET_IDS, DEFAULT_ENGINE_OPTIONS, REPLACEMENT_POLICY_NAMES, STAGES, } from "../src/engine/index.js";
+const HELP = `querylens — trace a SQL query through the QueryLens engine
+
+Usage:
+  querylens "<SQL>" [options]
+
+Options:
+  --policy <name>     buffer replacement policy: ${REPLACEMENT_POLICY_NAMES.join(', ')} (default: lru)
+  --dataset <name>    preset table: ${DATASET_IDS.join(', ')} (default: users)
+  --json             emit the trace as JSON instead of text
+  --no-color         disable ANSI colour (also respects the NO_COLOR env var)
+  -h, --help         show this help
+
+Examples:
+  querylens "SELECT * FROM users WHERE id = 5"
+  querylens "SELECT * FROM orders WHERE total > 500" --dataset orders --policy clock
+  querylens "SELECT * FROM users WHERE age > 30" --json
+`;
+export function parseArgs(argv, env = {}, isTTY = false) {
+    if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+        return { kind: 'help', text: HELP };
+    }
+    const positionals = [];
+    let policy = 'lru';
+    let dataset = 'users';
+    let json = false;
+    // Colour only when attached to a terminal and NO_COLOR is not set.
+    let color = isTTY && (env.NO_COLOR === undefined || env.NO_COLOR === '');
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--no-color') {
+            color = false;
+            continue;
+        }
+        if (arg === '--policy' || arg === '--dataset') {
+            const value = argv[++i];
+            if (value === undefined)
+                return { kind: 'error', message: `${arg} needs a value.` };
+            if (arg === '--policy') {
+                if (!REPLACEMENT_POLICY_NAMES.includes(value)) {
+                    return { kind: 'error', message: `Unknown policy "${value}". One of: ${REPLACEMENT_POLICY_NAMES.join(', ')}.` };
+                }
+                policy = value;
+            }
+            else {
+                if (!DATASET_IDS.includes(value)) {
+                    return { kind: 'error', message: `Unknown dataset "${value}". One of: ${DATASET_IDS.join(', ')}.` };
+                }
+                dataset = value;
+            }
+            continue;
+        }
+        if (arg.startsWith('--'))
+            return { kind: 'error', message: `Unknown option "${arg}". Try --help.` };
+        positionals.push(arg);
+    }
+    if (positionals.length === 0)
+        return { kind: 'error', message: 'No SQL query given. Try --help.' };
+    if (positionals.length > 1) {
+        return { kind: 'error', message: 'Give the query as a single quoted argument.' };
+    }
+    return { kind: 'run', options: { sql: positionals[0], policy, dataset, json, color } };
+}
+/* -------------------------------------------------------------------------- */
+/* Rendering                                                                   */
+/* -------------------------------------------------------------------------- */
+const STAGE_COLOUR = {
+    parse: '36', plan: '35', optimize: '95', execute: '33',
+    buffer: '32', index: '94', lock: '91', result: '96',
+};
+function paint(on) {
+    return (code, s) => (on ? `\x1b[${code}m${s}\x1b[0m` : s);
+}
+/** The one detail per event worth seeing at a glance. */
+function detail(event) {
+    switch (event.stage) {
+        case 'parse': return `ast(${String(countNodes(event.ast))} nodes)`;
+        case 'plan': return planShape(event.planTree);
+        case 'optimize': return `${event.rule}: ${planShape(event.before)} -> ${planShape(event.after)}`;
+        case 'execute': return `${event.op} -> ${String(event.rowsProduced)} rows`;
+        case 'buffer':
+            if (event.action === 'sweep')
+                return `sweep frame ${String(event.frameId)} -> usage ${String(event.usageCountAfter)}`;
+            if (event.action === 'evict')
+                return `evict page ${String(event.victimPageId)} from frame ${String(event.frameId)}`;
+            if (event.action === 'miss')
+                return `miss page ${String(event.pageId)}`;
+            return `${event.action} page ${String(event.pageId)} @ frame ${String(event.frameId)}`;
+        case 'index':
+            return event.action === 'open'
+                ? `open (height ${String(event.height)})`
+                : event.action === 'chain-next'
+                    ? `chain-next ${event.fromNodeId} -> ${event.toNodeId}`
+                    : `${event.action} ${event.nodeId}`;
+        case 'lock': return `${event.action} page ${String(event.pageId)} (${event.mode})`;
+        case 'result': return `${String(event.rows.length)} rows`;
+    }
+}
+function countNodes(node) {
+    const kids = (node.children ?? []);
+    return 1 + kids.reduce((n, c) => n + countNodes(c), 0);
+}
+function planShape(node) {
+    const kids = (node.children ?? []);
+    return kids.length === 0 ? node.op : `${node.op}(${kids.map(planShape).join(',')})`;
+}
+function summary(result) {
+    const count = (fn) => result.events.filter(fn).length;
+    return {
+        stages: STAGES.filter((s) => result.events.some((e) => e.stage === s)),
+        events: result.events.length,
+        diskReads: count((e) => e.stage === 'buffer' && e.action === 'load'),
+        hits: count((e) => e.stage === 'buffer' && e.action === 'hit'),
+        evictions: count((e) => e.stage === 'buffer' && e.action === 'evict'),
+        prompts: count((e) => e.predictable !== undefined),
+        rows: result.rows.length,
+    };
+}
+export function renderText(opts, result) {
+    const c = paint(opts.color);
+    const head = `${c('1', opts.sql.replace(/\s+/g, ' ').trim())}  ${c('2', '·')}  ${opts.policy}  ${c('2', '·')}  ${opts.dataset}`;
+    if (result.error) {
+        const lines = [head, '', c('91', `error  ${result.error.message}`)];
+        if (result.error.hint)
+            lines.push(c('2', `       ${result.error.hint}`));
+        return lines.join('\n');
+    }
+    const body = result.events.map((e) => {
+        const tag = c(STAGE_COLOUR[e.stage] ?? '0', e.stage.padEnd(8));
+        const gate = e.predictable ? ` ${c('95', '[predict]')}` : '';
+        return `  ${c('2', String(e.id).padStart(3))}  ${tag} ${detail(e).padEnd(40)}${gate}\n       ${c('2', e.label)}`;
+    });
+    const s = summary(result);
+    const foot = `  ${s.stages.length} stages · ${s.events} events · ${s.diskReads} disk reads · ` +
+        `${s.hits} hits · ${s.evictions} evictions · ${s.prompts} prompts · ` +
+        `${s.rows} row${s.rows === 1 ? '' : 's'}`;
+    return [head, '', ...body, '', c('1', foot)].join('\n');
+}
+export function renderJson(opts, result) {
+    return JSON.stringify({
+        sql: opts.sql,
+        policy: opts.policy,
+        dataset: opts.dataset,
+        ...(result.error ? { error: result.error } : { rows: result.rows, summary: summary(result), events: result.events }),
+    }, null, 2);
+}
+/* -------------------------------------------------------------------------- */
+/* Entry point                                                                 */
+/* -------------------------------------------------------------------------- */
+/** Runs the CLI. Returns the process exit code; does the I/O itself. */
+export function main(argv, out = (s) => process.stdout.write(`${s}\n`), err = (s) => process.stderr.write(`${s}\n`)) {
+    const parsed = parseArgs(argv, process.env, process.stdout.isTTY === true);
+    if (parsed.kind === 'help') {
+        out(parsed.text);
+        return 0;
+    }
+    if (parsed.kind === 'error') {
+        err(parsed.message);
+        return 2;
+    }
+    const { options } = parsed;
+    const result = runQuery(options.sql, DATASETS[options.dataset].make(), {
+        ...DEFAULT_ENGINE_OPTIONS,
+        policy: options.policy,
+    });
+    out(options.json ? renderJson(options, result) : renderText(options, result));
+    return result.error ? 1 : 0;
+}
+/** True when this module is the program's entry point. npm runs a bin through a symlink, so the path is resolved first. */
+function invokedDirectly(moduleUrl) {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === fileURLToPath(moduleUrl);
+    }
+    catch {
+        return false;
+    }
+}
+// Only run when invoked directly, not when imported by a test.
+if (invokedDirectly(import.meta.url)) {
+    process.exit(main(process.argv.slice(2)));
+}

package/dist/src/engine/bufferTrace.js

@@ -0,0 +1,67 @@
+/**
+ * A buffer pool trace driven by a bare page-reference string, with no SQL, no
+ * table and no index — the seam plan.md §20.2 #2 calls for and §21.4's tools
+ * catalogue needs.
+ *
+ * `createBufferPool` (storage/bufferPool.ts) already has no dependency on a
+ * heap or an index: it manages frames and takes page ids. `runQuery` is one
+ * caller of it; this is another, so the OS-course buffer-pool tool (§20.4) and
+ * the LRU/clock comparison view (§13, §21.3) render through the exact same
+ * `BufferPoolPanel` and the exact same event-folding (`createTraceProjector`)
+ * as the full pipeline — nothing about the panel or the fold is SQL-specific.
+ */
+import { createTracer } from "./trace.js";
+import { createBufferPool } from "./storage/index.js";
+import { DEFAULT_ENGINE_OPTIONS } from "./types.js";
+/** Same cap the URL layers use elsewhere: a hostile or pasted string should
+ *  not be able to hang the tab. Not a security boundary — there is nothing to
+ *  inject — just a size limit on user-typed input. */
+export const MAX_REFERENCES = 500;
+/**
+ * Runs a page-reference string through a buffer pool and returns the full
+ * event trace. Pure and synchronous, same as `runQuery` (plan.md §5).
+ */
+export function runBufferTrace(referenceString, options = DEFAULT_ENGINE_OPTIONS) {
+    const refs = referenceString.slice(0, MAX_REFERENCES);
+    const { emit, drain } = createTracer();
+    const pageCount = refs.length === 0 ? 1 : Math.max(...refs) + 1;
+    // The whole string is the lookahead the `optimal` policy needs; the other
+    // policies are handed it and ignore it.
+    const pool = createBufferPool(pageCount, options, emit, refs);
+    const accessBoundaries = [];
+    for (const pageId of refs) {
+        // `fetch` pins the frame it resolves to, the same as a live operator
+        // holding a page while it reads it (locks.test.ts covers that half). A
+        // bare reference string has no operator to release it, so the access is
+        // modelled as instantaneous: unpin immediately, or every frame is "in use"
+        // forever and the second distinct page onward can never find a victim.
+        const result = pool.fetch(pageId);
+        if (result)
+            pool.unpin(result.frameId);
+        accessBoundaries.push(drain().length);
+    }
+    return { events: drain(), accessBoundaries };
+}
+/**
+ * Parses free-typed input ("1 2 3, 4  5") into page ids, dropping anything
+ * that is not a non-negative integer rather than throwing — this is typed
+ * input from the one person using the tool, but the parse still has to be
+ * total, the same discipline `urlState.ts` applies to a stranger's link.
+ */
+export function parseReferenceString(input) {
+    return input
+        .split(/[\s,]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0)
+        .map(Number)
+        .filter((n) => Number.isInteger(n) && n >= 0)
+        .slice(0, MAX_REFERENCES);
+}
+/** A reference string with real locality — repeats and revisits — rather than
+ *  uniform noise, so a generated example actually produces hits, not just misses. */
+export function randomReferenceString(length, distinctPages) {
+    const hot = Math.max(1, Math.round(distinctPages * 0.4));
+    return Array.from({ length }, () => Math.random() < 0.7
+        ? Math.floor(Math.random() * hot)
+        : Math.floor(Math.random() * distinctPages));
+}

package/dist/src/engine/datasets.js

@@ -0,0 +1,139 @@
+import { createSeedDatabase } from "./seed.js";
+export const DEFAULT_DATASET = 'users';
+export const DATASET_IDS = ['users', 'orders', 'logins', 'employees', 'transactions'];
+export function isDatasetId(value) {
+    return typeof value === 'string' && DATASET_IDS.includes(value);
+}
+const ORDER_CUSTOMERS = [
+    'acme', 'globex', 'initech', 'umbrella', 'soylent', 'hooli', 'stark', 'wayne',
+    'wonka', 'tyrell', 'cyberdyne', 'aperture',
+];
+const ORDER_STATUS = ['paid', 'pending', 'refunded'];
+function orderRows() {
+    return Array.from({ length: 120 }, (_, i) => ({
+        id: i + 1,
+        customer: ORDER_CUSTOMERS[i % ORDER_CUSTOMERS.length],
+        total: 50 + ((i * 37) % 950),
+        status: ORDER_STATUS[i % 3],
+    }));
+}
+const LOGIN_USERS = [
+    'ada', 'brendan', 'carmack', 'dijkstra', 'grace', 'guido', 'hopper', 'ken',
+    'knuth', 'lamport', 'linus', 'matz', 'radia', 'ritchie', 'turing', 'yukihiro',
+];
+function loginRows() {
+    return Array.from({ length: 80 }, (_, i) => {
+        // 1 in 9 is blocked — the deliberate skew: `status = 'blocked'` is a
+        // handful of rows after a full scan, `status = 'ok'` is nearly all of them.
+        const blocked = i % 9 === 0;
+        return {
+            id: i + 1,
+            user: LOGIN_USERS[i % LOGIN_USERS.length],
+            status: blocked ? 'blocked' : 'ok',
+            attempts: blocked ? 3 + (i % 5) : 1,
+        };
+    });
+}
+const DEPARTMENTS = [
+    'engineering', 'sales', 'marketing', 'support', 'finance', 'legal', 'design', 'product',
+    'people', 'security', 'data', 'research', 'platform', 'growth', 'success', 'partnerships',
+    'operations', 'recruiting', 'it', 'facilities', 'compliance', 'strategy', 'brand',
+    'localization', 'devrel',
+];
+const EMPLOYEES_PER_DEPARTMENT = 10;
+/**
+ * `department` and `office` are perfectly correlated: every department occupies exactly one office, the way a real
+ * team often does. That is exactly the independence assumption `AND` selectivity makes (plan.md §25.4 C2), and
+ * exactly what `ANALYZE`'s own per-column statistics (plan.md §25.4 C1) cannot see — nothing there counts how two
+ * columns co-occur, only how each behaves alone: `department = 'sales' AND office = 'building-2'` is no narrower
+ * than `department = 'sales'` by itself, since office adds no information at all, but the optimizer's multiplied
+ * fractions assume it does — badly underestimating (RESEARCH.md §41: Leis et al. found real optimizers off by an
+ * order of magnitude or more from exactly this).
+ */
+function employeeRows() {
+    return DEPARTMENTS.flatMap((department, d) => Array.from({ length: EMPLOYEES_PER_DEPARTMENT }, (_, i) => ({
+        id: d * EMPLOYEES_PER_DEPARTMENT + i + 1,
+        department,
+        office: `building-${String(d + 1)}`,
+        salary: 60000 + ((d * EMPLOYEES_PER_DEPARTMENT + i) * 733) % 80000,
+    })));
+}
+const TRANSACTION_COUNT = 3000;
+const TRANSACTION_ACCOUNTS = Array.from({ length: 40 }, (_, i) => `acct-${String(i + 1).padStart(2, '0')}`);
+/**
+ * 3,000 rows: a genuinely taller B+Tree than any other preset (height 7, measured against `id` with this
+ * engine's real `maxKeys = 4` — `employees`'s 250 rows only reaches height 5) and 750 heap pages against the
+ * default 8 buffer frames, so a scan that touches most of the table evicts hard enough to be dramatic, not
+ * token. `amount` is deliberately unindexed and spans the whole table uniformly, so `amount > 4500` (~10%
+ * selectivity) still has to read every one of those 750 pages — `account` is likewise unindexed, 40 repeating
+ * values, for the same "an equality still costs a full scan" point a bigger table makes more vivid. Sized by a
+ * throwaway probe script measuring the real `height()`/heap-page count across 500–10,000 rows, not estimated
+ * (plan.md's own "measure, don't guess") — 3,000 was the smallest size that still reached height 7.
+ */
+function transactionRows() {
+    return Array.from({ length: TRANSACTION_COUNT }, (_, i) => ({
+        id: i + 1,
+        account: TRANSACTION_ACCOUNTS[i % TRANSACTION_ACCOUNTS.length],
+        amount: 10 + ((i * 97) % 4990),
+        status: i % 5 === 0 ? 'failed' : 'settled',
+    }));
+}
+export const DATASETS = {
+    users: { id: 'users', table: 'users', make: createSeedDatabase },
+    transactions: {
+        id: 'transactions',
+        table: 'transactions',
+        make: () => ({
+            tables: {
+                transactions: {
+                    name: 'transactions',
+                    columns: ['id', 'account', 'amount', 'status'],
+                    rows: transactionRows(),
+                    indexedColumns: ['id'],
+                },
+            },
+        }),
+    },
+    employees: {
+        id: 'employees',
+        table: 'employees',
+        make: () => ({
+            tables: {
+                employees: {
+                    name: 'employees',
+                    columns: ['id', 'department', 'office', 'salary'],
+                    rows: employeeRows(),
+                    indexedColumns: ['id'],
+                },
+            },
+        }),
+    },
+    orders: {
+        id: 'orders',
+        table: 'orders',
+        make: () => ({
+            tables: {
+                orders: {
+                    name: 'orders',
+                    columns: ['id', 'customer', 'total', 'status'],
+                    rows: orderRows(),
+                    indexedColumns: ['id'],
+                },
+            },
+        }),
+    },
+    logins: {
+        id: 'logins',
+        table: 'logins',
+        make: () => ({
+            tables: {
+                logins: {
+                    name: 'logins',
+                    columns: ['id', 'user', 'status', 'attempts'],
+                    rows: loginRows(),
+                    indexedColumns: ['id'],
+                },
+            },
+        }),
+    },
+};

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

@@ -0,0 +1,95 @@
+/**
+ * Executes a `DELETE`'s access plan (`SeqScan` or `IndexScan`, from
+ * `emitDeletePlanEvents`) against the real heap and index: finds every
+ * matching row, drops its key from the B+Tree with the real `deleteKey`
+ * algorithm — real borrows, merges, root-collapses, narrated — and marks the
+ * heap pages it removed a row from dirty (plan.md §22.2, the write path).
+ *
+ * A `SELECT` streams rows through Volcano operators one at a time; a
+ * `DELETE` cannot — it has to find *every* match before it starts mutating
+ * anything, or a deletion mid-scan could shift what a later step reads. So
+ * this is its own pass rather than a reuse of `buildOperator`, though it
+ * narrates through the same `execute`-stage shape (`op: 'SeqScan'` /
+ * `'IndexScan'` as it finds matches, then `op: 'Delete'` as it removes them)
+ * so the Execute panel reads the same way a `SELECT`'s does.
+ */
+import { indexLookupMatches, indexRangeMatches } from "./writeScan.js";
+import { passes } from "./evaluate.js";
+import { deleteKey, entryFor, indexNameOf, indexSpecsOf, keyText, keyValuesOf } from "../index/index.js";
+const DELETE = { name: 'DELETE', does: 'remove' };
+/**
+ * One clause summarising what a B+Tree delete had to do beyond the plain
+ * removal. Exported: `exec/update.ts` reuses it for the "drop the old key"
+ * half of a reindex.
+ */
+export function summarizeSteps(steps) {
+    const rest = steps.slice(1); // steps[0] is always the leaf `remove` itself
+    if (rest.length === 0)
+        return 'the leaf stayed at least half full, so nothing else moved';
+    return `the tree also had to ${rest.map((s) => s.kind.replace('-', ' ')).join(', then ')}`;
+}
+/**
+ * Removes the entry for the row at `pointer` from every index the table declares, skipping one whose leading column
+ * is NULL. An entry is the values *and* the row's address, so this drops exactly this row's entry even when other
+ * rows share its values.
+ */
+function deleteFromIndex(ctx, row, pointer) {
+    const details = [];
+    for (const spec of indexSpecsOf(ctx.table)) {
+        const name = indexNameOf(spec.columns);
+        const tree = ctx.trees[name];
+        if (!tree)
+            continue;
+        const values = keyValuesOf(row, spec.columns);
+        if (values[0] === null)
+            continue; // a NULL leading column was never indexed — nothing to remove
+        const { key } = entryFor(spec.columns, row, pointer, ctx.table.clusteredKey);
+        const result = deleteKey(tree, key);
+        if (!result.found)
+            continue; // defensive: every row here came from the heap this tree indexes
+        details.push(`The \`${name}\` B+Tree drops key ${keyText(values)} from leaf ${result.steps[0]?.node ?? '?'} — ${summarizeSteps(result.steps)}.`);
+    }
+    return details;
+}
+/** Every heap page, filtered by `filter` if present — the SeqScan half of a delete. */
+function scanForMatches(ctx, filter) {
+    const matched = [];
+    let produced = 0;
+    for (const page of ctx.heap.pages) {
+        ctx.locks.acquire(page.pageId, 'exclusive', `Take an exclusive lock on page ${String(page.pageId)} — DELETE may remove a row from it, so a shared lock is not enough.`);
+        const fetched = ctx.pool.fetch(page.pageId);
+        if (fetched)
+            ctx.pool.unpin(fetched.frameId);
+        let touchedPage = false;
+        page.rows.forEach((row, slot) => {
+            if (!passes(filter, row))
+                return;
+            matched.push({ row, pointer: { pageId: page.pageId, slot } });
+            touchedPage = true;
+            produced += 1;
+            ctx.emit(`SeqScan finds a matching row on page ${page.pageId} — DELETE will remove it.`, {
+                stage: 'execute',
+                op: 'SeqScan',
+                rowsProduced: produced,
+            });
+        });
+        if (touchedPage)
+            ctx.pool.markDirty(page.pageId);
+        ctx.locks.release(page.pageId, 'exclusive');
+    }
+    return matched;
+}
+export function executeDelete(plan, ctx) {
+    const matched = plan.op === 'IndexScan'
+        ? indexLookupMatches(ctx, plan, DELETE)
+        : plan.op === 'IndexRangeScan'
+            ? indexRangeMatches(ctx, plan, DELETE)
+            : scanForMatches(ctx, plan.op === 'SeqScan' ? plan.filter : undefined);
+    let produced = 0;
+    for (const { row, pointer } of matched) {
+        const indexDetails = deleteFromIndex(ctx, row, pointer);
+        produced += 1;
+        ctx.emit(`Delete removes row ${JSON.stringify(row)}.${indexDetails.length > 0 ? ` ${indexDetails.join(' ')}` : ''}`, { stage: 'execute', op: 'Delete', rowsProduced: produced });
+    }
+    return { deleted: matched.map((m) => m.row) };
+}