@rocicorp/zero 1.11.0-canary.13 → 1.11.0-canary.15

package/out/zqlite/src/pending-delta.d.ts

@@ -0,0 +1,110 @@
+import type { Ordering } from '../../zero-protocol/src/ast.ts';
+import type { Row } from '../../zero-protocol/src/data.ts';
+import type { PrimaryKey } from '../../zero-protocol/src/primary-key.ts';
+import { type Constraint } from '../../zql/src/ivm/constraint.ts';
+import type { Comparator } from '../../zql/src/ivm/data.ts';
+import type { MultiConstraint } from '../../zql/src/ivm/operator.ts';
+/**
+ * The batch overlay that lets a `TableSource` derive a transaction without
+ * writing to the database it is reading from.
+ *
+ * A `TableSource` normally makes each change durable in its backing SQLite
+ * connection as soon as it has been vended to every output, because change
+ * *k+1* has to read a base that already includes changes *1..k* -- IVM's
+ * joins fetch from the source mid-push. On the server that backing connection
+ * is a `BEGIN CONCURRENT` snapshot that is never committed and always rolled
+ * back, so those writes exist only to serve reads for the rest of the pass.
+ *
+ * A `PendingDelta` holds them in memory instead. The base stays pinned at the
+ * state it had when the pass began and this object supplies *1..k*, merged
+ * into every leaf scan. The durable copy comes from the replicator's own
+ * commit, which the source picks up when it leapfrogs to the next snapshot.
+ *
+ * State is coalesced by primary key: whatever the batch did to a row, all that
+ * matters downstream is the row's final value, or that it is gone. A key that
+ * appears here overrides the base unconditionally -- an added row has no base
+ * to override, an edited row's base copy is suppressed in favor of the new
+ * value, and a removed row's base copy is suppressed with nothing to put in
+ * its place.
+ *
+ * Live rows are additionally kept in lazily built sorted indexes, one per
+ * `[...constraintKeys, ...sort]` shape a fetch has asked for, so that merging
+ * the delta into a constrained scan costs `O(log D + matches)` rather than a
+ * walk of the whole delta. This mirrors `MemorySource`'s index handling; see
+ * its `#fetch` for the bound construction the scans here reproduce.
+ */
+export declare class PendingDelta {
+    #private;
+    constructor(primaryKey: PrimaryKey);
+    /**
+     * True when the source can take its untouched fast path: no suppression
+     * test per base row, no merge, no index maintenance.
+     */
+    get isEmpty(): boolean;
+    /** The number of rows the batch has touched, tombstones included. */
+    get size(): number;
+    /**
+     * Estimated retained bytes, including keys, tombstones, and sorted indexes.
+     * This is a budgeting heuristic, not a measurement of the JavaScript heap.
+     */
+    get estimatedBytes(): number;
+    /** Records that `row` is now present with this value. */
+    set(row: Row): void;
+    /** Records that `row` is now absent. */
+    delete(row: Row): void;
+    /**
+     * Whether the batch overrides this base row. Callers use it to suppress base
+     * rows during a merge, so it must be answered by primary key -- the value
+     * carried by the base row is exactly what the delta is replacing.
+     */
+    overrides(row: Row): boolean;
+    /**
+     * The batch's value for a row, by primary key. Returns `NOT_OVERRIDDEN` when
+     * the batch has not touched the key at all (so the caller should consult the
+     * base) and `undefined` when the batch removed it.
+     */
+    get(row: Row): Row | undefined | typeof NOT_OVERRIDDEN;
+    /**
+     * Looks a row up by an arbitrary (not necessarily primary) unique key. Only
+     * reachable when the delta is non-empty, which is never the case for the one
+     * caller that uses a non-primary key, so a walk is fine here.
+     */
+    getByColumns(keyCols: readonly string[], keyRow: Row): Row | undefined;
+    /**
+     * The live rows this batch contributes to a fetch, in the same order the
+     * backing SQL query returns its rows, so the two streams can be merged.
+     *
+     * `constraint`, `multiConstraints` and `filterPredicate` are the ones SQL
+     * already applied to the base rows; they are applied here so the delta rows
+     * are subject to the same query. `start` is the fetch's start row: the scan
+     * begins there rather than at the start of the constraint span. It is
+     * inclusive, so the caller still applies an `after` basis.
+     */
+    rowsFor(sort: Ordering, constraint: Constraint | undefined, reverse: boolean | undefined, filterPredicate: ((row: Row) => boolean | undefined) | undefined, multiConstraints: readonly MultiConstraint[] | undefined, start?: Row | undefined): Iterable<Row>;
+    /**
+     * A row with the primary key of each row the batch has touched, removed
+     * rows included. A live row is returned as is.
+     */
+    touchedKeys(): Iterable<Row>;
+    /** The rows the batch has added or edited, and not since removed. */
+    liveRows(): Iterable<Row>;
+    /** Drops the batch. Called when the source moves to a snapshot that has it. */
+    clear(): void;
+}
+export declare const NOT_OVERRIDDEN: unique symbol;
+/**
+ * Merges a batch's rows into an ordered base stream and drops the base rows
+ * the batch overrides.
+ *
+ * Both streams must already be in `compare` order. A delta row that ties with
+ * a base row is the *same* row by primary key -- every fetch ordering includes
+ * the primary key -- so the base copy is suppressed and the delta's value
+ * takes its place at that position.
+ */
+export declare function generateWithPendingDelta(baseRows: Iterable<Row>, deltaRows: Iterable<Row>, delta: PendingDelta, compare: Comparator): IterableIterator<Row>;
+/**
+ * The unordered counterpart. Nothing downstream depends on position, so the
+ * surviving base rows are emitted first and the batch's rows follow.
+ */
+export declare function generateWithPendingDeltaUnordered(baseRows: Iterable<Row>, deltaRows: Iterable<Row>, delta: PendingDelta): IterableIterator<Row>;
+//# sourceMappingURL=pending-delta.d.ts.map

package/out/zqlite/src/pending-delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-delta.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/pending-delta.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,QAAQ,EAAY,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAC,GAAG,EAAQ,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,wCAAwC,CAAC;AACvE,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AAQ1D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,YAAY;;IA0BvB,YAAY,UAAU,EAAE,UAAU,EAGjC;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,qEAAqE;IACrE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,IAAI,cAAc,IAAI,MAAM,CAO3B;IAqBD,yDAAyD;IACzD,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAgBlB;IAED,wCAAwC;IACxC,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAUrB;IAED;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAQ3B;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,GAAG,OAAO,cAAc,CAMrD;IAED;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAOrE;IA8BD;;;;;;;;;OASG;IACF,OAAO,CACN,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,eAAe,EAAE,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,EAChE,gBAAgB,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,EACxD,KAAK,CAAC,EAAE,GAAG,GAAG,SAAS,GACtB,QAAQ,CAAC,GAAG,CAAC,CAiEf;IAED;;;OAGG;IACF,WAAW,IAAI,QAAQ,CAAC,GAAG,CAAC,CAc5B;IAED,qEAAqE;IACpE,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,CAMzB;IAED,+EAA+E;IAC/E,KAAK,IAAI,IAAI,CAOZ;CACF;AAwBD,eAAO,MAAM,cAAc,eAA2B,CAAC;AAwBvD;;;;;;;;GAQG;AACH,wBAAiB,wBAAwB,CACvC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,EACvB,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,EACxB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,UAAU,GAClB,gBAAgB,CAAC,GAAG,CAAC,CAwBvB;AAED;;;GAGG;AACH,wBAAiB,iCAAiC,CAChD,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,EACvB,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,EACxB,KAAK,EAAE,YAAY,GAClB,gBAAgB,CAAC,GAAG,CAAC,CAOvB"}

package/out/zqlite/src/pending-delta.js

@@ -0,0 +1,278 @@
+import { hasOwn } from "../../shared/src/has-own.js";
+import { constraintMatchesPrimaryKey, constraintMatchesRow } from "../../zql/src/ivm/constraint.js";
+import { BTreeSet } from "../../shared/src/btree-set.js";
+import { generateRows, makeBoundComparator, maxValue, minValue } from "../../zql/src/ivm/memory-source.js";
+//#region ../zqlite/src/pending-delta.ts
+/**
+* The batch overlay that lets a `TableSource` derive a transaction without
+* writing to the database it is reading from.
+*
+* A `TableSource` normally makes each change durable in its backing SQLite
+* connection as soon as it has been vended to every output, because change
+* *k+1* has to read a base that already includes changes *1..k* -- IVM's
+* joins fetch from the source mid-push. On the server that backing connection
+* is a `BEGIN CONCURRENT` snapshot that is never committed and always rolled
+* back, so those writes exist only to serve reads for the rest of the pass.
+*
+* A `PendingDelta` holds them in memory instead. The base stays pinned at the
+* state it had when the pass began and this object supplies *1..k*, merged
+* into every leaf scan. The durable copy comes from the replicator's own
+* commit, which the source picks up when it leapfrogs to the next snapshot.
+*
+* State is coalesced by primary key: whatever the batch did to a row, all that
+* matters downstream is the row's final value, or that it is gone. A key that
+* appears here overrides the base unconditionally -- an added row has no base
+* to override, an edited row's base copy is suppressed in favor of the new
+* value, and a removed row's base copy is suppressed with nothing to put in
+* its place.
+*
+* Live rows are additionally kept in lazily built sorted indexes, one per
+* `[...constraintKeys, ...sort]` shape a fetch has asked for, so that merging
+* the delta into a constrained scan costs `O(log D + matches)` rather than a
+* walk of the whole delta. This mirrors `MemorySource`'s index handling; see
+* its `#fetch` for the bound construction the scans here reproduce.
+*/
+var PendingDelta = class {
+	#primaryKey;
+	#singleColumnKey;
+	/**
+	* For a composite primary key, the first key column's value of every key in
+	* `#byKey`. {@link overrides} runs for every base row of a merged fetch, and
+	* building a composite key allocates, so this rules most rows out first.
+	*/
+	#firstKeyValues = /* @__PURE__ */ new Set();
+	/**
+	* The coalesced net state, keyed by primary key. A `undefined` value is a
+	* tombstone: the batch removed the row, so the base copy is suppressed and
+	* nothing replaces it. Membership alone is what suppresses a base row, so
+	* this map is also the "is this key overridden" test.
+	*/
+	#byKey = /* @__PURE__ */ new Map();
+	/** Sorted views over the live (non-tombstone) rows, keyed by `JSON(sort)`. */
+	#indexes = /* @__PURE__ */ new Map();
+	#liveCount = 0;
+	#rowBytes = 0;
+	#indexBytes = 0;
+	constructor(primaryKey) {
+		this.#primaryKey = primaryKey;
+		this.#singleColumnKey = primaryKey.length === 1 ? primaryKey[0] : void 0;
+	}
+	/**
+	* True when the source can take its untouched fast path: no suppression
+	* test per base row, no merge, no index maintenance.
+	*/
+	get isEmpty() {
+		return this.#byKey.size === 0;
+	}
+	/** The number of rows the batch has touched, tombstones included. */
+	get size() {
+		return this.#byKey.size;
+	}
+	/**
+	* Estimated retained bytes, including keys, tombstones, and sorted indexes.
+	* This is a budgeting heuristic, not a measurement of the JavaScript heap.
+	*/
+	get estimatedBytes() {
+		return this.#rowBytes + this.#indexBytes + this.#liveCount * this.#indexes.size * 32;
+	}
+	#key(row) {
+		const single = this.#singleColumnKey;
+		if (single !== void 0) return row[single];
+		const key = this.#primaryKey.map((k) => row[k]);
+		return JSON.stringify(key);
+	}
+	#track(row, key) {
+		if (this.#byKey.has(key)) return;
+		this.#rowBytes += 64 + estimateBytes(key);
+		if (this.#singleColumnKey === void 0) this.#firstKeyValues.add(row[this.#primaryKey[0]]);
+	}
+	/** Records that `row` is now present with this value. */
+	set(row) {
+		const key = this.#key(row);
+		const existing = this.#byKey.get(key);
+		this.#track(row, key);
+		this.#rowBytes += estimateBytes(row) - (existing === void 0 ? 0 : estimateBytes(existing));
+		if (existing !== void 0) {
+			this.#removeFromIndexes(existing);
+			this.#liveCount--;
+		}
+		this.#byKey.set(key, row);
+		this.#addToIndexes(row);
+		this.#liveCount++;
+	}
+	/** Records that `row` is now absent. */
+	delete(row) {
+		const key = this.#key(row);
+		const existing = this.#byKey.get(key);
+		this.#track(row, key);
+		if (existing !== void 0) {
+			this.#rowBytes -= estimateBytes(existing);
+			this.#removeFromIndexes(existing);
+			this.#liveCount--;
+		}
+		this.#byKey.set(key, void 0);
+	}
+	/**
+	* Whether the batch overrides this base row. Callers use it to suppress base
+	* rows during a merge, so it must be answered by primary key -- the value
+	* carried by the base row is exactly what the delta is replacing.
+	*/
+	overrides(row) {
+		if (this.#singleColumnKey === void 0 && !this.#firstKeyValues.has(row[this.#primaryKey[0]])) return false;
+		return this.#byKey.has(this.#key(row));
+	}
+	/**
+	* The batch's value for a row, by primary key. Returns `NOT_OVERRIDDEN` when
+	* the batch has not touched the key at all (so the caller should consult the
+	* base) and `undefined` when the batch removed it.
+	*/
+	get(row) {
+		const key = this.#key(row);
+		if (!this.#byKey.has(key)) return NOT_OVERRIDDEN;
+		return this.#byKey.get(key);
+	}
+	/**
+	* Looks a row up by an arbitrary (not necessarily primary) unique key. Only
+	* reachable when the delta is non-empty, which is never the case for the one
+	* caller that uses a non-primary key, so a walk is fine here.
+	*/
+	getByColumns(keyCols, keyRow) {
+		for (const row of this.#byKey.values()) if (row !== void 0 && keyCols.every((c) => row[c] === keyRow[c])) return row;
+	}
+	#addToIndexes(row) {
+		for (const data of this.#indexes.values()) data.add(row);
+	}
+	#removeFromIndexes(row) {
+		for (const data of this.#indexes.values()) data.delete(row);
+	}
+	#getOrCreateIndex(sort) {
+		const indexKey = JSON.stringify(sort);
+		let data = this.#indexes.get(indexKey);
+		if (data === void 0) {
+			data = new BTreeSet(makeBoundComparator(sort));
+			for (const row of this.#byKey.values()) if (row !== void 0) data.add(row);
+			this.#indexes.set(indexKey, data);
+			this.#indexBytes += 128 + estimateBytes(indexKey) + estimateBytes(sort);
+		}
+		return data;
+	}
+	/**
+	* The live rows this batch contributes to a fetch, in the same order the
+	* backing SQL query returns its rows, so the two streams can be merged.
+	*
+	* `constraint`, `multiConstraints` and `filterPredicate` are the ones SQL
+	* already applied to the base rows; they are applied here so the delta rows
+	* are subject to the same query. `start` is the fetch's start row: the scan
+	* begins there rather than at the start of the constraint span. It is
+	* inclusive, so the caller still applies an `after` basis.
+	*/
+	*rowsFor(sort, constraint, reverse, filterPredicate, multiConstraints, start) {
+		if (this.#liveCount === 0) return;
+		const indexSort = [];
+		if (constraint) for (const key of Object.keys(constraint)) indexSort.push([key, "asc"]);
+		const sorted = !constraint || !constraintMatchesPrimaryKey(constraint, this.#primaryKey);
+		if (sorted) indexSort.push(...sort);
+		const data = this.#getOrCreateIndex(indexSort);
+		let scanStart;
+		if (start !== void 0 && sorted && (!constraint || constraintMatchesRow(constraint, start))) scanStart = start;
+		else if (constraint) {
+			scanStart = {};
+			for (const [key, dir] of indexSort) if (hasOwn(constraint, key)) scanStart[key] = constraint[key];
+			else if (reverse) scanStart[key] = dir === "asc" ? maxValue : minValue;
+			else scanStart[key] = dir === "asc" ? minValue : maxValue;
+		}
+		for (const row of generateRows(data, scanStart, reverse)) {
+			if (constraint && !constraintMatchesRow(constraint, row)) break;
+			if (multiConstraints && !matchesMultiConstraints(row, multiConstraints)) continue;
+			if (filterPredicate && !filterPredicate(row)) continue;
+			yield row;
+		}
+	}
+	/**
+	* A row with the primary key of each row the batch has touched, removed
+	* rows included. A live row is returned as is.
+	*/
+	*touchedKeys() {
+		const single = this.#singleColumnKey;
+		for (const [key, row] of this.#byKey) if (row !== void 0) yield row;
+		else if (single !== void 0) yield { [single]: key };
+		else {
+			const values = JSON.parse(key);
+			yield Object.fromEntries(this.#primaryKey.map((k, i) => [k, values[i]]));
+		}
+	}
+	/** The rows the batch has added or edited, and not since removed. */
+	*liveRows() {
+		for (const row of this.#byKey.values()) if (row !== void 0) yield row;
+	}
+	/** Drops the batch. Called when the source moves to a snapshot that has it. */
+	clear() {
+		this.#byKey.clear();
+		this.#firstKeyValues.clear();
+		this.#indexes.clear();
+		this.#liveCount = 0;
+		this.#rowBytes = 0;
+		this.#indexBytes = 0;
+	}
+};
+function estimateBytes(value) {
+	if (typeof value === "string") return 24 + value.length * 2;
+	if (value === null || typeof value !== "object") return 8;
+	let bytes = 32;
+	if (Array.isArray(value)) for (const item of value) bytes += 8 + estimateBytes(item);
+	else for (const key in value) bytes += 16 + estimateBytes(key) + estimateBytes(value[key]);
+	return bytes;
+}
+var NOT_OVERRIDDEN = Symbol("not-overridden");
+function matchesMultiConstraints(row, multiConstraints) {
+	for (const mc of multiConstraints) {
+		if (mc.length === 0) continue;
+		let any = false;
+		for (const c of mc) if (constraintMatchesRow(c, row)) {
+			any = true;
+			break;
+		}
+		if (!any) return false;
+	}
+	return true;
+}
+/**
+* Merges a batch's rows into an ordered base stream and drops the base rows
+* the batch overrides.
+*
+* Both streams must already be in `compare` order. A delta row that ties with
+* a base row is the *same* row by primary key -- every fetch ordering includes
+* the primary key -- so the base copy is suppressed and the delta's value
+* takes its place at that position.
+*/
+function* generateWithPendingDelta(baseRows, deltaRows, delta, compare) {
+	const deltaIter = deltaRows[Symbol.iterator]();
+	let pending = deltaIter.next();
+	try {
+		for (const row of baseRows) {
+			while (!pending.done && compare(pending.value, row) < 0) {
+				yield pending.value;
+				pending = deltaIter.next();
+			}
+			if (!delta.overrides(row)) yield row;
+		}
+		while (!pending.done) {
+			yield pending.value;
+			pending = deltaIter.next();
+		}
+	} finally {
+		if (!pending.done) deltaIter.return?.(void 0);
+	}
+}
+/**
+* The unordered counterpart. Nothing downstream depends on position, so the
+* surviving base rows are emitted first and the batch's rows follow.
+*/
+function* generateWithPendingDeltaUnordered(baseRows, deltaRows, delta) {
+	for (const row of baseRows) if (!delta.overrides(row)) yield row;
+	yield* deltaRows;
+}
+//#endregion
+export { NOT_OVERRIDDEN, PendingDelta, generateWithPendingDelta, generateWithPendingDeltaUnordered };
+
+//# sourceMappingURL=pending-delta.js.map

package/out/zqlite/src/pending-delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-delta.js","names":["#primaryKey","#singleColumnKey","#firstKeyValues","#byKey","#indexes","#rowBytes","#indexBytes","#liveCount","#key","#track","#removeFromIndexes","#addToIndexes","#getOrCreateIndex"],"sources":["../../../../zqlite/src/pending-delta.ts"],"sourcesContent":["import {BTreeSet} from '../../shared/src/btree-set.ts';\nimport {hasOwn} from '../../shared/src/has-own.ts';\nimport type {Ordering, OrderPart} from '../../zero-protocol/src/ast.ts';\nimport type {Row, Value} from '../../zero-protocol/src/data.ts';\nimport type {PrimaryKey} from '../../zero-protocol/src/primary-key.ts';\nimport {\n  constraintMatchesPrimaryKey,\n  constraintMatchesRow,\n  type Constraint,\n} from '../../zql/src/ivm/constraint.ts';\nimport type {Comparator} from '../../zql/src/ivm/data.ts';\nimport {\n  generateRows,\n  makeBoundComparator,\n  maxValue,\n  minValue,\n  type RowBound,\n} from '../../zql/src/ivm/memory-source.ts';\nimport type {MultiConstraint} from '../../zql/src/ivm/operator.ts';\n\n/**\n * The batch overlay that lets a `TableSource` derive a transaction without\n * writing to the database it is reading from.\n *\n * A `TableSource` normally makes each change durable in its backing SQLite\n * connection as soon as it has been vended to every output, because change\n * *k+1* has to read a base that already includes changes *1..k* -- IVM's\n * joins fetch from the source mid-push. On the server that backing connection\n * is a `BEGIN CONCURRENT` snapshot that is never committed and always rolled\n * back, so those writes exist only to serve reads for the rest of the pass.\n *\n * A `PendingDelta` holds them in memory instead. The base stays pinned at the\n * state it had when the pass began and this object supplies *1..k*, merged\n * into every leaf scan. The durable copy comes from the replicator's own\n * commit, which the source picks up when it leapfrogs to the next snapshot.\n *\n * State is coalesced by primary key: whatever the batch did to a row, all that\n * matters downstream is the row's final value, or that it is gone. A key that\n * appears here overrides the base unconditionally -- an added row has no base\n * to override, an edited row's base copy is suppressed in favor of the new\n * value, and a removed row's base copy is suppressed with nothing to put in\n * its place.\n *\n * Live rows are additionally kept in lazily built sorted indexes, one per\n * `[...constraintKeys, ...sort]` shape a fetch has asked for, so that merging\n * the delta into a constrained scan costs `O(log D + matches)` rather than a\n * walk of the whole delta. This mirrors `MemorySource`'s index handling; see\n * its `#fetch` for the bound construction the scans here reproduce.\n */\nexport class PendingDelta {\n  readonly #primaryKey: PrimaryKey;\n  readonly #singleColumnKey: string | undefined;\n\n  /**\n   * For a composite primary key, the first key column's value of every key in\n   * `#byKey`. {@link overrides} runs for every base row of a merged fetch, and\n   * building a composite key allocates, so this rules most rows out first.\n   */\n  readonly #firstKeyValues = new Set<Value>();\n\n  /**\n   * The coalesced net state, keyed by primary key. A `undefined` value is a\n   * tombstone: the batch removed the row, so the base copy is suppressed and\n   * nothing replaces it. Membership alone is what suppresses a base row, so\n   * this map is also the \"is this key overridden\" test.\n   */\n  readonly #byKey = new Map<unknown, Row | undefined>();\n\n  /** Sorted views over the live (non-tombstone) rows, keyed by `JSON(sort)`. */\n  readonly #indexes = new Map<string, BTreeSet<Row>>();\n\n  #liveCount = 0;\n  #rowBytes = 0;\n  #indexBytes = 0;\n\n  constructor(primaryKey: PrimaryKey) {\n    this.#primaryKey = primaryKey;\n    this.#singleColumnKey = primaryKey.length === 1 ? primaryKey[0] : undefined;\n  }\n\n  /**\n   * True when the source can take its untouched fast path: no suppression\n   * test per base row, no merge, no index maintenance.\n   */\n  get isEmpty(): boolean {\n    return this.#byKey.size === 0;\n  }\n\n  /** The number of rows the batch has touched, tombstones included. */\n  get size(): number {\n    return this.#byKey.size;\n  }\n\n  /**\n   * Estimated retained bytes, including keys, tombstones, and sorted indexes.\n   * This is a budgeting heuristic, not a measurement of the JavaScript heap.\n   */\n  get estimatedBytes(): number {\n    // Budget 32 bytes per live row per index for references and B-tree nodes.\n    return (\n      this.#rowBytes +\n      this.#indexBytes +\n      this.#liveCount * this.#indexes.size * 32\n    );\n  }\n\n  #key(row: Row): unknown {\n    const single = this.#singleColumnKey;\n    if (single !== undefined) {\n      return row[single];\n    }\n    const key = this.#primaryKey.map(k => row[k]);\n    return JSON.stringify(key);\n  }\n\n  #track(row: Row, key: unknown): void {\n    if (this.#byKey.has(key)) {\n      return;\n    }\n    this.#rowBytes += 64 + estimateBytes(key as Value);\n    if (this.#singleColumnKey === undefined) {\n      this.#firstKeyValues.add(row[this.#primaryKey[0]]);\n    }\n  }\n\n  /** Records that `row` is now present with this value. */\n  set(row: Row): void {\n    const key = this.#key(row);\n    const existing = this.#byKey.get(key);\n    this.#track(row, key);\n    this.#rowBytes +=\n      estimateBytes(row) -\n      (existing === undefined ? 0 : estimateBytes(existing));\n    if (existing !== undefined) {\n      // A live row for this key is already indexed under its old value, which\n      // may sort differently. Retract it before inserting the new one.\n      this.#removeFromIndexes(existing);\n      this.#liveCount--;\n    }\n    this.#byKey.set(key, row);\n    this.#addToIndexes(row);\n    this.#liveCount++;\n  }\n\n  /** Records that `row` is now absent. */\n  delete(row: Row): void {\n    const key = this.#key(row);\n    const existing = this.#byKey.get(key);\n    this.#track(row, key);\n    if (existing !== undefined) {\n      this.#rowBytes -= estimateBytes(existing);\n      this.#removeFromIndexes(existing);\n      this.#liveCount--;\n    }\n    this.#byKey.set(key, undefined);\n  }\n\n  /**\n   * Whether the batch overrides this base row. Callers use it to suppress base\n   * rows during a merge, so it must be answered by primary key -- the value\n   * carried by the base row is exactly what the delta is replacing.\n   */\n  overrides(row: Row): boolean {\n    if (\n      this.#singleColumnKey === undefined &&\n      !this.#firstKeyValues.has(row[this.#primaryKey[0]])\n    ) {\n      return false;\n    }\n    return this.#byKey.has(this.#key(row));\n  }\n\n  /**\n   * The batch's value for a row, by primary key. Returns `NOT_OVERRIDDEN` when\n   * the batch has not touched the key at all (so the caller should consult the\n   * base) and `undefined` when the batch removed it.\n   */\n  get(row: Row): Row | undefined | typeof NOT_OVERRIDDEN {\n    const key = this.#key(row);\n    if (!this.#byKey.has(key)) {\n      return NOT_OVERRIDDEN;\n    }\n    return this.#byKey.get(key);\n  }\n\n  /**\n   * Looks a row up by an arbitrary (not necessarily primary) unique key. Only\n   * reachable when the delta is non-empty, which is never the case for the one\n   * caller that uses a non-primary key, so a walk is fine here.\n   */\n  getByColumns(keyCols: readonly string[], keyRow: Row): Row | undefined {\n    for (const row of this.#byKey.values()) {\n      if (row !== undefined && keyCols.every(c => row[c] === keyRow[c])) {\n        return row;\n      }\n    }\n    return undefined;\n  }\n\n  #addToIndexes(row: Row): void {\n    for (const data of this.#indexes.values()) {\n      data.add(row);\n    }\n  }\n\n  #removeFromIndexes(row: Row): void {\n    for (const data of this.#indexes.values()) {\n      data.delete(row);\n    }\n  }\n\n  #getOrCreateIndex(sort: Ordering): BTreeSet<Row> {\n    const indexKey = JSON.stringify(sort);\n    let data = this.#indexes.get(indexKey);\n    if (data === undefined) {\n      data = new BTreeSet<Row>(makeBoundComparator(sort) as Comparator);\n      for (const row of this.#byKey.values()) {\n        if (row !== undefined) {\n          data.add(row);\n        }\n      }\n      this.#indexes.set(indexKey, data);\n      this.#indexBytes += 128 + estimateBytes(indexKey) + estimateBytes(sort);\n    }\n    return data;\n  }\n\n  /**\n   * The live rows this batch contributes to a fetch, in the same order the\n   * backing SQL query returns its rows, so the two streams can be merged.\n   *\n   * `constraint`, `multiConstraints` and `filterPredicate` are the ones SQL\n   * already applied to the base rows; they are applied here so the delta rows\n   * are subject to the same query. `start` is the fetch's start row: the scan\n   * begins there rather than at the start of the constraint span. It is\n   * inclusive, so the caller still applies an `after` basis.\n   */\n  *rowsFor(\n    sort: Ordering,\n    constraint: Constraint | undefined,\n    reverse: boolean | undefined,\n    filterPredicate: ((row: Row) => boolean | undefined) | undefined,\n    multiConstraints: readonly MultiConstraint[] | undefined,\n    start?: Row | undefined,\n  ): Iterable<Row> {\n    if (this.#liveCount === 0) {\n      return;\n    }\n\n    // Lead the index with the constraint keys so a constrained fetch scans\n    // only the matching span; within that span rows come out in `sort` order,\n    // which is the order SQL returned the base rows in.\n    const indexSort: OrderPart[] = [];\n    if (constraint) {\n      for (const key of Object.keys(constraint)) {\n        indexSort.push([key, 'asc']);\n      }\n    }\n    // Constraining by the whole primary key admits at most one row, so the\n    // requested sort adds nothing.\n    const sorted =\n      !constraint || !constraintMatchesPrimaryKey(constraint, this.#primaryKey);\n    if (sorted) {\n      indexSort.push(...sort);\n    }\n\n    const data = this.#getOrCreateIndex(indexSort);\n\n    let scanStart: RowBound | undefined;\n    if (\n      start !== undefined &&\n      sorted &&\n      (!constraint || constraintMatchesRow(constraint, start))\n    ) {\n      // `start` carries every index column, and within the constraint span it\n      // agrees with the constraint, so it is the scan's bound as it stands.\n      // A `start` outside the span bounds nothing the scan can use.\n      scanStart = start;\n    } else if (constraint) {\n      // The first row matching the constraint is not simply the constraint\n      // values with everything else absent: a `desc` part puts absent values\n      // last. The min/max sentinels say \"the first row with these constraint\n      // values\" regardless of direction. Same construction as `MemorySource`.\n      scanStart = {};\n      for (const [key, dir] of indexSort) {\n        if (hasOwn(constraint, key)) {\n          scanStart[key] = constraint[key] as Value;\n        } else if (reverse) {\n          scanStart[key] = dir === 'asc' ? maxValue : minValue;\n        } else {\n          scanStart[key] = dir === 'asc' ? minValue : maxValue;\n        }\n      }\n    }\n\n    for (const row of generateRows(data, scanStart, reverse)) {\n      if (constraint && !constraintMatchesRow(constraint, row)) {\n        // Rows are sorted by the constraint keys first, so matches are\n        // contiguous and the first miss ends the span.\n        break;\n      }\n      if (multiConstraints && !matchesMultiConstraints(row, multiConstraints)) {\n        continue;\n      }\n      if (filterPredicate && !filterPredicate(row)) {\n        continue;\n      }\n      yield row;\n    }\n  }\n\n  /**\n   * A row with the primary key of each row the batch has touched, removed\n   * rows included. A live row is returned as is.\n   */\n  *touchedKeys(): Iterable<Row> {\n    const single = this.#singleColumnKey;\n    for (const [key, row] of this.#byKey) {\n      if (row !== undefined) {\n        yield row;\n      } else if (single !== undefined) {\n        yield {[single]: key as Value};\n      } else {\n        const values = JSON.parse(key as string) as Value[];\n        yield Object.fromEntries(\n          this.#primaryKey.map((k, i) => [k, values[i]]),\n        );\n      }\n    }\n  }\n\n  /** The rows the batch has added or edited, and not since removed. */\n  *liveRows(): Iterable<Row> {\n    for (const row of this.#byKey.values()) {\n      if (row !== undefined) {\n        yield row;\n      }\n    }\n  }\n\n  /** Drops the batch. Called when the source moves to a snapshot that has it. */\n  clear(): void {\n    this.#byKey.clear();\n    this.#firstKeyValues.clear();\n    this.#indexes.clear();\n    this.#liveCount = 0;\n    this.#rowBytes = 0;\n    this.#indexBytes = 0;\n  }\n}\n\n// Allow for object/property storage and UTF-16 strings without allocating a\n// serialized copy. Shared values may be counted more than once intentionally.\nfunction estimateBytes(value: Value): number {\n  if (typeof value === 'string') {\n    return 24 + value.length * 2;\n  }\n  if (value === null || typeof value !== 'object') {\n    return 8;\n  }\n  let bytes = 32;\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      bytes += 8 + estimateBytes(item);\n    }\n  } else {\n    for (const key in value) {\n      bytes += 16 + estimateBytes(key) + estimateBytes((value as Row)[key]);\n    }\n  }\n  return bytes;\n}\n\nexport const NOT_OVERRIDDEN = Symbol('not-overridden');\n\nfunction matchesMultiConstraints(\n  row: Row,\n  multiConstraints: readonly MultiConstraint[],\n): boolean {\n  for (const mc of multiConstraints) {\n    if (mc.length === 0) {\n      continue;\n    }\n    let any = false;\n    for (const c of mc) {\n      if (constraintMatchesRow(c, row)) {\n        any = true;\n        break;\n      }\n    }\n    if (!any) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * Merges a batch's rows into an ordered base stream and drops the base rows\n * the batch overrides.\n *\n * Both streams must already be in `compare` order. A delta row that ties with\n * a base row is the *same* row by primary key -- every fetch ordering includes\n * the primary key -- so the base copy is suppressed and the delta's value\n * takes its place at that position.\n */\nexport function* generateWithPendingDelta(\n  baseRows: Iterable<Row>,\n  deltaRows: Iterable<Row>,\n  delta: PendingDelta,\n  compare: Comparator,\n): IterableIterator<Row> {\n  const deltaIter = deltaRows[Symbol.iterator]();\n  let pending = deltaIter.next();\n  try {\n    for (const row of baseRows) {\n      while (!pending.done && compare(pending.value, row) < 0) {\n        yield pending.value;\n        pending = deltaIter.next();\n      }\n      if (!delta.overrides(row)) {\n        yield row;\n      }\n    }\n    while (!pending.done) {\n      yield pending.value;\n      pending = deltaIter.next();\n    }\n  } finally {\n    // Propagate early termination so the delta iterator can release the BTree\n    // cursor it is walking, the same contract `mergeSortedStreams` documents.\n    if (!pending.done) {\n      deltaIter.return?.(undefined);\n    }\n  }\n}\n\n/**\n * The unordered counterpart. Nothing downstream depends on position, so the\n * surviving base rows are emitted first and the batch's rows follow.\n */\nexport function* generateWithPendingDeltaUnordered(\n  baseRows: Iterable<Row>,\n  deltaRows: Iterable<Row>,\n  delta: PendingDelta,\n): IterableIterator<Row> {\n  for (const row of baseRows) {\n    if (!delta.overrides(row)) {\n      yield row;\n    }\n  }\n  yield* deltaRows;\n}\n"],"mappings":"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"}

package/out/zqlite/src/query-delegate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-delegate.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/query-delegate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,+BAA+B,CAAC;AAE7D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,gCAAgC,CAAC;AAC3D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAC,iBAAiB,EAAC,MAAM,4CAA4C,CAAC;AAC7E,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAGtC,qBAAa,iBAAkB,SAAQ,iBAAiB;;IAMtD,QAAQ,CAAC,oBAAoB,QAAQ;IAGrC,YACE,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,SAAS,EAatB;IAED,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAYnC;IAED,mBAAmB,CAAC,EAAE,EAAE,cAAc,cAKrC;IACQ,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAMzD;CACF"}
+{"version":3,"file":"query-delegate.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/query-delegate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,+BAA+B,CAAC;AAE7D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,gCAAgC,CAAC;AAC3D,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAC,iBAAiB,EAAC,MAAM,4CAA4C,CAAC;AAC7E,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAGtC,qBAAa,iBAAkB,SAAQ,iBAAiB;;IAMtD,QAAQ,CAAC,oBAAoB,QAAQ;IAGrC,YACE,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,SAAS,EAiBtB;IAED,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAYnC;IAED,mBAAmB,CAAC,EAAE,EAAE,cAAc,cAKrC;IACQ,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAMzD;CACF"}

package/out/zqlite/src/query-delegate.js

@@ -20,7 +20,11 @@ var QueryDelegateImpl = class extends QueryDelegateBase {
 			ivmSampling: 0,
 			level: "info",
 			slowHydrateThreshold: 0,
-			slowRowThreshold: 0
+			slowAdvanceThreshold: 0,
+			queryStatsIntervalSeconds: 0,
+			slowRowThreshold: 0,
+			planWarningRowThreshold: 0,
+			planWarningCostThreshold: 0
 		};
 	}
 	getSource(tableName) {

package/out/zqlite/src/query-delegate.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-delegate.js","names":["#lc","#db","#schema","#sources","#logConfig","#commitObservers"],"sources":["../../../../zqlite/src/query-delegate.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type {LogConfig} from '../../otel/src/log-options.ts';\nimport {getOrInsertComputed} from '../../shared/src/map.ts';\nimport type {Schema} from '../../zero-types/src/schema.ts';\nimport type {Source} from '../../zql/src/ivm/source.ts';\nimport {QueryDelegateBase} from '../../zql/src/query/query-delegate-base.ts';\nimport type {CommitListener} from '../../zql/src/query/query-delegate.ts';\nimport type {Database} from './db.ts';\nimport {TableSource} from './table-source.ts';\n\nexport class QueryDelegateImpl extends QueryDelegateBase {\n  readonly #lc: LogContext;\n  readonly #db: Database;\n  readonly #schema: Schema;\n  readonly #sources: Map<string, Source> = new Map();\n  readonly #logConfig: LogConfig;\n  readonly defaultQueryComplete = true;\n  readonly #commitObservers = new Set<() => void>();\n\n  constructor(\n    lc: LogContext,\n    db: Database,\n    schema: Schema,\n    logConfig?: LogConfig,\n  ) {\n    super();\n    this.#lc = lc.withContext('class', 'QueryDelegateImpl');\n    this.#db = db;\n    this.#schema = schema;\n    this.#logConfig = logConfig ?? {\n      format: 'text',\n      ivmSampling: 0,\n      level: 'info',\n      slowHydrateThreshold: 0,\n      slowRowThreshold: 0,\n    };\n  }\n\n  getSource(tableName: string): Source {\n    return getOrInsertComputed(this.#sources, tableName, tableName => {\n      const tableSchema = this.#schema.tables[tableName];\n      return new TableSource(\n        this.#lc,\n        this.#logConfig,\n        this.#db,\n        tableName,\n        tableSchema.columns,\n        tableSchema.primaryKey,\n      );\n    });\n  }\n\n  onTransactionCommit(cb: CommitListener) {\n    this.#commitObservers.add(cb);\n    return () => {\n      this.#commitObservers.delete(cb);\n    };\n  }\n  override batchViewUpdates<T>(applyViewUpdates: () => T): T {\n    const ret = applyViewUpdates();\n    for (const observer of this.#commitObservers) {\n      observer();\n    }\n    return ret;\n  }\n}\n"],"mappings":";;;;AAUA,IAAa,oBAAb,cAAuC,kBAAkB;CACvD;CACA;CACA;CACA,2BAAyC,IAAI,IAAI;CACjD;CACA,uBAAgC;CAChC,mCAA4B,IAAI,IAAgB;CAEhD,YACE,IACA,IACA,QACA,WACA;EACA,MAAM;EACN,KAAKA,MAAM,GAAG,YAAY,SAAS,mBAAmB;EACtD,KAAKC,MAAM;EACX,KAAKC,UAAU;EACf,KAAKE,aAAa,aAAa;GAC7B,QAAQ;GACR,aAAa;GACb,OAAO;GACP,sBAAsB;GACtB,kBAAkB;EACpB;CACF;CAEA,UAAU,WAA2B;EACnC,OAAO,oBAAoB,KAAKD,UAAU,YAAW,cAAa;GAChE,MAAM,cAAc,KAAKD,QAAQ,OAAO;GACxC,OAAO,IAAI,YACT,KAAKF,KACL,KAAKI,YACL,KAAKH,KACL,WACA,YAAY,SACZ,YAAY,UACd;EACF,CAAC;CACH;CAEA,oBAAoB,IAAoB;EACtC,KAAKI,iBAAiB,IAAI,EAAE;EAC5B,aAAa;GACX,KAAKA,iBAAiB,OAAO,EAAE;EACjC;CACF;CACA,iBAA6B,kBAA8B;EACzD,MAAM,MAAM,iBAAiB;EAC7B,KAAK,MAAM,YAAY,KAAKA,kBAC1B,SAAS;EAEX,OAAO;CACT;AACF"}
+{"version":3,"file":"query-delegate.js","names":["#lc","#db","#schema","#sources","#logConfig","#commitObservers"],"sources":["../../../../zqlite/src/query-delegate.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport type {LogConfig} from '../../otel/src/log-options.ts';\nimport {getOrInsertComputed} from '../../shared/src/map.ts';\nimport type {Schema} from '../../zero-types/src/schema.ts';\nimport type {Source} from '../../zql/src/ivm/source.ts';\nimport {QueryDelegateBase} from '../../zql/src/query/query-delegate-base.ts';\nimport type {CommitListener} from '../../zql/src/query/query-delegate.ts';\nimport type {Database} from './db.ts';\nimport {TableSource} from './table-source.ts';\n\nexport class QueryDelegateImpl extends QueryDelegateBase {\n  readonly #lc: LogContext;\n  readonly #db: Database;\n  readonly #schema: Schema;\n  readonly #sources: Map<string, Source> = new Map();\n  readonly #logConfig: LogConfig;\n  readonly defaultQueryComplete = true;\n  readonly #commitObservers = new Set<() => void>();\n\n  constructor(\n    lc: LogContext,\n    db: Database,\n    schema: Schema,\n    logConfig?: LogConfig,\n  ) {\n    super();\n    this.#lc = lc.withContext('class', 'QueryDelegateImpl');\n    this.#db = db;\n    this.#schema = schema;\n    this.#logConfig = logConfig ?? {\n      format: 'text',\n      ivmSampling: 0,\n      level: 'info',\n      slowHydrateThreshold: 0,\n      slowAdvanceThreshold: 0,\n      queryStatsIntervalSeconds: 0,\n      slowRowThreshold: 0,\n      planWarningRowThreshold: 0,\n      planWarningCostThreshold: 0,\n    };\n  }\n\n  getSource(tableName: string): Source {\n    return getOrInsertComputed(this.#sources, tableName, tableName => {\n      const tableSchema = this.#schema.tables[tableName];\n      return new TableSource(\n        this.#lc,\n        this.#logConfig,\n        this.#db,\n        tableName,\n        tableSchema.columns,\n        tableSchema.primaryKey,\n      );\n    });\n  }\n\n  onTransactionCommit(cb: CommitListener) {\n    this.#commitObservers.add(cb);\n    return () => {\n      this.#commitObservers.delete(cb);\n    };\n  }\n  override batchViewUpdates<T>(applyViewUpdates: () => T): T {\n    const ret = applyViewUpdates();\n    for (const observer of this.#commitObservers) {\n      observer();\n    }\n    return ret;\n  }\n}\n"],"mappings":";;;;AAUA,IAAa,oBAAb,cAAuC,kBAAkB;CACvD;CACA;CACA;CACA,2BAAyC,IAAI,IAAI;CACjD;CACA,uBAAgC;CAChC,mCAA4B,IAAI,IAAgB;CAEhD,YACE,IACA,IACA,QACA,WACA;EACA,MAAM;EACN,KAAKA,MAAM,GAAG,YAAY,SAAS,mBAAmB;EACtD,KAAKC,MAAM;EACX,KAAKC,UAAU;EACf,KAAKE,aAAa,aAAa;GAC7B,QAAQ;GACR,aAAa;GACb,OAAO;GACP,sBAAsB;GACtB,sBAAsB;GACtB,2BAA2B;GAC3B,kBAAkB;GAClB,yBAAyB;GACzB,0BAA0B;EAC5B;CACF;CAEA,UAAU,WAA2B;EACnC,OAAO,oBAAoB,KAAKD,UAAU,YAAW,cAAa;GAChE,MAAM,cAAc,KAAKD,QAAQ,OAAO;GACxC,OAAO,IAAI,YACT,KAAKF,KACL,KAAKI,YACL,KAAKH,KACL,WACA,YAAY,SACZ,YAAY,UACd;EACF,CAAC;CACH;CAEA,oBAAoB,IAAoB;EACtC,KAAKI,iBAAiB,IAAI,EAAE;EAC5B,aAAa;GACX,KAAKA,iBAAiB,OAAO,EAAE;EACjC;CACF;CACA,iBAA6B,kBAA8B;EACzD,MAAM,MAAM,iBAAiB;EAC7B,KAAK,MAAM,YAAY,KAAKA,kBAC1B,SAAS;EAEX,OAAO;CACT;AACF"}

package/out/zqlite/src/sqlite-cost-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-cost-model.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/sqlite-cost-model.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,sCAAsC,CAAC;AAEtE,OAAO,KAAK,EACV,mBAAmB,EAEpB,MAAM,6CAA6C,CAAC;AAErD,OAAO,KAAK,EAAC,QAAQ,EAAY,MAAM,SAAS,CAAC;AAmBjD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAC,CAAC,GAC9D,mBAAmB,CA+DrB;AAmFD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9C"}
+{"version":3,"file":"sqlite-cost-model.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/sqlite-cost-model.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,sCAAsC,CAAC;AAEtE,OAAO,KAAK,EAEV,mBAAmB,EAEpB,MAAM,6CAA6C,CAAC;AAErD,OAAO,KAAK,EAAC,QAAQ,EAAY,MAAM,SAAS,CAAC;AAmBjD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAAC,CAAC,GAC9D,mBAAmB,CAgErB;AAqJD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9C"}

package/out/zqlite/src/sqlite-cost-model.js

@@ -17,13 +17,64 @@ import SQLite3Database from "@rocicorp/zero-sqlite3";
 */
 function createSQLiteCostModel(db, tableSpecs) {
 	const fanoutEstimator = new SQLiteStatFanout(db);
+	const tableRows = tableRowsReader(db);
 	return (tableName, sort, filters, constraint) => {
 		const noSubqueryFilters = transformFilters(filters).filters;
 		const { zqlSpec } = must(tableSpecs.get(tableName));
 		const sql = compileInline(buildSelectQuery(tableName, zqlSpec, constraint, noSubqueryFilters, sort, void 0, void 0));
 		const loops = getScanstatusLoops(db.prepare(sql));
 		assert(loops.length > 0, `Expected scanstatus to return at least one loop for query: ${sql}`);
-		return estimateCost(loops, (columns) => fanoutEstimator.getFanout(tableName, columns));
+		return {
+			...estimateCost(loops, (columns) => fanoutEstimator.getFanout(tableName, columns)),
+			plan: accessPlan(loops, tableRows(tableName))
+		};
+	};
+}
+/**
+* Returns a function that reads the number of rows in a table from
+* `sqlite_stat1`, or `undefined` if the table has not been analyzed.
+*
+* The counts are cached: they only feed plan warnings, for which the count
+* as of the first plan is close enough.
+*/
+function tableRowsReader(db) {
+	let stmt;
+	const read = (table) => {
+		try {
+			stmt ??= db.prepare("SELECT stat FROM sqlite_stat1 WHERE tbl = ? LIMIT 1");
+			const row = stmt.get(table);
+			const rows = row ? parseInt(row.stat, 10) : NaN;
+			return Number.isNaN(rows) ? void 0 : rows;
+		} catch {
+			return;
+		}
+	};
+	const cache = /* @__PURE__ */ new Map();
+	return (table) => {
+		if (!cache.has(table)) cache.set(table, read(table));
+		return cache.get(table);
+	};
+}
+/**
+* Describes how SQLite reads the rows, from the EXPLAIN text of the
+* statement's top-level loops, e.g.:
+*
+* - `SEARCH issue USING INDEX issue_project (projectID=?)`
+* - `SCAN comment USING INDEX sqlite_autoindex_comment_1` (every row, in the
+*   order of the index)
+* - `SCAN issue` (every row, in table order)
+* - `USE TEMP B-TREE FOR ORDER BY` (a full sort)
+* - `USE TEMP B-TREE FOR LAST TERM OF ORDER BY` or `... RIGHT PART OF ORDER
+*   BY` (sorting runs of rows that tie on the index)
+*/
+function accessPlan(loops, tableRows) {
+	const [first, ...rest] = loops.filter((loop) => loop.parentId === 0);
+	let sort = "none";
+	for (const { explain } of rest) if (explain.startsWith("USE TEMP B-TREE FOR") && explain.includes("ORDER BY")) sort = explain === "USE TEMP B-TREE FOR ORDER BY" ? "full" : "partial";
+	return {
+		access: first?.explain.startsWith("SCAN ") ? "scan" : "search",
+		sort,
+		tableRows
 	};
 }
 /**

package/out/zqlite/src/sqlite-cost-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-cost-model.js","names":[],"sources":["../../../../zqlite/src/sqlite-cost-model.ts"],"sourcesContent":["import SQLite3Database from '@rocicorp/zero-sqlite3';\nimport {assert} from '../../shared/src/asserts.ts';\nimport {must} from '../../shared/src/must.ts';\nimport type {Condition, Ordering} from '../../zero-protocol/src/ast.ts';\nimport type {SchemaValue} from '../../zero-types/src/schema-value.ts';\nimport {transformFilters} from '../../zql/src/builder/filter.ts';\nimport type {\n  ConnectionCostModel,\n  CostModelCost,\n} from '../../zql/src/planner/planner-connection.ts';\nimport type {PlannerConstraint} from '../../zql/src/planner/planner-constraint.ts';\nimport type {Database, Statement} from './db.ts';\nimport {compileInline} from './internal/sql-inline.ts';\nimport {buildSelectQuery} from './query-builder.ts';\nimport {SQLiteStatFanout} from './sqlite-stat-fanout.ts';\n\n/**\n * Loop information returned by SQLite's scanstatus API.\n */\ninterface ScanstatusLoop {\n  /** Unique identifier for this loop */\n  selectId: number;\n  /** Parent loop ID, or 0 for root loops */\n  parentId: number;\n  /** Estimated rows emitted per turn of parent loop */\n  est: number;\n  /** EXPLAIN text for this loop to determine: b-tree vs list subquery */\n  explain: string;\n}\n\n/**\n * Creates a SQLite-based cost model for query planning.\n * Uses SQLite's scanstatus API to estimate query costs based on the actual\n * SQLite query planner's analysis.\n *\n * @param db Database instance for preparing statements\n * @param tableSpecs Map of table names to their table specs with ZQL schemas\n * @returns ConnectionCostModel function for use with the planner\n */\nexport function createSQLiteCostModel(\n  db: Database,\n  tableSpecs: Map<string, {zqlSpec: Record<string, SchemaValue>}>,\n): ConnectionCostModel {\n  const fanoutEstimator = new SQLiteStatFanout(db);\n  return (\n    tableName: string,\n    sort: Ordering,\n    filters: Condition | undefined,\n    constraint: PlannerConstraint | undefined,\n  ): CostModelCost => {\n    // Transform filters to remove correlated subqueries.\n    //\n    // We use `transformFilters` (the same function the runtime uses to\n    // decide what to push to the source at connection time). It returns:\n    // - For AND: the non-CSQ conjuncts (a *superset* of the original).\n    // - For OR with any CSQ branch: `undefined` (the OR-with-CSQ is not\n    //   pushable, and matches a strict superset of any single branch).\n    //\n    // This matches what the runtime actually applies at the source. A\n    // previous implementation here had wrong OR semantics — it dropped the\n    // CSQ branch and returned the simple branch alone, which is a strict\n    // *subset* of the original OR's match set, causing the cost model to\n    // under-estimate scan rows for OR-with-CSQ shapes and biasing the\n    // planner toward semi-join plans. See the comment in\n    // `packages/zql/src/builder/filter.ts:transformFilters`.\n    const noSubqueryFilters = transformFilters(filters).filters;\n\n    // Build the SQL query using the same logic as actual queries\n    const {zqlSpec} = must(tableSpecs.get(tableName));\n\n    const query = buildSelectQuery(\n      tableName,\n      zqlSpec,\n      constraint,\n      noSubqueryFilters,\n      sort,\n      undefined, // reverse is undefined here\n      undefined, // start is undefined here\n    );\n\n    // Use compileInline to inline actual values into the SQL for cost estimation.\n    // This allows SQLite's query planner to see real values and make better decisions\n    // about index usage and query plans. This is safe here because it's only used for\n    // cost estimation, not for executing user-facing queries (which use parameterized\n    // queries via the standard compile() function).\n    const sql = compileInline(query);\n\n    // Prepare statement to get scanstatus information\n    const stmt = db.prepare(sql);\n\n    // Get scanstatus loops from the prepared statement\n    const loops = getScanstatusLoops(stmt);\n\n    // Scanstatus should always be available - if we get no loops, something is wrong\n    assert(\n      loops.length > 0,\n      `Expected scanstatus to return at least one loop for query: ${sql}`,\n    );\n\n    const ret = estimateCost(loops, (columns: string[]) =>\n      fanoutEstimator.getFanout(tableName, columns),\n    );\n\n    return ret;\n  };\n}\n\n/**\n * Gets scanstatus loop information from a prepared statement.\n * Iterates through all query elements and extracts loop statistics.\n *\n * Uses SQLITE_SCANSTAT_COMPLEX flag (1) to get all loops including sorting operations.\n *\n * @param stmt Prepared statement to get scanstatus from\n * @returns Array of loop information, or empty array if scanstatus unavailable\n */\nfunction getScanstatusLoops(stmt: Statement): ScanstatusLoop[] {\n  const loops: ScanstatusLoop[] = [];\n\n  // Iterate through query elements by incrementing idx until we get undefined\n  // which indicates we've reached the end\n  for (let idx = 0; ; idx++) {\n    const selectId = stmt.scanStatus(\n      idx,\n      SQLite3Database.SQLITE_SCANSTAT_SELECTID,\n      1,\n    );\n\n    if (selectId === undefined) {\n      break;\n    }\n\n    loops.push({\n      selectId: must(selectId),\n      parentId: must(\n        stmt.scanStatus(idx, SQLite3Database.SQLITE_SCANSTAT_PARENTID, 1),\n      ),\n      explain: must(\n        stmt.scanStatus(idx, SQLite3Database.SQLITE_SCANSTAT_EXPLAIN, 1),\n      ),\n      est: must(stmt.scanStatus(idx, SQLite3Database.SQLITE_SCANSTAT_EST, 1)),\n    });\n  }\n\n  return loops.sort((a, b) => a.selectId - b.selectId);\n}\n\n/**\n * Estimates the cost of a query based on scanstats from sqlite3_stmt_scanstatus_v2\n */\nfunction estimateCost(\n  scanstats: ScanstatusLoop[],\n  fanout: CostModelCost['fanout'],\n): CostModelCost {\n  // Sort by selectId to process in execution order\n  const sorted = scanstats.toSorted((a, b) => a.selectId - b.selectId);\n\n  let totalRows = 0;\n  let totalCost = 0;\n\n  // Identify if there are multiple top-level (parentId=0) operations\n  // If so, the first is typically the scan, and subsequent ones are sorts\n  const topLevelOps = sorted.filter(s => s.parentId === 0);\n\n  // We only consider top level ops since ZQL queries are single-table when hitting SQLite.\n  // We do have a nested op in the case of `WHERE x IN (:arg)` but it is negligible\n  // assuming :arg is small.\n  let firstLoop = true;\n  for (const op of topLevelOps) {\n    if (firstLoop) {\n      // First top-level op is the main scan\n      // and determines the total number of rows output.\n      totalRows = op.est;\n      firstLoop = false;\n    } else {\n      if (op.explain.includes('ORDER BY')) {\n        totalCost += btreeCost(totalRows);\n      }\n    }\n  }\n\n  return {\n    rows: totalRows,\n    startupCost: totalCost,\n    fanout,\n  };\n}\n\nexport function btreeCost(rows: number): number {\n  // B-Tree construction is ~O(n log n) so we estimate the cost as such.\n  // We divide the cost by 10 because sorting in SQLite is ~10x faster\n  // than bringing the data into JS and sorting there.\n  return (rows * Math.log2(rows)) / 10;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAuCA,SAAgB,sBACd,IACA,YACqB;CACrB,MAAM,kBAAkB,IAAI,iBAAiB,EAAE;CAC/C,QACE,WACA,MACA,SACA,eACkB;EAgBlB,MAAM,oBAAoB,iBAAiB,OAAO,EAAE;EAGpD,MAAM,EAAC,YAAW,KAAK,WAAW,IAAI,SAAS,CAAC;EAiBhD,MAAM,MAAM,cAfE,iBACZ,WACA,SACA,YACA,mBACA,MACA,KAAA,GACA,KAAA,CAQwB,CAAK;EAM/B,MAAM,QAAQ,mBAHD,GAAG,QAAQ,GAGS,CAAI;EAGrC,OACE,MAAM,SAAS,GACf,8DAA8D,KAChE;EAMA,OAJY,aAAa,QAAQ,YAC/B,gBAAgB,UAAU,WAAW,OAAO,CAGvC;CACT;AACF;;;;;;;;;;AAWA,SAAS,mBAAmB,MAAmC;CAC7D,MAAM,QAA0B,CAAC;CAIjC,KAAK,IAAI,MAAM,IAAK,OAAO;EACzB,MAAM,WAAW,KAAK,WACpB,KACA,gBAAgB,0BAChB,CACF;EAEA,IAAI,aAAa,KAAA,GACf;EAGF,MAAM,KAAK;GACT,UAAU,KAAK,QAAQ;GACvB,UAAU,KACR,KAAK,WAAW,KAAK,gBAAgB,0BAA0B,CAAC,CAClE;GACA,SAAS,KACP,KAAK,WAAW,KAAK,gBAAgB,yBAAyB,CAAC,CACjE;GACA,KAAK,KAAK,KAAK,WAAW,KAAK,gBAAgB,qBAAqB,CAAC,CAAC;EACxE,CAAC;CACH;CAEA,OAAO,MAAM,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ;AACrD;;;;AAKA,SAAS,aACP,WACA,QACe;CAEf,MAAM,SAAS,UAAU,UAAU,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ;CAEnE,IAAI,YAAY;CAChB,IAAI,YAAY;CAIhB,MAAM,cAAc,OAAO,QAAO,MAAK,EAAE,aAAa,CAAC;CAKvD,IAAI,YAAY;CAChB,KAAK,MAAM,MAAM,aACf,IAAI,WAAW;EAGb,YAAY,GAAG;EACf,YAAY;CACd,OACE,IAAI,GAAG,QAAQ,SAAS,UAAU,GAChC,aAAa,UAAU,SAAS;CAKtC,OAAO;EACL,MAAM;EACN,aAAa;EACb;CACF;AACF;AAEA,SAAgB,UAAU,MAAsB;CAI9C,OAAQ,OAAO,KAAK,KAAK,IAAI,IAAK;AACpC"}
+{"version":3,"file":"sqlite-cost-model.js","names":[],"sources":["../../../../zqlite/src/sqlite-cost-model.ts"],"sourcesContent":["import SQLite3Database from '@rocicorp/zero-sqlite3';\nimport {assert} from '../../shared/src/asserts.ts';\nimport {must} from '../../shared/src/must.ts';\nimport type {Condition, Ordering} from '../../zero-protocol/src/ast.ts';\nimport type {SchemaValue} from '../../zero-types/src/schema-value.ts';\nimport {transformFilters} from '../../zql/src/builder/filter.ts';\nimport type {\n  AccessPlan,\n  ConnectionCostModel,\n  CostModelCost,\n} from '../../zql/src/planner/planner-connection.ts';\nimport type {PlannerConstraint} from '../../zql/src/planner/planner-constraint.ts';\nimport type {Database, Statement} from './db.ts';\nimport {compileInline} from './internal/sql-inline.ts';\nimport {buildSelectQuery} from './query-builder.ts';\nimport {SQLiteStatFanout} from './sqlite-stat-fanout.ts';\n\n/**\n * Loop information returned by SQLite's scanstatus API.\n */\ninterface ScanstatusLoop {\n  /** Unique identifier for this loop */\n  selectId: number;\n  /** Parent loop ID, or 0 for root loops */\n  parentId: number;\n  /** Estimated rows emitted per turn of parent loop */\n  est: number;\n  /** EXPLAIN text for this loop to determine: b-tree vs list subquery */\n  explain: string;\n}\n\n/**\n * Creates a SQLite-based cost model for query planning.\n * Uses SQLite's scanstatus API to estimate query costs based on the actual\n * SQLite query planner's analysis.\n *\n * @param db Database instance for preparing statements\n * @param tableSpecs Map of table names to their table specs with ZQL schemas\n * @returns ConnectionCostModel function for use with the planner\n */\nexport function createSQLiteCostModel(\n  db: Database,\n  tableSpecs: Map<string, {zqlSpec: Record<string, SchemaValue>}>,\n): ConnectionCostModel {\n  const fanoutEstimator = new SQLiteStatFanout(db);\n  const tableRows = tableRowsReader(db);\n  return (\n    tableName: string,\n    sort: Ordering,\n    filters: Condition | undefined,\n    constraint: PlannerConstraint | undefined,\n  ): CostModelCost => {\n    // Transform filters to remove correlated subqueries.\n    //\n    // We use `transformFilters` (the same function the runtime uses to\n    // decide what to push to the source at connection time). It returns:\n    // - For AND: the non-CSQ conjuncts (a *superset* of the original).\n    // - For OR with any CSQ branch: `undefined` (the OR-with-CSQ is not\n    //   pushable, and matches a strict superset of any single branch).\n    //\n    // This matches what the runtime actually applies at the source. A\n    // previous implementation here had wrong OR semantics — it dropped the\n    // CSQ branch and returned the simple branch alone, which is a strict\n    // *subset* of the original OR's match set, causing the cost model to\n    // under-estimate scan rows for OR-with-CSQ shapes and biasing the\n    // planner toward semi-join plans. See the comment in\n    // `packages/zql/src/builder/filter.ts:transformFilters`.\n    const noSubqueryFilters = transformFilters(filters).filters;\n\n    // Build the SQL query using the same logic as actual queries\n    const {zqlSpec} = must(tableSpecs.get(tableName));\n\n    const query = buildSelectQuery(\n      tableName,\n      zqlSpec,\n      constraint,\n      noSubqueryFilters,\n      sort,\n      undefined, // reverse is undefined here\n      undefined, // start is undefined here\n    );\n\n    // Use compileInline to inline actual values into the SQL for cost estimation.\n    // This allows SQLite's query planner to see real values and make better decisions\n    // about index usage and query plans. This is safe here because it's only used for\n    // cost estimation, not for executing user-facing queries (which use parameterized\n    // queries via the standard compile() function).\n    const sql = compileInline(query);\n\n    // Prepare statement to get scanstatus information\n    const stmt = db.prepare(sql);\n\n    // Get scanstatus loops from the prepared statement\n    const loops = getScanstatusLoops(stmt);\n\n    // Scanstatus should always be available - if we get no loops, something is wrong\n    assert(\n      loops.length > 0,\n      `Expected scanstatus to return at least one loop for query: ${sql}`,\n    );\n\n    const ret = estimateCost(loops, (columns: string[]) =>\n      fanoutEstimator.getFanout(tableName, columns),\n    );\n\n    return {...ret, plan: accessPlan(loops, tableRows(tableName))};\n  };\n}\n\n/**\n * Returns a function that reads the number of rows in a table from\n * `sqlite_stat1`, or `undefined` if the table has not been analyzed.\n *\n * The counts are cached: they only feed plan warnings, for which the count\n * as of the first plan is close enough.\n */\nfunction tableRowsReader(db: Database): (table: string) => number | undefined {\n  let stmt: Statement | undefined;\n  const read = (table: string): number | undefined => {\n    try {\n      stmt ??= db.prepare(\n        'SELECT stat FROM sqlite_stat1 WHERE tbl = ? LIMIT 1',\n      );\n      // Every row for a table starts with the number of rows in the table.\n      const row = stmt.get<{stat: string} | undefined>(table);\n      const rows = row ? parseInt(row.stat, 10) : NaN;\n      return Number.isNaN(rows) ? undefined : rows;\n    } catch {\n      // sqlite_stat1 does not exist until the database is analyzed.\n      return undefined;\n    }\n  };\n  // Tables without statistics are cached too, as `undefined`.\n  const cache = new Map<string, number | undefined>();\n  return table => {\n    if (!cache.has(table)) {\n      cache.set(table, read(table));\n    }\n    return cache.get(table);\n  };\n}\n\n/**\n * Describes how SQLite reads the rows, from the EXPLAIN text of the\n * statement's top-level loops, e.g.:\n *\n * - `SEARCH issue USING INDEX issue_project (projectID=?)`\n * - `SCAN comment USING INDEX sqlite_autoindex_comment_1` (every row, in the\n *   order of the index)\n * - `SCAN issue` (every row, in table order)\n * - `USE TEMP B-TREE FOR ORDER BY` (a full sort)\n * - `USE TEMP B-TREE FOR LAST TERM OF ORDER BY` or `... RIGHT PART OF ORDER\n *   BY` (sorting runs of rows that tie on the index)\n */\nfunction accessPlan(\n  loops: ScanstatusLoop[],\n  tableRows: number | undefined,\n): AccessPlan {\n  const [first, ...rest] = loops.filter(loop => loop.parentId === 0);\n  let sort: AccessPlan['sort'] = 'none';\n  for (const {explain} of rest) {\n    if (\n      explain.startsWith('USE TEMP B-TREE FOR') &&\n      explain.includes('ORDER BY')\n    ) {\n      sort = explain === 'USE TEMP B-TREE FOR ORDER BY' ? 'full' : 'partial';\n    }\n  }\n  return {\n    access: first?.explain.startsWith('SCAN ') ? 'scan' : 'search',\n    sort,\n    tableRows,\n  };\n}\n\n/**\n * Gets scanstatus loop information from a prepared statement.\n * Iterates through all query elements and extracts loop statistics.\n *\n * Uses SQLITE_SCANSTAT_COMPLEX flag (1) to get all loops including sorting operations.\n *\n * @param stmt Prepared statement to get scanstatus from\n * @returns Array of loop information, or empty array if scanstatus unavailable\n */\nfunction getScanstatusLoops(stmt: Statement): ScanstatusLoop[] {\n  const loops: ScanstatusLoop[] = [];\n\n  // Iterate through query elements by incrementing idx until we get undefined\n  // which indicates we've reached the end\n  for (let idx = 0; ; idx++) {\n    const selectId = stmt.scanStatus(\n      idx,\n      SQLite3Database.SQLITE_SCANSTAT_SELECTID,\n      1,\n    );\n\n    if (selectId === undefined) {\n      break;\n    }\n\n    loops.push({\n      selectId: must(selectId),\n      parentId: must(\n        stmt.scanStatus(idx, SQLite3Database.SQLITE_SCANSTAT_PARENTID, 1),\n      ),\n      explain: must(\n        stmt.scanStatus(idx, SQLite3Database.SQLITE_SCANSTAT_EXPLAIN, 1),\n      ),\n      est: must(stmt.scanStatus(idx, SQLite3Database.SQLITE_SCANSTAT_EST, 1)),\n    });\n  }\n\n  return loops.sort((a, b) => a.selectId - b.selectId);\n}\n\n/**\n * Estimates the cost of a query based on scanstats from sqlite3_stmt_scanstatus_v2\n */\nfunction estimateCost(\n  scanstats: ScanstatusLoop[],\n  fanout: CostModelCost['fanout'],\n): CostModelCost {\n  // Sort by selectId to process in execution order\n  const sorted = scanstats.toSorted((a, b) => a.selectId - b.selectId);\n\n  let totalRows = 0;\n  let totalCost = 0;\n\n  // Identify if there are multiple top-level (parentId=0) operations\n  // If so, the first is typically the scan, and subsequent ones are sorts\n  const topLevelOps = sorted.filter(s => s.parentId === 0);\n\n  // We only consider top level ops since ZQL queries are single-table when hitting SQLite.\n  // We do have a nested op in the case of `WHERE x IN (:arg)` but it is negligible\n  // assuming :arg is small.\n  let firstLoop = true;\n  for (const op of topLevelOps) {\n    if (firstLoop) {\n      // First top-level op is the main scan\n      // and determines the total number of rows output.\n      totalRows = op.est;\n      firstLoop = false;\n    } else {\n      if (op.explain.includes('ORDER BY')) {\n        totalCost += btreeCost(totalRows);\n      }\n    }\n  }\n\n  return {\n    rows: totalRows,\n    startupCost: totalCost,\n    fanout,\n  };\n}\n\nexport function btreeCost(rows: number): number {\n  // B-Tree construction is ~O(n log n) so we estimate the cost as such.\n  // We divide the cost by 10 because sorting in SQLite is ~10x faster\n  // than bringing the data into JS and sorting there.\n  return (rows * Math.log2(rows)) / 10;\n}\n"],"mappings":"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"}

package/out/zqlite/src/sqlite-stat-fanout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-stat-fanout.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/sqlite-stat-fanout.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACvC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB;;IAkB3B;;;;;;;;OAQG;IACH,YAAY,EAAE,EAAE,QAAQ,EAAE,aAAa,SAAI,EAyB1C;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY,CAgC5D;IAED;;;OAGG;IACH,UAAU,IAAI,IAAI,CAEjB;CAgQF"}
+{"version":3,"file":"sqlite-stat-fanout.d.ts","sourceRoot":"","sources":["../../../../zqlite/src/sqlite-stat-fanout.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAGtC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAEpC;;;;;OAKG;IACH,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACvC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,gBAAgB;;IAkB3B;;;;;;;;OAQG;IACH,YAAY,EAAE,EAAE,QAAQ,EAAE,aAAa,SAAI,EAyB1C;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,YAAY,CAgC5D;IAED;;;OAGG;IACH,UAAU,IAAI,IAAI,CAEjB;CA0NF"}