bazis 0.98.11 → 0.98.13

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.11" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.13" }, 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/config/defineConfig.ts

@@ -154,18 +154,22 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
     const values = new Map<string, ConfigValueType>();
     const inspection: ConfigInspection[] = [];
     const issues: string[] = [];
+    // A wrong value names what came and where to change it: the variable that
+    // supplied it, or the variables that can override the value from the code.
+    const got = (raw: unknown) => raw === undefined ? "" : `, got ${JSON.stringify(String(raw)).slice(0, 80)}`;
+    const source = (key: string, selected: { readonly name: string } | undefined) => ` (${selected ? selected.name : names.get(key)!.join(", ")})`;
     for (const key of keys) {
       const base = schema.default[key]!;
       const override = schema[environment]?.[key];
       const cell = override ?? base;
       const type = isSecret(base) ? "secret" : isEnum(base) ? typeof base.default : typeof base;
-      const candidates: { raw: string; source: string; priority: number }[] = [];
+      const candidates: { raw: string; source: string; priority: number; name: string }[] = [];
       for (const name of names.get(key)!) {
         const sourceKey = name.slice(ENV_PREFIX.length).toLowerCase().replaceAll("__", ".");
         const raw = configuration.get(sourceKey);
         if (raw === undefined) continue;
         const origin = configuration.origin(sourceKey);
-        candidates.push({ raw, ...origin });
+        candidates.push({ raw, ...origin, name });
       }
       const priority = Math.max(...candidates.map(candidate => candidate.priority));
       const winners = candidates.filter(candidate => candidate.priority === priority);
@@ -178,17 +182,17 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
         else value = new Secret(raw);
       } else if (type === "number") {
         const parsed = Number(raw);
-        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issues.push(`${fullKey(key)} — expected a finite number`);
+        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issues.push(`${fullKey(key)} — expected a finite number${got(raw)}${source(key, selected)}`);
         else value = parsed;
       } else if (type === "boolean") {
         const normalized = String(raw).toLowerCase();
         if (normalized === "true" || normalized === "1") value = true;
         else if (normalized === "false" || normalized === "0") value = false;
-        else issues.push(`${fullKey(key)} — expected a boolean`);
+        else issues.push(`${fullKey(key)} — expected a boolean (true, false, 1, 0)${got(raw)}${source(key, selected)}`);
       } else if (typeof raw === "string") value = raw;
       else issues.push(`${fullKey(key)} — expected a string`);
       if (value === undefined) continue;
-      if (isEnum(base) && !base.values.includes(value as string | number)) issues.push(`${fullKey(key)} — value is not one of the declared enum values`);
+      if (isEnum(base) && !base.values.includes(value as string | number)) issues.push(`${fullKey(key)} — ${JSON.stringify(value)} is not allowed, use one of: ${base.values.join(", ")}${source(key, selected)}`);
       try {
         const issue = validators[key]?.(value);
         if (issue) issues.push(`${fullKey(key)} — ${issue}`);

package/core/orm/OrmLifecycle.ts

@@ -65,7 +65,10 @@ export class OrmLifecycle implements HostedService {
     const database = new DatabaseFacade(this.options.provider, this.options.model);
     try {
       if (this.ensureCreated) {
-        await database.ensureCreated();
+        const result = await database.ensureCreated();
+        for (const warning of result.warnings) {
+          console.warn(`[orm:schema] ${warning}`);
+        }
       }
       if (this.migrateOnStart) {
         const result = await database.migrate();

package/core/orm/databaseConnector.ts

@@ -1,4 +1,4 @@
-import { InfraError, reader, requireValue, postgresConnectionOptions, type InfraConnector, type PostgresConfigShape } from "../infra";
+import { errorMessage, InfraError, reader, requireValue, postgresConnectionOptions, type InfraConnector, type PostgresConfigShape } from "../infra";
 import type { AppConfig, ConfigRegistry } from "../kernel";
 import { postgres, type DatabaseProvider, type PostgresServerTimeouts } from "../../library/orm";
 import { DATABASE_PROVIDER } from "./DATABASE_PROVIDER";
@@ -86,16 +86,26 @@ export function ormBazisConnect<T extends PostgresOrmConfigShape>(config: AppCon
 export function ormBazisConnect(
   config: AppConfig<PostgresOrmConfigShape>,
 ): InfraConnector<DatabaseProvider> {
+  // Where the connection goes, for the startup error; never the password.
+  let target = "PostgreSQL";
   return {
     token: DATABASE_PROVIDER,
     config,
     phase: DATABASE_PHASE,
     create(configs) {
+      const c = reader(config, configs);
+      target = `PostgreSQL at ${String(c.get("host"))}:${String(c.get("port"))} (database "${String(c.get("database"))}", user "${String(c.get("username"))}")`;
       return buildPostgresProvider(config, configs);
     },
     async connect(provider, signal) {
-      if (!(await provider.ping(signal))) {
-        throw new InfraError('Infra connector "database": postgres is not reachable.');
+      if (provider.probe === undefined) {
+        if (!(await provider.ping(signal))) throw new InfraError(`Infra connector "database": cannot connect to ${target}.`);
+        return;
+      }
+      try {
+        await provider.probe(signal);
+      } catch (error) {
+        throw new InfraError(`Infra connector "database": cannot connect to ${target}: ${connectionFailure(error)}`);
       }
     },
     async dispose(provider) {
@@ -106,3 +116,12 @@ export function ormBazisConnect(
     },
   };
 }
+
+/** The driver's reason with its code: `password authentication failed for user "app" (28P01)`. */
+function connectionFailure(error: unknown): string {
+  const details = error as { errno?: unknown; code?: unknown };
+  const code = typeof details.errno === "string" && details.errno ? details.errno
+    : typeof details.code === "string" && details.code ? details.code : undefined;
+  const message = errorMessage(error);
+  return code === undefined || message.includes(code) ? message : `${message} (${code})`;
+}

package/library/orm/DatabaseFacade.ts

@@ -4,7 +4,7 @@ import type { DatabaseProvider, DbExecutor, ExecuteResult, ForeignKeyConstraint,
 import { Migrator, type MigrationResult } from "./Schema/Migrator";
 import { MigrationRunner, type Migration, type VersionedMigrationResult } from "./Schema/MigrationRunner";
 import { SchemaDiffer } from "./Schema/SchemaDiffer";
-import { SchemaAdmissionEngine } from "./Schema/SchemaAdmission";
+import { SchemaAdmissionEngine, type EnsureCreatedResult } from "./Schema/SchemaAdmission";
 import { SchemaAdmissionError } from "./errors";
 import { physicalColumnTypes } from "./Schema/physicalColumnTypes";
 import { bindResolvedForeignKey } from "./Providers/resolvedForeignKey";
@@ -26,10 +26,9 @@ export class DatabaseFacade {
    * whole tables, then exact-verifies again before commit. Existing tables are
    * never altered or repaired.
    */
-  async ensureCreated(): Promise<void> {
+  async ensureCreated(): Promise<EnsureCreatedResult> {
     if (this.provider.name === "postgres") {
-      await new SchemaAdmissionEngine(this.provider, this.models).ensureCreated();
-      return;
+      return new SchemaAdmissionEngine(this.provider, this.models).ensureCreated();
     }
     // The physical default contract belongs exclusively to exact PostgreSQL
     // admission. Other providers must reject it rather than silently ignore it.
@@ -45,6 +44,7 @@ export class DatabaseFacade {
         await this.provider.execute(indexSql, []);
       }
     }
+    return { warnings: [] };
   }
 
   /**

package/library/orm/Providers/PostgresProvider.ts

@@ -409,13 +409,17 @@ export class PostgresProvider implements DatabaseProvider {
 
   async ping(signal?: AbortSignal): Promise<boolean> {
     try {
-      await withPostgresScopeOptions({ signal }, () => this.pooledOperation((session) => this.runQuery(session, "SELECT 1", [])));
+      await this.probe(signal);
       return true;
     } catch {
       return false;
     }
   }
 
+  async probe(signal?: AbortSignal): Promise<void> {
+    await withPostgresScopeOptions({ signal }, () => this.pooledOperation((session) => this.runQuery(session, "SELECT 1", [])));
+  }
+
   async introspect(): Promise<IntrospectedSchema> {
     const tableRows = await this.query(
       `SELECT table_schema, table_name

package/library/orm/Providers/ormTransactionRuntime.ts

@@ -96,6 +96,7 @@ export function createObservedProvider(provider: DatabaseProvider, observe: Tran
     afterCommit: provider.afterCommit?.bind(provider),
     afterRollback: provider.afterRollback?.bind(provider),
     ping: (signal?: AbortSignal): Promise<boolean> => observe(() => provider.ping(signal)),
+    probe: provider.probe ? (signal?: AbortSignal): Promise<void> => observe(() => provider.probe!(signal)) : undefined,
     introspect: () => observe(() => provider.introspect()),
     schemaAdmissionCapability: schema ? {
       version: schema.version,

package/library/orm/Providers/types.ts

@@ -178,6 +178,11 @@ export interface DatabaseProvider {
   afterRollback?(callback: TransactionCallback): void;
   /** Connection check for the health check. */
   ping(signal?: AbortSignal): Promise<boolean>;
+  /**
+   * Connection check that rejects with the driver's error instead of `false`,
+   * so a startup failure can say why (wrong password, missing database, …).
+   */
+  probe?(signal?: AbortSignal): Promise<void>;
   /** Introspection of the actual database schema (for the auto-migration). */
   introspect(): Promise<IntrospectedSchema>;
   /**

package/library/orm/Saving/ExecutionStrategy.ts

@@ -103,6 +103,7 @@ export function withRetry(provider: DatabaseProvider, options?: ExecutionStrateg
     afterCommit: provider.afterCommit ? (callback) => provider.afterCommit!(callback) : undefined,
     afterRollback: provider.afterRollback ? (callback) => provider.afterRollback!(callback) : undefined,
     ping: (signal) => provider.ping(signal),
+    probe: provider.probe ? (signal) => provider.probe!(signal) : undefined,
     introspect: () => provider.introspect(),
     schemaAdmissionCapability: provider.schemaAdmissionCapability,
     withMigrationLock: provider.withMigrationLock ? (work) => provider.withMigrationLock!(work) : undefined,

package/library/orm/Schema/SchemaAdmission.ts

@@ -2,7 +2,7 @@ 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 { ExactSchemaVerifier, type SchemaVerificationResult } from "./ExactSchemaVerifier";
 import { classifySafeAdditive, renderSafeAdditivePostgres } from "./SafeAdditiveSchema";
 
 /** PostgreSQL-private trace boundary; deliberately absent from public capability types. */
@@ -10,10 +10,15 @@ type TraceableSchemaAdmissionScope = SchemaAdmissionScope & {
   readonly executeSchemaAdmission?: (sql: string, operation: string) => ReturnType<SchemaAdmissionScope["execute"]>;
 };
 
+/** Result of `ensureCreated`: tolerated differences the application should know about. */
+export interface EnsureCreatedResult {
+  readonly warnings: readonly string[];
+}
+
 /** 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> {
+  async ensureCreated(): Promise<EnsureCreatedResult> {
     let expected: OrmExpectedSchema;
     try {
       expected = compileExpectedSchema(this.models);
@@ -25,16 +30,18 @@ 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[] = [];
     try {
-      await capability.withSchemaAdmission([...new Set(expected.tables.map((table) => table.schema))], async (scope) => this.admit(scope, expected));
+      await capability.withSchemaAdmission([...new Set(expected.tables.map((table) => table.schema))], async (scope) => { warnings = 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 };
   }
-  private async admit(scope: SchemaAdmissionScope, expected: OrmExpectedSchema): Promise<void> {
+  private async admit(scope: SchemaAdmissionScope, expected: OrmExpectedSchema): Promise<readonly string[]> {
     const before = await scope.introspectExpected(expected);
-    const initial = new ExactSchemaVerifier().verify(expected, before, true);
+    const { verification: initial, warnings } = 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.");
@@ -49,8 +56,9 @@ export class SchemaAdmissionEngine {
       }
       catch (error) { throw this.mapDdlError(operation.kind, error); }
     }
-    const final = new ExactSchemaVerifier().verify(expected, await scope.introspectExpected(expected));
+    const { verification: final } = tolerateNameDrift(new ExactSchemaVerifier().verify(expected, await scope.introspectExpected(expected)));
     if (!final.compatible) throw new SchemaVerificationError(final);
+    return warnings;
   }
   private mapDdlError(kind: string, error: unknown): SchemaAdmissionError {
     const sqlState = typeof error === "object" && error !== null
@@ -60,3 +68,24 @@ export class SchemaAdmissionEngine {
     return new SchemaAdmissionError(kind === "createSchema" || kind === "createTable" ? "ORM_SCHEMA_CREATE_FAILED" : "ORM_SCHEMA_ADDITIVE_DDL_FAILED", "PostgreSQL additive schema admission failed.");
   }
 }
+
+/**
+ * A primary key that differs only by name (`tasks_pkey` from an older schema vs
+ * the model's `pk_tasks`) enforces the same thing, and queries never reference
+ * the name (`ON CONFLICT` names columns). It is reported, not refused; the same
+ * table passes `migrateOnStart`. Every other difference stays exact.
+ */
+function tolerateNameDrift(verification: SchemaVerificationResult): { readonly verification: SchemaVerificationResult; readonly warnings: readonly string[] } {
+  const tolerated = verification.differences.filter((difference) => difference.code === "primaryKey.name");
+  if (tolerated.length === 0) return { verification, warnings: [] };
+  const differences = verification.differences.filter((difference) => difference.code !== "primaryKey.name");
+  const quote = (name: string) => `"${name.replaceAll('"', '""')}"`;
+  const warnings = tolerated.map((difference) => {
+    const table = `${quote(difference.schema)}.${quote(difference.table)}`;
+    const actual = difference.actual?.value ?? "";
+    const expected = difference.expected?.value ?? difference.objectName ?? "";
+    return `table ${table}: primary key is named ${quote(actual)}, the model expects ${quote(expected)}. `
+      + `It works as is; to align the name run: ALTER TABLE ${table} RENAME CONSTRAINT ${quote(actual)} TO ${quote(expected)};`;
+  });
+  return { verification: { compatible: differences.length === 0, differences }, warnings };
+}

package/library/orm/index.ts

@@ -131,6 +131,7 @@ export type {
   IntrospectedCheck,
 } from "./Schema/introspection";
 export type { SchemaDifferenceCode, SafeSchemaDescriptor, SchemaDifference, SchemaVerificationResult } from "./Schema/ExactSchemaVerifier";
+export type { EnsureCreatedResult } from "./Schema/SchemaAdmission";
 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.11",
+  "version": "0.98.13",
   "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",