@quereus/quereus 4.14.0 → 4.16.0

package/dist/src/runtime/work-counters.d.ts

@@ -0,0 +1,180 @@
+import type { OutputValue } from '../common/types.js';
+import type { PlanNode } from '../planner/nodes/plan-node.js';
+import type { PlanNodeType } from '../planner/nodes/plan-node-type.js';
+import type { Scheduler } from './scheduler.js';
+/**
+ * Machine-independent work counters for one statement execution.
+ *
+ * Every number here is a *count* — executions, input values, output rows — chosen
+ * because counts come out identical on every machine and every run of the same plan,
+ * where timings do not. `elapsedNs` is deliberately absent: putting a nanosecond
+ * figure on a surface whose premise is machine-independence invites exactly the
+ * cross-machine comparison this surface exists to replace.
+ *
+ * Instruction identity is a structural program address (see
+ * {@link WorkCounterCollector}), never a plan-node id: `PlanNode.id` is a
+ * process-global counter, so two runs of the same query in one process get different
+ * ids and any id-derived key would diverge immediately.
+ */
+/** Plan-shape facts, available after compile without executing. */
+export interface PlanShape {
+    nodeCount: number;
+    /** PlanNodeType -> how many plan nodes of that type. Keys sorted. */
+    nodeTypes: Record<string, number>;
+}
+/**
+ * Engine-to-module access counts for one table within one execution.
+ *
+ * These measure the **engine-to-module** boundary — the calls the runtime itself
+ * issued — not the **module-to-storage** boundary. A module that swaps 1000 single-key
+ * reads for one batched multi-key read moves neither number here: the engine issued the
+ * same one `query()` either way. Counting inside a module is a separate instrument
+ * (the counting key-value store double in `@quereus/store/testing`).
+ */
+export interface TableWorkCounters {
+    /** `query()` calls the engine issued against this table. */
+    queryCalls: number;
+    /** Rows the engine pulled out of those `query()` calls. */
+    rowsScanned: number;
+    /** `update()` calls the engine issued — insert, update and delete alike. */
+    updateCalls: number;
+}
+/** JSON-serializable snapshot of one execution's work counters: no bigint, no timings. */
+export interface WorkCounterSnapshot {
+    /** Plan-shape facts. Available after compile — no execution needed. */
+    plan: PlanShape;
+    /** One entry per instruction that ran at least once, in program-walk order. */
+    instructions: Array<{
+        /** Structural address, e.g. `r#12` or `r/12/0#3`. Never contains a plan-node id. */
+        key: string;
+        /** PlanNodeType, when the instruction came from a plan node. */
+        nodeType?: string;
+        /** Times this instruction's `run` was invoked. */
+        executions: number;
+        /**
+         * Argument VALUES received, summed over executions — NOT input rows: a
+         * streaming argument counts 1 however many rows flow through it (its row
+         * count is the producing instruction's `out`). So `in` and `out` of one
+         * entry are on different scales; don't read `out/in` as selectivity.
+         */
+        in: number;
+        /** Rows/values produced, summed over executions — per yield for streams. */
+        out: number;
+    }>;
+    /**
+     * Engine-to-module access, keyed `<schema>.<table>` (lowercased), keys sorted.
+     *
+     * Keyed by TABLE, not by scan site: a self-join scans one table from two sites and
+     * both roll into one entry — the per-site breakdown is already in `instructions`.
+     * A table the execution never touched is absent (same claim-vs-silence rule the
+     * instruction list follows).
+     */
+    tables: Record<string, TableWorkCounters>;
+    totals: {
+        instructionExecutions: number;
+        rowsOut: number;
+        /** `query()` calls summed over every table. */
+        queryCalls: number;
+        /** Rows pulled out of those calls, summed over every table. */
+        rowsScanned: number;
+        /** `update()` calls summed over every table. */
+        updateCalls: number;
+    };
+}
+/** Mutable per-instruction counter cell; the scheduler's metrics hooks feed these. */
+export interface WorkCounterSlot {
+    /** Structural address (`<program-path>#<instruction-index>`); never a plan-node id. */
+    readonly key: string;
+    /**
+     * PlanNodeType stamped by `emitPlanNode` — the operator that PRODUCED the
+     * instruction, so a transparent wrapper (alias, collate, …) reports its source's
+     * type. Undefined for synthetic instructions (emitCall callbacks, fused scalars).
+     */
+    readonly nodeType: PlanNodeType | undefined;
+    executions: number;
+    in: number;
+    out: number;
+}
+/**
+ * Records one instruction output into `slot` and returns the value to park.
+ *
+ * - An async iterable is wrapped in a counting generator that increments `out` per
+ *   yield — the scheduler's `countOutputs` reports 1 for a stream, and a "row count"
+ *   that says 1 for every streaming operator is not a row count.
+ * - An array adds its length; everything else adds 1 (matching `countOutputs`).
+ *
+ * The wrap is skipped only when THIS slot already wrapped the iterable: a
+ * pass-through iterable re-counted by a *different* instruction's slot is correct
+ * double-wrapping (rows flow through both instructions), not a bug. Metrics mode and
+ * tracing mode are mutually exclusive in `Scheduler.run()` (metrics wins), so there
+ * is no interplay with the tracing wrapper's own marker symbol.
+ *
+ * NOTE: the wrap turns a re-iterable output (an object whose `[Symbol.asyncIterator]()`
+ * can be called more than once) into a single-shot generator, so a second pass over it
+ * would yield nothing WITH METRICS ON only. Safe today: every re-drive in the runtime
+ * goes through an `emitCall` callback that returns a fresh iterable per call, so no
+ * instruction output is iterated twice. If an emitter ever parks a re-iterable as its
+ * output, wrap per `[Symbol.asyncIterator]()` call instead of once per value.
+ */
+export declare function recordOutput(slot: WorkCounterSlot, value: OutputValue): OutputValue;
+/**
+ * Per-execution collector of work counters for a root scheduler and every
+ * sub-program reachable from it.
+ *
+ * Built once per statement execution (in `Statement._iterateRowsRawInternal`) and
+ * carried on the `RuntimeContext` (fork policy `shared-sink`: forks share it by
+ * reference, so counts from a forked branch roll up with no merge step). The
+ * scheduler's metrics hooks look up their slot array via {@link countersFor} once
+ * per program run.
+ *
+ * Instruction identity is structural: the root program is `r`, and the scheduler at
+ * `instructions[i].programs[j]` of program `P` is addressed `P/i/j`; instruction `i`
+ * of a program keys as `<path>#<i>`. This depends only on the shape of the compiled
+ * plan — never on execution order, which branch ran, or any plan-node id — so two
+ * runs of the same plan produce the same keys on any machine.
+ *
+ * Unlike `Instruction.runtimeStats` (zeroed per program invocation for the debug
+ * log), these slots are NEVER reset mid-execution: a correlated subquery's
+ * sub-program driven 100 times reports 100 executions of its inner instructions —
+ * the number that makes an N+1 regression visible.
+ */
+export declare class WorkCounterCollector {
+    /** Slot arrays keyed by Scheduler identity — root program and every sub-program. */
+    private readonly slots;
+    /** Every slot in deterministic walk order (each sub-program right after its owning instruction). */
+    private readonly walkOrder;
+    /**
+     * Engine-to-module access cells, keyed `<schema>.<table>` (lowercased) and created
+     * on first access. Unlike the instruction slots this is NOT pre-walked: which tables
+     * an execution actually touches is a run-time fact (a branch never taken never
+     * connects), and an entry that exists means "the engine called this table".
+     */
+    private readonly tables;
+    constructor(root: Scheduler);
+    private walk;
+    /** The slot array for one program, index-aligned with `scheduler.instructions`. */
+    countersFor(scheduler: Scheduler): WorkCounterSlot[] | undefined;
+    /**
+     * The engine-to-module cell for one table, created zeroed on first access.
+     *
+     * `key` must be the lowercased `<schema>.<table>` the table carries AT RUN TIME —
+     * the post-remap name when a deferred constraint evaluates a plan frozen before an
+     * `ALTER TABLE ... RENAME TO` — so one table never splits across two entries.
+     */
+    tableCounters(key: string): TableWorkCounters;
+    /**
+     * Builds a fresh, by-value snapshot: instructions that never ran are omitted
+     * (a missing snapshot and an all-zero one are different claims — see
+     * `Statement.getWorkCounters`), and totals sum over the included entries only.
+     * Table entries exist only for tables the engine actually called, on the same rule.
+     */
+    snapshot(plan: PlanShape): WorkCounterSnapshot;
+}
+/**
+ * Counts plan nodes and their types with an iterative walk over `getChildren()` and
+ * a visited set — NOT `PlanNode.visit()`, which deliberately visits a DAG node once
+ * per *path* and would double-count shared subtrees (inflating `nodeCount`
+ * nondeterministically-looking across otherwise-identical plans).
+ */
+export declare function computePlanShape(root: PlanNode): PlanShape;
+//# sourceMappingURL=work-counters.d.ts.map

package/dist/src/runtime/work-counters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-counters.d.ts","sourceRoot":"","sources":["../../../src/runtime/work-counters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;;;;;;;;;;;;GAaG;AAEH,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IACnC,uEAAuE;IACvE,IAAI,EAAE,SAAS,CAAC;IAChB,+EAA+E;IAC/E,YAAY,EAAE,KAAK,CAAC;QACnB,oFAAoF;QACpF,GAAG,EAAE,MAAM,CAAC;QACZ,gEAAgE;QAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,kDAAkD;QAClD,UAAU,EAAE,MAAM,CAAC;QACnB;;;;;WAKG;QACH,EAAE,EAAE,MAAM,CAAC;QACX,4EAA4E;QAC5E,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC,CAAC;IACH;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1C,MAAM,EAAE;QACP,qBAAqB,EAAE,MAAM,CAAC;QAC9B,OAAO,EAAE,MAAM,CAAC;QAChB,+CAA+C;QAC/C,UAAU,EAAE,MAAM,CAAC;QACnB,+DAA+D;QAC/D,WAAW,EAAE,MAAM,CAAC;QACpB,gDAAgD;QAChD,WAAW,EAAE,MAAM,CAAC;KACpB,CAAC;CACF;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACZ;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAqBnF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBAAoB;IAChC,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;IACjE,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;gBAEnD,IAAI,EAAE,SAAS;IAI3B,OAAO,CAAC,IAAI;IAgCZ,mFAAmF;IACnF,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,EAAE,GAAG,SAAS;IAIhE;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB;IAS7C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB;CAwC9C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAoB1D"}

package/dist/src/runtime/work-counters.js

@@ -0,0 +1,210 @@
+import { isAsyncIterable } from './utils.js';
+/** Marker linking a counting-wrapped iterable back to the slot that wrapped it. */
+const COUNTED_ITERABLE_SYMBOL = Symbol('workCountedIterable');
+/**
+ * Records one instruction output into `slot` and returns the value to park.
+ *
+ * - An async iterable is wrapped in a counting generator that increments `out` per
+ *   yield — the scheduler's `countOutputs` reports 1 for a stream, and a "row count"
+ *   that says 1 for every streaming operator is not a row count.
+ * - An array adds its length; everything else adds 1 (matching `countOutputs`).
+ *
+ * The wrap is skipped only when THIS slot already wrapped the iterable: a
+ * pass-through iterable re-counted by a *different* instruction's slot is correct
+ * double-wrapping (rows flow through both instructions), not a bug. Metrics mode and
+ * tracing mode are mutually exclusive in `Scheduler.run()` (metrics wins), so there
+ * is no interplay with the tracing wrapper's own marker symbol.
+ *
+ * NOTE: the wrap turns a re-iterable output (an object whose `[Symbol.asyncIterator]()`
+ * can be called more than once) into a single-shot generator, so a second pass over it
+ * would yield nothing WITH METRICS ON only. Safe today: every re-drive in the runtime
+ * goes through an `emitCall` callback that returns a fresh iterable per call, so no
+ * instruction output is iterated twice. If an emitter ever parks a re-iterable as its
+ * output, wrap per `[Symbol.asyncIterator]()` call instead of once per value.
+ */
+export function recordOutput(slot, value) {
+    if (isAsyncIterable(value)) {
+        if (value[COUNTED_ITERABLE_SYMBOL] === slot) {
+            return value;
+        }
+        const source = value;
+        const wrapped = (async function* () {
+            for await (const item of source) {
+                slot.out++;
+                yield item;
+            }
+        })();
+        wrapped[COUNTED_ITERABLE_SYMBOL] = slot;
+        return wrapped;
+    }
+    if (Array.isArray(value)) {
+        slot.out += value.length;
+        return value;
+    }
+    slot.out += 1;
+    return value;
+}
+/**
+ * Per-execution collector of work counters for a root scheduler and every
+ * sub-program reachable from it.
+ *
+ * Built once per statement execution (in `Statement._iterateRowsRawInternal`) and
+ * carried on the `RuntimeContext` (fork policy `shared-sink`: forks share it by
+ * reference, so counts from a forked branch roll up with no merge step). The
+ * scheduler's metrics hooks look up their slot array via {@link countersFor} once
+ * per program run.
+ *
+ * Instruction identity is structural: the root program is `r`, and the scheduler at
+ * `instructions[i].programs[j]` of program `P` is addressed `P/i/j`; instruction `i`
+ * of a program keys as `<path>#<i>`. This depends only on the shape of the compiled
+ * plan — never on execution order, which branch ran, or any plan-node id — so two
+ * runs of the same plan produce the same keys on any machine.
+ *
+ * Unlike `Instruction.runtimeStats` (zeroed per program invocation for the debug
+ * log), these slots are NEVER reset mid-execution: a correlated subquery's
+ * sub-program driven 100 times reports 100 executions of its inner instructions —
+ * the number that makes an N+1 regression visible.
+ */
+export class WorkCounterCollector {
+    /** Slot arrays keyed by Scheduler identity — root program and every sub-program. */
+    slots = new Map();
+    /** Every slot in deterministic walk order (each sub-program right after its owning instruction). */
+    walkOrder = [];
+    /**
+     * Engine-to-module access cells, keyed `<schema>.<table>` (lowercased) and created
+     * on first access. Unlike the instruction slots this is NOT pre-walked: which tables
+     * an execution actually touches is a run-time fact (a branch never taken never
+     * connects), and an entry that exists means "the engine called this table".
+     */
+    tables = new Map();
+    constructor(root) {
+        this.walk(root, 'r');
+    }
+    walk(scheduler, path) {
+        // Defensive: a scheduler reachable via two paths keeps its first path's keys
+        // (counters are per Scheduler identity, so both paths report under one key).
+        if (this.slots.has(scheduler))
+            return;
+        const programSlots = [];
+        this.slots.set(scheduler, programSlots);
+        for (let i = 0; i < scheduler.instructions.length; i++) {
+            const instruction = scheduler.instructions[i];
+            const slot = {
+                key: `${path}#${i}`,
+                nodeType: instruction.nodeType,
+                executions: 0,
+                in: 0,
+                out: 0,
+            };
+            programSlots.push(slot);
+            this.walkOrder.push(slot);
+            // NOTE: assumes `Instruction.programs` is only ever set by `emitCall`
+            // (runtime/emitters.ts), today's single site, and set at EMIT time — the walk
+            // runs once at execution start, so a Scheduler built during the run is absent
+            // from the map and `countersFor` returns undefined, silently counting nothing
+            // for it. The walk stays correct if a future emitter sets `programs` directly
+            // at emit time — addressing is purely structural — but that emitter's
+            // sub-programs silently start being counted here too.
+            if (instruction.programs) {
+                for (let j = 0; j < instruction.programs.length; j++) {
+                    this.walk(instruction.programs[j], `${path}/${i}/${j}`);
+                }
+            }
+        }
+    }
+    /** The slot array for one program, index-aligned with `scheduler.instructions`. */
+    countersFor(scheduler) {
+        return this.slots.get(scheduler);
+    }
+    /**
+     * The engine-to-module cell for one table, created zeroed on first access.
+     *
+     * `key` must be the lowercased `<schema>.<table>` the table carries AT RUN TIME —
+     * the post-remap name when a deferred constraint evaluates a plan frozen before an
+     * `ALTER TABLE ... RENAME TO` — so one table never splits across two entries.
+     */
+    tableCounters(key) {
+        let entry = this.tables.get(key);
+        if (entry === undefined) {
+            entry = { queryCalls: 0, rowsScanned: 0, updateCalls: 0 };
+            this.tables.set(key, entry);
+        }
+        return entry;
+    }
+    /**
+     * Builds a fresh, by-value snapshot: instructions that never ran are omitted
+     * (a missing snapshot and an all-zero one are different claims — see
+     * `Statement.getWorkCounters`), and totals sum over the included entries only.
+     * Table entries exist only for tables the engine actually called, on the same rule.
+     */
+    snapshot(plan) {
+        const instructions = [];
+        let instructionExecutions = 0;
+        let rowsOut = 0;
+        for (const slot of this.walkOrder) {
+            if (slot.executions === 0)
+                continue;
+            const entry = {
+                key: slot.key,
+                executions: slot.executions,
+                in: slot.in,
+                out: slot.out,
+            };
+            if (slot.nodeType !== undefined) {
+                entry.nodeType = slot.nodeType;
+            }
+            instructions.push(entry);
+            instructionExecutions += slot.executions;
+            rowsOut += slot.out;
+        }
+        // Sorted keys so two snapshots of the same execution serialize identically —
+        // Map iteration order is insertion order, which is scan-connect order, which a
+        // plan change can reshuffle without changing any count.
+        const tables = {};
+        let queryCalls = 0;
+        let rowsScanned = 0;
+        let updateCalls = 0;
+        for (const key of [...this.tables.keys()].sort()) {
+            const cell = this.tables.get(key);
+            tables[key] = { queryCalls: cell.queryCalls, rowsScanned: cell.rowsScanned, updateCalls: cell.updateCalls };
+            queryCalls += cell.queryCalls;
+            rowsScanned += cell.rowsScanned;
+            updateCalls += cell.updateCalls;
+        }
+        return {
+            plan: { nodeCount: plan.nodeCount, nodeTypes: { ...plan.nodeTypes } },
+            instructions,
+            tables,
+            totals: { instructionExecutions, rowsOut, queryCalls, rowsScanned, updateCalls },
+        };
+    }
+}
+/**
+ * Counts plan nodes and their types with an iterative walk over `getChildren()` and
+ * a visited set — NOT `PlanNode.visit()`, which deliberately visits a DAG node once
+ * per *path* and would double-count shared subtrees (inflating `nodeCount`
+ * nondeterministically-looking across otherwise-identical plans).
+ */
+export function computePlanShape(root) {
+    const visited = new Set();
+    const stack = [root];
+    const counts = new Map();
+    let nodeCount = 0;
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (visited.has(node))
+            continue;
+        visited.add(node);
+        nodeCount++;
+        counts.set(node.nodeType, (counts.get(node.nodeType) ?? 0) + 1);
+        for (const child of node.getChildren()) {
+            stack.push(child);
+        }
+    }
+    const nodeTypes = {};
+    for (const key of [...counts.keys()].sort()) {
+        nodeTypes[key] = counts.get(key);
+    }
+    return { nodeCount, nodeTypes };
+}
+//# sourceMappingURL=work-counters.js.map

package/dist/src/runtime/work-counters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-counters.js","sourceRoot":"","sources":["../../../src/runtime/work-counters.ts"],"names":[],"mappings":"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"}

package/dist/src/vtab/alter-event-shape.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The per-arm shape of an `ALTER TABLE` schema-change announcement, derived from the
+ * {@link SchemaChangeInfo} the arm was called with. One derivation, shared by every
+ * emitter-backed module, so a subscriber sees the same facts regardless of backend.
+ */
+import type { SchemaChangeInfo } from './module.js';
+import type { VTableSchemaChangeEvent } from './events.js';
+/** The fields of a schema-change event that an ALTER TABLE arm decides. */
+export type AlterEventShape = Pick<VTableSchemaChangeEvent, 'type' | 'objectType' | 'columnName' | 'oldColumnName'>;
+/**
+ * Derive the `type` / `objectType` / column naming of an `ALTER TABLE` announcement:
+ * `alter`/`column` naming the touched column for the column arms (`drop`/`column` for
+ * DROP COLUMN), `alter`/`table` for the whole-table ones. Matches what the engine's own
+ * no-emitter path reports for the same statements (`runtime/emit/alter-table.ts`) and
+ * what `docs/usage.md` § What each `ALTER TABLE` arm reports promises.
+ *
+ * The caller supplies the rest of the event (`schemaName`, `objectName`, `ddl`) and owns
+ * the emit-iff-`change.ddl` gate. `RENAME TO` is not an arm of this union — it goes
+ * through `renameTable` and reports `alter`/`table` with `oldObjectName`.
+ *
+ * The `switch` is exhaustive over the union so a new arm fails the build here rather
+ * than silently announcing the wrong shape.
+ *
+ * NOTE: this unifies the two EMITTER-BACKED producers (the memory module and the store).
+ * The engine's own fallback path is a third producer that still writes the same triples out
+ * by hand, one per arm, in `runtime/emit/alter-table.ts` — it emits at each arm's tail from
+ * per-arm locals, with no `SchemaChangeInfo` in scope to derive from. Drift between the two
+ * derivations is caught by the cross-backend parity spec (`@quereus/store`'s
+ * `test/alter-events.spec.ts`), so this is a duplication with a guard, not an open hole. If a
+ * fourth producer appears, or the arm union grows enough that the parity spec stops covering
+ * every arm, thread the `SchemaChangeInfo` down to those emit sites and delete the hand-written
+ * triples.
+ */
+export declare function alterEventShape(change: SchemaChangeInfo): AlterEventShape;
+//# sourceMappingURL=alter-event-shape.d.ts.map

package/dist/src/vtab/alter-event-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alter-event-shape.d.ts","sourceRoot":"","sources":["../../../src/vtab/alter-event-shape.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,IAAI,CACjC,uBAAuB,EACvB,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,eAAe,CACtD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAgBzE"}

package/dist/src/vtab/alter-event-shape.js

@@ -0,0 +1,47 @@
+/**
+ * The per-arm shape of an `ALTER TABLE` schema-change announcement, derived from the
+ * {@link SchemaChangeInfo} the arm was called with. One derivation, shared by every
+ * emitter-backed module, so a subscriber sees the same facts regardless of backend.
+ */
+/**
+ * Derive the `type` / `objectType` / column naming of an `ALTER TABLE` announcement:
+ * `alter`/`column` naming the touched column for the column arms (`drop`/`column` for
+ * DROP COLUMN), `alter`/`table` for the whole-table ones. Matches what the engine's own
+ * no-emitter path reports for the same statements (`runtime/emit/alter-table.ts`) and
+ * what `docs/usage.md` § What each `ALTER TABLE` arm reports promises.
+ *
+ * The caller supplies the rest of the event (`schemaName`, `objectName`, `ddl`) and owns
+ * the emit-iff-`change.ddl` gate. `RENAME TO` is not an arm of this union — it goes
+ * through `renameTable` and reports `alter`/`table` with `oldObjectName`.
+ *
+ * The `switch` is exhaustive over the union so a new arm fails the build here rather
+ * than silently announcing the wrong shape.
+ *
+ * NOTE: this unifies the two EMITTER-BACKED producers (the memory module and the store).
+ * The engine's own fallback path is a third producer that still writes the same triples out
+ * by hand, one per arm, in `runtime/emit/alter-table.ts` — it emits at each arm's tail from
+ * per-arm locals, with no `SchemaChangeInfo` in scope to derive from. Drift between the two
+ * derivations is caught by the cross-backend parity spec (`@quereus/store`'s
+ * `test/alter-events.spec.ts`), so this is a duplication with a guard, not an open hole. If a
+ * fourth producer appears, or the arm union grows enough that the parity spec stops covering
+ * every arm, thread the `SchemaChangeInfo` down to those emit sites and delete the hand-written
+ * triples.
+ */
+export function alterEventShape(change) {
+    switch (change.type) {
+        case 'addColumn':
+            return { type: 'alter', objectType: 'column', columnName: change.columnDef.name };
+        case 'dropColumn':
+            return { type: 'drop', objectType: 'column', columnName: change.columnName };
+        case 'renameColumn':
+            return { type: 'alter', objectType: 'column', columnName: change.newName, oldColumnName: change.oldName };
+        case 'alterColumn':
+            return { type: 'alter', objectType: 'column', columnName: change.columnName };
+        case 'alterPrimaryKey':
+        case 'addConstraint':
+        case 'dropConstraint':
+        case 'renameConstraint':
+            return { type: 'alter', objectType: 'table' };
+    }
+}
+//# sourceMappingURL=alter-event-shape.js.map

package/dist/src/vtab/alter-event-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alter-event-shape.js","sourceRoot":"","sources":["../../../src/vtab/alter-event-shape.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAwB;IACvD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,WAAW;YACf,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACnF,KAAK,YAAY;YAChB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QAC9E,KAAK,cAAc;YAClB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3G,KAAK,aAAa;YACjB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QAC/E,KAAK,iBAAiB,CAAC;QACvB,KAAK,eAAe,CAAC;QACrB,KAAK,gBAAgB,CAAC;QACtB,KAAK,kBAAkB;YACtB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IAChD,CAAC;AACF,CAAC"}

package/dist/src/vtab/best-access-plan.d.ts

@@ -5,6 +5,7 @@
 import { type SqlValue, type Row } from '../common/types.js';
 import type { LogicalType } from '../types/logical-type.js';
 import { type IndexDescriptor } from './index-descriptor.js';
+import type { IndexColumnSchema, TableSchema } from '../schema/table.js';
 /**
  * Constraint operators that can be pushed down to virtual tables
  */
@@ -128,6 +129,39 @@ export declare function equalitySeekKeyCount(f: PredicateConstraint): number | n
  * one fills no equality role at all, so it is not multi-valued either.
  */
 export declare function isMultiValueEquality(f: PredicateConstraint): boolean;
+/**
+ * Truncate an ordered key's order-preserving prefix at the first DESC column whose walk
+ * could misplace NULLs. Shared by every module that turns an index (or primary-key) walk
+ * into an ordering claim.
+ *
+ * The engine's ORDER BY places NULLs FIRST for BOTH directions — placement is absolute,
+ * never direction-conditioned (`orderByNullResult`, util/comparison.ts). Both shipped
+ * backends agree on an ASC column and DISAGREE on a DESC one: the store bit-inverts the
+ * column's key bytes (NULL's low `0x00` tag ends up last) and the memory module negates
+ * the ascending comparator (NULL is the lowest value, so negation sends it last). So a
+ * DESC ordering claim is only sound when no NULL can appear in that column's emitted
+ * rows:
+ *
+ *  - the column is declared NOT NULL — columns are NOT NULL by default in this engine, so
+ *    this is the case that keeps the gate from firing on ordinary tables;
+ *  - the column is pinned by this plan's own equality (`pinnedCols`) — an equality never
+ *    matches NULL, and a pinned column contributes no ordering anyway;
+ *  - some pushed filter on the column is NULL-excluding ({@link NULL_EXCLUDING_OPS}) —
+ *    this is what keeps `where n > 5 order by n desc` fast, and it holds whether or not
+ *    the module marks the filter handled: an unhandled filter is retained by the engine
+ *    as a residual `Filter`, which removes the NULL rows and preserves order either way.
+ *
+ * `keyColumns` is `ReadonlyArray<IndexColumnSchema>` rather than a whole `IndexSchema` so
+ * that a table's `primaryKeyDefinition` can be passed directly — `PrimaryKeyColumnDefinition`
+ * is structurally identical (`{ index; desc?; collation? }`) and a nullable DESC primary-key
+ * member is exposed by exactly the same reasoning as a secondary-index one.
+ *
+ * The prefix-length form is the primitive. A caller that claims a required ordering
+ * VERBATIM (all or nothing, which is what both backends' request-matching paths do) wants
+ * the boolean `nullSafeOrderingPrefixLength(...) === matchedLength`; truncation only
+ * matters where an index's OWN ordering is advertised with no request to match.
+ */
+export declare function nullSafeOrderingPrefixLength(tableInfo: TableSchema, request: BestAccessPlanRequest, keyColumns: ReadonlyArray<IndexColumnSchema>, orderPreservingPrefix: number, pinnedCols: ReadonlySet<number>): number;
 /**
  * Ordering specification for ORDER BY clauses
  */

package/dist/src/vtab/best-access-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"best-access-plan.d.ts","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"best-access-plan.d.ts","sourceRoot":"","sources":["../../../src/vtab/best-access-plan.ts"],"names":[],"mappings":"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"}

package/dist/src/vtab/best-access-plan.js

@@ -61,6 +61,70 @@ export function isMultiValueEquality(f) {
         return equalitySeekKeyCount(f) !== null;
     return Array.isArray(f.value) && f.value.length > 1;
 }
+/**
+ * Pushed-filter operators that reject a NULL in the filtered column: every comparison and
+ * IN-membership evaluates to NULL (not TRUE) against a NULL operand, and `IS NOT NULL`
+ * says so outright. A row with NULL in that column therefore cannot survive the filter —
+ * wherever the filter ends up being enforced.
+ *
+ * The set is deliberately INCOMPLETE, which costs an optimization and never correctness —
+ * a missing op declines a claim that would in fact have been sound. `OR_RANGE` is a union
+ * of NULL-rejecting ranges, but it already disqualifies an ordering claim on other grounds
+ * in both shipped backends (concatenated windows emit in range order, not column order),
+ * so listing it would widen what has to be argued and buy nothing. `NOT IN`, `MATCH`,
+ * `LIKE` and `GLOB` are NULL-rejecting too and could be added on demand; none of them
+ * reaches an ordering claim today.
+ */
+const NULL_EXCLUDING_OPS = new Set([
+    '=', 'IN', '>', '>=', '<', '<=', 'IS NOT NULL',
+]);
+/**
+ * Truncate an ordered key's order-preserving prefix at the first DESC column whose walk
+ * could misplace NULLs. Shared by every module that turns an index (or primary-key) walk
+ * into an ordering claim.
+ *
+ * The engine's ORDER BY places NULLs FIRST for BOTH directions — placement is absolute,
+ * never direction-conditioned (`orderByNullResult`, util/comparison.ts). Both shipped
+ * backends agree on an ASC column and DISAGREE on a DESC one: the store bit-inverts the
+ * column's key bytes (NULL's low `0x00` tag ends up last) and the memory module negates
+ * the ascending comparator (NULL is the lowest value, so negation sends it last). So a
+ * DESC ordering claim is only sound when no NULL can appear in that column's emitted
+ * rows:
+ *
+ *  - the column is declared NOT NULL — columns are NOT NULL by default in this engine, so
+ *    this is the case that keeps the gate from firing on ordinary tables;
+ *  - the column is pinned by this plan's own equality (`pinnedCols`) — an equality never
+ *    matches NULL, and a pinned column contributes no ordering anyway;
+ *  - some pushed filter on the column is NULL-excluding ({@link NULL_EXCLUDING_OPS}) —
+ *    this is what keeps `where n > 5 order by n desc` fast, and it holds whether or not
+ *    the module marks the filter handled: an unhandled filter is retained by the engine
+ *    as a residual `Filter`, which removes the NULL rows and preserves order either way.
+ *
+ * `keyColumns` is `ReadonlyArray<IndexColumnSchema>` rather than a whole `IndexSchema` so
+ * that a table's `primaryKeyDefinition` can be passed directly — `PrimaryKeyColumnDefinition`
+ * is structurally identical (`{ index; desc?; collation? }`) and a nullable DESC primary-key
+ * member is exposed by exactly the same reasoning as a secondary-index one.
+ *
+ * The prefix-length form is the primitive. A caller that claims a required ordering
+ * VERBATIM (all or nothing, which is what both backends' request-matching paths do) wants
+ * the boolean `nullSafeOrderingPrefixLength(...) === matchedLength`; truncation only
+ * matters where an index's OWN ordering is advertised with no request to match.
+ */
+export function nullSafeOrderingPrefixLength(tableInfo, request, keyColumns, orderPreservingPrefix, pinnedCols) {
+    for (let i = 0; i < orderPreservingPrefix; i++) {
+        const col = keyColumns[i];
+        if (!col.desc)
+            continue;
+        if (tableInfo.columns[col.index]?.notNull)
+            continue;
+        if (pinnedCols.has(col.index))
+            continue;
+        if (request.filters.some(f => f.columnIndex === col.index && NULL_EXCLUDING_OPS.has(f.op)))
+            continue;
+        return i;
+    }
+    return orderPreservingPrefix;
+}
 /**
  * Builder class for constructing access plan results
  */