@supacloud/compiler 0.10.0 → 0.12.0

package/README.md

@@ -1,5 +1,10 @@
 # @supacloud/compiler
 
+FA-derived direct-command RPC ownership, contract inspection and POST command
+protocol migration are documented in `docs/fa-consumer-governance.md` in the
+repository. `context <module> --json` reports `routeContracts` and standalone
+command execution plans; these are declarations and obligations, not runtime proof.
+
 SupaCloud 应用静态编译器：读取 `@supacloud/app` 装饰器元数据的原生 TypeScript AST，构建 ApplicationGraph，做静态校验，并生成**无反射、无容器**的工厂代码与 manifest。
 
 本包不依赖 `@supacloud/app`：AST 只按装饰器名匹配（`Module`/`Injectable`/`Inject`/`Command`/`Query`/`Controller`/`Get`/`Post`/`Put`/`Patch`/`Delete`/`defineModule`/`InjectionToken`），不校验 import 来源。
@@ -185,6 +190,7 @@ IDE 和 AI agent 做状态机漂移检查。
 | `unsupported-provider-helper` | warn（strict 时 error） | functional provider 的动态参数无法安全展开为静态 factory |
 | `dynamic-aspect-reference` | error | aspects 不是显式数组字面量，或包含 spread/表达式/字符串 pointcut |
 | `invalid-aspect-reference` | error | aspect 不是可静态解析的函数声明、箭头函数或函数表达式 |
+| `invalid-command-mode` | error | transaction/idempotency 必须显式为 `"required"` 或 `"none"`，不允许拼写错误或动态值悄悄关闭治理（SC4012） |
 | `missing-deps` | warn（strict 时 error） | 构造/工厂依赖无法静态解析 |
 | `generated-any` | warn（strict 时 error） | 生成的 TypeScript 产物包含 `any` |
 | `source-any` | warn（strict 时 error） | 未被排除的生产源码包含显式 `any` |
@@ -238,6 +244,20 @@ supacloud-compiler context case --root ./app --json
 `supacloud-compiler fix ./fix.json --dry-run` 调用；CLI 默认预览，需显式
 使用 `--write` 才写盘。写盘前会重新解析 AST，
 前置条件不满足时拒绝修改，并通过临时文件原子替换。
+CLI 修复的 `targetFile` 相对于配置的源码根目录解析，也可以用 `--root` 显式指定；
+JSON 修复文件本身仍相对于当前工作目录读取。
+
+上下游分别沿单一方向遍历，不会经过共享基础模块再扩散到无关兄弟业务。
+上下文包还包含准确的切面源文件、校验诊断和 `executionPlans`；`explain <module>`
+也展示静态执行计划。计划描述标准命令治理；自定义 executor 的内部实现和短路行为
+仍需运行时追踪验证。成功审计在 handler 返回后执行，而非 handler 之前。
+
+例如 `@Command({ transaction: "requried" })` 会报告 `invalid-command-mode`，
+并输出 `set_command_mode` 修复建议。必须显式给 fix 的 `value` 选择 `"required"`
+或 `"none"` 才能预览或写入；不会推断较弱权限。若诊断后的源表达式变化，修复拒绝写盘。
+
+`compileProject()` 现在默认在存在 error 时保留已有产物。仅诊断/迁移工具可以显式
+设置 `writeOnError: true` 导出错误版本；这些产物不应被部署或视为可执行成功产物。
 
 ## 编译基准
 
@@ -257,6 +277,24 @@ bun test
 bun run build
 ```
 
+## Route Contract Policy
+
+Enable `requireRouteContracts: true` in `defineSupacloudConfig(...)` or
+`CompileOptions` to report `route-contract-required` errors in both compile and
+check (including JSON diagnostics). Changing this option invalidates incremental
+results. Combine it with `writeOnError: false` when programmatic compilation must
+not emit files on errors.
+
+`inspectRouteContracts(graph)` lists each route and its missing body, params,
+query, and response declarations. Required inputs are detected from handler
+bindings and controller/route path parameters. Responses always require an
+explicit declaration, including intentional void contracts.
+
+This checks declaration coverage only, not schema quality, handler/schema type
+equivalence, or database authorization. It deliberately does not auto-fix missing
+schemas with `unknown` placeholders. Consumers must define the actual contracts
+and test decoding separately. The policy defaults to false for existing projects.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -668,9 +668,10 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
             className: classInfo.decl.name?.text ?? name,
             name: stringLiteralProp(meta, "name") ?? classInfo.decl.name?.text ?? name,
             permission: stringLiteralProp(meta, "permission"),
-            transaction: commandModeProp(meta, "transaction") ?? "none",
+            rpc: checkedRpc(meta, ctx),
+            transaction: checkedCommandMode(meta, "transaction", ctx, classInfo.decl.name?.text ?? name) ?? "none",
             audit: stringLiteralProp(meta, "audit"),
-            idempotency: commandModeProp(meta, "idempotency") ?? "none",
+            idempotency: checkedCommandMode(meta, "idempotency", ctx, classInfo.decl.name?.text ?? name) ?? "none",
             standalone: true,
             aspects: parseAspectRefs(getProp(meta, "aspects"), ctx, `command ${classInfo.decl.name?.text ?? name}`)
           });
@@ -960,9 +961,10 @@ function parseModule(candidate, nameByNode, ctx) {
           className: cls.name?.text ?? "<anonymous>",
           name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
           permission: stringLiteralProp(meta, "permission"),
-          transaction: commandModeProp(meta, "transaction") ?? "none",
+          rpc: checkedRpc(meta, ctx),
+          transaction: checkedCommandMode(meta, "transaction", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
           audit: stringLiteralProp(meta, "audit"),
-          idempotency: commandModeProp(meta, "idempotency") ?? "none",
+          idempotency: checkedCommandMode(meta, "idempotency", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
           ...booleanProp(meta, "standalone") ? { standalone: true } : {},
           ...aspects2.length > 0 ? { aspects: aspects2 } : {}
         });
@@ -1092,6 +1094,31 @@ function commandModeProp(object, name) {
   const value = stringLiteralProp(object, name);
   return value === "required" || value === "none" ? value : undefined;
 }
+function checkedCommandMode(object, property, ctx, command) {
+  const expression = getProp(object, property);
+  const value = commandModeProp(object, property);
+  if (expression && value === undefined) {
+    const file = sourcePath(ctx.rootDir, expression.getSourceFile().fileName);
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-command-mode",
+      errorCode: "SC4012",
+      docsUrl: "https://supacloud.dev/errors/SC4012",
+      message: `${command}.${property} must be the explicit literal "required" or "none"; invalid governance cannot be disabled silently.`,
+      file,
+      line: lineOf(expression),
+      suggestion: `Choose the intended ${property} policy explicitly; use set_command_mode with value "required" or "none".`,
+      fix: {
+        type: "set_command_mode",
+        targetFile: file,
+        command,
+        property,
+        expectedExpression: nodeText(expression)
+      }
+    });
+  }
+  return value;
+}
 function parseProvider(el, exportsSet, ctx) {
   const file = sourcePath(ctx.rootDir, el.getSourceFile().fileName);
   const line = lineOf(el);
@@ -1552,6 +1579,10 @@ function parseController(input, ctx) {
         path: routePath,
         handler: propertyName(method.name)
       };
+      const signature = ctx.checker.getSignatureFromDeclaration(method);
+      const resultType = signature && ctx.checker.typeToString(signature.getReturnType());
+      if (resultType && /\bResponse\b/.test(resultType))
+        route.nativeResponse = true;
       const pathParams = [];
       const paramRegex = /:([a-zA-Z0-9_]+)/g;
       let match;
@@ -1700,6 +1731,23 @@ function parseController(input, ctx) {
       }
       const optionsArg = args[1];
       if (optionsArg && ts3.isObjectLiteralExpression(optionsArg)) {
+        const contract = getProp(optionsArg, "contract");
+        if (contract && ts3.isObjectLiteralExpression(contract)) {
+          route.contract = {};
+          for (const field of ["body", "response", "evidence"]) {
+            const value = stringLiteralProp(contract, field);
+            const allowed = field === "body" ? ["framework", "domain"] : field === "response" ? ["framework", "native-json", "binary", "stream"] : undefined;
+            if (getProp(contract, field) && (!value || allowed && !allowed.includes(value))) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-route-contract",
+                file,
+                message: `Invalid contract.${field} on ${route.handler}; use an explicit supported string literal.`
+              });
+            } else if (value)
+              Object.assign(route.contract, { [field]: value });
+          }
+        }
         for (const field of ["body", "params", "query", "response"]) {
           const schemaExpr = getProp(optionsArg, field);
           if (schemaExpr && ts3.isIdentifier(schemaExpr)) {
@@ -1707,6 +1755,11 @@ function parseController(input, ctx) {
             const importPath = importPathOf(schemaExpr, ctx);
             if (importPath)
               schemaImports[schemaExpr.text] = importPath;
+            const declaration = resolveDeclaration(schemaExpr, ctx)[0];
+            const typeName = ctx.checker.typeToString(ctx.checker.getTypeAtLocation(schemaExpr));
+            const initializer = declaration && ts3.isVariableDeclaration(declaration) ? declaration.initializer : undefined;
+            const opaque = /\bT(?:Unknown|Any)\b/.test(typeName) || initializer && ts3.isCallExpression(initializer) && ts3.isPropertyAccessExpression(initializer.expression) && ["Unknown", "Any"].includes(initializer.expression.name.text);
+            (route.schemaKinds ??= {})[field] = opaque ? "opaque" : "declared";
           }
         }
         const commandExpr = getProp(optionsArg, "command");
@@ -1801,6 +1854,23 @@ function parseController(input, ctx) {
     schemaImports: Object.keys(schemaImports).length > 0 ? schemaImports : undefined
   };
 }
+function checkedRpc(meta, ctx) {
+  const expression = getProp(meta, "rpc");
+  if (!expression)
+    return;
+  const value = stringLiteralProp(meta, "rpc");
+  if (value?.trim())
+    return value;
+  ctx.diagnostics.push({
+    severity: "error",
+    code: "invalid-command-rpc",
+    file: sourcePath(ctx.rootDir, meta.getSourceFile().fileName),
+    line: lineOf(meta),
+    message: "Command rpc must be a non-empty string literal identifying a configured adapter.",
+    suggestion: "Declare a named RPC adapter and its tested persistence capabilities."
+  });
+  return;
+}
 function classDeps(cls, ctx) {
   const injectable = parseInjectableOptions(cls, ctx);
   const ctor = cls.members.find(ts3.isConstructorDeclaration);
@@ -2156,6 +2226,7 @@ function parseAspectRefs(expression, ctx, owner) {
     const declaredFile = declaration.getSourceFile().fileName;
     const projectLocal = isProjectSourcePath(declaredFile, ctx.rootDir);
     refs.push({
+      ...projectLocal ? { file: sourcePath(ctx.rootDir, declaredFile) } : {},
       name,
       expression: element.text,
       importPath: projectLocal ? modulePath(ctx.rootDir, declaredFile) : undefined,
@@ -2298,6 +2369,7 @@ var INTERFACES = `export interface CompiledRoute {
 }
 
 export interface CompiledCommand {
+  rpc?: string;
   className: string;
   name: string;
   permission: string;
@@ -2823,6 +2895,7 @@ ${indent(item, 2)}`).join(",")}
         `transaction: ${JSON.stringify(command.transaction)}`,
         ...command.audit ? [`audit: ${JSON.stringify(command.audit)}`] : [],
         `idempotency: ${JSON.stringify(command.idempotency)}`,
+        ...command.rpc ? [`rpc: ${JSON.stringify(command.rpc)}`] : [],
         ...command.standalone ? ["standalone: true"] : [],
         ...command.aspects && command.aspects.length > 0 ? [`aspects: ${this.renderAspects(command.aspects)}`] : []
       ];
@@ -3690,6 +3763,10 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "invalid-job-scope": { code: "SC4007", docsUrl: "https://supacloud.dev/errors/SC4007" },
   "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
   "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
+  "invalid-command-mode": { code: "SC4012", docsUrl: "https://supacloud.dev/errors/SC4012" },
+  "invalid-command-rpc": { code: "SC4013", docsUrl: "https://supacloud.dev/errors/SC4013" },
+  "command-rpc-unavailable": { code: "SC4014", docsUrl: "https://supacloud.dev/errors/SC4014" },
+  "invalid-route-contract": { code: "SC3020", docsUrl: "https://supacloud.dev/errors/SC3020" },
   "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" },
   "invalid-feature-states": { code: "SC6001", docsUrl: "https://supacloud.dev/errors/SC6001" },
   "duplicate-feature-transition": { code: "SC6002", docsUrl: "https://supacloud.dev/errors/SC6002" },
@@ -4119,8 +4196,18 @@ function validateGraph(graph, options = false) {
           permission: `${module.name}.${command.name}`
         });
       }
+      if (command.rpc && (typeof options !== "object" || !Object.hasOwn(options.commandCapabilities?.rpc ?? {}, command.rpc))) {
+        error("command-rpc-unavailable", `Command ${command.name} requires configured RPC adapter '${command.rpc}'.`, module.file, module.line);
+      }
       if (typeof options === "object" && options.commandCapabilities) {
-        const caps = options.commandCapabilities;
+        const hostCaps = options.commandCapabilities;
+        const rpcCaps = command.rpc && Object.hasOwn(hostCaps.rpc ?? {}, command.rpc) ? hostCaps.rpc?.[command.rpc] : undefined;
+        const caps = command.rpc ? {
+          permission: hostCaps.permission,
+          audit: rpcCaps?.audit === true,
+          transaction: rpcCaps?.transaction === true,
+          idempotency: rpcCaps?.idempotency === true
+        } : hostCaps;
         const location = `${command.className} (${module.file})`;
         if (command.permission && caps.permission === false) {
           error("command-permission-unsupported", `Command ${command.name} declares permission, but runtime permission checks are unavailable (${location}).`, module.file, module.line);
@@ -4682,6 +4769,55 @@ function isAnyKeyword(node) {
   return node.kind === ts4.SyntaxKind.AnyKeyword;
 }
 
+// src/route-contracts.ts
+function inspectRouteContracts(graph) {
+  return graph.modules.flatMap((module) => module.controllers.flatMap((controller) => controller.routes.map((route) => {
+    const missing = [];
+    if ((route.hasBodyBinding || route.handlerParams?.some((param) => param.kind === "body")) && !route.body)
+      missing.push("body");
+    if ((route.pathParams?.length || route.paramBindings?.length || route.handlerParams?.some((param) => param.kind === "param") || /:[^/]+/.test(`${controller.path}/${route.path}`)) && !route.params)
+      missing.push("params");
+    if ((route.queryBindings?.length || route.handlerParams?.some((param) => param.kind === "query")) && !route.query)
+      missing.push("query");
+    if (!route.response && !["binary", "stream"].includes(route.contract?.response ?? ""))
+      missing.push("response");
+    const body = !route.body ? "missing" : route.contract?.body === "domain" ? "domain" : route.schemaKinds?.body === "opaque" ? "opaque" : "framework-declared";
+    const response = route.contract?.response ?? (route.nativeResponse ? "native-response-unclassified" : route.schemaKinds?.response === "opaque" ? "opaque" : !route.response ? "missing" : "framework-declared");
+    return {
+      module: module.name,
+      controller: controller.className,
+      handler: route.handler,
+      method: route.method,
+      path: `${controller.path}${route.path}`,
+      file: controller.file,
+      missing,
+      validation: {
+        body,
+        response,
+        schemas: route.schemaKinds ?? {},
+        evidence: route.contract?.evidence ?? null,
+        verified: false,
+        obligations: [
+          "Exercise actual HTTP request and response boundaries.",
+          ...response === "opaque" ? ["Decode the response's business fields; an opaque schema accepts unvalidated output."] : [],
+          ...body === "domain" || body === "opaque" ? ["Prove invalid input is rejected by the domain before writes."] : [],
+          ...response === "native-json" || response === "native-response-unclassified" ? ["Validate serialized JSON explicitly; native Response bypasses framework response schemas."] : [],
+          ...["binary", "stream"].includes(response) ? ["Test transport headers, access and bytes without JSON decoding."] : []
+        ]
+      }
+    };
+  })));
+}
+function validateRouteContracts(graph) {
+  return inspectRouteContracts(graph).filter((route) => route.missing.length).map((route) => ({
+    severity: "error",
+    code: "route-contract-required",
+    file: route.file,
+    message: `${route.controller}.${route.handler} (${route.method} ${route.path}) is missing contract declarations: ${route.missing.join(", ")}.`,
+    suggestion: "Declare the missing schemas and test actual request/response decoding. An opaque schema is not proof of validation."
+  }));
+}
+
 // src/compile.ts
 async function compileProject(options) {
   const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
@@ -4704,6 +4840,8 @@ async function compileProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -4736,7 +4874,7 @@ async function compileProject(options) {
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
     artifactHashes: options.cache?.generatedHashes
   };
-  const written = !hasErrors || options.writeOnError !== false ? await generateApplication(graph, generatedOptions) : [];
+  const written = !hasErrors || options.writeOnError === true ? await generateApplication(graph, generatedOptions) : [];
   const stats = graph.cacheStats ? {
     cacheHit: graph.cacheStats.reanalyzedModules.length === 0,
     changedFiles: [],
@@ -4767,6 +4905,8 @@ async function checkProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -4873,22 +5013,23 @@ function createContextPack(graph, subject) {
   }
   const byName = new Map(graph.modules.map((module) => [module.name, module]));
   const selected = new Set([subjectModule.name]);
-  const queue = [subjectModule.name];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (!current)
-      continue;
-    const module = byName.get(current);
-    if (!module)
-      continue;
-    const neighbors = [
-      ...module.imports,
-      ...graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name)
-    ];
-    for (const neighbor of neighbors) {
-      if (!selected.has(neighbor) && byName.has(neighbor)) {
-        selected.add(neighbor);
-        queue.push(neighbor);
+  for (const direction of ["imports", "dependents"]) {
+    const visited = new Set([subjectModule.name]);
+    const queue = [subjectModule.name];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (!current)
+        continue;
+      const module = byName.get(current);
+      if (!module)
+        continue;
+      const neighbors = direction === "imports" ? module.imports : graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor) && byName.has(neighbor)) {
+          visited.add(neighbor);
+          selected.add(neighbor);
+          queue.push(neighbor);
+        }
       }
     }
   }
@@ -4896,7 +5037,8 @@ function createContextPack(graph, subject) {
   const files = [...new Set(modules.flatMap((module) => [
     module.file,
     ...module.providers.map((provider) => provider.file),
-    ...module.controllers.map((controller) => controller.file)
+    ...module.controllers.map((controller) => controller.file),
+    ...allAspects(module).flatMap((aspect) => aspect.file ? [aspect.file] : [])
   ]))].sort();
   const referencedTokens = new Set;
   for (const module of modules) {
@@ -4915,12 +5057,76 @@ function createContextPack(graph, subject) {
     modules,
     files,
     externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
+    executionPlans: createExecutionPlans({ ...graph, modules }),
+    routeContracts: inspectRouteContracts({ ...graph, modules }),
+    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 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 doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
   const checks = [
     {
@@ -4960,7 +5166,8 @@ function explainModule(graph, module) {
     `  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(", ") : "-"}`
+    `  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(`
 `);
 }
@@ -5144,6 +5351,7 @@ function optionsKeyOf(options) {
     allowRouteCommandBindings: options.allowRouteCommandBindings,
     commandCapabilities: options.commandCapabilities,
     disallowControllerDirectDb: options.disallowControllerDirectDb,
+    requireRouteContracts: options.requireRouteContracts,
     detectOrphanModules: options.detectOrphanModules,
     generateClient: options.generateClient,
     generatePermissions: options.generatePermissions,
@@ -5399,6 +5607,7 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   outDir: "generated",
   include: ["**/*.module.ts", "**/*.ts"],
   strict: true,
+  requireRouteContracts: false,
   generateClient: true,
   generatePermissions: true,
   treeShakeUnusedProviders: true,
@@ -5418,6 +5627,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     outDir: resolve5(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,
     generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
     generatePermissions: resolved.generatePermissions ?? DEFAULT_SUPACLOUD_CONFIG.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset ?? DEFAULT_SUPACLOUD_CONFIG.moduleBoundaryPreset,
@@ -5445,6 +5655,7 @@ function compileOptionsFromConfig(config, cwd = process.cwd()) {
     outDir: resolved.outDir,
     include: resolved.include,
     strict: resolved.strict,
+    requireRouteContracts: resolved.requireRouteContracts,
     generateClient: resolved.generateClient,
     generatePermissions: resolved.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset,
@@ -5473,6 +5684,18 @@ async function applyDiagnosticFix(fix, options = {}) {
   let source = parse(file, original);
   let content;
   switch (fix.type) {
+    case "set_command_mode": {
+      if (fix.property !== "transaction" && fix.property !== "idempotency" || fix.value !== "required" && fix.value !== "none") {
+        throw new Error("Command mode fix requires an explicit property and policy value");
+      }
+      const object = decoratorObject(findClass(source, fix.command), "Command");
+      const current = property(object, fix.property);
+      if (!current || current.initializer.getText(source) !== fix.expectedExpression) {
+        throw new Error("Command mode changed since diagnosis; analyze the project again");
+      }
+      content = replaceProperty(source, object, fix.property, ts5.factory.createStringLiteral(fix.value));
+      break;
+    }
     case "add_module_import": {
       if (!fix.importPath || !fix.symbol)
         throw new Error("Module fix requires importPath and symbol");
@@ -5775,7 +5998,7 @@ async function run() {
     if (!query)
       throw new Error("fix requires a JSON file containing one DiagnosticFix");
     const fix = JSON.parse(await readFile3(resolve7(process.cwd(), query), "utf8"));
-    const result = await applyDiagnosticFix(fix, { rootDir: process.cwd(), dryRun });
+    const result = await applyDiagnosticFix(fix, { rootDir: resolvedRoot, dryRun });
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
   } else if (command === "compile") {
     const result = await compileProject(compileDefaults);
@@ -5893,8 +6116,8 @@ Source change detected; compiling...`);
       process.exit(1);
     }
     try {
-      const graph = await analyzeProject(resolvedRoot);
-      const pack = createContextPack(graph, query);
+      const result = await checkProject(compileDefaults);
+      const pack = createContextPack({ ...result.graph, diagnostics: result.diagnostics }, query);
       if (json) {
         console.log(JSON.stringify(pack, null, 2));
       } else {
@@ -5904,7 +6127,9 @@ Source change detected; compiling...`);
           `  files: ${pack.files.join(", ") || "-"}`,
           `  external tokens: ${pack.externalTokens.join(", ") || "-"}`,
           `  imports: ${pack.relatedModules.imports.join(", ") || "-"}`,
-          `  imported by: ${pack.relatedModules.importedBy.join(", ") || "-"}`
+          `  imported by: ${pack.relatedModules.importedBy.join(", ") || "-"}`,
+          ...pack.executionPlans.map((plan) => `  execution ${plan.name}: ${plan.stages.join(" -> ")}`),
+          ...pack.diagnostics.map((diagnostic) => `  ${diagnostic.code}: ${diagnostic.message}`)
         ].join(`
 `));
       }

package/dist/compile.d.ts

@@ -1,7 +1,7 @@
 import type { CheckProjectResult, CompileOptions, CompileResult } from "./types";
 /**
  * Complete compilation pipeline: AST analysis -> validation -> generate static factory code and manifest.
- * Files are emitted even when error-level diagnostics exist; caller decides adoption based on diagnostics.
+ * Errors preserve the last working artifacts unless writeOnError is explicitly enabled.
  */
 export declare function compileProject(options: CompileOptions): Promise<CompileResult>;
 /**

package/dist/config.d.ts

@@ -4,6 +4,7 @@ export interface SupaCloudConfig {
     outDir?: string;
     include?: string[];
     strict?: boolean;
+    requireRouteContracts?: boolean;
     generateClient?: boolean;
     generatePermissions?: boolean;
     moduleBoundaryPreset?: ModuleBoundaryPresetName;
@@ -20,6 +21,7 @@ export declare function resolveSupacloudConfig(config?: SupaCloudConfig, cwd?: s
     outDir: string;
     include: string[];
     strict: boolean;
+    requireRouteContracts: boolean;
     generateClient: boolean;
     generatePermissions: boolean;
     moduleBoundaryPreset: ModuleBoundaryPresetName;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { applyDiagnosticFix } from "./fixes";
 export type { AppliedDiagnosticFix, ApplyDiagnosticFixOptions } from "./fixes";
 export { checkProject, compileProject } from "./compile";
 export { watchProject } from "./watch";
-export { createContextPack, doctorProject, explainGraph, formatGraph, exportGraphDot, exportGraphMermaid, } from "./inspect";
+export { createContextPack, createExecutionPlans, doctorProject, explainGraph, formatGraph, exportGraphDot, exportGraphMermaid, } from "./inspect";
 export { createIncrementalCompiler } from "./incremental";
 export { createDependencyGraphCache } from "./incremental";
 export { ModuleDependencyGraph } from "./incremental";
@@ -15,7 +15,7 @@ export { TraitCompiler } from "./traits";
 export type { TraitCompilation, TraitHandler, TraitKind, TraitRecord } from "./traits";
 export { generateApplication, renderApplication } from "./generate";
 export type { GenerateOptions, RenderedArtifacts } from "./generate";
-export type { ContextPack, DoctorResult } from "./inspect";
+export type { ContextPack, DoctorResult, ExecutionPlan } from "./inspect";
 export { validateGraph, COMPILER_DIAGNOSTIC_CODES } from "./validate";
 export { scanGeneratedArtifacts, scanProductionSource } from "./type-safety";
 export type { TypeSafetyScanOptions } from "./type-safety";
@@ -24,3 +24,4 @@ export type { SupaCloudConfig } from "./config";
 export { camelName } from "./util";
 export { ANGULAR_ENTERPRISE_RULES, CLEAN_ARCHITECTURE_RULES, MODULAR_MONOLITH_RULES, MODULE_BOUNDARY_PROFILES, getModuleBoundaryPreset, getModuleBoundaryProfile, resolveModuleBoundaries, } from "./profiles";
 export type { ApplicationGraph, AspectRefNode, CachedModuleEntry, CheckProjectResult, CommandExecutionCapabilities, CommandNode, CompileOptions, CompileResult, CompileStats, ControllerNode, DependencyGraphCache, DependencyGraphIndex, Diagnostic, DiagnosticFix, ModuleBoundaryPresetName, ModuleBoundaryProfile, ModuleBoundaryRule, ModuleNode, JobNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, TypeSafetyOptions, ValidateOptions, WatchEvent, WatchHandle, WatchOptions, FeatureSpecNode, FeatureTransitionNode, } from "./types";
+export { inspectRouteContracts, validateRouteContracts } from "./route-contracts";

package/dist/index.js

@@ -662,9 +662,10 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
             className: classInfo.decl.name?.text ?? name,
             name: stringLiteralProp(meta, "name") ?? classInfo.decl.name?.text ?? name,
             permission: stringLiteralProp(meta, "permission"),
-            transaction: commandModeProp(meta, "transaction") ?? "none",
+            rpc: checkedRpc(meta, ctx),
+            transaction: checkedCommandMode(meta, "transaction", ctx, classInfo.decl.name?.text ?? name) ?? "none",
             audit: stringLiteralProp(meta, "audit"),
-            idempotency: commandModeProp(meta, "idempotency") ?? "none",
+            idempotency: checkedCommandMode(meta, "idempotency", ctx, classInfo.decl.name?.text ?? name) ?? "none",
             standalone: true,
             aspects: parseAspectRefs(getProp(meta, "aspects"), ctx, `command ${classInfo.decl.name?.text ?? name}`)
           });
@@ -954,9 +955,10 @@ function parseModule(candidate, nameByNode, ctx) {
           className: cls.name?.text ?? "<anonymous>",
           name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
           permission: stringLiteralProp(meta, "permission"),
-          transaction: commandModeProp(meta, "transaction") ?? "none",
+          rpc: checkedRpc(meta, ctx),
+          transaction: checkedCommandMode(meta, "transaction", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
           audit: stringLiteralProp(meta, "audit"),
-          idempotency: commandModeProp(meta, "idempotency") ?? "none",
+          idempotency: checkedCommandMode(meta, "idempotency", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
           ...booleanProp(meta, "standalone") ? { standalone: true } : {},
           ...aspects2.length > 0 ? { aspects: aspects2 } : {}
         });
@@ -1086,6 +1088,31 @@ function commandModeProp(object, name) {
   const value = stringLiteralProp(object, name);
   return value === "required" || value === "none" ? value : undefined;
 }
+function checkedCommandMode(object, property, ctx, command) {
+  const expression = getProp(object, property);
+  const value = commandModeProp(object, property);
+  if (expression && value === undefined) {
+    const file = sourcePath(ctx.rootDir, expression.getSourceFile().fileName);
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-command-mode",
+      errorCode: "SC4012",
+      docsUrl: "https://supacloud.dev/errors/SC4012",
+      message: `${command}.${property} must be the explicit literal "required" or "none"; invalid governance cannot be disabled silently.`,
+      file,
+      line: lineOf(expression),
+      suggestion: `Choose the intended ${property} policy explicitly; use set_command_mode with value "required" or "none".`,
+      fix: {
+        type: "set_command_mode",
+        targetFile: file,
+        command,
+        property,
+        expectedExpression: nodeText(expression)
+      }
+    });
+  }
+  return value;
+}
 function parseProvider(el, exportsSet, ctx) {
   const file = sourcePath(ctx.rootDir, el.getSourceFile().fileName);
   const line = lineOf(el);
@@ -1546,6 +1573,10 @@ function parseController(input, ctx) {
         path: routePath,
         handler: propertyName(method.name)
       };
+      const signature = ctx.checker.getSignatureFromDeclaration(method);
+      const resultType = signature && ctx.checker.typeToString(signature.getReturnType());
+      if (resultType && /\bResponse\b/.test(resultType))
+        route.nativeResponse = true;
       const pathParams = [];
       const paramRegex = /:([a-zA-Z0-9_]+)/g;
       let match;
@@ -1694,6 +1725,23 @@ function parseController(input, ctx) {
       }
       const optionsArg = args[1];
       if (optionsArg && ts3.isObjectLiteralExpression(optionsArg)) {
+        const contract = getProp(optionsArg, "contract");
+        if (contract && ts3.isObjectLiteralExpression(contract)) {
+          route.contract = {};
+          for (const field of ["body", "response", "evidence"]) {
+            const value = stringLiteralProp(contract, field);
+            const allowed = field === "body" ? ["framework", "domain"] : field === "response" ? ["framework", "native-json", "binary", "stream"] : undefined;
+            if (getProp(contract, field) && (!value || allowed && !allowed.includes(value))) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-route-contract",
+                file,
+                message: `Invalid contract.${field} on ${route.handler}; use an explicit supported string literal.`
+              });
+            } else if (value)
+              Object.assign(route.contract, { [field]: value });
+          }
+        }
         for (const field of ["body", "params", "query", "response"]) {
           const schemaExpr = getProp(optionsArg, field);
           if (schemaExpr && ts3.isIdentifier(schemaExpr)) {
@@ -1701,6 +1749,11 @@ function parseController(input, ctx) {
             const importPath = importPathOf(schemaExpr, ctx);
             if (importPath)
               schemaImports[schemaExpr.text] = importPath;
+            const declaration = resolveDeclaration(schemaExpr, ctx)[0];
+            const typeName = ctx.checker.typeToString(ctx.checker.getTypeAtLocation(schemaExpr));
+            const initializer = declaration && ts3.isVariableDeclaration(declaration) ? declaration.initializer : undefined;
+            const opaque = /\bT(?:Unknown|Any)\b/.test(typeName) || initializer && ts3.isCallExpression(initializer) && ts3.isPropertyAccessExpression(initializer.expression) && ["Unknown", "Any"].includes(initializer.expression.name.text);
+            (route.schemaKinds ??= {})[field] = opaque ? "opaque" : "declared";
           }
         }
         const commandExpr = getProp(optionsArg, "command");
@@ -1795,6 +1848,23 @@ function parseController(input, ctx) {
     schemaImports: Object.keys(schemaImports).length > 0 ? schemaImports : undefined
   };
 }
+function checkedRpc(meta, ctx) {
+  const expression = getProp(meta, "rpc");
+  if (!expression)
+    return;
+  const value = stringLiteralProp(meta, "rpc");
+  if (value?.trim())
+    return value;
+  ctx.diagnostics.push({
+    severity: "error",
+    code: "invalid-command-rpc",
+    file: sourcePath(ctx.rootDir, meta.getSourceFile().fileName),
+    line: lineOf(meta),
+    message: "Command rpc must be a non-empty string literal identifying a configured adapter.",
+    suggestion: "Declare a named RPC adapter and its tested persistence capabilities."
+  });
+  return;
+}
 function classDeps(cls, ctx) {
   const injectable = parseInjectableOptions(cls, ctx);
   const ctor = cls.members.find(ts3.isConstructorDeclaration);
@@ -2150,6 +2220,7 @@ function parseAspectRefs(expression, ctx, owner) {
     const declaredFile = declaration.getSourceFile().fileName;
     const projectLocal = isProjectSourcePath(declaredFile, ctx.rootDir);
     refs.push({
+      ...projectLocal ? { file: sourcePath(ctx.rootDir, declaredFile) } : {},
       name,
       expression: element.text,
       importPath: projectLocal ? modulePath(ctx.rootDir, declaredFile) : undefined,
@@ -2370,6 +2441,18 @@ async function applyDiagnosticFix(fix, options = {}) {
   let source = parse(file, original);
   let content;
   switch (fix.type) {
+    case "set_command_mode": {
+      if (fix.property !== "transaction" && fix.property !== "idempotency" || fix.value !== "required" && fix.value !== "none") {
+        throw new Error("Command mode fix requires an explicit property and policy value");
+      }
+      const object = decoratorObject(findClass(source, fix.command), "Command");
+      const current = property(object, fix.property);
+      if (!current || current.initializer.getText(source) !== fix.expectedExpression) {
+        throw new Error("Command mode changed since diagnosis; analyze the project again");
+      }
+      content = replaceProperty(source, object, fix.property, ts4.factory.createStringLiteral(fix.value));
+      break;
+    }
     case "add_module_import": {
       if (!fix.importPath || !fix.symbol)
         throw new Error("Module fix requires importPath and symbol");
@@ -2579,6 +2662,7 @@ var INTERFACES = `export interface CompiledRoute {
 }
 
 export interface CompiledCommand {
+  rpc?: string;
   className: string;
   name: string;
   permission: string;
@@ -3104,6 +3188,7 @@ ${indent(item, 2)}`).join(",")}
         `transaction: ${JSON.stringify(command.transaction)}`,
         ...command.audit ? [`audit: ${JSON.stringify(command.audit)}`] : [],
         `idempotency: ${JSON.stringify(command.idempotency)}`,
+        ...command.rpc ? [`rpc: ${JSON.stringify(command.rpc)}`] : [],
         ...command.standalone ? ["standalone: true"] : [],
         ...command.aspects && command.aspects.length > 0 ? [`aspects: ${this.renderAspects(command.aspects)}`] : []
       ];
@@ -3871,6 +3956,10 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "invalid-job-scope": { code: "SC4007", docsUrl: "https://supacloud.dev/errors/SC4007" },
   "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
   "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
+  "invalid-command-mode": { code: "SC4012", docsUrl: "https://supacloud.dev/errors/SC4012" },
+  "invalid-command-rpc": { code: "SC4013", docsUrl: "https://supacloud.dev/errors/SC4013" },
+  "command-rpc-unavailable": { code: "SC4014", docsUrl: "https://supacloud.dev/errors/SC4014" },
+  "invalid-route-contract": { code: "SC3020", docsUrl: "https://supacloud.dev/errors/SC3020" },
   "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" },
   "invalid-feature-states": { code: "SC6001", docsUrl: "https://supacloud.dev/errors/SC6001" },
   "duplicate-feature-transition": { code: "SC6002", docsUrl: "https://supacloud.dev/errors/SC6002" },
@@ -4300,8 +4389,18 @@ function validateGraph(graph, options = false) {
           permission: `${module.name}.${command.name}`
         });
       }
+      if (command.rpc && (typeof options !== "object" || !Object.hasOwn(options.commandCapabilities?.rpc ?? {}, command.rpc))) {
+        error("command-rpc-unavailable", `Command ${command.name} requires configured RPC adapter '${command.rpc}'.`, module.file, module.line);
+      }
       if (typeof options === "object" && options.commandCapabilities) {
-        const caps = options.commandCapabilities;
+        const hostCaps = options.commandCapabilities;
+        const rpcCaps = command.rpc && Object.hasOwn(hostCaps.rpc ?? {}, command.rpc) ? hostCaps.rpc?.[command.rpc] : undefined;
+        const caps = command.rpc ? {
+          permission: hostCaps.permission,
+          audit: rpcCaps?.audit === true,
+          transaction: rpcCaps?.transaction === true,
+          idempotency: rpcCaps?.idempotency === true
+        } : hostCaps;
         const location = `${command.className} (${module.file})`;
         if (command.permission && caps.permission === false) {
           error("command-permission-unsupported", `Command ${command.name} declares permission, but runtime permission checks are unavailable (${location}).`, module.file, module.line);
@@ -4863,6 +4962,55 @@ function isAnyKeyword(node) {
   return node.kind === ts5.SyntaxKind.AnyKeyword;
 }
 
+// src/route-contracts.ts
+function inspectRouteContracts(graph) {
+  return graph.modules.flatMap((module) => module.controllers.flatMap((controller) => controller.routes.map((route) => {
+    const missing = [];
+    if ((route.hasBodyBinding || route.handlerParams?.some((param) => param.kind === "body")) && !route.body)
+      missing.push("body");
+    if ((route.pathParams?.length || route.paramBindings?.length || route.handlerParams?.some((param) => param.kind === "param") || /:[^/]+/.test(`${controller.path}/${route.path}`)) && !route.params)
+      missing.push("params");
+    if ((route.queryBindings?.length || route.handlerParams?.some((param) => param.kind === "query")) && !route.query)
+      missing.push("query");
+    if (!route.response && !["binary", "stream"].includes(route.contract?.response ?? ""))
+      missing.push("response");
+    const body = !route.body ? "missing" : route.contract?.body === "domain" ? "domain" : route.schemaKinds?.body === "opaque" ? "opaque" : "framework-declared";
+    const response = route.contract?.response ?? (route.nativeResponse ? "native-response-unclassified" : route.schemaKinds?.response === "opaque" ? "opaque" : !route.response ? "missing" : "framework-declared");
+    return {
+      module: module.name,
+      controller: controller.className,
+      handler: route.handler,
+      method: route.method,
+      path: `${controller.path}${route.path}`,
+      file: controller.file,
+      missing,
+      validation: {
+        body,
+        response,
+        schemas: route.schemaKinds ?? {},
+        evidence: route.contract?.evidence ?? null,
+        verified: false,
+        obligations: [
+          "Exercise actual HTTP request and response boundaries.",
+          ...response === "opaque" ? ["Decode the response's business fields; an opaque schema accepts unvalidated output."] : [],
+          ...body === "domain" || body === "opaque" ? ["Prove invalid input is rejected by the domain before writes."] : [],
+          ...response === "native-json" || response === "native-response-unclassified" ? ["Validate serialized JSON explicitly; native Response bypasses framework response schemas."] : [],
+          ...["binary", "stream"].includes(response) ? ["Test transport headers, access and bytes without JSON decoding."] : []
+        ]
+      }
+    };
+  })));
+}
+function validateRouteContracts(graph) {
+  return inspectRouteContracts(graph).filter((route) => route.missing.length).map((route) => ({
+    severity: "error",
+    code: "route-contract-required",
+    file: route.file,
+    message: `${route.controller}.${route.handler} (${route.method} ${route.path}) is missing contract declarations: ${route.missing.join(", ")}.`,
+    suggestion: "Declare the missing schemas and test actual request/response decoding. An opaque schema is not proof of validation."
+  }));
+}
+
 // src/compile.ts
 async function compileProject(options) {
   const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
@@ -4885,6 +5033,8 @@ async function compileProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -4917,7 +5067,7 @@ async function compileProject(options) {
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
     artifactHashes: options.cache?.generatedHashes
   };
-  const written = !hasErrors || options.writeOnError !== false ? await generateApplication(graph, generatedOptions) : [];
+  const written = !hasErrors || options.writeOnError === true ? await generateApplication(graph, generatedOptions) : [];
   const stats = graph.cacheStats ? {
     cacheHit: graph.cacheStats.reanalyzedModules.length === 0,
     changedFiles: [],
@@ -4948,6 +5098,8 @@ async function checkProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -5132,6 +5284,7 @@ function optionsKeyOf(options) {
     allowRouteCommandBindings: options.allowRouteCommandBindings,
     commandCapabilities: options.commandCapabilities,
     disallowControllerDirectDb: options.disallowControllerDirectDb,
+    requireRouteContracts: options.requireRouteContracts,
     detectOrphanModules: options.detectOrphanModules,
     generateClient: options.generateClient,
     generatePermissions: options.generatePermissions,
@@ -5423,22 +5576,23 @@ function createContextPack(graph, subject) {
   }
   const byName = new Map(graph.modules.map((module) => [module.name, module]));
   const selected = new Set([subjectModule.name]);
-  const queue = [subjectModule.name];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (!current)
-      continue;
-    const module = byName.get(current);
-    if (!module)
-      continue;
-    const neighbors = [
-      ...module.imports,
-      ...graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name)
-    ];
-    for (const neighbor of neighbors) {
-      if (!selected.has(neighbor) && byName.has(neighbor)) {
-        selected.add(neighbor);
-        queue.push(neighbor);
+  for (const direction of ["imports", "dependents"]) {
+    const visited = new Set([subjectModule.name]);
+    const queue = [subjectModule.name];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (!current)
+        continue;
+      const module = byName.get(current);
+      if (!module)
+        continue;
+      const neighbors = direction === "imports" ? module.imports : graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor) && byName.has(neighbor)) {
+          visited.add(neighbor);
+          selected.add(neighbor);
+          queue.push(neighbor);
+        }
       }
     }
   }
@@ -5446,7 +5600,8 @@ function createContextPack(graph, subject) {
   const files = [...new Set(modules.flatMap((module) => [
     module.file,
     ...module.providers.map((provider) => provider.file),
-    ...module.controllers.map((controller) => controller.file)
+    ...module.controllers.map((controller) => controller.file),
+    ...allAspects(module).flatMap((aspect) => aspect.file ? [aspect.file] : [])
   ]))].sort();
   const referencedTokens = new Set;
   for (const module of modules) {
@@ -5465,12 +5620,76 @@ function createContextPack(graph, subject) {
     modules,
     files,
     externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
+    executionPlans: createExecutionPlans({ ...graph, modules }),
+    routeContracts: inspectRouteContracts({ ...graph, modules }),
+    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 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 doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
   const checks = [
     {
@@ -5510,7 +5729,8 @@ function explainModule(graph, module) {
     `  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(", ") : "-"}`
+    `  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(`
 `);
 }
@@ -5577,6 +5797,7 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   outDir: "generated",
   include: ["**/*.module.ts", "**/*.ts"],
   strict: true,
+  requireRouteContracts: false,
   generateClient: true,
   generatePermissions: true,
   treeShakeUnusedProviders: true,
@@ -5596,6 +5817,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     outDir: resolve6(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,
     generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
     generatePermissions: resolved.generatePermissions ?? DEFAULT_SUPACLOUD_CONFIG.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset ?? DEFAULT_SUPACLOUD_CONFIG.moduleBoundaryPreset,
@@ -5623,6 +5845,7 @@ function compileOptionsFromConfig(config, cwd = process.cwd()) {
     outDir: resolved.outDir,
     include: resolved.include,
     strict: resolved.strict,
+    requireRouteContracts: resolved.requireRouteContracts,
     generateClient: resolved.generateClient,
     generatePermissions: resolved.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset,
@@ -5648,6 +5871,7 @@ export {
   compileTraits,
   createContextPack,
   createDependencyGraphCache,
+  createExecutionPlans,
   createIncrementalCompiler,
   createIncrementalProgramSession,
   defineSupacloudConfig,
@@ -5660,6 +5884,7 @@ export {
   generateFeatureSource,
   getModuleBoundaryPreset,
   getModuleBoundaryProfile,
+  inspectRouteContracts,
   loadSupacloudConfig,
   renderApplication,
   resolveModuleBoundaries,
@@ -5668,5 +5893,6 @@ export {
   scanProductionSource,
   validateFeatureSpec,
   validateGraph,
+  validateRouteContracts,
   watchProject
 };

package/dist/inspect.d.ts

@@ -1,10 +1,22 @@
 import type { ApplicationGraph, Diagnostic, ModuleNode } from "./types";
+import { inspectRouteContracts } from "./route-contracts";
+export interface ExecutionPlan {
+    module: string;
+    kind: "route" | "command" | "job";
+    name: string;
+    command?: string;
+    /** Standard governance contract. Audit success follows the handler; custom executors may short-circuit. */
+    stages: string[];
+}
 export interface ContextPack {
     version: 1;
     subject: string;
     modules: ModuleNode[];
     files: string[];
     externalTokens: string[];
+    executionPlans: ExecutionPlan[];
+    routeContracts: ReturnType<typeof inspectRouteContracts>;
+    diagnostics: Diagnostic[];
     relatedModules: {
         importedBy: string[];
         imports: string[];
@@ -26,6 +38,8 @@ export declare function explainGraph(graph: ApplicationGraph, subject: string):
  * editing one feature: the subject module, its imports, and its dependents.
  */
 export declare function createContextPack(graph: ApplicationGraph, subject: string): ContextPack;
+/** Static plan, not runtime discovery; custom executors remain explicit boundaries. */
+export declare function createExecutionPlans(graph: ApplicationGraph): ExecutionPlan[];
 export declare function doctorProject(rootDir: string, outDir: string, graph: ApplicationGraph, upToDate: boolean, diagnostics?: Diagnostic[]): DoctorResult;
 /**
  * Exports the application module architecture as a Mermaid graph diagram.

package/dist/route-contracts.d.ts

@@ -0,0 +1,20 @@
+import type { ApplicationGraph, Diagnostic } from "./types";
+/** Declaration coverage only; runtime decoding and database behavior require separate tests. */
+export declare function inspectRouteContracts(graph: ApplicationGraph): {
+    module: string;
+    controller: string;
+    handler: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    path: string;
+    file: string;
+    missing: ("query" | "body" | "params" | "response")[];
+    validation: {
+        body: string;
+        response: string;
+        schemas: Partial<Record<"query" | "body" | "params" | "response", "opaque" | "declared">>;
+        evidence: string | null;
+        verified: false;
+        obligations: string[];
+    };
+}[];
+export declare function validateRouteContracts(graph: ApplicationGraph): Diagnostic[];

package/dist/types.d.ts

@@ -21,6 +21,8 @@ export interface FunctionalInjectNode {
     host?: boolean;
 }
 export interface AspectRefNode {
+    /** Exact project-local source path for context packs. */
+    file?: string;
     /** Exported symbol name used in the generated static import. */
     name: string;
     /** Source expression retained for diagnostics and manifest inspection. */
@@ -50,6 +52,14 @@ export interface Diagnostic {
  * than raw text offsets so fixes remain valid after unrelated edits.
  */
 export type DiagnosticFix = {
+    type: "set_command_mode";
+    targetFile: string;
+    command: string;
+    property: "transaction" | "idempotency";
+    expectedExpression: string;
+    /** Must be selected by the caller; never infer weaker governance. */
+    value?: "required" | "none";
+} | {
     type: "add_module_import";
     targetFile: string;
     module: string;
@@ -136,6 +146,13 @@ export interface HandlerParamNode {
     default?: unknown;
 }
 export interface RouteNode {
+    contract?: {
+        body?: "framework" | "domain";
+        response?: "framework" | "native-json" | "binary" | "stream";
+        evidence?: string;
+    };
+    schemaKinds?: Partial<Record<"body" | "params" | "query" | "response", "opaque" | "declared">>;
+    nativeResponse?: boolean;
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     path: string;
     handler: string;
@@ -206,6 +223,7 @@ export interface ControllerNode {
     schemaImports?: Record<string, string>;
 }
 export interface CommandNode {
+    rpc?: string;
     className: string;
     name: string;
     permission?: string;
@@ -290,6 +308,8 @@ export interface ApplicationGraph {
     };
 }
 export interface CompileOptions {
+    /** Require schemas for bound route inputs and responses. Does not prove runtime validation. */
+    requireRouteContracts?: boolean;
     /** Project root directory (containing tsconfig). */
     rootDir: string;
     /** Glob patterns, defaults to ['**\/*.module.ts', '**\/*.ts']. */
@@ -310,7 +330,7 @@ export interface CompileOptions {
     disallowControllerDirectDb?: boolean;
     /** Detect modules declared in the project that are unreachable from any root module. */
     detectOrphanModules?: boolean;
-    /** Write generated artifacts even when error-level diagnostics exist (default: true). */
+    /** Explicit unsafe opt-in to emit artifacts with errors (default: false). */
     writeOnError?: boolean;
     /** Generate typed API client in client.ts (default: false). */
     generateClient?: boolean;
@@ -366,6 +386,12 @@ export interface ValidateOptions {
 }
 /** Runtime capabilities declared by the Command executor. */
 export interface CommandExecutionCapabilities {
+    /** Explicit named adapters; declarations must also be tested against the database. */
+    rpc?: Record<string, {
+        audit?: boolean;
+        idempotency?: boolean;
+        transaction?: boolean;
+    }>;
     /** Whether runtime permission checks are supported. */
     permission?: boolean;
     /** Whether runtime audit persistence is supported. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",