@quereus/store 4.5.0 → 4.7.0

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

@@ -0,0 +1,268 @@
+/**
+ * ALTER TABLE ... RENAME TO: the two-phase table rename. The first phase relocates the
+ * physical data / index / stats stores and writes the new catalog entry while leaving
+ * the old entry in place; the second, called by the engine once every dependent object
+ * has been rewritten, drains those dependent catalog writes and only then drops it.
+ *
+ * Seventh layer of the store-module chain:
+ *   StoreModuleBase -> StoreModuleCatalog -> StoreModuleSchemaSync -> StoreModuleIndex
+ *   -> StoreModuleAlterColumn -> StoreModuleAlter -> StoreModuleRename -> StoreModule
+ */
+import { QuereusError, StatusCode, renameTableInCheckConstraints, renameTableInColumnExpressions, renameTableInIndexPredicates, } from '@quereus/quereus';
+import { StoreConnection } from './store-connection.js';
+import { buildDataStoreName, buildIndexStoreName, buildStatsKey } from './key-builder.js';
+import { StoreModuleAlter } from './store-module-alter.js';
+import { collectOccupiedStoreNames } from './store-module-base.js';
+import { retargetSelfForeignKeys } from './store-module-schema-rewrite.js';
+export class StoreModuleRename extends StoreModuleAlter {
+    /**
+     * Rename a store-backed table.
+     *
+     * Drops every in-memory reference to the old name (so the coordinator, open
+     * handles, and cached StoreTable instance don't linger with stale paths),
+     * delegates physical storage relocation to the provider, then rewrites the
+     * persistent catalog DDL under the new key. After this returns, the next
+     * access to `newName` will reconnect via `connect()` and open fresh stores
+     * against the moved directories.
+     */
+    async renameTable(db, schemaName, oldName, newName, ddl) {
+        const oldKey = `${schemaName}.${oldName}`.toLowerCase();
+        const newKey = `${schemaName}.${newName}`.toLowerCase();
+        if (this.tables.has(newKey)) {
+            throw new QuereusError(`Store table '${newName}' already exists in schema '${schemaName}'`, StatusCode.ERROR);
+        }
+        // Capture the current schema BEFORE the guard (and before we drop in-memory
+        // references): the guard needs the index list to compute every relocated
+        // store name, and the new catalog DDL must reflect the real column set.
+        const existing = this.tables.get(oldKey);
+        const currentSchema = existing?.getSchema() ?? db.schemaManager.getTable(schemaName, oldName);
+        // Authoritative index list (exact store names): the provider relocates
+        // exactly these index stores instead of prefix-scanning `{oldName}_idx_`,
+        // which would also catch a sibling table named `{oldName}_idx_<x>`.
+        // MATERIALIZED, so the hidden `_uc_*` store realizing a plain UNIQUE moves with
+        // the table — otherwise the renamed table seeks a fresh EMPTY `_uc_*` and silently
+        // accepts a duplicate of a pre-rename row. `currentSchema` itself stays
+        // non-materialized: the catalog DDL rewritten below must carry no `_uc_*`.
+        const indexNames = this.materializedIndexNames(existing, currentSchema);
+        // Reject when ANY physical name the rename introduces — the new data store
+        // AND each relocated index store `{schema}.{newName}_idx_{x}` — already
+        // names an existing store. E.g. rename some table to `q_idx_archive` while
+        // table `q` has index `archive` (both → `{schema}.q_idx_archive`); or rename
+        // `t`→`u` while `t` has index `x` and a sibling table is literally named
+        // `u_idx_x`, which would relocate `t`'s index onto the sibling's data store.
+        // The renamed table's own current stores stay in the occupied set (see
+        // collectOccupiedStoreNames): an introduced name can only equal an own store
+        // in a footprint-swap rename providers cannot relocate safely. All checks
+        // run before the FIRST side effect (the coordinator commit, disconnect, and
+        // cache evictions below, then the physical relocation) so a colliding
+        // rename is a clean no-op.
+        const occupied = collectOccupiedStoreNames(this.tables.values(), db, schemaName, this);
+        this.assertStoreNameFree(db, schemaName, buildDataStoreName(schemaName, newName), `data store of table '${schemaName}.${newName}' (rename target)`, occupied);
+        for (const indexName of indexNames) {
+            this.assertStoreNameFree(db, schemaName, buildIndexStoreName(schemaName, newName, indexName), `index store of index '${indexName}' on table '${schemaName}.${newName}' (rename target)`, occupied);
+        }
+        // Flush buffered writes before the old store's handle is closed: once the
+        // on-disk directory moves, prior buffered ops address stores that no longer
+        // exist under those names. See `StoreModuleBase.ddlCommitPendingOps`.
+        await this.ddlCommitPendingOps();
+        // Hard-dispose the evicted handle: flush any lazy stats it was buffering AND
+        // deregister its coordinator stats-callback pair (the renamed instance is
+        // gone after this — the next connect()/getOrReconnectTable mints a fresh one
+        // that re-registers against the shared coordinator). Dispose failures must
+        // not block the physical rename.
+        if (existing) {
+            try {
+                await existing.dispose();
+            }
+            catch {
+                /* ignore — physical rename must proceed */
+            }
+        }
+        this.tables.delete(oldKey);
+        this.stores.delete(oldKey);
+        // The coordinator is module-wide (flushed above); it is not per-table, so
+        // it is not evicted here.
+        // Evict the disposed instance's registered engine connections — but ONLY the
+        // ones this module created. Unlike drop — where the engine's schema manager
+        // calls `removeConnectionsForTable` for us — the generic rename path
+        // (`alter-table.ts` renameTableImpl) does NOT, so the store must evict here or
+        // a StoreConnection leaks one per rename. Safe for `StoreConnection`s (both the
+        // StoreTable-owned DML connection and the StoreBackingHost-owned one): they hold
+        // no state of their own, delegating to the module-wide coordinator that the
+        // DDL-commit above already flushed, and their owning StoreTable is now disposed.
+        //
+        // A blanket name-keyed sweep is NOT safe: a wrapping module (the isolation layer)
+        // registers its own connection under the same qualified name, and that connection
+        // is the only thing that drives its staged overlay to storage at COMMIT. Evicting
+        // it silently drops the transaction's writes.
+        //
+        // NOTE: a rename onto a never-before-used name leaves the wrapper's connection
+        // registered under the stale old name (it is not retargeted here). Benign — the
+        // commit flush resolves overlays db-wide by their re-keyed names — but a workload
+        // that renames one table through many distinct names in a single process
+        // accumulates one such connection per name. If that ever matters, retarget the
+        // connection's `tableName` across the rename instead of leaving it stale.
+        const oldQualified = `${schemaName}.${oldName}`.toLowerCase();
+        for (const conn of db.getAllConnections()) {
+            if (conn instanceof StoreConnection && conn.tableName.toLowerCase() === oldQualified) {
+                db.removeConnection(conn.connectionId);
+            }
+        }
+        // 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);
+        }
+        // Rewrite persistent catalog under the new name. Write the new DDL first
+        // so a crash mid-rename leaves the table discoverable under at least one
+        // name rather than neither.
+        if (currentSchema) {
+            const renamedSchema = {
+                ...currentSchema,
+                name: newName,
+                // A self-referencing FK is persisted as `references <oldName>(...)`; after
+                // `removeTableDDL` below, that names a table no longer in the catalog. Pure
+                // copy — no rollback needed, `renamedSchema` is local to the write.
+                foreignKeys: retargetSelfForeignKeys(currentSchema.foreignKeys, schemaName, oldName, newName),
+            };
+            // A partial index's WHERE clause, a CHECK constraint's expression, and a column's
+            // DEFAULT / `generated always as` body can each name the OLD table — a
+            // table-qualified self-reference (`where t.b > 0`), or, for a column expression,
+            // a subquery reading it (`default ((select count(*) from t))`). All three are
+            // rendered into the persisted DDL bundle, and `propagateTableRename` runs only
+            // after this hook returns, so — exactly as in the `renameColumn` arm of
+            // `alterTable` — persisting now would durably write a stale reference that only
+            // the later propagation event corrects.
+            // Rewrite first, in place (each `Expression` is shared with the catalog
+            // `TableSchema` and, for a unique partial index, with its derived UNIQUE
+            // constraint), which also makes that later pass a no-op for these fields. A
+            // throw anywhere in the `try` — including partway through a walk — reverses the
+            // rewrites; reversing is a no-op wherever nothing names `newName`. The physical
+            // stores have already moved by this point, so the reverse restores only the AST,
+            // not the on-disk layout.
+            //
+            // NOTE: the reverse assumes no expression legitimately named `newName` before
+            // the rename. The rename-target guard above makes that true for a real table,
+            // and `compilePredicate` now rejects a foreign `table` qualifier at create time,
+            // so a live partial-index predicate can only carry a self-qualifier (`where
+            // <thisTable>.b > 0`) or a bare reference — never `where <newName>.b > 0` for a
+            // different table. The mis-reversal path is therefore unreachable for a live
+            // predicate.
+            //
+            // NOTE: that argument does NOT extend to the column-expression arm, and the
+            // residual is left open deliberately. A DEFAULT naming a table that does not
+            // exist is accepted at create time (the reference is only resolved when a row is
+            // written), so `create table u (…, v integer default ((select 1 from u2)))`
+            // followed by `alter table u rename to u2` has a forward pass that matches
+            // nothing and a reverse pass that would clobber that `u2` back to `u`. Reaching
+            // it needs `saveTableDDL` to throw, and closing it needs a per-walk changed-set
+            // threaded through every arm — not worth it for a failed-persist-only path.
+            const rewriteTable = (from, to) => {
+                renameTableInIndexPredicates(currentSchema.indexes, from, to, schemaName);
+                renameTableInCheckConstraints(currentSchema.checkConstraints, from, to, schemaName);
+                renameTableInColumnExpressions(currentSchema.columns, from, to, schemaName);
+            };
+            try {
+                rewriteTable(oldName, newName);
+                await this.saveTableDDL(renamedSchema);
+            }
+            catch (e) {
+                rewriteTable(newName, oldName);
+                throw e;
+            }
+        }
+        // NOTE: the OLD name's catalog entry is deliberately NOT removed here. Deleting it
+        // synchronously would drop `oldName` from the catalog BEFORE the engine's post-hook
+        // `propagateTableRename` has rewritten — let alone persisted — the OTHER tables /
+        // views / MVs that still name `oldName` (a cross-schema FK, a CHECK expression, a
+        // dependent view/MV body). A crash in that gap would strand a durable catalog set
+        // naming a vanished table, which reopens as a healthy-looking database whose
+        // dependents cannot be written to. The removal is deferred to `finalizeRename`,
+        // which the engine calls AFTER propagation has made the dependents durable.
+        // Migrate the stats entry (unified __stats__ store, keyed by schema.table).
+        // The entry is RE-KEYED, not physically moved with the directory: a unified
+        // store keys every table's stats under `schema.table` in one store, so the
+        // value must be copied from the old key to the new key and the old key
+        // dropped. `dispose()` above already flushed any buffered delta to disk under
+        // the old key, so the read here sees the current row-count estimate; deleting
+        // without copying (the prior behavior) blinded the planner — a freshly-renamed
+        // table reported getEstimatedRowCount() === 0 until stats were re-gathered.
+        //
+        // NOTE: this re-key reaches the old value only when getStatsStore(newName)
+        // returns a store that CONTAINS the old key — true for the shipped providers,
+        // which all share one unified __stats__ store, and for any provider whose
+        // renameTableStores physically relocates a per-table stats store. A provider
+        // that kept per-table stats stores and did NOT relocate them in
+        // renameTableStores would orphan the old-keyed value out of reach here (the
+        // prior delete-only code lost it just the same — no regression). No shipped
+        // provider does this; revisit if one ever keeps per-table, non-relocated stats.
+        try {
+            const statsStore = await this.provider.getStatsStore(schemaName, newName);
+            const oldStatsKey = buildStatsKey(schemaName, oldName);
+            const statsValue = await statsStore.get(oldStatsKey);
+            if (statsValue) {
+                // A table with no stats yet (never flushed) returns undefined here —
+                // skip the copy so no spurious zero-count entry lands under the new key.
+                await statsStore.put(buildStatsKey(schemaName, newName), statsValue);
+            }
+            await statsStore.delete(oldStatsKey);
+        }
+        catch {
+            /* stats are advisory — a stats hiccup must never block the rename */
+        }
+        // Same emit-iff-`ddl` rule as `StoreModuleAlter.alterTable`: `ddl` set means this
+        // call IS the RENAME TO statement's action; absent means an engine-internal step
+        // that must announce nothing. No in-tree caller omits it today — the shadow-table
+        // rebuild's trailing rename is itself a RENAME TO statement and is silenced by
+        // `withPublicEventsSuppressed`, not by this gate.
+        // `oldObjectName` says what the table renamed FROM — `objectName` names only the
+        // new table, and a receiver could not otherwise tell which of its tables moved.
+        if (ddl !== undefined) {
+            this.eventEmitter?.emitSchemaChange({
+                type: 'alter',
+                objectType: 'table',
+                schemaName,
+                objectName: newName,
+                oldObjectName: oldName,
+                ddl,
+            });
+        }
+    }
+    /**
+     * Second phase of a two-phase RENAME TABLE (see {@link renameTable}). The engine calls
+     * this at the END of ALTER TABLE ... RENAME TO — AFTER its `propagateTableRename` has
+     * rewritten every dependent object that named `oldName` and enqueued their corrective
+     * catalog writes onto `StoreModuleBase.persistQueue`. `renameTable` deliberately left `oldName`'s
+     * catalog entry in place; here we drain those dependent writes to durability and only
+     * THEN drop the old entry. During the window both entries coexist on disk, so every
+     * dependent resolves against one of them and every intermediate catalog set rehydrates
+     * into a working database.
+     *
+     * The old-entry delete rides `persistQueue` behind the dependents' already-enqueued
+     * writes (FIFO), so it can only run after them, and the drain below awaits the whole
+     * chain. Errors are swallowed+logged (the `StoreModuleBase.enqueuePersist` contract): a failed
+     * delete leaves the old entry present — a visible, droppable orphan, strictly safer
+     * than a dependent stranded against a vanished table.
+     *
+     * NOTE: full cross-table atomicity — bundling this old-entry delete together with every
+     * dependent rewrite into one `provider.beginAtomicBatch` commit — would eliminate even
+     * the transient two-entry window (and the physical-move orphan `renameTableStores`
+     * leaves), but only on atomic providers, and the dependent set is known only to the
+     * engine post-propagate. That is the atomic-provider hardening path; out of scope here.
+     */
+    async finalizeRename(_db, schemaName, oldName, _newName) {
+        this.enqueuePersist(() => this.removeTableDDL(schemaName, oldName));
+        await this.whenCatalogPersisted();
+    }
+}
+//# sourceMappingURL=store-module-rename.js.map

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

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

package/dist/src/common/store-module-schema-rewrite.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure schema-to-schema rewrites the module applies around DDL: reconciling an
+ * implicit-default text primary-key collation to the store's key collation at CREATE
+ * time, and retargeting a table's SELF-referencing foreign keys when the table or one
+ * of its columns is renamed.
+ *
+ * Free functions rather than a layer of the store-module chain — each takes a schema
+ * and returns a schema, reading no module state.
+ */
+import type { ForeignKeyConstraintSchema, TableSchema } from '@quereus/quereus';
+/**
+ * Reconcile each text PRIMARY KEY column's declared collation at CREATE time.
+ *
+ * The store now encodes PRIMARY KEY uniqueness/ordering PHYSICALLY with a
+ * PER-COLUMN key collation (`StoreTable.pkKeyCollations`, drawn from each PK
+ * column's declared `collation`), so ANY declared PK collation is honored
+ * natively — an explicit `collate binary` text PK is keyed under BINARY, a
+ * `collate nocase` under NOCASE, etc. The only thing this reconcile still does is
+ * supply the store's table-level DEFAULT (`keyCollation` = K = `config.collation`,
+ * default NOCASE) to a text PK column that declares NO explicit collation, so an
+ * implicit-default text PK keeps the store's historical NOCASE-keyed behavior
+ * (rather than the engine's BINARY column default). An EXPLICIT collation — even
+ * one diverging from K — is left exactly as declared and re-keyed natively.
+ *
+ * Collation governs key bytes only for text, so only PK members whose logical type
+ * is textual are touched (an `integer primary key` keeps its BINARY; temporal
+ * text-physical types carry no collation). Non-PK columns are never touched.
+ *
+ * This is the CREATE path only — the load path (`connect` / rehydrate) does not
+ * reconcile; the persisted DDL is the source of truth on reopen, and the column's
+ * (BINARY-elided) `COLLATE` clause round-trips the per-column key collation.
+ *
+ * Returns the schema unchanged when no implicit text PK column needs the default
+ * applied; otherwise a new schema with a rebuilt `columns` array + `columnIndexMap`.
+ */
+export declare function reconcilePkCollations(schema: TableSchema, keyCollation: string): TableSchema;
+/**
+ * Build a column remap array: newColumnIndex -> oldColumnIndex | -1.
+ * Maps each column in the new layout to its position in the old layout.
+ * -1 means the column is new (fill with default).
+ */
+export declare function buildColumnRemap(oldColumnNames: string[], newColumnNames: string[]): number[];
+/**
+ * Retarget a self-referencing foreign key's `referencedTable` across a rename of
+ * the owning table. A pure copy — unlike the CHECK / partial-index rewrites this
+ * touches a name field, not a shared AST, so the caller needs no rollback.
+ * Returns the input array when nothing self-references.
+ */
+export declare function retargetSelfForeignKeys(fks: ReadonlyArray<ForeignKeyConstraintSchema> | undefined, schemaName: string, oldName: string, newName: string): ReadonlyArray<ForeignKeyConstraintSchema> | undefined;
+/**
+ * Rename a column inside a self-referencing foreign key's `referencedColumnNames`
+ * (the names the FK resolves to parent-column indices at enforcement time). Pure
+ * copy, as in {@link retargetSelfForeignKeys}. The child-side `columns` are
+ * indices, unaffected by a rename.
+ */
+export declare function renameColumnInSelfForeignKeys(fks: ReadonlyArray<ForeignKeyConstraintSchema> | undefined, schemaName: string, tableName: string, oldCol: string, newCol: string): ReadonlyArray<ForeignKeyConstraintSchema> | undefined;
+//# sourceMappingURL=store-module-schema-rewrite.d.ts.map

package/dist/src/common/store-module-schema-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-module-schema-rewrite.d.ts","sourceRoot":"","sources":["../../../src/common/store-module-schema-rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGhF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,MAAM,GAClB,WAAW,CAkCb;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAS7F;AAYD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,aAAa,CAAC,0BAA0B,CAAC,GAAG,SAAS,EAC1D,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACb,aAAa,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAWvD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC5C,GAAG,EAAE,aAAa,CAAC,0BAA0B,CAAC,GAAG,SAAS,EAC1D,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACZ,aAAa,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAiBvD"}

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

@@ -0,0 +1,140 @@
+/**
+ * Pure schema-to-schema rewrites the module applies around DDL: reconciling an
+ * implicit-default text primary-key collation to the store's key collation at CREATE
+ * time, and retargeting a table's SELF-referencing foreign keys when the table or one
+ * of its columns is renamed.
+ *
+ * Free functions rather than a layer of the store-module chain — each takes a schema
+ * and returns a schema, reading no module state.
+ */
+import { buildColumnIndexMap } from '@quereus/quereus';
+/**
+ * Reconcile each text PRIMARY KEY column's declared collation at CREATE time.
+ *
+ * The store now encodes PRIMARY KEY uniqueness/ordering PHYSICALLY with a
+ * PER-COLUMN key collation (`StoreTable.pkKeyCollations`, drawn from each PK
+ * column's declared `collation`), so ANY declared PK collation is honored
+ * natively — an explicit `collate binary` text PK is keyed under BINARY, a
+ * `collate nocase` under NOCASE, etc. The only thing this reconcile still does is
+ * supply the store's table-level DEFAULT (`keyCollation` = K = `config.collation`,
+ * default NOCASE) to a text PK column that declares NO explicit collation, so an
+ * implicit-default text PK keeps the store's historical NOCASE-keyed behavior
+ * (rather than the engine's BINARY column default). An EXPLICIT collation — even
+ * one diverging from K — is left exactly as declared and re-keyed natively.
+ *
+ * Collation governs key bytes only for text, so only PK members whose logical type
+ * is textual are touched (an `integer primary key` keeps its BINARY; temporal
+ * text-physical types carry no collation). Non-PK columns are never touched.
+ *
+ * This is the CREATE path only — the load path (`connect` / rehydrate) does not
+ * reconcile; the persisted DDL is the source of truth on reopen, and the column's
+ * (BINARY-elided) `COLLATE` clause round-trips the per-column key collation.
+ *
+ * Returns the schema unchanged when no implicit text PK column needs the default
+ * applied; otherwise a new schema with a rebuilt `columns` array + `columnIndexMap`.
+ */
+export function reconcilePkCollations(schema, keyCollation) {
+    const pkIndices = new Set(schema.primaryKeyDefinition.map(def => def.index));
+    if (pkIndices.size === 0)
+        return schema;
+    let changed = false;
+    const newColumns = schema.columns.map((col, idx) => {
+        if (!pkIndices.has(idx))
+            return col;
+        // Collation governs key bytes only for text; non-text PK columns (integer,
+        // real, blob, …) are encoded type-natively and keep their declared collation.
+        // Deliberately `isTextual`, NOT `collationAware`: `any` now keys (and
+        // compares) under its declared collation, but an undecorated `any` PK's
+        // declared collation is always BINARY — `resolveDefaultCollation` never
+        // applies a non-BINARY default to ANY, which declares no supported-collation
+        // list — and rewriting it to K here would silently flip that shape's
+        // comparison semantics store-side only, diverging from the memory backend
+        // for no compatibility gain (the historical K-default covers text PKs, not
+        // `any`). Only `text` takes the rewrite.
+        if (!col.logicalType.isTextual)
+            return col;
+        // An EXPLICIT collation is honored as-declared — the per-column key encoding
+        // keys the column under it (Option B physical re-key parity with memory).
+        if (col.collationExplicit)
+            return col;
+        const declared = (col.collation || 'BINARY').toUpperCase();
+        if (declared === keyCollation)
+            return col; // implicit default already == K
+        // Implicit default diverges from K (e.g. the engine's BINARY column default
+        // under the store's NOCASE K): apply the store's table-level default so an
+        // undecorated text PK keeps the store's historical NOCASE-keyed semantics.
+        changed = true;
+        return { ...col, collation: keyCollation };
+    });
+    if (!changed)
+        return schema;
+    const columns = Object.freeze(newColumns);
+    return { ...schema, columns, columnIndexMap: buildColumnIndexMap(columns) };
+}
+/**
+ * Build a column remap array: newColumnIndex -> oldColumnIndex | -1.
+ * Maps each column in the new layout to its position in the old layout.
+ * -1 means the column is new (fill with default).
+ */
+export function buildColumnRemap(oldColumnNames, newColumnNames) {
+    const oldIndexByName = new Map();
+    for (let i = 0; i < oldColumnNames.length; i++) {
+        oldIndexByName.set(oldColumnNames[i].toLowerCase(), i);
+    }
+    return newColumnNames.map(name => {
+        const oldIdx = oldIndexByName.get(name.toLowerCase());
+        return oldIdx !== undefined ? oldIdx : -1;
+    });
+}
+/** Whether `fk` points back at the table that owns it. */
+function isSelfForeignKey(fk, schemaLower, tableLower) {
+    return (fk.referencedSchema ?? schemaLower).toLowerCase() === schemaLower
+        && fk.referencedTable.toLowerCase() === tableLower;
+}
+/**
+ * Retarget a self-referencing foreign key's `referencedTable` across a rename of
+ * the owning table. A pure copy — unlike the CHECK / partial-index rewrites this
+ * touches a name field, not a shared AST, so the caller needs no rollback.
+ * Returns the input array when nothing self-references.
+ */
+export function retargetSelfForeignKeys(fks, schemaName, oldName, newName) {
+    if (!fks)
+        return fks;
+    const schemaLower = schemaName.toLowerCase();
+    const oldLower = oldName.toLowerCase();
+    let changed = false;
+    const next = fks.map(fk => {
+        if (!isSelfForeignKey(fk, schemaLower, oldLower))
+            return fk;
+        changed = true;
+        return { ...fk, referencedTable: newName };
+    });
+    return changed ? Object.freeze(next) : fks;
+}
+/**
+ * Rename a column inside a self-referencing foreign key's `referencedColumnNames`
+ * (the names the FK resolves to parent-column indices at enforcement time). Pure
+ * copy, as in {@link retargetSelfForeignKeys}. The child-side `columns` are
+ * indices, unaffected by a rename.
+ */
+export function renameColumnInSelfForeignKeys(fks, schemaName, tableName, oldCol, newCol) {
+    if (!fks)
+        return fks;
+    const schemaLower = schemaName.toLowerCase();
+    const tableLower = tableName.toLowerCase();
+    const oldColLower = oldCol.toLowerCase();
+    let changed = false;
+    const next = fks.map(fk => {
+        if (!isSelfForeignKey(fk, schemaLower, tableLower))
+            return fk;
+        if (!fk.referencedColumnNames?.some(n => n.toLowerCase() === oldColLower))
+            return fk;
+        changed = true;
+        return {
+            ...fk,
+            referencedColumnNames: Object.freeze(fk.referencedColumnNames.map(n => n.toLowerCase() === oldColLower ? newCol : n)),
+        };
+    });
+    return changed ? Object.freeze(next) : fks;
+}
+//# sourceMappingURL=store-module-schema-rewrite.js.map

package/dist/src/common/store-module-schema-rewrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-module-schema-rewrite.js","sourceRoot":"","sources":["../../../src/common/store-module-schema-rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qBAAqB,CACpC,MAAmB,EACnB,YAAoB;IAEpB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7E,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAExC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAClD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACpC,2EAA2E;QAC3E,8EAA8E;QAC9E,sEAAsE;QACtE,wEAAwE;QACxE,wEAAwE;QACxE,6EAA6E;QAC7E,qEAAqE;QACrE,0EAA0E;QAC1E,2EAA2E;QAC3E,yCAAyC;QACzC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,SAAS;YAAE,OAAO,GAAG,CAAC;QAC3C,6EAA6E;QAC7E,0EAA0E;QAC1E,IAAI,GAAG,CAAC,iBAAiB;YAAE,OAAO,GAAG,CAAC;QACtC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3D,IAAI,QAAQ,KAAK,YAAY;YAAE,OAAO,GAAG,CAAC,CAAC,gCAAgC;QAE3E,4EAA4E;QAC5E,2EAA2E;QAC3E,2EAA2E;QAC3E,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC;IAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAwB,EAAE,cAAwB;IAClF,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QAChC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QACtD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,0DAA0D;AAC1D,SAAS,gBAAgB,CACxB,EAA8B,EAC9B,WAAmB,EACnB,UAAkB;IAElB,OAAO,CAAC,EAAE,CAAC,gBAAgB,IAAI,WAAW,CAAC,CAAC,WAAW,EAAE,KAAK,WAAW;WACrE,EAAE,CAAC,eAAe,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACtC,GAA0D,EAC1D,UAAkB,EAClB,OAAe,EACf,OAAe;IAEf,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QACzB,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,CAAC;YAAE,OAAO,EAAE,CAAC;QAC5D,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,EAAE,GAAG,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAC5C,GAA0D,EAC1D,UAAkB,EAClB,SAAiB,EACjB,MAAc,EACd,MAAc;IAEd,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IAC7C,MAAM,UAAU,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QACzB,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,WAAW,EAAE,UAAU,CAAC;YAAE,OAAO,EAAE,CAAC;QAC9D,IAAI,CAAC,EAAE,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC;YAAE,OAAO,EAAE,CAAC;QACrF,OAAO,GAAG,IAAI,CAAC;QACf,OAAO;YACN,GAAG,EAAE;YACL,qBAAqB,EAAE,MAAM,CAAC,MAAM,CACnC,EAAE,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SACjF,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC5C,CAAC"}