@supacloud/compiler 0.24.0 → 0.26.0

package/dist/index.js

@@ -125,7 +125,12 @@ function buildContractManifest(graph, artifacts) {
           ...command?.permission === undefined ? {} : { permission: command.permission },
           requestSchemas: Object.fromEntries(["body", "params", "query", "headers", "cookie"].flatMap((key) => route[key] === undefined ? [] : [[key, route[key]]])),
           ...route.response === undefined ? {} : { responseSchema: route.response },
-          ...route.contract?.evidence === undefined ? {} : { evidence: route.contract.evidence }
+          ...route.responses === undefined ? {} : {
+            responseSchemas: Object.fromEntries(Object.entries(route.responses).sort(([left], [right]) => left.localeCompare(right)))
+          },
+          ...route.contract?.evidence === undefined ? {} : { evidence: route.contract.evidence },
+          ...route.parse === undefined ? {} : { parse: route.parse },
+          ...route.allowDeleteBody === undefined ? {} : { allowDeleteBody: route.allowDeleteBody }
         });
       }
     }
@@ -214,7 +219,7 @@ function renderApplication(graph, options) {
       providers: mod.providers.filter((p) => p.providedIn !== "root" || p.multi || referencedTokens.has(p.token) || p.exported)
     }));
   }
-  const imports = new ImportManager;
+  const imports = new ImportManager(new Set(["CompiledApplicationModule"]));
   const factorySections = [];
   const descriptorEntries = [];
   for (const module of modules) {
@@ -231,7 +236,13 @@ function renderApplication(graph, options) {
     "",
     TYPE_GUARDS,
     "",
-    "export function createCompiledModules(): CompiledModule[] {",
+    ...modules.length > 0 ? [
+      'export type CompiledApplicationModule = Omit<CompiledModule, "name" | "createServices"> & (',
+      ...modules.map((module) => `  | { name: ${JSON.stringify(module.name)}; createServices: typeof create${pascalName(module.name)}Services }`),
+      ");"
+    ] : ["export type CompiledApplicationModule = CompiledModule;"],
+    "",
+    "export function createCompiledModules(): CompiledApplicationModule[] {",
     "  return [",
     ...descriptorEntries.map((entry) => indent(entry, 4) + ","),
     "  ];",
@@ -312,7 +323,9 @@ function renderApplication(graph, options) {
   };
 }
 async function generateApplication(graph, options) {
-  const rendered = renderApplication(graph, options);
+  return writeRenderedApplication(renderApplication(graph, options), options);
+}
+async function writeRenderedApplication(rendered, options) {
   await mkdir(options.outDir, { recursive: true });
   const applicationPath = join2(options.outDir, "application.ts");
   const manifestPath = join2(options.outDir, "app.manifest.json");
@@ -399,8 +412,12 @@ function indent(text, spaces) {
 }
 
 class ImportManager {
+  reserved;
   entries = new Map;
   lookup = new Map;
+  constructor(reserved = new Set) {
+    this.reserved = reserved;
+  }
   get size() {
     return this.entries.size;
   }
@@ -415,7 +432,7 @@ class ImportManager {
       return existing;
     let local = exported;
     let counter = 2;
-    while (this.entries.has(local)) {
+    while (this.entries.has(local) || this.reserved.has(local)) {
       local = `${exported}${counter}`;
       counter += 1;
     }
@@ -472,7 +489,7 @@ class ModuleGenerator {
   renderDescriptor() {
     const lines = [
       `{`,
-      `  name: ${JSON.stringify(this.module.name)},`,
+      `  name: ${JSON.stringify(this.module.name)} as const,`,
       `  createServices: create${this.pascal}Services,`
     ];
     if (this.hasFactoryContent("request")) {
@@ -611,6 +628,10 @@ class ModuleGenerator {
         if (route.contract !== undefined) {
           fields.push(`contract: ${JSON.stringify(route.contract)}`);
         }
+        if (route.parse === "none")
+          fields.push('parse: "none"');
+        if (route.allowDeleteBody === true)
+          fields.push("allowDeleteBody: true");
         if (route.schemaKinds !== undefined && Object.keys(route.schemaKinds).length > 0) {
           fields.push(`schemaKinds: ${JSON.stringify(route.schemaKinds)}`);
         }
@@ -710,7 +731,7 @@ ${indent(item, 2)}`).join(",")}
       `function create${this.pascal}Services(`,
       `  deps: Record<string, unknown>,`,
       `  imported: Record<string, Record<string, unknown>>,`,
-      `): Record<string, unknown> {`,
+      `) {`,
       indent(this.renderFactoryBody("services"), 2),
       `}`
     ].join(`
@@ -807,7 +828,7 @@ ${indent(item, 2)}`).join(",")}
 `);
     }
     const entries = [...returns.entries()].map(([key, expr]) => key === expr ? key : `${key}: ${expr}`);
-    lines.push(`return { ${entries.join(", ")} };`);
+    lines.push(`return retainPlatformDependencies({ ${entries.join(", ")} }, deps);`);
     return lines.join(`
 `);
   }
@@ -908,6 +929,9 @@ ${indent(item, 2)}`).join(",")}
         return this.depExpr(own.useExisting ?? token, kind, options);
       }
     }
+    if (own && factoryOfScope(own.scope) === "services" && kind !== "services" && !isSkipSelf && !isSelf) {
+      return `services.${camelName(token)}`;
+    }
     if (isSelf) {
       return isOptional ? "undefined" : `services.${camelName(token)}`;
     }
@@ -925,13 +949,14 @@ ${indent(item, 2)}`).join(",")}
         return `imported.${mod.name}.${camelName(token)}`;
       }
     }
-    if (isOptional && !this.graph.externalTokens.includes(token)) {
-      return "undefined";
-    }
     if (isSelf)
       return isOptional ? "undefined" : `services.${camelName(token)}`;
     if (kind === "services")
       return isOptional ? `(deps.${camelName(token)} ?? undefined)` : `deps.${camelName(token)}`;
+    if (!own || isSkipSelf) {
+      const external = `platformDependencies.get(services)?.${camelName(token)}`;
+      return isOptional ? `(${external} ?? undefined)` : external;
+    }
     return isOptional ? `(services.${camelName(token)} ?? undefined)` : `services.${camelName(token)}`;
   }
 }
@@ -959,7 +984,7 @@ function orderProviders(providers) {
 function renderClient(graph, options) {
   const rootDir = options?.rootDir ?? process.cwd();
   const outDir = options?.outDir ?? process.cwd();
-  const imports = new ImportManager;
+  const imports = new ImportManager(new Set(["ApiClientError", "ApiClientErrorCode", "ApiClientErrorDetails"]));
   const controllerEntries = [];
   const routeTypes = [];
   const schemaEntries = [];
@@ -1017,11 +1042,14 @@ function renderClient(graph, options) {
         }).filter((entry) => entry.length === 2));
         if (Object.keys(responseSchemas).length > 0)
           usesValue = true;
-        const paramNames = [...new Set((fullPath.match(/:([a-zA-Z0-9_]+)/g) ?? []).map((p) => p.slice(1)))];
+        const paramNames = [...new Set([
+          ...(fullPath.match(/:([a-zA-Z0-9_]+)/g) ?? []).map((p) => p.slice(1)),
+          ...fullPath.endsWith("/*") ? ["*"] : []
+        ])];
         const pathParamsType = paramNames.length > 0 ? `{ ${paramNames.map((p) => `${/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(p) ? p : JSON.stringify(p)}: string | number`).join("; ")} }` : "Record<string, string | number>";
         const paramsType = paramsSchema ? `Static<typeof ${paramsSchema.local}>${paramNames.length > 0 ? ` & ${pathParamsType}` : ""}` : pathParamsType;
         const queryType = querySchema ? `Static<typeof ${querySchema.local}>` : "Record<string, unknown>";
-        const bodyType = bodySchema ? `Static<typeof ${bodySchema.local}>` : "unknown";
+        const bodyType = route.parse === "none" ? "BodyInit" : bodySchema ? `Static<typeof ${bodySchema.local}>` : "unknown";
         const headersType = headersSchema ? `Static<typeof ${headersSchema.local}>` : "Record<string, string>";
         const cookieType = cookieSchema ? `Static<typeof ${cookieSchema.local}>` : "Record<string, string | number | boolean>";
         const responseTypes = [
@@ -1058,7 +1086,9 @@ function renderClient(graph, options) {
           ["queryTransforms", route.queryTransforms],
           ["queryDefaults", route.queryDefaults],
           ["title", route.title],
-          ["data", route.data]
+          ["data", route.data],
+          ["parse", route.parse],
+          ["allowDeleteBody", route.allowDeleteBody]
         ]) {
           if (value !== undefined)
             routeFields.push(`${key}: ${JSON.stringify(value)}`);
@@ -1092,7 +1122,7 @@ function renderClient(graph, options) {
         const responseSchemaArgument = responseSchemaEntries.length > 0 ? `{ ${responseSchemaEntries.map(([status, local]) => `${JSON.stringify(status)}: ${local}`).join(", ")} }` : "undefined";
         const responseKindArgument = responseKind === undefined ? "undefined" : JSON.stringify(responseKind);
         routeMethods.push(`
-    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}),`);
+    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -1123,6 +1153,40 @@ function renderClient(graph, options) {
     "",
     "export type ResponseDecoder<T> = (value: unknown) => T;",
     "",
+    'export type ApiClientErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED";',
+    "",
+    "export interface ApiClientErrorDetails {",
+    "  code: ApiClientErrorCode;",
+    "  method: string;",
+    "  path: string;",
+    "  status: number;",
+    "  requestId?: string | null;",
+    "  response?: Response;",
+    "}",
+    "",
+    "/** Transport/contract metadata, not proof that a failed write rolled back. */",
+    "export class ApiClientError extends Error {",
+    "  readonly code: ApiClientErrorCode;",
+    "  readonly method: string;",
+    "  readonly path: string;",
+    "  readonly status: number;",
+    "  readonly requestId: string | undefined;",
+    "  /** Undeclared HTTP response for explicit inspection; excluded from JSON serialization. */",
+    "  readonly response: Response | undefined;",
+    "  constructor(message: string, details: ApiClientErrorDetails) {",
+    "    super(message);",
+    '    this.name = "ApiClientError";',
+    "    const { code, method, path, status, requestId, response } = details;",
+    "    this.code = code;",
+    "    this.method = method;",
+    "    this.path = path;",
+    "    this.status = status;",
+    "    this.requestId = requestId && /^[A-Za-z0-9._:-]{1,256}$/.test(requestId) ? requestId : undefined;",
+    "    this.response = response;",
+    '    Object.defineProperty(this, "response", { enumerable: false });',
+    "  }",
+    "}",
+    "",
     "export type RouteMethod<",
     "  Options extends ClientRequestOptions = ClientRequestOptions,",
     "  Result = never,",
@@ -1176,6 +1240,13 @@ function renderClient(graph, options) {
     '    if (typeof value !== "string" && typeof value !== "number") throw new TypeError(`Missing route parameter: ${key}`);',
     "    return encodeURIComponent(String(value));",
     "  });",
+    '  if (path.endsWith("/*")) {',
+    '    const wildcard = params && Object.hasOwn(params, "*") ? params["*"] : undefined;',
+    '    if (typeof wildcard !== "string" && typeof wildcard !== "number") throw new TypeError("Missing route parameter: *");',
+    '    const segments = String(wildcard).split("/");',
+    '    if (segments.some(segment => segment === "." || segment === "..")) throw new TypeError("Wildcard dot segments are not supported by Fetch URLs");',
+    '    url = url.slice(0, -1) + segments.map(encodeURIComponent).join("/");',
+    "  }",
     "  if (query) {",
     "    const searchParams = new URLSearchParams();",
     "    for (const [k, v] of Object.entries(query)) {",
@@ -1362,6 +1433,10 @@ function renderClient(graph, options) {
     "export function createApiClient(config: ApiClientConfig = {}) {",
     "  const fetcher = config.fetch ?? globalThis.fetch.bind(globalThis);",
     '  const baseUrl = (config.baseUrl ?? "").replace(/\\/+$/, "");',
+    "  function rawBody(value: unknown): BodyInit {",
+    '    if (typeof value === "string" || value instanceof Blob || value instanceof FormData || value instanceof URLSearchParams || value instanceof ArrayBuffer || ArrayBuffer.isView(value) || value instanceof ReadableStream) return value as BodyInit;',
+    '    throw new TypeError("Raw routes require a BodyInit value; JSON encoding is not implicit");',
+    "  }",
     "",
     "  async function request<T>(",
     "    method: string,",
@@ -1370,6 +1445,7 @@ function renderClient(graph, options) {
     "    decode: ResponseDecoder<T>,",
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
+    "    raw?: boolean,",
     "  ): Promise<T>;",
     "  async function request<T>(",
     "    method: string,",
@@ -1378,6 +1454,7 @@ function renderClient(graph, options) {
     "    decode?: ResponseDecoder<T>,",
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
+    "    raw?: boolean,",
     "  ): Promise<T | unknown>;",
     "  async function request(",
     "    method: string,",
@@ -1391,11 +1468,12 @@ function renderClient(graph, options) {
     "    decode?: ResponseDecoder<T>,",
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
+    "    raw = false,",
     "  ): Promise<T | unknown> {",
     "    const url = `${baseUrl}${buildRouteUrl(path, options.params, options.query)}`;",
     '    const customHeaders = typeof config.headers === "function" ? await config.headers() : config.headers;',
     "    const headers: Record<string, string> = {",
-    '      "content-type": "application/json",',
+    '      ...(raw ? {} : { "content-type": "application/json" }),',
     "      ...customHeaders,",
     "      ...options.headers,",
     "    };",
@@ -1414,21 +1492,27 @@ function renderClient(graph, options) {
     "      return fetcher(reqPayload.url, {",
     "        method: reqPayload.method,",
     "        headers: reqPayload.headers,",
-    "        ...(reqPayload.body === undefined ? {} : { body: JSON.stringify(reqPayload.body) }),",
+    "        ...(reqPayload.body === undefined ? {} : { body: raw ? rawBody(reqPayload.body) : JSON.stringify(reqPayload.body) }),",
+    '        ...(raw && reqPayload.body instanceof ReadableStream ? { duplex: "half" } : {}),',
     "      });",
     "    };",
     "    const response = await executeChain(0, { method, url, headers, body: options.body });",
     "    const declaredSchema = responseSchemas ? selectResponseSchema(response.status, responseSchemas) : undefined;",
+    "    const failure = (code: ApiClientErrorCode, message: string) => new ApiClientError(message, {",
+    '      code, method, path, status: response.status, requestId: response.headers.get("x-request-id"),',
+    '      ...(code === "API_HTTP_ERROR" ? { response } : {}),',
+    "    });",
     "    if (!response.ok && declaredSchema === undefined) {",
-    "      const errBody = await response.text();",
-    "      throw new Error(`API request failed: ${method} ${path} -> ${response.status} ${errBody}`);",
+    '      throw failure("API_HTTP_ERROR", `API request failed: ${method} ${path} -> ${response.status}`);',
     "    }",
     '    const contentType = response.headers?.get("content-type") ?? "";',
     "    let value: unknown;",
     "    if ([204, 205, 304].includes(response.status)) {",
     "      value = undefined;",
     '    } else if (contentType.includes("application/json") || contentType.includes("+json")) {',
-    "      value = await response.json();",
+    "      const responseText = await response.text();",
+    "      try { value = JSON.parse(responseText); }",
+    '      catch { throw failure("API_RESPONSE_INVALID", "Response is not valid JSON"); }',
     '    } else if (responseKind === "binary" || contentType.includes("application/octet-stream")) {',
     "      value = await response.arrayBuffer();",
     '    } else if (responseKind === "stream") {',
@@ -1439,20 +1523,24 @@ function renderClient(graph, options) {
     "    if (!responseSchemas) return decode ? decode(value) : value;",
     "    if (declaredSchema === undefined) {",
     '      const transportSuccess = response.ok && (responseKind === "binary" || responseKind === "stream");',
-    "      if (!transportSuccess) throw new Error(`No response schema declared for HTTP ${response.status}`);",
+    '      if (!transportSuccess) throw failure("API_RESPONSE_UNDECLARED", `No response schema declared for HTTP ${response.status}`);',
     "      return decode ? decode(value) : value;",
     "    }",
-    ...usesValue ? ["    const checked = decodeResponseSchema(value, response.status, responseSchemas, { normalize: config.normalize ?? true });"] : ["    const checked = value;"],
+    ...usesValue ? [
+      "    let checked: unknown;",
+      "    try { checked = decodeResponseSchema(value, response.status, responseSchemas, { normalize: config.normalize ?? true }); }",
+      '    catch { throw failure("API_RESPONSE_INVALID", "Response does not match schema"); }'
+    ] : ["    const checked = value;"],
     "    return decode ? decode(checked) : checked;",
     "  }",
     "",
-    `  function makeRoute<Options extends ClientRequestOptions, Result = never>(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string): RouteMethod<Options, Result> {`,
+    `  function makeRoute<Options extends ClientRequestOptions, Result = never>(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): RouteMethod<Options, Result> {`,
     "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
     "    function route(options: Options): Promise<Result>;",
     "    function route(options?: Options): Promise<unknown>;",
     "    function route<T>(options?: Options, decode?: ResponseDecoder<T>): Promise<T | unknown> {",
     "      const requestOptions = options ?? {};",
-    "      return request(method, path, requestOptions, decode, responseSchemas, responseKind);",
+    "      return request(method, path, requestOptions, decode, responseSchemas, responseKind, raw);",
     "    }",
     "    return route as RouteMethod<Options, Result>;",
     "  }",
@@ -1509,11 +1597,15 @@ function renderOpenApi(graph, options) {
   for (const module of graph.modules) {
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
+        const documentation = route.data?.openapi;
+        if (documentation !== null && typeof documentation === "object" && "hide" in documentation && documentation.hide === true)
+          continue;
         const fullPath = joinRoutePaths(controller.path, route.path);
         const responseEntries = normalizedResponseEntries(route.responses);
         const hasResponseMap = responseEntries.length > 0;
         const pathParams = [...new Set([
           ...(fullPath.match(/:([A-Za-z0-9_]+)/g) ?? []).map((item) => item.slice(1)),
+          ...fullPath.endsWith("/*") ? ["*"] : [],
           ...route.pathParams ?? []
         ].filter((item) => item.length > 0))];
         const queryParams = [...new Set([
@@ -1546,6 +1638,8 @@ function renderOpenApi(graph, options) {
           }).filter((entry) => entry.length === 2)) } : {},
           responseContentType,
           responseKind: responseKind ?? (route.nativeResponse ? "native-response" : undefined),
+          ...route.parse === undefined ? {} : { parse: route.parse },
+          ...route.allowDeleteBody === undefined ? {} : { allowDeleteBody: route.allowDeleteBody },
           module: module.name,
           controller: controller.className,
           handler: route.handler,
@@ -1629,6 +1723,8 @@ function renderOpenApi(graph, options) {
     "  canMatch?: readonly string[];",
     "  canDeactivate?: readonly string[];",
     "  contract?: Record<string, unknown>;",
+    '  parse?: "none";',
+    "  allowDeleteBody?: true;",
     "  data?: Record<string, unknown>;",
     "  requiresAuth?: boolean;",
     "};",
@@ -1826,8 +1922,15 @@ function renderOpenApi(graph, options) {
     '  return { $ref: `#/components/schemas/${encodeURIComponent(name).replaceAll("%2F", "/")}` };',
     "}",
     "",
+    "function wildcardParameterName(path: string): string {",
+    "  const names = new Set([...path.matchAll(/:([A-Za-z0-9_]+)/g)].map(match => match[1]));",
+    '  let name = "wildcard";',
+    '  while (names.has(name)) name += "_";',
+    "  return name;",
+    "}",
+    "",
     "function openApiPath(path: string): string {",
-    '  return path.replace(/:([A-Za-z0-9_]+)/g, "{$1}");',
+    '  return path.replace(/:([A-Za-z0-9_]+)/g, "{$1}").replace(/\\/\\*$/, `/{${wildcardParameterName(path)}}`);',
     "}",
     "",
     "function responseHasBody(status: string, kind: string | undefined): boolean {",
@@ -1857,7 +1960,7 @@ function renderOpenApi(graph, options) {
     "  const parameters: Record<string, unknown>[] = [];",
     "  const paramsSchema = definition.paramsSchema ? OPENAPI_SCHEMA_REGISTRY[definition.paramsSchema as keyof typeof OPENAPI_SCHEMA_REGISTRY] : undefined;",
     "  for (const name of definition.pathParams) parameters.push({",
-    '    name, in: "path", required: true, schema: schemaProperty(paramsSchema, name),',
+    '    name: name === "*" ? wildcardParameterName(definition.path) : name, in: "path", required: true, schema: schemaProperty(paramsSchema, name),',
     "  });",
     "  const querySchema = definition.querySchema ? OPENAPI_SCHEMA_REGISTRY[definition.querySchema as keyof typeof OPENAPI_SCHEMA_REGISTRY] : undefined;",
     "  const queryNames = new Set([...(querySchema ? schemaPropertyNames(querySchema) : []), ...definition.queryParams]);",
@@ -1894,6 +1997,7 @@ function renderOpenApi(graph, options) {
     "    operationId: definition.operationId, tags: [...definition.tags], summary: definition.summary, responses,",
     "    ...(parameters.length === 0 ? {} : { parameters }),",
     '    ...(definition.bodySchema ? { requestBody: { required: !schemaAllowsUndefined(OPENAPI_SCHEMA_REGISTRY[definition.bodySchema as keyof typeof OPENAPI_SCHEMA_REGISTRY]), content: { "application/json": { schema: schemaReference(definition.bodySchema) } } } } : {}),',
+    '    ...(definition.parse === "none" ? { requestBody: { required: false, description: "Raw request bytes; validation and media types are owned by the domain handler.", content: { "*/*": { schema: { type: "string", format: "binary" } } } } } : {}),',
     "    ...(definition.requiresAuth ? { security: [{ bearerAuth: [] }] } : {}),",
     '    "x-supacloud": {',
     "      module: definition.module, controller: definition.controller, handler: definition.handler,",
@@ -1903,6 +2007,8 @@ function renderOpenApi(graph, options) {
     "      ...(definition.canMatch ? { canMatch: [...definition.canMatch] } : {}),",
     "      ...(definition.canDeactivate ? { canDeactivate: [...definition.canDeactivate] } : {}),",
     "      ...(definition.contract ? { contract: definition.contract } : {}),",
+    "      ...(definition.parse ? { parse: definition.parse } : {}),",
+    "      ...(definition.allowDeleteBody ? { allowDeleteBody: true } : {}),",
     "      ...(definition.data ? { data: definition.data } : {}),",
     "    },",
     "  };",
@@ -1998,6 +2104,8 @@ function renderPermissions(graph) {
 `);
 }
 var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES = `export interface CompiledRoute {
+  parse?: "none";
+  allowDeleteBody?: true;
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
   path: string;
   handler: string;
@@ -2150,6 +2258,12 @@ function resolveFactoryValue(value: unknown): unknown {
 }
 
 const scopeDestructions = new WeakMap<object, Promise<void>>();
+const platformDependencies = new WeakMap<object, Record<string, unknown>>();
+
+function retainPlatformDependencies<T extends Record<string, unknown>>(services: T, deps: Record<string, unknown>): T {
+  platformDependencies.set(services, deps);
+  return services;
+}
 
 function destroyScopeInstances(
   scope: Record<string, unknown>,
@@ -2696,9 +2810,9 @@ var init_graphql = __esm(() => {
 });
 
 // src/graphql-schema.ts
-import { mkdir as mkdir5, readFile as readFile11 } from "node:fs/promises";
-import { createHash as createHash9 } from "node:crypto";
-import { dirname as dirname10, resolve as resolve15 } from "node:path";
+import { mkdir as mkdir5, readFile as readFile12 } from "node:fs/promises";
+import { createHash as createHash10 } from "node:crypto";
+import { dirname as dirname10, resolve as resolve16 } from "node:path";
 async function pullGraphqlSchema(options) {
   assertGraphqlOptions({ schema: options.output });
   const endpoint = new URL(options.url);
@@ -2738,7 +2852,7 @@ async function pullGraphqlSchema(options) {
     throw new Error("GraphQL schema export failed. Verify caller grants and enable introspection only in the intended development environment.");
   }
   const schema = lexicographicSortSchema(buildClientSchema(data));
-  const path = resolve15(options.output);
+  const path = resolve16(options.output);
   const content = path.endsWith(".json") ? JSON.stringify(introspectionFromSchema(schema), null, 2) + `
 ` : `# GENERATED BY supacloud-compiler graphql-schema. DO NOT EDIT.
 # Database First: change database declarations, apply migrations, then re-export for the intended role.
@@ -2746,13 +2860,13 @@ async function pullGraphqlSchema(options) {
 `;
   let previous;
   try {
-    previous = await readFile11(path, "utf8");
+    previous = await readFile12(path, "utf8");
   } catch (error) {
     if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
       throw error;
   }
   const upToDate = previous === content;
-  const schemaHash = createHash9("sha256").update(content).digest("hex");
+  const schemaHash = createHash10("sha256").update(content).digest("hex");
   if (options.check)
     return { path, schemaHash, upToDate, written: false };
   await mkdir5(dirname10(path), { recursive: true });
@@ -2765,12 +2879,12 @@ var init_graphql_schema = __esm(() => {
 });
 
 // src/database-contracts.ts
-import { createHash as createHash10 } from "node:crypto";
-import { mkdir as mkdir6, readFile as readFile12 } from "node:fs/promises";
-import { dirname as dirname11, relative as relative12, resolve as resolve16 } from "node:path";
+import { createHash as createHash11 } from "node:crypto";
+import { mkdir as mkdir6, readFile as readFile13 } from "node:fs/promises";
+import { dirname as dirname11, relative as relative12, resolve as resolve17 } from "node:path";
 import * as ts13 from "@typescript/typescript6";
 function hash2(value) {
-  return createHash10("sha256").update(value).digest("hex");
+  return createHash11("sha256").update(value).digest("hex");
 }
 function importPath(out, path) {
   const value = relative12(out, path).replaceAll("\\", "/").replace(/\.(?:d\.)?[cm]?ts$/, "");
@@ -2795,19 +2909,19 @@ function parseDatabaseContractsOptions(value, directory) {
     throw new TypeError("migrations must be an ordered list of SQL files");
   }
   return {
-    rootDir: resolve16(directory, field("rootDir")),
-    outDir: resolve16(directory, field("outDir")),
-    postgrestTypes: resolve16(directory, field("postgrestTypes")),
-    drizzleSchema: resolve16(directory, field("drizzleSchema")),
+    rootDir: resolve17(directory, field("rootDir")),
+    outDir: resolve17(directory, field("outDir")),
+    postgrestTypes: resolve17(directory, field("postgrestTypes")),
+    drizzleSchema: resolve17(directory, field("drizzleSchema")),
     role: field("role"),
-    graphql: { ...graphql, schema: resolve16(directory, graphql.schema) },
-    migrations: migrations.map((file) => resolve16(directory, file))
+    graphql: { ...graphql, schema: resolve17(directory, graphql.schema) },
+    migrations: migrations.map((file) => resolve17(directory, file))
   };
 }
 async function generateDatabaseContracts(options, check = false) {
-  const rootDir = resolve16(options.rootDir), outDir = resolve16(options.outDir);
-  const postgrestTypes = resolve16(rootDir, options.postgrestTypes), drizzleSchema = resolve16(rootDir, options.drizzleSchema);
-  const snapshot = await readFile12(postgrestTypes, "utf8");
+  const rootDir = resolve17(options.rootDir), outDir = resolve17(options.outDir);
+  const postgrestTypes = resolve17(rootDir, options.postgrestTypes), drizzleSchema = resolve17(rootDir, options.drizzleSchema);
+  const snapshot = await readFile13(postgrestTypes, "utf8");
   const syntax = ts13.createSourceFile(postgrestTypes, snapshot, ts13.ScriptTarget.Latest, true);
   const database = syntax.statements.find((node) => (ts13.isTypeAliasDeclaration(node) || ts13.isInterfaceDeclaration(node)) && node.name.text === "Database" && node.modifiers?.some((modifier) => modifier.kind === ts13.SyntaxKind.ExportKeyword));
   if (!database)
@@ -2834,8 +2948,8 @@ async function generateDatabaseContracts(options, check = false) {
   }
   const inputs = {};
   const addInput = async (path) => {
-    const absolute = resolve16(rootDir, path);
-    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile12(absolute, "utf8"));
+    const absolute = resolve17(rootDir, path);
+    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile13(absolute, "utf8"));
   };
   await addInput(postgrestTypes);
   await addInput(drizzleSchema);
@@ -2851,8 +2965,8 @@ async function generateDatabaseContracts(options, check = false) {
     if (!source.isDeclarationFile && !source.fileName.includes("/node_modules/"))
       await addInput(source.fileName);
   }
-  await addInput(resolve16(rootDir, options.graphql.schema));
-  if (new Set(options.migrations.map((path) => resolve16(rootDir, path))).size !== options.migrations.length) {
+  await addInput(resolve17(rootDir, options.graphql.schema));
+  if (new Set(options.migrations.map((path) => resolve17(rootDir, path))).size !== options.migrations.length) {
     throw new Error("Duplicate migration in database contracts configuration");
   }
   for (const path of options.migrations)
@@ -2873,17 +2987,17 @@ async function generateDatabaseContracts(options, check = false) {
     version: 1,
     role: options.role,
     inputs: Object.fromEntries(Object.entries(inputs).sort(([a], [b]) => a.localeCompare(b))),
-    migrationOrder: options.migrations.map((path) => relative12(rootDir, resolve16(rootDir, path)).replaceAll("\\", "/")),
+    migrationOrder: options.migrations.map((path) => relative12(rootDir, resolve17(rootDir, path)).replaceAll("\\", "/")),
     outputs: Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([file, text]) => [file, hash2(text)]))
   };
   files["database.manifest.json"] = JSON.stringify(manifest, null, 2) + `
 `;
   const mismatches = [];
   for (const [file, content] of Object.entries(files)) {
-    const path = resolve16(outDir, file);
+    const path = resolve17(outDir, file);
     let current;
     try {
-      current = await readFile12(path, "utf8");
+      current = await readFile13(path, "utf8");
     } catch (error) {
       if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
         throw error;
@@ -2894,13 +3008,13 @@ async function generateDatabaseContracts(options, check = false) {
   if (!check) {
     await mkdir6(outDir, { recursive: true });
     for (const [file, content] of Object.entries(files))
-      await writeFileIfChanged(resolve16(outDir, file), content);
+      await writeFileIfChanged(resolve17(outDir, file), content);
   }
   return { upToDate: mismatches.length === 0, mismatches, written: check ? [] : mismatches, manifest };
 }
 async function runDatabaseContractsFile(path, check = false) {
-  const absolute = resolve16(path);
-  const value = JSON.parse(await readFile12(absolute, "utf8"));
+  const absolute = resolve17(path);
+  const value = JSON.parse(await readFile13(absolute, "utf8"));
   return generateDatabaseContracts(parseDatabaseContractsOptions(value, dirname11(absolute)), check);
 }
 var init_database_contracts = __esm(() => {
@@ -3608,6 +3722,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
 };
 function validateGraph(graph, options = false) {
   const strict = typeof options === "boolean" ? options : options.strict ?? false;
+  const generateOpenApi = typeof options === "object" && options.generateOpenApi === true;
   const diagnostics = [];
   for (const module of graph.modules) {
     for (const owner of [...module.providers, ...module.controllers]) {
@@ -3743,7 +3858,7 @@ function validateGraph(graph, options = false) {
         }
         const fullPath = joinRoutePaths2(controller.path, route.path);
         const rawFullPath = joinRawRoutePaths(controller.path, route.path);
-        const key = `${route.method} ${fullPath}`;
+        const key = `${route.method} ${generateOpenApi ? fullPath.replace(/:[A-Za-z0-9_]+|\*$/g, "{}") : fullPath}`;
         const openApiMatch = route.path.match(/\{([a-zA-Z0-9_]+)\}/);
         if (openApiMatch) {
           error("missing-param-colon", `Route path '${route.path}' in '${controller.className}.${route.handler}' uses OpenAPI-style '{${openApiMatch[1]}}'. SupaCloud routes require Express/Angular-style ':${openApiMatch[1]}'.`, controller.file, undefined, `Replace '{${openApiMatch[1]}}' with ':${openApiMatch[1]}'.`);
@@ -3843,7 +3958,13 @@ function validateGraph(graph, options = false) {
             }
           }
         }
-        if ((route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS" || route.method === "DELETE") && (route.hasBodyBinding || route.body)) {
+        if (route.allowDeleteBody && (route.method !== "DELETE" || !route.body)) {
+          error("invalid-delete-body-opt-in", `Route ${controller.className}.${route.handler} allowDeleteBody requires DELETE and an explicit body schema.`, controller.file);
+        }
+        if (route.parse === "none" && (route.body || route.hasBodyBinding || route.contract?.body !== "domain" || !route.contract.evidence?.trim())) {
+          error("invalid-raw-body-contract", `Route ${controller.className}.${route.handler} parse: "none" requires domain body ownership and evidence, without a parsed body schema or @Body binding.`, controller.file);
+        }
+        if ((route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS" || route.method === "DELETE" && !route.allowDeleteBody) && (route.hasBodyBinding || route.body)) {
           error("disallowed-body-on-get-delete", `Route handler ${controller.className}.${route.handler} binds @Body() or declares body schema on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`, {
             type: "remove_route_body_binding",
             targetFile: controller.file,
@@ -4555,6 +4676,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     tokensByName: new Map,
     classesByName: new Map,
     variablesByName: new Map,
+    moduleHandlerFiles: new Map,
     diagnostics: []
   };
   const nativeTraitFiles = new Map;
@@ -4645,10 +4767,11 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
       const hasChangedFile = entry.ownedFiles.some((f) => changedFiles.has(f));
       const moduleFileExists = currentFileHashes.has(entry.module.file);
       const isAffectedByDep = affectedModuleNames.has(modName);
-      if (!hasChangedFile && !isAffectedByDep && moduleFileExists) {
+      if (!hasChangedFile && !isAffectedByDep && moduleFileExists && entry.handlerFiles !== undefined) {
         modulesToKeep.set(modName, entry);
         reusedModules.push(modName);
         finalModules.push(entry.module);
+        ctx.moduleHandlerFiles.set(modName, entry.handlerFiles);
         if (entry.diagnostics)
           finalDiagnostics.push(...entry.diagnostics);
       }
@@ -4668,6 +4791,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
       }
       cache.modules.set(parsed.name, {
         module: parsed,
+        handlerFiles: ctx.moduleHandlerFiles.get(parsed.name) ?? [],
         ownedFiles: [...ownedFiles],
         fileHashes,
         diagnostics: moduleDiagnostics
@@ -4836,6 +4960,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     externalTokens,
     diagnostics: ctx.diagnostics.map(withDiagnosticMetadata),
     tokenNames,
+    moduleHandlerFiles: Object.fromEntries(ctx.moduleHandlerFiles),
     ...cache ? { cacheStats: { reusedModules, reanalyzedModules } } : {}
   };
 }
@@ -5048,6 +5173,7 @@ function parseModule(candidate, nameByNode, ctx) {
   arrayProp(options, "commands").forEach(collectHandler);
   arrayProp(options, "jobs").forEach(collectHandler);
   arrayProp(options, "queries").forEach(collectHandler);
+  ctx.moduleHandlerFiles.set(name, [...new Set([...handlerClasses].map((cls) => sourcePath(ctx.rootDir, cls.getSourceFile().fileName)))].sort());
   const commands = [];
   const jobs = [];
   const queries = [];
@@ -5226,6 +5352,25 @@ function resolveStaticObjectLiteral(input, ctx, seen = new Set) {
   }
   return ts4.isObjectLiteralExpression(input) ? input : undefined;
 }
+function routePolicyProperty(object, name, ctx, seen = new Set) {
+  if (seen.has(object))
+    return { unresolved: true };
+  const ancestry = new Set(seen).add(object);
+  let result = { unresolved: false };
+  for (const property of object.properties) {
+    if (ts4.isSpreadAssignment(property)) {
+      const spread = resolveStaticObjectLiteral(property.expression, ctx);
+      const nested = spread ? routePolicyProperty(spread, name, ctx, ancestry) : { unresolved: true };
+      if (nested.unresolved || nested.value !== undefined)
+        result = nested;
+    } else if (ts4.isComputedPropertyName(property.name)) {
+      result = { unresolved: true };
+    } else if (propertyName(property.name) === name) {
+      result = ts4.isPropertyAssignment(property) ? { value: property.initializer, unresolved: false } : { unresolved: true };
+    }
+  }
+  return result;
+}
 function commandModeProp(object, name) {
   const value = stringLiteralProp(object, name);
   return value === "required" || value === "none" ? value : undefined;
@@ -5733,10 +5878,13 @@ function parseController(input, ctx) {
       const pathParams = [];
       const paramRegex = /:([a-zA-Z0-9_]+)/g;
       let match;
-      while ((match = paramRegex.exec(routePath)) !== null) {
+      const fullPath = joinRoutePaths(path, routePath);
+      while ((match = paramRegex.exec(fullPath)) !== null) {
         if (match[1] !== undefined)
           pathParams.push(match[1]);
       }
+      if (joinRoutePaths(path, routePath).endsWith("/*"))
+        pathParams.push("*");
       if (pathParams.length > 0)
         route.pathParams = pathParams;
       const paramBindings = [];
@@ -5887,6 +6035,40 @@ function parseController(input, ctx) {
       const optionsArg = args[1];
       const optionsObject = resolveStaticObjectLiteral(optionsArg, ctx);
       if (optionsObject) {
+        const parsePolicy = routePolicyProperty(optionsObject, "parse", ctx);
+        const deletePolicy = routePolicyProperty(optionsObject, "allowDeleteBody", ctx);
+        if (parsePolicy.unresolved || deletePolicy.unresolved) {
+          ctx.diagnostics.push({
+            severity: "error",
+            code: "unresolved-route-body-policy",
+            file,
+            message: `Route ${route.handler} body policy must be statically resolvable; dynamic spreads, computed keys and shorthand policies are unsupported.`
+          });
+        }
+        const parse = parsePolicy.value;
+        if (parse) {
+          if (ts4.isStringLiteral(parse) && parse.text === "none")
+            route.parse = "none";
+          else
+            ctx.diagnostics.push({
+              severity: "error",
+              code: "invalid-route-parser",
+              file,
+              message: `Route ${route.handler} parse must be the literal "none".`
+            });
+        }
+        const allowDeleteBody = deletePolicy.value;
+        if (allowDeleteBody) {
+          if (allowDeleteBody.kind === ts4.SyntaxKind.TrueKeyword)
+            route.allowDeleteBody = true;
+          else
+            ctx.diagnostics.push({
+              severity: "error",
+              code: "invalid-delete-body-opt-in",
+              file,
+              message: `Route ${route.handler} allowDeleteBody must be the literal true.`
+            });
+        }
         const legacyResponseExpr = getProp(optionsObject, "response");
         const responsesExpr = getProp(optionsObject, "responses");
         if (legacyResponseExpr !== undefined && responsesExpr !== undefined) {
@@ -7080,7 +7262,7 @@ async function compileProject(options) {
     ...options,
     ...options.cache ? { artifactHashes: options.cache.generatedHashes } : {}
   };
-  const written = !hasErrors || options.writeOnError === true ? await generateApplication(graph, generatedOptions) : [];
+  const written = !hasErrors || options.writeOnError === true ? await writeRenderedApplication(rendered, generatedOptions) : [];
   if (!hasErrors) {
     for (const [filename, content] of Object.entries(graphql.files)) {
       const path = join4(options.outDir, filename);
@@ -11438,6 +11620,48 @@ function importSymbol(source, path, symbol) {
   return `import { ${symbol} } from ${JSON.stringify(path)};
 ${source.text}`;
 }
+// src/repair-plan.ts
+function createDiagnosticRepairPlan(diagnostics) {
+  return diagnostics.flatMap((diagnostic) => {
+    const fix = diagnostic.fix;
+    if (!fix)
+      return [];
+    return [{
+      code: diagnostic.code,
+      ...diagnostic.errorCode === undefined ? {} : { errorCode: diagnostic.errorCode },
+      ...diagnostic.file === undefined ? {} : { file: diagnostic.file },
+      ...diagnostic.line === undefined ? {} : { line: diagnostic.line },
+      type: fix.type,
+      targetFile: fix.targetFile,
+      fix,
+      ...classifyFix(fix)
+    }];
+  });
+}
+function classifyFix(fix) {
+  switch (fix.type) {
+    case "set_command_mode":
+      if (fix.value !== "required" && fix.value !== "none") {
+        return { readiness: "input-required", reason: "Choose an explicit transaction or idempotency policy; no policy is inferred." };
+      }
+      break;
+    case "add_command_permission":
+      if (!fix.permission?.trim()) {
+        return { readiness: "input-required", reason: "Choose an explicit business permission; privileges are never inferred." };
+      }
+      break;
+    case "add_module_import":
+      if (!fix.importPath || !fix.symbol) {
+        return { readiness: "input-required", reason: "Supply the module import path and exported symbol before previewing." };
+      }
+      break;
+    case "add_route_parameter_binding":
+      break;
+    default:
+      return { readiness: "manual", reason: "The semantic fix executor does not implement this suggestion; edit and verify it manually." };
+  }
+  return { readiness: "preview", reason: "Preview with the semantic fix executor; source preconditions are checked before writing." };
+}
 // src/watch.ts
 import { existsSync as existsSync3, watch } from "node:fs";
 import { dirname as dirname7, relative as relative9, resolve as resolve10, sep as sep9 } from "node:path";
@@ -11585,6 +11809,8 @@ function optionsKeyOf(options) {
     requireRouteContracts: options.requireRouteContracts,
     detectOrphanModules: options.detectOrphanModules,
     generateClient: options.generateClient,
+    generateOpenApi: options.generateOpenApi,
+    openApi: options.openApi,
     generatePermissions: options.generatePermissions,
     typeSafety: options.typeSafety,
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
@@ -11719,6 +11945,16 @@ function findAffectedModules(previous, current, changedFiles) {
 
 // src/watch.ts
 var DEFAULT_DEBOUNCE_MS = 100;
+function isCompilerConfigurationPath(rootDir, changedPath) {
+  const relativePath = relative9(rootDir, changedPath).split(sep9).join("/");
+  return [
+    "supacloud.config.ts",
+    "supacloud.config.mts",
+    "supacloud.config.js",
+    "supacloud.config.mjs",
+    "tsconfig.json"
+  ].includes(relativePath) || /^tsconfig\.[^/]+\.json$/.test(relativePath);
+}
 function watchProject(options) {
   const rootDir = resolve10(options.rootDir);
   const outDir = resolve10(options.outDir);
@@ -11811,7 +12047,7 @@ function watchProject(options) {
       const relativePath = relative9(outDir, changedPath);
       if (!relativePath.startsWith("..") && relativePath !== "")
         return;
-      if (/\.(tsx?|mts|cts)$/.test(changedPath) || options.graphql && (/\.(graphql|gql)$/.test(changedPath) || changedPath === schemaPath)) {
+      if (/\.(tsx?|mts|cts)$/.test(changedPath) || isCompilerConfigurationPath(rootDir, changedPath) || options.graphql && (/\.(graphql|gql)$/.test(changedPath) || changedPath === schemaPath)) {
         schedule(relative9(rootDir, changedPath));
       }
     });
@@ -11865,9 +12101,9 @@ function compilerVersion() {
 }
 function migrationDependencies() {
   return {
-    "@supacloud/app": "0.16.0",
+    "@supacloud/app": "0.17.0",
     "@supacloud/compiler": compilerVersion(),
-    "@supacloud/elysia": "0.18.0",
+    "@supacloud/elysia": "0.19.0",
     elysia: "1.4.30",
     typescript: "7.0.2"
   };
@@ -11948,6 +12184,8 @@ function isDefineRouteContractCall(node, checker) {
   return resolveSymbol(checker.getSymbolAtLocation(node.expression), checker)?.name === "defineRouteContract";
 }
 function isRouteDecoratorCall(node, checker) {
+  if (node.arguments.length < 2)
+    return false;
   const name = node.expression.getText(node.getSourceFile());
   if (ts12.isIdentifier(node.expression) && ROUTE_DECORATORS2.has(node.expression.text))
     return true;
@@ -12232,7 +12470,7 @@ async function migrateProject(options) {
       const before = sourceByPath.get(absoluteFile);
       if (before === undefined)
         continue;
-      const result = projectResults?.results.get(absoluteFile) ?? migration.apply(before, file);
+      const result = projectResults ? projectResults.results.get(absoluteFile) ?? { changed: false, content: before, replacements: 0, issues: [] } : migration.apply(before, file);
       sourceByPath.set(absoluteFile, result.content);
       if (result.changed && result.issues.length === 0) {
         pendingWrites.set(absoluteFile, result.content);
@@ -12285,798 +12523,999 @@ async function migrateProject(options) {
     issues
   };
 }
-// src/inspect.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { dirname as dirname8, join as join7, relative as relative11, sep as sep10 } from "node:path";
-function formatGraph(graph) {
-  const lines = [];
-  for (const module of graph.modules) {
-    lines.push(`MODULE ${module.name}`);
-    lines.push(`  file: ${module.file}:${module.line}`);
-    lines.push(`  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`);
-    lines.push(`  providers: ${module.providers.length > 0 ? module.providers.map((p) => p.token).join(", ") : "-"}`);
-    lines.push(`  controllers: ${module.controllers.length > 0 ? module.controllers.map((c) => c.className).join(", ") : "-"}`);
-    lines.push(`  commands: ${module.commands.length > 0 ? module.commands.map((c) => c.name).join(", ") : "-"}`);
+// src/migration-assess.ts
+import { createHash as createHash9 } from "node:crypto";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join7, resolve as resolve14 } from "node:path";
+
+// src/openapi-tools.ts
+import { mkdir as mkdir4, readFile as readFile10, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
+import { dirname as dirname8, resolve as resolve13 } from "node:path";
+import { pathToFileURL } from "node:url";
+
+class OpenApiDocumentError extends Error {
+  code = "OPENAPI_DOCUMENT_INVALID";
+  constructor() {
+    super("OpenAPI document is invalid or could not be loaded.");
+    this.name = "OpenApiDocumentError";
   }
-  lines.push(`EXTERNAL TOKENS ${graph.externalTokens.length > 0 ? graph.externalTokens.join(", ") : "-"}`);
-  return lines.join(`
-`);
 }
-function explainGraph(graph, subject) {
-  const module = graph.modules.find((candidate) => candidate.name === subject);
-  if (module)
-    return explainModule(graph, module);
-  const provider = findProvider(graph, subject);
-  if (provider)
-    return explainProvider(graph, provider.module, provider.provider);
-  if (graph.externalTokens.includes(subject)) {
-    const references = graph.modules.flatMap((candidate) => [
-      ...candidate.providers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.token}`),
-      ...candidate.controllers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.className}`)
-    ]);
-    return [
-      `EXTERNAL TOKEN ${subject}`,
-      "  provided by: platform runtime",
-      `  references: ${references.length > 0 ? references.join(", ") : "-"}`
-    ].join(`
-`);
-  }
-  const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
-  throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+var COMPONENT_GROUPS = [
+  "schemas",
+  "responses",
+  "parameters",
+  "requestBodies",
+  "headers",
+  "securitySchemes"
+];
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function createContextPack(graph, subject) {
-  const subjectModule = graph.modules.find((module) => module.name === subject);
-  if (!subjectModule) {
-    throw new Error(`No module named "${subject}". Context packs require a module name.`);
+function stringValue(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function recordValue(value) {
+  return isRecord(value) ? value : undefined;
+}
+function arrayValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+function sortedKeys(value) {
+  return value ? Object.keys(value).sort() : [];
+}
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function decodeJsonPointerPart(value) {
+  return value.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveSchema(value, document, seen = new Set) {
+  const schema = recordValue(value);
+  if (!schema)
+    return;
+  const ref = stringValue(schema.$ref);
+  if (!ref || !ref.startsWith("#/components/schemas/"))
+    return schema;
+  if (seen.has(ref))
+    return schema;
+  const name = decodeJsonPointerPart(ref.slice("#/components/schemas/".length));
+  const components = recordValue(document.components);
+  const schemas = recordValue(components?.schemas);
+  const target = schemas?.[name];
+  if (target === undefined)
+    return schema;
+  return resolveSchema(target, document, new Set([...seen, ref]));
+}
+function schemaEnum(value) {
+  return Array.isArray(value?.enum) ? value.enum : undefined;
+}
+function schemaProperties(value) {
+  return recordValue(value?.properties);
+}
+function schemaRequired(value) {
+  return new Set(arrayValue(value?.required).filter((item) => typeof item === "string"));
+}
+function schemaType(value) {
+  return value?.type;
+}
+function addChange(changes, change) {
+  if (changes.some((item) => item.kind === change.kind && item.code === change.code && item.path === change.path && item.message === change.message))
+    return;
+  changes.push(change);
+}
+function compareSchema(baseValue, currentValue, baseDocument, currentDocument, path, direction, changes, seen = new Set) {
+  const baseSchema = resolveSchema(baseValue, baseDocument);
+  const currentSchema = resolveSchema(currentValue, currentDocument);
+  if (!baseSchema || !currentSchema)
+    return;
+  const pair = `${path}|${JSON.stringify(baseSchema)}|${JSON.stringify(currentSchema)}`;
+  if (seen.has(pair))
+    return;
+  seen.add(pair);
+  if (schemaType(baseSchema) !== undefined && schemaType(currentSchema) !== undefined && !sameJson(schemaType(baseSchema), schemaType(currentSchema))) {
+    addChange(changes, {
+      kind: "breaking",
+      code: "schema-type-changed",
+      path,
+      message: "The schema type changed."
+    });
   }
-  const byName = new Map(graph.modules.map((module) => [module.name, module]));
-  const selected = new Set([subjectModule.name]);
-  const reverseDependents = new Map;
-  for (const mod of graph.modules) {
-    for (const imp of mod.imports) {
-      const list = reverseDependents.get(imp);
-      if (list)
-        list.push(mod.name);
-      else
-        reverseDependents.set(imp, [mod.name]);
+  const baseEnum = schemaEnum(baseSchema);
+  const currentEnum = schemaEnum(currentSchema);
+  if (baseEnum && currentEnum) {
+    for (const value of baseEnum) {
+      if (!currentEnum.some((candidate) => sameJson(candidate, value))) {
+        addChange(changes, {
+          kind: "breaking",
+          code: "schema-enum-value-removed",
+          path,
+          message: "An enum value accepted by the previous contract was removed."
+        });
+        break;
+      }
     }
   }
-  for (const direction of ["imports", "dependents"]) {
-    const visited = new Set([subjectModule.name]);
-    const queue = [subjectModule.name];
-    let head = 0;
-    while (head < queue.length) {
-      const current = queue[head++];
-      if (!current)
-        continue;
-      const module = byName.get(current);
-      if (!module)
-        continue;
-      const neighbors = direction === "imports" ? module.imports : reverseDependents.get(module.name) ?? [];
-      for (const neighbor of neighbors) {
-        if (!visited.has(neighbor) && byName.has(neighbor)) {
-          visited.add(neighbor);
-          selected.add(neighbor);
-          queue.push(neighbor);
+  const baseProperties = schemaProperties(baseSchema);
+  const currentProperties = schemaProperties(currentSchema);
+  if (baseProperties && currentProperties) {
+    for (const name of sortedKeys(baseProperties)) {
+      if (currentProperties[name] === undefined) {
+        const inputRemovalIsBreaking = baseSchema.additionalProperties === false;
+        if (direction === "output" || inputRemovalIsBreaking) {
+          addChange(changes, {
+            kind: "breaking",
+            code: direction === "output" ? "response-property-removed" : "request-property-removed",
+            path: `${path}.properties.${name}`,
+            message: direction === "output" ? "A property returned by the previous contract was removed." : "A request property was removed while additional properties are rejected."
+          });
         }
+        continue;
       }
+      compareSchema(baseProperties[name], currentProperties[name], baseDocument, currentDocument, `${path}.properties.${name}`, direction, changes, seen);
     }
   }
-  const modules = graph.modules.filter((module) => selected.has(module.name));
-  const queryDocuments = graph.graphql?.documents.filter((file) => modules.some((module) => {
-    const path = relative11(dirname8(module.file), file);
-    return path !== ".." && !path.startsWith(`..${sep10}`);
-  })) ?? [];
-  const graphql = graph.graphql ? {
-    ...graph.graphql,
-    documents: queryDocuments,
-    operations: graph.graphql.operations.filter((operation) => queryDocuments.includes(operation.file))
-  } : undefined;
-  const files = [...new Set(modules.flatMap((module) => [
-    module.file,
-    ...module.providers.map((provider) => provider.file),
-    ...module.controllers.map((controller) => controller.file),
-    ...allAspects(module).flatMap((aspect) => aspect.file ? [aspect.file] : [])
-  ]).concat(graphql ? [graphql.schema, ...queryDocuments] : []))].sort();
-  const referencedTokens = new Set;
-  for (const module of modules) {
-    for (const provider of module.providers) {
-      for (const token of provider.deps)
-        referencedTokens.add(token);
+  const baseRequired = schemaRequired(baseSchema);
+  const currentRequired = schemaRequired(currentSchema);
+  if (direction === "input") {
+    for (const name of currentRequired) {
+      if (!baseRequired.has(name)) {
+        addChange(changes, {
+          kind: "breaking",
+          code: "request-property-required",
+          path: `${path}.required`,
+          message: `Request property '${name}' became required.`
+        });
+      }
     }
-    for (const controller of module.controllers) {
-      for (const token of controller.deps)
-        referencedTokens.add(token);
+    if (baseSchema.additionalProperties !== false && currentSchema.additionalProperties === false) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-additional-properties-rejected",
+        path,
+        message: "The request schema now rejects additional properties."
+      });
     }
-  }
-  return {
-    version: 1,
-    subject: subjectModule.name,
-    modules,
-    files,
-    externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
-    executionPlans: createExecutionPlans({ ...graph, modules }),
-    routeContracts: inspectRouteContracts({ ...graph, modules }),
-    ...graphql ? { graphql } : {},
-    diagnostics: (graph.diagnostics ?? []).filter((diagnostic) => diagnostic.file === undefined || files.includes(diagnostic.file)),
-    relatedModules: {
-      imports: subjectModule.imports.filter((name) => selected.has(name)),
-      importedBy: graph.modules.filter((module) => module.imports.includes(subjectModule.name)).map((module) => module.name).sort()
+  } else {
+    for (const name of baseRequired) {
+      if (!currentRequired.has(name)) {
+        addChange(changes, {
+          kind: "breaking",
+          code: "response-property-optional",
+          path: `${path}.required`,
+          message: `Response property '${name}' is no longer guaranteed.`
+        });
+      }
     }
-  };
-}
-function allAspects(module) {
-  return [
-    ...module.aspects ?? [],
-    ...module.controllers.flatMap((controller) => controller.routes.flatMap((route) => route.aspects ?? [])),
-    ...module.commands.flatMap((command) => command.aspects ?? []),
-    ...(module.jobs ?? []).flatMap((job) => job.aspects ?? [])
-  ];
+  }
 }
-function createExecutionPlans(graph) {
-  const aspects = (boundary, refs = []) => refs.map((ref, index) => `${boundary}.aspect[${index}]:${ref.name}`);
-  return graph.modules.flatMap((module) => [
-    ...module.controllers.flatMap((controller) => controller.routes.map((route) => {
-      const command = module.commands.find((item) => item.className === route.command);
-      const path = `${controller.path}/${route.path}`.replace(/\/+/g, "/");
-      return {
-        module: module.name,
-        kind: "route",
-        name: `${route.method} ${path.length > 1 ? path.replace(/\/+$/, "") : path}`,
-        ...command ? { command: command.name } : {},
-        stages: [
-          ...aspects(`module:${module.name}`, module.aspects),
-          ...aspects("route", route.aspects),
-          ...aspects("command", command?.aspects),
-          ...command ? [
-            "commandExecutor",
-            "authorize",
-            ...command.rpc ? [`rpc:${command.rpc}`] : [
-              ...command.idempotency === "required" ? ["idempotency"] : [],
-              ...command.transaction === "required" ? ["transaction"] : []
-            ]
-          ] : [],
-          "handler",
-          ...command?.audit && !command.rpc ? ["audit"] : []
-        ]
-      };
-    })),
-    ...module.commands.map((command) => ({
-      module: module.name,
-      kind: "command",
-      name: command.name,
-      command: command.name,
-      stages: [
-        "authorize",
-        ...command.rpc ? [`rpc:${command.rpc}`] : [
-          ...command.idempotency === "required" ? ["idempotency"] : [],
-          ...command.transaction === "required" ? ["transaction"] : []
-        ],
-        ...aspects(`module:${module.name}`, module.aspects),
-        ...aspects("command", command.aspects),
-        "handler",
-        ...command.audit && !command.rpc ? ["audit"] : []
-      ]
-    })),
-    ...(module.jobs ?? []).map((job) => ({
-      module: module.name,
-      kind: "job",
-      name: job.name,
-      stages: [...aspects(`module:${module.name}`, module.aspects), ...aspects("job", job.aspects), "jobExecutor", "handler"]
-    }))
-  ]);
+function parameterKey(value) {
+  const parameter = recordValue(value);
+  const name = stringValue(parameter?.name);
+  const location = stringValue(parameter?.in);
+  return name && location ? `${location}:${name}` : undefined;
 }
-function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
-  const checks = [
-    {
-      name: "project-root",
-      ok: existsSync4(rootDir),
-      detail: existsSync4(rootDir) ? rootDir : `missing: ${rootDir}`
-    },
-    {
-      name: "tsconfig",
-      ok: existsSync4(join7(rootDir, "tsconfig.json")),
-      detail: existsSync4(join7(rootDir, "tsconfig.json")) ? "tsconfig.json found" : "tsconfig.json missing"
-    },
-    {
-      name: "modules",
-      ok: graph.modules.length > 0,
-      detail: `${graph.modules.length} module(s) discovered`
-    },
-    {
-      name: "generated-artifacts",
-      ok: upToDate,
-      detail: upToDate ? "application.ts and app.manifest.json are up to date" : "generated artifacts are missing or stale"
+function operationParameters(pathItem, operation) {
+  const result = new Map;
+  for (const source of [pathItem.parameters, operation.parameters]) {
+    for (const item of arrayValue(source)) {
+      const parameter = recordValue(item);
+      const key = parameterKey(parameter);
+      if (parameter && key)
+        result.set(key, parameter);
     }
-  ];
-  const allDiagnostics = [...graph.diagnostics ?? [], ...diagnostics];
-  return {
-    checks,
-    diagnostics: allDiagnostics,
-    errors: allDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length + checks.filter((check) => !check.ok).length
-  };
-}
-function explainModule(graph, module) {
-  const dependents = graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
-  return [
-    `MODULE ${module.name}`,
-    `  file: ${module.file}:${module.line}`,
-    `  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`,
-    `  imported by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`,
-    `  providers: ${module.providers.length > 0 ? module.providers.map((provider) => provider.token).join(", ") : "-"}`,
-    `  controllers: ${module.controllers.length > 0 ? module.controllers.map((controller) => controller.className).join(", ") : "-"}`,
-    `  commands: ${module.commands.length > 0 ? module.commands.map((command) => command.name).join(", ") : "-"}`,
-    ...createExecutionPlans({ ...graph, modules: [module] }).map((plan) => `  execution ${plan.name}: ${plan.stages.join(" -> ")}`)
-  ].join(`
-`);
-}
-function explainProvider(graph, module, provider) {
-  const dependents = graph.modules.flatMap((candidate) => [
-    ...candidate.providers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.token}`),
-    ...candidate.controllers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.className}`)
-  ]);
-  return [
-    `PROVIDER ${provider.token}`,
-    `  module: ${module.name}`,
-    `  file: ${provider.file}:${provider.line}`,
-    `  kind: ${provider.kind}`,
-    `  scope: ${provider.scope}`,
-    `  exported: ${provider.exported ? "yes" : "no"}`,
-    `  deps: ${provider.deps.length > 0 ? provider.deps.join(", ") : "-"}`,
-    `  depended on by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`
-  ].join(`
-`);
-}
-function findProvider(graph, subject) {
-  for (const module of graph.modules) {
-    const provider = module.providers.find((candidate) => candidate.token === subject || candidate.useClass === subject || candidate.useFactoryName === subject);
-    if (provider)
-      return { module, provider };
   }
-  return;
+  return result;
 }
-function exportGraphMermaid(graph) {
-  const lines = ["graph TD"];
-  for (const mod of graph.modules) {
-    const safeId = mod.name.replace(/[^a-zA-Z0-9_]/g, "_");
-    lines.push(`  ${safeId}["${mod.className ?? mod.name}"]`);
-    for (const imp of mod.imports) {
-      const safeImp = imp.replace(/[^a-zA-Z0-9_]/g, "_");
-      lines.push(`  ${safeId} --> ${safeImp}`);
-    }
-  }
-  return lines.join(`
-`);
+function parameterSchema(value) {
+  return value.schema;
 }
-function exportGraphDot(graph) {
-  const lines = [
-    "digraph ApplicationGraph {",
-    "  rankdir=LR;",
-    '  node [shape=box, fontname="Helvetica"];'
-  ];
-  for (const mod of graph.modules) {
-    lines.push(`  "${mod.name}" [label="${mod.className ?? mod.name}"];`);
-    for (const imp of mod.imports) {
-      lines.push(`  "${mod.name}" -> "${imp}";`);
+function compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  const baseParameters = operationParameters(basePathItem, baseOperation);
+  const currentParameters = operationParameters(currentPathItem, currentOperation);
+  for (const key of [...baseParameters.keys()].sort()) {
+    const baseParameter = baseParameters.get(key);
+    const currentParameter = currentParameters.get(key);
+    if (!baseParameter || !currentParameter) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "parameter-removed",
+        path: `${path}.parameters.${key}`,
+        message: "A parameter from the previous contract was removed."
+      });
+      continue;
+    }
+    if (currentParameter.required === true && baseParameter.required !== true) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "parameter-required",
+        path: `${path}.parameters.${key}`,
+        message: "An optional parameter became required."
+      });
+    }
+    if (parameterSchema(baseParameter) !== undefined && parameterSchema(currentParameter) !== undefined) {
+      compareSchema(parameterSchema(baseParameter), parameterSchema(currentParameter), baseDocument, currentDocument, `${path}.parameters.${key}.schema`, "input", changes);
     }
   }
-  lines.push("}");
-  return lines.join(`
-`);
-}
-
-// src/index.ts
-init_generate();
-init_contract_manifest();
-
-// src/openapi-tools.ts
-import { mkdir as mkdir4, readFile as readFile10, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
-import { dirname as dirname9, resolve as resolve13 } from "node:path";
-import { pathToFileURL } from "node:url";
-
-class OpenApiDocumentError extends Error {
-  code = "OPENAPI_DOCUMENT_INVALID";
-  constructor() {
-    super("OpenAPI document is invalid or could not be loaded.");
-    this.name = "OpenApiDocumentError";
+  for (const key of [...currentParameters.keys()].sort()) {
+    if (baseParameters.has(key))
+      continue;
+    const parameter = currentParameters.get(key);
+    if (!parameter)
+      continue;
+    addChange(changes, {
+      kind: parameter.required === true ? "breaking" : "non-breaking",
+      code: parameter.required === true ? "parameter-required" : "parameter-added",
+      path: `${path}.parameters.${key}`,
+      message: parameter.required === true ? "A new required parameter was added." : "An optional parameter was added."
+    });
   }
 }
-var HTTP_METHODS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace"
-];
-var COMPONENT_GROUPS = [
-  "schemas",
-  "responses",
-  "parameters",
-  "requestBodies",
-  "headers",
-  "securitySchemes"
-];
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function stringValue(value) {
-  return typeof value === "string" ? value : undefined;
-}
-function recordValue(value) {
-  return isRecord(value) ? value : undefined;
-}
-function arrayValue(value) {
-  return Array.isArray(value) ? value : [];
-}
-function sortedKeys(value) {
-  return value ? Object.keys(value).sort() : [];
-}
-function sameJson(left, right) {
-  return JSON.stringify(left) === JSON.stringify(right);
-}
-function decodeJsonPointerPart(value) {
-  return value.replace(/~1/g, "/").replace(/~0/g, "~");
-}
-function resolveSchema(value, document, seen = new Set) {
-  const schema = recordValue(value);
-  if (!schema)
-    return;
-  const ref = stringValue(schema.$ref);
-  if (!ref || !ref.startsWith("#/components/schemas/"))
-    return schema;
-  if (seen.has(ref))
-    return schema;
-  const name = decodeJsonPointerPart(ref.slice("#/components/schemas/".length));
-  const components = recordValue(document.components);
-  const schemas = recordValue(components?.schemas);
-  const target = schemas?.[name];
-  if (target === undefined)
-    return schema;
-  return resolveSchema(target, document, new Set([...seen, ref]));
-}
-function schemaEnum(value) {
-  return Array.isArray(value?.enum) ? value.enum : undefined;
-}
-function schemaProperties(value) {
-  return recordValue(value?.properties);
-}
-function schemaRequired(value) {
-  return new Set(arrayValue(value?.required).filter((item) => typeof item === "string"));
-}
-function schemaType(value) {
-  return value?.type;
-}
-function addChange(changes, change) {
-  if (changes.some((item) => item.kind === change.kind && item.code === change.code && item.path === change.path && item.message === change.message))
-    return;
-  changes.push(change);
-}
-function compareSchema(baseValue, currentValue, baseDocument, currentDocument, path, direction, changes, seen = new Set) {
-  const baseSchema = resolveSchema(baseValue, baseDocument);
-  const currentSchema = resolveSchema(currentValue, currentDocument);
-  if (!baseSchema || !currentSchema)
-    return;
-  const pair = `${path}|${JSON.stringify(baseSchema)}|${JSON.stringify(currentSchema)}`;
-  if (seen.has(pair))
+function compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  const baseBody = recordValue(baseOperation.requestBody);
+  const currentBody = recordValue(currentOperation.requestBody);
+  if (!baseBody || !currentBody) {
+    if (baseBody && !currentBody) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-body-removed",
+        path: `${path}.requestBody`,
+        message: "A request body from the previous contract was removed."
+      });
+    } else if (!baseBody && currentBody?.required === true) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-body-required",
+        path: `${path}.requestBody`,
+        message: "A request body became required."
+      });
+    } else if (!baseBody && currentBody) {
+      addChange(changes, {
+        kind: "non-breaking",
+        code: "request-body-added",
+        path: `${path}.requestBody`,
+        message: "An optional request body was added."
+      });
+    }
     return;
-  seen.add(pair);
-  if (schemaType(baseSchema) !== undefined && schemaType(currentSchema) !== undefined && !sameJson(schemaType(baseSchema), schemaType(currentSchema))) {
+  }
+  if (currentBody.required === true && baseBody.required !== true) {
     addChange(changes, {
       kind: "breaking",
-      code: "schema-type-changed",
-      path,
-      message: "The schema type changed."
+      code: "request-body-required",
+      path: `${path}.requestBody`,
+      message: "An optional request body became required."
     });
   }
-  const baseEnum = schemaEnum(baseSchema);
-  const currentEnum = schemaEnum(currentSchema);
-  if (baseEnum && currentEnum) {
-    for (const value of baseEnum) {
-      if (!currentEnum.some((candidate) => sameJson(candidate, value))) {
-        addChange(changes, {
-          kind: "breaking",
-          code: "schema-enum-value-removed",
-          path,
-          message: "An enum value accepted by the previous contract was removed."
-        });
-        break;
-      }
+  const baseContent = recordValue(baseBody.content);
+  const currentContent = recordValue(currentBody.content);
+  for (const mediaType of sortedKeys(baseContent)) {
+    const baseMedia = recordValue(baseContent?.[mediaType]);
+    const currentMedia = recordValue(currentContent?.[mediaType]);
+    if (!baseMedia || !currentMedia) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-media-type-removed",
+        path: `${path}.requestBody.content.${mediaType}`,
+        message: "A request media type from the previous contract was removed."
+      });
+      continue;
     }
-  }
-  const baseProperties = schemaProperties(baseSchema);
-  const currentProperties = schemaProperties(currentSchema);
-  if (baseProperties && currentProperties) {
-    for (const name of sortedKeys(baseProperties)) {
-      if (currentProperties[name] === undefined) {
-        const inputRemovalIsBreaking = baseSchema.additionalProperties === false;
-        if (direction === "output" || inputRemovalIsBreaking) {
-          addChange(changes, {
-            kind: "breaking",
-            code: direction === "output" ? "response-property-removed" : "request-property-removed",
-            path: `${path}.properties.${name}`,
-            message: direction === "output" ? "A property returned by the previous contract was removed." : "A request property was removed while additional properties are rejected."
-          });
-        }
-        continue;
-      }
-      compareSchema(baseProperties[name], currentProperties[name], baseDocument, currentDocument, `${path}.properties.${name}`, direction, changes, seen);
+    if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
+      compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.requestBody.content.${mediaType}.schema`, "input", changes);
     }
   }
-  const baseRequired = schemaRequired(baseSchema);
-  const currentRequired = schemaRequired(currentSchema);
-  if (direction === "input") {
-    for (const name of currentRequired) {
-      if (!baseRequired.has(name)) {
+}
+function compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  const baseResponses = recordValue(baseOperation.responses);
+  const currentResponses = recordValue(currentOperation.responses);
+  for (const status of sortedKeys(baseResponses)) {
+    const baseResponse = recordValue(baseResponses?.[status]);
+    const currentResponse = recordValue(currentResponses?.[status]);
+    if (!baseResponse || !currentResponse) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "response-removed",
+        path: `${path}.responses.${status}`,
+        message: "A response status from the previous contract was removed."
+      });
+      continue;
+    }
+    const baseContent = recordValue(baseResponse.content);
+    const currentContent = recordValue(currentResponse.content);
+    for (const mediaType of sortedKeys(baseContent)) {
+      const baseMedia = recordValue(baseContent?.[mediaType]);
+      const currentMedia = recordValue(currentContent?.[mediaType]);
+      if (!baseMedia || !currentMedia) {
         addChange(changes, {
           kind: "breaking",
-          code: "request-property-required",
-          path: `${path}.required`,
-          message: `Request property '${name}' became required.`
+          code: "response-media-type-removed",
+          path: `${path}.responses.${status}.content.${mediaType}`,
+          message: "A response media type from the previous contract was removed."
         });
+        continue;
+      }
+      if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
+        compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.responses.${status}.content.${mediaType}.schema`, "output", changes);
       }
     }
-    if (baseSchema.additionalProperties !== false && currentSchema.additionalProperties === false) {
+  }
+  for (const status of sortedKeys(currentResponses)) {
+    if (baseResponses?.[status] !== undefined)
+      continue;
+    addChange(changes, {
+      kind: "non-breaking",
+      code: "response-added",
+      path: `${path}.responses.${status}`,
+      message: "A response status was added."
+    });
+  }
+}
+function compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
+  compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
+  compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
+  const baseSecurity = baseOperation.security;
+  const currentSecurity = currentOperation.security;
+  if (Array.isArray(currentSecurity) && currentSecurity.length > 0 && (!Array.isArray(baseSecurity) || baseSecurity.length === 0)) {
+    addChange(changes, {
+      kind: "breaking",
+      code: "security-requirement-added",
+      path: `${path}.security`,
+      message: "The operation now requires authentication or an additional security scheme."
+    });
+  }
+}
+function compareComponents(baseDocument, currentDocument, changes) {
+  const baseComponents = recordValue(baseDocument.components);
+  const currentComponents = recordValue(currentDocument.components);
+  for (const group of COMPONENT_GROUPS) {
+    const baseGroup = recordValue(baseComponents?.[group]);
+    const currentGroup = recordValue(currentComponents?.[group]);
+    for (const name of sortedKeys(baseGroup)) {
+      if (currentGroup?.[name] !== undefined)
+        continue;
       addChange(changes, {
         kind: "breaking",
-        code: "request-additional-properties-rejected",
-        path,
-        message: "The request schema now rejects additional properties."
+        code: "component-removed",
+        path: `components.${group}.${name}`,
+        message: "A reusable component from the previous contract was removed."
       });
     }
-  } else {
-    for (const name of baseRequired) {
-      if (!currentRequired.has(name)) {
-        addChange(changes, {
-          kind: "breaking",
-          code: "response-property-optional",
-          path: `${path}.required`,
-          message: `Response property '${name}' is no longer guaranteed.`
-        });
-      }
+    for (const name of sortedKeys(currentGroup)) {
+      if (baseGroup?.[name] !== undefined)
+        continue;
+      addChange(changes, {
+        kind: "non-breaking",
+        code: "component-added",
+        path: `components.${group}.${name}`,
+        message: "A reusable component was added."
+      });
     }
   }
 }
-function parameterKey(value) {
-  const parameter = recordValue(value);
-  const name = stringValue(parameter?.name);
-  const location = stringValue(parameter?.in);
-  return name && location ? `${location}:${name}` : undefined;
+function parseOpenApiDocument(value) {
+  if (!isRecord(value) || typeof value.openapi !== "string" || !/^3\.[0-9]+(?:\.[0-9]+)?$/.test(value.openapi) || !isRecord(value.info) || !isRecord(value.paths)) {
+    throw new OpenApiDocumentError;
+  }
+  return { ...value, openapi: value.openapi, info: value.info, paths: value.paths };
 }
-function operationParameters(pathItem, operation) {
-  const result = new Map;
-  for (const source of [pathItem.parameters, operation.parameters]) {
-    for (const item of arrayValue(source)) {
-      const parameter = recordValue(item);
-      const key = parameterKey(parameter);
-      if (parameter && key)
-        result.set(key, parameter);
-    }
+function serializeOpenApiJson(document, space = 2) {
+  const parsed = parseOpenApiDocument(document);
+  if (!Number.isInteger(space) || space < 0 || space > 10)
+    throw new OpenApiDocumentError;
+  const serialized = JSON.stringify(parsed, null, space);
+  if (serialized === undefined)
+    throw new OpenApiDocumentError;
+  return `${serialized}
+`;
+}
+async function readOpenApiJson(path) {
+  try {
+    const value = JSON.parse(await readFile10(resolve13(path), "utf8"));
+    return parseOpenApiDocument(value);
+  } catch (error) {
+    if (error instanceof OpenApiDocumentError)
+      throw error;
+    throw new OpenApiDocumentError;
   }
-  return result;
 }
-function parameterSchema(value) {
-  return value.schema;
+async function writeOpenApiJson(document, outputPath, space = 2) {
+  const path = resolve13(outputPath);
+  const content = serializeOpenApiJson(document, space);
+  await mkdir4(dirname8(path), { recursive: true });
+  try {
+    if (await readFile10(path, "utf8") === content)
+      return { path, written: false };
+  } catch {}
+  const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  try {
+    await writeFile5(temporaryPath, content, "utf8");
+    await rename6(temporaryPath, path);
+  } catch (error) {
+    await unlink3(temporaryPath).catch(() => {
+      return;
+    });
+    throw error;
+  }
+  return { path, written: true };
 }
-function compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  const baseParameters = operationParameters(basePathItem, baseOperation);
-  const currentParameters = operationParameters(currentPathItem, currentOperation);
-  for (const key of [...baseParameters.keys()].sort()) {
-    const baseParameter = baseParameters.get(key);
-    const currentParameter = currentParameters.get(key);
-    if (!baseParameter || !currentParameter) {
+async function loadGeneratedOpenApiDocument(modulePath) {
+  try {
+    const moduleUrl = pathToFileURL(resolve13(modulePath));
+    moduleUrl.searchParams.set("supacloud-openapi-export", "1");
+    const loaded = await import(moduleUrl.href);
+    if (!isRecord(loaded))
+      throw new OpenApiDocumentError;
+    return parseOpenApiDocument(loaded.OPENAPI_DOCUMENT);
+  } catch (error) {
+    if (error instanceof OpenApiDocumentError)
+      throw error;
+    throw new OpenApiDocumentError;
+  }
+}
+async function exportGeneratedOpenApiJson(options) {
+  const document = await loadGeneratedOpenApiDocument(options.modulePath);
+  return writeOpenApiJson(document, options.outputPath, options.space);
+}
+function diffOpenApiDocuments(baseValue, currentValue) {
+  const baseDocument = parseOpenApiDocument(baseValue);
+  const currentDocument = parseOpenApiDocument(currentValue);
+  const changes = [];
+  const basePaths = baseDocument.paths;
+  const currentPaths = currentDocument.paths;
+  for (const path of sortedKeys(basePaths)) {
+    const basePathItem = recordValue(basePaths[path]);
+    const currentPathItem = recordValue(currentPaths[path]);
+    if (!basePathItem || !currentPathItem) {
       addChange(changes, {
         kind: "breaking",
-        code: "parameter-removed",
-        path: `${path}.parameters.${key}`,
-        message: "A parameter from the previous contract was removed."
+        code: "path-removed",
+        path: `paths.${path}`,
+        message: "A path from the previous contract was removed."
       });
       continue;
     }
-    if (currentParameter.required === true && baseParameter.required !== true) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "parameter-required",
-        path: `${path}.parameters.${key}`,
-        message: "An optional parameter became required."
-      });
-    }
-    if (parameterSchema(baseParameter) !== undefined && parameterSchema(currentParameter) !== undefined) {
-      compareSchema(parameterSchema(baseParameter), parameterSchema(currentParameter), baseDocument, currentDocument, `${path}.parameters.${key}.schema`, "input", changes);
+    for (const method of HTTP_METHODS) {
+      const baseOperation = recordValue(basePathItem[method]);
+      const currentOperation = recordValue(currentPathItem[method]);
+      if (!baseOperation || !currentOperation) {
+        if (baseOperation) {
+          addChange(changes, {
+            kind: "breaking",
+            code: "operation-removed",
+            path: `paths.${path}.${method}`,
+            message: "An operation from the previous contract was removed."
+          });
+        } else if (currentOperation) {
+          addChange(changes, {
+            kind: "non-breaking",
+            code: "operation-added",
+            path: `paths.${path}.${method}`,
+            message: "An operation was added to an existing path."
+          });
+        }
+        continue;
+      }
+      compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, `paths.${path}.${method}`, changes);
     }
   }
-  for (const key of [...currentParameters.keys()].sort()) {
-    if (baseParameters.has(key))
-      continue;
-    const parameter = currentParameters.get(key);
-    if (!parameter)
+  for (const path of sortedKeys(currentPaths)) {
+    if (basePaths[path] !== undefined)
       continue;
     addChange(changes, {
-      kind: parameter.required === true ? "breaking" : "non-breaking",
-      code: parameter.required === true ? "parameter-required" : "parameter-added",
-      path: `${path}.parameters.${key}`,
-      message: parameter.required === true ? "A new required parameter was added." : "An optional parameter was added."
+      kind: "non-breaking",
+      code: "path-added",
+      path: `paths.${path}`,
+      message: "A path was added."
     });
   }
+  compareComponents(baseDocument, currentDocument, changes);
+  const breaking = changes.filter((change) => change.kind === "breaking");
+  return { ok: breaking.length === 0, breaking, changes };
 }
-function compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  const baseBody = recordValue(baseOperation.requestBody);
-  const currentBody = recordValue(currentOperation.requestBody);
-  if (!baseBody || !currentBody) {
-    if (baseBody && !currentBody) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "request-body-removed",
-        path: `${path}.requestBody`,
-        message: "A request body from the previous contract was removed."
-      });
-    } else if (!baseBody && currentBody?.required === true) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "request-body-required",
-        path: `${path}.requestBody`,
-        message: "A request body became required."
+function formatOpenApiDiff(result) {
+  if (result.changes.length === 0)
+    return "OpenAPI diff passed: no contract changes.";
+  return [
+    `OpenAPI diff ${result.ok ? "passed" : "failed"}: ${result.breaking.length} breaking change(s).`,
+    ...result.changes.map((change) => `${change.kind === "breaking" ? "BREAKING" : "NON-BREAKING"} ${change.code} at ${change.path}: ${change.message}`)
+  ].join(`
+`);
+}
+
+// src/migration-assess.ts
+var STATUS_PRIORITY = {
+  compatible: 0,
+  "needs-review": 1,
+  "not-proven": 2,
+  unsupported: 3,
+  breaking: 4
+};
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function arrayLength(value) {
+  return Array.isArray(value) ? value.length : undefined;
+}
+async function sha256(path) {
+  return createHash9("sha256").update(await readFile11(path)).digest("hex");
+}
+function overallStatus(findings) {
+  return findings.reduce((current, finding) => STATUS_PRIORITY[finding.status] > STATUS_PRIORITY[current] ? finding.status : current, "compatible");
+}
+async function assessMigration(options) {
+  const projectDir = resolve14(options.projectDir);
+  const compile = {
+    ...options.compile,
+    rootDir: resolve14(options.compile.rootDir),
+    outDir: resolve14(options.compile.outDir)
+  };
+  const findings = [];
+  const dependencyProblems = await checkMigrationDependencies(projectDir);
+  if (dependencyProblems.length > 0) {
+    findings.push({
+      code: "migration-dependency-tuple-not-proven",
+      status: "not-proven",
+      message: "The installed compiler migration dependency tuple is not the exact tested tuple.",
+      evidence: dependencyProblems.join("; "),
+      remediation: "Install the exact tested package versions before applying a source migration."
+    });
+  }
+  let compiler = {
+    upToDate: false,
+    diagnostics: [],
+    mismatches: []
+  };
+  try {
+    const checked = await checkProject(compile);
+    compiler = {
+      upToDate: checked.upToDate,
+      diagnostics: checked.diagnostics,
+      mismatches: checked.mismatches
+    };
+    const errors = checked.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0) {
+      findings.push({
+        code: "compiler-governance-not-proven",
+        status: "not-proven",
+        message: `Compiler governance has ${errors.length} error(s).`,
+        remediation: "Resolve compiler diagnostics without weakening governance, then reassess."
       });
-    } else if (!baseBody && currentBody) {
-      addChange(changes, {
-        kind: "non-breaking",
-        code: "request-body-added",
-        path: `${path}.requestBody`,
-        message: "An optional request body was added."
+    }
+    if (!checked.upToDate) {
+      findings.push({
+        code: "generated-artifact-drift",
+        status: "needs-review",
+        message: "Generated artifacts do not match the current source and compiler configuration.",
+        evidence: checked.mismatches.join("; "),
+        remediation: "Regenerate candidate artifacts in isolation and review the diff before adoption."
       });
     }
-    return;
+  } catch {
+    findings.push({
+      code: "compiler-check-unavailable",
+      status: "not-proven",
+      message: "The local compiler check could not complete.",
+      remediation: "Verify the project source, configuration and installed dependencies, then reassess."
+    });
   }
-  if (currentBody.required === true && baseBody.required !== true) {
-    addChange(changes, {
-      kind: "breaking",
-      code: "request-body-required",
-      path: `${path}.requestBody`,
-      message: "An optional request body became required."
+  const contractsManifestPath = join7(compile.outDir, "contracts.manifest.json");
+  let contractsManifest = {
+    path: contractsManifestPath,
+    present: false
+  };
+  try {
+    const parsed = JSON.parse(await readFile11(contractsManifestPath, "utf8"));
+    if (!isRecord2(parsed) || parsed.version !== 1)
+      throw new Error("invalid manifest");
+    contractsManifest = {
+      path: contractsManifestPath,
+      present: true,
+      sha256: await sha256(contractsManifestPath),
+      version: 1,
+      ...arrayLength(parsed.commands) === undefined ? {} : { commands: arrayLength(parsed.commands) },
+      ...arrayLength(parsed.routes) === undefined ? {} : { routes: arrayLength(parsed.routes) },
+      ...arrayLength(parsed.permissions) === undefined ? {} : { permissions: arrayLength(parsed.permissions) }
+    };
+  } catch {
+    findings.push({
+      code: "contract-manifest-not-proven",
+      status: "not-proven",
+      message: "contracts.manifest.json is missing or invalid.",
+      evidence: contractsManifestPath,
+      remediation: "Generate and review the contract manifest before migration."
     });
   }
-  const baseContent = recordValue(baseBody.content);
-  const currentContent = recordValue(currentBody.content);
-  for (const mediaType of sortedKeys(baseContent)) {
-    const baseMedia = recordValue(baseContent?.[mediaType]);
-    const currentMedia = recordValue(currentContent?.[mediaType]);
-    if (!baseMedia || !currentMedia) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "request-media-type-removed",
-        path: `${path}.requestBody.content.${mediaType}`,
-        message: "A request media type from the previous contract was removed."
+  let openApi;
+  if (options.baselineOpenApiPath && options.currentOpenApiPath) {
+    const baselinePath = resolve14(projectDir, options.baselineOpenApiPath);
+    const currentPath = resolve14(projectDir, options.currentOpenApiPath);
+    try {
+      const diff = diffOpenApiDocuments(await readOpenApiJson(baselinePath), await readOpenApiJson(currentPath));
+      openApi = {
+        baselinePath,
+        baselineSha256: await sha256(baselinePath),
+        currentPath,
+        currentSha256: await sha256(currentPath),
+        diff
+      };
+      if (!diff.ok) {
+        findings.push({
+          code: "openapi-breaking-change",
+          status: "breaking",
+          message: `OpenAPI contains ${diff.breaking.length} breaking change(s).`,
+          remediation: "Review and explicitly approve or redesign each breaking contract change."
+        });
+      } else if (diff.changes.length > 0) {
+        findings.push({
+          code: "openapi-compatible-change-review",
+          status: "needs-review",
+          message: `OpenAPI contains ${diff.changes.length} non-breaking change(s) requiring release review.`
+        });
+      }
+    } catch {
+      findings.push({
+        code: "openapi-diff-not-proven",
+        status: "not-proven",
+        message: "The OpenAPI baseline or current document could not be loaded.",
+        remediation: "Export both OpenAPI documents as JSON and rerun the assessment."
       });
-      continue;
-    }
-    if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
-      compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.requestBody.content.${mediaType}.schema`, "input", changes);
     }
+  } else {
+    findings.push({
+      code: "openapi-baseline-not-proven",
+      status: "not-proven",
+      message: "No complete OpenAPI baseline/current pair was supplied.",
+      remediation: "Provide both --baseline-openapi and --current-openapi for compatibility evidence."
+    });
   }
+  findings.push({
+    code: "rendering-mode-preserved",
+    status: "compatible",
+    message: "SupaCloud migration does not require SSR and does not change the existing rendering topology.",
+    evidence: `selected=${options.renderMode ?? "unspecified"}`
+  });
+  const status = overallStatus(findings);
+  return {
+    version: 1,
+    ok: status === "compatible" || status === "needs-review",
+    status,
+    readOnly: true,
+    writesPerformed: false,
+    rendering: {
+      selected: options.renderMode ?? "unspecified",
+      ssrRequired: false,
+      supportedModes: ["browser", "ssr", "edge", "trusted-server"],
+      guidance: "Keep the application's existing CSR, SPA, SSR or edge topology; use trusted adapters only for governed server operations."
+    },
+    dependencies: {
+      expected: migrationDependencies(),
+      problems: dependencyProblems
+    },
+    compiler,
+    artifacts: {
+      contractsManifest,
+      ...openApi === undefined ? {} : { openApi }
+    },
+    findings
+  };
 }
-function compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  const baseResponses = recordValue(baseOperation.responses);
-  const currentResponses = recordValue(currentOperation.responses);
-  for (const status of sortedKeys(baseResponses)) {
-    const baseResponse = recordValue(baseResponses?.[status]);
-    const currentResponse = recordValue(currentResponses?.[status]);
-    if (!baseResponse || !currentResponse) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "response-removed",
-        path: `${path}.responses.${status}`,
-        message: "A response status from the previous contract was removed."
-      });
-      continue;
+function formatMigrationAssessment(result) {
+  return [
+    `Migration assessment: ${result.status}. Read-only; no files, databases or remote environments were changed.`,
+    `Rendering: ${result.rendering.selected}; SSR required: no.`,
+    ...result.findings.map((finding) => `${finding.status.toUpperCase()} ${finding.code}: ${finding.message}`)
+  ].join(`
+`);
+}
+// src/inspect.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname9, join as join8, relative as relative11, sep as sep10 } from "node:path";
+function formatGraph(graph) {
+  const lines = [];
+  for (const module of graph.modules) {
+    lines.push(`MODULE ${module.name}`);
+    lines.push(`  file: ${module.file}:${module.line}`);
+    lines.push(`  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`);
+    lines.push(`  providers: ${module.providers.length > 0 ? module.providers.map((p) => p.token).join(", ") : "-"}`);
+    lines.push(`  controllers: ${module.controllers.length > 0 ? module.controllers.map((c) => c.className).join(", ") : "-"}`);
+    lines.push(`  commands: ${module.commands.length > 0 ? module.commands.map((c) => c.name).join(", ") : "-"}`);
+  }
+  lines.push(`EXTERNAL TOKENS ${graph.externalTokens.length > 0 ? graph.externalTokens.join(", ") : "-"}`);
+  return lines.join(`
+`);
+}
+function explainGraph(graph, subject) {
+  const module = graph.modules.find((candidate) => candidate.name === subject);
+  if (module)
+    return explainModule(graph, module);
+  const provider = findProvider(graph, subject);
+  if (provider)
+    return explainProvider(graph, provider.module, provider.provider);
+  if (graph.externalTokens.includes(subject)) {
+    const references = graph.modules.flatMap((candidate) => [
+      ...candidate.providers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.token}`),
+      ...candidate.controllers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.className}`)
+    ]);
+    return [
+      `EXTERNAL TOKEN ${subject}`,
+      "  provided by: platform runtime",
+      `  references: ${references.length > 0 ? references.join(", ") : "-"}`
+    ].join(`
+`);
+  }
+  const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
+  throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
+}
+function createContextPack(graph, subject) {
+  const subjectModule = resolveContextModule(graph, subject);
+  const byName = new Map(graph.modules.map((module) => [module.name, module]));
+  const selected = new Set([subjectModule.name]);
+  const reverseDependents = new Map;
+  for (const mod of graph.modules) {
+    for (const imp of mod.imports) {
+      const list = reverseDependents.get(imp);
+      if (list)
+        list.push(mod.name);
+      else
+        reverseDependents.set(imp, [mod.name]);
     }
-    const baseContent = recordValue(baseResponse.content);
-    const currentContent = recordValue(currentResponse.content);
-    for (const mediaType of sortedKeys(baseContent)) {
-      const baseMedia = recordValue(baseContent?.[mediaType]);
-      const currentMedia = recordValue(currentContent?.[mediaType]);
-      if (!baseMedia || !currentMedia) {
-        addChange(changes, {
-          kind: "breaking",
-          code: "response-media-type-removed",
-          path: `${path}.responses.${status}.content.${mediaType}`,
-          message: "A response media type from the previous contract was removed."
-        });
+  }
+  for (const direction of ["imports", "dependents"]) {
+    const visited = new Set([subjectModule.name]);
+    const queue = [subjectModule.name];
+    let head = 0;
+    while (head < queue.length) {
+      const current = queue[head++];
+      if (!current)
         continue;
-      }
-      if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
-        compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.responses.${status}.content.${mediaType}.schema`, "output", changes);
+      const module = byName.get(current);
+      if (!module)
+        continue;
+      const neighbors = direction === "imports" ? module.imports : reverseDependents.get(module.name) ?? [];
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor) && byName.has(neighbor)) {
+          visited.add(neighbor);
+          selected.add(neighbor);
+          queue.push(neighbor);
+        }
       }
     }
   }
-  for (const status of sortedKeys(currentResponses)) {
-    if (baseResponses?.[status] !== undefined)
-      continue;
-    addChange(changes, {
-      kind: "non-breaking",
-      code: "response-added",
-      path: `${path}.responses.${status}`,
-      message: "A response status was added."
-    });
+  const modules = graph.modules.filter((module) => selected.has(module.name));
+  const queryDocuments = graph.graphql?.documents.filter((file) => modules.some((module) => {
+    const path = relative11(dirname9(module.file), file);
+    return path !== ".." && !path.startsWith(`..${sep10}`);
+  })) ?? [];
+  const graphql = graph.graphql ? {
+    ...graph.graphql,
+    documents: queryDocuments,
+    operations: graph.graphql.operations.filter((operation) => queryDocuments.includes(operation.file))
+  } : undefined;
+  const files = [...new Set(modules.flatMap((module) => [
+    module.file,
+    ...module.providers.map((provider) => provider.file),
+    ...module.controllers.map((controller) => controller.file),
+    ...graph.moduleHandlerFiles?.[module.name] ?? [],
+    ...allAspects(module).flatMap((aspect) => aspect.file ? [aspect.file] : [])
+  ]).concat(graphql ? [graphql.schema, ...queryDocuments] : []))].sort();
+  const referencedTokens = new Set;
+  for (const module of modules) {
+    for (const provider of module.providers) {
+      for (const token of provider.deps)
+        referencedTokens.add(token);
+    }
+    for (const controller of module.controllers) {
+      for (const token of controller.deps)
+        referencedTokens.add(token);
+    }
   }
+  return {
+    version: 1,
+    subject: subjectModule.name,
+    modules,
+    files,
+    externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
+    executionPlans: createExecutionPlans({ ...graph, modules }),
+    routeContracts: inspectRouteContracts({ ...graph, modules }),
+    ...graphql ? { graphql } : {},
+    diagnostics: (graph.diagnostics ?? []).filter((diagnostic) => diagnostic.file === undefined || files.includes(diagnostic.file)),
+    relatedModules: {
+      imports: subjectModule.imports.filter((name) => selected.has(name)),
+      importedBy: graph.modules.filter((module) => module.imports.includes(subjectModule.name)).map((module) => module.name).sort()
+    }
+  };
 }
-function compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
-  compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
-  compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
-  const baseSecurity = baseOperation.security;
-  const currentSecurity = currentOperation.security;
-  if (Array.isArray(currentSecurity) && currentSecurity.length > 0 && (!Array.isArray(baseSecurity) || baseSecurity.length === 0)) {
-    addChange(changes, {
-      kind: "breaking",
-      code: "security-requirement-added",
-      path: `${path}.security`,
-      message: "The operation now requires authentication or an additional security scheme."
-    });
+function resolveContextModule(graph, subject) {
+  const exact = graph.modules.find((module) => module.name === subject);
+  if (exact)
+    return exact;
+  const matches = graph.modules.filter((module) => module.className === subject || module.providers.some((provider) => provider.token === subject || provider.useClass === subject) || module.controllers.some((controller) => controller.className === subject) || module.commands.some((command) => command.name === subject || command.className === subject) || (module.jobs ?? []).some((job) => job.name === subject || job.className === subject || job.serviceKey === subject) || module.queries.some((query) => query.name === subject || query.className === subject));
+  if (matches.length === 1)
+    return matches[0];
+  if (matches.length > 1) {
+    throw new Error(`Ambiguous context target "${subject}". Select a module name: ${matches.map((module) => module.name).sort().join(", ")}`);
   }
+  throw new Error(`No context target named "${subject}". Select a module name: ${graph.modules.map((module) => module.name).sort().join(", ") || "(none)"}`);
+}
+function allAspects(module) {
+  return [
+    ...module.aspects ?? [],
+    ...module.controllers.flatMap((controller) => controller.routes.flatMap((route) => route.aspects ?? [])),
+    ...module.commands.flatMap((command) => command.aspects ?? []),
+    ...(module.jobs ?? []).flatMap((job) => job.aspects ?? [])
+  ];
+}
+function createExecutionPlans(graph) {
+  const aspects = (boundary, refs = []) => refs.map((ref, index) => `${boundary}.aspect[${index}]:${ref.name}`);
+  return graph.modules.flatMap((module) => [
+    ...module.controllers.flatMap((controller) => controller.routes.map((route) => {
+      const command = module.commands.find((item) => item.className === route.command);
+      const path = `${controller.path}/${route.path}`.replace(/\/+/g, "/");
+      return {
+        module: module.name,
+        kind: "route",
+        name: `${route.method} ${path.length > 1 ? path.replace(/\/+$/, "") : path}`,
+        ...command ? { command: command.name } : {},
+        stages: [
+          ...aspects(`module:${module.name}`, module.aspects),
+          ...aspects("route", route.aspects),
+          ...aspects("command", command?.aspects),
+          ...command ? [
+            "commandExecutor",
+            "authorize",
+            ...command.rpc ? [`rpc:${command.rpc}`] : [
+              ...command.idempotency === "required" ? ["idempotency"] : [],
+              ...command.transaction === "required" ? ["transaction"] : []
+            ]
+          ] : [],
+          "handler",
+          ...command?.audit && !command.rpc ? ["audit"] : []
+        ]
+      };
+    })),
+    ...module.commands.map((command) => ({
+      module: module.name,
+      kind: "command",
+      name: command.name,
+      command: command.name,
+      stages: [
+        "authorize",
+        ...command.rpc ? [`rpc:${command.rpc}`] : [
+          ...command.idempotency === "required" ? ["idempotency"] : [],
+          ...command.transaction === "required" ? ["transaction"] : []
+        ],
+        ...aspects(`module:${module.name}`, module.aspects),
+        ...aspects("command", command.aspects),
+        "handler",
+        ...command.audit && !command.rpc ? ["audit"] : []
+      ]
+    })),
+    ...(module.jobs ?? []).map((job) => ({
+      module: module.name,
+      kind: "job",
+      name: job.name,
+      stages: [...aspects(`module:${module.name}`, module.aspects), ...aspects("job", job.aspects), "jobExecutor", "handler"]
+    }))
+  ]);
 }
-function compareComponents(baseDocument, currentDocument, changes) {
-  const baseComponents = recordValue(baseDocument.components);
-  const currentComponents = recordValue(currentDocument.components);
-  for (const group of COMPONENT_GROUPS) {
-    const baseGroup = recordValue(baseComponents?.[group]);
-    const currentGroup = recordValue(currentComponents?.[group]);
-    for (const name of sortedKeys(baseGroup)) {
-      if (currentGroup?.[name] !== undefined)
-        continue;
-      addChange(changes, {
-        kind: "breaking",
-        code: "component-removed",
-        path: `components.${group}.${name}`,
-        message: "A reusable component from the previous contract was removed."
-      });
-    }
-    for (const name of sortedKeys(currentGroup)) {
-      if (baseGroup?.[name] !== undefined)
-        continue;
-      addChange(changes, {
-        kind: "non-breaking",
-        code: "component-added",
-        path: `components.${group}.${name}`,
-        message: "A reusable component was added."
-      });
+function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
+  const checks = [
+    {
+      name: "project-root",
+      ok: existsSync4(rootDir),
+      detail: existsSync4(rootDir) ? rootDir : `missing: ${rootDir}`
+    },
+    {
+      name: "tsconfig",
+      ok: existsSync4(join8(rootDir, "tsconfig.json")),
+      detail: existsSync4(join8(rootDir, "tsconfig.json")) ? "tsconfig.json found" : "tsconfig.json missing"
+    },
+    {
+      name: "modules",
+      ok: graph.modules.length > 0,
+      detail: `${graph.modules.length} module(s) discovered`
+    },
+    {
+      name: "generated-artifacts",
+      ok: upToDate,
+      detail: upToDate ? "application.ts and app.manifest.json are up to date" : "generated artifacts are missing or stale"
     }
-  }
-}
-function parseOpenApiDocument(value) {
-  if (!isRecord(value) || typeof value.openapi !== "string" || !/^3\.[0-9]+(?:\.[0-9]+)?$/.test(value.openapi) || !isRecord(value.info) || !isRecord(value.paths)) {
-    throw new OpenApiDocumentError;
-  }
-  return { ...value, openapi: value.openapi, info: value.info, paths: value.paths };
+  ];
+  const allDiagnostics = [...graph.diagnostics ?? [], ...diagnostics];
+  return {
+    checks,
+    diagnostics: allDiagnostics,
+    errors: allDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length + checks.filter((check) => !check.ok).length
+  };
 }
-function serializeOpenApiJson(document, space = 2) {
-  const parsed = parseOpenApiDocument(document);
-  if (!Number.isInteger(space) || space < 0 || space > 10)
-    throw new OpenApiDocumentError;
-  const serialized = JSON.stringify(parsed, null, space);
-  if (serialized === undefined)
-    throw new OpenApiDocumentError;
-  return `${serialized}
-`;
+function explainModule(graph, module) {
+  const dependents = graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
+  return [
+    `MODULE ${module.name}`,
+    `  file: ${module.file}:${module.line}`,
+    `  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`,
+    `  imported by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`,
+    `  providers: ${module.providers.length > 0 ? module.providers.map((provider) => provider.token).join(", ") : "-"}`,
+    `  controllers: ${module.controllers.length > 0 ? module.controllers.map((controller) => controller.className).join(", ") : "-"}`,
+    `  commands: ${module.commands.length > 0 ? module.commands.map((command) => command.name).join(", ") : "-"}`,
+    ...createExecutionPlans({ ...graph, modules: [module] }).map((plan) => `  execution ${plan.name}: ${plan.stages.join(" -> ")}`)
+  ].join(`
+`);
 }
-async function readOpenApiJson(path) {
-  try {
-    const value = JSON.parse(await readFile10(resolve13(path), "utf8"));
-    return parseOpenApiDocument(value);
-  } catch (error) {
-    if (error instanceof OpenApiDocumentError)
-      throw error;
-    throw new OpenApiDocumentError;
-  }
+function explainProvider(graph, module, provider) {
+  const dependents = graph.modules.flatMap((candidate) => [
+    ...candidate.providers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.token}`),
+    ...candidate.controllers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.className}`)
+  ]);
+  return [
+    `PROVIDER ${provider.token}`,
+    `  module: ${module.name}`,
+    `  file: ${provider.file}:${provider.line}`,
+    `  kind: ${provider.kind}`,
+    `  scope: ${provider.scope}`,
+    `  exported: ${provider.exported ? "yes" : "no"}`,
+    `  deps: ${provider.deps.length > 0 ? provider.deps.join(", ") : "-"}`,
+    `  depended on by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`
+  ].join(`
+`);
 }
-async function writeOpenApiJson(document, outputPath, space = 2) {
-  const path = resolve13(outputPath);
-  const content = serializeOpenApiJson(document, space);
-  await mkdir4(dirname9(path), { recursive: true });
-  try {
-    if (await readFile10(path, "utf8") === content)
-      return { path, written: false };
-  } catch {}
-  const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-  try {
-    await writeFile5(temporaryPath, content, "utf8");
-    await rename6(temporaryPath, path);
-  } catch (error) {
-    await unlink3(temporaryPath).catch(() => {
-      return;
-    });
-    throw error;
+function findProvider(graph, subject) {
+  for (const module of graph.modules) {
+    const provider = module.providers.find((candidate) => candidate.token === subject || candidate.useClass === subject || candidate.useFactoryName === subject);
+    if (provider)
+      return { module, provider };
   }
-  return { path, written: true };
+  return;
 }
-async function loadGeneratedOpenApiDocument(modulePath) {
-  try {
-    const moduleUrl = pathToFileURL(resolve13(modulePath));
-    moduleUrl.searchParams.set("supacloud-openapi-export", "1");
-    const loaded = await import(moduleUrl.href);
-    if (!isRecord(loaded))
-      throw new OpenApiDocumentError;
-    return parseOpenApiDocument(loaded.OPENAPI_DOCUMENT);
-  } catch (error) {
-    if (error instanceof OpenApiDocumentError)
-      throw error;
-    throw new OpenApiDocumentError;
+function exportGraphMermaid(graph) {
+  const lines = ["graph TD"];
+  for (const mod of graph.modules) {
+    const safeId = mod.name.replace(/[^a-zA-Z0-9_]/g, "_");
+    lines.push(`  ${safeId}["${mod.className ?? mod.name}"]`);
+    for (const imp of mod.imports) {
+      const safeImp = imp.replace(/[^a-zA-Z0-9_]/g, "_");
+      lines.push(`  ${safeId} --> ${safeImp}`);
+    }
   }
+  return lines.join(`
+`);
 }
-async function exportGeneratedOpenApiJson(options) {
-  const document = await loadGeneratedOpenApiDocument(options.modulePath);
-  return writeOpenApiJson(document, options.outputPath, options.space);
-}
-function diffOpenApiDocuments(baseValue, currentValue) {
-  const baseDocument = parseOpenApiDocument(baseValue);
-  const currentDocument = parseOpenApiDocument(currentValue);
-  const changes = [];
-  const basePaths = baseDocument.paths;
-  const currentPaths = currentDocument.paths;
-  for (const path of sortedKeys(basePaths)) {
-    const basePathItem = recordValue(basePaths[path]);
-    const currentPathItem = recordValue(currentPaths[path]);
-    if (!basePathItem || !currentPathItem) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "path-removed",
-        path: `paths.${path}`,
-        message: "A path from the previous contract was removed."
-      });
-      continue;
-    }
-    for (const method of HTTP_METHODS) {
-      const baseOperation = recordValue(basePathItem[method]);
-      const currentOperation = recordValue(currentPathItem[method]);
-      if (!baseOperation || !currentOperation) {
-        if (baseOperation) {
-          addChange(changes, {
-            kind: "breaking",
-            code: "operation-removed",
-            path: `paths.${path}.${method}`,
-            message: "An operation from the previous contract was removed."
-          });
-        } else if (currentOperation) {
-          addChange(changes, {
-            kind: "non-breaking",
-            code: "operation-added",
-            path: `paths.${path}.${method}`,
-            message: "An operation was added to an existing path."
-          });
-        }
-        continue;
-      }
-      compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, `paths.${path}.${method}`, changes);
+function exportGraphDot(graph) {
+  const lines = [
+    "digraph ApplicationGraph {",
+    "  rankdir=LR;",
+    '  node [shape=box, fontname="Helvetica"];'
+  ];
+  for (const mod of graph.modules) {
+    lines.push(`  "${mod.name}" [label="${mod.className ?? mod.name}"];`);
+    for (const imp of mod.imports) {
+      lines.push(`  "${mod.name}" -> "${imp}";`);
     }
   }
-  for (const path of sortedKeys(currentPaths)) {
-    if (basePaths[path] !== undefined)
-      continue;
-    addChange(changes, {
-      kind: "non-breaking",
-      code: "path-added",
-      path: `paths.${path}`,
-      message: "A path was added."
-    });
-  }
-  compareComponents(baseDocument, currentDocument, changes);
-  const breaking = changes.filter((change) => change.kind === "breaking");
-  return { ok: breaking.length === 0, breaking, changes };
-}
-function formatOpenApiDiff(result) {
-  if (result.changes.length === 0)
-    return "OpenAPI diff passed: no contract changes.";
-  return [
-    `OpenAPI diff ${result.ok ? "passed" : "failed"}: ${result.breaking.length} breaking change(s).`,
-    ...result.changes.map((change) => `${change.kind === "breaking" ? "BREAKING" : "NON-BREAKING"} ${change.code} at ${change.path}: ${change.message}`)
-  ].join(`
+  lines.push("}");
+  return lines.join(`
 `);
 }
+
+// src/index.ts
+init_generate();
+init_contract_manifest();
+
 // src/config.ts
 init_graphql_options();
 import { existsSync as existsSync5 } from "node:fs";
-import { join as join8, resolve as resolve14 } from "node:path";
+import { join as join9, resolve as resolve15 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 var DEFAULT_SUPACLOUD_CONFIG = {
   graphql: false,
@@ -13169,8 +13608,8 @@ function validateGovernanceConfig(config) {
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
   return {
-    rootDir: resolve14(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
-    outDir: resolve14(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
+    rootDir: resolve15(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
+    outDir: resolve15(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
     include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
     strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
     requireRouteContracts: resolved.requireRouteContracts ?? DEFAULT_SUPACLOUD_CONFIG.requireRouteContracts,
@@ -13188,16 +13627,16 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders,
     graphql: resolved.graphql ? {
       ...resolved.graphql,
-      schema: resolve14(cwd, resolved.graphql.schema)
+      schema: resolve15(cwd, resolved.graphql.schema)
     } : undefined
   };
 }
 async function loadSupacloudConfig(cwd = process.cwd()) {
   const candidates = [
-    join8(cwd, "supacloud.config.ts"),
-    join8(cwd, "supacloud.config.mts"),
-    join8(cwd, "supacloud.config.js"),
-    join8(cwd, "supacloud.config.mjs")
+    join9(cwd, "supacloud.config.ts"),
+    join9(cwd, "supacloud.config.mts"),
+    join9(cwd, "supacloud.config.js"),
+    join9(cwd, "supacloud.config.mjs")
   ];
   const configPath = candidates.find((candidate) => existsSync5(candidate));
   if (!configPath)
@@ -13234,6 +13673,7 @@ export {
   TraitCompiler,
   analyzeProject,
   applyDiagnosticFix,
+  assessMigration,
   buildContractManifest,
   buildDeliveryProject,
   camelName,
@@ -13244,6 +13684,7 @@ export {
   createContextPack,
   createDeliveryPlan,
   createDependencyGraphCache,
+  createDiagnosticRepairPlan,
   createExecutionPlans,
   createIncrementalCompiler,
   createIncrementalProgramSession,
@@ -13256,6 +13697,7 @@ export {
   exportGraphMermaid,
   formatDeliveryPlan,
   formatGraph,
+  formatMigrationAssessment,
   formatOpenApiDiff,
   generateApplication,
   generateDatabaseContracts,