bazis 0.98.19 → 0.98.21

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.19" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.21" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/Bazis.ts

@@ -1,10 +1,10 @@
-import { inspect } from "node:util";
 import { DiError } from "../di";
 import { Kernel } from "./Kernel";
 import { KernelBuilder, type RootModuleInput } from "./KernelBuilder";
 import { KernelError, ShutdownTimeoutError } from "./errors";
 import type { KernelOptions } from "./types";
-import { redactSensitive, redactSensitiveText } from "../../library/redaction";
+import { redactSensitiveText } from "../../library/redaction";
+import { formatStartupFailure } from "./startupFailure";
 
 /**
  * Entry-point facade.
@@ -61,10 +61,7 @@ export class Bazis {
       if (error instanceof DiError || error instanceof KernelError) {
         console.error(`[bazis] configuration error: ${redactSensitiveText(error.message)}`);
       } else {
-        console.error("[bazis] application failed:", inspect(redactSensitive(error), {
-          depth: null, colors: false, customInspect: false, getters: false,
-          maxArrayLength: null, maxStringLength: null,
-        }));
+        console.error(`[bazis] application failed: ${formatStartupFailure(error)}`);
       }
       process.exitCode = 1;
       return 1;

package/core/kernel/startupFailure.ts

@@ -0,0 +1,46 @@
+import { inspect } from "node:util";
+import { redactSensitive, redactSensitiveText } from "../../library/redaction";
+
+const MAX_CAUSES = 5;
+/** Properties already printed in the header, the frames or the cause chain. */
+const SHOWN = new Set(["name", "message", "stack", "cause", "code", "errno", "errors"]);
+const INSPECT = { depth: null, colors: false, customInspect: false, getters: false, maxArrayLength: null, maxStringLength: null } as const;
+
+/**
+ * Text of an application startup failure: `Name [code]: message`, the
+ * stack frames, the remaining error properties (for example a schema
+ * verification report or a PostgreSQL `detail`) and the `cause` chain. The
+ * message is printed once as plain text instead of inside an inspected object.
+ */
+export function formatStartupFailure(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return inspect(redactSensitive(error), INSPECT);
+  }
+  const lines: string[] = [];
+  let current: unknown = error;
+  for (let depth = 0; depth <= MAX_CAUSES && current !== undefined; depth += 1) {
+    const prefix = depth === 0 ? "" : "Caused by: ";
+    if (!(current instanceof Error)) {
+      lines.push(prefix + inspect(redactSensitive(current), { depth: 2, colors: false, customInspect: false, getters: false }));
+      break;
+    }
+    lines.push(`${prefix}${current.name}${codeOf(current)}: ${current.message}`);
+    if (current instanceof AggregateError) {
+      for (const inner of current.errors) lines.push(`  - ${inner instanceof Error ? `${inner.name}: ${inner.message}` : String(inner)}`);
+    }
+    lines.push(...(current.stack ?? "").split("\n").filter((line) => /^\s+at /.test(line)));
+    const details = Object.fromEntries(Object.entries(current).filter(([name]) => !SHOWN.has(name)));
+    if (Object.keys(details).length > 0) lines.push(inspect(redactSensitive(details), INSPECT));
+    current = current.cause;
+  }
+  return redactSensitiveText(lines.join("\n"));
+}
+
+function codeOf(error: Error): string {
+  // Node style: `Error [ERR_X]: message`; a database error code such as 42P01 follows it.
+  const fields = ["code", "errno"].flatMap((name) => {
+    const value = (error as unknown as Record<string, unknown>)[name];
+    return typeof value === "string" || typeof value === "number" ? [String(value)] : [];
+  });
+  return fields.length > 0 ? ` [${fields.join(", ")}]` : "";
+}

package/core/orm/OrmHostedPlan.validator.ts

@@ -21,28 +21,38 @@ function validateOrmHostedPlan(services: readonly HostedService[]): void {
       if (!framework && (service.phase ?? 0) < 0) throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Application hosted services must use phase 0 or later with ORM owned-store admission.");
     }
   }
-  const strict = services.filter((service): service is HostedService & { readonly __bazisSchemaAdmission: { readonly unit: readonly string[]; readonly tables: readonly string[]; readonly foreignKeys: readonly { readonly source: string; readonly target: string }[] } } =>
+  const strict = services.filter((service): service is HostedService & { readonly __bazisSchemaAdmission: { readonly owner?: string; readonly unit: readonly string[]; readonly tables: readonly string[]; readonly foreignKeys: readonly { readonly source: string; readonly target: string }[] } } =>
     (service as { __bazisSchemaAdmission?: unknown }).__bazisSchemaAdmission !== undefined,
   );
   if (strict.length === 0) return;
-  const owners = new Set<string>();
+  const owners = new Map<string, string>();
   for (const service of strict) {
     if ((service.phase ?? 0) !== -105) throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Schema admission has an invalid hosted phase.");
-    for (const table of service.__bazisSchemaAdmission.tables) { if (owners.has(table)) throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", "Schema admission table ownership conflicts."); owners.add(table); }
+    const owner = service.__bazisSchemaAdmission.owner ?? "A DbContext";
+    for (const table of service.__bazisSchemaAdmission.tables) {
+      const other = owners.get(table);
+      if (other !== undefined) throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", `Schema admission table ownership conflicts: table ${table} is created by both ${other} and ${owner} with ensureCreated. One context must own the table: remove the entity from the other context and refer to it by a plain id column.`);
+      owners.set(table, owner);
+    }
     const unit = new Set(service.__bazisSchemaAdmission.unit);
     for (const foreignKey of service.__bazisSchemaAdmission.foreignKeys) {
       if (!unit.has(foreignKey.source) || !unit.has(foreignKey.target)) {
-        throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", "Schema admission foreign keys must target the same explicit unit.");
+        throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", `Schema admission foreign keys must target the same explicit unit: ${owner} has a foreign key from ${foreignKey.source} to ${foreignKey.target}, which it does not create.`);
       }
     }
   }
   if (!services.some((service) => isOrmProviderLifecycle(service) && (service.phase ?? 0) === -110)) {
     throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Schema admission requires a provider lifecycle at phase -110.");
   }
+  const legacy = services.filter((service) => (service as { __bazisLegacySchemaAuthority?: unknown }).__bazisLegacySchemaAuthority === true);
+  if (legacy.length > 0) {
+    const describe = (service: HostedService) => {
+      const owner = (service as { __bazisSchemaOwner?: { context: string; mode: string } }).__bazisSchemaOwner;
+      return owner ? `${owner.context} uses ${owner.mode}` : "a module uses migrateOnStart or migrations";
+    };
+    throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", `Schema admission and legacy ORM schema authority cannot be composed together: ${[...strict, ...legacy].map(describe).join(", ")}. Use one schema mode in the application: ensureCreated (with or without migrations) in every module, or migrateOnStart/migrations without ensureCreated in every module.`);
+  }
   for (const service of services) {
-    if ((service as { __bazisLegacySchemaAuthority?: unknown }).__bazisLegacySchemaAuthority === true) {
-      throw new SchemaAdmissionError("ORM_SCHEMA_HOSTED_PHASE_CONFLICT", "Schema admission and legacy ORM schema authority cannot be composed together.");
-    }
     const framework = isOrmProviderLifecycle(service)
       || isStrictSchemaPrerequisiteLifecycle(service)
       || (service as { __bazisOrmLegacyLifecycle?: unknown }).__bazisOrmLegacyLifecycle === true

package/core/orm/OrmLifecycle.ts

@@ -1,6 +1,6 @@
 import { ormHostedPlanValidator } from "./OrmHostedPlan.validator";
 import type { HostedService } from "../di";
-import { DatabaseFacade, type DbContextOptions, type Migration } from "../../library/orm";
+import { DatabaseFacade, type DbContextOptions, type EnsureCreatedWithMigrationsResult, type Migration } from "../../library/orm";
 import { compileExpectedSchema } from "../../library/orm/Schema/ExpectedSchema";
 
 /**
@@ -22,10 +22,15 @@ export class OrmLifecycle implements HostedService {
   readonly __bazisLegacySchemaAuthority: boolean;
   /** Internal hosted-plan marker: tables and foreign keys of the phase -105 exact `ensureCreated` admission on PostgreSQL. */
   readonly __bazisSchemaAdmission?: {
+    readonly owner: string;
     readonly unit: readonly string[];
     readonly tables: readonly string[];
     readonly foreignKeys: readonly { readonly source: string; readonly target: string }[];
   };
+  /** Internal hosted-plan marker: the context and its startup schema mode, for readable plan errors. */
+  readonly __bazisSchemaOwner: { readonly context: string; readonly mode: string };
+  /** `ensureCreated` owns the versioned migrations of this context (run or baselined before the check). */
+  private readonly withMigrations: boolean;
   private connectionClosed = false;
   private closePromise?: Promise<void>;
 
@@ -42,13 +47,18 @@ export class OrmLifecycle implements HostedService {
      * must not close it at shutdown, or the shared pool would be closed twice.
      */
     private readonly ownsConnection: boolean = true,
+    contextName = "DbContext",
   ) {
+    const modes = [ensureCreated && "ensureCreated", migrateOnStart && "migrateOnStart", runMigrationsOnStart && migrations.length > 0 && "migrations"].filter(Boolean);
+    this.withMigrations = ensureCreated && runMigrationsOnStart && migrations.length > 0;
+    this.__bazisSchemaOwner = Object.freeze({ context: contextName, mode: modes.join(" + ") || "none" });
     this.phase = ensureCreated && options.provider.name === "postgres" ? -105 : -100;
     this.__bazisLegacySchemaAuthority = this.phase === -100 && (ensureCreated || migrateOnStart || (runMigrationsOnStart && migrations.length > 0));
     if (this.phase === -105) {
       const expected = compileExpectedSchema(options.model);
       const tables = Object.freeze(expected.tables.map((table) => `${table.schema}.${table.table}`));
       this.__bazisSchemaAdmission = Object.freeze({
+        owner: contextName,
         unit: tables,
         tables,
         foreignKeys: Object.freeze(expected.tables.flatMap((table) =>
@@ -65,7 +75,17 @@ export class OrmLifecycle implements HostedService {
     const database = new DatabaseFacade(this.options.provider, this.options.model);
     try {
       if (this.ensureCreated) {
-        const result = await database.ensureCreated();
+        const result: Partial<EnsureCreatedWithMigrationsResult> & Pick<EnsureCreatedWithMigrationsResult, "warnings"> = this.withMigrations ? await database.ensureCreatedWithMigrations(this.migrations) : await database.ensureCreated();
+        // Logged in execution order: migrations, schema changes, then the baseline record.
+        if (result.migrated && result.migrated.length > 0) {
+          console.info(`[orm:migrations] applied: ${result.migrated.join(", ")}`);
+        }
+        if (result.applied && result.applied.length > 0) {
+          console.info(`[orm:schema] applied ${result.applied.length} operation(s): ${result.applied.join(", ")}`);
+        }
+        if (result.baselined && result.baselined.length > 0) {
+          console.info(`[orm:migrations] baseline: the schema was created from the model, recorded as applied without running: ${result.baselined.join(", ")}`);
+        }
         for (const warning of result.warnings) {
           console.warn(`[orm:schema] ${warning}`);
         }
@@ -79,7 +99,7 @@ export class OrmLifecycle implements HostedService {
           console.warn(`[orm:migrate] ${warning}`);
         }
       }
-      if (this.runMigrationsOnStart && this.migrations.length > 0) {
+      if (this.runMigrationsOnStart && this.migrations.length > 0 && !this.withMigrations) {
         const result = await database.migrateVersioned(this.migrations);
         if (result.applied.length > 0) {
           console.info(`[orm:migrations] applied: ${result.applied.join(", ")}`);

package/core/orm/buildOrmProviders.ts

@@ -39,6 +39,7 @@ function createOrmLifecycle<TContext extends DbContext>(
     config.migrations ?? [],
     config.runMigrationsOnStart === true,
     ownsConnection,
+    config.context.name,
   );
 }
 

package/core/orm/ormModule.ts

@@ -121,7 +121,7 @@ export function ormModule<TContext extends DbContext>(config: OrmModuleConfig<TC
     attachOwnedStoreRegistration(module, buildConfig.context, buildConfig.entities ?? [], config.ownedStore);
     return module;
   }
-  if (config.ensureCreated && (config.migrateOnStart || config.runMigrationsOnStart || (config.migrations?.length ?? 0) > 0)) throw new OrmError("ensureCreated is mutually exclusive with ORM migration startup options.");
+  if (config.ensureCreated && config.migrateOnStart) throw new OrmError("ensureCreated and migrateOnStart are mutually exclusive: ensureCreated already adds the safe changes. Put other changes into migrations with runMigrationsOnStart: true.");
   if (config.ensureCreated && config.provider?.name === "postgres" && config.context) throw new OrmError("PostgreSQL ensureCreated requires the shared DATABASE_PROVIDER from @Infra.");
   // "Connection" mode: a provider only, no context.
   if (!config.context) {

package/library/orm/DatabaseFacade.ts

@@ -5,6 +5,15 @@ import { Migrator, type MigrationResult } from "./Schema/Migrator";
 import { MigrationRunner, type Migration, type VersionedMigrationResult } from "./Schema/MigrationRunner";
 import { SchemaDiffer } from "./Schema/SchemaDiffer";
 import { SchemaAdmissionEngine, type EnsureCreatedResult } from "./Schema/SchemaAdmission";
+import { entityStorageKey } from "./Schema/tableKey";
+
+/** Result of `ensureCreated` together with versioned migrations. */
+export interface EnsureCreatedWithMigrationsResult extends EnsureCreatedResult {
+  /** Migrations run before the schema check. */
+  readonly migrated: readonly string[];
+  /** Migrations recorded as applied without running, because the schema was created from the model. */
+  readonly baselined: readonly string[];
+}
 import { SchemaAdmissionError } from "./errors";
 import { physicalColumnTypes } from "./Schema/physicalColumnTypes";
 import { bindResolvedForeignKey } from "./Providers/resolvedForeignKey";
@@ -47,6 +56,32 @@ export class DatabaseFacade {
     return { warnings: [] };
   }
 
+  /**
+   * `ensureCreated` with versioned migrations, under the migration lock so that
+   * starting instances do not race:
+   *
+   * - none of the context tables exist yet: `ensureCreated` creates the current
+   *   model and the migrations are recorded as applied without running (a
+   *   baseline: the model already contains their result, so a seed `INSERT` in
+   *   a migration is skipped here too);
+   * - otherwise pending migrations run first (`ALTER`, renames, data moves),
+   *   then `ensureCreated` adds what is still missing and verifies the result.
+   */
+  async ensureCreatedWithMigrations(migrations: readonly Migration[]): Promise<EnsureCreatedWithMigrationsResult> {
+    const work = async (): Promise<EnsureCreatedWithMigrationsResult> => {
+      const runner = new MigrationRunner(this.provider, migrations);
+      const existing = await this.provider.introspect();
+      const fresh = this.models.entities.every((model) => !existing.tables.has(entityStorageKey(model)) && !existing.tables.has(model.tableName));
+      if (fresh) {
+        const created = await this.ensureCreated();
+        return { ...created, migrated: [], baselined: await runner.baseline() };
+      }
+      const { applied } = await runner.migrate();
+      return { ...(await this.ensureCreated()), migrated: applied, baselined: [] };
+    };
+    return this.provider.withMigrationLock ? this.provider.withMigrationLock(work) : work();
+  }
+
   /**
    * Additive auto-migration of the schema for all context entities (enabled in
    * the module: `ormBazis: { migrateOnStart: true }`): introspects the database,
@@ -72,7 +107,7 @@ export class DatabaseFacade {
     const types = this.provider.dialect.name === "postgres" ? physicalColumnTypes(this.models.entities) : undefined;
     const foreignKeys = new Map(targets.map((model) => [model, this.foreignKeysFor(model, types)]));
     const schema = await this.provider.introspect();
-    const { operations, warnings } = new SchemaDiffer().diff(targets, schema);
+    const { operations, warnings } = new SchemaDiffer(types).diff(targets, schema);
     const migrator = new Migrator(this.provider, (model) => foreignKeys.get(model)!);
     const applied = await migrator.apply(operations);
     return { applied: applied.length, operations: applied, warnings };

package/library/orm/Metadata/ModelBuilder.ts

@@ -54,7 +54,7 @@ export class ModelBuilder {
       }
       if (rawProp.index) {
         indexes.push({
-          name: rawProp.index.name ?? `ix_${defaultTableName(ctor.name).toLowerCase()}_${property.columnName}`,
+          name: rawProp.index.name ?? `ix_${(raw.table ?? defaultTableName(ctor.name)).toLowerCase()}_${property.columnName}`,
           columns: [property.columnName],
           unique: rawProp.index.unique,
         });

package/library/orm/Schema/ExpectedSchema.ts

@@ -2,7 +2,8 @@ import type { EntityModel } from "../Metadata/types";
 import type { OrmModel } from "../Metadata/OrmModel";
 import type { CanonicalDefault, GenerationStrategy } from "./introspection";
 import { projectCheckAstIdentifiers } from "./CheckExpression";
-import { physicalColumnTypes } from "./physicalColumnTypes";
+import { crossUnitForeignKey, physicalColumnTypes } from "./physicalColumnTypes";
+import { SchemaAdmissionError } from "../errors";
 import { physicalTableIdentity } from "./tableKey";
 
 export interface ExpectedColumn { readonly property: string; readonly column: string; readonly physicalType: string; readonly nullable: boolean; readonly default: CanonicalDefault; readonly generation: GenerationStrategy }
@@ -14,18 +15,19 @@ const schemaOf = (model: EntityModel) => physicalTableIdentity(model).schema?.tr
 /** Pure expected physical contract compiled solely from the explicit entity unit. */
 export function compileExpectedSchema(models: OrmModel): OrmExpectedSchema {
   const byCtor = new Map(models.entities.map((model) => [model.ctor, model]));
-  const identities = new Set<string>();
+  const identities = new Map<string, string>();
   const types = physicalColumnTypes(models.entities);
   const tables = models.entities.map((model) => compileTable(model, byCtor, identities, types));
   return { tables: Object.freeze(tables.sort((a, b) => Buffer.compare(Buffer.from(`${a.schema}\0${a.table}`, "utf8"), Buffer.from(`${b.schema}\0${b.table}`, "utf8")))) };
 }
 
-function compileTable(model: EntityModel, byCtor: ReadonlyMap<EntityModel["ctor"], EntityModel>, identities: Set<string>, types: ReturnType<typeof physicalColumnTypes>): ExpectedTable {
+function compileTable(model: EntityModel, byCtor: ReadonlyMap<EntityModel["ctor"], EntityModel>, identities: Map<string, string>, types: ReturnType<typeof physicalColumnTypes>): ExpectedTable {
   const schema = schemaOf(model);
   const table = physicalTableIdentity(model).table;
   const identity = `${schema}\0${table}`;
-  if (identities.has(identity)) throw new Error("ORM_SCHEMA_OWNERSHIP_CONFLICT");
-  identities.add(identity);
+  const other = identities.get(identity);
+  if (other !== undefined) throw new SchemaAdmissionError("ORM_SCHEMA_OWNERSHIP_CONFLICT", `Entities "${other}" and "${model.name}" both map table "${schema}"."${table}"; one table belongs to one entity.`);
+  identities.set(identity, model.name);
   const columns = model.properties.map((property) => ({
     property: property.propertyName,
     column: property.columnName,
@@ -36,7 +38,7 @@ function compileTable(model: EntityModel, byCtor: ReadonlyMap<EntityModel["ctor"
   }));
   const foreignKeys = model.foreignKeys.map((foreignKey) => {
     const target = byCtor.get(foreignKey.target());
-    if (!target) throw new Error("ORM_SCHEMA_CROSS_UNIT_FOREIGN_KEY");
+    if (!target) throw crossUnitForeignKey(model, foreignKey.properties, foreignKey.target());
     return { name: foreignKey.name ?? `fk_${table}_${foreignKey.properties.join("_")}`, columns: foreignKey.properties.map((name) => model.propertyByName(name)!.columnName), target: { schema: schemaOf(target), table: physicalTableIdentity(target).table }, targetColumns: target.key.map((property) => property.columnName), onDelete: foreignKey.onDelete, onUpdate: foreignKey.onUpdate };
   });
   return Object.freeze({ schema, table, columns: Object.freeze(columns), primaryKey: Object.freeze({ name: model.keyName ?? `pk_${table}`, columns: Object.freeze(model.key.map((property) => property.columnName)) }), indexes: Object.freeze(model.indexes.map((index) => Object.freeze({ ...index, columns: Object.freeze([...index.columns]), method: "btree" as const }))), foreignKeys: Object.freeze(foreignKeys), checks: Object.freeze(model.checks.map((check) => Object.freeze({ name: check.name, expression: projectCheckAstIdentifiers(check.expression, (name) => model.propertyByName(name)!.columnName) }))) });

package/library/orm/Schema/MigrationRunner.ts

@@ -1,4 +1,6 @@
 import type { DatabaseProvider, DbExecutor, Row, SqlParam } from "../Providers/types";
+import { OrmError } from "../errors";
+import { isUnknownTransactionOutcome } from "../Providers/transactionOutcome";
 
 /** Execution context of a versioned migration. */
 export interface MigrationContext {
@@ -53,12 +55,33 @@ export class MigrationRunner {
           `INSERT INTO ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")}, ${this.quote("AppliedAt")}) VALUES (${this.param(0)}, ${this.param(1)})`,
           [migration.id, new Date().toISOString()],
         );
-      });
+      }).catch((error: unknown) => { throw migrationFailed(`Migration "${migration.id}"`, error); });
       applied.push(migration.id);
     }
     return { applied, rolledBack: [] };
   }
 
+  /**
+   * Records pending migrations as applied without running them. Used when the
+   * schema was just created from the current model, which already contains
+   * their result.
+   */
+  async baseline(): Promise<readonly string[]> {
+    return this.withMigrationLock(async () => {
+      await this.ensureHistory();
+      const appliedSet = await this.loadApplied();
+      const recorded: string[] = [];
+      for (const migration of this.migrations.filter((item) => !appliedSet.has(item.id))) {
+        await this.provider.execute(
+          `INSERT INTO ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")}, ${this.quote("AppliedAt")}) VALUES (${this.param(0)}, ${this.param(1)})`,
+          [migration.id, new Date().toISOString()],
+        );
+        recorded.push(migration.id);
+      }
+      return recorded;
+    });
+  }
+
   /** Rolls back the last `steps` migrations (requires `down`). */
   async rollback(steps = 1): Promise<VersionedMigrationResult> {
     if (!Number.isSafeInteger(steps) || steps < 0) {
@@ -86,7 +109,7 @@ export class MigrationRunner {
         await tx.execute(`DELETE FROM ${this.quote(HISTORY_TABLE)} WHERE ${this.quote("MigrationId")} = ${this.param(0)}`, [
           id,
         ]);
-      });
+      }).catch((error: unknown) => { throw migrationFailed(`Rollback of migration "${id}"`, error); });
       rolledBack.push(id);
     }
     return { applied: [], rolledBack };
@@ -144,3 +167,11 @@ export class MigrationRunner {
     });
   }
 }
+
+/** Names the failed migration; its transaction was rolled back, earlier ones stay applied. */
+function migrationFailed(subject: string, error: unknown): unknown {
+  // An unknown COMMIT outcome must not be reported as a rollback.
+  if (isUnknownTransactionOutcome(error)) return error;
+  const reason = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  return new OrmError(`${subject} failed and was rolled back: ${reason}`, { cause: error });
+}

package/library/orm/Schema/SchemaAdmission.ts

@@ -3,7 +3,8 @@ import { SchemaAdmissionError, SchemaMigrationRequiredError, SchemaVerificationE
 import type { OrmModel } from "../Metadata/OrmModel";
 import { compileExpectedSchema, type OrmExpectedSchema } from "./ExpectedSchema";
 import { ExactSchemaVerifier, type SchemaVerificationResult } from "./ExactSchemaVerifier";
-import { classifySafeAdditive, renderSafeAdditivePostgres } from "./SafeAdditiveSchema";
+import { classifySafeAdditive, renderSafeAdditivePostgres, type SafeAdditiveSchemaOperation } from "./SafeAdditiveSchema";
+import type { IntrospectedSchema } from "./introspection";
 
 /** PostgreSQL-private trace boundary; deliberately absent from public capability types. */
 type TraceableSchemaAdmissionScope = SchemaAdmissionScope & {
@@ -13,6 +14,8 @@ type TraceableSchemaAdmissionScope = SchemaAdmissionScope & {
 /** Result of `ensureCreated`: tolerated differences the application should know about. */
 export interface EnsureCreatedResult {
   readonly warnings: readonly string[];
+  /** Additive changes made by this call, for example `add column products.sku`. */
+  readonly applied?: readonly string[];
 }
 
 /** PostgreSQL-only create-missing-whole-tables and exact admission. */
@@ -22,7 +25,8 @@ export class SchemaAdmissionEngine {
     let expected: OrmExpectedSchema;
     try {
       expected = compileExpectedSchema(this.models);
-    } catch {
+    } catch (error) {
+      if (error instanceof SchemaAdmissionError) throw error;
       throw new SchemaAdmissionError("ORM_SCHEMA_MODEL_INVALID", "The declared ORM model cannot be admitted.");
     }
     const capability = this.provider.schemaAdmissionCapability;
@@ -30,23 +34,24 @@ export class SchemaAdmissionEngine {
     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.");
     }
-    let warnings: readonly string[] = [];
+    let result: EnsureCreatedResult = { warnings: [], applied: [] };
     try {
-      await capability.withSchemaAdmission([...new Set(expected.tables.map((table) => table.schema))], async (scope) => { warnings = await this.admit(scope, expected); });
+      await capability.withSchemaAdmission([...new Set(expected.tables.map((table) => table.schema))], async (scope) => { result = await 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.");
     }
-    return { warnings };
+    return result;
   }
-  private async admit(scope: SchemaAdmissionScope, expected: OrmExpectedSchema): Promise<readonly string[]> {
-    const before = await scope.introspectExpected(expected);
-    const { verification: initial, warnings } = tolerateNameDrift(new ExactSchemaVerifier().verify(expected, before, true));
+  private async admit(scope: SchemaAdmissionScope, expected: OrmExpectedSchema): Promise<EnsureCreatedResult> {
+    const { schema: before, warnings: indexWarnings } = alignIndexNames(expected, await scope.introspectExpected(expected));
+    const { verification: initial, warnings: keyWarnings } = tolerateNameDrift(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);
     }
+    const applied: string[] = [];
     for (const operation of preflight.plan ?? []) {
       try {
         const sql = renderSafeAdditivePostgres(operation);
@@ -54,18 +59,21 @@ export class SchemaAdmissionEngine {
         if (traceable.executeSchemaAdmission) await traceable.executeSchemaAdmission(sql, operation.kind);
         else await scope.execute(sql, []);
       }
-      catch (error) { throw this.mapDdlError(operation.kind, error); }
+      catch (error) { throw this.mapDdlError(operation, error); }
+      applied.push(describeOperation(operation));
     }
-    const { verification: final } = tolerateNameDrift(new ExactSchemaVerifier().verify(expected, await scope.introspectExpected(expected)));
+    const { verification: final } = tolerateNameDrift(new ExactSchemaVerifier().verify(expected, alignIndexNames(expected, await scope.introspectExpected(expected)).schema));
     if (!final.compatible) throw new SchemaVerificationError(final);
-    return warnings;
+    return { warnings: [...keyWarnings, ...indexWarnings], applied };
   }
-  private mapDdlError(kind: string, error: unknown): SchemaAdmissionError {
+  private mapDdlError(operation: SafeAdditiveSchemaOperation, 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.");
+    // The PostgreSQL message names objects, not row values (those stay in its detail field).
+    const reason = `${describeOperation(operation)} failed${sqlState ? ` with PostgreSQL ${sqlState}` : ""}${error instanceof Error && error.message ? `: ${error.message}` : ""}`;
+    if (["23502", "23503", "23505", "23514"].includes(sqlState)) return new SchemaAdmissionError("ORM_SCHEMA_ADDITIVE_DATA_VIOLATION", `Existing PostgreSQL data violates the declared additive schema change: ${reason}. Fix the data, then start again.`);
+    return new SchemaAdmissionError(operation.kind === "createSchema" || operation.kind === "createTable" ? "ORM_SCHEMA_CREATE_FAILED" : "ORM_SCHEMA_ADDITIVE_DDL_FAILED", `PostgreSQL additive schema admission failed: ${reason}.`);
   }
 }
 
@@ -89,3 +97,47 @@ function tolerateNameDrift(verification: SchemaVerificationResult): { readonly v
   });
   return { verification: { compatible: differences.length === 0, differences }, warnings };
 }
+
+const tableName = (schema: string, table: string) => schema === "public" ? table : `${schema}.${table}`;
+
+/** Short log form of an additive operation, in the style of `migrateOnStart`. */
+function describeOperation(operation: SafeAdditiveSchemaOperation): string {
+  switch (operation.kind) {
+    case "createSchema": return `create schema ${operation.schema}`;
+    case "createTable": return `create table ${tableName(operation.table.schema, operation.table.table)}`;
+    case "addColumn": return `add column ${tableName(operation.table.schema, operation.table.table)}.${operation.column.column}`;
+    case "addCheck": return `add check ${operation.check.name} on ${tableName(operation.table.schema, operation.table.table)}`;
+    case "addForeignKey": return `add foreign key ${operation.foreignKey.name} on ${tableName(operation.table.schema, operation.table.table)}`;
+    case "createIndex": return `create ${operation.index.unique ? "unique " : ""}index ${operation.index.name} on ${tableName(operation.table.schema, operation.table.table)} (${operation.index.columns.join(", ")})`;
+  }
+}
+
+/**
+ * An index that differs only by name (same columns, uniqueness and method)
+ * enforces the same thing; before 0.98.20 property-level `@Index` names ignored
+ * `@Entity({ table })`. Like a renamed primary key it is reported, not refused,
+ * and never duplicated.
+ */
+function alignIndexNames(expected: OrmExpectedSchema, actual: IntrospectedSchema): { readonly schema: IntrospectedSchema; readonly warnings: readonly string[] } {
+  const warnings: string[] = [];
+  const tables = new Map(actual.tables);
+  const quote = (name: string) => `"${name.replaceAll('"', '""')}"`;
+  for (const table of expected.tables) {
+    const key = `${table.schema}.${table.table}`;
+    const found = actual.tables.get(key);
+    if (!found) continue;
+    const expectedNames = new Set(table.indexes.map((index) => index.name));
+    let indexes = found.indexes;
+    for (const index of table.indexes) {
+      if (indexes.some((item) => item.name === index.name)) continue;
+      const match = indexes.find((item) => !item.backingConstraint && !item.unsupported && !item.predicate && item.method === "btree" && !expectedNames.has(item.name)
+        && item.unique === index.unique && item.columns.length === index.columns.length && item.columns.every((column, position) => column === index.columns[position]));
+      if (!match) continue;
+      warnings.push(`table ${quote(table.schema)}.${quote(table.table)}: index is named ${quote(match.name)}, the model expects ${quote(index.name)}. `
+        + `It works as is; to align the name run: ALTER INDEX ${quote(table.schema)}.${quote(match.name)} RENAME TO ${quote(index.name)};`);
+      indexes = indexes.map((item) => item === match ? { ...item, name: index.name } : item);
+    }
+    if (indexes !== found.indexes) tables.set(key, { ...found, indexes });
+  }
+  return { schema: { ...actual, tables }, warnings };
+}

package/library/orm/Schema/SchemaDiffer.ts

@@ -1,5 +1,5 @@
 import { entityStorageKey } from "./tableKey";
-import type { EntityModel, IndexModel, PropertyModel } from "../Metadata/types";
+import type { ColumnType, EntityModel, IndexModel, PropertyModel } from "../Metadata/types";
 import type { IntrospectedSchema, IntrospectedTable } from "./introspection";
 
 /**
@@ -23,6 +23,9 @@ export interface SchemaDiff {
  * from introspection; no separate snapshot file is needed.
  */
 export class SchemaDiffer {
+  /** `types` are the physical column types (UUID foreign keys follow their keys); without them types are not compared. */
+  constructor(private readonly types?: ReadonlyMap<PropertyModel, ColumnType | "uuid">) {}
+
   diff(targets: readonly EntityModel[], schema: IntrospectedSchema): SchemaDiff {
     const operations: AdditiveSchemaOperation[] = [];
     const warnings: string[] = [];
@@ -39,7 +42,7 @@ export class SchemaDiffer {
         continue;
       }
       this.diffColumns(model, table, operations, warnings);
-      this.diffIndexes(model, table, operations);
+      this.diffIndexes(model, table, operations, warnings);
     }
 
     return { operations, warnings };
@@ -52,8 +55,21 @@ export class SchemaDiffer {
     warnings: string[],
   ): void {
     for (const property of model.properties) {
-      if (!table.columns.has(property.columnName)) {
+      const column = table.columns.get(property.columnName);
+      if (!column) {
         operations.push({ kind: "addColumn", model, property });
+        continue;
+      }
+      // Changing a type or NULL-ability can lose data or fail on existing rows: report, never apply.
+      const expectedType = this.types?.get(property);
+      if (expectedType !== undefined && column.physicalType !== undefined && column.physicalType !== expectedType) {
+        warnings.push(`table "${model.tableName}": column "${property.columnName}" is ${column.physicalType} in the database but ${expectedType} in the model (left untouched; change it with an explicit migration).`);
+      }
+      if (!property.isKey && property.required && !column.notNull) {
+        warnings.push(`table "${model.tableName}": column "${property.columnName}" allows NULL in the database but is required in the model (left untouched; fill the NULL values and set NOT NULL with an explicit migration).`);
+      }
+      if (!property.isKey && !property.required && column.notNull) {
+        warnings.push(`table "${model.tableName}": column "${property.columnName}" is NOT NULL in the database but nullable in the model (left untouched; drop NOT NULL with an explicit migration).`);
       }
     }
     // Destructive: columns exist in the database but not in the model; never dropped automatically.
@@ -67,12 +83,19 @@ export class SchemaDiffer {
     }
   }
 
-  private diffIndexes(model: EntityModel, table: IntrospectedTable, operations: AdditiveSchemaOperation[]): void {
+  private diffIndexes(model: EntityModel, table: IntrospectedTable, operations: AdditiveSchemaOperation[], warnings: string[]): void {
     const existing = new Set(table.indexes.map((index) => index.name));
+    const declared = new Set(model.indexes.map((index) => index.name));
     for (const index of model.indexes) {
-      if (!existing.has(index.name)) {
-        operations.push({ kind: "createIndex", model, index });
+      if (existing.has(index.name)) continue;
+      // The same index under another name (for example from before 0.98.20) is not duplicated.
+      const renamed = table.indexes.find((item) => !declared.has(item.name) && !item.backingConstraint && !item.predicate && item.unique === index.unique
+        && item.columns.length === index.columns.length && item.columns.every((column, position) => column === index.columns[position]));
+      if (renamed) {
+        warnings.push(`table "${model.tableName}": index "${renamed.name}" matches "${index.name}" from the model except for its name (left untouched; to align it run: ALTER INDEX "${renamed.name}" RENAME TO "${index.name}";).`);
+        continue;
       }
+      operations.push({ kind: "createIndex", model, index });
     }
   }
 }

package/library/orm/Schema/physicalColumnTypes.ts

@@ -1,4 +1,5 @@
 import { isUuidKeyGeneration, type ColumnType, type EntityModel, type PropertyModel } from "../Metadata/types";
+import { SchemaAdmissionError } from "../errors";
 
 /** Resolve the physical FK contract without changing logical converter types.
  * UUID storage follows referenced keys, including PK/FK chains and cycles. */
@@ -10,7 +11,7 @@ export function physicalColumnTypes(models: readonly EntityModel[]): ReadonlyMap
     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 (!target) throw crossUnitForeignKey(model, fk.properties, fk.target());
       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);
@@ -35,3 +36,9 @@ export function physicalColumnTypes(models: readonly EntityModel[]): ReadonlyMap
   }
   return result;
 }
+
+/** A database foreign key cannot leave the context that creates the schema. */
+export function crossUnitForeignKey(model: EntityModel, properties: readonly string[], target: new () => object): SchemaAdmissionError {
+  const columns = properties.join(", ");
+  return new SchemaAdmissionError("ORM_SCHEMA_CROSS_UNIT_FOREIGN_KEY", `Entity "${model.name}" has a foreign key (${columns}) to "${target.name}", which is not an entity of the same DbContext. A database foreign key can only point to an entity of the same context: keep ${columns} as a plain column without @ManyToOne, or map both entities in one context.`);
+}

package/library/orm/errors.ts

@@ -10,7 +10,7 @@ export class OrmError extends Error {
   }
 }
 
-export type SchemaAdmissionErrorCode = "ORM_SCHEMA_PROVIDER_UNSUPPORTED" | "ORM_SCHEMA_LOCK_UNAVAILABLE" | "ORM_SCHEMA_LOCK_KEY_COLLISION" | "ORM_SCHEMA_ATOMICITY_UNAVAILABLE" | "ORM_SCHEMA_MODEL_INVALID" | "ORM_SCHEMA_CATALOG_UNSUPPORTED" | "ORM_SCHEMA_CREATE_FAILED" | "ORM_SCHEMA_ADDITIVE_DATA_VIOLATION" | "ORM_SCHEMA_ADDITIVE_DDL_FAILED" | "ORM_SCHEMA_MIGRATION_REQUIRED" | "ORM_SCHEMA_DRIFT" | "ORM_SCHEMA_OWNERSHIP_CONFLICT" | "ORM_SCHEMA_HOSTED_PHASE_CONFLICT";
+export type SchemaAdmissionErrorCode = "ORM_SCHEMA_PROVIDER_UNSUPPORTED" | "ORM_SCHEMA_LOCK_UNAVAILABLE" | "ORM_SCHEMA_LOCK_KEY_COLLISION" | "ORM_SCHEMA_ATOMICITY_UNAVAILABLE" | "ORM_SCHEMA_MODEL_INVALID" | "ORM_SCHEMA_CATALOG_UNSUPPORTED" | "ORM_SCHEMA_CREATE_FAILED" | "ORM_SCHEMA_ADDITIVE_DATA_VIOLATION" | "ORM_SCHEMA_ADDITIVE_DDL_FAILED" | "ORM_SCHEMA_MIGRATION_REQUIRED" | "ORM_SCHEMA_DRIFT" | "ORM_SCHEMA_OWNERSHIP_CONFLICT" | "ORM_SCHEMA_HOSTED_PHASE_CONFLICT" | "ORM_SCHEMA_CROSS_UNIT_FOREIGN_KEY";
 /** Safe public admission failure; deliberately contains no driver cause or SQL. */
 export class SchemaAdmissionError extends OrmError {
   constructor(readonly code: SchemaAdmissionErrorCode, message: string) { super(message); }
@@ -33,7 +33,7 @@ export class SchemaMigrationRequiredError extends SchemaAdmissionError {
 
 function schemaVerificationMessage(summary: string, verification: SchemaVerificationResult): string {
   return [summary, formatSchemaDifferences(verification),
-    "Check the application version and target database. Align the ORM model and database schema; apply an explicit migration if a database change is intended.",
+    "Check the application version and target database. Align the ORM model and database schema; apply an explicit migration if a database change is intended (with ensureCreated: add it to the module's migrations with runMigrationsOnStart: true).",
   ].filter(Boolean).join("\n");
 }
 

package/library/orm/index.ts

@@ -132,6 +132,7 @@ export type {
 } from "./Schema/introspection";
 export type { SchemaDifferenceCode, SafeSchemaDescriptor, SchemaDifference, SchemaVerificationResult } from "./Schema/ExactSchemaVerifier";
 export type { EnsureCreatedResult } from "./Schema/SchemaAdmission";
+export type { EnsureCreatedWithMigrationsResult } from "./DatabaseFacade";
 export { SchemaAdmissionError, SchemaMigrationRequiredError, SchemaVerificationError } from "./errors";
 export type { SchemaAdmissionErrorCode } from "./errors";
 export { compileCheck, renderCheck } from "./Schema/CheckExpression";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.19",
+  "version": "0.98.21",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",