@supacloud/compiler 0.40.1 → 0.41.0

package/README.md

@@ -8,6 +8,13 @@ response unions, caller decoders, binary/stream routes and GraphQL stay intact.
 These errors do not prove write rollback and do not add automatic retries.
 See [typed clients and recovery](../../docs/framework-composition.md).
 
+For Elysia routes, the compiler governs Effect contracts by default:
+`effect.dependencies` documents the runtime environment, `effect.errors`
+documents safe HTTP mappings, and `effect.retry` requires explicit bounded
+attempts. The default policy requires `requireRouteEffects`,
+`requireErrorMappings` and `requireDependencies`. See
+[Effect governance](../../docs/effect-governance.md).
+
 ## Unified Database Contracts
 
 `supacloud-compiler database-contracts database-contracts.json` generates a shared
@@ -320,6 +327,7 @@ bunx supacloud-compiler dev
 | OpenAPI 3.1 module | 开启 |
 | permissions manifest | 开启 |
 | module boundary preset | `modular-monolith` |
+| Effect route governance | 三项严格检查均开启 |
 | provider tree-shaking | 开启 |
 
 需要覆盖默认值时，在项目根目录添加 `supacloud.config.ts`：

package/dist/cli.js

@@ -1237,6 +1237,17 @@ var init_validate = __esm(() => {
     "route-contract-required": { code: "SC3021", docsUrl: "https://supacloud.dev/errors/SC3021" },
     "route-contract-unverified": { code: "SC3022", docsUrl: "https://supacloud.dev/errors/SC3022" },
     "route-contract-evidence-required": { code: "SC3023", docsUrl: "https://supacloud.dev/errors/SC3023" },
+    "invalid-effect-contract": { code: "SC3030", docsUrl: "https://supacloud.dev/errors/SC3030" },
+    "invalid-effect-retry": { code: "SC3031", docsUrl: "https://supacloud.dev/errors/SC3031" },
+    "invalid-effect-timeout": { code: "SC3032", docsUrl: "https://supacloud.dev/errors/SC3032" },
+    "invalid-effect-dependencies": { code: "SC3033", docsUrl: "https://supacloud.dev/errors/SC3033" },
+    "invalid-effect-errors": { code: "SC3034", docsUrl: "https://supacloud.dev/errors/SC3034" },
+    "effect-return-type": { code: "SC3035", docsUrl: "https://supacloud.dev/errors/SC3035" },
+    "effect-contract-required": { code: "SC3036", docsUrl: "https://supacloud.dev/errors/SC3036" },
+    "effect-error-mapping-required": { code: "SC3037", docsUrl: "https://supacloud.dev/errors/SC3037" },
+    "effect-dependencies-required": { code: "SC3038", docsUrl: "https://supacloud.dev/errors/SC3038" },
+    "effect-command-retry-forbidden": { code: "SC3039", docsUrl: "https://supacloud.dev/errors/SC3039" },
+    "effect-dependency-type": { code: "SC3040", docsUrl: "https://supacloud.dev/errors/SC3040" },
     "invalid-route-response-map": { code: "SC3024", docsUrl: "https://supacloud.dev/errors/SC3024" },
     "invalid-route-response-selector": { code: "SC3025", docsUrl: "https://supacloud.dev/errors/SC3025" },
     "conflicting-route-response-schema": { code: "SC3026", docsUrl: "https://supacloud.dev/errors/SC3026" },
@@ -1775,6 +1786,9 @@ class ModuleGenerator {
           });
           fields.push(`responses: { ${responseFields.join(", ")} }`);
         }
+        if (route.effect !== undefined) {
+          fields.push(`effect: ${JSON.stringify(route.effect)}`);
+        }
         if (route.command)
           fields.push(`command: ${JSON.stringify(route.command)}`);
         if (route.guards && route.guards.length > 0) {
@@ -3586,6 +3600,14 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
   cookie?: unknown;
   response?: unknown;
   responses?: Record<string | number, unknown>;
+  effect?: {
+    required: true;
+    errors?: Array<{ tag: string; status: number; code: string; message?: string }>;
+    dependencies?: string[];
+    retry?: "none" | "explicit";
+    maxAttempts?: number;
+    timeoutMs?: number;
+  };
   /** Compile-time ownership and transport classification for the route boundary. */
   contract?: {
     body?: "framework" | "domain";
@@ -29330,6 +29352,188 @@ function parseController(input, ctx) {
               Object.assign(route.contract, { [field]: value });
           }
         }
+        const effectExpr = getProp(optionsObject, "effect");
+        if (effectExpr) {
+          const effectObject = resolveStaticObjectLiteral(effectExpr, ctx);
+          if (!effectObject) {
+            ctx.diagnostics.push({
+              severity: "error",
+              code: "invalid-effect-contract",
+              errorCode: "SC3030",
+              docsUrl: "https://supacloud.dev/errors/SC3030",
+              file,
+              line: lineOf(effectExpr),
+              message: `Route ${route.handler} effect must be a statically resolvable object literal.`,
+              suggestion: "Use effect: { required: true, errors: [...], dependencies: [...] }."
+            });
+          } else {
+            const effect = { required: true };
+            const requiredExpr = getProp(effectObject, "required");
+            if (requiredExpr !== undefined && booleanProp(effectObject, "required") !== true) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-effect-contract",
+                errorCode: "SC3030",
+                docsUrl: "https://supacloud.dev/errors/SC3030",
+                file,
+                line: lineOf(requiredExpr),
+                message: `Route ${route.handler} effect.required must be the literal true.`
+              });
+            }
+            const retry = stringLiteralProp(effectObject, "retry");
+            if (retry !== undefined) {
+              if (retry !== "none" && retry !== "explicit") {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-retry",
+                  errorCode: "SC3031",
+                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  file,
+                  line: lineOf(getProp(effectObject, "retry")),
+                  message: `Route ${route.handler} effect.retry must be "none" or "explicit".`
+                });
+              } else {
+                effect.retry = retry;
+              }
+            }
+            const maxAttemptsExpr = getProp(effectObject, "maxAttempts");
+            if (maxAttemptsExpr !== undefined) {
+              const maxAttempts = numberLiteralProp(effectObject, "maxAttempts");
+              if (maxAttempts === undefined || maxAttempts < 1 || !Number.isInteger(maxAttempts)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-retry",
+                  errorCode: "SC3031",
+                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  file,
+                  line: lineOf(maxAttemptsExpr),
+                  message: `Route ${route.handler} effect.maxAttempts must be a positive integer.`
+                });
+              } else {
+                effect.maxAttempts = maxAttempts;
+              }
+            }
+            if (effect.retry === "explicit" && effect.maxAttempts === undefined) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-effect-retry",
+                errorCode: "SC3031",
+                docsUrl: "https://supacloud.dev/errors/SC3031",
+                file,
+                line: lineOf(effectExpr),
+                message: `Route ${route.handler} effect.maxAttempts is required when retry is "explicit".`
+              });
+            }
+            const timeoutExpr = getProp(effectObject, "timeoutMs");
+            if (timeoutExpr !== undefined) {
+              const timeoutMs = numberLiteralProp(effectObject, "timeoutMs");
+              if (timeoutMs === undefined || timeoutMs <= 0 || !Number.isInteger(timeoutMs)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-timeout",
+                  errorCode: "SC3032",
+                  docsUrl: "https://supacloud.dev/errors/SC3032",
+                  file,
+                  line: lineOf(timeoutExpr),
+                  message: `Route ${route.handler} effect.timeoutMs must be a positive integer.`
+                });
+              } else {
+                effect.timeoutMs = timeoutMs;
+              }
+            }
+            const dependenciesExpr = getProp(effectObject, "dependencies");
+            if (dependenciesExpr !== undefined) {
+              if (!ts7.isArrayLiteralExpression(dependenciesExpr) || dependenciesExpr.elements.some((element) => !ts7.isStringLiteral(element) || element.text.trim().length === 0)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-dependencies",
+                  errorCode: "SC3033",
+                  docsUrl: "https://supacloud.dev/errors/SC3033",
+                  file,
+                  line: lineOf(dependenciesExpr),
+                  message: `Route ${route.handler} effect.dependencies must be an explicit string array.`
+                });
+              } else {
+                effect.dependencies = dependenciesExpr.elements.map((element) => element.text);
+              }
+            }
+            const errorsExpr = getProp(effectObject, "errors");
+            if (errorsExpr !== undefined) {
+              if (!ts7.isArrayLiteralExpression(errorsExpr)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-errors",
+                  errorCode: "SC3034",
+                  docsUrl: "https://supacloud.dev/errors/SC3034",
+                  file,
+                  line: lineOf(errorsExpr),
+                  message: `Route ${route.handler} effect.errors must be an explicit object array.`
+                });
+              } else {
+                const errors = [];
+                for (const errorExpr of errorsExpr.elements) {
+                  if (!ts7.isObjectLiteralExpression(errorExpr)) {
+                    ctx.diagnostics.push({
+                      severity: "error",
+                      code: "invalid-effect-errors",
+                      errorCode: "SC3034",
+                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      file,
+                      line: lineOf(errorExpr),
+                      message: `Route ${route.handler} effect.errors entries must be object literals.`
+                    });
+                    continue;
+                  }
+                  const tag = stringLiteralProp(errorExpr, "tag");
+                  const code = stringLiteralProp(errorExpr, "code");
+                  const status = numberLiteralProp(errorExpr, "status");
+                  const message = stringLiteralProp(errorExpr, "message");
+                  if (!tag || !code || status === undefined || !Number.isInteger(status) || status < 400 || status > 599) {
+                    ctx.diagnostics.push({
+                      severity: "error",
+                      code: "invalid-effect-errors",
+                      errorCode: "SC3034",
+                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      file,
+                      line: lineOf(errorExpr),
+                      message: `Route ${route.handler} effect.errors entries require tag, code and an HTTP status from 400 to 599.`
+                    });
+                    continue;
+                  }
+                  errors.push({ tag, code, status, ...message === undefined ? {} : { message } });
+                }
+                effect.errors = errors;
+              }
+            }
+            route.effect = effect;
+            if (!resultType || !/\bEffect(?:\.Effect)?(?:<|\s)/.test(resultType)) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "effect-return-type",
+                errorCode: "SC3035",
+                docsUrl: "https://supacloud.dev/errors/SC3035",
+                file,
+                line: lineOf(method),
+                message: `Route ${route.handler} declares an Effect contract but returns ${resultType ?? "an unresolved type"}.`,
+                suggestion: "Return Effect.Effect<Success, Failure, Requirements> from the handler."
+              });
+            }
+            for (const dependency of effect.dependencies ?? []) {
+              if (!resultType?.includes(dependency)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "effect-dependency-type",
+                  errorCode: "SC3040",
+                  docsUrl: "https://supacloud.dev/errors/SC3040",
+                  file,
+                  line: lineOf(method),
+                  message: `Route ${route.handler} declares Effect dependency "${dependency}", but it is absent from the return type environment ${resultType ?? "unknown"}.`,
+                  suggestion: "Keep effect.dependencies aligned with the third Effect type parameter."
+                });
+              }
+            }
+          }
+        }
         for (const field of ["body", "params", "query", "headers", "cookie", "response"]) {
           const schemaExpr = getProp(optionsObject, field);
           if (schemaExpr && ts7.isIdentifier(schemaExpr)) {
@@ -29913,6 +30117,13 @@ function stringLiteralProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && ts7.isStringLiteral(expr) ? expr.text : undefined;
 }
+function numberLiteralProp(obj, name) {
+  const expr = getProp(obj, name);
+  if (!expr || !ts7.isNumericLiteral(expr))
+    return;
+  const value = Number(expr.text);
+  return Number.isFinite(value) ? value : undefined;
+}
 function arrayProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && ts7.isArrayLiteralExpression(expr) ? [...expr.elements] : [];
@@ -30574,6 +30785,57 @@ function validateClientSchemaBoundaries(graph, options) {
   return diagnostics;
 }
 
+// src/effect-governance.ts
+init_validate();
+function diagnostic(code, message, file, suggestion) {
+  const metadata = COMPILER_DIAGNOSTIC_CODES[code];
+  return {
+    severity: "error",
+    code,
+    message,
+    ...file === undefined ? {} : { file },
+    ...suggestion === undefined ? {} : { suggestion },
+    ...metadata ? { errorCode: metadata.code, docsUrl: metadata.docsUrl } : {}
+  };
+}
+function routeLabel(route, controllerPath) {
+  return `${route.method} ${controllerPath}${route.path}`;
+}
+function validateEffectPolicies(graph, options = {}) {
+  const diagnostics = [];
+  for (const module of graph.modules) {
+    const commands = new Map(module.commands.map((command) => [command.className, command]));
+    for (const controller of module.controllers) {
+      for (const route of controller.routes) {
+        const label = routeLabel(route, controller.path);
+        if (options.requireRouteEffects && route.effect === undefined) {
+          diagnostics.push(diagnostic("effect-contract-required", `Route ${label} must declare an Effect contract.`, controller.file, 'Add effect: { dependencies: [...], errors: [...], retry: "none" } to the route options.'));
+          continue;
+        }
+        const effect = route.effect;
+        if (effect === undefined)
+          continue;
+        if (options.requireErrorMappings && effect.errors === undefined) {
+          diagnostics.push(diagnostic("effect-error-mapping-required", `Route ${label} declares an Effect contract without public error mappings.`, controller.file, "Map every expected domain failure to a stable HTTP status and public code."));
+        }
+        if (options.requireDependencies && effect.dependencies === undefined) {
+          diagnostics.push(diagnostic("effect-dependencies-required", `Route ${label} declares an Effect contract without dependencies.`, controller.file, "Declare the logical services required by the Effect environment."));
+        }
+        if (effect.retry === "explicit" && effect.maxAttempts === undefined) {
+          diagnostics.push(diagnostic("invalid-effect-retry", `Route ${label} enables explicit Effect retry without maxAttempts.`, controller.file, "Declare a positive maxAttempts value including the initial attempt."));
+        }
+        if (route.command && effect.retry === "explicit") {
+          const command = commands.get(route.command);
+          if (command && command.idempotency !== "required") {
+            diagnostics.push(diagnostic("effect-command-retry-forbidden", `Route ${label} enables explicit Effect retry for non-idempotent command "${command.name}".`, controller.file, 'Set command idempotency to "required" or use effect.retry: "none".'));
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+
 // src/compile.ts
 function withDefaultGovernance(options) {
   return options.commandCapabilities === undefined ? { ...options, commandCapabilities: {
@@ -30593,7 +30855,8 @@ async function compileProject(options) {
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
-    ...validateClientSchemaBoundaries(graph, options)
+    ...validateClientSchemaBoundaries(graph, options),
+    ...validateEffectPolicies(graph, options.effect)
   ];
   if (diagnostics.some((item) => item.code === "runtime-injection-disallowed")) {
     return { diagnostics, graph, written: [] };
@@ -30657,7 +30920,8 @@ async function checkProject(options) {
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
-    ...validateClientSchemaBoundaries(graph, options)
+    ...validateClientSchemaBoundaries(graph, options),
+    ...validateEffectPolicies(graph, options.effect)
   ];
   if (diagnostics.some((item) => item.code === "runtime-injection-disallowed")) {
     return { diagnostics, graph, upToDate: false, mismatches: ["Runtime DI must be migrated to constructor injection."] };
@@ -31467,7 +31731,12 @@ var DEFAULT_SUPACLOUD_CONFIG = {
     idempotency: true,
     transaction: true
   },
-  moduleBoundaryPreset: "modular-monolith"
+  moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true
+  }
 };
 function defineSupacloudConfig(config = {}) {
   if (config.delivery !== undefined)
@@ -31479,7 +31748,8 @@ function defineSupacloudConfig(config = {}) {
     ...DEFAULT_SUPACLOUD_CONFIG,
     ...config,
     include: config.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
-    graphql: config.graphql ?? DEFAULT_SUPACLOUD_CONFIG.graphql
+    graphql: config.graphql ?? DEFAULT_SUPACLOUD_CONFIG.graphql,
+    effect: config.effect === undefined ? { ...DEFAULT_SUPACLOUD_CONFIG.effect } : { ...DEFAULT_SUPACLOUD_CONFIG.effect, ...config.effect }
   };
 }
 function validateGovernanceConfig(config) {
@@ -31536,6 +31806,16 @@ function validateGovernanceConfig(config) {
     if (config[key] !== undefined && typeof config[key] !== "boolean")
       throw new Error(`${key} must be a boolean.`);
   }
+  if (config.effect !== undefined) {
+    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => !["requireRouteEffects", "requireErrorMappings", "requireDependencies"].includes(key))) {
+      throw new Error("effect accepts requireRouteEffects, requireErrorMappings and requireDependencies.");
+    }
+    for (const key of ["requireRouteEffects", "requireErrorMappings", "requireDependencies"]) {
+      if (config.effect[key] !== undefined && typeof config.effect[key] !== "boolean") {
+        throw new Error(`effect.${key} must be boolean.`);
+      }
+    }
+  }
 }
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
@@ -31556,6 +31836,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     ...resolved.allowRouteCommandBindings === undefined ? {} : { allowRouteCommandBindings: resolved.allowRouteCommandBindings },
     ...resolved.disallowControllerDirectDb === undefined ? {} : { disallowControllerDirectDb: resolved.disallowControllerDirectDb },
     ...resolved.detectOrphanModules === undefined ? {} : { detectOrphanModules: resolved.detectOrphanModules },
+    effect: resolved.effect === undefined ? { ...DEFAULT_SUPACLOUD_CONFIG.effect } : { ...DEFAULT_SUPACLOUD_CONFIG.effect, ...resolved.effect },
     treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders,
     graphql: resolved.graphql ? {
       ...resolved.graphql,
@@ -31644,7 +31925,7 @@ import { createHash as createHash10 } from "node:crypto";
 init_validate();
 var compare3 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 var sorted = (values) => [...new Set(values)].sort(compare3);
-function diagnostic(error) {
+function diagnostic2(error) {
   return {
     severity: error.severity,
     code: error.code,
@@ -31669,8 +31950,8 @@ function createDeliveryPlan(graph, input) {
     }] };
   }
   const diagnostics = [
-    ...(graph.diagnostics ?? []).map(diagnostic),
-    ...validateGraph(graph, { strict: true }).map(diagnostic)
+    ...(graph.diagnostics ?? []).map(diagnostic2),
+    ...validateGraph(graph, { strict: true }).map(diagnostic2)
   ];
   const fail = (code, message, suggestion) => {
     diagnostics.push({ severity: "error", code, message, suggestion });
@@ -32840,10 +33121,10 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { resolve as resolve18 } from "node:path";
 
 // src/migration-app-version.ts
-var MIGRATION_APP_VERSION = "0.23.0";
+var MIGRATION_APP_VERSION = "0.24.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.27.1";
+var MIGRATION_ELYSIA_VERSION = "0.28.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

package/dist/config.d.ts

@@ -20,12 +20,14 @@ export interface SupaCloudConfig {
     allowRouteCommandBindings?: boolean;
     disallowControllerDirectDb?: boolean;
     detectOrphanModules?: boolean;
+    effect?: NonNullable<CompileOptions["effect"]>;
     commandCapabilities?: CommandExecutionCapabilities;
     treeShakeUnusedProviders?: boolean;
 }
-export declare const DEFAULT_SUPACLOUD_CONFIG: Required<Omit<SupaCloudConfig, "include" | "moduleBoundaryPreset" | "moduleBoundaries" | "typeSafety" | "delivery" | "allowRouteCommandBindings" | "disallowControllerDirectDb" | "detectOrphanModules" | "openApi">> & {
+export declare const DEFAULT_SUPACLOUD_CONFIG: Required<Omit<SupaCloudConfig, "include" | "moduleBoundaryPreset" | "moduleBoundaries" | "typeSafety" | "delivery" | "allowRouteCommandBindings" | "disallowControllerDirectDb" | "detectOrphanModules" | "openApi" | "effect">> & {
     include: string[];
     moduleBoundaryPreset: ModuleBoundaryPresetName;
+    effect: NonNullable<CompileOptions["effect"]>;
 };
 export declare function defineSupacloudConfig(config?: SupaCloudConfig): SupaCloudConfig;
 export declare function resolveSupacloudConfig(config?: SupaCloudConfig, cwd?: string): {
@@ -45,6 +47,7 @@ export declare function resolveSupacloudConfig(config?: SupaCloudConfig, cwd?: s
     allowRouteCommandBindings?: boolean;
     disallowControllerDirectDb?: boolean;
     detectOrphanModules?: boolean;
+    effect?: NonNullable<CompileOptions["effect"]>;
     treeShakeUnusedProviders: boolean;
     graphql?: GraphqlOptions;
 };

package/dist/effect-governance.d.ts

@@ -0,0 +1,3 @@
+import type { ApplicationGraph, Diagnostic, EffectCompilerOptions } from "./types";
+/** Validates the static Effect contract without inspecting Effect runtime internals. */
+export declare function validateEffectPolicies(graph: ApplicationGraph, options?: EffectCompilerOptions): Diagnostic[];

package/dist/index.d.ts

@@ -52,8 +52,9 @@ export { DEFAULT_SUPACLOUD_CONFIG, compileOptionsFromConfig, defineSupacloudConf
 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, GraphqlOptions, GraphqlContractSummary, OpenApiOptions, OpenApiSecurityScheme, OpenApiServer, } from "./types";
+export type { ApplicationGraph, AspectRefNode, CachedModuleEntry, CheckProjectResult, CommandExecutionCapabilities, CommandNode, CompileOptions, CompileResult, CompileStats, ControllerNode, DependencyGraphCache, DependencyGraphIndex, Diagnostic, DiagnosticFix, EffectCompilerOptions, EffectErrorMappingNode, EffectRetryPolicy, EffectRouteNode, ModuleBoundaryPresetName, ModuleBoundaryProfile, ModuleBoundaryRule, ModuleNode, JobNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, TypeSafetyOptions, ValidateOptions, WatchEvent, WatchHandle, WatchOptions, FeatureSpecNode, FeatureTransitionNode, GraphqlOptions, GraphqlContractSummary, OpenApiOptions, OpenApiSecurityScheme, OpenApiServer, } from "./types";
 export { inspectRouteContracts, validateRouteContracts } from "./route-contracts";
+export { validateEffectPolicies } from "./effect-governance";
 export { pullGraphqlSchema } from "./graphql-schema";
 export type { PullGraphqlSchemaOptions } from "./graphql-schema";
 export { checkGraphqlCompatibility, createRoleSnapshotReport, diffGraphqlSchemas, graphqlFeatureMatrix, introspectionQuery, readGraphqlSchema, schemaFromSource, } from "./graphql-governance";

package/dist/index.js

@@ -1236,6 +1236,17 @@ var init_validate = __esm(() => {
     "route-contract-required": { code: "SC3021", docsUrl: "https://supacloud.dev/errors/SC3021" },
     "route-contract-unverified": { code: "SC3022", docsUrl: "https://supacloud.dev/errors/SC3022" },
     "route-contract-evidence-required": { code: "SC3023", docsUrl: "https://supacloud.dev/errors/SC3023" },
+    "invalid-effect-contract": { code: "SC3030", docsUrl: "https://supacloud.dev/errors/SC3030" },
+    "invalid-effect-retry": { code: "SC3031", docsUrl: "https://supacloud.dev/errors/SC3031" },
+    "invalid-effect-timeout": { code: "SC3032", docsUrl: "https://supacloud.dev/errors/SC3032" },
+    "invalid-effect-dependencies": { code: "SC3033", docsUrl: "https://supacloud.dev/errors/SC3033" },
+    "invalid-effect-errors": { code: "SC3034", docsUrl: "https://supacloud.dev/errors/SC3034" },
+    "effect-return-type": { code: "SC3035", docsUrl: "https://supacloud.dev/errors/SC3035" },
+    "effect-contract-required": { code: "SC3036", docsUrl: "https://supacloud.dev/errors/SC3036" },
+    "effect-error-mapping-required": { code: "SC3037", docsUrl: "https://supacloud.dev/errors/SC3037" },
+    "effect-dependencies-required": { code: "SC3038", docsUrl: "https://supacloud.dev/errors/SC3038" },
+    "effect-command-retry-forbidden": { code: "SC3039", docsUrl: "https://supacloud.dev/errors/SC3039" },
+    "effect-dependency-type": { code: "SC3040", docsUrl: "https://supacloud.dev/errors/SC3040" },
     "invalid-route-response-map": { code: "SC3024", docsUrl: "https://supacloud.dev/errors/SC3024" },
     "invalid-route-response-selector": { code: "SC3025", docsUrl: "https://supacloud.dev/errors/SC3025" },
     "conflicting-route-response-schema": { code: "SC3026", docsUrl: "https://supacloud.dev/errors/SC3026" },
@@ -1774,6 +1785,9 @@ class ModuleGenerator {
           });
           fields.push(`responses: { ${responseFields.join(", ")} }`);
         }
+        if (route.effect !== undefined) {
+          fields.push(`effect: ${JSON.stringify(route.effect)}`);
+        }
         if (route.command)
           fields.push(`command: ${JSON.stringify(route.command)}`);
         if (route.guards && route.guards.length > 0) {
@@ -3585,6 +3599,14 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
   cookie?: unknown;
   response?: unknown;
   responses?: Record<string | number, unknown>;
+  effect?: {
+    required: true;
+    errors?: Array<{ tag: string; status: number; code: string; message?: string }>;
+    dependencies?: string[];
+    retry?: "none" | "explicit";
+    maxAttempts?: number;
+    timeoutMs?: number;
+  };
   /** Compile-time ownership and transport classification for the route boundary. */
   contract?: {
     body?: "framework" | "domain";
@@ -29289,6 +29311,188 @@ function parseController(input, ctx) {
               Object.assign(route.contract, { [field]: value });
           }
         }
+        const effectExpr = getProp(optionsObject, "effect");
+        if (effectExpr) {
+          const effectObject = resolveStaticObjectLiteral(effectExpr, ctx);
+          if (!effectObject) {
+            ctx.diagnostics.push({
+              severity: "error",
+              code: "invalid-effect-contract",
+              errorCode: "SC3030",
+              docsUrl: "https://supacloud.dev/errors/SC3030",
+              file,
+              line: lineOf(effectExpr),
+              message: `Route ${route.handler} effect must be a statically resolvable object literal.`,
+              suggestion: "Use effect: { required: true, errors: [...], dependencies: [...] }."
+            });
+          } else {
+            const effect = { required: true };
+            const requiredExpr = getProp(effectObject, "required");
+            if (requiredExpr !== undefined && booleanProp(effectObject, "required") !== true) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-effect-contract",
+                errorCode: "SC3030",
+                docsUrl: "https://supacloud.dev/errors/SC3030",
+                file,
+                line: lineOf(requiredExpr),
+                message: `Route ${route.handler} effect.required must be the literal true.`
+              });
+            }
+            const retry = stringLiteralProp(effectObject, "retry");
+            if (retry !== undefined) {
+              if (retry !== "none" && retry !== "explicit") {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-retry",
+                  errorCode: "SC3031",
+                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  file,
+                  line: lineOf(getProp(effectObject, "retry")),
+                  message: `Route ${route.handler} effect.retry must be "none" or "explicit".`
+                });
+              } else {
+                effect.retry = retry;
+              }
+            }
+            const maxAttemptsExpr = getProp(effectObject, "maxAttempts");
+            if (maxAttemptsExpr !== undefined) {
+              const maxAttempts = numberLiteralProp(effectObject, "maxAttempts");
+              if (maxAttempts === undefined || maxAttempts < 1 || !Number.isInteger(maxAttempts)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-retry",
+                  errorCode: "SC3031",
+                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  file,
+                  line: lineOf(maxAttemptsExpr),
+                  message: `Route ${route.handler} effect.maxAttempts must be a positive integer.`
+                });
+              } else {
+                effect.maxAttempts = maxAttempts;
+              }
+            }
+            if (effect.retry === "explicit" && effect.maxAttempts === undefined) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-effect-retry",
+                errorCode: "SC3031",
+                docsUrl: "https://supacloud.dev/errors/SC3031",
+                file,
+                line: lineOf(effectExpr),
+                message: `Route ${route.handler} effect.maxAttempts is required when retry is "explicit".`
+              });
+            }
+            const timeoutExpr = getProp(effectObject, "timeoutMs");
+            if (timeoutExpr !== undefined) {
+              const timeoutMs = numberLiteralProp(effectObject, "timeoutMs");
+              if (timeoutMs === undefined || timeoutMs <= 0 || !Number.isInteger(timeoutMs)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-timeout",
+                  errorCode: "SC3032",
+                  docsUrl: "https://supacloud.dev/errors/SC3032",
+                  file,
+                  line: lineOf(timeoutExpr),
+                  message: `Route ${route.handler} effect.timeoutMs must be a positive integer.`
+                });
+              } else {
+                effect.timeoutMs = timeoutMs;
+              }
+            }
+            const dependenciesExpr = getProp(effectObject, "dependencies");
+            if (dependenciesExpr !== undefined) {
+              if (!ts7.isArrayLiteralExpression(dependenciesExpr) || dependenciesExpr.elements.some((element) => !ts7.isStringLiteral(element) || element.text.trim().length === 0)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-dependencies",
+                  errorCode: "SC3033",
+                  docsUrl: "https://supacloud.dev/errors/SC3033",
+                  file,
+                  line: lineOf(dependenciesExpr),
+                  message: `Route ${route.handler} effect.dependencies must be an explicit string array.`
+                });
+              } else {
+                effect.dependencies = dependenciesExpr.elements.map((element) => element.text);
+              }
+            }
+            const errorsExpr = getProp(effectObject, "errors");
+            if (errorsExpr !== undefined) {
+              if (!ts7.isArrayLiteralExpression(errorsExpr)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-errors",
+                  errorCode: "SC3034",
+                  docsUrl: "https://supacloud.dev/errors/SC3034",
+                  file,
+                  line: lineOf(errorsExpr),
+                  message: `Route ${route.handler} effect.errors must be an explicit object array.`
+                });
+              } else {
+                const errors = [];
+                for (const errorExpr of errorsExpr.elements) {
+                  if (!ts7.isObjectLiteralExpression(errorExpr)) {
+                    ctx.diagnostics.push({
+                      severity: "error",
+                      code: "invalid-effect-errors",
+                      errorCode: "SC3034",
+                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      file,
+                      line: lineOf(errorExpr),
+                      message: `Route ${route.handler} effect.errors entries must be object literals.`
+                    });
+                    continue;
+                  }
+                  const tag = stringLiteralProp(errorExpr, "tag");
+                  const code = stringLiteralProp(errorExpr, "code");
+                  const status = numberLiteralProp(errorExpr, "status");
+                  const message = stringLiteralProp(errorExpr, "message");
+                  if (!tag || !code || status === undefined || !Number.isInteger(status) || status < 400 || status > 599) {
+                    ctx.diagnostics.push({
+                      severity: "error",
+                      code: "invalid-effect-errors",
+                      errorCode: "SC3034",
+                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      file,
+                      line: lineOf(errorExpr),
+                      message: `Route ${route.handler} effect.errors entries require tag, code and an HTTP status from 400 to 599.`
+                    });
+                    continue;
+                  }
+                  errors.push({ tag, code, status, ...message === undefined ? {} : { message } });
+                }
+                effect.errors = errors;
+              }
+            }
+            route.effect = effect;
+            if (!resultType || !/\bEffect(?:\.Effect)?(?:<|\s)/.test(resultType)) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "effect-return-type",
+                errorCode: "SC3035",
+                docsUrl: "https://supacloud.dev/errors/SC3035",
+                file,
+                line: lineOf(method),
+                message: `Route ${route.handler} declares an Effect contract but returns ${resultType ?? "an unresolved type"}.`,
+                suggestion: "Return Effect.Effect<Success, Failure, Requirements> from the handler."
+              });
+            }
+            for (const dependency of effect.dependencies ?? []) {
+              if (!resultType?.includes(dependency)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "effect-dependency-type",
+                  errorCode: "SC3040",
+                  docsUrl: "https://supacloud.dev/errors/SC3040",
+                  file,
+                  line: lineOf(method),
+                  message: `Route ${route.handler} declares Effect dependency "${dependency}", but it is absent from the return type environment ${resultType ?? "unknown"}.`,
+                  suggestion: "Keep effect.dependencies aligned with the third Effect type parameter."
+                });
+              }
+            }
+          }
+        }
         for (const field of ["body", "params", "query", "headers", "cookie", "response"]) {
           const schemaExpr = getProp(optionsObject, field);
           if (schemaExpr && ts7.isIdentifier(schemaExpr)) {
@@ -29872,6 +30076,13 @@ function stringLiteralProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && ts7.isStringLiteral(expr) ? expr.text : undefined;
 }
+function numberLiteralProp(obj, name) {
+  const expr = getProp(obj, name);
+  if (!expr || !ts7.isNumericLiteral(expr))
+    return;
+  const value = Number(expr.text);
+  return Number.isFinite(value) ? value : undefined;
+}
 function arrayProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && ts7.isArrayLiteralExpression(expr) ? [...expr.elements] : [];
@@ -30535,6 +30746,57 @@ function validateClientSchemaBoundaries(graph, options) {
   return diagnostics;
 }
 
+// src/effect-governance.ts
+init_validate();
+function diagnostic(code, message, file, suggestion) {
+  const metadata = COMPILER_DIAGNOSTIC_CODES[code];
+  return {
+    severity: "error",
+    code,
+    message,
+    ...file === undefined ? {} : { file },
+    ...suggestion === undefined ? {} : { suggestion },
+    ...metadata ? { errorCode: metadata.code, docsUrl: metadata.docsUrl } : {}
+  };
+}
+function routeLabel(route, controllerPath) {
+  return `${route.method} ${controllerPath}${route.path}`;
+}
+function validateEffectPolicies(graph, options = {}) {
+  const diagnostics = [];
+  for (const module of graph.modules) {
+    const commands = new Map(module.commands.map((command) => [command.className, command]));
+    for (const controller of module.controllers) {
+      for (const route of controller.routes) {
+        const label = routeLabel(route, controller.path);
+        if (options.requireRouteEffects && route.effect === undefined) {
+          diagnostics.push(diagnostic("effect-contract-required", `Route ${label} must declare an Effect contract.`, controller.file, 'Add effect: { dependencies: [...], errors: [...], retry: "none" } to the route options.'));
+          continue;
+        }
+        const effect = route.effect;
+        if (effect === undefined)
+          continue;
+        if (options.requireErrorMappings && effect.errors === undefined) {
+          diagnostics.push(diagnostic("effect-error-mapping-required", `Route ${label} declares an Effect contract without public error mappings.`, controller.file, "Map every expected domain failure to a stable HTTP status and public code."));
+        }
+        if (options.requireDependencies && effect.dependencies === undefined) {
+          diagnostics.push(diagnostic("effect-dependencies-required", `Route ${label} declares an Effect contract without dependencies.`, controller.file, "Declare the logical services required by the Effect environment."));
+        }
+        if (effect.retry === "explicit" && effect.maxAttempts === undefined) {
+          diagnostics.push(diagnostic("invalid-effect-retry", `Route ${label} enables explicit Effect retry without maxAttempts.`, controller.file, "Declare a positive maxAttempts value including the initial attempt."));
+        }
+        if (route.command && effect.retry === "explicit") {
+          const command = commands.get(route.command);
+          if (command && command.idempotency !== "required") {
+            diagnostics.push(diagnostic("effect-command-retry-forbidden", `Route ${label} enables explicit Effect retry for non-idempotent command "${command.name}".`, controller.file, 'Set command idempotency to "required" or use effect.retry: "none".'));
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+
 // src/compile.ts
 function withDefaultGovernance(options) {
   return options.commandCapabilities === undefined ? { ...options, commandCapabilities: {
@@ -30554,7 +30816,8 @@ async function compileProject(options) {
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
-    ...validateClientSchemaBoundaries(graph, options)
+    ...validateClientSchemaBoundaries(graph, options),
+    ...validateEffectPolicies(graph, options.effect)
   ];
   if (diagnostics.some((item) => item.code === "runtime-injection-disallowed")) {
     return { diagnostics, graph, written: [] };
@@ -30618,7 +30881,8 @@ async function checkProject(options) {
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
-    ...validateClientSchemaBoundaries(graph, options)
+    ...validateClientSchemaBoundaries(graph, options),
+    ...validateEffectPolicies(graph, options.effect)
   ];
   if (diagnostics.some((item) => item.code === "runtime-injection-disallowed")) {
     return { diagnostics, graph, upToDate: false, mismatches: ["Runtime DI must be migrated to constructor injection."] };
@@ -30704,7 +30968,7 @@ init_delivery_schema();
 init_validate();
 var compare2 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 var sorted = (values) => [...new Set(values)].sort(compare2);
-function diagnostic(error) {
+function diagnostic2(error) {
   return {
     severity: error.severity,
     code: error.code,
@@ -30729,8 +30993,8 @@ function createDeliveryPlan(graph, input) {
     }] };
   }
   const diagnostics = [
-    ...(graph.diagnostics ?? []).map(diagnostic),
-    ...validateGraph(graph, { strict: true }).map(diagnostic)
+    ...(graph.diagnostics ?? []).map(diagnostic2),
+    ...validateGraph(graph, { strict: true }).map(diagnostic2)
   ];
   const fail = (code, message, suggestion) => {
     diagnostics.push({ severity: "error", code, message, suggestion });
@@ -32573,10 +32837,10 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { resolve as resolve17 } from "node:path";
 
 // src/migration-app-version.ts
-var MIGRATION_APP_VERSION = "0.23.0";
+var MIGRATION_APP_VERSION = "0.24.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.27.1";
+var MIGRATION_ELYSIA_VERSION = "0.28.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;
@@ -33746,7 +34010,12 @@ var DEFAULT_SUPACLOUD_CONFIG = {
     idempotency: true,
     transaction: true
   },
-  moduleBoundaryPreset: "modular-monolith"
+  moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true
+  }
 };
 function defineSupacloudConfig(config = {}) {
   if (config.delivery !== undefined)
@@ -33758,7 +34027,8 @@ function defineSupacloudConfig(config = {}) {
     ...DEFAULT_SUPACLOUD_CONFIG,
     ...config,
     include: config.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
-    graphql: config.graphql ?? DEFAULT_SUPACLOUD_CONFIG.graphql
+    graphql: config.graphql ?? DEFAULT_SUPACLOUD_CONFIG.graphql,
+    effect: config.effect === undefined ? { ...DEFAULT_SUPACLOUD_CONFIG.effect } : { ...DEFAULT_SUPACLOUD_CONFIG.effect, ...config.effect }
   };
 }
 function validateGovernanceConfig(config) {
@@ -33815,6 +34085,16 @@ function validateGovernanceConfig(config) {
     if (config[key] !== undefined && typeof config[key] !== "boolean")
       throw new Error(`${key} must be a boolean.`);
   }
+  if (config.effect !== undefined) {
+    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => !["requireRouteEffects", "requireErrorMappings", "requireDependencies"].includes(key))) {
+      throw new Error("effect accepts requireRouteEffects, requireErrorMappings and requireDependencies.");
+    }
+    for (const key of ["requireRouteEffects", "requireErrorMappings", "requireDependencies"]) {
+      if (config.effect[key] !== undefined && typeof config.effect[key] !== "boolean") {
+        throw new Error(`effect.${key} must be boolean.`);
+      }
+    }
+  }
 }
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
@@ -33835,6 +34115,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     ...resolved.allowRouteCommandBindings === undefined ? {} : { allowRouteCommandBindings: resolved.allowRouteCommandBindings },
     ...resolved.disallowControllerDirectDb === undefined ? {} : { disallowControllerDirectDb: resolved.disallowControllerDirectDb },
     ...resolved.detectOrphanModules === undefined ? {} : { detectOrphanModules: resolved.detectOrphanModules },
+    effect: resolved.effect === undefined ? { ...DEFAULT_SUPACLOUD_CONFIG.effect } : { ...DEFAULT_SUPACLOUD_CONFIG.effect, ...resolved.effect },
     treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders,
     graphql: resolved.graphql ? {
       ...resolved.graphql,
@@ -34237,6 +34518,7 @@ export {
   scanProductionSource,
   schemaFromSource,
   serializeOpenApiJson,
+  validateEffectPolicies,
   validateFeatureSpec,
   validateGraph,
   validateRouteContracts,

package/dist/migration-app-version.d.ts

@@ -1 +1 @@
-export declare const MIGRATION_APP_VERSION = "0.23.0";
+export declare const MIGRATION_APP_VERSION = "0.24.0";

package/dist/migration-elysia-version.d.ts

@@ -1 +1 @@
-export declare const MIGRATION_ELYSIA_VERSION = "0.27.1";
+export declare const MIGRATION_ELYSIA_VERSION = "0.28.0";

package/dist/types.d.ts

@@ -185,6 +185,21 @@ export interface HandlerParamNode {
     transform?: "number" | "boolean" | "string";
     default?: unknown;
 }
+export type EffectRetryPolicy = "none" | "explicit";
+export interface EffectErrorMappingNode {
+    tag: string;
+    status: number;
+    code: string;
+    message?: string;
+}
+export interface EffectRouteNode {
+    required: true;
+    errors?: EffectErrorMappingNode[];
+    dependencies?: string[];
+    retry?: EffectRetryPolicy;
+    maxAttempts?: number;
+    timeoutMs?: number;
+}
 export interface RouteNode {
     parse?: "none";
     allowDeleteBody?: true;
@@ -205,6 +220,8 @@ export interface RouteNode {
     cookie?: string;
     response?: string;
     responses?: Record<string, string>;
+    /** Static Effect execution contract for this route. */
+    effect?: EffectRouteNode;
     /** @Command-decorated class explicitly bound by the route. */
     command?: string;
     /** Route guards executed before handler (Angular CanActivateFn style). */
@@ -429,6 +446,16 @@ export interface CompileOptions {
     changedPaths?: string[];
     /** Type-safety gates for generated artifacts and production source. */
     typeSafety?: TypeSafetyOptions;
+    /** Compile-time Effect governance for routes and command handlers. */
+    effect?: EffectCompilerOptions;
+}
+export interface EffectCompilerOptions {
+    /** Require every discovered route to declare an Effect contract. */
+    requireRouteEffects?: boolean;
+    /** Require explicit public mappings for Effect failures. */
+    requireErrorMappings?: boolean;
+    /** Require an explicit dependency list for Effect environments. */
+    requireDependencies?: boolean;
 }
 export interface GraphqlOptions {
     /** Additionally emit standard TypedDocumentNode artifacts for GraphQL ecosystem clients. */
@@ -527,6 +554,7 @@ export interface ValidateOptions {
     disallowControllerDirectDb?: boolean;
     /** Detect modules declared in the project that are unreachable from any root module. */
     detectOrphanModules?: boolean;
+    effect?: EffectCompilerOptions;
 }
 /** Runtime capabilities declared by the Command executor. */
 export interface CommandExecutionCapabilities {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.40.1",
+  "version": "0.41.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",