@quereus/quereus 4.8.0 → 4.10.0

package/dist/src/runtime/emit/materialized-view-helpers.js

@@ -777,14 +777,30 @@ function hasApplicableConstraints(db, mt) {
  * the LIVE record here. So the live record is swapped for a constraint-stripped
  * clone for the duration of the scans (the ADD COLUMN intermediate-schema
  * discipline, see `runtime/emit/alter-table.ts`), then restored.
+ *
+ * `validationColumns` (the reshape arms only, {@link previewReshapedColumns})
+ * overrides the clone's column list with the attributes the reshape is ABOUT TO
+ * land, so a CHECK / FK resolves its affinity and collation from the final
+ * declared shape rather than the one being replaced. Comparison semantics are a
+ * function of the DECLARED column attributes, and the reshape's `retype` /
+ * `recollate` module ops run after this scan (they convert stored rows, so they
+ * must); without the override this scan would evaluate `v < '9'` on a column
+ * moving TEXT → INTEGER as a text comparison and admit a row that violates the
+ * constraint under the type it is about to have. Omitted (⇒ `mt.columns`) on
+ * every non-reshape path, so those stay byte-identical.
  */
-async function validateDeclaredConstraintsOverContents(db, mt) {
+async function validateDeclaredConstraintsOverContents(db, mt, validationColumns) {
     const applicableChecks = mt.checkConstraints.filter(c => (c.operations & (RowOpFlag.INSERT | RowOpFlag.UPDATE)) !== 0);
     const fks = mt.foreignKeys ?? [];
     if (applicableChecks.length === 0 && fks.length === 0)
         return;
     const schema = db.schemaManager.getSchemaOrFail(mt.schemaName);
-    const stripped = { ...mt, checkConstraints: Object.freeze([]), foreignKeys: undefined };
+    const stripped = {
+        ...mt,
+        columns: validationColumns ?? mt.columns,
+        checkConstraints: Object.freeze([]),
+        foreignKeys: undefined,
+    };
     schema.addTable(stripped);
     try {
         await validateChecksOverExistingRows(db, mt, applicableChecks, (check, exprSql) => maintainedTableCheckViolationError(mt.schemaName, mt.name, check.name ?? `_check_${mt.checkConstraints.indexOf(check)}`, exprSql));
@@ -1079,8 +1095,11 @@ discardBackingOnFailure = false) {
         changes = await host.applyMaintenance(conn, [{ kind: 'replace-all', rows }]);
         // Declared CHECK / child-side FK over the reconciled (derived) row set —
         // inside this try so a violation restores the prior record; the pending
-        // reconcile writes roll back with the failing statement.
-        await validateDeclaredConstraintsOverContents(db, live);
+        // reconcile writes roll back with the failing statement. On the reshape arm
+        // the scan resolves against the attributes the post-reconcile ops below are
+        // about to land, keeping this path identical to the refresh reshape arm
+        // (`reshapeBackingInPlace` → `rebuildBacking`).
+        await validateDeclaredConstraintsOverContents(db, live, reshapePlan ? previewReshapedColumns(live, shape) : undefined);
         if (reshapePlan && reshapePlan.postReconcileOps.length > 0) {
             // Data-validating attribute ops (retype / recollate / tighten NOT NULL)
             // must validate the RECONCILED body rows, not the stale backing — but the
@@ -1320,8 +1339,14 @@ export async function createMaintainedTable(db, stmt) {
  * behavior. The caller is responsible for staleness re-validation when relevant;
  * this helper assumes the derivation body plans. Throws if the table is missing
  * from the catalog.
+ *
+ * `validationColumns` is the reshape arm's column preview
+ * ({@link previewReshapedColumns}) — the type/collation attributes the reshape's
+ * still-pending post-reconcile ops are about to land — forwarded to the scan so
+ * the CHECK / FK resolve against the final declared shape. `undefined` on every
+ * other path (and on a reshape that shifts neither attribute).
  */
-export async function rebuildBacking(db, mv) {
+export async function rebuildBacking(db, mv, validationColumns) {
     const bodySql = astToString(mv.derivation.selectAst);
     const rows = await collectBodyRows(db, mv.schemaName, bodySql);
     const backing = db.schemaManager.getTable(mv.schemaName, mv.name);
@@ -1367,23 +1392,15 @@ export async function rebuildBacking(db, mv) {
     // leaving the pre-refresh committed contents intact (the MV stays stale, so the
     // next read re-validates rather than serving the rejected set).
     //
-    // Documented limitation (collation-sensitive CHECK on the reshape arm): on the
-    // reshape path this scan validates the rows in their PRE-recollate physical form
-    // — the catalog column still carries the OLD collation here, and any
-    // `recollate` op runs post-reconcile in reshapeBackingInPlace, AFTER this commit.
-    // So a CHECK whose truth flips under a recollate-during-reshape (e.g. `v <> 'abc'`
-    // with v recollated BINARY → NOCASE over a row 'ABC') passes here and is then
-    // recollated into a violating state. The same class of corner applies to a
-    // `retype` op (it shares this `postReconcileOps` batch): a CHECK whose truth flips
-    // under the column's NEW affinity (e.g. `v < '9'` retyped TEXT → INTEGER over a
-    // row '10' — lexicographic-true then numeric-false) passes here and is retyped into
-    // violation. Not closed: this commit is load-bearing (commit-first parity + the
-    // post-reconcile ops scan committed contents), and the attach reshape path uses the
-    // identical ordering. See docs/materialized-views.md § REFRESH MATERIALIZED VIEW
-    // "Known limitation — collation-sensitive CHECK" / "… type-sensitive CHECK" and
-    // maintained-table-refresh-revalidation.spec.ts § "reshape arm: collation-
-    // sensitive CHECK" / "reshape arm: type-sensitive CHECK".
-    await validateDeclaredConstraintsOverContents(db, backing);
+    // On the reshape arm `validationColumns` carries the attributes the reshape is
+    // about to land ({@link previewReshapedColumns}), so a CHECK / FK is evaluated
+    // under the column's FINAL type and collation even though the `retype` /
+    // `recollate` module ops still run post-reconcile in reshapeBackingInPlace. That
+    // keeps this commit's ordering exactly as it was — the scan stays before the
+    // commit, the post-reconcile ops still scan committed contents — while removing
+    // the wrong-semantics gap. The attach reshape path passes the same preview at its
+    // own call site, so both arms reject identically.
+    await validateDeclaredConstraintsOverContents(db, backing, validationColumns);
     await conn.commit();
 }
 /**
@@ -2111,6 +2128,76 @@ function reshapeOpToChange(op) {
 function graftReshapedRecord(moduleSchema, source) {
     return { ...moduleSchema, derivation: source.derivation, tags: source.tags };
 }
+/**
+ * The column list a reshape is ABOUT TO land, for the declared-constraint scan that
+ * runs mid-reshape ({@link validateDeclaredConstraintsOverContents}).
+ *
+ * A reshape's data-validating ops (`retype` / `recollate`) must run AFTER the data
+ * reconcile — they convert/re-key STORED rows, so running them first would validate
+ * the about-to-be-discarded contents and throw spuriously. But a SQL comparison
+ * takes its type affinity and its collation from the column's DECLARED attributes,
+ * so a scan against the live (pre-op) record evaluates a declared CHECK under the
+ * attributes the reshape is replacing: `check (v < '9')` on a column moving
+ * TEXT → INTEGER compares as text ('10' < '9' is true) and never as the numeric
+ * comparison it is becoming. Previewing the attributes fixes the semantics without
+ * moving a single op — the scan stays exactly where it was, still before the commit.
+ *
+ * Maps `live`'s columns onto `shape`'s **by name** (names and order already agree:
+ * the reshape's pre-reconcile batch has applied every rename / add / drop before
+ * either caller reaches this) and overrides only `logicalType` and `collation`.
+ * Returns `undefined` when neither attribute shifts, so a reshape with no
+ * `retype`/`recollate` — and every non-reshape path — behaves exactly as before.
+ *
+ * Deliberately NOT previewed:
+ *  - **`notNull`.** The tighten-NOT-NULL op stays a post-reconcile module op and
+ *    keeps validating there. Declaring `notNull` early would let the optimizer fold
+ *    a nullability-sensitive CHECK into a vacuous pass — the same class of unsound
+ *    folding the caller's constraint-stripped-clone swap exists to prevent.
+ *  - **`defaultValue` and the generated-column attributes.** A reshape never moves
+ *    them, so previewing them could only introduce drift.
+ *
+ * Physical-PK columns need no special handling: `describePhysicalPkChange` refuses
+ * a reshape whose key column changes type or collation, so a previewed attribute
+ * can never desynchronize the key encoding `assertRefreshRowsAreSet` or the host's
+ * keyed diff rely on.
+ *
+ * NOTE: the scan sees the rebuilt values in their PRE-conversion physical form but
+ * under the POST-conversion declared type. These agree in practice — the target
+ * attribute is derived FROM the body's own output type, so the body already emits
+ * values of the new type. A retype whose conversion genuinely rewrites the value
+ * (a text → date canonicalization turning '2024-06-05T00:00:00Z' into '2024-06-05')
+ * would have the CHECK see the un-normalized spelling. Not chased; revisit if a
+ * value-rewriting conversion is ever added to the reshape's op set.
+ *
+ * NOTE: with the preview in place, a body emitting a value that does not conform to
+ * its own declared output type now trips the physical-representation checker
+ * (`QUEREUS_REPR_STRICT`) at this scan rather than sliding through. That is a
+ * genuine defect surfacing at the earliest honest point, not a regression.
+ *
+ * NOTE: this RE-DERIVES the attribute shift from live-vs-shape rather than reading
+ * `ReshapePlan.postReconcileOps`, which is the authoritative list of the `retype` /
+ * `recollate` ops that will actually run. The two agree today because the
+ * pre-reconcile structural ops preserve attributes exactly ({@link backingColumnDef}
+ * carries type + collation through a rename, and an `add` lands the shape column's
+ * own attributes), so every live-vs-shape shift has a queued op and vice versa. If a
+ * structural op ever stops preserving an attribute, this would preview an attribute
+ * no op lands and the scan would reject rows the finished reshape accepts — build the
+ * preview from `postReconcileOps` then.
+ */
+function previewReshapedColumns(live, shape) {
+    const byName = new Map(shape.columns.map(c => [c.name.toLowerCase(), c]));
+    let shifted = false;
+    const preview = live.columns.map(col => {
+        const target = byName.get(col.name.toLowerCase());
+        if (!target)
+            return col;
+        if (backingTypeMatches(col, target) && backingCollationMatches(col, target))
+            return col;
+        shifted = true;
+        return { ...col, logicalType: target.logicalType, collation: target.collation };
+    });
+    return shifted ? Object.freeze(preview) : undefined;
+}
 /**
  * The sited error a refresh raises when the re-derived body shape cannot be
  * reconciled onto the live maintained table in place — an interleaving column
@@ -2209,8 +2296,10 @@ async function reshapeBackingInPlace(db, mv, shape, plan) {
     let live = graftReshapedRecord(current, mv);
     schema.addTable(live);
     // Data reconcile: re-run the body and swap contents (the identity-preserving
-    // data-only path — same host, same incarnation).
-    await rebuildBacking(db, live);
+    // data-only path — same host, same incarnation). The column preview lets that
+    // path's declared-constraint scan resolve against the type/collation the
+    // post-reconcile ops below will land, not the ones they replace.
+    await rebuildBacking(db, live, previewReshapedColumns(live, shape));
     // Post-reconcile data-validating ops (retype / recollate / tighten NOT NULL): the
     // reconciled body rows satisfy the new attribute where the discarded backing
     // might not, so each validates the fresh data, not the stale rows. Re-register
@@ -2221,14 +2310,14 @@ async function reshapeBackingInPlace(db, mv, shape, plan) {
     // partial throw. Per-op registration keeps the catalog tracking the module so a
     // mid-batch failure leaves a coherent, re-runnable table.
     //
-    // NOTE: a `recollate` here applies AFTER step 3's rebuildBacking has already
-    // validated + committed the rows under the OLD collation — so a collation-
-    // sensitive declared CHECK whose truth flips under this recollate is not caught
-    // by that scan. A `retype` in this same batch is the affinity analog: a CHECK
-    // whose truth flips under the column's NEW logical type (e.g. `v < '9'` retyped
-    // TEXT → INTEGER) is likewise validated under the OLD type and missed (documented
-    // limitation; see the note in rebuildBacking's constraint-bearing branch and
-    // docs/materialized-views.md § REFRESH MATERIALIZED VIEW).
+    // These ops still run after step 3's rebuildBacking has validated + committed,
+    // but the declared-CHECK/FK scan inside that step is no longer blind to them:
+    // the `previewReshapedColumns` argument above hands it the type/collation each
+    // `retype` / `recollate` here is about to land, so a constraint whose truth
+    // flips under the new attribute (`v <> 'abc'` recollated BINARY → NOCASE over
+    // 'ABC'; `v < '9'` retyped TEXT → INTEGER over '10') is rejected there, before
+    // the commit, with nothing written. A tighten-NOT-NULL is deliberately NOT
+    // previewed and keeps validating right here — see previewReshapedColumns.
     for (const op of plan.postReconcileOps) {
         current = await module.alterTable(db, mv.schemaName, mv.name, reshapeOpToChange(op));
         live = graftReshapedRecord(current, mv);
@@ -2393,8 +2482,9 @@ function maintainedTablesOf(schema) {
 /**
  * Rewrites every dependent materialized view in `schema` after a source TABLE
  * RENAME — the MV mirror of the plain-view loop in `propagateTableRenameInSchema`
- * ("MV ≡ faster view"): the caller applies the same same-schema gate, and the body
- * `selectAst` is mutated in place by the same `renameTableInAst` walker. An MV is
+ * ("MV ≡ faster view"): the caller calls this once per schema in the catalog with
+ * `target` bound to THAT schema's home path, and the body `selectAst` is mutated
+ * in place by the same `renameTableInAst` walker. An MV is
  * processed when its body AST changed, its `insert defaults` clause changed (an
  * expr subquery can name the renamed table even when the body doesn't), OR its
  * `sourceTables` carries the old base — the latter catches a body that reads the
@@ -2409,8 +2499,9 @@ function maintainedTablesOf(schema) {
  * `materialized_view_modified`. Failures mark the MV stale and propagation
  * continues — best-effort, like the rest of the rename propagation.
  */
-export async function propagateTableRenameToMaterializedViews(db, schema, renamedSchemaName, oldName, newName, preStale) {
-    const schemaLower = renamedSchemaName.toLowerCase();
+export async function propagateTableRenameToMaterializedViews(db, schema, preStale, target) {
+    const { oldName, newName } = target;
+    const schemaLower = target.schemaName.toLowerCase();
     const oldBase = `${schemaLower}.${oldName.toLowerCase()}`;
     const newBase = `${schemaLower}.${newName.toLowerCase()}`;
     for (const mv of maintainedTablesOf(schema)) {
@@ -2419,7 +2510,7 @@ export async function propagateTableRenameToMaterializedViews(db, schema, rename
             // The body walk also descends the trailing `with defaults (…)` clause
             // (now on `selectAst.defaults`), so a defaults-expr subquery naming the
             // renamed table flips `bodyChanged` even when the body never names it.
-            const bodyChanged = renameTableInAst(d.selectAst, oldName, newName, renamedSchemaName);
+            const bodyChanged = renameTableInAst(d.selectAst, target);
             if (!bodyChanged && !d.sourceTables.includes(oldBase))
                 continue;
             const covers = d.covers
@@ -2440,7 +2531,10 @@ export async function propagateTableRenameToMaterializedViews(db, schema, rename
 /**
  * Rewrites every dependent materialized view in `schema` after a source COLUMN
  * RENAME — the MV mirror of the plain-view loop in `propagateColumnRenameInSchema`
- * (same same-schema gate at the caller, same in-place `renameColumnInAst` walk).
+ * (called once per schema PER CASCADE ROUND — the target may be the renamed table
+ * or a view/MV whose published names a prior round shifted, see
+ * `column-rename-cascade.ts` — with that schema's resolver, same in-place
+ * `renameColumnInAst` walk).
  * The body walk also descends the trailing `with defaults (…)` clause (now on
  * `selectAst.defaults`): the clause target is typically a projected-away NOT NULL
  * column the body never mentions, so its rewrite still flips `bodyChanged` and
@@ -2452,14 +2546,14 @@ export async function propagateTableRenameToMaterializedViews(db, schema, rename
  * (a bare passthrough projection of the renamed column — plain-view parity),
  * which {@link applyMaterializedViewRewrite} carries onto the live backing table.
  */
-export async function propagateColumnRenameToMaterializedViews(db, schema, renamedSchemaName, tableName, oldCol, newCol, preStale, resolveColumnInSource) {
+export async function propagateColumnRenameToMaterializedViews(db, schema, tableName, oldCol, newCol, preStale, resolve, targetKey, resolveColumnInSource) {
     for (const mv of maintainedTablesOf(schema)) {
         try {
             const d = mv.derivation;
             // `resolveColumnInSource` keeps the body walk scope-aware for a defaults-expr
             // subquery referencing a like-named column on its own FROM — plain-view /
             // differ-reconcile parity (see `renameColumnInAst`).
-            const bodyChanged = renameColumnInAst(d.selectAst, tableName, oldCol, newCol, renamedSchemaName, resolveColumnInSource);
+            const bodyChanged = renameColumnInAst(d.selectAst, tableName, oldCol, newCol, resolve, targetKey, 'none', resolveColumnInSource);
             if (!bodyChanged)
                 continue;
             await applyMaterializedViewRewrite(db, schema, mv, {}, preStale, /*renamedColumns*/ true);
@@ -2580,10 +2674,22 @@ async function restoreMaterializedViewLive(db, schema, mv, backingNames) {
  * sql, sourceTables) is unchanged here — `stale` is runtime state, not persisted.
  * Walks all schemas (the listener marks cross-schema dependents too), in creation
  * order — topological for same-schema MV chains, so a producer restores before its
- * consumer is examined. A chained MV whose body references a renamed-away producer
- * output name fails shape derivation and stays stale (staleness-diagnostic parity
- * with a broken plain-view chain). Best-effort like the rest of the propagation:
- * a per-MV failure logs, leaves that MV stale, and continues.
+ * consumer is examined. A chained MV normally follows a producer's shifted output
+ * name through the cascade driver's later rounds (`column-rename-cascade.ts`); one
+ * whose body still references a renamed-away name (a mid-statement rewrite
+ * failure) fails shape derivation here and stays stale.
+ *
+ * NOTE: the walk is schema-by-schema, then creation order WITHIN a schema, so a
+ * CROSS-schema MV chain is only topological when the producer's schema is iterated
+ * first. Harmless today — a consumer whose body does not itself name the renamed
+ * object is skipped by the propagation entirely and only ever reaches this pass, and
+ * a producer whose own NAME did not change re-plans fine either way (verified for
+ * both verbs in `test/schema/rename-cross-schema.spec.ts`). If a producer's output
+ * names can shift while its consumer lives in an earlier-iterated schema, this pass
+ * needs a topological order (or a second round) rather than catalog order.
+ *
+ * Best-effort like the rest of the propagation: a per-MV failure logs, leaves that MV
+ * stale, and continues.
  *
  * NOTE: firing no `materialized_view_modified` is deliberate, but
  * {@link renameShiftedBackingColumns} (run from the shared restore tail) DOES change the
@@ -2653,11 +2759,14 @@ function sameSourceTables(a, b) {
  * difference (count / types / PK) is NOT a rename outcome — throw so the caller's
  * failure path leaves the MV stale rather than rebuilding data here.
  *
- * The backing `table_modified` fired on a real rename deliberately cascades: a
- * chained MV whose body references the OLD output name is marked stale by the
- * manager's listener and surfaces the staleness diagnostic on its next read
- * (parity with a broken plain-view chain — strictly better than silently freezing),
- * and cached plans scanning the backing directly recompile against the new names.
+ * The backing `table_modified` fired on a real rename deliberately cascades to
+ * the manager's listener (a chained MV referencing the OLD output name is marked
+ * stale), and cached plans scanning the backing directly recompile against the
+ * new names. Within a RENAME COLUMN statement that staleness is transient: the
+ * cascade driver (`column-rename-cascade.ts`) re-runs the propagation with this
+ * MV as the target, so the chained body is rewritten and restored in a later
+ * round — the staleness diagnostic remains only for a body the cascade could not
+ * rewrite (a mid-statement failure).
  */
 async function renameShiftedBackingColumns(db, schema, mv, bodySql, preDerivedShape) {
     const shape = preDerivedShape ?? deriveBackingShape(db, mv.schemaName, bodySql, mv.derivation.columns);