bazis 0.111.2 → 0.113.0

package/cli/main.ts

@@ -210,7 +210,10 @@ async function runGenerate(cwd: string, args: ParsedGenerateArgs, codegen: CliRu
   if (result.registered) s.line(`  ${s.strong("↗", PALETTE.export)}  ${s.text(t.module.registered(host ?? "App.module.ts"))}`);
   else s.warning(t.module.notRegistered);
   // What the module needs from the application to run.
-  if (args.generator === "module" && args.profile !== "empty") s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.muted(t.module.needsDb)}`);
+  if (args.generator === "module" && args.profile !== "empty") {
+    s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.muted(t.module.needsDb)}`);
+    s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.muted(t.module.needsTable(`${args.name}.module.ts`))}`);
+  }
   if (args.generator === "module" && args.profile === "full") s.line(`  ${s.strong("◆", PALETTE.service)}  ${s.muted(t.module.needsCache)}`);
   s.line();
   if (result.dryRun) {

package/core/di/errors/configurationError.ts

@@ -0,0 +1,21 @@
+import { DiError } from "./DiError";
+
+const CONFIGURATION_ERROR = Symbol.for("bazis.configurationError");
+
+/**
+ * Marks an error found in the application's declarations — a module, a
+ * connector, a config — as a configuration error: the start prints it as one
+ * `[bazis] configuration error` line instead of a stack. The error keeps its
+ * class; the same error is returned.
+ */
+export function markConfigurationError<T>(error: T): T {
+  if (error instanceof Error && !Object.prototype.hasOwnProperty.call(error, CONFIGURATION_ERROR)) {
+    Object.defineProperty(error, CONFIGURATION_ERROR, { value: true });
+  }
+  return error;
+}
+
+/** A DI error, or an error marked with {@link markConfigurationError}. */
+export function isConfigurationError(error: unknown): error is Error {
+  return error instanceof DiError || (error instanceof Error && (error as unknown as Record<symbol, unknown>)[CONFIGURATION_ERROR] === true);
+}

package/core/di/errors/index.ts

@@ -12,3 +12,4 @@ export { ProviderNotFoundError } from "./ProviderNotFoundError";
 export { ScopeDisposedError } from "./ScopeDisposedError";
 export { ScopedServiceFromRootError } from "./ScopedServiceFromRootError";
 export { ServiceValidationError } from "./ServiceValidationError";
+export { isConfigurationError, markConfigurationError } from "./configurationError";

package/core/di/index.ts

@@ -10,6 +10,8 @@ export {
   CircularDependencyError,
   ClassDependenciesMismatchError,
   DiError,
+  isConfigurationError,
+  markConfigurationError,
   InvalidProviderError,
   ModuleEncapsulationError,
   ModuleOwnedProviderConflictError,
@@ -35,6 +37,7 @@ export {
   registerModuleOwnedContributionValidator,
   registerModuleOwnedProviderContributor,
   expandModuleMetadata,
+  deferModuleDeclarationError,
   createModuleOwnedMetadataChannel,
   createModuleOwnedProviderChannel,
   scoped,

package/core/di/module/index.ts

@@ -6,6 +6,7 @@ export { ModuleRegistrar } from "./ModuleRegistrar";
 export {
   registerModuleMetadataExpander,
   expandModuleMetadata,
+  deferModuleDeclarationError,
   type ModuleMetadataExpander,
 } from "./moduleExtensions";
 export {

package/core/di/module/moduleExtensions.ts

@@ -1,3 +1,4 @@
+import { markConfigurationError } from "../errors/configurationError";
 import type { BazisModuleMetadata, BazisModuleRef } from "./types";
 
 /**
@@ -21,15 +22,37 @@ export function registerModuleMetadataExpander(expander: ModuleMetadataExpander)
   }
 }
 
+const declarationErrors = new WeakMap<object, unknown>();
+
+/**
+ * Keeps a problem found while a module was declared (a bad `@Infra` manifest,
+ * …) instead of throwing it at import time. The application reports it as a
+ * configuration error when it builds this module.
+ */
+export function deferModuleDeclarationError(moduleRef: object, error: unknown): void {
+  if (!declarationErrors.has(moduleRef)) {
+    declarationErrors.set(moduleRef, markConfigurationError(error));
+  }
+}
+
 /** Collects extra module refs contributed by registered expanders for a module. */
 export function expandModuleMetadata(metadata: BazisModuleMetadata): readonly BazisModuleRef[] {
+  if (declarationErrors.has(metadata)) {
+    throw declarationErrors.get(metadata);
+  }
   if (expanders.length === 0) {
     return [];
   }
   const extra: BazisModuleRef[] = [];
   for (let index = 0; index < expanders.length; index += 1) {
     const expander = expanders[index] as ModuleMetadataExpander;
-    extra.push(...expander(metadata));
+    try {
+      extra.push(...expander(metadata));
+    } catch (error) {
+      // A bad declarative key (`ormBazis` options, …) is a configuration
+      // problem of the module, not an application crash.
+      throw markConfigurationError(error);
+    }
   }
   return extra;
 }

package/core/di/module/moduleOwnedProviderContributors.ts

@@ -1,4 +1,4 @@
-import { ModuleOwnedProviderConflictError } from "../errors";
+import { markConfigurationError, ModuleOwnedProviderConflictError } from "../errors";
 import type { ServiceCollection } from "../ServiceCollection";
 import {
   isClassProvider,
@@ -380,7 +380,11 @@ export function applyModuleOwnedProviderContributors(
   };
 
   for (let index = 0; index < contributors.length; index += 1) {
-    (contributors[index] as ModuleOwnedProviderContributor)(metadata, context);
+    try {
+      (contributors[index] as ModuleOwnedProviderContributor)(metadata, context);
+    } catch (error) {
+      throw markConfigurationError(error);
+    }
   }
 }
 
@@ -404,6 +408,12 @@ export function validateModuleOwnedContributions(
     ): readonly ModuleOwnedMetadataContribution<TPayload>[] => store.getMetadata(channel),
   });
   for (let index = 0; index < validators.length; index += 1) {
-    (validators[index] as ModuleOwnedContributionValidator)(snapshot);
+    try {
+      (validators[index] as ModuleOwnedContributionValidator)(snapshot);
+    } catch (error) {
+      // Conflicting owned stores or connector tokens across modules are
+      // declaration problems: report them as configuration errors.
+      throw markConfigurationError(error);
+    }
   }
 }

package/core/grpc/GrpcSetupError.ts

@@ -0,0 +1,8 @@
+import { KernelError } from "../kernel/errors";
+
+/**
+ * A gRPC controller that cannot be served as declared (an RPC without
+ * @GrpcMethod, a duplicate RPC). A configuration error of the code: the start
+ * prints it as one line and exits with code 1.
+ */
+export class GrpcSetupError extends KernelError {}

package/core/grpc/decorators.ts

@@ -1,4 +1,5 @@
 import type { ServiceDefinition } from "./serviceDefinition";
+import { GrpcSetupError } from "./GrpcSetupError";
 import type { Class } from "../di";
 import type { GrpcControllerDefinition } from "./contracts";
 import type { RequestModelClass } from "../http/Binding/requestModelRegistry";
@@ -10,6 +11,8 @@ interface ControllerMetadata {
   service?: ServiceDefinition;
   methods: Map<string | symbol, string>;
   requestModels: Map<string | symbol, RequestModelClass>;
+  /** Declaration problems, reported by grpcControllerDefinition at start. */
+  problems: string[];
 }
 interface Carrier { [GRPC_META]?: ControllerMetadata }
 
@@ -17,7 +20,12 @@ function ownMetadata(metadata: object): ControllerMetadata {
   const carrier = metadata as Carrier;
   if (!Object.hasOwn(carrier, GRPC_META)) {
     const parent = carrier[GRPC_META];
-    carrier[GRPC_META] = { service: parent?.service, methods: new Map(parent?.methods), requestModels: new Map(parent?.requestModels) };
+    carrier[GRPC_META] = {
+      service: parent?.service,
+      methods: new Map(parent?.methods),
+      requestModels: new Map(parent?.requestModels),
+      problems: [...(parent?.problems ?? [])],
+    };
   }
   return carrier[GRPC_META]!;
 }
@@ -25,32 +33,44 @@ function ownMetadata(metadata: object): ControllerMetadata {
 /** Bind a controller to a generated codec definition or grpcService(). */
 export function GrpcController(service: ServiceDefinition) {
   return (_value: Class<object>, context: ClassDecoratorContext): void => {
+    const meta = ownMetadata(context.metadata);
     if (!service || typeof service !== "object" || Object.keys(service).length === 0) {
-      throw new TypeError("@GrpcController requires a non-empty gRPC service definition.");
+      meta.problems.push("@GrpcController requires a non-empty gRPC service definition.");
+      return;
     }
     const snapshot: Record<string, ServiceDefinition[string]> = Object.create(null);
     for (const [name, method] of Object.entries(service)) {
       if (!method || typeof method.path !== "string" || !/^\/[^/]+\/[^/]+$/.test(method.path)
         || typeof method.requestStream !== "boolean" || typeof method.responseStream !== "boolean"
         || typeof method.requestDeserialize !== "function" || typeof method.responseSerialize !== "function") {
-        throw new TypeError(`Invalid gRPC service method: ${name}.`);
+        meta.problems.push(`invalid gRPC service method: ${name}.`);
+        return;
       }
       snapshot[name] = Object.freeze({ ...method });
     }
-    ownMetadata(context.metadata).service = Object.freeze(snapshot);
+    meta.service = Object.freeze(snapshot);
   };
 }
 
 /** Request/response values for unary; AsyncIterable values for streaming sides. */
 export function GrpcMethod(rpcName?: string, requestModel?: RequestModelClass) {
-  if (requestModel !== undefined && (typeof requestModel !== "function" || !requestModel.prototype)) {
-    throw new TypeError("gRPC requestModel must be a DTO class.");
-  }
   return (_value: unknown, context: ClassMethodDecoratorContext): void => {
-    if (context.static || context.private) throw new TypeError("@GrpcMethod requires a public instance method.");
-    const name = rpcName ?? (typeof context.name === "string" ? context.name : "");
-    if (typeof name !== "string" || name.trim().length === 0) throw new TypeError("gRPC method name must not be empty.");
     const meta = ownMetadata(context.metadata);
+    // Problems are reported when the controller is registered, not at import.
+    const method = String(context.name);
+    if (requestModel !== undefined && (typeof requestModel !== "function" || !requestModel.prototype)) {
+      meta.problems.push(`${method}: gRPC requestModel must be a DTO class.`);
+      return;
+    }
+    if (context.static || context.private) {
+      meta.problems.push(`${method}: @GrpcMethod requires a public instance method.`);
+      return;
+    }
+    const name = rpcName ?? (typeof context.name === "string" ? context.name : "");
+    if (typeof name !== "string" || name.trim().length === 0) {
+      meta.problems.push(`${method}: gRPC method name must not be empty.`);
+      return;
+    }
     meta.methods.set(context.name, name);
     // A redecorated override must not silently retain the base method's DTO.
     if (requestModel === undefined) meta.requestModels.delete(context.name);
@@ -62,21 +82,23 @@ export function GrpcMethod(rpcName?: string, requestModel?: RequestModelClass) {
 export function grpcControllerDefinition(controller: Class<object>): GrpcControllerDefinition {
   const carrier = (controller as unknown as { [Symbol.metadata]?: Carrier })[Symbol.metadata];
   const meta = carrier?.[GRPC_META];
-  if (!meta?.service) throw new TypeError(`${controller.name} must use @GrpcController().`);
+  const problem = meta?.problems[0];
+  if (problem !== undefined) throw new GrpcSetupError(`${controller.name}: ${problem}`);
+  if (!meta?.service) throw new GrpcSetupError(`${controller.name} must use @GrpcController().`);
   const methods = new Map<string, string | symbol>();
   for (const [methodName, rpcName] of meta.methods) {
     const keys = Object.keys(meta.service).filter((key) => {
       const rpc = meta.service![key]!;
       return key === rpcName || rpc.originalName === rpcName || rpc.path.split("/").at(-1) === rpcName;
     });
-    if (keys.length !== 1) throw new TypeError(`${controller.name}.${String(methodName)}: unknown or ambiguous RPC ${rpcName}.`);
+    if (keys.length !== 1) throw new GrpcSetupError(`${controller.name}.${String(methodName)}: unknown or ambiguous RPC ${rpcName}.`);
     const key = keys[0]!;
-    if (methods.has(key)) throw new TypeError(`${controller.name}: duplicate RPC ${rpcName}.`);
-    if (typeof controller.prototype[methodName] !== "function") throw new TypeError(`Missing RPC handler ${String(methodName)}.`);
+    if (methods.has(key)) throw new GrpcSetupError(`${controller.name}: duplicate RPC ${rpcName}.`);
+    if (typeof controller.prototype[methodName] !== "function") throw new GrpcSetupError(`Missing RPC handler ${String(methodName)}.`);
     methods.set(key, methodName);
   }
   for (const key of Object.keys(meta.service)) {
-    if (!methods.has(key)) throw new TypeError(`${controller.name}: RPC ${key} is missing @GrpcMethod().`);
+    if (!methods.has(key)) throw new GrpcSetupError(`${controller.name}: RPC ${key} is missing @GrpcMethod().`);
   }
   return Object.freeze({ controller, service: meta.service, methods, requestModels: new Map(meta.requestModels) });
 }

package/core/grpc/index.ts

@@ -1,5 +1,6 @@
 export { GrpcController, GrpcMethod } from "./decorators";
 export { GrpcError } from "./GrpcError";
+export { GrpcSetupError } from "./GrpcSetupError";
 export { grpcModule } from "./Grpc.module";
 export { GrpcServer } from "./GrpcServer";
 export { GrpcClient } from "./GrpcClient";

package/core/infra/Infra.ts

@@ -4,6 +4,7 @@ import {
   Module,
   createToken,
   createModuleOwnedMetadataChannel,
+  deferModuleDeclarationError,
   registerModuleOwnedProviderContributor,
   registerModuleOwnedContributionValidator,
   type ModuleConfig,
@@ -14,6 +15,7 @@ import {
 import { ConfigRegistry, HEALTH_CHECK, StartupReport } from "../kernel";
 import { InfraError, type InfraConnector } from "./InfraConnector";
 import { InfraLifecycle } from "./InfraLifecycle";
+import { connectorDeclarationError } from "./connectorIdentity";
 
 /**
  * Infrastructure manifest: a readable "logical name → connector" map.
@@ -57,6 +59,8 @@ function buildInfraDefinitions(manifest: InfraManifest): {
   const seenTokens = new Map<InfraConnector["token"], string>();
 
   for (const [name, connector] of Object.entries(manifest)) {
+    const invalid = connectorDeclarationError(connector);
+    if (invalid !== undefined) throw invalid.error;
     if (!name.trim() || name !== name.trim()) throw new InfraError("Infra instance names must be non-empty and trimmed.");
     if (connector.phase !== undefined && !Number.isSafeInteger(connector.phase)) {
       throw new InfraError(`Infra instance "${name}": phase must be a finite safe integer.`);
@@ -135,8 +139,15 @@ function buildInfraDefinitions(manifest: InfraManifest): {
  * `@Infra`, but without a class. Handy for `imports` or `runApp({ infra })`.
  */
 export function infraModule(manifest: InfraManifest): BazisModuleRef {
-  const { providers, exports, config } = buildInfraDefinitions(manifest);
-  return { global: true, providers, exports, config };
+  try {
+    const { providers, exports, config } = buildInfraDefinitions(manifest);
+    return { global: true, providers, exports, config };
+  } catch (error) {
+    // Reported when the application is built, not while the file is imported.
+    const moduleRef: BazisModuleRef = { global: true };
+    deferModuleDeclarationError(moduleRef, error);
+    return moduleRef;
+  }
 }
 
 /**
@@ -157,8 +168,21 @@ export function infraModule(manifest: InfraManifest): BazisModuleRef {
  * ```
  */
 export function Infra(manifest: InfraManifest) {
-  const { providers, exports, config } = buildInfraDefinitions(manifest);
+  let definitions: ReturnType<typeof buildInfraDefinitions> | undefined;
+  let declarationError: unknown;
+  try {
+    definitions = buildInfraDefinitions(manifest);
+  } catch (error) {
+    declarationError = error;
+  }
   return (target: abstract new (...args: never) => unknown, _context: ClassDecoratorContext): void => {
+    if (definitions === undefined) {
+      // Reported when the application is built, not while the file is imported.
+      Module({ global: true })(target, _context);
+      deferModuleDeclarationError(target, declarationError);
+      return;
+    }
+    const { providers, exports, config } = definitions;
     Module({ global: true, providers, exports, config })(target, _context);
   };
 }

package/core/infra/connectorIdentity.ts

@@ -9,6 +9,31 @@ const lifecycles = new WeakMap<object, LifecycleBinding>();
 const values = (c: InfraConnector) => [c.token, c.config, c.phase, c.create, c.connect, c.dispose, c.healthCheck, c.providers, c.exports] as const;
 const unchanged = (c: InfraConnector, identity: ConnectorIdentity) => values(c).every((value, index) => Object.is(value, identity.fingerprint[index]));
 
+const declarationErrors = new WeakMap<object, unknown>();
+
+/**
+ * @internal A connector factory whose options are invalid returns a connector
+ * that carries the problem: `@Infra` reports it when the application is built
+ * instead of crashing the import of the manifest file.
+ */
+export function invalidConnector<T>(token: InfraConnector<T>["token"], error: unknown): InfraConnector<T> {
+  const connector: InfraConnector<T> = {
+    token,
+    create() {
+      throw error;
+    },
+    connect() {},
+    dispose() {},
+  };
+  declarationErrors.set(connector, error);
+  return connector;
+}
+
+/** @internal The declaration problem of a connector made by `invalidConnector`. */
+export function connectorDeclarationError(connector: InfraConnector): { readonly error: unknown } | undefined {
+  return declarationErrors.has(connector) ? { error: declarationErrors.get(connector) } : undefined;
+}
+
 /** @internal A factory identifies its original connector; copies inherit no identity. */
 export function identifyConnector<T>(connector: InfraConnector<T>, role: string): InfraConnector<T> {
   identities.set(connector, Object.freeze({ role, fingerprint: values(connector) }));

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.111.2" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.113.0" }, 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/infra/connectors/llmRouter.ts

@@ -12,7 +12,7 @@ import {
   type AgentModelResponse,
 } from "../../agent";
 import { InfraError, type InfraConnector } from "../InfraConnector";
-import { identifyConnector } from "../connectorIdentity";
+import { identifyConnector, invalidConnector } from "../connectorIdentity";
 import { redactSensitiveText } from "../../../library/redaction";
 import { awaitAbortable } from "../../kernel/internal/awaitAbortable";
 import {
@@ -422,9 +422,16 @@ export function llmRouter(
   profiles: Readonly<Record<string, LlmModelProfile>>,
   options: LlmRouterOptions = {},
 ): InfraConnector<AgentModelProvider> {
-  const entries = profileEntries(profiles);
-  const defaultProfile = defaultProfileName(entries, options);
-  ensureFallbacksValid(entries);
+  let entries: ReturnType<typeof profileEntries>;
+  let defaultProfile: string;
+  try {
+    entries = profileEntries(profiles);
+    defaultProfile = defaultProfileName(entries, options);
+    ensureFallbacksValid(entries);
+  } catch (error) {
+    // Reported by `@Infra` when the application is built, not at import.
+    return invalidConnector(AGENT_MODEL_PROVIDER, error);
+  }
   const configs = Object.freeze(Array.from(new Set(entries.map(([, profile]) => profile.config))));
 
   // The framework LLM connector, like llmConnect: it never touches the schema,

package/core/kernel/Bazis.ts

@@ -1,4 +1,4 @@
-import { DiError } from "../di";
+import { isConfigurationError } from "../di";
 import { Kernel } from "./Kernel";
 import { KernelBuilder, type RootModuleInput } from "./KernelBuilder";
 import { KernelError, ShutdownTimeoutError } from "./errors";
@@ -76,7 +76,7 @@ export class Bazis {
       // deserve the same friendly output as build-time ones.
       if (screen !== undefined) {
         screen.failed(error, kernel);
-      } else if (error instanceof DiError || error instanceof KernelError) {
+      } else if (error instanceof KernelError || isConfigurationError(error)) {
         console.error(`[bazis] configuration error: ${redactSensitiveText(error.message)}`);
       } else {
         console.error(`[bazis] application failed: ${formatStartupFailure(error)}`);
@@ -103,7 +103,7 @@ export function reportBuildFailure(
     process.exitCode = 1;
     return 1;
   }
-  if (error instanceof DiError || error instanceof KernelError) {
+  if (error instanceof KernelError || isConfigurationError(error)) {
     console.error(`[bazis] configuration error: ${redactSensitiveText(error.message)}`);
     process.exitCode = 1;
     return 1;

package/core/kernel/config/ConfigValidationError.ts

@@ -1,6 +1,6 @@
 import { KernelError } from "../errors";
 
-export type ConfigIssueKind = "missing-secret" | "development-secret" | "number" | "boolean" | "string" | "enum" | "validator" | "conflict";
+export type ConfigIssueKind = "missing-secret" | "empty-secret" | "development-secret" | "number" | "boolean" | "string" | "enum" | "validator" | "conflict";
 
 /** One invalid configuration key, with what can change it. */
 export interface ConfigIssue {

package/core/kernel/config/defineConfig.ts

@@ -30,11 +30,14 @@ export interface ConfigEnum<T extends string | number = string | number> {
   readonly default: T;
 }
 export function configEnum<const V extends readonly [string | number, ...(string | number)[]]>(values: V, defaultValue: V[number]): ConfigEnum<V[number]> {
+  const declared: ConfigEnum<V[number]> = Object.freeze({ __enum: true, values: Object.freeze([...values]), default: defaultValue });
   if (!values.length || !values.includes(defaultValue) || values.some(value => typeof value !== typeof defaultValue || (typeof value === "number" && !Number.isFinite(value)))) {
-    throw new KernelError("configEnum requires non-empty homogeneous finite values and a declared default.");
+    // defineConfig reports it at start, with the other configuration errors.
+    invalidEnums.set(declared, new KernelError("configEnum requires non-empty homogeneous finite values and a declared default."));
   }
-  return Object.freeze({ __enum: true, values: Object.freeze([...values]), default: defaultValue });
+  return declared;
 }
+const invalidEnums = new WeakMap<object, KernelError>();
 type Cell = Primitive | SecretSpec | ConfigEnum;
 type Defaults = Record<string, Cell>;
 export type ConfigValueType = Primitive | Secret;
@@ -119,7 +122,11 @@ function isSecret(cell: Cell): cell is SecretSpec { return typeof cell === "obje
 function isEnum(cell: Cell): cell is ConfigEnum { return typeof cell === "object" && cell !== null && "__enum" in cell; }
 function copyCell(cell: Cell): Cell {
   if (isSecret(cell)) return secret(cell.default);
-  if (isEnum(cell)) return Object.freeze({ ...cell, values: Object.freeze([...cell.values]) });
+  if (isEnum(cell)) {
+    const problem = invalidEnums.get(cell);
+    if (problem !== undefined) throw problem;
+    return Object.freeze({ ...cell, values: Object.freeze([...cell.values]) });
+  }
   if (["string", "number", "boolean"].includes(typeof cell)) return cell;
   throw new KernelError("Configuration supports only primitive values, secret() and configEnum().");
 }
@@ -141,6 +148,26 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
   // The file that declared the config, for "declared in" of a startup failure.
   const declaredIn = callerFile(new Error().stack);
   const input = typeof prefixOrSchema === "string" ? maybeSchema! : prefixOrSchema;
+  let definition: ConfigDefinition<ConfigShape>;
+  try {
+    definition = createDefinition(prefix, input, declaredIn);
+  } catch (error) {
+    if (!(error instanceof KernelError)) throw error;
+    // A declaration problem is reported at start, with the other configuration
+    // errors, instead of crashing the import of the file that declares it.
+    const fail = (): never => { throw error; };
+    definition = Object.freeze({
+      token: Object.freeze(createToken<ConfigView<ConfigShape>>(`Config:${prefix || "default"}`)),
+      resolve: fail,
+      get: fail,
+      has: fail,
+      ensureValid: fail,
+    });
+  }
+  definitions.add(definition);
+  return definition;
+}
+function createDefinition(prefix: string, input: ConfigSchema<Defaults>, declaredIn: string | undefined): ConfigDefinition<ConfigShape> {
   const schema = Object.freeze({
     default: Object.freeze(Object.fromEntries(Object.entries(input.default).map(([key, value]) => [key, copyCell(value)]))),
     ...Object.fromEntries((["development", "test", "production"] as const).map(stand => [stand, Object.freeze(Object.fromEntries(Object.entries(input[stand] ?? {}).map(([key, value]) => [key, copyCell(value as Cell)])))])),
@@ -202,7 +229,10 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
       const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
       let value: ConfigValueType | undefined;
       if (type === "secret") {
-        if (typeof raw !== "string" || !raw.trim()) issue(key, "missing-secret", `required non-empty secret is not set (${names.get(key)!.join(", ")})`);
+        // secret("") reads like an empty default but would mean "required":
+        // the declaration is ambiguous, so it is refused with the fix.
+        if (isSecret(cell) && cell.default !== undefined && !cell.default.trim()) issue(key, "empty-secret", 'secret("") is not a value: a secret cannot be empty. Write secret() for a required secret, or give a non-empty development value');
+        else if (typeof raw !== "string" || !raw.trim()) issue(key, "missing-secret", `required non-empty secret is not set (${names.get(key)!.join(", ")})`);
         // A secret default in the code is a development value; production must
         // get the secret from a source or declare its own value explicitly.
         // No "apiKey: …" in the hint: the console redaction would hide it.
@@ -242,13 +272,11 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
       inspect: () => rows,
     });
   };
-  const definition: ConfigDefinition<ConfigShape> = Object.freeze({
+  return Object.freeze({
     token: Object.freeze(createToken<ConfigView<ConfigShape>>(`Config:${prefix || "default"}`)),
     resolve,
     get: <K extends keyof ConfigShape>(key: K): ConfigShape[K] => resolve().get(key),
     has: <K extends keyof ConfigShape>(key: K) => resolve().has(key),
     ensureValid(environment?: Stand) { resolve(environment); },
   });
-  definitions.add(definition);
-  return definition;
 }

package/core/kernel/report/startupProblems.ts

@@ -1,4 +1,4 @@
-import { DiError } from "../../di";
+import { DiError, isConfigurationError } from "../../di";
 import { ServiceValidationError } from "../../di/errors/ServiceValidationError";
 import { redactSensitiveText } from "../../../library/redaction";
 import type { Problem, Screen } from "../../../library/terminal";
@@ -68,7 +68,7 @@ export function diagnoseStartupFailure(error: unknown, screen: Screen, context:
     };
   }
   const failed = context.failedServices?.[0];
-  const stage = error instanceof KernelError && failed === undefined ? "configuration" : stageOf(failed ?? "");
+  const stage = (error instanceof KernelError || isConfigurationError(error)) && failed === undefined ? "configuration" : stageOf(failed ?? "");
   return { stage, title: t.failure.app, problems: [genericProblem(error, failed)] };
 }
 
@@ -84,6 +84,7 @@ function configProblem(issue: ConfigIssue, screen: Screen): Problem {
   const variables = issue.env.map((name) => screen.code(name)).join(" / ");
   const causes: Record<ConfigIssue["kind"], string> = {
     "missing-secret": t.config.issue.missingSecret,
+    "empty-secret": t.config.issue.emptySecret,
     "development-secret": t.config.issue.devSecret,
     number: t.config.issue.number,
     boolean: t.config.issue.boolean,
@@ -94,6 +95,7 @@ function configProblem(issue: ConfigIssue, screen: Screen): Problem {
   };
   const fixes: string[] = [];
   if (issue.kind === "missing-secret") fixes.push(`${t.config.fix.setVariable(variables)}, ${t.config.fix.orSecretFile}`);
+  else if (issue.kind === "empty-secret") fixes.push(t.config.fix.emptySecret);
   else if (issue.kind === "development-secret") fixes.push(t.config.fix.setVariable(variables), t.config.fix.orProduction(screen.code(issue.key.split(".").at(-1) ?? issue.key)));
   else fixes.push(t.config.fix.change(issue.source === undefined ? variables : screen.code(issue.source)));
   // The wrong value and the variable that brought it.

package/library/orm/Schema/MigrationRunner.ts

@@ -101,8 +101,11 @@ export class MigrationRunner {
 
     for (const id of toRollback) {
       const migration = this.migrations.find((m) => m.id === id);
-      if (!migration?.down) {
-        throw new Error(`Migration "${id}" has no down() method.`);
+      if (!migration) {
+        throw new OrmError(`Migration "${id}" is applied but is not in the migrations passed to rollbackVersioned(); pass the full list.`);
+      }
+      if (!migration.down) {
+        throw new OrmError(`Migration "${id}" has no down() method.`);
       }
       await this.provider.transaction(async (tx) => {
         await migration.down!(this.context(tx));

package/library/orm/Transactions/TransactionScopeCoordinator.ts

@@ -198,7 +198,7 @@ export async function transactionScope<TResult>(context: DbContext, provider: Da
 function assertRetryable(context: DbContext): void {
   const tracked = trackedEntryCount(context.changeTracker);
   if (tracked === 0) return;
-  throw new OrmTransactionScopeError(`transactionScope({ retry }) needs ${contextName(context)} without tracked entities: every attempt starts from a clean context, and the ${tracked} entities tracked before the scope would lose their changes. Start the scope before loading anything, or create a new scope for it.`);
+  throw new OrmTransactionScopeError(`transactionScope({ retry }) needs ${contextName(context)} without tracked entities: every attempt starts from a clean context, and the ${tracked === 1 ? "1 entity" : `${tracked} entities`} tracked before the scope would lose ${tracked === 1 ? "its" : "their"} changes. Start the scope before loading anything, or create a new scope for it.`);
 }
 
 async function runScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options: OrmTransactionScopeOptions | undefined, retryContexts?: Set<DbContext>): Promise<TResult> {

package/library/terminal/messages.ts

@@ -111,6 +111,7 @@ const en = {
     invalid: (total: number) => `of ${total} sections invalid`,
     issue: {
       missingSecret: "required secret is not set",
+      emptySecret: 'secret("") is not a value: a secret cannot be empty',
       devSecret: "production would use the development default secret from the code",
       number: "expected a finite number",
       boolean: "expected a boolean (true, false, 1, 0)",
@@ -124,6 +125,7 @@ const en = {
       setVariable: (names: string) => `set ${names}`,
       orSecretFile: "or a file in a secretFilesSource directory",
       orProduction: (key: string) => `or declare ${key}: secret() with a value source in the production section`,
+      emptySecret: "write secret() for a required secret, or give a non-empty development value",
       change: (names: string) => `change ${names}`,
     },
   },
@@ -233,6 +235,7 @@ const en = {
     notRegistered: "not connected — codegen skips it until a module imports it",
     codegenSkipped: "codegen skipped (--no-codegen) — run bazis codegen",
     needsDb: "this module uses a database: connect one with @Infra({ db: ormBazisConnect(dbConfig) })",
+    needsTable: (moduleFile: string) => `its table is not created: add ensureCreated: true to ormBazis in ${moduleFile}, or write a migration`,
     needsCache: "this module caches: pass runApp(AppModule, { cache: memory() })",
     keptOnFailure: "scaffold files were kept — fix the error and run bazis codegen",
   },
@@ -273,6 +276,7 @@ const ru: Messages = {
     invalid: (total) => `из ${total} с ошибками`,
     issue: {
       missingSecret: "обязательный секрет не задан",
+      emptySecret: 'secret("") — не значение: секрет не может быть пустым',
       devSecret: "в production попадёт секрет для разработки из кода",
       number: "нужно конечное число",
       boolean: "нужно логическое значение (true, false, 1, 0)",
@@ -286,6 +290,7 @@ const ru: Messages = {
       setVariable: (names) => `задайте ${names}`,
       orSecretFile: "или файл в каталоге secretFilesSource",
       orProduction: (key) => `или объявите ${key}: secret() с источником значения в разделе production`,
+      emptySecret: "обязательный секрет пишется secret(), а для разработки нужно непустое значение",
       change: (names) => `исправьте ${names}`,
     },
   },
@@ -339,10 +344,10 @@ const ru: Messages = {
     typecheck: (count) => `проверка типов не прошла · ${count} ${formRu(count, NOUNS_RU.error)}`,
     tests: "тесты не прошли",
     command: "команда не выполнена",
-    skipConfig: "не проверялось — конфигурация с ошибками",
-    skipInfra: "не запускалось — инфраструктура недоступна",
-    skipCodegen: "не запускалось — кодогенерация не удалась",
-    skipEarlier: "не запускалось — предыдущий этап не удался",
+    skipConfig: "без проверки — конфигурация с ошибками",
+    skipInfra: "без запуска — инфраструктура недоступна",
+    skipCodegen: "без запуска — кодогенерация не удалась",
+    skipEarlier: "без запуска — предыдущий этап не удался",
     exitNothing: (code) => `код выхода ${code} · ничего не запущено`,
     exitWatch: (code, src) => `код выхода ${code} · слежу за ${src} — исправьте и сохраните для перезапуска`,
     exit: (code) => `код выхода ${code}`,
@@ -395,6 +400,7 @@ const ru: Messages = {
     notRegistered: "не подключён — кодогенерация пропускает его, пока модуль не импортирован",
     codegenSkipped: "кодогенерация пропущена (--no-codegen) — запустите bazis codegen",
     needsDb: "модулю нужна база данных: подключите её через @Infra({ db: ormBazisConnect(dbConfig) })",
+    needsTable: (moduleFile) => `таблицу шаблон не создаёт: добавьте ensureCreated: true в ormBazis в ${moduleFile} или напишите миграцию`,
     needsCache: "модуль кэширует: передайте runApp(AppModule, { cache: memory() })",
     keptOnFailure: "файлы модуля оставлены — исправьте ошибку и запустите bazis codegen",
   },

package/package.json

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