@supacloud/compiler 0.57.1 → 0.58.0

package/dist/cli.js

@@ -382,6 +382,7 @@ var init_di_resolution = __esm(() => {
     "conflicting-injection-flags",
     "cross-module-scoped-dependency",
     "mixed-multi-provider-scopes",
+    "effect-contract-required",
     "dynamic-aspect-reference",
     "invalid-aspect-reference",
     "aspect-operation-mismatch"
@@ -2453,6 +2454,7 @@ function renderApplication(graph, options) {
           executor: route.command === undefined ? "route" : "command",
           ...command === undefined ? {} : { commandBoundary: route.command === undefined ? "handler" : "route" },
           ...route.effect === undefined ? {} : { effect: route.effect },
+          ...route.effectMode === undefined ? {} : { effectMode: route.effectMode },
           invoker: isPipeline ? "pipeline" : "direct",
           stages: operationPlans.find((plan) => plan.module === module.name && plan.kind === "route" && plan.name === `${route.method} ${joinRoutePaths(controller.path, route.path)}`).stages,
           ...commandRef === undefined ? {} : { command: command?.name ?? commandRef },
@@ -2832,6 +2834,8 @@ class ModuleGenerator {
         if (route.effect !== undefined) {
           fields.push(`effect: ${JSON.stringify(route.effect)}`);
         }
+        if (route.effectMode !== undefined)
+          fields.push(`effectMode: ${JSON.stringify(route.effectMode)}`);
         if (idempotency !== undefined) {
           fields.push(`idempotency: ${JSON.stringify(idempotency)}`);
         }
@@ -4681,6 +4685,8 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
     maxAttempts?: number;
     timeoutMs?: number;
   };
+  /** Simple route profile; no Effect interpreter or error mapping is required. */
+  effectMode?: "simple";
   /** Compile-time ownership and transport classification for the route boundary. */
   contract?: {
     body?: "framework" | "domain";
@@ -21488,111 +21494,102 @@ async function parseController(input, ctx) {
         }
         const effectExpr = getProp(optionsObject, "effect");
         if (effectExpr) {
-          const effectObject = await 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: [...], retry: "none" }.'
-            });
+          if (effectExpr.kind === ts8.SyntaxKind.FalseKeyword) {
+            route.effectMode = "simple";
           } else {
-            const effect = { required: true };
-            const requiredExpr = getProp(effectObject, "required");
-            if (requiredExpr !== undefined && booleanProp(effectObject, "required") !== true) {
+            const effectObject = await 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(requiredExpr),
-                message: `Route ${route.handler} effect.required must be the literal true.`
+                line: lineOf(effectExpr),
+                message: `Route ${route.handler} effect must be a statically resolvable object literal.`,
+                suggestion: 'Use effect: { required: true, errors: [...], dependencies: [...], retry: "none" }.'
               });
-            }
-            const retry = stringLiteralProp(effectObject, "retry");
-            if (retry !== undefined) {
-              if (retry !== "none" && retry !== "explicit") {
+            } 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-retry",
-                  errorCode: "SC3031",
-                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  code: "invalid-effect-contract",
+                  errorCode: "SC3030",
+                  docsUrl: "https://supacloud.dev/errors/SC3030",
                   file,
-                  line: lineOf(getProp(effectObject, "retry")),
-                  message: `Route ${route.handler} effect.retry must be "none" or "explicit".`
+                  line: lineOf(requiredExpr),
+                  message: `Route ${route.handler} effect.required must be the literal true.`
                 });
-              } else {
-                effect.retry = retry;
               }
-            } else if (ctx.effectOptions.requireRetryPolicy === false) {
-              effect.retry = "none";
-            }
-            const maxAttemptsExpr = getProp(effectObject, "maxAttempts");
-            if (maxAttemptsExpr !== undefined) {
-              const maxAttempts = numberLiteralProp(effectObject, "maxAttempts");
-              if (maxAttempts === undefined || maxAttempts < 1 || !Number.isInteger(maxAttempts)) {
+              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;
+                }
+              } else if (ctx.effectOptions.requireRetryPolicy === false) {
+                effect.retry = "none";
+              }
+              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(maxAttemptsExpr),
-                  message: `Route ${route.handler} effect.maxAttempts must be a positive integer.`
+                  line: lineOf(effectExpr),
+                  message: `Route ${route.handler} effect.maxAttempts is required when retry is "explicit".`
                 });
-              } 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 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) {
-              const dependenciesArray = await resolveStaticArrayLiteral(dependenciesExpr, ctx);
-              if (!dependenciesArray || dependenciesArray.elements.some((element) => !ts8.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 a string array or a const initialized with one.`
-                });
-              } else {
-                effect.dependencies = dependenciesArray.elements.map((element) => element.text);
-                if (new Set(effect.dependencies).size !== effect.dependencies.length) {
+              const dependenciesExpr = getProp(effectObject, "dependencies");
+              if (dependenciesExpr !== undefined) {
+                const dependenciesArray = await resolveStaticArrayLiteral(dependenciesExpr, ctx);
+                if (!dependenciesArray || dependenciesArray.elements.some((element) => !ts8.isStringLiteral(element) || element.text.trim().length === 0)) {
                   ctx.diagnostics.push({
                     severity: "error",
                     code: "invalid-effect-dependencies",
@@ -21600,148 +21597,161 @@ async function parseController(input, ctx) {
                     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."
+                    message: `Route ${route.handler} effect.dependencies must be a string array or a const initialized with one.`
                   });
-                }
-              }
-            }
-            const errorsExpr = getProp(effectObject, "errors");
-            if (errorsExpr !== undefined) {
-              const errorsArray = await resolveStaticArrayLiteral(errorsExpr, ctx);
-              if (!errorsArray) {
-                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 object array or a const initialized with one.`
-                });
-              } else {
-                const errors = [];
-                for (const errorExpr of errorsArray.elements) {
-                  if (!ts8.isObjectLiteralExpression(errorExpr)) {
+                } else {
+                  effect.dependencies = dependenciesArray.elements.map((element) => element.text);
+                  if (new Set(effect.dependencies).size !== effect.dependencies.length) {
                     ctx.diagnostics.push({
                       severity: "error",
-                      code: "invalid-effect-errors",
-                      errorCode: "SC3034",
-                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      code: "invalid-effect-dependencies",
+                      errorCode: "SC3033",
+                      docsUrl: "https://supacloud.dev/errors/SC3033",
                       file,
-                      line: lineOf(errorExpr),
-                      message: `Route ${route.handler} effect.errors entries must be object literals.`
+                      line: lineOf(dependenciesExpr),
+                      message: `Route ${route.handler} effect.dependencies must not contain duplicate service names.`,
+                      suggestion: "List each logical Effect dependency exactly once."
                     });
-                    continue;
                   }
-                  const tag = stringLiteralProp(errorExpr, "tag");
-                  const code = stringLiteralProp(errorExpr, "code");
-                  const status = numberLiteralProp(errorExpr, "status");
-                  const message = stringLiteralProp(errorExpr, "message");
-                  const codeFromError = booleanLiteralProp(errorExpr, "codeFromError");
-                  const messageFromError = booleanLiteralProp(errorExpr, "messageFromError");
-                  const statusFromError = booleanLiteralProp(errorExpr, "statusFromError");
-                  const retryable = booleanLiteralProp(errorExpr, "retryable");
-                  const outcomeUnknown = booleanLiteralProp(errorExpr, "outcomeUnknown");
-                  if (invalidBooleanProp(errorExpr, "codeFromError") || invalidBooleanProp(errorExpr, "messageFromError") || invalidBooleanProp(errorExpr, "statusFromError") || invalidBooleanProp(errorExpr, "retryable") || invalidBooleanProp(errorExpr, "outcomeUnknown")) {
-                    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 instance flags must be boolean literals.`
+                }
+              }
+              const errorsExpr = getProp(effectObject, "errors");
+              if (errorsExpr !== undefined) {
+                const errorsArray = await resolveStaticArrayLiteral(errorsExpr, ctx);
+                if (!errorsArray) {
+                  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 object array or a const initialized with one.`
+                  });
+                } else {
+                  const errors = [];
+                  for (const errorExpr of errorsArray.elements) {
+                    if (!ts8.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");
+                    const codeFromError = booleanLiteralProp(errorExpr, "codeFromError");
+                    const messageFromError = booleanLiteralProp(errorExpr, "messageFromError");
+                    const statusFromError = booleanLiteralProp(errorExpr, "statusFromError");
+                    const retryable = booleanLiteralProp(errorExpr, "retryable");
+                    const outcomeUnknown = booleanLiteralProp(errorExpr, "outcomeUnknown");
+                    if (invalidBooleanProp(errorExpr, "codeFromError") || invalidBooleanProp(errorExpr, "messageFromError") || invalidBooleanProp(errorExpr, "statusFromError") || invalidBooleanProp(errorExpr, "retryable") || invalidBooleanProp(errorExpr, "outcomeUnknown")) {
+                      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 instance flags must be boolean literals.`
+                      });
+                      continue;
+                    }
+                    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 },
+                      ...codeFromError === undefined ? {} : { codeFromError },
+                      ...messageFromError === undefined ? {} : { messageFromError },
+                      ...statusFromError === undefined ? {} : { statusFromError },
+                      ...retryable === undefined ? {} : { retryable },
+                      ...outcomeUnknown === undefined ? {} : { outcomeUnknown }
                     });
-                    continue;
                   }
-                  if (!tag || !code || status === undefined || !Number.isInteger(status) || status < 400 || status > 599) {
+                  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(errorExpr),
-                      message: `Route ${route.handler} effect.errors entries require tag, code and an HTTP status from 400 to 599.`
+                      line: lineOf(errorsExpr),
+                      message: `Route ${route.handler} effect.errors must not contain duplicate tags.`,
+                      suggestion: "Map each tagged failure exactly once."
                     });
-                    continue;
                   }
-                  errors.push({
-                    tag,
-                    code,
-                    status,
-                    ...message === undefined ? {} : { message },
-                    ...codeFromError === undefined ? {} : { codeFromError },
-                    ...messageFromError === undefined ? {} : { messageFromError },
-                    ...statusFromError === undefined ? {} : { statusFromError },
-                    ...retryable === undefined ? {} : { retryable },
-                    ...outcomeUnknown === undefined ? {} : { outcomeUnknown }
-                  });
-                }
-                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 = await 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 = await 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 ${await 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.");
-                }
+              route.effect = effect;
+              const effectArguments = await 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."
+                });
               }
-              const environment = await 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 (effectArguments) {
+                const [, failureType, environmentType] = effectArguments;
+                const failure = await 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 ${await 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 = await 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.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, ts8.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.");
+              if (ctx.effectOptions.forbidDirectThrows && method.body) {
+                for (const throwStatement of descendantsOfKind(method.body, ts8.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.");
+                }
               }
             }
           }
@@ -23375,6 +23385,14 @@ function validateEffectPolicies(graph, options = {}) {
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
         const label = routeLabel(route, controller.path);
+        if (route.effectMode === "simple") {
+          const featureTransition = featureTransitionForRoute(module, controller, route);
+          const commandRef = route.command ?? featureTransition?.command;
+          if (commandRef !== undefined || !["GET", "HEAD", "OPTIONS"].includes(route.method)) {
+            diagnostics.push(diagnostic("effect-contract-required", commandRef === undefined ? `Route ${label} cannot use effect: false for a write operation.` : `Route ${label} cannot use effect: false when it enters command ${commandRef}.`, controller.file, "Keep Effect enabled for writes and durable commands; effect: false is only for simple read routes."));
+          }
+          continue;
+        }
         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;
@@ -26432,10 +26450,10 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { resolve as resolve19 } from "node:path";
 
 // src/migration-app-version.ts
-var MIGRATION_APP_VERSION = "0.38.0";
+var MIGRATION_APP_VERSION = "0.39.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.40.0";
+var MIGRATION_ELYSIA_VERSION = "0.41.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

package/dist/index.js

@@ -381,6 +381,7 @@ var init_di_resolution = __esm(() => {
     "conflicting-injection-flags",
     "cross-module-scoped-dependency",
     "mixed-multi-provider-scopes",
+    "effect-contract-required",
     "dynamic-aspect-reference",
     "invalid-aspect-reference",
     "aspect-operation-mismatch"
@@ -2452,6 +2453,7 @@ function renderApplication(graph, options) {
           executor: route.command === undefined ? "route" : "command",
           ...command === undefined ? {} : { commandBoundary: route.command === undefined ? "handler" : "route" },
           ...route.effect === undefined ? {} : { effect: route.effect },
+          ...route.effectMode === undefined ? {} : { effectMode: route.effectMode },
           invoker: isPipeline ? "pipeline" : "direct",
           stages: operationPlans.find((plan) => plan.module === module.name && plan.kind === "route" && plan.name === `${route.method} ${joinRoutePaths(controller.path, route.path)}`).stages,
           ...commandRef === undefined ? {} : { command: command?.name ?? commandRef },
@@ -2831,6 +2833,8 @@ class ModuleGenerator {
         if (route.effect !== undefined) {
           fields.push(`effect: ${JSON.stringify(route.effect)}`);
         }
+        if (route.effectMode !== undefined)
+          fields.push(`effectMode: ${JSON.stringify(route.effectMode)}`);
         if (idempotency !== undefined) {
           fields.push(`idempotency: ${JSON.stringify(idempotency)}`);
         }
@@ -4680,6 +4684,8 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
     maxAttempts?: number;
     timeoutMs?: number;
   };
+  /** Simple route profile; no Effect interpreter or error mapping is required. */
+  effectMode?: "simple";
   /** Compile-time ownership and transport classification for the route boundary. */
   contract?: {
     body?: "framework" | "domain";
@@ -21447,111 +21453,102 @@ async function parseController(input, ctx) {
         }
         const effectExpr = getProp(optionsObject, "effect");
         if (effectExpr) {
-          const effectObject = await 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: [...], retry: "none" }.'
-            });
+          if (effectExpr.kind === ts8.SyntaxKind.FalseKeyword) {
+            route.effectMode = "simple";
           } else {
-            const effect = { required: true };
-            const requiredExpr = getProp(effectObject, "required");
-            if (requiredExpr !== undefined && booleanProp(effectObject, "required") !== true) {
+            const effectObject = await 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(requiredExpr),
-                message: `Route ${route.handler} effect.required must be the literal true.`
+                line: lineOf(effectExpr),
+                message: `Route ${route.handler} effect must be a statically resolvable object literal.`,
+                suggestion: 'Use effect: { required: true, errors: [...], dependencies: [...], retry: "none" }.'
               });
-            }
-            const retry = stringLiteralProp(effectObject, "retry");
-            if (retry !== undefined) {
-              if (retry !== "none" && retry !== "explicit") {
+            } 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-retry",
-                  errorCode: "SC3031",
-                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  code: "invalid-effect-contract",
+                  errorCode: "SC3030",
+                  docsUrl: "https://supacloud.dev/errors/SC3030",
                   file,
-                  line: lineOf(getProp(effectObject, "retry")),
-                  message: `Route ${route.handler} effect.retry must be "none" or "explicit".`
+                  line: lineOf(requiredExpr),
+                  message: `Route ${route.handler} effect.required must be the literal true.`
                 });
-              } else {
-                effect.retry = retry;
               }
-            } else if (ctx.effectOptions.requireRetryPolicy === false) {
-              effect.retry = "none";
-            }
-            const maxAttemptsExpr = getProp(effectObject, "maxAttempts");
-            if (maxAttemptsExpr !== undefined) {
-              const maxAttempts = numberLiteralProp(effectObject, "maxAttempts");
-              if (maxAttempts === undefined || maxAttempts < 1 || !Number.isInteger(maxAttempts)) {
+              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;
+                }
+              } else if (ctx.effectOptions.requireRetryPolicy === false) {
+                effect.retry = "none";
+              }
+              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(maxAttemptsExpr),
-                  message: `Route ${route.handler} effect.maxAttempts must be a positive integer.`
+                  line: lineOf(effectExpr),
+                  message: `Route ${route.handler} effect.maxAttempts is required when retry is "explicit".`
                 });
-              } 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 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) {
-              const dependenciesArray = await resolveStaticArrayLiteral(dependenciesExpr, ctx);
-              if (!dependenciesArray || dependenciesArray.elements.some((element) => !ts8.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 a string array or a const initialized with one.`
-                });
-              } else {
-                effect.dependencies = dependenciesArray.elements.map((element) => element.text);
-                if (new Set(effect.dependencies).size !== effect.dependencies.length) {
+              const dependenciesExpr = getProp(effectObject, "dependencies");
+              if (dependenciesExpr !== undefined) {
+                const dependenciesArray = await resolveStaticArrayLiteral(dependenciesExpr, ctx);
+                if (!dependenciesArray || dependenciesArray.elements.some((element) => !ts8.isStringLiteral(element) || element.text.trim().length === 0)) {
                   ctx.diagnostics.push({
                     severity: "error",
                     code: "invalid-effect-dependencies",
@@ -21559,148 +21556,161 @@ async function parseController(input, ctx) {
                     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."
+                    message: `Route ${route.handler} effect.dependencies must be a string array or a const initialized with one.`
                   });
-                }
-              }
-            }
-            const errorsExpr = getProp(effectObject, "errors");
-            if (errorsExpr !== undefined) {
-              const errorsArray = await resolveStaticArrayLiteral(errorsExpr, ctx);
-              if (!errorsArray) {
-                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 object array or a const initialized with one.`
-                });
-              } else {
-                const errors = [];
-                for (const errorExpr of errorsArray.elements) {
-                  if (!ts8.isObjectLiteralExpression(errorExpr)) {
+                } else {
+                  effect.dependencies = dependenciesArray.elements.map((element) => element.text);
+                  if (new Set(effect.dependencies).size !== effect.dependencies.length) {
                     ctx.diagnostics.push({
                       severity: "error",
-                      code: "invalid-effect-errors",
-                      errorCode: "SC3034",
-                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      code: "invalid-effect-dependencies",
+                      errorCode: "SC3033",
+                      docsUrl: "https://supacloud.dev/errors/SC3033",
                       file,
-                      line: lineOf(errorExpr),
-                      message: `Route ${route.handler} effect.errors entries must be object literals.`
+                      line: lineOf(dependenciesExpr),
+                      message: `Route ${route.handler} effect.dependencies must not contain duplicate service names.`,
+                      suggestion: "List each logical Effect dependency exactly once."
                     });
-                    continue;
                   }
-                  const tag = stringLiteralProp(errorExpr, "tag");
-                  const code = stringLiteralProp(errorExpr, "code");
-                  const status = numberLiteralProp(errorExpr, "status");
-                  const message = stringLiteralProp(errorExpr, "message");
-                  const codeFromError = booleanLiteralProp(errorExpr, "codeFromError");
-                  const messageFromError = booleanLiteralProp(errorExpr, "messageFromError");
-                  const statusFromError = booleanLiteralProp(errorExpr, "statusFromError");
-                  const retryable = booleanLiteralProp(errorExpr, "retryable");
-                  const outcomeUnknown = booleanLiteralProp(errorExpr, "outcomeUnknown");
-                  if (invalidBooleanProp(errorExpr, "codeFromError") || invalidBooleanProp(errorExpr, "messageFromError") || invalidBooleanProp(errorExpr, "statusFromError") || invalidBooleanProp(errorExpr, "retryable") || invalidBooleanProp(errorExpr, "outcomeUnknown")) {
-                    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 instance flags must be boolean literals.`
+                }
+              }
+              const errorsExpr = getProp(effectObject, "errors");
+              if (errorsExpr !== undefined) {
+                const errorsArray = await resolveStaticArrayLiteral(errorsExpr, ctx);
+                if (!errorsArray) {
+                  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 object array or a const initialized with one.`
+                  });
+                } else {
+                  const errors = [];
+                  for (const errorExpr of errorsArray.elements) {
+                    if (!ts8.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");
+                    const codeFromError = booleanLiteralProp(errorExpr, "codeFromError");
+                    const messageFromError = booleanLiteralProp(errorExpr, "messageFromError");
+                    const statusFromError = booleanLiteralProp(errorExpr, "statusFromError");
+                    const retryable = booleanLiteralProp(errorExpr, "retryable");
+                    const outcomeUnknown = booleanLiteralProp(errorExpr, "outcomeUnknown");
+                    if (invalidBooleanProp(errorExpr, "codeFromError") || invalidBooleanProp(errorExpr, "messageFromError") || invalidBooleanProp(errorExpr, "statusFromError") || invalidBooleanProp(errorExpr, "retryable") || invalidBooleanProp(errorExpr, "outcomeUnknown")) {
+                      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 instance flags must be boolean literals.`
+                      });
+                      continue;
+                    }
+                    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 },
+                      ...codeFromError === undefined ? {} : { codeFromError },
+                      ...messageFromError === undefined ? {} : { messageFromError },
+                      ...statusFromError === undefined ? {} : { statusFromError },
+                      ...retryable === undefined ? {} : { retryable },
+                      ...outcomeUnknown === undefined ? {} : { outcomeUnknown }
                     });
-                    continue;
                   }
-                  if (!tag || !code || status === undefined || !Number.isInteger(status) || status < 400 || status > 599) {
+                  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(errorExpr),
-                      message: `Route ${route.handler} effect.errors entries require tag, code and an HTTP status from 400 to 599.`
+                      line: lineOf(errorsExpr),
+                      message: `Route ${route.handler} effect.errors must not contain duplicate tags.`,
+                      suggestion: "Map each tagged failure exactly once."
                     });
-                    continue;
                   }
-                  errors.push({
-                    tag,
-                    code,
-                    status,
-                    ...message === undefined ? {} : { message },
-                    ...codeFromError === undefined ? {} : { codeFromError },
-                    ...messageFromError === undefined ? {} : { messageFromError },
-                    ...statusFromError === undefined ? {} : { statusFromError },
-                    ...retryable === undefined ? {} : { retryable },
-                    ...outcomeUnknown === undefined ? {} : { outcomeUnknown }
-                  });
-                }
-                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 = await 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 = await 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 ${await 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.");
-                }
+              route.effect = effect;
+              const effectArguments = await 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."
+                });
               }
-              const environment = await 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 (effectArguments) {
+                const [, failureType, environmentType] = effectArguments;
+                const failure = await 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 ${await 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 = await 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.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, ts8.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.");
+              if (ctx.effectOptions.forbidDirectThrows && method.body) {
+                for (const throwStatement of descendantsOfKind(method.body, ts8.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.");
+                }
               }
             }
           }
@@ -23336,6 +23346,14 @@ function validateEffectPolicies(graph, options = {}) {
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
         const label = routeLabel(route, controller.path);
+        if (route.effectMode === "simple") {
+          const featureTransition = featureTransitionForRoute(module, controller, route);
+          const commandRef = route.command ?? featureTransition?.command;
+          if (commandRef !== undefined || !["GET", "HEAD", "OPTIONS"].includes(route.method)) {
+            diagnostics.push(diagnostic("effect-contract-required", commandRef === undefined ? `Route ${label} cannot use effect: false for a write operation.` : `Route ${label} cannot use effect: false when it enters command ${commandRef}.`, controller.file, "Keep Effect enabled for writes and durable commands; effect: false is only for simple read routes."));
+          }
+          continue;
+        }
         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;
@@ -25684,10 +25702,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.38.0";
+var MIGRATION_APP_VERSION = "0.39.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.40.0";
+var MIGRATION_ELYSIA_VERSION = "0.41.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

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

@@ -1 +1 @@
-export declare const MIGRATION_APP_VERSION = "0.38.0";
+export declare const MIGRATION_APP_VERSION = "0.39.0";

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

@@ -1 +1 @@
-export declare const MIGRATION_ELYSIA_VERSION = "0.40.0";
+export declare const MIGRATION_ELYSIA_VERSION = "0.41.0";

package/dist/types.d.ts

@@ -253,6 +253,8 @@ export interface RouteNode {
     responses?: Record<string, string>;
     /** Static Effect execution contract for this route. */
     effect?: EffectRouteNode;
+    /** Simple route profile: handler may return a Promise/value without Effect governance. */
+    effectMode?: "simple";
     /** @Command-decorated class explicitly bound by the route. */
     command?: string;
     /** Route guards executed before handler (Angular CanActivateFn style). */
@@ -404,6 +406,7 @@ export interface ExecutionPlanRoute {
     invoker: "direct" | "pipeline";
     commandBoundary?: "route" | "handler";
     effect?: EffectRouteNode;
+    effectMode?: "simple";
     stages: string[];
     command?: string;
     guards: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.57.1",
+  "version": "0.58.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",
@@ -57,7 +57,7 @@
     "directory": "packages/compiler"
   },
   "dependencies": {
-    "@supacloud/db": "0.21.0",
+    "@supacloud/db": "0.22.0",
     "@supacloud/delivery": "0.25.0",
     "typebox": "1.4.3",
     "@graphql-codegen/core": "^6.2.2",