@quereus/quereus 4.4.1 → 4.6.0

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

@@ -38,6 +38,39 @@ export interface RangeSpec {
         value: SqlValue;
     };
 }
+/**
+ * Describes an `IN` constraint whose member values are produced at execution time
+ * (typically from a subquery), so the planner cannot name them. Present ⇒ `value`
+ * is absent.
+ *
+ * A module that accepts such a constraint (`handledFilters[i] = true`, plus
+ * `indexName` and `seekColumnIndexes`) promises only that it can serve the column as
+ * a multi-seek on the named index. In exchange the engine promises that at `query()`
+ * time the module receives an ordinary `plan=5` multi-seek `FilterInfo` — the same
+ * shape a literal `IN (…)` list produces, with `1 ≤ K ≤ maxCount` seek keys — so no
+ * module runtime needs to change and nothing distinguishes a runtime-derived set from
+ * a hand-written list. Declining is always safe. See `docs/module-authoring.md`
+ * § "Runtime-valued `IN` sets".
+ */
+export interface RuntimeSetSpec {
+    /**
+     * Hard ceiling on the number of seek keys the engine will deliver at query() time.
+     * The engine enforces it: a larger set never reaches the module — the engine falls
+     * back to a full scan on its own.
+     */
+    readonly maxCount: number;
+    /**
+     * Planner's estimate of the actual count, when it has one. Advisory — a module may
+     * price against it but must still be correct for any count in `1..maxCount`. When
+     * present it is an integer in `0..maxCount` (0 meaning "probably empty").
+     *
+     * NOTE: no shipped module reads this — both price against `maxCount`, i.e. worst case.
+     * If the engine ever probes with a large ceiling for a typically tiny set, those plans
+     * will look more expensive than they are and may lose to a scan they should beat;
+     * blend `estimatedCount` into the cost (not into the safety gates) at that point.
+     */
+    readonly estimatedCount?: number;
+}
 /**
  * A predicate constraint extracted from WHERE clause
  */
@@ -52,7 +85,49 @@ export interface PredicateConstraint {
     usable: boolean;
     /** Range specifications for OR_RANGE constraints */
     ranges?: RangeSpec[];
+    /**
+     * Set only when `op === 'IN'` and the members are not known at plan time.
+     * Mutually exclusive with `value` — see {@link RuntimeSetSpec}.
+     */
+    readonly runtimeSet?: RuntimeSetSpec;
 }
+/**
+ * Number of seek keys an equality-role filter contributes at plan time, or null when
+ * the filter cannot fill an equality role at all:
+ *
+ *   `=`                    → 1
+ *   literal `IN`           → `value.length` (elements may be `undefined` for parameter
+ *                            bindings — only the LENGTH is meaningful at plan time)
+ *   runtime-set `IN`       → `runtimeSet.maxCount`, the WORST case; the delivered count
+ *                            is anywhere in `1..maxCount`
+ *   anything else          → null
+ *
+ * A malformed shape — an empty literal list, a `maxCount` that is not a positive integer —
+ * returns null, so a module declines it and it survives as a residual. That mirrors the
+ * literal arm's long-standing non-empty-array gate and holds even when
+ * {@link validateAccessPlanRequest} was never called (the store module, for one, does not
+ * call it), so a bad request degrades to a scan rather than to a zero-key seek.
+ *
+ * For plan-time-known values this mirrors the exact predicate
+ * `rule-select-access-path`'s `eqBySeekCol` uses to pick its per-column equality
+ * constraint, so a module's positional claim and the rule's pick cannot disagree. The
+ * runtime-set arm has no counterpart there because nothing in the planner emits
+ * `runtimeSet` yet — `feat-key-set-semi-join` supplies the engine half and lowers a
+ * runtime set to a literal seek-key list before the rule ever sees it.
+ */
+export declare function equalitySeekKeyCount(f: PredicateConstraint): number | null;
+/**
+ * True when the filter may seek more than one key — i.e. it walks the index in seek-key
+ * order rather than column order, so a plan built on it cannot claim `providesOrdering`
+ * over that column and is not a scan-constant.
+ *
+ * A well-formed runtime set is ALWAYS multi-valued here, even at `maxCount === 1`: the
+ * delivered count is not knowable at plan time, and mistaking a multi-seek for a constant
+ * would elide a `Sort` the plan needs. (That is the one case where this disagrees with
+ * `equalitySeekKeyCount(f) > 1`; the conservative answer is the safe one.) A malformed
+ * one fills no equality role at all, so it is not multi-valued either.
+ */
+export declare function isMultiValueEquality(f: PredicateConstraint): boolean;
 /**
  * Ordering specification for ORDER BY clauses
  */
@@ -248,6 +323,18 @@ export declare class AccessPlanBuilder {
      */
     build(): BestAccessPlanResult;
 }
+/**
+ * Validate the REQUEST the engine hands a module, before the module can improvise on a
+ * shape it was never promised. Called from {@link validateAccessPlan}, so every module
+ * that follows the validate-your-plan convention gets it without a second call site.
+ *
+ * The checks are all on {@link RuntimeSetSpec}: it must ride an `IN`, it must not carry
+ * plan-time `value`s (a module reading `value` on a runtime set would seek on garbage),
+ * its ceiling must be a usable count, and an advisory `estimatedCount` must fall within
+ * that ceiling — an estimate above `maxCount` describes a set the engine has promised
+ * never to deliver, so it is an engine bug rather than a pessimistic guess.
+ */
+export declare function validateAccessPlanRequest(request: BestAccessPlanRequest): void;
 /**
  * Validation function for access plan results
  * Throws if the plan violates basic contracts

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":"AAAA;;;GAGG;AAGH,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhJ;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,qDAAqD;IACrD,YAAY,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACzB,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,IAAI,GAAG,GAAG,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC5C,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,IAAI,GAAG,GAAG,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,EAAE,EAAE,YAAY,CAAC;IACjB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,oCAAoC;IACpC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,wDAAwD;IACxD,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,kFAAkF;IAClF,cAAc,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,kEAAkE;IAClE,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;IACvC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC;KAChB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAEpC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,MAAM,CAAqC;IAEnD;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,iBAAiB;IAOzD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,iBAAiB;IAQ/E;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,iBAAiB;IAOnF;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAKvC;;OAEG;IACH,iBAAiB,CAAC,cAAc,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAK3D;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,IAAI;IAKpD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAK9B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKzC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKrC;;;OAGG;IACH,kBAAkB,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI;IAK1D;;OAEG;IACH,cAAc,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAK1D;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,IAAI;IAKtD;;OAEG;IACH,KAAK,IAAI,oBAAoB;CAW7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,EAAE,oBAAoB,GAC1B,IAAI,CAsGN"}
+{"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

@@ -5,6 +5,62 @@
 import { quereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
 import { validateIndexDescriptor } from './index-descriptor.js';
+/**
+ * Number of seek keys an equality-role filter contributes at plan time, or null when
+ * the filter cannot fill an equality role at all:
+ *
+ *   `=`                    → 1
+ *   literal `IN`           → `value.length` (elements may be `undefined` for parameter
+ *                            bindings — only the LENGTH is meaningful at plan time)
+ *   runtime-set `IN`       → `runtimeSet.maxCount`, the WORST case; the delivered count
+ *                            is anywhere in `1..maxCount`
+ *   anything else          → null
+ *
+ * A malformed shape — an empty literal list, a `maxCount` that is not a positive integer —
+ * returns null, so a module declines it and it survives as a residual. That mirrors the
+ * literal arm's long-standing non-empty-array gate and holds even when
+ * {@link validateAccessPlanRequest} was never called (the store module, for one, does not
+ * call it), so a bad request degrades to a scan rather than to a zero-key seek.
+ *
+ * For plan-time-known values this mirrors the exact predicate
+ * `rule-select-access-path`'s `eqBySeekCol` uses to pick its per-column equality
+ * constraint, so a module's positional claim and the rule's pick cannot disagree. The
+ * runtime-set arm has no counterpart there because nothing in the planner emits
+ * `runtimeSet` yet — `feat-key-set-semi-join` supplies the engine half and lowers a
+ * runtime set to a literal seek-key list before the rule ever sees it.
+ */
+export function equalitySeekKeyCount(f) {
+    if (f.op === '=')
+        return 1;
+    if (f.op === 'IN') {
+        if (f.runtimeSet) {
+            const { maxCount } = f.runtimeSet;
+            return Number.isInteger(maxCount) && maxCount > 0 ? maxCount : null;
+        }
+        if (Array.isArray(f.value) && f.value.length > 0) {
+            return f.value.length;
+        }
+    }
+    return null;
+}
+/**
+ * True when the filter may seek more than one key — i.e. it walks the index in seek-key
+ * order rather than column order, so a plan built on it cannot claim `providesOrdering`
+ * over that column and is not a scan-constant.
+ *
+ * A well-formed runtime set is ALWAYS multi-valued here, even at `maxCount === 1`: the
+ * delivered count is not knowable at plan time, and mistaking a multi-seek for a constant
+ * would elide a `Sort` the plan needs. (That is the one case where this disagrees with
+ * `equalitySeekKeyCount(f) > 1`; the conservative answer is the safe one.) A malformed
+ * one fills no equality role at all, so it is not multi-valued either.
+ */
+export function isMultiValueEquality(f) {
+    if (f.op !== 'IN')
+        return false;
+    if (f.runtimeSet)
+        return equalitySeekKeyCount(f) !== null;
+    return Array.isArray(f.value) && f.value.length > 1;
+}
 /**
  * Builder class for constructing access plan results
  */
@@ -123,11 +179,42 @@ export class AccessPlanBuilder {
         return this.result;
     }
 }
+/**
+ * Validate the REQUEST the engine hands a module, before the module can improvise on a
+ * shape it was never promised. Called from {@link validateAccessPlan}, so every module
+ * that follows the validate-your-plan convention gets it without a second call site.
+ *
+ * The checks are all on {@link RuntimeSetSpec}: it must ride an `IN`, it must not carry
+ * plan-time `value`s (a module reading `value` on a runtime set would seek on garbage),
+ * its ceiling must be a usable count, and an advisory `estimatedCount` must fall within
+ * that ceiling — an estimate above `maxCount` describes a set the engine has promised
+ * never to deliver, so it is an engine bug rather than a pessimistic guess.
+ */
+export function validateAccessPlanRequest(request) {
+    for (const filter of request.filters) {
+        if (!filter.runtimeSet)
+            continue;
+        if (filter.op !== 'IN') {
+            quereusError(`runtimeSet is only valid on an 'IN' constraint, got '${filter.op}' on column ${filter.columnIndex}`, StatusCode.FORMAT);
+        }
+        if (filter.value !== undefined) {
+            quereusError(`runtimeSet and value are mutually exclusive (column ${filter.columnIndex}); a runtime set has no plan-time members`, StatusCode.FORMAT);
+        }
+        const { maxCount, estimatedCount } = filter.runtimeSet;
+        if (!Number.isInteger(maxCount) || maxCount < 1) {
+            quereusError(`runtimeSet.maxCount must be an integer >= 1, got ${maxCount} on column ${filter.columnIndex}`, StatusCode.FORMAT);
+        }
+        if (estimatedCount !== undefined && (!Number.isInteger(estimatedCount) || estimatedCount < 0 || estimatedCount > maxCount)) {
+            quereusError(`runtimeSet.estimatedCount must be an integer in 0..${maxCount}, got ${estimatedCount} on column ${filter.columnIndex}`, StatusCode.FORMAT);
+        }
+    }
+}
 /**
  * Validation function for access plan results
  * Throws if the plan violates basic contracts
  */
 export function validateAccessPlan(request, result) {
+    validateAccessPlanRequest(request);
     // Validate handledFilters array length
     if (result.handledFilters.length !== request.filters.length) {
         quereusError(`handledFilters length (${result.handledFilters.length}) must match filters length (${request.filters.length})`, StatusCode.FORMAT);

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

@@ -24,7 +24,7 @@ import type { SqlValue, Row, CompareFn } from '../common/types.js';
  * 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".
+ * and docs/module-capabilities.md § "DDL transactionality tiers".
  */
 export type DdlTransactionality = 'transactional' | 'non-transactional' | 'auto-commit';
 /**

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

@@ -10,6 +10,10 @@ import type { AnyVirtualTableModule } from './module.js';
 export declare function tryGetEventEmitter(module: AnyVirtualTableModule): VTableEventEmitter | undefined;
 /**
  * Data change event emitted when mutations are committed.
+ *
+ * Producers owe the key contract in `docs/usage.md` § Subscribing to Data Changes: `key` is
+ * projected from the event's own row image, and an `update` never moves a row (a relocating
+ * primary-key change is a `delete` at the old key then an `insert` at the new one).
  */
 export interface VTableDataChangeEvent {
     /** The type of mutation operation */
@@ -18,7 +22,7 @@ export interface VTableDataChangeEvent {
     schemaName: string;
     /** Table name */
     tableName: string;
-    /** Primary key values */
+    /** Primary key projected from this event's own image: `newRow` for insert/update, `oldRow` for delete */
     key?: SqlValue[];
     /** Previous row data (for update/delete) */
     oldRow?: Row;

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/vtab/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKzD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,GAAG,kBAAkB,GAAG,SAAS,CAQhG;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,qCAAqC;IACrC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACrC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uCAAuC;IACvC,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,mCAAmC;IACnC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAClC,wCAAwC;IACxC,UAAU,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IACzC,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,CAAC;AAElF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,YAAY,CAAC,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAAC;IAE9D;;OAEG;IACH,gBAAgB,CAAC,IAAI,OAAO,CAAC;IAE7B;;OAEG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAEpD;;OAEG;IACH,UAAU,CAAC,IAAI,IAAI,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,IAAI,IAAI,CAAC;IAEpB;;OAEG;IACH,YAAY,CAAC,IAAI,IAAI,CAAC;IAEtB;;;OAGG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,0BAA0B,GAAG,MAAM,IAAI,CAAC;IAElE;;OAEG;IACH,kBAAkB,CAAC,IAAI,OAAO,CAAC;IAE/B;;OAEG;IACH,gBAAgB,CAAC,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAExD;;OAEG;IACH,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC5B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACnE,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,UAAU,CAAS;IAE3B,YAAY,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI;IAK5D,gBAAgB,IAAI,OAAO;IAI3B,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI;IAgBlD,UAAU,IAAI,IAAI;IAKlB,UAAU,IAAI,IAAI;IAiBlB,YAAY,IAAI,IAAI;IAKpB,cAAc,CAAC,QAAQ,EAAE,0BAA0B,GAAG,MAAM,IAAI;IAKhE,kBAAkB,IAAI,OAAO;IAI7B,gBAAgB,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI;IAWtD,kBAAkB,IAAI,IAAI;CAM1B"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/vtab/events.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/vtab/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/vtab/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,GAAG,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA6B;IAC/D,MAAM,QAAQ,GAAG,MAA6C,CAAC;IAC/D,IAAI,OAAO,QAAQ,CAAC,eAAe,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IACrE,MAAM,OAAO,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;IAC3C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,KAAK,GAAG,OAA+D,CAAC;IAC9E,IAAI,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,cAAc,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAC7G,OAAO,OAA6B,CAAC;AACtC,CAAC;AA+GD;;;GAGG;AACH,MAAM,OAAO,yBAAyB;IAC7B,aAAa,GAAkC,IAAI,GAAG,EAAE,CAAC;IACzD,eAAe,GAAoC,IAAI,GAAG,EAAE,CAAC;IAC7D,iBAAiB,GAA4B,EAAE,CAAC;IAChD,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAY,CAAC,QAAkC;QAC9C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,gBAAgB;QACf,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,cAAc,CAAC,KAA4B;QAC1C,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnC,OAAO;QACR,CAAC;QAED,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACJ,QAAQ,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,QAAQ,CAAC,8CAA8C,EACtD,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YACpD,CAAC;QACF,CAAC;IACF,CAAC;IAED,UAAU;QACT,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC;IAC7B,CAAC;IAED,UAAU;QACT,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACtC,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC;QAE5B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC5B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBAC3C,IAAI,CAAC;oBACJ,QAAQ,CAAC,KAAK,CAAC,CAAC;gBACjB,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACZ,QAAQ,CAAC,8CAA8C,EACtD,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBACpD,CAAC;YACF,CAAC;QACF,CAAC;IACF,CAAC;IAED,YAAY;QACX,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC;IAC7B,CAAC;IAED,cAAc,CAAC,QAAoC;QAClD,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED,kBAAkB;QACjB,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,gBAAgB,CAAC,KAA8B;QAC9C,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACJ,QAAQ,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACZ,QAAQ,CAAC,8CAA8C,EACtD,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;YACrD,CAAC;QACF,CAAC;IACF,CAAC;IAED,kBAAkB;QACjB,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IACzB,CAAC;CACD"}

package/dist/src/vtab/memory/layer/alter-column.d.ts

@@ -0,0 +1,147 @@
+import type { Expression } from '../../../parser/ast.js';
+import type { ColumnSchema } from '../../../schema/column.js';
+import { type TableSchema } from '../../../schema/table.js';
+import { type SqlValue } from '../../../common/types.js';
+import type { Row } from '../../../common/types.js';
+/**
+ * The decide-and-validate half of `MemoryTableManager.alterColumn`.
+ *
+ * Everything here is a function of the PRE-change {@link TableSchema} plus the DDL
+ * transaction's effective rows. It may THROW — that is how an illegal ALTER is rejected —
+ * but it never mutates the manager, the base layer, or any open transaction layer. That
+ * split is the "validate before any mutation" guarantee the ALTER paths depend on: the
+ * manager runs every function in this file (plus its own re-keyed UNIQUE / primary-key
+ * probes) before its first write, so a rejection leaves the table exactly as it was.
+ *
+ * The apply half — base rebuild, open-layer propagation, rollback — stays on the manager,
+ * which owns that state.
+ */
+/** The single-attribute change one `alter column` statement asks for. */
+export interface AlterColumnChange {
+    columnName: string;
+    setNotNull?: boolean;
+    setDataType?: string;
+    setDefault?: Expression | null;
+    setCollation?: string;
+}
+/**
+ * A physical rewrite of every stored value in the altered column: `set data type` (every
+ * non-alias retype — values normalize to the new type's canonical spelling even when the
+ * storage class is unchanged) and the `set not null` null → DEFAULT backfill.
+ *
+ * The manager applies it by REPLACING the base primary tree with a freshly-built one (never
+ * an in-place mutation, which inheritree forbids while the open transaction's layers derive
+ * from it) and converting the transaction's own-written rows in every open layer.
+ */
+export interface ValueRewrite {
+    readonly convert: (v: SqlValue) => SqlValue;
+    /**
+     * Route NULLs through `convert` too. Set by the `set not null` backfill (null → DEFAULT);
+     * `set data type` leaves nulls untouched.
+     */
+    readonly convertNulls: boolean;
+}
+/** What one attribute handler decided: the column schema it produces, plus its consequences. */
+export interface ColumnAttributeChange {
+    readonly newCol: ColumnSchema;
+    /**
+     * The collation NAME moved, which re-keys any PK / UNIQUE / index that orders by this
+     * column — so the structures need the re-sort + uniqueness re-validation. False for a
+     * metadata-only `set collate` that merely marks an already-matching collation explicit.
+     */
+    readonly collationChanged: boolean;
+    /**
+     * A `set data type` moved to a type that ORDERS values differently
+     * ({@link comparisonSemanticsDiffer}). Same consequence as a collation change — every
+     * structure keyed by the column has to be re-sorted and its uniqueness re-judged — but a
+     * separate flag, because the index-column collation propagation and the primary-tree
+     * re-key belong to `set collate` alone. Usually coincides with {@link rewrite} (every
+     * non-alias retype sets that), whose full-rebuild path subsumes the comparator-only re-sort.
+     */
+    readonly comparatorChanged: boolean;
+    /** Set when the stored values themselves must be rewritten; null for a schema-only change. */
+    readonly rewrite: ValueRewrite | null;
+}
+/** {@link ColumnAttributeChange} resolved against the table: post-change schema + rebuild consequences. */
+export interface AlterColumnPlan {
+    readonly colIndex: number;
+    readonly newSchema: TableSchema;
+    readonly rewrite: ValueRewrite | null;
+    /**
+     * The comparators the structures are keyed by moved: `set collate` (values untouched) or a
+     * retype into a differently-ordering type (which, unless it is an alias retype, ALSO sets
+     * {@link rewrite}, whose full-rebuild path subsumes the comparator-only re-sort).
+     */
+    readonly structuresRekeyed: boolean;
+    /** `set collate` moved a PRIMARY KEY member's collation — the primary tree itself re-keys. */
+    readonly pkColumnRekeyed: boolean;
+}
+/**
+ * The DDL transaction's EFFECTIVE rows: committed rows overlaid with its own pending writes. A
+ * value the transaction can SEE rejects the ALTER; one only in a row it has DELETED does not block
+ * it. Re-callable — each scan gets a fresh stream.
+ *
+ * Either flavour: the manager's own layered walk is synchronous, a wrapper module's overlay (the
+ * isolation layer) is an `EffectiveRowSource` and therefore async. {@link scanEffectiveRows} keeps
+ * the sync one sync.
+ */
+export type EffectiveRows = () => Iterable<Row> | AsyncIterable<Row>;
+/** Everything the attribute handlers read beyond the change itself. */
+export interface AlterColumnContext {
+    readonly schema: TableSchema;
+    readonly tableName: string;
+    /** The column name as the statement spelled it — error messages echo it verbatim. */
+    readonly columnName: string;
+    readonly colIndex: number;
+    readonly effectiveRows: EffectiveRows;
+    readonly isCollationRegistered: (name: string) => boolean;
+}
+/**
+ * Resolve the one populated attribute in `change`. Returns null when the column is already in
+ * the requested state — a no-op ALTER the manager returns from without touching anything.
+ */
+export declare function planColumnAttributeChange(ctx: AlterColumnContext, change: AlterColumnChange): Promise<ColumnAttributeChange | null>;
+/**
+ * `set collate`. A user declaration with the same standing as a CREATE-time COLLATE clause, so
+ * the collation is marked explicit (rank 2 in the comparison lattice) regardless of the column's
+ * creation history — including `set collate binary`. When only the name matches but the column
+ * was not yet explicit (a defaulted collation, or one inherited from session default_collation),
+ * flipping the flag is METADATA-ONLY: the collation bytes are unchanged, so the physical re-sort
+ * / re-key / UNIQUE re-validation are skipped. A different name takes the full path.
+ */
+export declare function planSetCollation(ctx: AlterColumnContext, requested: string): ColumnAttributeChange | null;
+/** `set not null` / `drop not null`. */
+export declare function planSetNotNull(ctx: AlterColumnContext, setNotNull: boolean): Promise<ColumnAttributeChange | null>;
+/**
+ * `set data type`.
+ *
+ * Gates on logical-type IDENTITY, not the physical storage class: `inferType` flattens aliases to
+ * the shared type object (`varchar(50)` IS `TEXT_TYPE`, `bigint` IS `INTEGER_TYPE`), so an alias
+ * retype is schema-only — no scan, no rewrite, no re-key. Every OTHER retype validates AND
+ * normalizes every value, whether or not the storage class changes: a same-class move (text →
+ * date) must reject values the new type refuses ('hello') and rewrite the rest to the new type's
+ * canonical spelling ('2024-06-05T00:00:00Z' → '2024-06-05'), or the column holds values no
+ * INSERT could have produced — unfindable by equality (DATE compares BINARY over the stored text)
+ * and invisible to UNIQUE.
+ *
+ * NOTE: the rewrite is unconditional once the types differ, even when every converted value comes
+ * back byte-identical (already-canonical ISO durations on a text → timespan). That costs a full
+ * base-tree + secondary-index rebuild, and a physical rewrite of every row on the store leg. If
+ * ALTER on large tables ever shows up as slow, have the convert pre-pass record whether any value
+ * actually moved and, when none did, fall through to the comparator-only re-key.
+ */
+export declare function planSetDataType(ctx: AlterColumnContext, dataType: string): Promise<ColumnAttributeChange>;
+/**
+ * Build the post-change {@link TableSchema} and the flags the apply half keys off.
+ *
+ * Every re-keying change REBUILDS the IndexSchema objects, because their identity is the
+ * discriminator `TransactionLayer.adoptSchema` uses to decide an open layer's MemoryIndex must be
+ * replaced rather than kept (an index it holds under an object the new schema still carries is
+ * left alone). SET COLLATE has a field to write — the index column's own collation. A
+ * comparator-only retype has none: an index column carries no logical type, it reads the column's
+ * from `newSchema.columns`, so the fresh object IS the whole signal. Without it the base rebuilt
+ * its trees under the new comparator while the DDL transaction's own layers went on comparing the
+ * old way — and shadowed the base's rebuilt trees once the pending layer became the committed head.
+ */
+export declare function buildAlterColumnPlan(schema: TableSchema, colIndex: number, change: ColumnAttributeChange): AlterColumnPlan;
+//# sourceMappingURL=alter-column.d.ts.map

package/dist/src/vtab/memory/layer/alter-column.d.ts.map

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