@quereus/store 4.4.0 → 4.4.1

package/dist/src/common/store-module.js

@@ -12,15 +12,15 @@
  *   - {prefix}.__stats__ - Unified stats store (row counts for all tables)
  *   - Catalog store: __catalog__ - DDL metadata keyed by {schema}.{table}
  */
-import { AccessPlanBuilder, QuereusError, StatusCode, buildColumnIndexMap, columnDefToSchema, compilePredicate, inferType, tryFoldLiteral, validateAndParse, buildAdvertisementsFromTags, resolveNamedConstraintClass, validateCollationForType, buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, extractColumnLevelCheckConstraints, extractColumnLevelForeignKeys, appendIndexToTableSchema, logicalTypeCanHoldText, serializeRowKey, isMaintainedTable, renameColumnInIndexPredicates, renameTableInIndexPredicates, renameColumnInCheckConstraints, renameTableInCheckConstraints } from '@quereus/quereus';
+import { AccessPlanBuilder, QuereusError, StatusCode, buildColumnIndexMap, columnDefToSchema, compilePredicate, inferType, tryFoldLiteral, validateAndParse, buildAdvertisementsFromTags, resolveNamedConstraintClass, validateCollationForType, buildUniqueConstraintSchema, buildForeignKeyConstraintSchema, buildCheckConstraintSchema, validateForeignKeyOverExistingRows, appendIndexToTableSchema, logicalTypeCanHoldText, serializeKey, isMaintainedTable, renameColumnInIndexPredicates, renameTableInIndexPredicates, renameColumnInCheckConstraints, renameTableInCheckConstraints } from '@quereus/quereus';
 import { TransactionCoordinator } from './transaction.js';
 import { StoreConnection } from './store-connection.js';
 import { StoreBackingHost } from './backing-host.js';
-import { StoreTable, resolvePkKeyCollations, columnCanHoldText, keyOrderMatchesCollation, pkOrderPreservingPrefixLength, withImplicitUniqueIndexes, implicitUniqueIndexName } from './store-table.js';
+import { StoreTable, resolvePkKeyCollations, resolvePkKeyTransforms, resolveIndexKeyTransforms, storeSemanticKeyTransform, columnCanHoldText, keyOrderMatchesCollation, pkOrderPreservingPrefixLength, withImplicitUniqueIndexes, implicitUniqueIndexName } from './store-table.js';
 import { buildCatalogKey, buildCatalogScanBounds, buildDataKey, buildDataStoreName, buildIndexKey, buildIndexStoreName, buildFullScanBounds, buildStatsKey, buildViewCatalogKey, buildMaterializedViewCatalogKey, parseMaterializedViewCatalogKey, buildMetaCatalogKey, CLEAN_SHUTDOWN_META_NAME, STALE_MVS_META_NAME, classifyCatalogKey, } from './key-builder.js';
 import { assertNoUnpairedSurrogate } from './encoding.js';
 import { deserializeRow } from './serialization.js';
-import { generateTableDDL, generateIndexDDL, generateViewDDL, generateMaintainedTableDDL, generateIndexTagsDDL, isHiddenImplicitIndex, exposedImplicitIndexes } from '@quereus/quereus';
+import { generateTableDDL, generateIndexDDL, generateDropTableDDL, generateDropIndexDDL, generateViewDDL, generateMaintainedTableDDL, generateIndexTagsDDL, isHiddenImplicitIndex, exposedImplicitIndexes } from '@quereus/quereus';
 /**
  * Default serialized-byte budget for a single index-build write batch. Bounds
  * heap directly: {@link StoreModule.buildIndexEntries} flushes and starts a fresh
@@ -113,6 +113,42 @@ function rangeRoles(colIdx) {
 function equalityRoles(colIdxs) {
     return colIdxs.map(colIdx => ({ colIdx, ops: EQ_OPS }));
 }
+/**
+ * Guard the FULL persisted schema text, not just the object's own name: a lone
+ * surrogate anywhere in it — a quoted column name, a `default '…'` string literal, a
+ * `check` constraint's string constant — folds to U+FFFD under `TextEncoder` and would
+ * read back as different schema text than what was created. Independent of the
+ * catalog-key builders' identifier guard; it catches what they cannot see.
+ */
+function assertPersistableDdlText(ddl) {
+    assertNoUnpairedSurrogate(ddl, 'persisted schema text');
+}
+/**
+ * The catalog entry a plain view would be persisted as. Building it is the check:
+ * {@link buildViewCatalogKey} rejects an unencodable name, and the caller then runs
+ * {@link assertPersistableDdlText} over `ddl`. Shared by the write path
+ * ({@link StoreModule.saveViewDDL}) and the pre-flight veto
+ * ({@link StoreModule.assertCatalogObjectPersistable}) so the two cannot drift.
+ */
+function viewCatalogEntry(view) {
+    return {
+        key: buildViewCatalogKey(view.schemaName, view.name),
+        ddl: generateViewDDL(view),
+    };
+}
+/**
+ * The catalog entry a materialized view would be persisted as, or `undefined` when
+ * `table` carries no derivation (not an MV — nothing lands under the MV prefix).
+ * Counterpart of {@link viewCatalogEntry}; same write/veto sharing.
+ */
+function maintainedViewCatalogEntry(table) {
+    if (!isMaintainedTable(table))
+        return undefined;
+    return {
+        key: buildMaterializedViewCatalogKey(table.schemaName, table.name),
+        ddl: generateMaintainedTableDDL(table),
+    };
+}
 /**
  * Generic store module that works with any KVStoreProvider.
  *
@@ -372,6 +408,14 @@ export class StoreModule {
      * stores in the set therefore causes no false rejects and keeps the
      * reject-before-any-side-effect guarantee uniform.
      */
+    // NOTE: the builders below carry the unpaired-surrogate identifier guard, so this
+    // enumeration can THROW on an EXISTING schema object, not just on the incoming one —
+    // an unrelated CREATE/RENAME in the same schema would then fail with a confusing
+    // "cannot store the identifier ..." error. Unreachable today: `create` throws before
+    // the table is registered, and a catalog entry written before the guard existed was
+    // folded to a real U+FFFD character, which passes. If a lone-surrogate-named table ever
+    // does reach the schema manager by another route, skip such an object here (it occupies
+    // no store) rather than letting the enumeration throw.
     collectOccupiedStoreNames(db, schemaName) {
         const names = new Map();
         const add = (s) => {
@@ -561,12 +605,15 @@ export class StoreModule {
         // torn down too — the engine-facing `.indexes` omits them and would leak them.
         const indexNames = this.materializedIndexNames(table, currentSchema);
         await this.tearDownTableStorage(schemaName, tableName, indexNames);
-        // Emit schema change event for table drop
+        // Emit schema change event for table drop. The `ddl` is what a sync peer
+        // re-executes to replicate the drop — a drop with no DDL crosses the wire as
+        // an empty statement and silently changes nothing on the receiver.
         this.eventEmitter?.emitSchemaChange({
             type: 'drop',
             objectType: 'table',
             schemaName,
             objectName: tableName,
+            ddl: generateDropTableDDL(schemaName, tableName),
         });
     }
     /**
@@ -745,12 +792,17 @@ export class StoreModule {
         // skips (identical) — see persistCatalogIfChanged.
         await this.saveTableDDL(updatedSchema);
         table.markDdlSaved();
-        // Emit schema change event
+        // Emit schema change event. `updatedSchema` (not the pre-create
+        // `tableSchema`) is the owner the canonical CREATE INDEX renders against —
+        // it is only read for the table's qualified name and column names, but
+        // passing the post-create schema keeps the rendering consistent with what a
+        // receiving peer regenerates when it compares definitions.
         this.eventEmitter?.emitSchemaChange({
             type: 'create',
             objectType: 'index',
             schemaName,
             objectName: indexSchema.name,
+            ddl: generateIndexDDL(indexSchema, updatedSchema),
         });
     }
     /**
@@ -808,6 +860,7 @@ export class StoreModule {
             objectType: 'index',
             schemaName,
             objectName: indexName,
+            ddl: generateDropIndexDDL(schemaName, indexName),
         });
     }
     /**
@@ -841,6 +894,11 @@ export class StoreModule {
         const encodeOptions = { collation: keyCollation, normalizers };
         const pkDirections = tableSchema.primaryKeyDefinition.map(pk => !!pk.desc);
         const pkCollations = resolvePkKeyCollations(tableSchema.primaryKeyDefinition, tableSchema.columns, keyCollation);
+        // Key-identity transforms for both halves, mirroring `StoreTable`'s maintenance
+        // writes (`updateSecondaryIndexes` / `encodeDataKey`) — a rebuild that skipped them
+        // would re-encode a TIMESPAN member under different bytes than DML writes.
+        const pkTransforms = resolvePkKeyTransforms(tableSchema.primaryKeyDefinition, tableSchema.columns);
+        const indexTransforms = resolveIndexKeyTransforms(indexSchema, tableSchema.columns);
         const indexDirections = indexSchema.columns.map(col => !!col.desc);
         const predicate = indexSchema.predicate
             ? compilePredicate(indexSchema.predicate, tableSchema.columns, tableSchema.name)
@@ -868,9 +926,9 @@ export class StoreModule {
             // Extract index column values
             const indexValues = indexSchema.columns.map(col => row[col.index]);
             if (seen) {
-                // serializeRowKey returns null when any indexed column is NULL —
+                // The signature returns null when any indexed column is NULL —
                 // SQL UNIQUE allows multiple NULLs, so those rows never collide.
-                const keySig = serializeRowKey(row, indexColIndices, indexNormalizers);
+                const keySig = dedupeRowSignature(row, indexColIndices, indexNormalizers, indexTransforms);
                 if (keySig !== null) {
                     if (seen.has(keySig)) {
                         const colNames = indexSchema.columns
@@ -882,13 +940,13 @@ export class StoreModule {
                 }
             }
             // Build and store index key
-            const indexKey = buildIndexKey(indexValues, pkValues, encodeOptions, indexDirections, pkDirections, pkCollations);
+            const indexKey = buildIndexKey(indexValues, pkValues, encodeOptions, indexDirections, pkDirections, pkCollations, indexTransforms, pkTransforms);
             // Index value = the row's encoded DATA key, so an index scan resolves each
             // entry back to its base row via a direct data-store read (see
             // `StoreTable.scanIndex`). Encoded under the same PK directions + per-column
-            // PK collations as `buildDataKey` / `updateSecondaryIndexes`, so the value
-            // byte-matches the data store's key for this row.
-            const dataKey = buildDataKey(pkValues, encodeOptions, pkDirections, pkCollations);
+            // PK collations + key transforms as `buildDataKey` / `updateSecondaryIndexes`,
+            // so the value byte-matches the data store's key for this row.
+            const dataKey = buildDataKey(pkValues, encodeOptions, pkDirections, pkCollations, pkTransforms);
             batch.put(indexKey, dataKey);
             // Bound heap: once the accumulated serialized key bytes cross the budget, flush
             // the batch and start a fresh one. Both callers ITERATE the data store and WRITE
@@ -920,11 +978,20 @@ export class StoreModule {
      * connection's `db.getKeyNormalizerResolver()` — see {@link buildIndexEntries}.
      *
      * NOTE: reads the data store committed-only and writes the index stores outside the
-     * coordinator. Sound only because both callers (the two re-key arms) call
-     * {@link ddlCommitPendingOps} first, so "committed" is "everything live". A caller
-     * that skips that flush would rebuild an index missing its transaction's pending rows.
-     */
-    async rebuildSecondaryIndexes(schemaName, tableName, table, schema, normalizers) {
+     * coordinator. Sound only because every caller calls {@link ddlCommitPendingOps}
+     * first, so this module's "committed" is "everything live". A caller that skips that
+     * flush would rebuild an index missing its transaction's pending rows.
+     *
+     * `skipDuplicateCheck` suppresses {@link buildIndexEntries}' in-pass UNIQUE check.
+     * The value-rewriting / key-transform ALTER COLUMN arm sets it: its pre-mutation
+     * UNIQUE re-validation already judged the ISSUING connection's effective rows (a
+     * wrapper's overlay included), and this rebuild sees only THIS module's committed
+     * rows — a superset that may retain a row the wrapper's transaction has deleted, so
+     * judging it here would spuriously reject a duplicate pair the probe correctly
+     * accepted. Mirrors the memory module's deliberately non-enforcing base rebuild
+     * (the probe is the only guard).
+     */
+    async rebuildSecondaryIndexes(schemaName, tableName, table, schema, normalizers, skipDuplicateCheck = false) {
         const keyCollation = (table.getConfig().collation || 'NOCASE').toUpperCase();
         const dataStore = await this.getStore(schemaName, tableName, table.getConfig());
         const maxBatchBytes = table.getConfig().maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES;
@@ -942,7 +1009,7 @@ export class StoreModule {
                 clearBatch.delete(entry.key);
             }
             await clearBatch.write();
-            await this.buildIndexEntries(dataStore.iterate(buildFullScanBounds()), indexStore, schema, indexSchema, keyCollation, normalizers, false, maxBatchBytes);
+            await this.buildIndexEntries(dataStore.iterate(buildFullScanBounds()), indexStore, schema, indexSchema, keyCollation, normalizers, skipDuplicateCheck, maxBatchBytes);
         }
     }
     /**
@@ -965,7 +1032,7 @@ export class StoreModule {
      *
      * No index store is written — store UNIQUE enforcement is a full-scan over
      * `uniqueConstraints` at write time. The signature is built by
-     * {@link serializeRowKey} with one normalizer per constrained column, resolved from
+     * {@link dedupeRowSignature} with one normalizer per constrained column, resolved from
      * `tableSchema.columns[idx].collation` through the connection's
      * `db.getKeyNormalizerResolver()`, so a per-column collation registered with
      * `db.registerCollation` is honored (matching write-time `compareSqlValues`
@@ -1183,8 +1250,16 @@ export class StoreModule {
      * ADD COLUMN arm of {@link alterTable}: append the new column, eagerly migrate
      * each row (literal or per-row backfill), and persist. Behavior-preserving
      * extraction of the former `switch` arm.
+     *
+     * The store always appends. A caller-chosen `insertAtIndex` (module-API only; SQL never
+     * produces one) is rejected unless it names the append position, rather than silently
+     * landing the column somewhere the caller did not ask for.
      */
     async alterAddColumn(db, schemaName, tableName, table, oldSchema, change, defaultNotNull) {
+        if (change.insertAtIndex !== undefined && change.insertAtIndex !== oldSchema.columns.length) {
+            throw new QuereusError(`Store-backed table '${schemaName}.${tableName}' can only ADD COLUMN at the end `
+                + `(position ${oldSchema.columns.length}), not at position ${change.insertAtIndex}`, StatusCode.UNSUPPORTED);
+        }
         // Honor the session `default_collation` for an ADD COLUMN that omits an
         // explicit COLLATE, matching the CREATE path so an ADD-COLUMN-ed text column
         // gets the same collation a CREATE-d one would. The persisted DDL re-emits an
@@ -1221,19 +1296,11 @@ export class StoreModule {
             columns: updatedColumns,
             columnIndexMap: buildColumnIndexMap(updatedColumns),
         };
-        // Extract any column-level CHECK / FK to persist (see the persist block below).
-        // Hoisted above the row migration so a malformed constraint (e.g. a multi-column
-        // FK on a single ADD COLUMN, which `extractColumnLevelForeignKeys` rejects) throws
-        // BEFORE any rows are migrated or the in-memory schema is swapped — validate-before-
-        // mutate, matching the engine's ordering in `runAddColumn`.
-        const newCheckConstraints = extractColumnLevelCheckConstraints(change.columnDef);
-        const newForeignKeys = extractColumnLevelForeignKeys(change.columnDef, schemaName);
         // Physical rewrite ahead: flush the module's buffered writes so `migrateRows`
         // (a committed-store scan + batch) sees this transaction's rows and re-encodes
         // them under the new column layout. See {@link ddlCommitPendingOps}. Placed
         // after every throw-only check above — the NOT NULL rejection reads effectively
-        // (`hasAnyRows`) and `extractColumnLevel*` reads no rows — so a rejected ALTER
-        // leaves the enclosing transaction intact.
+        // (`hasAnyRows`) — so a rejected ALTER leaves the enclosing transaction intact.
         await this.ddlCommitPendingOps();
         // Migrate rows: append the new column's value — a single literal default, or a
         // per-row value derived from the existing row when a backfill evaluator is set.
@@ -1241,33 +1308,13 @@ export class StoreModule {
         await table.migrateRows(remap, defaultValue, backfillEvaluator
             ? { evaluator: backfillEvaluator, notNull: newColSchema.notNull, columnName: newColSchema.name }
             : undefined);
-        // Update table schema (column-only) and persist DDL.
-        //
-        // The engine's `runAddColumn` re-merges the column-level FK/CHECK extracted
-        // from `columnDef.constraints` into the LIVE in-memory schema AFTER this hook
-        // returns, so the schema handed back to it must stay column-only — returning a
-        // constrained schema would double the constraint in the live SchemaManager (and,
-        // on the next persist, in the DDL). But that engine-side merge is in-memory only:
-        // it never reaches the catalog, so persistence must carry the column-level
-        // CHECK/FK itself or they vanish on `rehydrateCatalog`. Build a separate
-        // `persistedSchema` for `saveTableDDL` when (and only when) the column declares
-        // such a constraint; the common path persists `updatedSchema` unchanged. This is
-        // unconditional on the default kind — a per-row (evaluator) DEFAULT extracts the
-        // same AST constraints as a literal one.
+        // Update table schema (column-only) and persist DDL. Any constraint declared inline
+        // on the added column (UNIQUE / CHECK / FOREIGN KEY) arrives as its own follow-up
+        // `addConstraint` call from the engine's `runAddColumn`, which is what persists it —
+        // so this arm neither installs nor persists them, and the schema it hands back stays
+        // column-only.
         table.updateSchema(updatedSchema);
-        let persistedSchema = updatedSchema;
-        if (newCheckConstraints.length > 0 || newForeignKeys.length > 0) {
-            // The new column is appended last; resolve each FK's child column to its index
-            // (matching how the engine resolves `resolvedForeignKeys` via columnIndexMap).
-            const newColIdx = updatedColumns.length - 1;
-            const resolvedForeignKeys = newForeignKeys.map(fk => ({ ...fk, columns: Object.freeze([newColIdx]) }));
-            persistedSchema = {
-                ...updatedSchema,
-                checkConstraints: Object.freeze([...updatedSchema.checkConstraints, ...newCheckConstraints]),
-                foreignKeys: Object.freeze([...(updatedSchema.foreignKeys ?? []), ...resolvedForeignKeys]),
-            };
-        }
-        await this.saveTableDDL(persistedSchema);
+        await this.saveTableDDL(updatedSchema);
         this.eventEmitter?.emitSchemaChange({
             type: 'alter',
             objectType: 'table',
@@ -1313,6 +1360,18 @@ export class StoreModule {
         const updatedUniqueConstraints = (oldSchema.uniqueConstraints ?? [])
             .filter(uc => !uc.columns.includes(colIndex))
             .map(uc => ({ ...uc, columns: Object.freeze(uc.columns.map(i => i > colIndex ? i - 1 : i)) }));
+        // Shift or prune this table's own foreign keys, mirroring the UNIQUE pruning above
+        // and the memory module's `dropColumn`. `foreignKeys[].columns` are indices into
+        // THIS table, so they renumber over the removed slot; a key that loses ANY of its
+        // child columns is removed outright (a key missing a child column is a different
+        // constraint against the parent's key, not a narrowed one). Left unshifted, a
+        // surviving key's index dangles past the column array or silently slides onto an
+        // unrelated column — and `saveTableDDL` below persists whichever it ends up being.
+        // `referencedColumnNames` is resolved against the parent by name at enforcement
+        // time, so the parent side needs nothing here.
+        const updatedForeignKeys = (oldSchema.foreignKeys ?? [])
+            .filter(fk => !fk.columns.includes(colIndex))
+            .map(fk => ({ ...fk, columns: Object.freeze(fk.columns.map(i => i > colIndex ? i - 1 : i)) }));
         const updatedSchema = {
             ...oldSchema,
             columns: Object.freeze(updatedColumns),
@@ -1322,6 +1381,9 @@ export class StoreModule {
             uniqueConstraints: updatedUniqueConstraints.length > 0
                 ? Object.freeze(updatedUniqueConstraints)
                 : undefined,
+            foreignKeys: updatedForeignKeys.length > 0
+                ? Object.freeze(updatedForeignKeys)
+                : undefined,
         };
         // Physical rewrite ahead — flush buffered writes so `migrateRows` re-encodes
         // this transaction's rows too. See {@link ddlCommitPendingOps}.
@@ -1581,16 +1643,17 @@ export class StoreModule {
         const oldCol = oldSchema.columns[colIndex];
         // Pull exactly one attribute from the change. Each sub-helper returns the new
         // column schema plus whether the collation bytes changed (`collationChanged` gates
-        // the existing-row UNIQUE re-validation and PK re-key below), or null when the column
-        // is already in the desired state — preserving the pre-refactor early exits
-        // (SET NOT NULL no-op, SET COLLATE already-explicit) that leave the table and any
-        // open transaction untouched.
+        // the existing-row UNIQUE re-validation and PK re-key below) plus a DEFERRED
+        // `valueConvert` closure when the change rewrites stored values — the sub-helper
+        // itself mutates nothing. Or null when the column is already in the desired state —
+        // preserving the pre-refactor early exits (SET NOT NULL no-op, SET COLLATE
+        // already-explicit) that leave the table and any open transaction untouched.
         let attr;
         if (change.setNotNull !== undefined) {
             attr = await this.alterColumnSetNotNull(table, oldSchema, oldCol, colIndex, change, rows);
         }
         else if (change.setDataType !== undefined) {
-            attr = await this.alterColumnSetDataType(table, oldCol, colIndex, change);
+            attr = await this.alterColumnSetDataType(table, oldSchema, oldCol, colIndex, change);
         }
         else if (change.setDefault !== undefined) {
             attr = { newCol: { ...oldCol, defaultValue: change.setDefault }, collationChanged: false };
@@ -1604,7 +1667,12 @@ export class StoreModule {
         if (attr === null) {
             return oldSchema;
         }
-        const { newCol, collationChanged, valuesRewritten } = attr;
+        const { newCol, collationChanged, valueConvert } = attr;
+        // Named for the PENDING act, not a completed one: the deferred value rewrite (SET DATA
+        // TYPE conversion / SET NOT NULL backfill) is applied below, after every throw-only
+        // check. Both gates that read this run BEFORE it, while the store still holds the old
+        // values.
+        const rewritesValues = valueConvert !== undefined;
         const updatedColumns = oldSchema.columns.map((c, i) => i === colIndex ? newCol : c);
         // Mirror the memory module (MemoryTableManager.alterColumn): a per-column
         // collation change propagates into every index column ordering by this
@@ -1630,21 +1698,47 @@ export class StoreModule {
             columnIndexMap: buildColumnIndexMap(updatedColumns),
             indexes: updatedIndexes ? Object.freeze(updatedIndexes) : updatedIndexes,
         };
-        // SET COLLATE existing-row re-validation (Option A, non-PK UNIQUE): a new
-        // per-column collation can make rows that were distinct under the old
-        // collation collide. Re-scan every UNIQUE constraint covering the altered
-        // column under the NEW collation (`updatedSchema` carries it). The first
-        // collision throws CONSTRAINT BEFORE any mutation/persist, so the table is
-        // left unchanged and writable (matches the ADD CONSTRAINT rollback shape).
+        // SET DATA TYPE onto/off a type with a key transform (TIMESPAN's total-seconds
+        // groupKey, JSON's structural encoder — see `storeSemanticKeyTransform`)
+        // changes the physical KEY BYTES a value encodes to, even when the stored
+        // VALUE bytes don't change (text → timespan keeps TEXT physical). Treated
+        // exactly like a collation change below: existing-row UNIQUE re-validation
+        // (equal-elapsed spellings now collide), a PK re-key when the column is a PK
+        // member, and a secondary-index rebuild (index keys encode the column's
+        // values). A same-type no-op ALTER never gets here (`inferType` returns the
+        // shared type object, so the identity check short-circuits).
+        const keyTransformChanged = oldCol.logicalType !== newCol.logicalType
+            && (storeSemanticKeyTransform(oldCol.logicalType) !== undefined
+                || storeSemanticKeyTransform(newCol.logicalType) !== undefined);
+        // Existing-row UNIQUE re-validation (Option A, non-PK UNIQUE). Two ways an ALTER
+        // COLUMN can make rows that were distinct collide, both judged here BEFORE any
+        // mutation/persist so the first collision throws CONSTRAINT and leaves the table
+        // unchanged and writable (matches the ADD CONSTRAINT rollback shape):
+        //  - SET COLLATE / a key-transform change: the comparators change ('a'/'A' collide
+        //    under NOCASE). Re-scan under the NEW collation (`updatedSchema` carries it).
+        //  - a value-REWRITING change (`valueConvert`: SET DATA TYPE, or a SET NOT NULL
+        //    null → DEFAULT backfill): the comparators are unchanged but the VALUES collapse
+        //    ('1'/'01' → 1; two NULLs → the same DEFAULT). The probe judges the CONVERTED
+        //    rows — the same closure the deferred rewrite below applies — while the store
+        //    still holds the old values. A standalone `create unique index` synthesizes a
+        //    `derivedFromIndex` entry in `uniqueConstraints`, so both declaration shapes are
+        //    reachable through this walk.
         // The PK is intentionally excluded — it never appears in `uniqueConstraints`;
-        // its physical re-key/re-validation is the `isPkColumn` block below.
-        if (collationChanged) {
+        // its physical re-key/re-validation is the `pkRekeyNeeded` block below.
+        //
+        // NOTE: one full row scan per covering constraint, and this gate now fires on the
+        // COMMON retype/backfill path, not only on the rare collation/transform ones. Fine
+        // while tables covered by several UNIQUE constraints over one column are rare; if a
+        // wide-constraint table makes ALTER COLUMN slow, judge all covering constraints in a
+        // single pass (one `seen` Set per constraint, one stream).
+        if (collationChanged || keyTransformChanged || rewritesValues) {
             const coveringConstraints = (updatedSchema.uniqueConstraints ?? [])
                 .filter(uc => uc.columns.includes(colIndex));
             for (const uc of coveringConstraints) {
                 // Fresh generator per constraint — an async generator is single-shot. An
                 // `EffectiveRowSource` is re-callable for exactly this reason.
-                await this.validateUniqueOverExistingRows(rows ? rows() : rowsFromEntries(table.iterateEffectiveEntries(buildFullScanBounds())), updatedSchema, uc, db.getKeyNormalizerResolver());
+                const effectiveRows = rows ? rows() : rowsFromEntries(table.iterateEffectiveEntries(buildFullScanBounds()));
+                await this.validateUniqueOverExistingRows(valueConvert ? convertRowsAtIndex(effectiveRows, colIndex, valueConvert) : effectiveRows, updatedSchema, uc, db.getKeyNormalizerResolver());
             }
         }
         // SET COLLATE on a PRIMARY KEY member (Option B physical re-key): re-encode
@@ -1656,7 +1750,9 @@ export class StoreModule {
         // ALTER PRIMARY KEY. Runs AFTER the non-PK UNIQUE re-validation above so both
         // throw-only checks precede the first store mutation. `updatedSchema.columns`
         // carries the new collation, so the new key bytes follow it.
-        if (collationChanged && oldSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
+        const pkRekeyNeeded = (collationChanged || keyTransformChanged)
+            && oldSchema.primaryKeyDefinition.some(def => def.index === colIndex);
+        if (pkRekeyNeeded) {
             // Physical re-key ahead — flush buffered writes (see
             // {@link ddlCommitPendingOps}). Deliberately AFTER the non-PK UNIQUE
             // re-validation above: that check reads effectively and throws without
@@ -1674,18 +1770,46 @@ export class StoreModule {
             // key collation too (`updatedSchema` carries none on its own).
             await this.rebuildSecondaryIndexes(schemaName, tableName, table, withImplicitUniqueIndexes(updatedSchema), db.getKeyNormalizerResolver());
         }
-        // SET DATA TYPE physical conversion / SET NOT NULL DEFAULT backfill rewrote stored
-        // column values in place (same PK, new value) via mapRowsAtIndex. Secondary index KEY
-        // bytes encode the indexed column VALUES, so any index covering this column still points
-        // at the OLD value bytes until rebuilt — an index-backed lookup for the new value finds
-        // nothing (mirrors the memory module's `valuesRewritten` rebuild in MemoryTableManager.
-        // alterColumn). The sub-helper already ran ddlCommitPendingOps before its rewrite, so the
-        // committed data store rebuildSecondaryIndexes reads is "everything live". Mutually
-        // exclusive with the collation re-key above (distinct attributes), so no double rebuild.
-        // Materialize so an implicit `_uc_*` over the rewritten column is rebuilt against the
-        // new value bytes too.
-        if (valuesRewritten) {
-            await this.rebuildSecondaryIndexes(schemaName, tableName, table, withImplicitUniqueIndexes(updatedSchema), db.getKeyNormalizerResolver());
+        // Deferred value rewrite (SET DATA TYPE physical conversion / SET NOT NULL DEFAULT
+        // backfill): every throw-only check above has passed, so the store mutation is now
+        // safe — a rejected ALTER never reaches this point, leaving values, DDL and the
+        // transaction untouched. Flush buffered writes first so `mapRowsAtIndex` rewrites this
+        // transaction's rows too; unflushed, they would replay under the OLD physical type
+        // (see {@link ddlCommitPendingOps}; a re-flush after the PK re-key's own is a no-op).
+        //
+        // NOTE: `valueConvert` and `pkRekeyNeeded` cannot both be set today, and this ordering
+        // depends on that. `valueConvert` comes only from SET DATA TYPE or SET NOT NULL;
+        // SET NOT NULL changes neither collation nor logical type, so it never sets
+        // `pkRekeyNeeded`, and SET DATA TYPE on a PK member is refused both upstream (every live
+        // caller — the engine's ALTER COLUMN emitter, see `runAlterColumn` in
+        // runtime/emit/alter-table.ts, and the materialized-view reshape, which declares a
+        // key-column retype inexpressible) AND locally, by `alterColumnSetDataType` itself. If a
+        // PK-member retype is ever admitted (that local guard removed), this rewrite must move IN
+        // FRONT of the `pkRekeyNeeded` block: otherwise `rekeyRows` and its index rebuild encode
+        // the PRE-rewrite values and the rebuild below is skipped, leaving keys and indexes
+        // disagreeing with the stored values.
+        if (valueConvert) {
+            await this.ddlCommitPendingOps();
+            await table.mapRowsAtIndex(colIndex, valueConvert);
+        }
+        // The value rewrite above changed stored column values in place (same PK, new value) —
+        // and a key-identity transform change re-encodes the column's index-key bytes even with
+        // values untouched. Secondary index KEY bytes encode the indexed column VALUES, so any
+        // index covering this column still points at the OLD bytes until rebuilt — an
+        // index-backed lookup for the new value finds nothing (mirrors the memory module's
+        // `valueConvert` rebuild in MemoryTableManager.alterColumn). `rebuildSecondaryIndexes`
+        // reads committed-only, so flush buffered writes first — the value rewrite above
+        // already did, and the transform-only path (text → timespan: no value rewrite) must
+        // too; a re-flush with nothing pending is a no-op. Skipped when the PK re-key above
+        // already rebuilt every index, so no double rebuild. Materialize so an implicit `_uc_*`
+        // over the rewritten column is rebuilt against the new value bytes too. The rebuild is
+        // NON-enforcing (`skipDuplicateCheck`): the UNIQUE re-validation above already judged
+        // the issuer's effective rows, and this module's committed rows may retain a row a
+        // wrapper's transaction has deleted whose converted value duplicates a survivor —
+        // enforcing here would spuriously reject what the probe correctly accepted.
+        if ((rewritesValues || keyTransformChanged) && !pkRekeyNeeded) {
+            await this.ddlCommitPendingOps();
+            await this.rebuildSecondaryIndexes(schemaName, tableName, table, withImplicitUniqueIndexes(updatedSchema), db.getKeyNormalizerResolver(), true);
         }
         table.updateSchema(updatedSchema);
         await this.saveTableDDL(updatedSchema);
@@ -1700,8 +1824,10 @@ export class StoreModule {
     /**
      * SET NOT NULL / DROP NOT NULL sub-branch of {@link alterColumnChange}. Returns the
      * new column schema, or null when the column is already in the desired nullability
-     * (the pre-refactor `return oldSchema` no-op). The NULL-backfill probe and rewrite
-     * order (throw-only probe before {@link ddlCommitPendingOps}) is unchanged.
+     * (the pre-refactor `return oldSchema` no-op). Mutates nothing: the NULL-backfill
+     * probe is throw-only, and the backfill itself is returned as a deferred
+     * `valueConvert` (null → DEFAULT) the caller applies only after every throw-only
+     * check — including the UNIQUE re-validation over the backfilled values — has passed.
      *
      * `rows` is the wrapper-supplied effective row source (the isolation overlay). When present,
      * the reject-vs-backfill decision scans it instead of `table.rowsWithNullAtIndex`: behind the
@@ -1712,7 +1838,7 @@ export class StoreModule {
      */
     async alterColumnSetNotNull(table, oldSchema, oldCol, colIndex, change, rows) {
         let newCol;
-        let valuesRewritten = false;
+        let valueConvert;
         if (change.setNotNull === true && !oldCol.notNull) {
             // Backfill NULLs from a literal DEFAULT, or throw.
             let defaultLiteral;
@@ -1743,14 +1869,12 @@ export class StoreModule {
                     throw new QuereusError(`column ${change.columnName} contains NULL values`, StatusCode.CONSTRAINT);
                 }
                 const fill = defaultLiteral;
-                // Physical rewrite ahead — flush buffered writes so `mapRowsAtIndex` backfills this
-                // store's own NULL rows. Run directly, that also fills the transaction's rows (the
-                // probe saw them). Behind isolation the issuer's overlay-resident NULL rows are
-                // filled by the isolation layer's overlay migration, not here — this store never
-                // holds them. See {@link ddlCommitPendingOps}.
-                await this.ddlCommitPendingOps();
-                await table.mapRowsAtIndex(colIndex, (v) => v === null ? fill : v);
-                valuesRewritten = true;
+                // Backfill DEFERRED: the caller flushes + `mapRowsAtIndex`es this closure only
+                // after its throw-only checks pass. Run directly, that fills the transaction's
+                // rows too (the probe saw them). Behind isolation the issuer's overlay-resident
+                // NULL rows are filled by the isolation layer's overlay migration, not here —
+                // this store never holds them.
+                valueConvert = (v) => v === null ? fill : v;
             }
             newCol = { ...oldCol, notNull: true };
         }
@@ -1763,18 +1887,40 @@ export class StoreModule {
         else {
             return null; // already in desired state
         }
-        return { newCol, collationChanged: false, valuesRewritten };
+        return { newCol, collationChanged: false, valueConvert };
     }
     /**
      * SET DATA TYPE sub-branch of {@link alterColumnChange}. Returns the retyped column
-     * schema. When the physical type changes, a throw-only convert pass over the live
-     * rows precedes {@link ddlCommitPendingOps} and the rewrite — order unchanged.
-     */
-    async alterColumnSetDataType(table, oldCol, colIndex, change) {
+     * schema. Mutates nothing: for every retype between DIFFERENT logical types, a
+     * throw-only convert pass over the live rows proves every value convertible, and the
+     * conversion itself is returned as a deferred `valueConvert` the caller applies only
+     * after every throw-only check — including the UNIQUE re-validation over the converted
+     * values — has passed. Gated on logical-type IDENTITY, not the physical storage class:
+     * `inferType` flattens aliases to the shared type object (`varchar(50)` IS `TEXT_TYPE`),
+     * so an alias retype is schema-only, while a same-class retype (text → date) still
+     * rejects values the new type refuses and rewrites the rest to the new type's
+     * canonical spelling ('2024-06-05T00:00:00Z' → '2024-06-05') — exactly as an INSERT
+     * would have stored them.
+     *
+     * A retype of a PRIMARY KEY member is refused here rather than converted: the rewrite
+     * below is `mapRowsAtIndex`, a payload-only rewrite that reuses `entry.key` verbatim, so
+     * a PK column's physical key bytes would stay encoded under the OLD type while the value
+     * moves to the new one — unfindable by any lookup under the new encoding, and the same
+     * `keyTransformChanged` path in the caller would re-key from the pre-rewrite values before
+     * this rewrite ever ran (see the NOTE above the `valueConvert` block in
+     * {@link alterColumnChange}). Every live SQL caller already refuses this earlier (the
+     * engine's `runAlterColumn` and the materialized-view reshape's inexpressibility check),
+     * so this only guards a direct module call — mirrors the memory backend's carve-out
+     * (`MemoryTableManager.alterColumn`).
+     */
+    async alterColumnSetDataType(table, oldSchema, oldCol, colIndex, change) {
         const newLogicalType = inferType(change.setDataType);
-        let valuesRewritten = false;
-        if (newLogicalType.physicalType !== oldCol.logicalType.physicalType) {
-            // Physical conversion required — walk every row and attempt parse.
+        let valueConvert;
+        if (newLogicalType !== oldCol.logicalType) {
+            if (oldSchema.primaryKeyDefinition.some(def => def.index === colIndex)) {
+                throw new QuereusError(`Cannot change the data type of primary key column '${change.columnName}' of table '${oldSchema.name}'.`, StatusCode.CONSTRAINT);
+            }
+            // Conversion required — walk every row and attempt parse.
             const convert = (v) => {
                 try {
                     return validateAndParse(v, newLogicalType, change.columnName);
@@ -1783,21 +1929,21 @@ export class StoreModule {
                     throw new QuereusError(`Cannot convert value in '${change.columnName}' to ${change.setDataType}`, StatusCode.MISMATCH);
                 }
             };
-            // Throw-only pass over the LIVE rows first, so an unconvertible value
-            // this transaction inserted rejects the ALTER with the transaction still
-            // intact. The rewrite below reads only committed rows.
+            // Throw-only pass over the LIVE rows, so an unconvertible value this
+            // transaction inserted rejects the ALTER with the transaction still intact.
+            // The rewrite itself is DEFERRED: the caller flushes + `mapRowsAtIndex`es
+            // this closure only after its remaining throw-only checks pass.
+            // NOTE: pre-existing gap — this scan reads the store's own effective rows and
+            // ignores a wrapper-supplied `rows` stream (unlike the memory module's arm). No
+            // hole under isolation: the wrapper's `validateOverlayMigration` converts every
+            // staged overlay value itself before the underlying mutates.
             for await (const value of table.iterateEffectiveValuesAtIndex(colIndex)) {
                 if (value !== null)
                     convert(value);
             }
-            // Physical rewrite ahead — flush buffered writes so `mapRowsAtIndex`
-            // converts this transaction's rows too; unflushed, they would replay
-            // under the OLD physical type. See {@link ddlCommitPendingOps}.
-            await this.ddlCommitPendingOps();
-            await table.mapRowsAtIndex(colIndex, (v) => v === null ? v : convert(v));
-            valuesRewritten = true;
+            valueConvert = (v) => v === null ? v : convert(v);
         }
-        return { newCol: { ...oldCol, logicalType: newLogicalType }, collationChanged: false, valuesRewritten };
+        return { newCol: { ...oldCol, logicalType: newLogicalType }, collationChanged: false, valueConvert };
     }
     /**
      * SET COLLATE sub-branch of {@link alterColumnChange}. Returns the recollated column
@@ -1928,6 +2074,17 @@ export class StoreModule {
             }
         }
         // Move physical storage (data directory + index directories).
+        //
+        // NOTE: the relocation runs BEFORE the catalog rewrite below, and nothing undoes it.
+        // Any failure after this point — an IO error, or the DDL-text guard in
+        // `encodeCatalogDDL` firing on an unpaired surrogate in a column name or a `default`
+        // literal — strands the rows under the NEW physical name while the catalog still
+        // names the old table, so the table reads as empty with only the raised error as a
+        // clue. Harmless for today's validation cases: the store-name guard in
+        // `buildDataStoreName` (called above, before any side effect) refuses a bad target
+        // name outright, and a table whose DDL text is unpersistable can never have held
+        // rows in the first place. If a new post-relocation failure mode appears, the
+        // relocation must be undone here or deferred until after the catalog write.
         if (this.provider.renameTableStores) {
             await this.provider.renameTableStores(schemaName, oldName, newName, indexNames);
         }
@@ -2463,15 +2620,11 @@ export class StoreModule {
     }
     /**
      * Encode a bundle of persisted schema text (DDL) for the catalog store.
-     *
-     * Guards the FULL text, not just the object's name: a lone surrogate anywhere in it — a
-     * quoted column name, a `default '…'` string literal, a `check` constraint's string
-     * constant — would otherwise fold to U+FFFD under `TextEncoder` and read back as
-     * different schema text than what was created. This does not rely on the catalog-key
-     * builders' identifier guard having already caught it; it catches it independently.
+     * The guard is {@link assertPersistableDdlText} — see it for why the FULL text
+     * is checked, not just the object's name.
      */
     encodeCatalogDDL(ddl) {
-        assertNoUnpairedSurrogate(ddl, 'persisted schema text');
+        assertPersistableDdlText(ddl);
         return new TextEncoder().encode(ddl);
     }
     /**
@@ -2792,7 +2945,8 @@ export class StoreModule {
      * {@link persistObjectCatalogEntryIfChanged}.
      */
     async saveViewDDL(view) {
-        await this.persistObjectCatalogEntryIfChanged(buildViewCatalogKey(view.schemaName, view.name), generateViewDDL(view));
+        const { key, ddl } = viewCatalogEntry(view);
+        await this.persistObjectCatalogEntryIfChanged(key, ddl);
     }
     /** Remove a plain view's catalog entry (on DROP VIEW). */
     async removeViewDDL(schemaName, viewName) {
@@ -2806,13 +2960,50 @@ export class StoreModule {
      * {@link persistObjectCatalogEntryIfChanged}.
      */
     async saveMaterializedViewDDL(mv) {
-        await this.persistObjectCatalogEntryIfChanged(buildMaterializedViewCatalogKey(mv.schemaName, mv.name), generateMaintainedTableDDL(mv));
+        const entry = maintainedViewCatalogEntry(mv);
+        // Callers only reach here with a maintained table; the guard keeps the shared
+        // helper's `undefined` arm honest rather than asserting non-null.
+        if (!entry)
+            return;
+        await this.persistObjectCatalogEntryIfChanged(entry.key, entry.ddl);
     }
     /** Remove a materialized view's catalog entry (on DROP MATERIALIZED VIEW). */
     async removeMaterializedViewDDL(schemaName, mvName) {
         const catalogStore = await this.provider.getCatalogStore();
         await catalogStore.delete(buildMaterializedViewCatalogKey(schemaName, mvName));
     }
+    /**
+     * Pre-flight veto (see `VirtualTableModule.assertCatalogObjectPersistable`): refuse a
+     * view / materialized view whose catalog entry this module could not durably write.
+     *
+     * It runs exactly the derivation the write path runs — {@link viewCatalogEntry} /
+     * {@link maintainedViewCatalogEntry} build the key (rejecting an unencodable
+     * identifier) and {@link assertPersistableDdlText} checks the generated DDL text —
+     * so the veto and the write cannot disagree about what is persistable. It is the only
+     * synchronous path a rejection can travel: the actual save is chained onto
+     * `persistQueue` behind a `SchemaChangeNotifier` listener, and both layers swallow.
+     *
+     * Gated on `subscribedDb === db`: this module persists a view/MV only while subscribed
+     * to that `Database`'s change notifier ({@link ensureSchemaSubscription}, driven by the
+     * first `create`/`connect`/`alterTable`/`rehydrateCatalog`). A module registered but
+     * never handed a `db` writes nothing, so vetoing there would reject a definition that
+     * loses nothing. The gate becomes removable if persistence is ever made unconditional
+     * (`bug-store-untouched-table-and-early-view-never-persisted`).
+     */
+    // NOTE: regenerates the object's full DDL text on every CREATE VIEW / CREATE MATERIALIZED
+    // VIEW / view-or-MV SET TAGS, and the persist that follows regenerates it again. DDL is
+    // rare and the text is small, so the duplicate render is not worth caching today; if a
+    // schema-heavy workload (a large `apply schema` deploying many views) ever shows up hot
+    // here, thread the already-built CatalogEntry from the veto through to the write.
+    assertCatalogObjectPersistable(db, kind, object) {
+        if (this.subscribedDb !== db)
+            return;
+        const entry = kind === 'view'
+            ? viewCatalogEntry(object)
+            : maintainedViewCatalogEntry(object);
+        if (entry)
+            assertPersistableDdlText(entry.ddl);
+    }
     /**
      * Compare-write a view/MV catalog entry: write only when the entry is absent or its
      * DDL differs from `newDDL` (skip identical). Unlike the table path's
@@ -3203,6 +3394,21 @@ async function* rowsFromEntries(entries) {
         yield deserializeRow(entry.value);
     }
 }
+/**
+ * Read-side wrap for a value-rewriting ALTER COLUMN's pre-mutation UNIQUE probe: each row's
+ * value at `colIndex` run through `convert` (the sub-branch's deferred `valueConvert`, which
+ * owns its own NULL handling), so the probe judges the POST-alter values while the store
+ * still holds the old ones. Mutates nothing — the memory module's `convertRowAtIndex`
+ * counterpart. A conversion failure propagates: the setDataType pre-pass already proved
+ * every visible value convertible, so a throw here is unreachable, and surfacing it beats
+ * probing a stale value that could mask a collision.
+ */
+async function* convertRowsAtIndex(rows, colIndex, convert) {
+    for await (const row of rows) {
+        const newVal = convert(row[colIndex]);
+        yield newVal === row[colIndex] ? row : row.map((v, i) => i === colIndex ? newVal : v);
+    }
+}
 /**
  * Per-column key normalizers for a UNIQUE INDEX dedupe signature, drawing each column's
  * collation from the index column (if it carries one) else the underlying table column —
@@ -3210,7 +3416,7 @@ async function* rowsFromEntries(entries) {
  * write-time enforcement.
  *
  * A column whose declared type can never hold text takes the identity normalizer regardless
- * of its collation (`serializeRowKey` normalizes only string values), so a comparator-only
+ * of its collation (the signature serializer normalizes only string values), so a comparator-only
  * collation named on an integer column is not rejected here when the engine's own hash sites
  * would accept it.
  */
@@ -3222,20 +3428,38 @@ function indexDedupeNormalizers(tableSchema, indexSchema, keyNormalizers) {
             : undefined);
     });
 }
+/**
+ * Collation- and identity-aware dedupe signature of `row` over `colIndices`: each value
+ * runs through its column's key transform (`storeSemanticKeyTransform` — TIMESPAN's
+ * total-seconds `groupKey`, so 'PT1H' and 'PT60M' sign identically; JSON's structural
+ * bytes, so reorder-equal objects sign identically) before `serializeKey` applies the
+ * per-column normalizer. Returns null when any covered value
+ * is NULL (SQL UNIQUE allows multiple NULLs). The build/validate-time twin of the
+ * write-time typed compare in `StoreTable.uniqueColumnComparators`.
+ */
+function dedupeRowSignature(row, colIndices, normalizers, transforms) {
+    const values = colIndices.map((c, i) => {
+        const v = row[c];
+        const transform = transforms[i];
+        return transform && v !== null ? transform(v) : v;
+    });
+    return serializeKey(values, normalizers);
+}
 /**
  * Throws CONSTRAINT on the first pair of `rows` that share a signature over `columnIndices`.
  *
- * SQL NULL semantics: `serializeRowKey` returns null when any constrained column is NULL, and
- * such rows never collide. A partial `predicate` restricts the judged set to rows it accepts
- * unambiguously. Shared by {@link StoreModule.validateUniqueOverExistingRows} (constraint
- * columns) and {@link StoreModule.validateUniqueIndexOverRows} (index columns).
+ * SQL NULL semantics: {@link dedupeRowSignature} returns null when any constrained column is
+ * NULL, and such rows never collide. A partial `predicate` restricts the judged set to rows
+ * it accepts unambiguously. Shared by {@link StoreModule.validateUniqueOverExistingRows}
+ * (constraint columns) and {@link StoreModule.validateUniqueIndexOverRows} (index columns).
  */
 async function assertNoDuplicateRows(rows, tableSchema, columnIndices, normalizers, predicate) {
+    const transforms = columnIndices.map(i => storeSemanticKeyTransform(tableSchema.columns[i]?.logicalType));
     const seen = new Set();
     for await (const row of rows) {
         if (predicate && predicate.evaluate(row) !== true)
             continue;
-        const keySig = serializeRowKey(row, columnIndices, normalizers);
+        const keySig = dedupeRowSignature(row, columnIndices, normalizers, transforms);
         if (keySig === null)
             continue;
         if (seen.has(keySig)) {