@quereus/quereus 4.4.0 → 4.5.0

package/dist/src/vtab/module.d.ts

@@ -8,6 +8,7 @@ import type { ModuleCapabilities } from './capabilities.js';
 import type { MappingAdvertisement } from './mapping-advertisement.js';
 import type { BackingHost } from './backing-host.js';
 import type { Schema } from '../schema/schema.js';
+import type { ViewSchema } from '../schema/view.js';
 import type { LensDeploymentSnapshot } from '../schema/lens.js';
 import type { Row, SqlValue } from '../common/types.js';
 /**
@@ -427,7 +428,51 @@ export interface VirtualTableModule<TTable extends VirtualTable, TConfig extends
      * never consulted on deploy (today's behavior).
      */
     notifyLensDeployment?(db: Database, logicalSchemaName: string, snapshot: LensDeploymentSnapshot): void | Promise<void>;
+    /**
+     * Optional pre-flight veto: throw when this module would be UNABLE to durably
+     * persist the catalog entry for `object`. Consulted over every registered module
+     * by the CREATE VIEW / CREATE MATERIALIZED VIEW / ALTER … SET TAGS paths BEFORE
+     * the object is registered (or, for a materialized view, inside `materializeView`'s
+     * existing rollback arm), so a rejection leaves the statement a clean no-op.
+     *
+     * Why a veto instead of an error on the persist itself: catalog persistence for
+     * views and materialized views is **advisory / fire-and-forget** — it rides the
+     * `SchemaChangeNotifier`, whose listeners are wrapped in try/catch, and a store
+     * module chains the actual write onto an async queue. Neither layer can surface a
+     * failure to the statement, so an unpersistable definition would otherwise appear
+     * to succeed and then vanish on reopen. This hook is the ONE synchronous point where
+     * a module can refuse. See `docs/schema.md` § View and materialized-view persistence.
+     *
+     * Views and materialized views are not owned by any one module the way a table is,
+     * so every module gets the veto; a module that would not persist the object must
+     * no-op. Synchronous by contract: the check must be a pure function of the schema
+     * (no IO). Omit ⇒ never consulted (today's behavior).
+     *
+     * Call sites, each ahead of its statement's first side effect: `emitCreateView`
+     * (before `schema.addView`); `materializeView` (inside its existing rollback arm — an
+     * MV's DDL text does not exist until the derivation is attached); the two view/MV SET
+     * TAGS paths in `SchemaManager` (tags ride the persisted DDL); and both ALTER RENAME
+     * arms in `runtime/emit/alter-table.ts`, which reach this through
+     * `assertRenameDependentsPersistable` — the pre-flight scan that offers the
+     * PROSPECTIVE (rewritten-on-a-clone) body of every dependent view / materialized view,
+     * plus, for a renamed materialized view, its own prospective record under the new name.
+     *
+     * Not covered: a `select *` materialized view's persisted backing COLUMN LIST shifts
+     * under a column rename with no AST change and no persist event, so nothing asks here
+     * (see the `NOTE:` on `restoreUnaffectedMaterializedViews`); and dependent TABLE
+     * entries — the FK / CHECK / partial-index rewrites a rename propagates into other
+     * tables — re-persist through the same swallowing path with no veto at all, since
+     * {@link CatalogObjectKind} has no `'table'` case
+     * (`bug-store-rename-diverges-dependent-table-catalog-entry`).
+     */
+    assertCatalogObjectPersistable?(db: Database, kind: CatalogObjectKind, object: ViewSchema | TableSchema): void;
 }
+/**
+ * The catalog object classes {@link VirtualTableModule.assertCatalogObjectPersistable}
+ * arbitrates. `'view'` carries a {@link ViewSchema}; `'materializedView'` carries the
+ * maintained {@link TableSchema} (the unified MV record).
+ */
+export type CatalogObjectKind = 'view' | 'materializedView';
 /**
  * Defines the structure for schema change information passed to xAlterSchema
  */
@@ -443,6 +488,24 @@ export type SchemaChangeInfo = {
      * writing a single default value.
      */
     backfillEvaluator?: (row: Row) => SqlValue | Promise<SqlValue>;
+    /**
+     * Insert the new column at this index instead of appending. Undefined (the normal
+     * case, and what SQL `alter table … add column` always produces) means append.
+     * A module that cannot honour a position must reject it rather than silently append.
+     *
+     * There is no SQL syntax for this — it is reachable only from an in-process module
+     * wrapper. The one caller today is the transaction-isolation overlay, which keeps a
+     * private bookkeeping column last and so must insert ahead of it.
+     *
+     * NOTE: the engine's own ADD COLUMN pipeline assumes an append in one place a wrapper
+     * can reach — the per-row context it evaluates a column-level CHECK against is built as
+     * `[...existingRow, value]` (`buildAddColumnChecks` in planner/building/alter-table.ts).
+     * So a wrapper that redirects an *engine-driven* `alter table … add column` to a
+     * non-append position must not rely on a column-level CHECK on that column; it would be
+     * evaluated against the append layout. Applying the change straight to a module (the
+     * isolation overlay's case) never goes near that path.
+     */
+    insertAtIndex?: number;
 } | {
     type: 'dropColumn';
     columnName: string;

package/dist/src/vtab/module.d.ts.map

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

package/dist/src/vtab/table.d.ts

@@ -25,11 +25,15 @@ export interface UpdateArgs {
     /** Optional: Deterministic SQL statement that reproduces this mutation (if logMutations is enabled) */
     mutationStatement?: string;
     /**
-     * If true, `values` is already coerced to the table's declared column logical
-     * types (e.g. flushed from an overlay that coerced on write). The vtab may skip
-     * its own coercion pass. Used by the isolation layer's overlay→underlying flush
-     * to avoid double-parsing values that are not idempotent under parse (e.g.
-     * JSON scalar strings).
+     * If true, `values` (and any key cells in `oldKeyValues`) are already coerced
+     * to the table's declared column logical types, and the vtab may skip its own
+     * coercion pass — conversion is not idempotent for every type (JSON scalar
+     * strings double-parse to a different value or throw). Set by the DML executor
+     * (whose emitters convert every write at the top of the pipeline, driven by
+     * static expression types — docs/types.md § Where coercion happens) and by the
+     * isolation layer's overlay→underlying flush and tombstone writes (rows built
+     * from already-converted stored values). Direct API callers leave it unset and
+     * the vtab converts raw values itself, as before.
      */
     preCoerced?: boolean;
     /**
@@ -112,7 +116,21 @@ export declare abstract class VirtualTable {
      * Performs an INSERT, UPDATE, or DELETE operation.
      *
      * Returns an UpdateResult indicating success or constraint violation:
-     * - `{ status: 'ok', row?: Row }` - Success. Row is new/updated row for INSERT/UPDATE, undefined for DELETE.
+     * - `{ status: 'ok', row?: Row }` - Success. The presence of `row` is how the module
+     *   reports that a row was actually written or removed. Omitting it means "no row
+     *   changed" (an UPDATE/DELETE whose key was not found, or a conflict the module
+     *   resolved as IGNORE): the executor then skips the whole post-write pipeline and
+     *   emits nothing downstream — so every module must return `row` on a real write.
+     *   For INSERT/UPDATE, `row` is the row the module actually STORED: the proposed
+     *   `args.values` after the module's own coercion to the declared column logical
+     *   types. A module that coerces MUST return the coerced row, because the DML
+     *   executor reports `row` (not `args.values`) to every post-write consumer —
+     *   RETURNING, change tracking, row-time materialized-view maintenance, FK cascades,
+     *   data-change events. Returning the raw input from a coercing module makes
+     *   RETURNING disagree with a subsequent `select` on the same row. A row whose width
+     *   is not the table's column count makes the executor fall back to `args.values`.
+     *   For DELETE, only the presence of `row` is consulted, never its contents (the OLD
+     *   image comes from the source scan), so a PK-only placeholder is acceptable.
      * - `{ status: 'constraint', constraint, message?, existingRow? }` - Constraint violation.
      *   For 'unique' constraints, existingRow contains the conflicting row (enables UPSERT).
      *
@@ -194,9 +212,17 @@ export declare abstract class VirtualTable {
     /**
      * Modifies the schema of this virtual table
      * @param changeInfo Object describing the schema modification
+     * @param validateOnly When true, run every pre-mutation validation the change would run
+     *   and throw exactly what the real application would throw, but mutate NOTHING — a
+     *   dry-run. A caller coordinating this table's change with another irreversible
+     *   mutation (the isolation layer sequencing a per-connection overlay against the
+     *   shared underlying table) uses it to surface a refusal while everything is still
+     *   untouched. Support is per-module (the bundled memory module supports it for
+     *   `alterColumn`); a module that cannot validate without mutating must throw rather
+     *   than silently apply.
      * @throws QuereusError or ConstraintError on failure
      */
-    alterSchema?(changeInfo: SchemaChangeInfo): Promise<void>;
+    alterSchema?(changeInfo: SchemaChangeInfo, validateOnly?: boolean): Promise<void>;
     /**
      * Creates a secondary index on the virtual table
      * @param indexInfo The index definition

package/dist/src/vtab/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/vtab/table.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/vtab/table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,wDAAwD;IACxD,SAAS,EAAE,KAAK,CAAC;IACjB,4EAA4E;IAC5E,MAAM,EAAE,GAAG,GAAG,SAAS,CAAC;IACxB,uFAAuF;IACvF,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB,kEAAkE;IAClE,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,uGAAuG;IACvG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,8BAAsB,YAAY;IACjC,SAAgB,MAAM,EAAE,qBAAqB,CAAC;IAC9C,SAAgB,EAAE,EAAE,QAAQ,CAAC;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,8DAA8D;IAC9D,SAAgB,UAAU,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC;IAEjC;;;;OAIG;IACI,cAAc,CAAC,EAAE,OAAO,CAAC;gBAEpB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAO9F;;;OAGG;IACH,SAAS,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI5D;;;;OAIG;IACH,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAEpC;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC;IAElD;;;;;;;;OAQG;IACH,WAAW,CAAC,CACX,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,QAAQ,EACd,GAAG,CAAC,EAAE,OAAO,GACX,aAAa,CAAC,GAAG,CAAC;IAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAExD;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,YAAY,CAAC,sBAAsB,CAAC;IAEzD;;;;OAIG;IACH,aAAa,CAAC,IAAI,sBAAsB,GAAG,SAAS;IAEpD;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,CAAC,UAAU,EAAE,sBAAsB,GAAG,YAAY,CAAC,IAAI,CAAC;IAExE;;OAEG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAEvB;;OAEG;IACH,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAEtB;;OAEG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvC;;;OAGG;IACH,SAAS,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjD;;;OAGG;IACH,OAAO,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE/C;;;OAGG;IACH,UAAU,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,CAAC,UAAU,EAAE,gBAAgB,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAEjF;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9E;;;OAGG;IACH,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE5C;;;OAGG;IACH,eAAe,CAAC,IAAI,kBAAkB,GAAG,SAAS;IAElD;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe;IAI5D;;;OAGG;IACH,iBAAiB,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE;IAExC;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM;IAExD;;;OAGG;IACH,oBAAoB,CAAC,IAAI,MAAM,EAAE;IAEjC;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAS;CAC/D"}

package/dist/src/vtab/table.js.map

@@ -1 +1 @@
-{"version":3,"file":"table.js","sourceRoot":"","sources":["../../../src/vtab/table.ts"],"names":[],"mappings":"AA8CA;;;GAGG;AACH,MAAM,OAAgB,YAAY;IACjB,MAAM,CAAwB;IAC9B,EAAE,CAAW;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACa,SAAS,CAAS;IAClC,8DAA8D;IAC9C,UAAU,CAAS;IAC5B,YAAY,CAAU;IACtB,WAAW,CAAe;IAEjC;;;;OAIG;IACI,cAAc,CAAW;IAEhC,YAAY,EAAY,EAAE,MAA6B,EAAE,UAAkB,EAAE,SAAiB;QAC7F,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACO,eAAe,CAAC,OAA2B;QACpD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAC7B,CAAC;CAkMD"}
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../../src/vtab/table.ts"],"names":[],"mappings":"AAkDA;;;GAGG;AACH,MAAM,OAAgB,YAAY;IACjB,MAAM,CAAwB;IAC9B,EAAE,CAAW;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACa,SAAS,CAAS;IAClC,8DAA8D;IAC9C,UAAU,CAAS;IAC5B,YAAY,CAAU;IACtB,WAAW,CAAe;IAEjC;;;;OAIG;IACI,cAAc,CAAW;IAEhC,YAAY,EAAY,EAAE,MAA6B,EAAE,UAAkB,EAAE,SAAiB;QAC7F,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACO,eAAe,CAAC,OAA2B;QACpD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAC7B,CAAC;CAwND"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quereus/quereus",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "type": "module",
   "description": "Pure TypeScript SQL engine — no WASM, no native bindings. Runs in browsers, Node.js, React Native, edge workers, and anywhere JS runs.",
   "keywords": [
@@ -71,9 +71,9 @@
     "mutation:subsystem": "node mutation-subsystem.mjs"
   },
   "devDependencies": {
-    "@quereus/plugin-leveldb": "^4.4.0",
+    "@quereus/plugin-leveldb": "^4.5.0",
     "@quereus/plugin-loader": "*",
-    "@quereus/store": "^4.4.0",
+    "@quereus/store": "^4.5.0",
     "@stryker-mutator/core": "^9.6.1",
     "@stryker-mutator/mocha-runner": "^9.6.1",
     "@stryker-mutator/typescript-checker": "^9.6.1",

package/dist/src/planner/rules/cache/rule-in-subquery-cache.d.ts

@@ -1,26 +0,0 @@
-/**
- * Rule: IN-Subquery Cache
- *
- * Required Characteristics:
- * - Node must be an InNode with a subquery source (not a value list)
- * - Source must be uncorrelated (no outer attribute references)
- * - Source must be deterministic and read-only (functional)
- * - Source must not already be cached
- *
- * Applied When:
- * - IN subquery source would be re-executed for every outer row in a filter predicate
- *
- * Benefits: Materializes the subquery result once and replays from cache on subsequent
- * evaluations, reducing O(N * K) CTE/subquery evaluations to O(K + N * K_cached)
- *
- * The CacheNode is built in EAGER mode: emitIn's pure streaming consumer returns on
- * the first matching row, which would abort a streaming-first cache mid-build and leave
- * it uncommitted (so every outer row re-opens the source). Eager mode drains + commits
- * the buffer on the first evaluation before yielding any row, so IN's first-match
- * short-circuit cannot defeat the cache. Safe here because the rule already gates on
- * uncorrelated + functional, so the materialized set is identical across outer rows.
- */
-import type { PlanNode } from '../../nodes/plan-node.js';
-import type { OptContext } from '../../framework/context.js';
-export declare function ruleInSubqueryCache(node: PlanNode, context: OptContext): PlanNode | null;
-//# sourceMappingURL=rule-in-subquery-cache.d.ts.map

package/dist/src/planner/rules/cache/rule-in-subquery-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rule-in-subquery-cache.d.ts","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-in-subquery-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAS7D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CA0DxF"}

package/dist/src/planner/rules/cache/rule-in-subquery-cache.js

@@ -1,66 +0,0 @@
-/**
- * Rule: IN-Subquery Cache
- *
- * Required Characteristics:
- * - Node must be an InNode with a subquery source (not a value list)
- * - Source must be uncorrelated (no outer attribute references)
- * - Source must be deterministic and read-only (functional)
- * - Source must not already be cached
- *
- * Applied When:
- * - IN subquery source would be re-executed for every outer row in a filter predicate
- *
- * Benefits: Materializes the subquery result once and replays from cache on subsequent
- * evaluations, reducing O(N * K) CTE/subquery evaluations to O(K + N * K_cached)
- *
- * The CacheNode is built in EAGER mode: emitIn's pure streaming consumer returns on
- * the first matching row, which would abort a streaming-first cache mid-build and leave
- * it uncommitted (so every outer row re-opens the source). Eager mode drains + commits
- * the buffer on the first evaluation before yielding any row, so IN's first-match
- * short-circuit cannot defeat the cache. Safe here because the rule already gates on
- * uncorrelated + functional, so the materialized set is identical across outer rows.
- */
-import { createLogger } from '../../../common/logger.js';
-import { InNode } from '../../nodes/subquery.js';
-import { CacheNode } from '../../nodes/cache-node.js';
-import { CapabilityDetectors, CachingAnalysis, PlanNodeCharacteristics } from '../../framework/characteristics.js';
-import { isCorrelatedSubquery } from '../../cache/correlation-detector.js';
-import { PlanNodeType } from '../../nodes/plan-node-type.js';
-const log = createLogger('optimizer:rule:in-subquery-cache');
-export function ruleInSubqueryCache(node, context) {
-    // Guard: must be an InNode with a subquery source
-    if (node.nodeType !== PlanNodeType.In) {
-        return null;
-    }
-    const inNode = node;
-    if (!inNode.source) {
-        return null; // Value-list IN, nothing to cache
-    }
-    const source = inNode.source;
-    // Gate: source must not already be cached
-    if (CapabilityDetectors.isCached(source) && source.isCached()) {
-        log('IN-subquery source already cached, skipping');
-        return null;
-    }
-    // Gate: source must be uncorrelated (no outer attribute references)
-    if (isCorrelatedSubquery(source)) {
-        log('IN-subquery is correlated, skipping cache wrapping');
-        return null;
-    }
-    // Gate: source must be deterministic and read-only
-    if (!PlanNodeCharacteristics.isFunctional(source)) {
-        log('IN-subquery source is not functional, skipping cache wrapping');
-        return null;
-    }
-    log('Wrapping uncorrelated IN-subquery source in CacheNode');
-    const cacheThreshold = Math.min(CachingAnalysis.getCacheThreshold(source), context.tuning.cte.maxCacheThreshold);
-    // NOTE: eager drains the whole subquery on the first eval, so a low-cardinality
-    // outer relation (e.g. one row, or an early LIMIT) pays the full drain and loses
-    // IN's first-match early-exit. Harmless for small sources; if large-source +
-    // low-outer-cardinality IN-subqueries show up as slow, gate eager (or the whole
-    // rule) on estimated outer cardinality.
-    const cachedSource = new CacheNode(source.scope, source, 'memory', cacheThreshold, true // eager: defeat IN's first-match short-circuit that would abort a streaming build
-    );
-    return new InNode(inNode.scope, inNode.expression, inNode.condition, cachedSource, inNode.values);
-}
-//# sourceMappingURL=rule-in-subquery-cache.js.map

package/dist/src/planner/rules/cache/rule-in-subquery-cache.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"rule-in-subquery-cache.js","sourceRoot":"","sources":["../../../../../src/planner/rules/cache/rule-in-subquery-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AACnH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D,MAAM,GAAG,GAAG,YAAY,CAAC,kCAAkC,CAAC,CAAC;AAE7D,MAAM,UAAU,mBAAmB,CAAC,IAAc,EAAE,OAAmB;IACtE,kDAAkD;IAClD,IAAI,IAAI,CAAC,QAAQ,KAAK,YAAY,CAAC,EAAE,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,MAAM,GAAG,IAAc,CAAC;IAC9B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC,CAAC,kCAAkC;IAChD,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAE7B,0CAA0C;IAC1C,IAAI,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC/D,GAAG,CAAC,6CAA6C,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACb,CAAC;IAED,oEAAoE;IACpE,IAAI,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;QAClC,GAAG,CAAC,oDAAoD,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACb,CAAC;IAED,mDAAmD;IACnD,IAAI,CAAC,uBAAuB,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,+DAA+D,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC;IACb,CAAC;IAED,GAAG,CAAC,uDAAuD,CAAC,CAAC;IAE7D,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC9B,eAAe,CAAC,iBAAiB,CAAC,MAAM,CAAC,EACzC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,iBAAiB,CACpC,CAAC;IAEF,gFAAgF;IAChF,iFAAiF;IACjF,6EAA6E;IAC7E,gFAAgF;IAChF,wCAAwC;IACxC,MAAM,YAAY,GAAG,IAAI,SAAS,CACjC,MAAM,CAAC,KAAK,EACZ,MAAM,EACN,QAAQ,EACR,cAAc,EACd,IAAI,CAAE,kFAAkF;KACxF,CAAC;IAEF,OAAO,IAAI,MAAM,CAChB,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,SAAS,EAChB,YAAY,EACZ,MAAM,CAAC,MAAM,CACb,CAAC;AACH,CAAC"}