bazis 0.96.1

package/core/di/module/types/DiRegistrar.ts

@@ -0,0 +1,24 @@
+import type { OpenGenericTokenFamily, Token } from "../../token";
+import type { Provider, ProviderDefinition, ProviderLifetime } from "../../provider";
+import type { ServiceKey } from "../../types";
+
+export interface DiRegistrar {
+  singleton<T>(provider: Provider<T>): void;
+  scoped<T>(provider: Provider<T>): void;
+  transient<T>(provider: Provider<T>): void;
+  keyedSingleton<T>(key: ServiceKey, provider: Provider<T>): void;
+  keyedScoped<T>(key: ServiceKey, provider: Provider<T>): void;
+  keyedTransient<T>(key: ServiceKey, provider: Provider<T>): void;
+  trySingleton<T>(provider: Provider<T>): boolean;
+  tryScoped<T>(provider: Provider<T>): boolean;
+  tryTransient<T>(provider: Provider<T>): boolean;
+  tryAddEnumerable(definition: ProviderDefinition): boolean;
+  replace<T>(token: Token<T>, provider: Provider<T>, lifetime: ProviderLifetime, key?: ServiceKey): void;
+  remove(token: Token<unknown>, key?: ServiceKey): number;
+  addOpenGeneric(
+    family: OpenGenericTokenFamily<unknown, unknown>,
+    lifetime: ProviderLifetime,
+    providerFactory: (argument: Token<unknown>) => Provider<unknown>,
+    key?: ServiceKey,
+  ): void;
+}

package/core/di/module/types/index.ts

@@ -0,0 +1,2 @@
+export type { DiRegistrar } from "./DiRegistrar";
+export type { ModuleConfig, ModuleExport, BazisModule, BazisModuleMetadata, BazisModuleRef } from "./BazisModule";

package/core/di/provider/index.ts

@@ -0,0 +1,26 @@
+export type {
+  AsyncFactoryProvider,
+  ClassProvider,
+  FactoryProvider,
+  NamedDependency,
+  ProviderDependencyList,
+  ProviderLifetime,
+  Provider,
+  ProviderOwnership,
+  ProviderOwnershipOptions,
+  ResolvedDeps,
+  ValueProvider,
+} from "./types";
+export {
+  keyedDependency,
+  isKeyedDependency,
+  namedDependency,
+  isNamedDependency,
+  lazyDependency,
+  isLazyDependency,
+  ProviderDefinition,
+  type KeyedDependency,
+  type Lazy,
+  type LazyDependency,
+} from "./types";
+export { isAsyncFactoryProvider, isClassProvider, isFactoryProvider, isValueProvider } from "./providerGuards";

package/core/di/provider/providerGuards.ts

@@ -0,0 +1,17 @@
+import type { AsyncFactoryProvider, ClassProvider, FactoryProvider, Provider, ValueProvider } from "./types";
+
+export function isClassProvider<T>(provider: Provider<T>): provider is ClassProvider<T> {
+  return "useClass" in provider;
+}
+
+export function isFactoryProvider<T>(provider: Provider<T>): provider is FactoryProvider<T> {
+  return "useFactory" in provider;
+}
+
+export function isAsyncFactoryProvider<T>(provider: Provider<T>): provider is AsyncFactoryProvider<T> {
+  return "useAsyncFactory" in provider;
+}
+
+export function isValueProvider<T>(provider: Provider<T>): provider is ValueProvider<T> {
+  return "useValue" in provider;
+}

package/core/di/provider/types/AsyncFactoryProvider.ts

@@ -0,0 +1,15 @@
+import type { Token } from "../../token";
+import type { ServiceResolver } from "../../types";
+import type { ProviderDependencyList } from "./ProviderDependencyList";
+import type { ResolvedDeps } from "./ResolvedDeps";
+import type { ProviderOwnershipOptions } from "./ProviderOwnership";
+
+export interface AsyncFactoryProvider<T, D extends ProviderDependencyList = []> extends ProviderOwnershipOptions {
+  readonly provide: Token<T>;
+  readonly useAsyncFactory:
+    | ((resolver: ServiceResolver, ...args: ResolvedDeps<D>) => Promise<T>)
+    | ((...args: ResolvedDeps<D>) => Promise<T>);
+  readonly deps: D;
+  /** Same explicit contract as FactoryProvider: resolver is passed only when true. */
+  readonly withResolver?: boolean;
+}

package/core/di/provider/types/ClassProvider.ts

@@ -0,0 +1,18 @@
+import type { Class, Token } from "../../token";
+import type { ServiceResolver } from "../../types";
+import type { ProviderDependencyList } from "./ProviderDependencyList";
+import type { ProviderOwnershipOptions } from "./ProviderOwnership";
+
+export interface ClassProvider<T, D extends ProviderDependencyList = []> extends ProviderOwnershipOptions {
+  readonly provide: Token<T>;
+  readonly useClass: Class<T>;
+  readonly deps?: D;
+  /** Optional synchronous wrapper applied after normal constructor activation.
+   * Its dependencies participate in graph, lifetime and module validation.
+   * The wrapper must preserve disposal of the created instance.
+   */
+  readonly activation?: {
+    readonly deps: ProviderDependencyList;
+    wrap(instance: T, resolver: ServiceResolver, ...deps: unknown[]): T;
+  };
+}

package/core/di/provider/types/FactoryProvider.ts

@@ -0,0 +1,20 @@
+import type { Token } from "../../token";
+import type { ServiceResolver } from "../../types";
+import type { ProviderDependencyList } from "./ProviderDependencyList";
+import type { ResolvedDeps } from "./ResolvedDeps";
+import type { ProviderOwnershipOptions } from "./ProviderOwnership";
+
+export interface FactoryProvider<T, D extends ProviderDependencyList = []> extends ProviderOwnershipOptions {
+  readonly provide: Token<T>;
+  readonly useFactory:
+    | ((resolver: ServiceResolver, ...args: ResolvedDeps<D>) => T)
+    | ((...args: ResolvedDeps<D>) => T);
+  readonly deps: D;
+  /**
+   * When true, the container passes a `ServiceResolver` as the first factory
+   * argument. This is an explicit contract: the container never guesses the
+   * factory signature (e.g. via `Function.length`, which breaks with default
+   * and rest parameters).
+   */
+  readonly withResolver?: boolean;
+}

package/core/di/provider/types/KeyedDependency.ts

@@ -0,0 +1,20 @@
+import type { Token } from "../../token";
+import type { ServiceKey } from "../../types";
+
+export interface KeyedDependency<T> {
+  readonly token: Token<T>;
+  readonly key: ServiceKey;
+}
+
+export function keyedDependency<T>(token: Token<T>, key: ServiceKey): KeyedDependency<T> {
+  return { token, key };
+}
+
+export function isKeyedDependency(value: unknown): value is KeyedDependency<unknown> {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      "token" in (value as Record<string, unknown>) &&
+      "key" in (value as Record<string, unknown>),
+  );
+}

package/core/di/provider/types/LazyDependency.ts

@@ -0,0 +1,31 @@
+import type { Token } from "../../token";
+import type { KeyedDependency } from "./KeyedDependency";
+import type { NamedDependency } from "./NamedDependency";
+
+/**
+ * Deferred dependency: the wrapped service is created on first `.value`
+ * access (and cached), not when the consumer is constructed.
+ */
+export interface Lazy<T> {
+  readonly value: T;
+  /** True once the underlying service has been created. */
+  readonly isCreated: boolean;
+}
+
+export interface LazyDependency<T> {
+  readonly lazy: true;
+  readonly inner: Token<T> | KeyedDependency<T> | NamedDependency<T>;
+}
+
+export function lazyDependency<T>(inner: Token<T> | KeyedDependency<T> | NamedDependency<T>): LazyDependency<T> {
+  return { lazy: true, inner };
+}
+
+export function isLazyDependency(value: unknown): value is LazyDependency<unknown> {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      (value as Record<string, unknown>).lazy === true &&
+      "inner" in (value as Record<string, unknown>),
+  );
+}

package/core/di/provider/types/NamedDependency.ts

@@ -0,0 +1,16 @@
+export interface NamedDependency<T = unknown> {
+  readonly name: string;
+}
+
+export function namedDependency<T = unknown>(name: string): NamedDependency<T> {
+  return { name };
+}
+
+export function isNamedDependency(value: unknown): value is NamedDependency<unknown> {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      "name" in (value as Record<string, unknown>) &&
+      typeof (value as Record<string, unknown>).name === "string",
+  );
+}

package/core/di/provider/types/Provider.ts

@@ -0,0 +1,10 @@
+import type { AsyncFactoryProvider } from "./AsyncFactoryProvider";
+import type { ClassProvider } from "./ClassProvider";
+import type { FactoryProvider } from "./FactoryProvider";
+import type { ValueProvider } from "./ValueProvider";
+
+export type Provider<T = unknown> =
+  | ClassProvider<T, any>
+  | FactoryProvider<T, any>
+  | AsyncFactoryProvider<T, any>
+  | ValueProvider<T>;

package/core/di/provider/types/ProviderDefinition.ts

@@ -0,0 +1,11 @@
+import type { ServiceKey } from "../../types";
+import type { Provider } from "./Provider";
+import type { ProviderLifetime } from "./ProviderLifetime";
+
+export class ProviderDefinition<T = unknown> {
+  public constructor(
+    public readonly provider: Provider<T>,
+    public readonly lifetime: ProviderLifetime,
+    public readonly key?: ServiceKey,
+  ) {}
+}

package/core/di/provider/types/ProviderDependencyList.ts

@@ -0,0 +1,11 @@
+import type { Token } from "../../token";
+import type { KeyedDependency } from "./KeyedDependency";
+import type { LazyDependency } from "./LazyDependency";
+import type { NamedDependency } from "./NamedDependency";
+
+export type ProviderDependencyList = readonly (
+  | Token<unknown>
+  | KeyedDependency<unknown>
+  | NamedDependency<unknown>
+  | LazyDependency<unknown>
+)[];

package/core/di/provider/types/ProviderLifetime.ts

@@ -0,0 +1 @@
+export type ProviderLifetime = "singleton" | "scoped" | "transient";

package/core/di/provider/types/ProviderOwnership.ts

@@ -0,0 +1,7 @@
+/** Who is responsible for disposing an instance created by a provider. */
+export type ProviderOwnership = "container" | "external";
+
+export interface ProviderOwnershipOptions {
+  /** Defaults to `container`; use `external` when a lifecycle adapter owns cleanup. */
+  readonly ownership?: ProviderOwnership;
+}

package/core/di/provider/types/ResolvedDeps.ts

@@ -0,0 +1,18 @@
+import type { Token } from "../../token";
+import type { KeyedDependency } from "./KeyedDependency";
+import type { Lazy, LazyDependency } from "./LazyDependency";
+import type { NamedDependency } from "./NamedDependency";
+
+export type ResolvedDeps<
+  D extends readonly (Token<unknown> | KeyedDependency<unknown> | NamedDependency<unknown> | LazyDependency<unknown>)[],
+> = {
+  [K in keyof D]: D[K] extends LazyDependency<infer TResolvedLazy>
+    ? Lazy<TResolvedLazy>
+    : D[K] extends Token<infer TResolved>
+      ? TResolved
+      : D[K] extends KeyedDependency<infer TResolvedKeyed>
+        ? TResolvedKeyed
+        : D[K] extends NamedDependency<infer TResolvedNamed>
+          ? TResolvedNamed
+          : never;
+};

package/core/di/provider/types/ValueProvider.ts

@@ -0,0 +1,6 @@
+import type { Token } from "../../token";
+
+export interface ValueProvider<T> {
+  readonly provide: Token<T>;
+  readonly useValue: T;
+}

package/core/di/provider/types/index.ts

@@ -0,0 +1,13 @@
+export type { AsyncFactoryProvider } from "./AsyncFactoryProvider";
+export type { ClassProvider } from "./ClassProvider";
+export type { FactoryProvider } from "./FactoryProvider";
+export { keyedDependency, isKeyedDependency, type KeyedDependency } from "./KeyedDependency";
+export { namedDependency, isNamedDependency, type NamedDependency } from "./NamedDependency";
+export { lazyDependency, isLazyDependency, type Lazy, type LazyDependency } from "./LazyDependency";
+export type { ProviderDependencyList } from "./ProviderDependencyList";
+export { ProviderDefinition } from "./ProviderDefinition";
+export type { ProviderLifetime } from "./ProviderLifetime";
+export type { Provider } from "./Provider";
+export type { ProviderOwnership, ProviderOwnershipOptions } from "./ProviderOwnership";
+export type { ResolvedDeps } from "./ResolvedDeps";
+export type { ValueProvider } from "./ValueProvider";

package/core/di/token.ts

@@ -0,0 +1,84 @@
+// `any[]` is intentional: it lets concrete classes act as their own tokens
+// without TS rejecting constructors with typed parameters. Runtime shape of
+// constructor deps is still validated by the container.
+export type Class<T> = new (...args: any[]) => T;
+
+export interface InjectionToken<T> {
+  readonly id: symbol;
+  readonly description: string;
+  readonly genericFamilyId?: symbol;
+  readonly genericArgId?: symbol;
+  readonly genericArgToken?: Token<unknown>;
+}
+
+export function createToken<T>(description: string): InjectionToken<T> {
+  return {
+    id: Symbol(description),
+    description,
+  };
+}
+
+export type Token<T> = Class<T> | InjectionToken<T>;
+
+export interface OpenGenericTokenFamily<TArg, TResult> {
+  readonly id: symbol;
+  readonly description: string;
+  of(argument: Token<TArg>): InjectionToken<TResult>;
+}
+
+export function createOpenGenericTokenFamily<TArg, TResult>(description: string): OpenGenericTokenFamily<TArg, TResult> {
+  const familyId = Symbol(description);
+  // Canonical closed tokens per argument: `of(X)` must always return the same
+  // token instance, otherwise singleton identity breaks (a fresh token would
+  // materialize a fresh registration and a fresh instance on every call).
+  const closedTokens = new Map<symbol, InjectionToken<TResult>>();
+  return {
+    id: familyId,
+    description,
+    of(argument: Token<TArg>): InjectionToken<TResult> {
+      const argumentId = getTokenStableId(argument);
+      const existing = closedTokens.get(argumentId);
+      if (existing) {
+        return existing;
+      }
+
+      const closedDescription = `${description}<${tokenToDebugName(argument)}>`;
+      const token: InjectionToken<TResult> = {
+        id: Symbol(closedDescription),
+        description: closedDescription,
+        genericFamilyId: familyId,
+        genericArgId: argumentId,
+        genericArgToken: argument,
+      };
+      closedTokens.set(argumentId, token);
+      return token;
+    },
+  };
+}
+
+export function tokenToDebugName(token: Token<unknown>): string {
+  if (typeof token === "function") {
+    return token.name || "<anonymous class>";
+  }
+
+  return token.description;
+}
+
+// Stable identity for class tokens is kept off-object in a WeakMap so the
+// container never mutates user classes (no enumerable `__bazisTokenId` leaks
+// into Object.keys / serialization). Garbage-collected with the class itself.
+const classTokenIds = new WeakMap<Function, symbol>();
+
+function getTokenStableId(token: Token<unknown>): symbol {
+  if (typeof token === "function") {
+    const existing = classTokenIds.get(token);
+    if (existing) {
+      return existing;
+    }
+    const id = Symbol(token.name || "class-token");
+    classTokenIds.set(token, id);
+    return id;
+  }
+
+  return token.id;
+}

package/core/di/types/BuildServiceProviderOptions.ts

@@ -0,0 +1,4 @@
+export interface BuildServiceProviderOptions {
+  readonly validateOnBuild?: boolean;
+  readonly validateScopes?: boolean;
+}

package/core/di/types/ServiceKey.ts

@@ -0,0 +1 @@
+export type ServiceKey = string | number | symbol;

package/core/di/types/ServiceResolver.ts

@@ -0,0 +1,16 @@
+import type { Token } from "../token";
+import type { ServiceKey } from "./ServiceKey";
+
+export interface ServiceResolver {
+  resolve<T>(token: Token<T>): T;
+  resolveAll<T>(token: Token<T>): readonly T[];
+  resolveKeyed<T>(token: Token<T>, key: ServiceKey): T;
+  resolveAllKeyed<T>(token: Token<T>, key: ServiceKey): readonly T[];
+  /** Resolves a service whose chain may contain async factories. */
+  resolveAsync<T>(token: Token<T>): Promise<T>;
+  resolveKeyedAsync<T>(token: Token<T>, key: ServiceKey): Promise<T>;
+  /** Returns the service or undefined when no provider is registered (other errors propagate). */
+  tryResolve<T>(token: Token<T>, key?: ServiceKey): T | undefined;
+  /** Checks whether a provider is registered for the token (and key, if given). */
+  has(token: Token<unknown>, key?: ServiceKey): boolean;
+}

package/core/di/types/index.ts

@@ -0,0 +1,3 @@
+export type { BuildServiceProviderOptions } from "./BuildServiceProviderOptions";
+export type { ServiceKey } from "./ServiceKey";
+export type { ServiceResolver } from "./ServiceResolver";

package/core/generatedFingerprint.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/** What codegen saw: project sources of the target and the framework version. */
+export interface GeneratedSourceFingerprint {
+  /** Project root relative to the generated directory. */
+  readonly root: string;
+  readonly framework: string;
+  /** Project-relative source files of the target, sorted. */
+  readonly files: readonly string[];
+  readonly hash: string;
+}
+
+/** sha256 over every path and its bytes; undefined when a listed file is gone. */
+export function hashSources(root: string, files: readonly string[]): string | undefined {
+  const hasher = new Bun.CryptoHasher("sha256");
+  for (const file of files) {
+    const absolute = path.join(root, file);
+    if (!existsSync(absolute)) return undefined;
+    hasher.update(file).update("\0").update(readFileSync(absolute)).update("\0");
+  }
+  return hasher.digest("hex");
+}
+
+/** Version of the framework package this module belongs to, when on disk. */
+export function frameworkVersion(): string | undefined {
+  try {
+    const version = JSON.parse(readFileSync(path.resolve(import.meta.dir, "../package.json"), "utf8")).version;
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Warns loudly when the app is started from sources that changed after codegen
+ * (or with another framework version): new routes and dependencies would be
+ * silently missing. A compiled binary carries no sources, so it is skipped.
+ */
+export function warnIfGeneratedSourcesChanged(
+  generatedDir: string,
+  fingerprint: GeneratedSourceFingerprint,
+  warn: (message: string) => void = (message) => console.warn(message),
+): boolean {
+  const root = path.resolve(generatedDir, fingerprint.root);
+  if (!existsSync(path.join(root, "bazis.config.json"))) return false;
+  const changes: string[] = [];
+  if (hashSources(root, fingerprint.files) !== fingerprint.hash) changes.push("application sources changed");
+  const version = frameworkVersion();
+  if (version !== undefined && version !== fingerprint.framework) changes.push(`bazis ${fingerprint.framework} -> ${version}`);
+  if (changes.length === 0) return false;
+  warn([
+    "",
+    `[bazis] WARNING: generated code is out of date (${changes.join("; ")}).`,
+    "[bazis] New or changed controllers, routes and constructor dependencies are NOT active.",
+    "[bazis] Run: bunx bazis codegen   (bazis dev, bazis build and bazis test run it automatically)",
+    "",
+  ].join("\n"));
+  return true;
+}

package/core/generatedRuntime.ts

@@ -0,0 +1,187 @@
+import path from "node:path";
+import type { AgentMetadataIndex } from "./agent/AgentRegistry";
+import { registerGeneratedClassDeps, restoreGeneratedClassDeps, snapshotGeneratedClassDeps, type GeneratedClassDependency } from "./di/module/autoDeps";
+import { registerGeneratedBindings, restoreGeneratedBindings, snapshotGeneratedBindings } from "./http/Binding/autoBindings";
+import { registerRequestModelShape, restoreRequestModelRegistry, snapshotRequestModelRegistry, type RequestModelClass, type RequestModelShape } from "./http/Binding/requestModelRegistry";
+import { registerListModelClass, restoreListModelRegistry, snapshotListModelRegistry, type ListModelClass } from "./http/Binding/listModelRegistry";
+import { registerGeneratedOpenApiMetadata, registerGeneratedOpenApiSchemaModel, restoreGeneratedOpenApiRegistry, snapshotGeneratedOpenApiRegistry, type GeneratedOpenApiSchemaModel } from "./http/OpenApi/generatedOpenApiRegistry";
+import type { Class } from "./di";
+import type { GeneratedBindingSpec } from "./http/Binding/generatedSpec";
+import type { GeneratedOpenApiMetadata } from "../library/openapi";
+import {
+  commitGeneratedProviderAttachments,
+  prepareGeneratedProviderAttachments,
+  restoreGeneratedProviderAttachments,
+  snapshotGeneratedProviderAttachments,
+  type GeneratedProviderAttachmentV1,
+} from "./di/module/generatedProviderAttachments";
+export type { GeneratedProviderAttachmentV1 } from "./di/module/generatedProviderAttachments";
+export { warnIfGeneratedSourcesChanged, type GeneratedSourceFingerprint } from "./generatedFingerprint";
+export {
+  createGeneratedProviderAttachmentChannel,
+  getGeneratedProviderAttachment,
+  type GeneratedProviderAttachmentChannel,
+} from "./di/module/generatedProviderAttachments";
+
+type GeneratedRuntimeModule = {
+  readonly registerBazisGeneratedRuntime?: () => void | Promise<void>;
+};
+
+type GeneratedAgentCatalogModule = {
+  readonly GENERATED_AGENT_METADATA?: AgentMetadataIndex;
+};
+
+let runtimeLoad: Promise<void> | undefined;
+
+export interface BazisGeneratedTargetDescriptor {
+  readonly id: string;
+  readonly classDeps: readonly (readonly [Class<unknown>, readonly GeneratedClassDependency[]])[];
+  readonly bindings: readonly (readonly [Class<object>, Readonly<Record<string, readonly GeneratedBindingSpec[]>>])[];
+  readonly requestModels: readonly RequestModelClass[];
+  readonly requestShapes: readonly (readonly [RequestModelClass, RequestModelShape])[];
+  readonly listModels: readonly ListModelClass[];
+  readonly openApi: GeneratedOpenApiMetadata;
+  readonly openApiSchemaModels: readonly (readonly [GeneratedOpenApiSchemaModel, string])[];
+  /** Target-local generated Agent/Tool/Prompt metadata. */
+  readonly agentMetadata?: AgentMetadataIndex;
+  /** Package-internal exact-class metadata attached atomically with this target. */
+  readonly providerAttachments?: readonly GeneratedProviderAttachmentV1[];
+}
+
+const committedTargetDescriptors = new Set<string>();
+const targetDescriptorLoads = new Map<string, Promise<void>>();
+const committedTargetDescriptorsById = new Map<string, BazisGeneratedTargetDescriptor>();
+const explicitlyActivatedTargetIds = new Set<string>();
+
+/**
+ * Internal atomic publication boundary for one complete generated target.
+ * Generated modules only export immutable data; validation happens before any
+ * owner registry receives a mutation. Repeated and concurrent activation is
+ * target-idempotent.
+ */
+export function registerBazisGeneratedTargetDescriptor(descriptor: BazisGeneratedTargetDescriptor): Promise<void> {
+  const existing = targetDescriptorLoads.get(descriptor.id);
+  if (existing !== undefined) return existing;
+  const load = Promise.resolve().then(() => {
+    validateDescriptor(descriptor);
+    if (committedTargetDescriptors.has(descriptor.id)) return;
+    const preparedAttachments = prepareGeneratedProviderAttachments(descriptor.providerAttachments);
+    const snapshots = {
+      classDeps: snapshotGeneratedClassDeps(),
+      bindings: snapshotGeneratedBindings(),
+      requestModels: snapshotRequestModelRegistry(),
+      listModels: snapshotListModelRegistry(),
+      openApi: snapshotGeneratedOpenApiRegistry(),
+      providerAttachments: snapshotGeneratedProviderAttachments(),
+    };
+    try {
+      for (const [target, deps] of descriptor.classDeps) registerGeneratedClassDeps(target, deps);
+      const modelIndex = new Map<string, Class<object>>();
+      for (const model of [...descriptor.requestModels, ...descriptor.listModels]) {
+        if (model.name) modelIndex.set(model.name, model);
+      }
+      for (const [target, bindings] of descriptor.bindings) registerGeneratedBindings(target, bindings, modelIndex);
+      for (const [model, shape] of descriptor.requestShapes) registerRequestModelShape(model, shape);
+      for (const model of descriptor.listModels) registerListModelClass(model);
+      registerGeneratedOpenApiMetadata(descriptor.openApi, descriptor.bindings.map(([controller]) => controller));
+      for (const [model, name] of descriptor.openApiSchemaModels) registerGeneratedOpenApiSchemaModel(model, name);
+      commitGeneratedProviderAttachments(preparedAttachments);
+      committedTargetDescriptors.add(descriptor.id);
+      committedTargetDescriptorsById.set(descriptor.id, descriptor);
+      explicitlyActivatedTargetIds.add(descriptor.id);
+    } catch (error) {
+      restoreGeneratedClassDeps(snapshots.classDeps);
+      restoreGeneratedBindings(snapshots.bindings);
+      restoreRequestModelRegistry(snapshots.requestModels);
+      restoreListModelRegistry(snapshots.listModels);
+      restoreGeneratedOpenApiRegistry(snapshots.openApi);
+      restoreGeneratedProviderAttachments(snapshots.providerAttachments);
+      throw error;
+    }
+  });
+  targetDescriptorLoads.set(descriptor.id, load);
+  void load.catch(() => targetDescriptorLoads.delete(descriptor.id));
+  return load;
+}
+
+function validateDescriptor(descriptor: BazisGeneratedTargetDescriptor): void {
+  if (!/^[a-z][a-z0-9-]*$/.test(descriptor.id)) throw new TypeError("Invalid generated target descriptor id.");
+  const dependencyTargets = new Set<object>();
+  for (const [target, deps] of descriptor.classDeps) {
+    if (typeof target !== "function" || !Array.isArray(deps) || dependencyTargets.has(target)) throw new TypeError(`Invalid generated DI descriptor for ${descriptor.id}.`);
+    dependencyTargets.add(target);
+  }
+  const bindingTargets = new Set<object>();
+  for (const [target, bindings] of descriptor.bindings) {
+    if (typeof target !== "function" || bindings === null || typeof bindings !== "object" || bindingTargets.has(target)) throw new TypeError(`Invalid generated HTTP descriptor for ${descriptor.id}.`);
+    bindingTargets.add(target);
+  }
+  for (const model of [...descriptor.requestModels, ...descriptor.listModels]) if (typeof model !== "function") throw new TypeError(`Invalid generated model descriptor for ${descriptor.id}.`);
+  for (const [model, name] of descriptor.openApiSchemaModels) if (typeof model !== "function" || name.trim().length === 0) throw new TypeError(`Invalid generated OpenAPI descriptor for ${descriptor.id}.`);
+  if (descriptor.providerAttachments !== undefined && !Array.isArray(descriptor.providerAttachments)) throw new TypeError(`Invalid generated provider attachment descriptor for ${descriptor.id}.`);
+}
+
+/**
+ * Loads project-owned generated runtime registrations, when present.
+ *
+ * The framework core stays independent from `src/app`: generated
+ * files live under `src/generated/bazis` and register request/list models,
+ * OpenAPI metadata and similar app-owned artifacts through public registries.
+ */
+export function loadBazisGeneratedRuntime(): Promise<void> {
+  // A project-local target bootstrap is authoritative for this process.  Do
+  // not even import the default generated graph after it was selected.
+  if (explicitlyActivatedTargetIds.size > 0) return Promise.resolve();
+  runtimeLoad ??= loadRuntimeOnce();
+  return runtimeLoad;
+}
+
+export async function loadBazisGeneratedAgentMetadata(
+  targets: readonly Class<object>[] = [],
+): Promise<AgentMetadataIndex | undefined> {
+  const registered = selectRegisteredAgentMetadata(targets);
+  if (registered !== undefined || explicitlyActivatedTargetIds.size > 0) return registered;
+  const module = await importGeneratedModule<GeneratedAgentCatalogModule>("agentCatalog");
+  return module?.GENERATED_AGENT_METADATA;
+}
+
+function selectRegisteredAgentMetadata(targets: readonly Class<object>[]): AgentMetadataIndex | undefined {
+  const candidates = [...committedTargetDescriptorsById.values()]
+    .map((descriptor) => descriptor.agentMetadata)
+    .filter((metadata): metadata is AgentMetadataIndex => metadata !== undefined);
+  if (candidates.length === 0) return undefined;
+  for (const metadata of candidates) {
+    for (const target of targets) {
+      if (metadata.agents.has(target) || metadata.tools.has(target) || metadata.prompts.has(target)) return metadata;
+    }
+  }
+  return candidates.length === 1 ? candidates[0] : undefined;
+}
+
+async function loadRuntimeOnce(): Promise<void> {
+  const module = await importGeneratedModule<GeneratedRuntimeModule>("runtime");
+  await module?.registerBazisGeneratedRuntime?.();
+}
+
+/**
+ * The project's generated module `name`, or undefined when it does not exist.
+ * Framework sources inside the project (`src/bazis`) find `src/generated`
+ * next to them; an installed package (`node_modules/bazis`) cannot, so the
+ * project root is the working directory, as for `bazis dev` and `bazis test`.
+ */
+async function importGeneratedModule<T>(name: string): Promise<T | undefined> {
+  const candidates = [`../../generated/bazis/${name}`, path.join(process.cwd(), "src/generated/bazis", name)];
+  for (const candidate of candidates) {
+    try {
+      return (await import(candidate)) as T;
+    } catch (error) {
+      if (!isOptionalGeneratedModuleMissing(error, `generated/bazis/${name}`)) throw error;
+    }
+  }
+  return undefined;
+}
+
+function isOptionalGeneratedModuleMissing(error: unknown, generatedPath: string): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Cannot find module") && message.includes(generatedPath);
+}