@supacloud/compiler 0.24.0 → 0.26.0

package/dist/cli.js

@@ -126,7 +126,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 }
         });
       }
     }
@@ -215,7 +220,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) {
@@ -232,7 +237,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) + ","),
     "  ];",
@@ -313,7 +324,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");
@@ -400,8 +413,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;
   }
@@ -416,7 +433,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;
     }
@@ -473,7 +490,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")) {
@@ -612,6 +629,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)}`);
         }
@@ -711,7 +732,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(`
@@ -808,7 +829,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(`
 `);
   }
@@ -909,6 +930,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)}`;
     }
@@ -926,13 +950,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)}`;
   }
 }
@@ -960,7 +985,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 = [];
@@ -1018,11 +1043,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 = [
@@ -1059,7 +1087,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)}`);
@@ -1093,7 +1123,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("")}
@@ -1124,6 +1154,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,",
@@ -1177,6 +1241,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)) {",
@@ -1363,6 +1434,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,",
@@ -1371,6 +1446,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,",
@@ -1379,6 +1455,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,",
@@ -1392,11 +1469,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,",
     "    };",
@@ -1415,21 +1493,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") {',
@@ -1440,20 +1524,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>;",
     "  }",
@@ -1510,11 +1598,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([
@@ -1547,6 +1639,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,
@@ -1630,6 +1724,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;",
     "};",
@@ -1827,8 +1923,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 {",
@@ -1858,7 +1961,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]);",
@@ -1895,6 +1998,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,",
@@ -1904,6 +2008,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 } : {}),",
     "    },",
     "  };",
@@ -1999,6 +2105,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;
@@ -2151,6 +2259,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>,
@@ -2697,12 +2811,12 @@ var init_graphql = __esm(() => {
 });
 
 // src/database-contracts.ts
-import { createHash as createHash9 } from "node:crypto";
-import { mkdir as mkdir5, readFile as readFile11 } from "node:fs/promises";
-import { dirname as dirname10, relative as relative12, resolve as resolve15 } from "node:path";
+import { createHash as createHash10 } from "node:crypto";
+import { mkdir as mkdir5, readFile as readFile12 } from "node:fs/promises";
+import { dirname as dirname10, relative as relative12, resolve as resolve16 } from "node:path";
 import * as ts13 from "@typescript/typescript6";
 function hash2(value) {
-  return createHash9("sha256").update(value).digest("hex");
+  return createHash10("sha256").update(value).digest("hex");
 }
 function importPath(out, path) {
   const value = relative12(out, path).replaceAll("\\", "/").replace(/\.(?:d\.)?[cm]?ts$/, "");
@@ -2727,19 +2841,19 @@ function parseDatabaseContractsOptions(value, directory) {
     throw new TypeError("migrations must be an ordered list of SQL files");
   }
   return {
-    rootDir: resolve15(directory, field("rootDir")),
-    outDir: resolve15(directory, field("outDir")),
-    postgrestTypes: resolve15(directory, field("postgrestTypes")),
-    drizzleSchema: resolve15(directory, field("drizzleSchema")),
+    rootDir: resolve16(directory, field("rootDir")),
+    outDir: resolve16(directory, field("outDir")),
+    postgrestTypes: resolve16(directory, field("postgrestTypes")),
+    drizzleSchema: resolve16(directory, field("drizzleSchema")),
     role: field("role"),
-    graphql: { ...graphql, schema: resolve15(directory, graphql.schema) },
-    migrations: migrations.map((file) => resolve15(directory, file))
+    graphql: { ...graphql, schema: resolve16(directory, graphql.schema) },
+    migrations: migrations.map((file) => resolve16(directory, file))
   };
 }
 async function generateDatabaseContracts(options, check = false) {
-  const rootDir = resolve15(options.rootDir), outDir = resolve15(options.outDir);
-  const postgrestTypes = resolve15(rootDir, options.postgrestTypes), drizzleSchema = resolve15(rootDir, options.drizzleSchema);
-  const snapshot = await readFile11(postgrestTypes, "utf8");
+  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 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)
@@ -2766,8 +2880,8 @@ async function generateDatabaseContracts(options, check = false) {
   }
   const inputs = {};
   const addInput = async (path) => {
-    const absolute = resolve15(rootDir, path);
-    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile11(absolute, "utf8"));
+    const absolute = resolve16(rootDir, path);
+    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile12(absolute, "utf8"));
   };
   await addInput(postgrestTypes);
   await addInput(drizzleSchema);
@@ -2783,8 +2897,8 @@ async function generateDatabaseContracts(options, check = false) {
     if (!source.isDeclarationFile && !source.fileName.includes("/node_modules/"))
       await addInput(source.fileName);
   }
-  await addInput(resolve15(rootDir, options.graphql.schema));
-  if (new Set(options.migrations.map((path) => resolve15(rootDir, path))).size !== options.migrations.length) {
+  await addInput(resolve16(rootDir, options.graphql.schema));
+  if (new Set(options.migrations.map((path) => resolve16(rootDir, path))).size !== options.migrations.length) {
     throw new Error("Duplicate migration in database contracts configuration");
   }
   for (const path of options.migrations)
@@ -2805,17 +2919,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, resolve15(rootDir, path)).replaceAll("\\", "/")),
+    migrationOrder: options.migrations.map((path) => relative12(rootDir, resolve16(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 = resolve15(outDir, file);
+    const path = resolve16(outDir, file);
     let current;
     try {
-      current = await readFile11(path, "utf8");
+      current = await readFile12(path, "utf8");
     } catch (error) {
       if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
         throw error;
@@ -2826,13 +2940,13 @@ async function generateDatabaseContracts(options, check = false) {
   if (!check) {
     await mkdir5(outDir, { recursive: true });
     for (const [file, content] of Object.entries(files))
-      await writeFileIfChanged(resolve15(outDir, file), content);
+      await writeFileIfChanged(resolve16(outDir, file), content);
   }
   return { upToDate: mismatches.length === 0, mismatches, written: check ? [] : mismatches, manifest };
 }
 async function runDatabaseContractsFile(path, check = false) {
-  const absolute = resolve15(path);
-  const value = JSON.parse(await readFile11(absolute, "utf8"));
+  const absolute = resolve16(path);
+  const value = JSON.parse(await readFile12(absolute, "utf8"));
   return generateDatabaseContracts(parseDatabaseContractsOptions(value, dirname10(absolute)), check);
 }
 var init_database_contracts = __esm(() => {
@@ -2842,9 +2956,9 @@ var init_database_contracts = __esm(() => {
 });
 
 // src/graphql-schema.ts
-import { mkdir as mkdir6, readFile as readFile12 } from "node:fs/promises";
-import { createHash as createHash10 } from "node:crypto";
-import { dirname as dirname11, resolve as resolve16 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile13 } from "node:fs/promises";
+import { createHash as createHash11 } from "node:crypto";
+import { dirname as dirname11, resolve as resolve17 } from "node:path";
 async function pullGraphqlSchema(options) {
   assertGraphqlOptions({ schema: options.output });
   const endpoint = new URL(options.url);
@@ -2884,7 +2998,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 = resolve16(options.output);
+  const path = resolve17(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.
@@ -2892,13 +3006,13 @@ async function pullGraphqlSchema(options) {
 `;
   let previous;
   try {
-    previous = await readFile12(path, "utf8");
+    previous = await readFile13(path, "utf8");
   } catch (error) {
     if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
       throw error;
   }
   const upToDate = previous === content;
-  const schemaHash = createHash10("sha256").update(content).digest("hex");
+  const schemaHash = createHash11("sha256").update(content).digest("hex");
   if (options.check)
     return { path, schemaHash, upToDate, written: false };
   await mkdir6(dirname11(path), { recursive: true });
@@ -2911,8 +3025,8 @@ var init_graphql_schema = __esm(() => {
 });
 
 // src/cli.ts
-import { resolve as resolve17 } from "node:path";
-import { readFile as readFile13 } from "node:fs/promises";
+import { resolve as resolve18 } from "node:path";
+import { readFile as readFile14 } from "node:fs/promises";
 
 // src/analyze.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -3613,6 +3727,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]) {
@@ -3748,7 +3863,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]}'.`);
@@ -3848,7 +3963,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,
@@ -4560,6 +4681,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;
@@ -4650,10 +4772,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);
       }
@@ -4673,6 +4796,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
@@ -4841,6 +4965,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     externalTokens,
     diagnostics: ctx.diagnostics.map(withDiagnosticMetadata),
     tokenNames,
+    moduleHandlerFiles: Object.fromEntries(ctx.moduleHandlerFiles),
     ...cache ? { cacheStats: { reusedModules, reanalyzedModules } } : {}
   };
 }
@@ -5053,6 +5178,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 = [];
@@ -5231,6 +5357,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;
@@ -5738,10 +5883,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 = [];
@@ -5892,6 +6040,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) {
@@ -7083,7 +7265,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);
@@ -7224,10 +7406,7 @@ function explainGraph(graph, subject) {
   throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
 }
 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.`);
-  }
+  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;
@@ -7275,6 +7454,7 @@ function createContextPack(graph, subject) {
     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;
@@ -7304,6 +7484,18 @@ function createContextPack(graph, subject) {
     }
   };
 }
+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 ?? [],
@@ -7611,6 +7803,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,
@@ -7745,6 +7939,16 @@ function findAffectedModules(previous, current, changedFiles) {
 
 // src/watch.ts
 var DEFAULT_DEBOUNCE_MS = 100;
+function isCompilerConfigurationPath(rootDir, changedPath) {
+  const relativePath = relative7(rootDir, changedPath).split(sep7).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 = resolve6(options.rootDir);
   const outDir = resolve6(options.outDir);
@@ -7837,7 +8041,7 @@ function watchProject(options) {
       const relativePath = relative7(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(relative7(rootDir, changedPath));
       }
     });
@@ -12295,9 +12499,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"
   };
@@ -12378,6 +12582,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;
@@ -12662,7 +12868,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);
@@ -12716,6 +12922,11 @@ async function migrateProject(options) {
   };
 }
 
+// src/migration-assess.ts
+import { createHash as createHash9 } from "node:crypto";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join9, resolve as resolve15 } 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 dirname9, resolve as resolve14 } from "node:path";
@@ -13221,10 +13432,199 @@ function formatOpenApiDiff(result) {
 `);
 }
 
+// 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 = resolve15(options.projectDir);
+  const compile = {
+    ...options.compile,
+    rootDir: resolve15(options.compile.rootDir),
+    outDir: resolve15(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."
+      });
+    }
+    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."
+      });
+    }
+  } 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."
+    });
+  }
+  const contractsManifestPath = join9(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."
+    });
+  }
+  let openApi;
+  if (options.baselineOpenApiPath && options.currentOpenApiPath) {
+    const baselinePath = resolve15(projectDir, options.baselineOpenApiPath);
+    const currentPath = resolve15(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."
+      });
+    }
+  } 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 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/cli.ts
 function isModuleBoundaryPresetName(value) {
   return value === "modular-monolith" || value === "feature-slices" || value === "vertical-slices" || value === "angular-enterprise" || value === "angular" || value === "clean-architecture" || value === "domain-driven";
 }
+function isMigrationRenderMode(value) {
+  return value === "unspecified" || value === "browser" || value === "ssr" || value === "edge" || value === "trusted-server";
+}
 function printUsage() {
   console.log(`
 @supacloud/compiler CLI
@@ -13235,9 +13635,10 @@ Usage:
   supacloud-compiler dev     [rootDir] [options]
   supacloud-compiler graph   [rootDir] [options]
   supacloud-compiler explain <name> [rootDir] [options]
-  supacloud-compiler context <module> [rootDir] [options]
+  supacloud-compiler context <name> [rootDir] [options]
   supacloud-compiler doctor  [rootDir] [options]
   supacloud-compiler migrate [rootDir] [options]
+  supacloud-compiler migration-assess [rootDir] [options]
   supacloud-compiler plan    [rootDir] [options]
   supacloud-compiler build-delivery [rootDir] [options]
   supacloud-compiler openapi-export <openapi-module> <output.json> [options]
@@ -13255,6 +13656,7 @@ Commands:
   context             Extract an AI-sized module context pack
   doctor              Run project and generated-artifact health checks
   migrate             Preview or apply versioned source migrations
+  migration-assess    Produce a read-only migration compatibility report
   plan                Preview deterministic workload targets without writing or deploying
   build-delivery      Build independent local factories and an atomic delivery manifest (Bun)
   openapi-export      Export a generated OpenAPI module to a standalone JSON document
@@ -13278,13 +13680,16 @@ Options:
   --token-env <name>  Environment variable holding the intended user's access token
   --check             graphql-schema: compare the remote schema without changing the snapshot
   --debounce <ms>     Debounce source changes in dev mode (default: 100)
-  --json              Print machine-readable output for compile/check/graph/explain/context/doctor/plan/build-delivery/openapi-export/openapi-diff
+  --json              Print machine-readable output for compile/check/graph/explain/context/doctor/migration-assess/plan/build-delivery/openapi-export/openapi-diff
   --space <n>         openapi-export: JSON indentation (0-10, default: 2)
   --delivery <file>   plan/build-delivery: validated JSON configuration (overrides config.delivery)
   --dry-run           Preview a fix without writing the target file
   --write             Apply a fix or migration to disk (preview-only by default)
   --from-version      Migration source-format checkpoint (requires --to-version)
   --to-version        Migration target checkpoint; verifies installed dependencies
+  --baseline-openapi  OpenAPI baseline JSON for migration-assess
+  --current-openapi   Current OpenAPI JSON for migration-assess
+  --render-mode       Optional browser | ssr | edge | trusted-server label; SSR is never required
   --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
   --help, -h          Show this help
 `);
@@ -13308,7 +13713,7 @@ async function run() {
       process.exitCode = 1;
     return;
   }
-  if (!command || !["compile", "check", "dev", "graph", "explain", "context", "doctor", "migrate", "fix", "graphql-schema", "plan", "build-delivery", "openapi-export", "openapi-diff"].includes(command)) {
+  if (!command || !["compile", "check", "dev", "graph", "explain", "context", "doctor", "migrate", "migration-assess", "fix", "graphql-schema", "plan", "build-delivery", "openapi-export", "openapi-diff"].includes(command)) {
     console.error(`Error: unknown command "${command}"`);
     printUsage();
     process.exit(1);
@@ -13332,6 +13737,9 @@ async function run() {
   let tokenEnv;
   let checkSchema = false;
   let deliveryPath;
+  let baselineOpenApi;
+  let currentOpenApi;
+  let renderMode = "unspecified";
   const openApiDiffPaths = [];
   const openApiExportPaths = [];
   let openApiExportSpace;
@@ -13436,9 +13844,27 @@ async function run() {
     } else if (arg === "--dry-run") {
       dryRun = true;
     } else if (arg === "--write") {
-      if (command === "plan")
-        throw new Error("plan is read-only; --write is not supported");
+      if (command === "plan" || command === "migration-assess")
+        throw new Error(`${command} is read-only; --write is not supported`);
       dryRun = false;
+    } else if (arg === "--baseline-openapi" || arg === "--current-openapi") {
+      if (command !== "migration-assess")
+        throw new Error(`${arg} is only supported by migration-assess`);
+      const value = args[++i];
+      if (!value || value.startsWith("-"))
+        throw new Error(`${arg} requires a JSON file path`);
+      if (arg === "--baseline-openapi")
+        baselineOpenApi = value;
+      else
+        currentOpenApi = value;
+    } else if (arg === "--render-mode") {
+      if (command !== "migration-assess")
+        throw new Error("--render-mode is only supported by migration-assess");
+      const value = args[++i];
+      if (!isMigrationRenderMode(value)) {
+        throw new Error("--render-mode requires browser, ssr, edge or trusted-server");
+      }
+      renderMode = value;
     } else if (arg === "--from-version" || arg === "--to-version") {
       if (command !== "migrate")
         throw new Error(`${arg} is only supported by migrate`);
@@ -13479,7 +13905,7 @@ async function run() {
     const currentPath = openApiDiffPaths[1];
     if (!basePath || !currentPath)
       throw new Error("openapi-diff requires two JSON file paths");
-    const result = diffOpenApiDocuments(await readOpenApiJson(resolve17(process.cwd(), basePath)), await readOpenApiJson(resolve17(process.cwd(), currentPath)));
+    const result = diffOpenApiDocuments(await readOpenApiJson(resolve18(process.cwd(), basePath)), await readOpenApiJson(resolve18(process.cwd(), currentPath)));
     console.log(json ? JSON.stringify(result, null, 2) : formatOpenApiDiff(result));
     if (!result.ok)
       process.exitCode = 1;
@@ -13494,8 +13920,8 @@ async function run() {
     if (!modulePath || !outputPath)
       throw new Error("openapi-export requires an OpenAPI module and output path");
     const result = await exportGeneratedOpenApiJson({
-      modulePath: resolve17(process.cwd(), modulePath),
-      outputPath: resolve17(process.cwd(), outputPath),
+      modulePath: resolve18(process.cwd(), modulePath),
+      outputPath: resolve18(process.cwd(), outputPath),
       ...openApiExportSpace === undefined ? {} : { space: openApiExportSpace }
     });
     console.log(json ? JSON.stringify({ ok: true, ...result }, null, 2) : result.written ? `OpenAPI JSON written: ${result.path}` : `OpenAPI JSON matches: ${result.path}`);
@@ -13503,7 +13929,7 @@ async function run() {
   }
   if (command === "migrate") {
     const result = await migrateProject({
-      rootDir: rootDir ? resolve17(process.cwd(), rootDir) : process.cwd(),
+      rootDir: rootDir ? resolve18(process.cwd(), rootDir) : process.cwd(),
       write: !dryRun,
       ...fromVersion === undefined ? {} : { fromVersion },
       ...toVersion === undefined ? {} : { toVersion }
@@ -13531,8 +13957,8 @@ async function run() {
   if (checkSchema && command !== "graphql-schema")
     throw new Error("--check is only supported by graphql-schema");
   const defaults = resolveSupacloudConfig(loadedConfig, process.cwd());
-  const resolvedRoot = rootDir ? resolve17(process.cwd(), rootDir) : defaults.rootDir;
-  const resolvedOut = outDir ? resolve17(process.cwd(), outDir) : defaults.outDir;
+  const resolvedRoot = rootDir ? resolve18(process.cwd(), rootDir) : defaults.rootDir;
+  const resolvedOut = outDir ? resolve18(process.cwd(), outDir) : defaults.outDir;
   const configured = compileOptionsFromConfig({
     ...loadedConfig,
     root: resolvedRoot,
@@ -13551,7 +13977,7 @@ async function run() {
     let delivery = loadedConfig.delivery;
     if (deliveryPath !== undefined) {
       try {
-        delivery = JSON.parse(await readFile13(resolve17(process.cwd(), deliveryPath), "utf8"));
+        delivery = JSON.parse(await readFile14(resolve18(process.cwd(), deliveryPath), "utf8"));
       } catch {
         throw new DeliveryConfigurationError;
       }
@@ -13595,10 +14021,21 @@ ${item.suggestion ?? ""}`).join(`
     console.log(json ? JSON.stringify({ ok: result.upToDate, ...result }, null, 2) : result.written ? `GraphQL schema written: ${result.path}` : result.upToDate ? `GraphQL schema matches: ${result.path}` : `GraphQL schema drift: ${result.path}. Export the role-scoped snapshot and compile before promotion.`);
     if (!result.upToDate)
       process.exit(1);
+  } else if (command === "migration-assess") {
+    const result = await assessMigration({
+      projectDir: process.cwd(),
+      compile: compileDefaults,
+      ...baselineOpenApi === undefined ? {} : { baselineOpenApiPath: baselineOpenApi },
+      ...currentOpenApi === undefined ? {} : { currentOpenApiPath: currentOpenApi },
+      renderMode
+    });
+    console.log(json ? JSON.stringify(result, null, 2) : formatMigrationAssessment(result));
+    if (result.status === "breaking" || result.status === "unsupported")
+      process.exitCode = 1;
   } else if (command === "fix") {
     if (!query)
       throw new Error("fix requires a JSON file containing one DiagnosticFix");
-    const fix = JSON.parse(await readFile13(resolve17(process.cwd(), query), "utf8"));
+    const fix = JSON.parse(await readFile14(resolve18(process.cwd(), query), "utf8"));
     const result = await applyDiagnosticFix(fix, { rootDir: resolvedRoot, dryRun });
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
   } else if (command === "compile") {
@@ -13713,7 +14150,7 @@ Source change detected; compiling...`);
     }
   } else if (command === "context") {
     if (!query) {
-      console.error("Error: context requires a module name");
+      console.error("Error: context requires a module or owned symbol name");
       process.exit(1);
     }
     try {