@supacloud/compiler 0.40.1 → 0.42.0

package/dist/index.js

@@ -1236,6 +1236,24 @@ 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" },
+    "effect-error-type": { code: "SC3041", docsUrl: "https://supacloud.dev/errors/SC3041" },
+    "effect-error-mapping-type": { code: "SC3042", docsUrl: "https://supacloud.dev/errors/SC3042" },
+    "effect-dependency-mismatch": { code: "SC3043", docsUrl: "https://supacloud.dev/errors/SC3043" },
+    "effect-timeout-required": { code: "SC3044", docsUrl: "https://supacloud.dev/errors/SC3044" },
+    "effect-direct-runtime-execution": { code: "SC3045", docsUrl: "https://supacloud.dev/errors/SC3045" },
+    "effect-direct-throw": { code: "SC3046", docsUrl: "https://supacloud.dev/errors/SC3046" },
+    "effect-promise-return": { code: "SC3047", docsUrl: "https://supacloud.dev/errors/SC3047" },
     "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 +1792,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 +3606,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";
@@ -27752,6 +27781,13 @@ function withDiagnosticMetadata(diagnostic) {
   const metadata = COMPILER_DIAGNOSTIC_CODES[diagnostic.code];
   return metadata ? { ...diagnostic, errorCode: metadata.code, docsUrl: metadata.docsUrl } : diagnostic;
 }
+var DEFAULT_EFFECT_ANALYSIS_OPTIONS = {
+  requireTaggedErrorTypes: true,
+  requireExactDependencyTypes: true,
+  requireTimeoutForDependencies: true,
+  forbidDirectRuntimeExecution: true,
+  forbidDirectThrows: true
+};
 function nodeText(node) {
   return node.getText(node.getSourceFile());
 }
@@ -27797,7 +27833,7 @@ function descendantsOfKind(root, predicate) {
   visit(root);
   return result;
 }
-async function analyzeProject(rootDir, include, cache, changedPaths) {
+async function analyzeProject(rootDir, include, cache, changedPaths, effectOptions = {}) {
   const session = cache?.programSession ?? createIncrementalProgramSession(rootDir);
   if (cache)
     cache.programSession = session;
@@ -27816,8 +27852,21 @@ async function analyzeProject(rootDir, include, cache, changedPaths) {
     moduleHandlerFiles: new Map,
     infraResources: new Map,
     infraResourceClasses: new Map,
-    diagnostics: []
+    diagnostics: [],
+    effectOptions: {
+      ...DEFAULT_EFFECT_ANALYSIS_OPTIONS,
+      requireTaggedErrorTypes: effectOptions.requireTaggedErrorTypes ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireTaggedErrorTypes,
+      requireExactDependencyTypes: effectOptions.requireExactDependencyTypes ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireExactDependencyTypes,
+      requireTimeoutForDependencies: effectOptions.requireTimeoutForDependencies ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.requireTimeoutForDependencies,
+      forbidDirectRuntimeExecution: effectOptions.forbidDirectRuntimeExecution ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.forbidDirectRuntimeExecution,
+      forbidDirectThrows: effectOptions.forbidDirectThrows ?? DEFAULT_EFFECT_ANALYSIS_OPTIONS.forbidDirectThrows
+    }
   };
+  if (ctx.effectOptions.forbidDirectRuntimeExecution) {
+    for (const sourceFile of sourceFiles) {
+      scanEffectRuntimeEscapes(sourceFile, ctx);
+    }
+  }
   const nativeTraitFiles = new Map;
   for (const diagnostic of session.getDiagnostics()) {
     ctx.diagnostics.push(toCompilerDiagnostic(diagnostic, rootDir));
@@ -28993,11 +29042,150 @@ function declaredClassType(declaration, ctx) {
   return symbol ? ctx.checker.getDeclaredTypeOfSymbol(symbol) : undefined;
 }
 function typeArgumentsOf(type, ctx) {
-  return isTypeReference(type) ? ctx.checker.getTypeArguments(type) : [];
+  if (!isTypeReference(type))
+    return [];
+  const argumentsFromChecker = ctx.checker.getTypeArguments(type);
+  if (argumentsFromChecker.length > 0)
+    return argumentsFromChecker;
+  const reference = type;
+  if (reference.resolvedTypeArguments && reference.resolvedTypeArguments.length > 0) {
+    return reference.resolvedTypeArguments;
+  }
+  return reference.aliasTypeArguments ?? [];
 }
 function isTypeReference(type) {
   return "target" in type;
 }
+function effectTypeArgumentsOf(type, ctx) {
+  if (!type)
+    return;
+  const reference = isTypeReference(type) ? type : undefined;
+  const target = reference?.target ?? type;
+  const symbol = target.aliasSymbol ?? target.getSymbol();
+  const text = ctx.checker.typeToString(type, undefined, ts7.TypeFormatFlags.NoTruncation);
+  if (symbol?.getName() !== "Effect" && !/^(?:Effect\.)?Effect</.test(text))
+    return;
+  const args = typeArgumentsOf(type, ctx);
+  return args.length >= 3 ? [args[0], args[1], args[2]] : undefined;
+}
+function effectTypeName(type, location, ctx) {
+  return ctx.checker.typeToString(type, location, ts7.TypeFormatFlags.NoTruncation);
+}
+function stringLiteralTypeValue(type) {
+  return (type.flags & ts7.TypeFlags.StringLiteral) !== 0 ? type.value : undefined;
+}
+function effectFailureTags(type, location, ctx) {
+  if ((type.flags & ts7.TypeFlags.Never) !== 0)
+    return { tags: [], invalid: false };
+  if ((type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0) {
+    return { tags: [], invalid: true };
+  }
+  if (type.isUnion()) {
+    return type.types.reduce((result, part) => {
+      const next = effectFailureTags(part, location, ctx);
+      result.tags.push(...next.tags);
+      result.invalid ||= next.invalid;
+      return result;
+    }, { tags: [], invalid: false });
+  }
+  const apparent = ctx.checker.getApparentType(type);
+  for (const propertyName of ["_tag", "tag"]) {
+    const property = ctx.checker.getPropertyOfType(apparent, propertyName);
+    if (!property)
+      continue;
+    const propertyType = ctx.checker.getTypeOfSymbolAtLocation(property, location);
+    const tag = stringLiteralTypeValue(propertyType);
+    if (tag)
+      return { tags: [tag], invalid: false };
+  }
+  return { tags: [], invalid: true };
+}
+function effectEnvironmentNames(type, location, ctx) {
+  if ((type.flags & ts7.TypeFlags.Never) !== 0)
+    return { names: [], invalid: false };
+  if ((type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0) {
+    return { names: [], invalid: true };
+  }
+  if (type.isUnion() || type.isIntersection()) {
+    return type.types.reduce((result, part) => {
+      const next = effectEnvironmentNames(part, location, ctx);
+      result.names.push(...next.names);
+      result.invalid ||= next.invalid;
+      return result;
+    }, { names: [], invalid: false });
+  }
+  const literal = stringLiteralTypeValue(type);
+  if (literal)
+    return { names: [literal], invalid: false };
+  const symbolName = type.getSymbol()?.getName();
+  if (symbolName && symbolName !== "__type" && symbolName !== "__object") {
+    return { names: [symbolName], invalid: false };
+  }
+  const text = effectTypeName(type, location, ctx).trim();
+  if (text && text !== "object")
+    return { names: [text], invalid: false };
+  return { names: [], invalid: true };
+}
+function sortedUnique(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right, "en"));
+}
+function pushEffectDiagnostic(ctx, code, file, line, message, suggestion) {
+  const metadata = COMPILER_DIAGNOSTIC_CODES[code];
+  ctx.diagnostics.push({
+    severity: "error",
+    code,
+    ...metadata ? { errorCode: metadata.code, docsUrl: metadata.docsUrl } : {},
+    file,
+    line,
+    message,
+    suggestion
+  });
+}
+function scanEffectRuntimeEscapes(sourceFile, ctx) {
+  const relativeFile = sourcePath(ctx.rootDir, sourceFile.fileName);
+  if (/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(relativeFile))
+    return;
+  const namespaceBindings = new Set;
+  const runtimeBindings = new Set;
+  for (const statement of sourceFile.statements) {
+    if (!ts7.isImportDeclaration(statement) || !ts7.isStringLiteral(statement.moduleSpecifier))
+      continue;
+    const moduleName = statement.moduleSpecifier.text;
+    if (moduleName !== "effect" && moduleName !== "effect/Effect" && moduleName !== "effect/Runtime")
+      continue;
+    const clause = statement.importClause;
+    if (!clause)
+      continue;
+    if (clause.name)
+      namespaceBindings.add(clause.name.text);
+    if (clause.namedBindings && ts7.isNamespaceImport(clause.namedBindings)) {
+      namespaceBindings.add(clause.namedBindings.name.text);
+    } else if (clause.namedBindings && ts7.isNamedImports(clause.namedBindings)) {
+      for (const element of clause.namedBindings.elements) {
+        const imported = element.propertyName?.text ?? element.name.text;
+        if (moduleName === "effect" && (imported === "Effect" || imported === "Runtime")) {
+          namespaceBindings.add(element.name.text);
+        }
+        if (["runPromise", "runPromiseExit", "runSync", "runFork"].includes(imported)) {
+          runtimeBindings.add(element.name.text);
+        }
+      }
+    }
+  }
+  if (namespaceBindings.size === 0 && runtimeBindings.size === 0)
+    return;
+  for (const call of descendantsOfKind(sourceFile, ts7.isCallExpression)) {
+    let runtimeName;
+    if (ts7.isPropertyAccessExpression(call.expression) && namespaceBindings.has(call.expression.expression.getText(sourceFile)) && ["runPromise", "runPromiseExit", "runSync", "runFork"].includes(call.expression.name.text)) {
+      runtimeName = call.expression.name.text;
+    } else if (ts7.isIdentifier(call.expression) && runtimeBindings.has(call.expression.text)) {
+      runtimeName = call.expression.text;
+    }
+    if (!runtimeName)
+      continue;
+    pushEffectDiagnostic(ctx, "effect-direct-runtime-execution", sourcePath(ctx.rootDir, sourceFile.fileName), lineOf(call), `Direct ${runtimeName} execution escapes the Effect boundary.`, "Return the Effect program to the Elysia boundary; only the framework adapter may interpret it.");
+  }
+}
 function isUnknownOrAny(type) {
   return (type.flags & (ts7.TypeFlags.Any | ts7.TypeFlags.Unknown)) !== 0;
 }
@@ -29061,7 +29249,8 @@ function parseController(input, ctx) {
         handler: propertyName(method.name)
       };
       const signature = ctx.checker.getSignatureFromDeclaration(method);
-      const resultType = signature && ctx.checker.typeToString(signature.getReturnType());
+      const returnType = signature?.getReturnType();
+      const resultType = returnType && ctx.checker.typeToString(returnType);
       if (resultType && /\bResponse\b/.test(resultType))
         route.nativeResponse = true;
       const pathParams = [];
@@ -29289,6 +29478,235 @@ 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);
+                if (new Set(effect.dependencies).size !== effect.dependencies.length) {
+                  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 not contain duplicate service names.`,
+                    suggestion: "List each logical Effect dependency exactly once."
+                  });
+                }
+              }
+            }
+            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;
+                if (new Set(errors.map((entry) => entry.tag)).size !== errors.length) {
+                  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 not contain duplicate tags.`,
+                    suggestion: "Map each tagged failure exactly once."
+                  });
+                }
+              }
+            }
+            route.effect = effect;
+            const effectArguments = effectTypeArgumentsOf(returnType, ctx);
+            const promiseReturn = Boolean(resultType && /\bPromise(?:<|\s)/.test(resultType));
+            if (promiseReturn) {
+              pushEffectDiagnostic(ctx, "effect-promise-return", file, lineOf(method), `Route ${route.handler} returns Promise instead of an Effect program.`, "Return Effect.Effect<Success, Failure, Requirements>; the Elysia boundary owns Promise interpretation.");
+            } else if (!effectArguments) {
+              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."
+              });
+            }
+            if (effectArguments) {
+              const [, failureType, environmentType] = effectArguments;
+              const failure = effectFailureTags(failureType, method, ctx);
+              if (ctx.effectOptions.requireTaggedErrorTypes && failure.invalid) {
+                pushEffectDiagnostic(ctx, "effect-error-type", file, lineOf(method), `Route ${route.handler} must use never or a tagged failure union in Effect's error channel, not ${effectTypeName(failureType, method, ctx)}.`, "Replace unknown/any with never or a union of objects carrying a literal _tag.");
+              } else if (ctx.effectOptions.requireTaggedErrorTypes && effect.errors !== undefined && !failure.invalid) {
+                const declaredTags = sortedUnique(effect.errors.map((entry) => entry.tag));
+                const typedTags = sortedUnique(failure.tags);
+                if (declaredTags.join("\x00") !== typedTags.join("\x00")) {
+                  pushEffectDiagnostic(ctx, "effect-error-mapping-type", file, lineOf(method), `Route ${route.handler} maps [${declaredTags.join(", ")}], but its Effect failure type declares [${typedTags.join(", ")}].`, "Make effect.errors and the Effect error type the same tagged union; do not hide unmapped failures.");
+                }
+              }
+              const environment = effectEnvironmentNames(environmentType, method, ctx);
+              if (ctx.effectOptions.requireExactDependencyTypes && effect.dependencies !== undefined) {
+                if (environment.invalid) {
+                  pushEffectDiagnostic(ctx, "effect-dependency-mismatch", file, lineOf(method), `Route ${route.handler} uses an Effect environment that cannot be represented by its explicit dependency list.`, "Use named service types or never in the third Effect type parameter.");
+                } else {
+                  const declaredDependencies = sortedUnique(effect.dependencies);
+                  const typedDependencies = sortedUnique(environment.names);
+                  if (declaredDependencies.join("\x00") !== typedDependencies.join("\x00")) {
+                    pushEffectDiagnostic(ctx, "effect-dependency-mismatch", file, lineOf(method), `Route ${route.handler} declares dependencies [${declaredDependencies.join(", ")}], but its Effect environment is [${typedDependencies.join(", ")}].`, "Make effect.dependencies exactly match the third Effect type parameter.");
+                  }
+                }
+              }
+              if (ctx.effectOptions.requireTimeoutForDependencies && (effect.dependencies?.length ?? 0) > 0 && effect.timeoutMs === undefined) {
+                pushEffectDiagnostic(ctx, "effect-timeout-required", file, lineOf(method), `Route ${route.handler} declares external Effect dependencies without a timeout.`, "Add a positive effect.timeoutMs so external I/O cannot occupy a request indefinitely.");
+              }
+            }
+            if (ctx.effectOptions.forbidDirectThrows && method.body) {
+              for (const throwStatement of descendantsOfKind(method.body, ts7.isThrowStatement)) {
+                pushEffectDiagnostic(ctx, "effect-direct-throw", file, lineOf(throwStatement), `Route ${route.handler} throws directly instead of representing failure in Effect.`, "Use Effect.fail with a tagged error value and map it in effect.errors.");
+              }
+            }
+          }
+        }
         for (const field of ["body", "params", "query", "headers", "cookie", "response"]) {
           const schemaExpr = getProp(optionsObject, field);
           if (schemaExpr && ts7.isIdentifier(schemaExpr)) {
@@ -29872,6 +30290,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 +30960,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: {
@@ -30550,11 +31026,12 @@ async function renderOptionalGraphql(options) {
 }
 async function compileProject(options) {
   options = withDefaultGovernance(options);
-  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths, options.effect);
   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: [] };
@@ -30614,11 +31091,12 @@ async function compileProject(options) {
 }
 async function checkProject(options) {
   options = withDefaultGovernance(options);
-  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths, options.effect);
   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 +31182,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 +31207,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 });
@@ -32264,6 +32742,7 @@ function optionsKeyOf(options) {
     openApi: options.openApi,
     generatePermissions: options.generatePermissions,
     typeSafety: options.typeSafety,
+    effect: options.effect,
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
     graphql: options.graphql
   });
@@ -32573,10 +33052,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.29.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;
@@ -33746,7 +34225,17 @@ var DEFAULT_SUPACLOUD_CONFIG = {
     idempotency: true,
     transaction: true
   },
-  moduleBoundaryPreset: "modular-monolith"
+  moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true,
+    requireTaggedErrorTypes: true,
+    requireExactDependencyTypes: true,
+    requireTimeoutForDependencies: true,
+    forbidDirectRuntimeExecution: true,
+    forbidDirectThrows: true
+  }
 };
 function defineSupacloudConfig(config = {}) {
   if (config.delivery !== undefined)
@@ -33758,7 +34247,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 +34305,34 @@ 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",
+      "requireTaggedErrorTypes",
+      "requireExactDependencyTypes",
+      "requireTimeoutForDependencies",
+      "forbidDirectRuntimeExecution",
+      "forbidDirectThrows"
+    ].includes(key))) {
+      throw new Error("effect contains an unsupported governance option.");
+    }
+    for (const key of [
+      "requireRouteEffects",
+      "requireErrorMappings",
+      "requireDependencies",
+      "requireTaggedErrorTypes",
+      "requireExactDependencyTypes",
+      "requireTimeoutForDependencies",
+      "forbidDirectRuntimeExecution",
+      "forbidDirectThrows"
+    ]) {
+      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 +34353,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 +34756,7 @@ export {
   scanProductionSource,
   schemaFromSource,
   serializeOpenApiJson,
+  validateEffectPolicies,
   validateFeatureSpec,
   validateGraph,
   validateRouteContracts,