@quereus/quereus 4.22.0 → 4.23.0

package/dist/src/planner/stats/table-cardinality.js

@@ -1,13 +1,23 @@
 /**
  * The base-table row-count seam.
  *
- * Every planner reading of a base table's size goes through {@link plannedRowCount}:
- * the count observed during execution (the per-database overlay, see
- * `core/database-cardinality-feedback.ts`), else the catalog's count, else
- * `undefined`. `TableReferenceNode` (every scan's base cardinality, and the
+ * Every planner reading of a base table's size goes through {@link plannedRowCount},
+ * which ranks four sources (docs/progressive-optimizer.md §3.3): an exact count the
+ * table's module maintains (`VirtualTableModule.getRowCount`), the count observed
+ * during execution (the per-database overlay, see `core/database-cardinality-feedback.ts`),
+ * an approximate module count, the catalog's count — else `undefined`.
+ * `TableReferenceNode` (every scan's base cardinality, and the
  * `BestAccessPlanRequest.estimatedRows` hint) and `CatalogStatsProvider.tableRows`
- * (selectivity denominators, MV sizing) both call it, so scan cardinality and the
- * stats-provider estimate cannot drift apart within one plan.
+ * (selectivity denominators, MV sizing) both call it with the database's one
+ * {@link RowCountSources}, so scan cardinality and the stats-provider estimate cannot
+ * drift apart within one plan.
+ *
+ * The same sources carry the overlay's observed rows per key of an equality seek,
+ * read through {@link plannedRowsPerKey} by `IndexSeekNode` (what the seek advertises)
+ * and the index-nested-loop candidate (what one seek costs). That reader overrides only
+ * the engine's own consumers of a module's `rows` estimate; the module's cost, its
+ * `rows` and its access-path choice stay in the module's currency
+ * (docs/optimizer-costing.md § Where a module's own SELECTIVITY fits).
  *
  * There are exactly two spellings: `undefined` means "nobody knows" and a number —
  * including a real 0 — means "measured". `undefined` must stay `undefined` here:
@@ -15,16 +25,18 @@
  * folding a default in would change every un-analyzed table's cardinality.
  *
  * NOTE: the catalog `rowCount` is a snapshot from the last `ANALYZE` — rows written
- * afterwards are invisible until the next one (or until a complete scan is observed).
- *
- * NOTE: a real 0 (analyzed or observed empty table) is distinct from `undefined`,
- * but the `estimatedRows || default` spellings in `rule-select-access-path`,
- * `rule-grow-retrieve` and `IndexSeekNode.computePhysical` collapse the two and
- * substitute their default — so a measured empty table reaches `getBestAccessPlan`
- * as "unknown" (1000) while a SeqScan over it reports 0. Harmless today (any plan
- * over 0 rows is cheap); switch those to `??` if an empty-table plan ever costs out
- * wrong.
+ * afterwards are invisible until the next one (or until a complete scan is observed),
+ * unless the module reports its own count.
+ *
+ * A real 0 (analyzed or observed empty table) is relayed as 0 everywhere a row count is
+ * reported. Sites that turn a count into a COST floor a measured 0 at one row instead
+ * (`costedRows` in `planner/util/row-estimates.ts`; the store's request sizing floors
+ * its own): a zero goes stale on the first insert, and a table priced at nothing would
+ * trade its primary-key seeks for scans (docs/optimizer-costing.md § Base-table row
+ * estimates).
  */
+import { createLogger } from '../../common/logger.js';
+const debugLog = createLogger('optimizer:stats:row-count').extend('debug');
 /**
  * The catalog's row count — `TableSchema.statistics`, populated by `ANALYZE` or VTab
  * reporting.
@@ -37,21 +49,117 @@
 export function catalogRowCount(table) {
     return table.statistics?.rowCount;
 }
+/** The database's row-count sources: its observed overlay, and its tables' modules. */
+export function databaseRowCountSources(db, observed) {
+    return {
+        observedRows: table => observed.observedRows(table),
+        observedRowsPerKey: (table, columns) => observed.observedRowsPerKey(table, columns),
+        reportedRows: table => reportedRowCount(db, table),
+    };
+}
+/** True when `table`'s registered module implements `VirtualTableModule.getRowCount`, whether or not it answers now. */
+export function moduleReportsRowCount(db, table) {
+    return db.schemaManager.getModule(table.vtabModuleName)?.module.getRowCount !== undefined;
+}
+/**
+ * Asks `table`'s registered module for its count (`VirtualTableModule.getRowCount`).
+ * A hint, so a module without the hook, a throw, or a malformed answer (`rows` not a
+ * non-negative integer) is `undefined` — a failed hint must never fail planning.
+ */
+export function reportedRowCount(db, table) {
+    const module = db.schemaManager.getModule(table.vtabModuleName)?.module;
+    if (!module?.getRowCount)
+        return undefined;
+    let answer;
+    try {
+        answer = module.getRowCount(db, table);
+    }
+    catch (e) {
+        debugLog('Ignored row count for %s.%s: module %s threw %O', table.schemaName, table.name, table.vtabModuleName, e);
+        return undefined;
+    }
+    if (answer === undefined)
+        return undefined;
+    if (!Number.isInteger(answer.rows) || answer.rows < 0) {
+        debugLog('Ignored row count for %s.%s: module %s answered %o', table.schemaName, table.name, table.vtabModuleName, answer);
+        return undefined;
+    }
+    return answer;
+}
+/**
+ * The base-table row count the planner uses, first answer wins:
+ *
+ * 1. an exact module count — maintained on every write, so it is the truth now and any
+ *    snapshot below is older;
+ * 2. the overlay's observed count — an entry only answers for the exact `TableSchema`
+ *    it was observed under and any `ANALYZE` swaps that object, so it is newer than the
+ *    catalog numbers on the schema it names;
+ * 3. an approximate module count — below a measurement this session made, because an
+ *    estimate can be off by more than the overlay's shift factor and only a complete
+ *    scan can correct it; above the catalog, because it describes the table now;
+ * 4. the catalog (`ANALYZE`) count;
+ * 5. `undefined` (unknown).
+ *
+ * The overlay's floor then raises whatever answered from 2–4, and answers alone when
+ * nothing did (it was recorded only above the default). It never raises an exact module
+ * count: that is current, and a floor describes committed state at some earlier moment,
+ * so it cannot legitimately exceed it.
+ *
+ * The module is asked first so an exactly-sized table never touches the overlay, whose
+ * reads refresh its recency. Only the row count is overridden; column statistics are
+ * untouched.
+ *
+ * The result also becomes `BestAccessPlanRequest.estimatedRows`, so a module that reports
+ * its count prices its access path against the same number the rest of the plan uses —
+ * one size per plan.
+ */
+export function plannedRowCount(table, sources) {
+    const reported = sources?.reportedRows(table);
+    if (reported?.exact)
+        return reported.rows;
+    const observed = sources?.observedRows(table);
+    return raiseToFloor(observed?.rows ?? reported?.rows ?? catalogRowCount(table), observed?.atLeast);
+}
+function raiseToFloor(rows, floor) {
+    if (floor === undefined)
+        return rows;
+    return rows === undefined ? floor : Math.max(rows, floor);
+}
 /**
- * The base-table row count the planner uses: observed, else catalog (`ANALYZE`), else
- * `undefined` (unknown). The overlay wins because an entry only answers for the exact
- * `TableSchema` it was observed under and any `ANALYZE` swaps that object — an
- * answering entry is always newer than the catalog numbers on the schema it names.
- * Only the row count is overridden; column statistics are untouched.
- *
- * NOTE: accepted tradeoff — the result also becomes `BestAccessPlanRequest.estimatedRows`,
- * and a self-sizing module (`StoreModule.sizeRequestFromLiveCount`) honors a supplied
- * hint over its own running count, so between full scans it prices against the last
- * observed size instead of its live one; one size per plan weighed over the fresher
- * live count. Revisit when a module's live size reaches the planner
- * (`feat-planner-asks-the-backend-how-big-a-table-is`) — it should outrank the overlay.
+ * The rows per key the planner prices a single-key equality seek on `columns` at, or
+ * `undefined` to leave the module's own estimate standing (docs/progressive-optimizer.md
+ * §3.3):
+ *
+ * 1. when the catalog's statistics cover the column set — `table.statistics` with a
+ *    positive `rowCount` and a `columnStats` entry for every column — the catalog wins and
+ *    nothing is overridden: the module's statistics-backed estimate is the engine's own
+ *    `estimateLeaf` arithmetic over the same numbers, and the count rule (newest exact
+ *    wins) does not transfer to a mean sampled under some bindings and not others.
+ *    Coverage is all-or-nothing, the rule both shipped modules apply before mixing a
+ *    measured factor with a shape constant;
+ * 2. otherwise the overlay's mean for the set, rounded and floored at one row — the
+ *    module's `Math.max(1, …)` floor, so a key that matched nothing so far does not price a
+ *    seek at nothing;
+ * 3. otherwise `undefined`.
+ *
+ * NOTE: catalog-wins is a first rule, not a measured one; an `ANALYZE` snapshot can be
+ * older than the mean. Reconsider only against a measured case where the stale catalog
+ * loses a plan the mean would have won.
  */
-export function plannedRowCount(table, observed) {
-    return observed?.observedRows(table) ?? catalogRowCount(table);
+export function plannedRowsPerKey(table, columns, sources) {
+    if (sources === undefined || catalogCoversColumns(table, columns))
+        return undefined;
+    const mean = sources.observedRowsPerKey(table, columns);
+    return mean === undefined ? undefined : Math.max(1, Math.round(mean));
+}
+/** True when the catalog holds a usable row count and column statistics for every column in `columns`. */
+function catalogCoversColumns(table, columns) {
+    const stats = table.statistics;
+    if (!stats || stats.rowCount <= 0)
+        return false;
+    return columns.every(i => {
+        const name = table.columns[i]?.name;
+        return name !== undefined && stats.columnStats.has(name.toLowerCase());
+    });
 }
 //# sourceMappingURL=table-cardinality.js.map

package/dist/src/planner/stats/table-cardinality.js.map

@@ -1 +1 @@
-{"version":3,"file":"table-cardinality.js","sourceRoot":"","sources":["../../../../src/planner/stats/table-cardinality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IACjD,OAAO,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB,EAAE,QAAuC;IAC1F,OAAO,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"table-cardinality.js","sourceRoot":"","sources":["../../../../src/planner/stats/table-cardinality.ts"],"names":[],"mappings":"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"}

package/dist/src/planner/util/relative-rows.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A join side's row count for RELATIVE comparison — defined even where nobody
+ * measured anything.
+ *
+ * A never-analyzed table's scan reports `undefined` (see `row-estimates.ts`), and
+ * that blank propagates: a Filter over it, a join over that, an aggregate over the
+ * join all read `undefined` too, so a consumer that defaults the blank side flat
+ * forgets that a filter has already narrowed it. This walker instead starts the
+ * unknown LEAF at the shared no-statistics default and carries that figure up
+ * through each operator with the operator's own shared formula, so a filtered
+ * side of an unknown table compares smaller than the unfiltered table beside it.
+ *
+ * The figure is relative, not an estimate the plan records: only join selection
+ * reads it, to compare candidates against each other. Everywhere else an unknown
+ * stays `undefined`, so the gates that deliberately refuse on unknown keep
+ * refusing.
+ *
+ * Lives apart from `row-estimates.ts` because it dispatches on node classes, and
+ * those node modules import `row-estimates.ts`.
+ */
+import type { RelationalPlanNode } from '../nodes/plan-node.js';
+/**
+ * Rows `side` is priced at in a relative comparison: its physical estimate when
+ * known, else `unknownLeafRows` at each unknown leaf carried up through the
+ * side's operators. Floored at one row through `costedRows`, so a measured (or
+ * relayed) 0 prices the way every cost site prices it.
+ */
+export declare function relativeRows(side: RelationalPlanNode, unknownLeafRows: number): number;
+//# sourceMappingURL=relative-rows.d.ts.map

package/dist/src/planner/util/relative-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-rows.d.ts","sourceRoot":"","sources":["../../../../src/planner/util/relative-rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAWhE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAEtF"}

package/dist/src/planner/util/relative-rows.js

@@ -0,0 +1,67 @@
+/**
+ * A join side's row count for RELATIVE comparison — defined even where nobody
+ * measured anything.
+ *
+ * A never-analyzed table's scan reports `undefined` (see `row-estimates.ts`), and
+ * that blank propagates: a Filter over it, a join over that, an aggregate over the
+ * join all read `undefined` too, so a consumer that defaults the blank side flat
+ * forgets that a filter has already narrowed it. This walker instead starts the
+ * unknown LEAF at the shared no-statistics default and carries that figure up
+ * through each operator with the operator's own shared formula, so a filtered
+ * side of an unknown table compares smaller than the unfiltered table beside it.
+ *
+ * The figure is relative, not an estimate the plan records: only join selection
+ * reads it, to compare candidates against each other. Everywhere else an unknown
+ * stays `undefined`, so the gates that deliberately refuse on unknown keep
+ * refusing.
+ *
+ * Lives apart from `row-estimates.ts` because it dispatches on node classes, and
+ * those node modules import `row-estimates.ts`.
+ */
+import { DEFAULT_FILTER_SELECTIVITY, FilterNode } from '../nodes/filter.js';
+import { JoinNode } from '../nodes/join-node.js';
+import { BloomJoinNode } from '../nodes/bloom-join-node.js';
+import { MergeJoinNode } from '../nodes/merge-join-node.js';
+import { AggregateNode } from '../nodes/aggregate-node.js';
+import { HashAggregateNode } from '../nodes/hash-aggregate.js';
+import { StreamAggregateNode } from '../nodes/stream-aggregate.js';
+import { joinPhysicalRows } from '../nodes/join-utils.js';
+import { costedRows, filterRowsFrom, physicalSourceRows } from './row-estimates.js';
+/**
+ * Rows `side` is priced at in a relative comparison: its physical estimate when
+ * known, else `unknownLeafRows` at each unknown leaf carried up through the
+ * side's operators. Floored at one row through `costedRows`, so a measured (or
+ * relayed) 0 prices the way every cost site prices it.
+ */
+export function relativeRows(side, unknownLeafRows) {
+    return costedRows(relayedRows(side, unknownLeafRows), unknownLeafRows);
+}
+// NOTE: recursive, unlike the iterative `PlanNode.physical` fold — it descends only
+// through nodes with no known count, so depth is bounded by a side's unknown chain,
+// far below the ~30,000 frames that overflow (test/planner/plan-node-traversal.spec.ts).
+// If deep generated plans ever reach join selection with unknown leaves, convert to
+// a worklist walk (`PlanNode.computePostOrder`).
+function relayedRows(node, unknownLeafRows) {
+    const known = physicalSourceRows(node.physical, node);
+    if (known !== undefined)
+        return known;
+    if (node instanceof FilterNode) {
+        return filterRowsFrom(relayedRows(node.source, unknownLeafRows), node.selectivity ?? DEFAULT_FILTER_SELECTIVITY) ?? unknownLeafRows;
+    }
+    // Key coverage (`analyzeJoinKeyCoverage`) is not re-derived: the heuristic
+    // alone is close enough for a figure that is only ever compared.
+    if (node instanceof JoinNode || node instanceof BloomJoinNode || node instanceof MergeJoinNode) {
+        return joinPhysicalRows(node.joinType, undefined, relayedRows(node.left, unknownLeafRows), relayedRows(node.right, unknownLeafRows)) ?? unknownLeafRows;
+    }
+    if (node instanceof AggregateNode || node instanceof HashAggregateNode || node instanceof StreamAggregateNode) {
+        return node.rowsFrom(relayedRows(node.source, unknownLeafRows)) ?? unknownLeafRows;
+    }
+    // Any other single-relation node (Alias, Project, Sort, Cache, Distinct,
+    // LimitOffset, …) at most passes its source's rows through: an upper bound,
+    // which is all a relative comparison needs.
+    const relations = node.getRelations();
+    if (relations.length === 1)
+        return relayedRows(relations[0], unknownLeafRows);
+    return unknownLeafRows;
+}
+//# sourceMappingURL=relative-rows.js.map

package/dist/src/planner/util/relative-rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-rows.js","sourceRoot":"","sources":["../../../../src/planner/util/relative-rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,0BAA0B,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAwB,EAAE,eAAuB;IAC7E,OAAO,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,oFAAoF;AACpF,oFAAoF;AACpF,yFAAyF;AACzF,oFAAoF;AACpF,iDAAiD;AACjD,SAAS,WAAW,CAAC,IAAwB,EAAE,eAAuB;IACrE,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAEtC,IAAI,IAAI,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,cAAc,CACpB,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,IAAI,CAAC,WAAW,IAAI,0BAA0B,CAC9C,IAAI,eAAe,CAAC;IACtB,CAAC;IACD,2EAA2E;IAC3E,iEAAiE;IACjE,IAAI,IAAI,YAAY,QAAQ,IAAI,IAAI,YAAY,aAAa,IAAI,IAAI,YAAY,aAAa,EAAE,CAAC;QAChG,OAAO,gBAAgB,CACtB,IAAI,CAAC,QAAQ,EACb,SAAS,EACT,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,EACvC,WAAW,CAAC,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,CACxC,IAAI,eAAe,CAAC;IACtB,CAAC;IACD,IAAI,IAAI,YAAY,aAAa,IAAI,IAAI,YAAY,iBAAiB,IAAI,IAAI,YAAY,mBAAmB,EAAE,CAAC;QAC/G,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,IAAI,eAAe,CAAC;IACpF,CAAC;IACD,yEAAyE;IACzE,4EAA4E;IAC5E,4CAA4C;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IACtC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;IAC9E,OAAO,eAAe,CAAC;AACxB,CAAC"}

package/dist/src/planner/util/row-estimates.d.ts

@@ -25,6 +25,29 @@ import type { PhysicalProperties, RelationalPlanNode } from '../nodes/plan-node.
  * pre-optimization truth.
  */
 export declare function physicalSourceRows(childPhysical: PhysicalProperties | undefined, source: RelationalPlanNode): number | undefined;
+/**
+ * A row estimate as a cost site prices it: `unknown` stands in for `undefined`
+ * (nobody measured), and a measured 0 is floored at one row. A zero is the most
+ * fragile measurement there is — any insert since invalidates it by an infinite
+ * ratio — and a table or join side priced at nothing undercuts every seek and
+ * wins every comparison it enters. One row keeps an empty table cheap without
+ * making it free. Relays keep the 0; only sites turning a count into a cost call
+ * this (docs/optimizer-costing.md § Base-table row estimates).
+ */
+export declare function costedRows(rows: number | undefined, unknown: number): number;
+/**
+ * A Filter's output cardinality as a pure function of its source's and a
+ * selectivity — shared by `FilterNode`'s logical `estimatedRows` getter, its
+ * `computePhysical` (which feeds it the PHYSICAL source count), and the join
+ * rule's relative estimate (`planner/util/relative-rows.ts`) so the three cannot
+ * drift. The caller resolves the selectivity (stamped, or the last-resort
+ * `DEFAULT_FILTER_SELECTIVITY`).
+ *
+ * A non-empty source floors at one row — selectivity 0 (the provider says nothing
+ * matches) must not price the Filter at nothing — while a genuinely empty source
+ * stays 0, matching {@link aggregateRowsFrom}'s convention.
+ */
+export declare function filterRowsFrom(sourceRows: number | undefined, selectivity: number): number | undefined;
 /**
  * An aggregate's output cardinality as a pure function of its source's — shared
  * by every aggregate node's logical `estimatedRows` getter and its

package/dist/src/planner/util/row-estimates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"row-estimates.d.ts","sourceRoot":"","sources":["../../../../src/planner/util/row-estimates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEpF;;;;;;;;GAQG;AAMH,wBAAgB,kBAAkB,CACjC,aAAa,EAAE,kBAAkB,GAAG,SAAS,EAC7C,MAAM,EAAE,kBAAkB,GACxB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAapB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,QAA0B,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,GAAG,SAAS,CAQpB;AAED,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,UAAU,GAAG,cAAc,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GACzC,MAAM,GAAG,SAAS,CAoBpB"}
+{"version":3,"file":"row-estimates.d.ts","sourceRoot":"","sources":["../../../../src/planner/util/row-estimates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEpF;;;;;;;;GAQG;AAMH,wBAAgB,kBAAkB,CACjC,aAAa,EAAE,kBAAkB,GAAG,SAAS,EAC7C,MAAM,EAAE,kBAAkB,GACxB,MAAM,GAAG,SAAS,CAEpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGtG;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAapB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,QAA0B,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,gBAAgB,EACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC3B,MAAM,GAAG,SAAS,CAQpB;AAED,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,UAAU,GAAG,cAAc,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,oBAAoB,EAC1B,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GACzC,MAAM,GAAG,SAAS,CAoBpB"}

package/dist/src/planner/util/row-estimates.js

@@ -31,6 +31,35 @@
 export function physicalSourceRows(childPhysical, source) {
     return childPhysical?.estimatedRows ?? source.estimatedRows;
 }
+/**
+ * A row estimate as a cost site prices it: `unknown` stands in for `undefined`
+ * (nobody measured), and a measured 0 is floored at one row. A zero is the most
+ * fragile measurement there is — any insert since invalidates it by an infinite
+ * ratio — and a table or join side priced at nothing undercuts every seek and
+ * wins every comparison it enters. One row keeps an empty table cheap without
+ * making it free. Relays keep the 0; only sites turning a count into a cost call
+ * this (docs/optimizer-costing.md § Base-table row estimates).
+ */
+export function costedRows(rows, unknown) {
+    return rows === undefined ? unknown : Math.max(1, rows);
+}
+/**
+ * A Filter's output cardinality as a pure function of its source's and a
+ * selectivity — shared by `FilterNode`'s logical `estimatedRows` getter, its
+ * `computePhysical` (which feeds it the PHYSICAL source count), and the join
+ * rule's relative estimate (`planner/util/relative-rows.ts`) so the three cannot
+ * drift. The caller resolves the selectivity (stamped, or the last-resort
+ * `DEFAULT_FILTER_SELECTIVITY`).
+ *
+ * A non-empty source floors at one row — selectivity 0 (the provider says nothing
+ * matches) must not price the Filter at nothing — while a genuinely empty source
+ * stays 0, matching {@link aggregateRowsFrom}'s convention.
+ */
+export function filterRowsFrom(sourceRows, selectivity) {
+    if (sourceRows === undefined)
+        return undefined;
+    return sourceRows > 0 ? Math.max(1, Math.floor(sourceRows * selectivity)) : 0;
+}
 /**
  * An aggregate's output cardinality as a pure function of its source's — shared
  * by every aggregate node's logical `estimatedRows` getter and its

package/dist/src/planner/util/row-estimates.js.map

@@ -1 +1 @@
-{"version":3,"file":"row-estimates.js","sourceRoot":"","sources":["../../../../src/planner/util/row-estimates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;;GAQG;AACH,kFAAkF;AAClF,+EAA+E;AAC/E,qFAAqF;AACrF,qFAAqF;AACrF,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CACjC,aAA6C,EAC7C,MAA0B;IAE1B,OAAO,aAAa,EAAE,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC;AAC7D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAChC,UAA8B,EAC9B,OAAgB,EAChB,YAAoB;IAEpB,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAE/C,6EAA6E;IAC7E,gFAAgF;IAChF,IAAI,CAAC,OAAO;QAAE,OAAO,CAAC,CAAC;IAEvB,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,IAAI,UAAU,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE/B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC5C,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAChD,IAAI,IAAI,IAAI,gBAAgB;QAAE,OAAO,gBAAgB,CAAC;IACtD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AAKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CACnC,EAAoB,EACpB,QAA4B,EAC5B,SAA6B;IAE7B,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,qEAAqE;IACrE,IAAI,EAAE,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACvD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,EAAE,KAAK,WAAW;QAAE,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/E,sDAAsD;IACtD,OAAO,gBAAgB,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;AAC/C,CAAC;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc,CAC7B,IAA0B,EAC1B,UAA2C;IAE3C,IAAI,GAAG,GAAG,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC/B,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,QAAQ,IAAI,EAAE,CAAC;YACd,KAAK,UAAU;gBACd,GAAG,IAAI,IAAI,CAAC;gBACZ,MAAM;YACP,KAAK,UAAU;gBACd,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC1B,MAAM;YACP,KAAK,cAAc;gBAClB,qEAAqE;gBACrE,mEAAmE;gBACnE,yBAAyB;gBACzB,GAAG,GAAG,gBAAgB,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;gBACnC,MAAM;QACR,CAAC;IACF,CAAC;IACD,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"row-estimates.js","sourceRoot":"","sources":["../../../../src/planner/util/row-estimates.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime/cardinality-observations.d.ts

@@ -1,15 +1,45 @@
 /**
- * Per-execution sink for cardinality feedback: the exact row counts of base tables
- * that a scan read in full during one execution (docs/progressive-optimizer.md §3.1).
+ * Per-execution sink for cardinality feedback (docs/progressive-optimizer.md §3.1): the
+ * exact row counts of base tables a scan read in full during one execution, the
+ * floors — "holds at least N rows" — proven by scans that read only part of a table, and
+ * the rows each single-key equality seek through a non-unique index returned.
  *
- * The scan leaf (`runtime/emit/scan.ts`) reports here when a qualifying scan runs to
- * natural exhaustion; the run site hands the sink to
- * `CardinalityFeedbackManager.publish` once the execution ends. Nothing here decides
- * whether a count is worth keeping — that is the overlay's record policy.
+ * The scan leaf (`runtime/emit/scan.ts`) reports here as each qualifying invocation
+ * ends; the run site hands the sink to `CardinalityFeedbackManager.publish` once the
+ * execution ends. Beyond dropping floors too small to ever be recorded, nothing here
+ * decides whether an observation is worth keeping — that is the overlay's record policy.
  */
 import type { TableSchema } from '../schema/table.js';
+/**
+ * What a rows-per-key site knows at emit time: which base columns its equality seek
+ * looks up, their canonical key, and the rows per key the plan was priced with. Built
+ * once per scan site, so an invocation composes no string.
+ */
+export interface RowsPerKeySpec {
+    /** Sorted, de-duplicated base-column indexes of the seek's equality constraints. */
+    readonly columns: readonly number[];
+    /** {@link columnSetKey} of `columns` — the overlay's key for the column set within a table. */
+    readonly key: string;
+    /**
+     * The rows per key the plan priced this seek at — the overlay's observed mean when
+     * one answered at plan time, else the module's `estimatedRows`; a new entry's baseline.
+     */
+    readonly plannedRowsPerKey: number;
+}
+/**
+ * The overlay's key for an equality column set within one table. Shared by the scan
+ * leaf's spec and the planner's reader so the two cannot spell one set two ways.
+ */
+export declare function columnSetKey(columns: readonly number[]): string;
+/** Samples of one column set's rows per key, summed within one execution. */
+export interface RowsPerKeySamples {
+    readonly spec: RowsPerKeySpec;
+    sum: number;
+    count: number;
+}
 export declare class CardinalityObservations {
     readonly rollbacksAtStart: number;
+    private readonly recordFloor;
     /**
      * Keyed by schema object, not name: every scan in one execution was emitted from one
      * compile, so a nested-loop inner's re-scans and a self-join's two scan sites share
@@ -17,14 +47,39 @@ export declare class CardinalityObservations {
      * per completed scan. The overlay re-keys by name when it records.
      */
     private readonly counts;
+    /** Largest floor per table; same keying as `counts`. */
+    private readonly floors;
+    /**
+     * Rows-per-key samples per table and column-set key; same table keying as `counts`.
+     * One invocation is one sample: a nested-loop inner probing 10,000 outer rows adds
+     * 10,000 samples to one key here, published once as a sum and a count. Forked parallel
+     * branches share this sink by reference (`parallel-driver.ts`, `shared-sink`); the
+     * updates are synchronous map writes, so interleaving cannot lose one.
+     */
+    private readonly perKey;
     /**
      * @param rollbacksAtStart The overlay's rollback count when the execution began;
      * opaque here. If it has moved by publication, work this execution may have seen
      * was undone under it (`CardinalityFeedbackManager.publish`).
+     * @param recordFloor The overlay's `cardinalityFeedback.minRows`: a floor at or below
+     * it can never be recorded, so it is dropped before touching a map — which is every
+     * point seek and `get()`.
      */
-    constructor(rollbacksAtStart: number);
+    constructor(rollbacksAtStart: number, recordFloor: number);
     observe(table: TableSchema, rows: number): void;
+    /**
+     * One scan invocation yielded `rows` distinct rows of `table`, so it holds at least
+     * that many. Re-scans keep the largest single invocation: their rows may overlap, so
+     * a sum would overstate.
+     */
+    observeAtLeast(table: TableSchema, rows: number): void;
+    /** One exhausted equality seek of `spec`'s column set on `table` yielded `rows` rows — one sample. */
+    observeRowsPerKey(table: TableSchema, spec: RowsPerKeySpec, rows: number): void;
     get isEmpty(): boolean;
     entries(): IterableIterator<[TableSchema, number]>;
+    /** Floors of tables this execution did not also count exactly — the complete count supersedes. */
+    lowerBounds(): IterableIterator<[TableSchema, number]>;
+    /** Every column set sampled this execution, with its summed rows and sample count. */
+    rowsPerKey(): IterableIterator<[TableSchema, RowsPerKeySamples]>;
 }
 //# sourceMappingURL=cardinality-observations.d.ts.map

package/dist/src/runtime/cardinality-observations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cardinality-observations.d.ts","sourceRoot":"","sources":["../../../src/runtime/cardinality-observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,qBAAa,uBAAuB;IAcvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IAb7C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD;;;;OAIG;gBACkB,gBAAgB,EAAE,MAAM;IAE7C,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,IAAI,gBAAgB,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;CAGlD"}
+{"version":3,"file":"cardinality-observations.d.ts","sourceRoot":"","sources":["../../../src/runtime/cardinality-observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,+FAA+F;IAC/F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE/D;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,uBAAuB;IA2BvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IAAE,OAAO,CAAC,QAAQ,CAAC,WAAW;IA1B3E;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IAEjF;;;;;;;OAOG;gBACkB,gBAAgB,EAAE,MAAM,EAAmB,WAAW,EAAE,MAAM;IAEnF,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/C;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMtD,sGAAsG;IACtG,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAe/E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,OAAO,IAAI,gBAAgB,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAIlD,kGAAkG;IACjG,WAAW,IAAI,gBAAgB,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAMvD,sFAAsF;IACrF,UAAU,IAAI,gBAAgB,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;CAKjE"}

package/dist/src/runtime/cardinality-observations.js

@@ -1,14 +1,24 @@
 /**
- * Per-execution sink for cardinality feedback: the exact row counts of base tables
- * that a scan read in full during one execution (docs/progressive-optimizer.md §3.1).
+ * Per-execution sink for cardinality feedback (docs/progressive-optimizer.md §3.1): the
+ * exact row counts of base tables a scan read in full during one execution, the
+ * floors — "holds at least N rows" — proven by scans that read only part of a table, and
+ * the rows each single-key equality seek through a non-unique index returned.
  *
- * The scan leaf (`runtime/emit/scan.ts`) reports here when a qualifying scan runs to
- * natural exhaustion; the run site hands the sink to
- * `CardinalityFeedbackManager.publish` once the execution ends. Nothing here decides
- * whether a count is worth keeping — that is the overlay's record policy.
+ * The scan leaf (`runtime/emit/scan.ts`) reports here as each qualifying invocation
+ * ends; the run site hands the sink to `CardinalityFeedbackManager.publish` once the
+ * execution ends. Beyond dropping floors too small to ever be recorded, nothing here
+ * decides whether an observation is worth keeping — that is the overlay's record policy.
  */
+/**
+ * The overlay's key for an equality column set within one table. Shared by the scan
+ * leaf's spec and the planner's reader so the two cannot spell one set two ways.
+ */
+export function columnSetKey(columns) {
+    return columns.join(',');
+}
 export class CardinalityObservations {
     rollbacksAtStart;
+    recordFloor;
     /**
      * Keyed by schema object, not name: every scan in one execution was emitted from one
      * compile, so a nested-loop inner's re-scans and a self-join's two scan sites share
@@ -16,22 +26,78 @@ export class CardinalityObservations {
      * per completed scan. The overlay re-keys by name when it records.
      */
     counts = new Map();
+    /** Largest floor per table; same keying as `counts`. */
+    floors = new Map();
+    /**
+     * Rows-per-key samples per table and column-set key; same table keying as `counts`.
+     * One invocation is one sample: a nested-loop inner probing 10,000 outer rows adds
+     * 10,000 samples to one key here, published once as a sum and a count. Forked parallel
+     * branches share this sink by reference (`parallel-driver.ts`, `shared-sink`); the
+     * updates are synchronous map writes, so interleaving cannot lose one.
+     */
+    perKey = new Map();
     /**
      * @param rollbacksAtStart The overlay's rollback count when the execution began;
      * opaque here. If it has moved by publication, work this execution may have seen
      * was undone under it (`CardinalityFeedbackManager.publish`).
+     * @param recordFloor The overlay's `cardinalityFeedback.minRows`: a floor at or below
+     * it can never be recorded, so it is dropped before touching a map — which is every
+     * point seek and `get()`.
      */
-    constructor(rollbacksAtStart) {
+    constructor(rollbacksAtStart, recordFloor) {
         this.rollbacksAtStart = rollbacksAtStart;
+        this.recordFloor = recordFloor;
     }
     observe(table, rows) {
         this.counts.set(table, rows);
     }
+    /**
+     * One scan invocation yielded `rows` distinct rows of `table`, so it holds at least
+     * that many. Re-scans keep the largest single invocation: their rows may overlap, so
+     * a sum would overstate.
+     */
+    observeAtLeast(table, rows) {
+        if (rows <= this.recordFloor)
+            return;
+        const known = this.floors.get(table);
+        if (known === undefined || rows > known)
+            this.floors.set(table, rows);
+    }
+    /** One exhausted equality seek of `spec`'s column set on `table` yielded `rows` rows — one sample. */
+    observeRowsPerKey(table, spec, rows) {
+        let byKey = this.perKey.get(table);
+        if (!byKey) {
+            byKey = new Map();
+            this.perKey.set(table, byKey);
+        }
+        const samples = byKey.get(spec.key);
+        if (samples) {
+            samples.sum += rows;
+            samples.count++;
+        }
+        else {
+            byKey.set(spec.key, { spec, sum: rows, count: 1 });
+        }
+    }
     get isEmpty() {
-        return this.counts.size === 0;
+        return this.counts.size === 0 && this.floors.size === 0 && this.perKey.size === 0;
     }
     entries() {
         return this.counts.entries();
     }
+    /** Floors of tables this execution did not also count exactly — the complete count supersedes. */
+    *lowerBounds() {
+        for (const entry of this.floors) {
+            if (!this.counts.has(entry[0]))
+                yield entry;
+        }
+    }
+    /** Every column set sampled this execution, with its summed rows and sample count. */
+    *rowsPerKey() {
+        for (const [table, byKey] of this.perKey) {
+            for (const samples of byKey.values())
+                yield [table, samples];
+        }
+    }
 }
 //# sourceMappingURL=cardinality-observations.js.map

package/dist/src/runtime/cardinality-observations.js.map

@@ -1 +1 @@
-{"version":3,"file":"cardinality-observations.js","sourceRoot":"","sources":["../../../src/runtime/cardinality-observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,OAAO,uBAAuB;IAcd;IAbrB;;;;;OAKG;IACc,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAEzD;;;;OAIG;IACH,YAAqB,gBAAwB;QAAxB,qBAAgB,GAAhB,gBAAgB,CAAQ;IAAG,CAAC;IAEjD,OAAO,CAAC,KAAkB,EAAE,IAAY;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IAC9B,CAAC;CACD"}
+{"version":3,"file":"cardinality-observations.js","sourceRoot":"","sources":["../../../src/runtime/cardinality-observations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAA0B;IACtD,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AASD,MAAM,OAAO,uBAAuB;IA2Bd;IAA2C;IA1BhE;;;;;OAKG;IACc,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IACzD,wDAAwD;IACvC,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IACzD;;;;;;OAMG;IACc,MAAM,GAAG,IAAI,GAAG,EAA+C,CAAC;IAEjF;;;;;;;OAOG;IACH,YAAqB,gBAAwB,EAAmB,WAAmB;QAA9D,qBAAgB,GAAhB,gBAAgB,CAAQ;QAAmB,gBAAW,GAAX,WAAW,CAAQ;IAAG,CAAC;IAEvF,OAAO,CAAC,KAAkB,EAAE,IAAY;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAkB,EAAE,IAAY;QAC9C,IAAI,IAAI,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,GAAG,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,sGAAsG;IACtG,iBAAiB,CAAC,KAAkB,EAAE,IAAoB,EAAE,IAAY;QACvE,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QACD,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC;YACpB,OAAO,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;aAAM,CAAC;YACP,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACpD,CAAC;IACF,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC;IACnF,CAAC;IAED,OAAO;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IAC9B,CAAC;IAED,kGAAkG;IAClG,CAAC,WAAW;QACX,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAE,MAAM,KAAK,CAAC;QAC7C,CAAC;IACF,CAAC;IAED,sFAAsF;IACtF,CAAC,UAAU;QACV,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE;gBAAE,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9D,CAAC;IACF,CAAC;CACD"}

package/dist/src/runtime/emit/scan.d.ts

@@ -1,6 +1,6 @@
 import { type SqlValue } from "../../common/types.js";
 import { SeqScanNode, IndexScanNode, IndexSeekNode } from "../../planner/nodes/table-access-nodes.js";
-import type { FilterInfo } from "../../vtab/filter-info.js";
+import { type FilterInfo } from "../../vtab/filter-info.js";
 import type { Instruction, RuntimeContext } from "../types.js";
 import type { EmissionContext } from "../emission-context.js";
 /**