@quereus/quereus 4.3.1 → 4.3.2

package/dist/src/vtab/backing-host.d.ts

@@ -16,6 +16,13 @@
  * module-agnostic. A module that cannot provide the ordered prefix scan must
  * NOT advertise the capability — the engine does not gate per maintenance arm.
  *
+ * NOTE: this obligation is normative but unenforced — nothing checks it at
+ * runtime, so a module advertising the capability without the ordered prefix
+ * scan degrades silently (correct results, linear cost). Only the in-tree
+ * memory and store hosts implement it today. If third-party backing hosts
+ * appear, promote this to a shared conformance suite the module runs against
+ * (docs/invariants.md MV-015).
+ *
  * ## Effective-change reporting
  *
  * Reporting the EFFECTIVE per-row changes from {@link BackingHost.applyMaintenance}
@@ -163,7 +170,7 @@ import type { BTreeKeyForPrimary } from './memory/types.js';
  * The point ops (`delete-key`/`upsert`) keep a one-source-row → one-backing-row
  * delta (covering-index, aggregate-residual); `delete-by-prefix` is the
  * one-source-row → N-backing-rows primitive; `replace-all` is the whole-table
- * primitive — see `docs/materialized-views.md` § Row-time refresh and
+ * primitive — see `docs/mv-maintenance.md` § Maintenance (row-time, per-statement) and
  * `docs/incremental-maintenance.md` § prefix-delete / § replace-all.
  */
 export type MaintenanceOp = {

package/dist/src/vtab/backing-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backing-host.d.ts","sourceRoot":"","sources":["../../../src/vtab/backing-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AAE9C,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IAClC;4CACwC;IACxC,cAAc,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,+EAA+E;IAC/E,cAAc,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IACtD;;gFAE4E;IAC5E,OAAO,IAAI,sBAAsB,CAAC;IAClC;;;;;;;;;;0CAUsC;IACtC,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC3G;;;gCAG4B;IAC5B,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F;;oDAEgD;IAChD,aAAa,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA4BiC;IACjC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACjD"}
+{"version":3,"file":"backing-host.d.ts","sourceRoot":"","sources":["../../../src/vtab/backing-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,GAAG,EAAE,CAAA;CAAE,CAAC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC;AAE9C,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IAClC;4CACwC;IACxC,cAAc,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,+EAA+E;IAC/E,cAAc,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IACtD;;gFAE4E;IAC5E,OAAO,IAAI,sBAAsB,CAAC;IAClC;;;;;;;;;;0CAUsC;IACtC,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC3G;;;gCAG4B;IAC5B,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F;;oDAEgD;IAChD,aAAa,CAAC,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA4BiC;IACjC,QAAQ,CAAC,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACjD"}

package/dist/src/vtab/backing-host.js

@@ -16,6 +16,13 @@
  * module-agnostic. A module that cannot provide the ordered prefix scan must
  * NOT advertise the capability — the engine does not gate per maintenance arm.
  *
+ * NOTE: this obligation is normative but unenforced — nothing checks it at
+ * runtime, so a module advertising the capability without the ordered prefix
+ * scan degrades silently (correct results, linear cost). Only the in-tree
+ * memory and store hosts implement it today. If third-party backing hosts
+ * appear, promote this to a shared conformance suite the module runs against
+ * (docs/invariants.md MV-015).
+ *
  * ## Effective-change reporting
  *
  * Reporting the EFFECTIVE per-row changes from {@link BackingHost.applyMaintenance}

package/dist/src/vtab/backing-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"backing-host.js","sourceRoot":"","sources":["../../../src/vtab/backing-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG"}
+{"version":3,"file":"backing-host.js","sourceRoot":"","sources":["../../../src/vtab/backing-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0HG"}

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

@@ -4,6 +4,7 @@
  */
 import { type SqlValue, type Row } from '../common/types.js';
 import type { LogicalType } from '../types/logical-type.js';
+import { type IndexDescriptor } from './index-descriptor.js';
 /**
  * Constraint operators that can be pushed down to virtual tables
  */
@@ -108,6 +109,18 @@ export interface BestAccessPlanResult {
     orderingIndexName?: string;
     /** Name of the index chosen for filtering (e.g., '_primary_' or a secondary index name) */
     indexName?: string;
+    /**
+     * Structured identity of the index named by `indexName` (or, for an ordering-only
+     * plan, by `orderingIndexName`).
+     *
+     * OPTIONAL when that name is `_primary_` or matches an index present in the table
+     * schema — the engine resolves those itself. REQUIRED when the module names the
+     * index anything else (e.g. a per-plan alias like `_primary_1`): without it the
+     * engine cannot tell a primary-key walk from a secondary-index walk, and consumers
+     * that depend on scan order (the isolation layer's overlay merge) cannot trust the
+     * plan. See `docs/module-authoring.md`.
+     */
+    indexDescriptor?: IndexDescriptor;
     /** Column indexes that form the seek/range key, in order */
     seekColumnIndexes?: readonly number[];
     /** Whether this plan guarantees unique rows (helps DISTINCT optimization) */
@@ -217,6 +230,11 @@ export declare class AccessPlanBuilder {
      * Set the index name chosen for this access plan
      */
     setIndexName(indexName: string): this;
+    /**
+     * Set the structured identity of the chosen index. Required when `indexName` is a
+     * per-plan alias the engine cannot resolve from the table schema.
+     */
+    setIndexDescriptor(indexDescriptor: IndexDescriptor): this;
     /**
      * Set the column indexes that form the seek/range key
      */

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

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

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

@@ -4,6 +4,7 @@
  */
 import { quereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
+import { validateIndexDescriptor } from './index-descriptor.js';
 /**
  * Builder class for constructing access plan results
  */
@@ -86,6 +87,14 @@ export class AccessPlanBuilder {
         this.result.indexName = indexName;
         return this;
     }
+    /**
+     * Set the structured identity of the chosen index. Required when `indexName` is a
+     * per-plan alias the engine cannot resolve from the table schema.
+     */
+    setIndexDescriptor(indexDescriptor) {
+        this.result.indexDescriptor = indexDescriptor;
+        return this;
+    }
     /**
      * Set the column indexes that form the seek/range key
      */
@@ -161,6 +170,12 @@ export function validateAccessPlan(request, result) {
             }
         }
     }
+    // A supplied indexDescriptor must describe the index the plan actually drives —
+    // a descriptor naming a different index than `indexName` is a module bug, and
+    // silently reconciling it would hand order-sensitive consumers the wrong sort key.
+    if (result.indexDescriptor) {
+        validateIndexDescriptor(result.indexDescriptor, result.indexName, result.orderingIndexName, request.columns.length);
+    }
     // Validate monotonicOn column index is in range
     if (result.monotonicOn) {
         const colIdx = result.monotonicOn.columnIndex;

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

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

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

@@ -1,4 +1,32 @@
 import type { SqlValue, Row, CompareFn } from '../common/types.js';
+/**
+ * How a module's DDL (schema-change) statements behave with respect to the
+ * enclosing transaction. A single worst-case summary across every DDL statement
+ * the module can execute — per-statement detail belongs in the backend docs, not
+ * this flag. Severity order (least → most surprising):
+ *
+ *  - `'transactional'` — the reference semantics: a schema change is part of the
+ *    enclosing transaction. The catalog entry and physical structures are buffered
+ *    with the transaction, visible to later statements inside it, made durable
+ *    atomically with the DML at commit, and discarded whole on `rollback` /
+ *    `rollback to savepoint`. No built-in module reaches this tier today.
+ *  - `'non-transactional'` — the schema change escapes the transaction (it survives
+ *    `rollback`) but buffered DML still rolls back normally. This is the memory
+ *    module, and the store's non-committing DDL statements.
+ *  - `'auto-commit'` — executing certain DDL commits the module's buffered
+ *    transaction at DDL time: the schema change AND every buffered write become
+ *    durable immediately, and a later `rollback` undoes nothing. This is the store
+ *    module (its row-rewriting ALTER arms and `renameTable` flush pending ops).
+ *
+ * A module declares its WORST case: the store does both non-transactional and
+ * auto-committing DDL, so it declares `'auto-commit'`.
+ *
+ * Consumed by the `ddl_transaction_policy = 'strict'` gate, which refuses a
+ * module-dispatching DDL statement inside an explicit transaction on any module
+ * whose tier is not `'transactional'`. See `runtime/emit/ddl-transaction-policy.ts`
+ * and docs/module-authoring.md § "Capability negotiation surface".
+ */
+export type DdlTransactionality = 'transactional' | 'non-transactional' | 'auto-commit';
 /**
  * Capability flags that modules can advertise to consumers.
  * Used for runtime capability discovery and isolation layer decisions.
@@ -59,6 +87,22 @@ export interface ModuleCapabilities {
      * lifted by separate paths and are NOT gated by this flag.
      */
     permitsGrandfatheredCheckViolators?: boolean;
+    /**
+     * Declares how this module's DDL behaves inside a transaction — the third LIVE
+     * capability gate alongside `delegatesNotNullBackfill` and
+     * `permitsGrandfatheredCheckViolators`. See {@link DdlTransactionality} for the
+     * three tiers.
+     *
+     * Default/absent ⇒ `'non-transactional'`. A module must EXPLICITLY claim
+     * `'transactional'`; assuming the clean semantics by default would let every
+     * existing module silently over-promise.
+     *
+     * Read live by the `ddl_transaction_policy = 'strict'` gate: a module-dispatching
+     * DDL statement inside an explicit transaction is refused unless the owning
+     * module's tier is `'transactional'`. Under the default `'permissive'` policy the
+     * flag is not consulted and behavior is unchanged.
+     */
+    ddlTransactionality?: DdlTransactionality;
 }
 /**
  * Extended interface for tables that can be wrapped by the isolation layer.

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/vtab/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAUlC,oHAAoH;IACpH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,sFAAsF;IACtF,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE,CAAC;IAExC;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAExD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;IAEhE;;;OAGG;IACH,oBAAoB,IAAI,MAAM,EAAE,CAAC;CACjC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/vtab/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,mBAAmB,GAAG,aAAa,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAUlC,oHAAoH;IACpH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,sFAAsF;IACtF,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;;;;;OAiBG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAE7C;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,EAAE,CAAC;IAExC;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAExD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;IAEhE;;;OAGG;IACH,oBAAoB,IAAI,MAAM,EAAE,CAAC;CACjC"}

package/dist/src/vtab/filter-info.d.ts

@@ -1,5 +1,6 @@
 import type { SqlValue } from '../common/types.js';
 import type { IndexConstraint, IndexInfo } from './index-info.js';
+import type { AccessPath, IndexDescriptor } from './index-descriptor.js';
 /**
  * Structure to pass all necessary filter and planning information
  * to a virtual table's xOpen method when cursors are not used.
@@ -22,6 +23,16 @@ export interface FilterInfo {
      * This is needed by xOpen to understand how constraints were used by the planner.
      */
     indexInfoOutput: IndexInfo;
+    /**
+     * Structured description of the access path this FilterInfo drives — the typed,
+     * validated form of what `idxStr` encodes as text. Populated by
+     * `rule-select-access-path`; consumers should read this rather than parse `idxStr`.
+     *
+     * Absent ⇒ this FilterInfo was hand-built by a caller that declared no access path.
+     * A consumer that needs the access path MUST fail loudly rather than infer one from
+     * `idxStr`; the engine's own builders below always populate it.
+     */
+    readonly accessPath?: AccessPath;
     /**
      * If set, the access plan honors a soft row cap — the vtab should stop
      * emitting after this many rows. Pushed down by OrdinalSlice / future
@@ -37,4 +48,35 @@ export interface FilterInfo {
      */
     offset?: number;
 }
+/**
+ * FilterInfo for a full table scan: no constraints, no index.
+ *
+ * Shared by the planner's sequential-scan arms, `ANALYZE`'s scan-based statistics
+ * collection, and the isolation layer's overlay-merge / migration / commit-flush
+ * scans — one definition keeps those sites from drifting.
+ */
+export declare function makeFullScanFilterInfo(cost?: number, rows?: number): FilterInfo;
+/**
+ * FilterInfo for a provably empty relation (an unsatisfiable predicate). Distinct from
+ * {@link makeFullScanFilterInfo} so a consumer can tell "no index" from "no rows".
+ */
+export declare function makeEmptyFilterInfo(): FilterInfo;
+/**
+ * FilterInfo for an equality (point/prefix) seek over `index`: one EQ constraint per
+ * entry of `seekColumnIndexes`, bound positionally to `values`.
+ *
+ * Used by the isolation layer's primary-key point lookups and by any caller that must
+ * drive an O(log n) seek instead of a scan.
+ */
+export declare function makeIndexEqSeekFilterInfo(index: IndexDescriptor, seekColumnIndexes: readonly number[], values: readonly SqlValue[]): FilterInfo;
+/**
+ * Rewrite the index name across `idxStr`, `indexInfoOutput.idxStr`, and
+ * `accessPath.index.name` (or `accessPath.indexName` when unresolved).
+ *
+ * A module may advertise a per-plan alias for an index (`_primary_1`) that a wrapping
+ * table's delegate does not know. Retargeting rewrites only the name; `plan`, `nameArg`,
+ * and every parameter — including ones this engine does not understand — survive verbatim.
+ * A FilterInfo naming no index (full scan / empty) is returned unchanged.
+ */
+export declare function retargetFilterInfoIndex(filterInfo: FilterInfo, newIndexName: string): FilterInfo;
 //# sourceMappingURL=filter-info.d.ts.map

package/dist/src/vtab/filter-info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter-info.d.ts","sourceRoot":"","sources":["../../../src/vtab/filter-info.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAElE;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oEAAoE;IACpE,WAAW,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,eAAe,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,8DAA8D;IAC9D,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC9B;;;;OAIG;IACH,eAAe,EAAE,SAAS,CAAC;IAE3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"filter-info.d.ts","sourceRoot":"","sources":["../../../src/vtab/filter-info.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGzE;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oEAAoE;IACpE,WAAW,EAAE,aAAa,CAAC;QAAE,UAAU,EAAE,eAAe,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,8DAA8D;IAC9D,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC9B;;;;OAIG;IACH,eAAe,EAAE,SAAS,CAAC;IAE3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IAEjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,SAAY,EAAE,IAAI,SAAY,GAAG,UAAU,CAsBrF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAsBhD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,eAAe,EACtB,iBAAiB,EAAE,SAAS,MAAM,EAAE,EACpC,MAAM,EAAE,SAAS,QAAQ,EAAE,GACzB,UAAU,CA4BZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,UAAU,CAehG"}

package/dist/src/vtab/filter-info.js

@@ -1,2 +1,138 @@
-export {};
+import { IndexConstraintOp } from '../common/constants.js';
+import { encodeIdxStr, makeIdxStrSpec, retargetIdxStr } from './idx-str.js';
+/** The `idxStr` sentinel meaning "no index chosen — walk every row". */
+const FULL_SCAN_IDX_STR = 'fullscan';
+/** The `idxStr` sentinel meaning "the predicate is unsatisfiable — emit no rows". */
+const EMPTY_IDX_STR = 'empty';
+/**
+ * FilterInfo for a full table scan: no constraints, no index.
+ *
+ * Shared by the planner's sequential-scan arms, `ANALYZE`'s scan-based statistics
+ * collection, and the isolation layer's overlay-merge / migration / commit-flush
+ * scans — one definition keeps those sites from drifting.
+ */
+export function makeFullScanFilterInfo(cost = 1_000_000, rows = 1_000_000) {
+    return {
+        idxNum: 0,
+        idxStr: FULL_SCAN_IDX_STR,
+        constraints: [],
+        args: [],
+        accessPath: { kind: 'fullScan' },
+        indexInfoOutput: {
+            nConstraint: 0,
+            aConstraint: [],
+            nOrderBy: 0,
+            aOrderBy: [],
+            colUsed: 0n,
+            aConstraintUsage: [],
+            idxNum: 0,
+            idxStr: FULL_SCAN_IDX_STR,
+            orderByConsumed: false,
+            estimatedCost: cost,
+            estimatedRows: BigInt(rows),
+            idxFlags: 0,
+        },
+    };
+}
+/**
+ * FilterInfo for a provably empty relation (an unsatisfiable predicate). Distinct from
+ * {@link makeFullScanFilterInfo} so a consumer can tell "no index" from "no rows".
+ */
+export function makeEmptyFilterInfo() {
+    return {
+        idxNum: 0,
+        idxStr: EMPTY_IDX_STR,
+        constraints: [],
+        args: [],
+        accessPath: { kind: 'empty' },
+        indexInfoOutput: {
+            nConstraint: 0,
+            aConstraint: [],
+            nOrderBy: 0,
+            aOrderBy: [],
+            colUsed: 0n,
+            aConstraintUsage: [],
+            idxNum: 0,
+            idxStr: EMPTY_IDX_STR,
+            orderByConsumed: false,
+            estimatedCost: 0,
+            estimatedRows: 0n,
+            idxFlags: 0,
+        },
+    };
+}
+/**
+ * FilterInfo for an equality (point/prefix) seek over `index`: one EQ constraint per
+ * entry of `seekColumnIndexes`, bound positionally to `values`.
+ *
+ * Used by the isolation layer's primary-key point lookups and by any caller that must
+ * drive an O(log n) seek instead of a scan.
+ */
+export function makeIndexEqSeekFilterInfo(index, seekColumnIndexes, values) {
+    const constraints = seekColumnIndexes.map((columnIndex, i) => ({
+        constraint: { iColumn: columnIndex, op: IndexConstraintOp.EQ, usable: true },
+        argvIndex: i + 1,
+    }));
+    const idxStr = encodeIdxStr(makeIdxStrSpec(index.name, 'eqSeek'));
+    return {
+        idxNum: 0,
+        idxStr,
+        constraints,
+        args: values,
+        accessPath: { kind: 'index', index, plan: 'eqSeek' },
+        indexInfoOutput: {
+            nConstraint: constraints.length,
+            aConstraint: constraints.map(c => c.constraint),
+            nOrderBy: 0,
+            aOrderBy: [],
+            colUsed: 0n,
+            aConstraintUsage: constraints.map(c => ({ argvIndex: c.argvIndex, omit: true })),
+            idxNum: 0,
+            idxStr,
+            orderByConsumed: false,
+            estimatedCost: 1,
+            estimatedRows: 1n,
+            idxFlags: 0,
+        },
+    };
+}
+/**
+ * Rewrite the index name across `idxStr`, `indexInfoOutput.idxStr`, and
+ * `accessPath.index.name` (or `accessPath.indexName` when unresolved).
+ *
+ * A module may advertise a per-plan alias for an index (`_primary_1`) that a wrapping
+ * table's delegate does not know. Retargeting rewrites only the name; `plan`, `nameArg`,
+ * and every parameter — including ones this engine does not understand — survive verbatim.
+ * A FilterInfo naming no index (full scan / empty) is returned unchanged.
+ */
+export function retargetFilterInfoIndex(filterInfo, newIndexName) {
+    const idxStr = retargetIdxStr(filterInfo.idxStr, newIndexName);
+    const outIdxStr = retargetIdxStr(filterInfo.indexInfoOutput.idxStr, newIndexName);
+    const accessPath = retargetAccessPath(filterInfo.accessPath, newIndexName);
+    if (idxStr === filterInfo.idxStr && outIdxStr === filterInfo.indexInfoOutput.idxStr && accessPath === filterInfo.accessPath) {
+        return filterInfo;
+    }
+    return {
+        ...filterInfo,
+        idxStr,
+        ...(accessPath ? { accessPath } : {}),
+        indexInfoOutput: { ...filterInfo.indexInfoOutput, idxStr: outIdxStr },
+    };
+}
+function retargetAccessPath(accessPath, newIndexName) {
+    if (!accessPath)
+        return undefined;
+    switch (accessPath.kind) {
+        case 'index':
+            if (accessPath.index.name === newIndexName)
+                return accessPath;
+            return { ...accessPath, index: { ...accessPath.index, name: newIndexName } };
+        case 'unresolvedIndex':
+            if (accessPath.indexName === newIndexName)
+                return accessPath;
+            return { ...accessPath, indexName: newIndexName };
+        default:
+            return accessPath;
+    }
+}
 //# sourceMappingURL=filter-info.js.map

package/dist/src/vtab/filter-info.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter-info.js","sourceRoot":"","sources":["../../../src/vtab/filter-info.ts"],"names":[],"mappings":""}
+{"version":3,"file":"filter-info.js","sourceRoot":"","sources":["../../../src/vtab/filter-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAI3D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAkD5E,wEAAwE;AACxE,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAErC,qFAAqF;AACrF,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAI,GAAG,SAAS,EAAE,IAAI,GAAG,SAAS;IACxE,OAAO;QACN,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,iBAAiB;QACzB,WAAW,EAAE,EAAE;QACf,IAAI,EAAE,EAAE;QACR,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;QAChC,eAAe,EAAE;YAChB,WAAW,EAAE,CAAC;YACd,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,EAAE;YACX,gBAAgB,EAAE,EAAE;YACpB,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,iBAAiB;YACzB,eAAe,EAAE,KAAK;YACtB,aAAa,EAAE,IAAI;YACnB,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC;YAC3B,QAAQ,EAAE,CAAC;SACX;KACD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IAClC,OAAO;QACN,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,aAAa;QACrB,WAAW,EAAE,EAAE;QACf,IAAI,EAAE,EAAE;QACR,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;QAC7B,eAAe,EAAE;YAChB,WAAW,EAAE,CAAC;YACd,WAAW,EAAE,EAAE;YACf,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,EAAE;YACX,gBAAgB,EAAE,EAAE;YACpB,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,aAAa;YACrB,eAAe,EAAE,KAAK;YACtB,aAAa,EAAE,CAAC;YAChB,aAAa,EAAE,EAAE;YACjB,QAAQ,EAAE,CAAC;SACX;KACD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CACxC,KAAsB,EACtB,iBAAoC,EACpC,MAA2B;IAE3B,MAAM,WAAW,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9D,UAAU,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;QAC5E,SAAS,EAAE,CAAC,GAAG,CAAC;KAChB,CAAC,CAAC,CAAC;IACJ,MAAM,MAAM,GAAG,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAElE,OAAO;QACN,MAAM,EAAE,CAAC;QACT,MAAM;QACN,WAAW;QACX,IAAI,EAAE,MAAM;QACZ,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE;QACpD,eAAe,EAAE;YAChB,WAAW,EAAE,WAAW,CAAC,MAAM;YAC/B,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;YAC/C,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,EAAE;YACX,gBAAgB,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAChF,MAAM,EAAE,CAAC;YACT,MAAM;YACN,eAAe,EAAE,KAAK;YACtB,aAAa,EAAE,CAAC;YAChB,aAAa,EAAE,EAAE;YACjB,QAAQ,EAAE,CAAC;SACX;KACD,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAsB,EAAE,YAAoB;IACnF,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,cAAc,CAAC,UAAU,CAAC,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAClF,MAAM,UAAU,GAAG,kBAAkB,CAAC,UAAU,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAE3E,IAAI,MAAM,KAAK,UAAU,CAAC,MAAM,IAAI,SAAS,KAAK,UAAU,CAAC,eAAe,CAAC,MAAM,IAAI,UAAU,KAAK,UAAU,CAAC,UAAU,EAAE,CAAC;QAC7H,OAAO,UAAU,CAAC;IACnB,CAAC;IAED,OAAO;QACN,GAAG,UAAU;QACb,MAAM;QACN,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,eAAe,EAAE,EAAE,GAAG,UAAU,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE;KACrE,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,UAAkC,EAAE,YAAoB;IACnF,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAClC,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACzB,KAAK,OAAO;YACX,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY;gBAAE,OAAO,UAAU,CAAC;YAC9D,OAAO,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC;QAC9E,KAAK,iBAAiB;YACrB,IAAI,UAAU,CAAC,SAAS,KAAK,YAAY;gBAAE,OAAO,UAAU,CAAC;YAC7D,OAAO,EAAE,GAAG,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;QACnD;YACC,OAAO,UAAU,CAAC;IACpB,CAAC;AACF,CAAC"}

package/dist/src/vtab/idx-str.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The `idxStr` wire format: one encoder, one decoder.
+ *
+ * `FilterInfo.idxStr` is the text the planner hands a module's runtime to say which
+ * index it chose and how it means to walk it. Its shape is:
+ *
+ *     idx=<indexName>(<nameArg>);plan=<code>[;<key>=<value>]*
+ *
+ * plus two sentinels — `fullscan` (no index) and `empty` (provably no rows). Every
+ * producer and consumer in the engine goes through this module, so the format is
+ * defined in exactly one place. The structured, typed form of the same information
+ * is `FilterInfo.accessPath` (see `index-descriptor.ts`); prefer that when you need
+ * to know *what the index is* rather than what to hand a module runtime.
+ */
+import type { IndexPlanKind } from './index-descriptor.js';
+/** Parsed form of an `idx=name(n);plan=N;…` string. */
+export interface IdxStrSpec {
+    readonly indexName: string;
+    /** The `(n)` group after the name. The planner always emits 0; aliasing modules may not. */
+    readonly nameArg: number;
+    /** The numeric `plan=` code. Not narrowed to {@link IndexPlanKind}: unknown codes round-trip. */
+    readonly plan: number;
+    /**
+     * Remaining `k=v` parameters in source order (inCount, seekWidth, prefixLen,
+     * rangeCount, rangeOps, argvMap, ordCons, …). Insertion-ordered so that
+     * `encodeIdxStr(decodeIdxStr(s))` reproduces `s` byte-for-byte.
+     */
+    readonly params: ReadonlyMap<string, string>;
+}
+/** The {@link IndexPlanKind} for a `plan=` code, or undefined for a code this engine never emits. */
+export declare function planKindFromCode(code: number): IndexPlanKind | undefined;
+/** The `plan=` code for an {@link IndexPlanKind}. Total — every kind has a code. */
+export declare function planCodeFromKind(kind: IndexPlanKind): number;
+/**
+ * Distinguish the two sentinel strings from a genuine index string.
+ * Returns null for `null`, `''`, and anything that is not a sentinel.
+ */
+export declare function idxStrSentinel(idxStr: string | null): 'fullScan' | 'empty' | null;
+/** Render an {@link IdxStrSpec} to its wire form. */
+export declare function encodeIdxStr(spec: IdxStrSpec): string;
+/**
+ * Parse an `idxStr`.
+ *
+ * Returns null for `null`, `''`, the `fullscan` / `empty` sentinels, and any string
+ * without a parseable `idx=<name>(<n>)` term — i.e. exactly the cases where no index
+ * is named. Use {@link idxStrSentinel} to tell the two sentinels apart from garbage.
+ *
+ * A parameter's value may contain `=`, `:` and `,` (e.g. `rangeOps=ge:lt,gt`); only the
+ * FIRST `=` in each `;`-separated term separates key from value.
+ */
+export declare function decodeIdxStr(idxStr: string | null): IdxStrSpec | null;
+/**
+ * Rename the index inside an `idxStr`, preserving `plan`, `nameArg`, and every parameter
+ * verbatim — including parameters and plan codes this engine does not understand. Strings
+ * that name no index (sentinels, null, garbage) are returned unchanged.
+ *
+ * Implemented as decode → swap name → encode, so it cannot corrupt what it cannot read.
+ */
+export declare function retargetIdxStr(idxStr: string | null, newIndexName: string): string | null;
+/** Build an {@link IdxStrSpec} for a plan the engine itself chose. `nameArg` is always 0. */
+export declare function makeIdxStrSpec(indexName: string, plan: IndexPlanKind, params?: ReadonlyMap<string, string>): IdxStrSpec;
+//# sourceMappingURL=idx-str.d.ts.map

package/dist/src/vtab/idx-str.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idx-str.d.ts","sourceRoot":"","sources":["../../../src/vtab/idx-str.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,uDAAuD;AACvD,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAwBD,qGAAqG;AACrG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAExE;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAM5D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,OAAO,GAAG,IAAI,CAIjF;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CASrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAgCrE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKzF;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,UAAU,CAEZ"}