bazis 0.98.29 → 0.98.30

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.29" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.30" }, 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/Kernel.ts

@@ -28,6 +28,8 @@ export interface KernelRuntimeOptions {
   readonly signals: readonly NodeJS.Signals[];
   readonly unhandledErrorPolicy: UnhandledErrorPolicy;
   readonly startupReport: boolean;
+  /** Start the infrastructure and the schema only, then stop (BAZIS_SCHEMA_ONLY). */
+  readonly schemaOnly?: boolean;
 }
 
 interface StopRequest {
@@ -101,9 +103,19 @@ export class Kernel {
       // Async singletons first: hosted services and controllers take them
       // through constructors, which resolve synchronously.
       await awaitAbortable(this.container.initializeAsyncSingletons(), abortController.signal);
-      await this.coordinator.start(abortController.signal, this.options.shutdownTimeoutMs);
+      await this.coordinator.start(abortController.signal, this.options.shutdownTimeoutMs, this.options.schemaOnly === true);
       coordinatorStarted = true;
       this.startupMs = performance.now() - this.timings.buildStartedAt;
+      if (this.options.schemaOnly === true) {
+        // The application itself never started: no lifetime callbacks, no
+        // STARTED event, no report. run() stops right away with exit code 0.
+        this.container.tryResolve(LOGGER)?.info("schema only: infrastructure and schema are ready, stopping (BAZIS_SCHEMA_ONLY)", {
+          hostedServices: this.coordinator.startedHostedCount,
+          startupMs: Number(this.startupMs.toFixed(1)),
+        });
+        this.state = "started";
+        return;
+      }
       await this.lifetime.notifyStarted(abortController.signal);
       await this.container.resolve(EventBus).publish(
         APPLICATION_STARTED,
@@ -222,16 +234,21 @@ export class Kernel {
 
   private async runShutdownSequence(request: StopRequest): Promise<void> {
     const errors: unknown[] = [];
+    // A schema-only start never announced the application, so it does not
+    // announce its stop either.
+    const announced = this.options.schemaOnly !== true;
     try {
-      await this.lifetime.notifyStopping();
+      if (announced) await this.lifetime.notifyStopping();
     } catch (error) {
       errors.push(error);
     }
     try {
-      await this.container.resolve(EventBus).publish(APPLICATION_STOPPING, {
-        ...(request.signal === undefined ? {} : { signal: request.signal }),
-        exitCode: request.exitCode,
-      });
+      if (announced) {
+        await this.container.resolve(EventBus).publish(APPLICATION_STOPPING, {
+          ...(request.signal === undefined ? {} : { signal: request.signal }),
+          exitCode: request.exitCode,
+        });
+      }
     } catch (error) {
       errors.push(error);
     }
@@ -249,7 +266,7 @@ export class Kernel {
     }
 
     try {
-      await this.lifetime.notifyStopped();
+      if (announced) await this.lifetime.notifyStopped();
     } catch (error) {
       errors.push(error);
     }
@@ -287,6 +304,10 @@ export class Kernel {
         return request.exitCode;
       }
 
+      if (this.options.schemaOnly === true) {
+        // The schema is in place: nothing to serve, stop as a finished job.
+        this.requestStop(this.stopRequested ?? { exitCode: 0 });
+      }
       const request = await new Promise<StopRequest>((resolve) => {
         // lifetime.stop() or a process signal may have fired during start().
         if (this.stopRequested) {

package/core/kernel/KernelBuilder.ts

@@ -6,6 +6,7 @@ import { ConfigRegistry } from "./config/ConfigRegistry";
 import { argsSource, envSource } from "./config/sources";
 import { Environment } from "./Environment";
 import { EventBus } from "./events/EventBus";
+import { KernelError } from "./errors";
 import { HealthService } from "./health/HealthService";
 import { Kernel, type KernelTimings } from "./Kernel";
 import { ConsoleLogger } from "./logging/ConsoleLogger";
@@ -46,6 +47,7 @@ export class KernelBuilder {
   private validateOnBuild = true;
   private overrides: readonly ProviderDefinition[] = [];
   private startupReport?: boolean;
+  private schemaOnly?: boolean;
   private logger?: Logger;
 
   public constructor(private readonly rootModule: RootModuleInput) {}
@@ -65,6 +67,7 @@ export class KernelBuilder {
     if (options.unhandledErrorPolicy !== undefined) this.unhandledErrorPolicy = options.unhandledErrorPolicy;
     if (options.validateOnBuild !== undefined) this.validateOnBuild = options.validateOnBuild;
     if (options.startupReport !== undefined) this.startupReport = options.startupReport;
+    if (options.schemaOnly !== undefined) this.schemaOnly = options.schemaOnly;
     return this;
   }
 
@@ -177,6 +180,17 @@ export class KernelBuilder {
       signals: this.signals,
       unhandledErrorPolicy: this.unhandledErrorPolicy,
       startupReport: this.startupReport ?? !environment.isProduction,
+      schemaOnly: this.schemaOnly ?? schemaOnlyFromProcess(),
     });
   }
 }
+
+/** BAZIS_SCHEMA_ONLY: `1`/`true` or `0`/`false`/unset; anything else is a mistake worth stopping for. */
+function schemaOnlyFromProcess(): boolean {
+  const raw = process.env.BAZIS_SCHEMA_ONLY;
+  if (raw === undefined || raw === "") return false;
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true") return true;
+  if (normalized === "0" || normalized === "false") return false;
+  throw new KernelError(`BAZIS_SCHEMA_ONLY must be 1, true, 0 or false, got ${JSON.stringify(raw.slice(0, 40))}.`);
+}

package/core/kernel/LifecycleCoordinator.ts

@@ -55,16 +55,21 @@ export class LifecycleCoordinator {
     return this.rollbackStartedAt === undefined ? 0 : performance.now() - this.rollbackStartedAt;
   }
 
-  public async start(signal?: AbortSignal, rollbackTimeoutMs = 0): Promise<void> {
+  /**
+   * `infrastructureOnly` starts only hosted services with a negative phase
+   * (connections and the database schema) and no lifecycle hooks.
+   */
+  public async start(signal?: AbortSignal, rollbackTimeoutMs = 0, infrastructureOnly = false): Promise<void> {
     signal?.throwIfAborted();
     validateOptionsOnStart(this.resolver);
-    const hosted = resolveHostedServices(this.resolver);
+    const resolved = resolveHostedServices(this.resolver);
+    const hosted = infrastructureOnly ? resolved.filter((service) => (service.phase ?? 0) < 0) : resolved;
     // Background failures go to the application logger, like HTTP errors.
     const logger = this.resolver.tryResolve?.(LOGGER);
     if (logger) for (const service of hosted) service.useDiagnostics?.(logger);
     const validation = validateHostedServicePlan(hosted, signal);
     if (validation) await awaitAbortable(validation, signal);
-    this.hooks = this.resolver.resolveAll(LIFECYCLE_HOOK);
+    this.hooks = infrastructureOnly ? [] : this.resolver.resolveAll(LIFECYCLE_HOOK);
 
     try {
       for (let index = 0; index < this.hooks.length; index += 1) {

package/core/kernel/types/KernelOptions.ts

@@ -20,4 +20,12 @@ export interface KernelOptions {
   readonly validateOnBuild?: boolean;
   /** Startup report in the console. Default: only outside production. */
   readonly startupReport?: boolean;
+  /**
+   * Start only the infrastructure and the database schema (hosted services with
+   * a negative phase: connections, migrations, `ensureCreated`), then stop with
+   * exit code 0. HTTP, background services and lifecycle hooks do not run.
+   * For a deployment step with the schema owner's credentials.
+   * Default: the BAZIS_SCHEMA_ONLY variable (`1`/`true`), otherwise false.
+   */
+  readonly schemaOnly?: boolean;
 }

package/library/orm/Schema/MigrationRunner.ts

@@ -130,10 +130,24 @@ export class MigrationRunner {
   }
 
   private async ensureHistory(): Promise<void> {
+    // CREATE TABLE IF NOT EXISTS needs the CREATE privilege on the schema even
+    // when the table exists, so an application user with data rights only
+    // could never start. Create the table only when it is missing.
+    const [found] = await this.provider.query(`SELECT to_regclass(${this.param(0)}) IS NOT NULL AS present`, [this.quote(HISTORY_TABLE)]);
+    if (found?.present === true) {
+      return;
+    }
     await this.provider.execute(
       `CREATE TABLE IF NOT EXISTS ${this.quote(HISTORY_TABLE)} (${this.quote("MigrationId")} TEXT PRIMARY KEY, ${this.quote("AppliedAt")} TEXT NOT NULL)`,
       [],
-    );
+    ).catch((error: unknown) => {
+      if (sqlState(error) !== "42501") throw error;
+      throw new OrmError(
+        `The migration history table "${HISTORY_TABLE}" does not exist and this database user may not create it (PostgreSQL 42501). ` +
+          "Run the first start with the schema owner's credentials (BAZIS_SCHEMA_ONLY=1 applies the schema and exits), or grant CREATE on the schema.",
+        { cause: error },
+      );
+    });
   }
 
   private async loadApplied(): Promise<Set<string>> {
@@ -168,6 +182,11 @@ export class MigrationRunner {
   }
 }
 
+function sqlState(error: unknown): string | undefined {
+  const code = (error as { errno?: unknown; code?: unknown } | null)?.errno ?? (error as { code?: unknown } | null)?.code;
+  return typeof code === "string" ? code : undefined;
+}
+
 /** 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.

package/library/orm/Schema/SchemaAdmission.ts

@@ -73,7 +73,12 @@ export class SchemaAdmissionEngine {
     // 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}.`);
+    // 42501: an application user with data rights only. The schema change is
+    // right; it has to be applied by a user that owns the tables.
+    const hint = sqlState === "42501"
+      ? " This database user may not change the schema: apply the change with the schema owner's credentials (BAZIS_SCHEMA_ONLY=1 applies the schema and exits), or grant the rights."
+      : "";
+    return new SchemaAdmissionError(operation.kind === "createSchema" || operation.kind === "createTable" ? "ORM_SCHEMA_CREATE_FAILED" : "ORM_SCHEMA_ADDITIVE_DDL_FAILED", `PostgreSQL additive schema admission failed: ${reason}.${hint}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.29",
+  "version": "0.98.30",
   "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",