bazis 0.96.1

package/library/orm/Schema/SafeAdditiveSchema.ts

@@ -0,0 +1,100 @@
+import { renderCheck } from "./CheckExpression";
+import type { OrmExpectedSchema, ExpectedColumn, ExpectedTable } from "./ExpectedSchema";
+import type { IntrospectedSchema } from "./introspection";
+import type { SchemaDifference, SchemaVerificationResult } from "./ExactSchemaVerifier";
+
+export type SafeAdditiveSchemaOperation =
+  | { readonly kind: "createSchema"; readonly schema: string }
+  | { readonly kind: "createTable"; readonly table: ExpectedTable }
+  | { readonly kind: "addColumn"; readonly table: ExpectedTable; readonly column: ExpectedColumn }
+  | { readonly kind: "addCheck"; readonly table: ExpectedTable; readonly check: ExpectedTable["checks"][number] }
+  | { readonly kind: "addForeignKey"; readonly table: ExpectedTable; readonly foreignKey: ExpectedTable["foreignKeys"][number] }
+  | { readonly kind: "createIndex"; readonly table: ExpectedTable; readonly index: ExpectedTable["indexes"][number] };
+
+export interface SafeAdditivePreflight { readonly verification: SchemaVerificationResult; readonly hardDifferences: readonly SchemaDifference[]; readonly plan?: readonly SafeAdditiveSchemaOperation[] }
+
+/** Classifies a complete catalog snapshot before any DDL is rendered or executed. */
+export function classifySafeAdditive(expected: OrmExpectedSchema, actual: IntrospectedSchema, verification: SchemaVerificationResult): SafeAdditivePreflight {
+  const hard = verification.differences.filter((difference) => !isPotentialAddition(difference));
+  const plan: SafeAdditiveSchemaOperation[] = [];
+  const existingSchemas = new Set(actual.schemas ?? ["public"]);
+  for (const table of expected.tables) {
+    const found = actual.tables.get(`${table.schema}.${table.table}`);
+    if (!found) {
+      if (table.schema !== "public" && !existingSchemas.has(table.schema)) { plan.push({ kind: "createSchema", schema: table.schema }); existingSchemas.add(table.schema); }
+      plan.push({ kind: "createTable", table });
+      for (const foreignKey of table.foreignKeys) plan.push({ kind: "addForeignKey", table, foreignKey });
+      for (const index of table.indexes) plan.push({ kind: "createIndex", table, index });
+      continue;
+    }
+    for (const column of table.columns) if (!found.columns.has(column.column)) {
+      if (column.generation !== "none" || (!column.nullable && (column.default.kind === "none" || column.default.kind === "null"))) {
+        hard.push(...verification.differences.filter((d) => d.schema === table.schema && d.table === table.table && d.code === "column.missing" && d.objectName === column.column));
+      } else plan.push({ kind: "addColumn", table, column });
+    }
+    for (const check of table.checks) if (!(found.checks ?? []).some((item) => item.name === check.name)) plan.push({ kind: "addCheck", table, check });
+    for (const foreignKey of table.foreignKeys) if (!(found.foreignKeys ?? []).some((item) => item.name === foreignKey.name)) plan.push({ kind: "addForeignKey", table, foreignKey });
+    for (const index of table.indexes) if (!found.indexes.some((item) => !item.backingConstraint && item.name === index.name)) plan.push({ kind: "createIndex", table, index });
+  }
+  const uniqueHard = deduplicate(hard);
+  if (uniqueHard.length) return { verification, hardDifferences: uniqueHard };
+  return { verification, hardDifferences: [], plan: Object.freeze(plan.sort(compareOperation)) };
+}
+
+function isPotentialAddition(difference: SchemaDifference): boolean {
+  return difference.code === "table.missing" || difference.code === "column.missing" || difference.code === "index.missing" || difference.code === "foreignKey.missing" || difference.code === "check.missing";
+}
+function deduplicate(differences: readonly SchemaDifference[]): readonly SchemaDifference[] {
+  const seen = new Set<string>();
+  return differences.filter((value) => { const key = `${value.schema}\0${value.table}\0${value.code}\0${value.objectName ?? ""}`; if (seen.has(key)) return false; seen.add(key); return true; });
+}
+const stage: Record<SafeAdditiveSchemaOperation["kind"], number> = { createSchema: 0, createTable: 1, addColumn: 2, addCheck: 3, addForeignKey: 4, createIndex: 5 };
+function compareOperation(a: SafeAdditiveSchemaOperation, b: SafeAdditiveSchemaOperation): number {
+  const stageDifference = stage[a.kind] - stage[b.kind];
+  if (stageDifference) return stageDifference;
+  return bytes(operationIdentity(a), operationIdentity(b));
+}
+function operationIdentity(operation: SafeAdditiveSchemaOperation): string {
+  if (operation.kind === "createSchema") return operation.schema;
+  const table = operation.table;
+  const name = operation.kind === "createTable" ? table.table : operation.kind === "addColumn" ? operation.column.column : operation.kind === "addCheck" ? operation.check.name : operation.kind === "addForeignKey" ? operation.foreignKey.name : operation.index.name;
+  return `${table.schema}\0${table.table}\0${name}`;
+}
+function bytes(a: string, b: string): number { return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8")); }
+
+/** Pure PostgreSQL renderer. Parameters/rows/raw fragments never enter the plan. */
+export function renderSafeAdditivePostgres(operation: SafeAdditiveSchemaOperation): string {
+  switch (operation.kind) {
+    case "createSchema": return `CREATE SCHEMA ${q(operation.schema)}`;
+    case "createTable": return createTable(operation.table);
+    case "addColumn": return `ALTER TABLE ${tableName(operation.table)} ADD COLUMN ${column(operation.column)}`;
+    case "addCheck": return `ALTER TABLE ${tableName(operation.table)} ADD CONSTRAINT ${q(operation.check.name)} CHECK (${renderCheck(operation.check.expression as never, q)})`;
+    case "addForeignKey": return `ALTER TABLE ${tableName(operation.table)} ADD CONSTRAINT ${q(operation.foreignKey.name)} FOREIGN KEY (${operation.foreignKey.columns.map(q).join(", ")}) REFERENCES ${q(operation.foreignKey.target.schema)}.${q(operation.foreignKey.target.table)} (${operation.foreignKey.targetColumns.map(q).join(", ")}) ON DELETE ${action(operation.foreignKey.onDelete)} ON UPDATE ${action(operation.foreignKey.onUpdate)}`;
+    case "createIndex": return `CREATE ${operation.index.unique ? "UNIQUE " : ""}INDEX ${q(operation.index.name)} ON ${tableName(operation.table)} (${operation.index.columns.map(q).join(", ")})`;
+  }
+}
+function createTable(table: ExpectedTable): string {
+  const parts = table.columns.map(column);
+  parts.push(`CONSTRAINT ${q(table.primaryKey.name)} PRIMARY KEY (${table.primaryKey.columns.map(q).join(", ")})`);
+  for (const check of table.checks) parts.push(`CONSTRAINT ${q(check.name)} CHECK (${renderCheck(check.expression as never, q)})`);
+  return `CREATE TABLE ${tableName(table)} (${parts.join(", ")})`;
+}
+function column(value: ExpectedColumn): string {
+  const pieces = [q(value.column), type(value.physicalType)];
+  if (value.generation === "identityByDefault") pieces.push("GENERATED BY DEFAULT AS IDENTITY");
+  if (value.default.kind !== "none") pieces.push(`DEFAULT ${literal(value.default, value.physicalType)}`);
+  if (!value.nullable) pieces.push("NOT NULL");
+  return pieces.join(" ");
+}
+function literal(value: ExpectedColumn["default"], physicalType: string): string {
+  if (physicalType === "json") {
+    const json = value.kind === "null" ? "null" : value.kind === "boolean" || value.kind === "number" ? String(value.value) : value.kind === "string" ? JSON.stringify(value.value) : undefined;
+    if (json === undefined) throw new Error("Unrenderable PostgreSQL JSON schema default.");
+    return `'${json.replaceAll("'", "''")}'::jsonb`;
+  }
+  switch (value.kind) { case "null": return "NULL"; case "boolean": return value.value ? "TRUE" : "FALSE"; case "number": return String(value.value); case "string": return `'${value.value.replaceAll("'", "''")}'`; case "uuidV4": return "gen_random_uuid()"; default: throw new Error("Unrenderable PostgreSQL schema default."); }
+}
+function type(value: string): string { return value === "integer" ? "bigint" : value === "real" ? "double precision" : value === "datetime" ? "timestamptz" : value === "json" ? "jsonb" : value; }
+function q(value: string): string { return `"${value.replaceAll('"', '""')}"`; }
+function tableName(table: Pick<ExpectedTable, "schema" | "table">): string { return `${q(table.schema)}.${q(table.table)}`; }
+function action(value: string): string { return value === "noAction" ? "NO ACTION" : value === "setNull" ? "SET NULL" : value.toUpperCase(); }

package/library/orm/Schema/SchemaAdmission.ts

@@ -0,0 +1,62 @@
+import type { DatabaseProvider, SchemaAdmissionScope } from "../Providers/types";
+import { SchemaAdmissionError, SchemaMigrationRequiredError, SchemaVerificationError } from "../errors";
+import type { OrmModel } from "../Metadata/OrmModel";
+import { compileExpectedSchema, type OrmExpectedSchema } from "./ExpectedSchema";
+import { ExactSchemaVerifier } from "./ExactSchemaVerifier";
+import { classifySafeAdditive, renderSafeAdditivePostgres } from "./SafeAdditiveSchema";
+
+/** PostgreSQL-private trace boundary; deliberately absent from public capability types. */
+type TraceableSchemaAdmissionScope = SchemaAdmissionScope & {
+  readonly executeSchemaAdmission?: (sql: string, operation: string) => ReturnType<SchemaAdmissionScope["execute"]>;
+};
+
+/** PostgreSQL-only create-missing-whole-tables and exact admission. */
+export class SchemaAdmissionEngine {
+  constructor(private readonly provider: DatabaseProvider, private readonly models: OrmModel) {}
+  async ensureCreated(): Promise<void> {
+    let expected: OrmExpectedSchema;
+    try {
+      expected = compileExpectedSchema(this.models);
+    } catch {
+      throw new SchemaAdmissionError("ORM_SCHEMA_MODEL_INVALID", "The declared ORM model cannot be admitted.");
+    }
+    const capability = this.provider.schemaAdmissionCapability;
+    if (!capability || this.provider.name !== "postgres" || capability.provider !== "postgres") throw new SchemaAdmissionError("ORM_SCHEMA_PROVIDER_UNSUPPORTED", "PostgreSQL schema admission capability is unavailable.");
+    if (capability.version !== 1 || !capability.distributedLock || !capability.transactionalDdl || !capability.exactIntrospection) {
+      throw new SchemaAdmissionError("ORM_SCHEMA_ATOMICITY_UNAVAILABLE", "PostgreSQL schema admission cannot guarantee atomic exact verification.");
+    }
+    try {
+      await capability.withSchemaAdmission([...new Set(expected.tables.map((table) => table.schema))], async (scope) => this.admit(scope, expected));
+    } catch (error) {
+      if (error instanceof SchemaAdmissionError) throw error;
+      throw new SchemaAdmissionError("ORM_SCHEMA_ATOMICITY_UNAVAILABLE", "PostgreSQL schema admission could not complete safely.");
+    }
+  }
+  private async admit(scope: SchemaAdmissionScope, expected: OrmExpectedSchema): Promise<void> {
+    const before = await scope.introspectExpected(expected);
+    const initial = new ExactSchemaVerifier().verify(expected, before, true);
+    const preflight = classifySafeAdditive(expected, before, initial);
+    if (preflight.hardDifferences.length) {
+      if (preflight.hardDifferences.some((difference) => difference.code === "catalog.unsupported")) throw new SchemaAdmissionError("ORM_SCHEMA_CATALOG_UNSUPPORTED", "PostgreSQL catalog contains a schema form unsupported by exact admission.");
+      throw new SchemaMigrationRequiredError(preflight.verification);
+    }
+    for (const operation of preflight.plan ?? []) {
+      try {
+        const sql = renderSafeAdditivePostgres(operation);
+        const traceable = scope as TraceableSchemaAdmissionScope;
+        if (traceable.executeSchemaAdmission) await traceable.executeSchemaAdmission(sql, operation.kind);
+        else await scope.execute(sql, []);
+      }
+      catch (error) { throw this.mapDdlError(operation.kind, error); }
+    }
+    const final = new ExactSchemaVerifier().verify(expected, await scope.introspectExpected(expected));
+    if (!final.compatible) throw new SchemaVerificationError(final);
+  }
+  private mapDdlError(kind: string, error: unknown): SchemaAdmissionError {
+    const sqlState = typeof error === "object" && error !== null
+      ? String((error as { code?: unknown; sqlState?: unknown; errno?: unknown }).sqlState ?? (error as { errno?: unknown }).errno ?? (error as { code?: unknown }).code ?? "")
+      : "";
+    if (["23502", "23503", "23505", "23514"].includes(sqlState)) return new SchemaAdmissionError("ORM_SCHEMA_ADDITIVE_DATA_VIOLATION", "Existing PostgreSQL data violates the declared additive schema change.");
+    return new SchemaAdmissionError(kind === "createSchema" || kind === "createTable" ? "ORM_SCHEMA_CREATE_FAILED" : "ORM_SCHEMA_ADDITIVE_DDL_FAILED", "PostgreSQL additive schema admission failed.");
+  }
+}

package/library/orm/Schema/SchemaDiffer.ts

@@ -0,0 +1,78 @@
+import { entityStorageKey } from "./tableKey";
+import type { EntityModel, IndexModel, PropertyModel } from "../Metadata/types";
+import type { IntrospectedSchema, IntrospectedTable } from "./introspection";
+
+/**
+ * Additive schema change operation. Destructive changes (drop/type change) never
+ * get here; they are recorded as warnings so no data is lost.
+ */
+export type AdditiveSchemaOperation =
+  | { readonly kind: "createTable"; readonly model: EntityModel }
+  | { readonly kind: "addColumn"; readonly model: EntityModel; readonly property: PropertyModel }
+  | { readonly kind: "createIndex"; readonly model: EntityModel; readonly index: IndexModel };
+
+export interface SchemaDiff {
+  readonly operations: readonly AdditiveSchemaOperation[];
+  /** Destructive differences found, which the auto mode leaves alone. */
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Compares the target model (the context entities) with the actual database
+ * schema and returns a list of additive operations. The current state comes
+ * from introspection; no separate snapshot file is needed.
+ */
+export class SchemaDiffer {
+  diff(targets: readonly EntityModel[], schema: IntrospectedSchema): SchemaDiff {
+    const operations: AdditiveSchemaOperation[] = [];
+    const warnings: string[] = [];
+
+    for (const model of targets) {
+      const table =
+        schema.tables.get(entityStorageKey(model)) ?? schema.tables.get(model.tableName);
+      if (!table) {
+        // No table: create it whole (with indexes and FKs).
+        operations.push({ kind: "createTable", model });
+        for (const index of model.indexes) {
+          operations.push({ kind: "createIndex", model, index });
+        }
+        continue;
+      }
+      this.diffColumns(model, table, operations, warnings);
+      this.diffIndexes(model, table, operations);
+    }
+
+    return { operations, warnings };
+  }
+
+  private diffColumns(
+    model: EntityModel,
+    table: IntrospectedTable,
+    operations: AdditiveSchemaOperation[],
+    warnings: string[],
+  ): void {
+    for (const property of model.properties) {
+      if (!table.columns.has(property.columnName)) {
+        operations.push({ kind: "addColumn", model, property });
+      }
+    }
+    // Destructive: columns exist in the database but not in the model; never dropped automatically.
+    const modelColumns = new Set(model.properties.map((property) => property.columnName));
+    for (const columnName of table.columns.keys()) {
+      if (!modelColumns.has(columnName)) {
+        warnings.push(
+          `table "${model.tableName}": column "${columnName}" exists in the database but not in the model (left untouched; drop it with an explicit migration).`,
+        );
+      }
+    }
+  }
+
+  private diffIndexes(model: EntityModel, table: IntrospectedTable, operations: AdditiveSchemaOperation[]): void {
+    const existing = new Set(table.indexes.map((index) => index.name));
+    for (const index of model.indexes) {
+      if (!existing.has(index.name)) {
+        operations.push({ kind: "createIndex", model, index });
+      }
+    }
+  }
+}

package/library/orm/Schema/formatSchemaDifferences.ts

@@ -0,0 +1,62 @@
+import type { SafeSchemaDescriptor, SchemaDifference, SchemaDifferenceCode, SchemaVerificationResult } from "./ExactSchemaVerifier";
+
+const descriptions: Record<SchemaDifferenceCode, string> = {
+  "table.missing": "table is missing",
+  "column.missing": "column is missing",
+  "column.unexpected": "column exists in the database but is absent from the ORM model",
+  "column.type": "column type differs",
+  "column.nullability": "column NOT NULL constraint differs",
+  "column.default": "column default differs",
+  "column.generation": "column generation strategy differs",
+  "primaryKey.missing": "primary key is missing",
+  "primaryKey.unexpected": "primary key is not declared in the ORM model",
+  "primaryKey.name": "primary key name differs",
+  "primaryKey.columns": "primary key columns or their order differ",
+  "index.missing": "index is missing",
+  "index.unexpected": "index is not declared in the ORM model",
+  "index.name": "index name differs",
+  "index.columns": "index columns or their order differ",
+  "index.uniqueness": "index uniqueness differs",
+  "index.method": "index method differs",
+  "index.unsupportedShape": "index shape is unsupported by exact schema admission",
+  "foreignKey.missing": "foreign key is missing",
+  "foreignKey.unexpected": "foreign key is not declared in the ORM model",
+  "foreignKey.name": "foreign key name differs",
+  "foreignKey.columns": "foreign key columns or their order differ",
+  "foreignKey.target": "foreign key target differs",
+  "foreignKey.actions": "foreign key referential actions differ",
+  "foreignKey.deferrable": "foreign key deferrability differs",
+  "foreignKey.match": "foreign key match type differs",
+  "check.missing": "CHECK constraint is missing",
+  "check.unexpected": "CHECK constraint is not declared in the ORM model",
+  "check.name": "CHECK constraint name differs",
+  "check.expression": "CHECK constraint expression differs",
+  "catalog.unsupported": "catalog shape is unsupported by exact schema admission",
+};
+
+/** Formats only the verifier's safe descriptors; never SQL, rows or literal defaults. */
+export function formatSchemaDifferences(verification: SchemaVerificationResult): string {
+  return verification.differences.map(formatDifference).join("\n");
+}
+
+function formatDifference(difference: SchemaDifference): string {
+  const table = `${JSON.stringify(difference.schema)}.${JSON.stringify(difference.table)}`;
+  const object = difference.objectName === undefined ? "" : `, object ${JSON.stringify(difference.objectName)}`;
+  return `- Table ${table}${object}: ${descriptions[difference.code]} (${difference.code}); `
+    + `expected (ORM): ${formatDescriptor(difference.expected, difference.code)}; actual (database): ${formatDescriptor(difference.actual, difference.code)}.`;
+}
+
+function formatDescriptor(descriptor: SafeSchemaDescriptor | undefined, code: SchemaDifferenceCode): string {
+  if (!descriptor) return "unspecified";
+  // These kinds intentionally expose fingerprints, even if a caller supplies a value.
+  if (descriptor.kind === "canonicalDefault" || descriptor.kind === "canonicalExpression") {
+    return descriptor.hash ? `${descriptor.kind} fingerprint ${JSON.stringify(descriptor.hash)}` : `${descriptor.kind} (value hidden)`;
+  }
+  if (code === "column.nullability" && descriptor.kind === "present") {
+    if (descriptor.value === "true") return "NOT NULL";
+    if (descriptor.value === "false") return "NULL allowed";
+  }
+  if (descriptor.values) return JSON.stringify(descriptor.values);
+  if (descriptor.value !== undefined) return JSON.stringify(descriptor.value);
+  return descriptor.kind;
+}

package/library/orm/Schema/introspection.ts

@@ -0,0 +1,52 @@
+/**
+ * Snapshot of the actual database schema obtained by introspection. The source
+ * of the "current" state for the additive auto-migration (the target is the
+ * model from the decorators).
+ */
+
+export interface IntrospectedColumn {
+  readonly name: string;
+  readonly notNull: boolean;
+  readonly isPrimaryKey: boolean;
+  /** Strict providers report canonical physical details; absent is fail-closed for exact verification. */
+  readonly physicalType?: string;
+  readonly default?: CanonicalDefault;
+  readonly generation?: GenerationStrategy;
+  /** Catalog form could not be decoded into the closed strict-v1 domain. */
+  readonly unsupported?: boolean;
+}
+
+export interface IntrospectedIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  readonly method?: "btree";
+  readonly backingConstraint?: boolean;
+  readonly predicate?: string;
+  readonly unsupported?: boolean;
+}
+
+export type CanonicalDefault = { readonly kind: "none" | "null" | "currentTimestamp" | "uuidV4" } | { readonly kind: "boolean"; readonly value: boolean } | { readonly kind: "number"; readonly value: number } | { readonly kind: "string"; readonly value: string };
+export type GenerationStrategy = "none" | "identityByDefault" | "uuidDefault";
+export interface IntrospectedPrimaryKey { readonly name: string; readonly columns: readonly string[] }
+export interface IntrospectedForeignKey { readonly name: string; readonly columns: readonly string[]; readonly targetSchema: string | null; readonly targetTable: string; readonly targetColumns: readonly string[]; readonly onDelete: string; readonly onUpdate: string; readonly deferrable?: boolean; readonly unsupported?: boolean }
+export interface IntrospectedCheck { readonly name: string; readonly expression: unknown; readonly unsupported?: boolean }
+
+export interface IntrospectedTable {
+  readonly name: string;
+  /** Columns by name. */
+  readonly columns: ReadonlyMap<string, IntrospectedColumn>;
+  readonly indexes: readonly IntrospectedIndex[];
+  readonly primaryKey?: IntrospectedPrimaryKey;
+  readonly foreignKeys?: readonly IntrospectedForeignKey[];
+  readonly checks?: readonly IntrospectedCheck[];
+  /** The provider observed an unsupported table-level catalog shape. */
+  readonly unsupported?: boolean;
+}
+
+export interface IntrospectedSchema {
+  /** Tables by name. */
+  readonly tables: ReadonlyMap<string, IntrospectedTable>;
+  /** Normalized physical schemas observed by the provider for this admission unit. */
+  readonly schemas?: ReadonlySet<string>;
+}

package/library/orm/Schema/physicalColumnTypes.ts

@@ -0,0 +1,37 @@
+import { isUuidKeyGeneration, type ColumnType, type EntityModel, type PropertyModel } from "../Metadata/types";
+
+/** Resolve the physical FK contract without changing logical converter types.
+ * UUID storage follows referenced keys, including PK/FK chains and cycles. */
+export function physicalColumnTypes(models: readonly EntityModel[]): ReadonlyMap<PropertyModel, ColumnType | "uuid"> {
+  const byCtor = new Map(models.map((model) => [model.ctor, model]));
+  const result = new Map<PropertyModel, ColumnType | "uuid">();
+  const pairs: [PropertyModel, PropertyModel][] = [];
+  for (const model of models) {
+    for (const property of model.properties) result.set(property, isUuidKeyGeneration(property.generation) ? "uuid" : property.type);
+    for (const fk of model.foreignKeys) {
+      const target = byCtor.get(fk.target());
+      if (!target) throw new Error("ORM_SCHEMA_CROSS_UNIT_FOREIGN_KEY");
+      if (fk.properties.length !== target.key.length) throw new Error("ORM_SCHEMA_FOREIGN_KEY_ARITY");
+      fk.properties.forEach((name, index) => {
+        const local = model.propertyByName(name);
+        if (!local) throw new Error("ORM_SCHEMA_FOREIGN_KEY_PROPERTY");
+        pairs.push([local, target.key[index]!]);
+      });
+    }
+  }
+  // Monotonic propagation terminates: each text column can become UUID once.
+  let changed: boolean;
+  do {
+    changed = false;
+    for (const [local, target] of pairs) {
+      if (result.get(target) === "uuid" && result.get(local) === "text" && local.generation === "none") {
+        result.set(local, "uuid");
+        changed = true;
+      }
+    }
+  } while (changed);
+  for (const [local, target] of pairs) {
+    if (result.get(local) !== result.get(target)) throw new Error("ORM_SCHEMA_FOREIGN_KEY_TYPE_MISMATCH");
+  }
+  return result;
+}

package/library/orm/Schema/tableKey.ts

@@ -0,0 +1,26 @@
+import type { EntityModel } from "../Metadata/types";
+
+interface TableIdentity { readonly schema?: string; readonly table: string }
+const dynamicIdentities = new WeakMap<EntityModel["ctor"], TableIdentity>();
+
+/** Legacy dynamic models expose schema.table in tableName. Retain the
+ * original components privately so literal dots are never parsed as SQL. */
+export function registerDynamicTableIdentity(ctor: EntityModel["ctor"], identity: TableIdentity): void {
+  dynamicIdentities.set(ctor, Object.freeze({ ...identity }));
+}
+
+export function physicalTableIdentity(model: EntityModel): TableIdentity {
+  const dynamic = dynamicIdentities.get(model.ctor);
+  if (model.schema === undefined && dynamic && model.tableName === (dynamic.schema ? `${dynamic.schema}.${dynamic.table}` : dynamic.table)) return dynamic;
+  return { schema: model.schema, table: model.tableName };
+}
+
+/** Table key in the introspection / diff for an `EntityModel`. */
+export function entityStorageKey(model: EntityModel): string {
+  return model.schema !== undefined ? `${model.schema}.${model.tableName}` : model.tableName;
+}
+
+/** Table key from a PostgreSQL introspection row. */
+export function introspectedTableKey(schema: string, table: string): string {
+  return schema === "public" ? table : `${schema}.${table}`;
+}