@supacloud/cli 0.72.0 → 0.74.0

package/dist/index.js

@@ -207715,7 +207715,7 @@ var ACTION_POLICY = {
     read: ["status", "logs"],
     write: ["upload", "configure", "deploy", "rollback", "reconcile", "retire"]
   },
-  db: { local: ["lint", "explain"], read: ["module_check"] },
+  db: { local: ["context", "lint", "explain"], read: ["module_check"] },
   dev: { read: ["status"], write: ["sync", "watch", "migrate"] }
 };
 function declaredMode(moduleName, action) {
@@ -221498,6 +221498,24 @@ var init_validate = __esm2(() => {
     "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" },
@@ -222026,6 +222044,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) {
@@ -223838,6 +223859,14 @@ var INTERFACES = `export interface CompiledRoute {
   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";
@@ -244728,6 +244757,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());
 }
@@ -244773,7 +244809,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;
@@ -244792,8 +244828,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));
@@ -245969,11 +246018,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), lineOf2(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;
 }
@@ -246037,7 +246225,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 = [];
@@ -246265,6 +246454,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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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: lineOf2(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, lineOf2(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: lineOf2(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, lineOf2(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, lineOf2(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, lineOf2(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, lineOf2(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, lineOf2(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, lineOf2(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)) {
@@ -246848,6 +247266,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] : [];
@@ -247489,6 +247914,55 @@ function validateClientSchemaBoundaries(graph, options) {
   }
   return diagnostics;
 }
+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;
+}
 function withDefaultGovernance(options) {
   return options.commandCapabilities === undefined ? { ...options, commandCapabilities: {
     requirePersistentAdapters: true,
@@ -247503,11 +247977,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: [] };
@@ -247567,11 +248042,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."] };
@@ -247653,7 +248129,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,
@@ -247678,8 +248154,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 });
@@ -248807,6 +249283,7 @@ function optionsKeyOf(options) {
     openApi: options.openApi,
     generatePermissions: options.generatePermissions,
     typeSafety: options.typeSafety,
+    effect: options.effect,
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
     graphql: options.graphql
   });
@@ -249134,7 +249611,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)
@@ -249146,7 +249633,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) {
@@ -249203,6 +249691,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);
@@ -249223,6 +249739,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,
@@ -249371,16 +249888,16 @@ var starter_metadata_default = {
   generatedBy: "supacloud/starter-metadata-v1",
   packages: {
     compiler: {
-      version: "0.40.1"
+      version: "0.42.0"
     },
     app: {
-      version: "0.23.0",
+      version: "0.24.0",
       dependencies: {
         rxjs: "7.8.2"
       }
     },
     elysia: {
-      version: "0.27.1"
+      version: "0.29.0"
     },
     commands: {
       version: "0.9.1"
@@ -249734,6 +250251,7 @@ function baseFiles(name, sdkDependencies) {
       dependencies: {
         "@supacloud/app": `^${appMetadata.version}`,
         "@supacloud/elysia": `^${elysiaMetadata.version}`,
+        effect: "4.0.2",
         elysia: "2.0.0-beta.21",
         ...sdkDependencies ?? { rxjs: appMetadata.dependencies.rxjs }
       },
@@ -249778,6 +250296,16 @@ export default defineSupacloudConfig({
   outDir: "generated",
   strict: true,
   moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true,
+    requireTaggedErrorTypes: true,
+    requireExactDependencyTypes: true,
+    requireTimeoutForDependencies: true,
+    forbidDirectRuntimeExecution: true,
+    forbidDirectThrows: true,
+  },
   typeSafety: { scanProductionSource: true, noAnyInGenerated: true },
   disallowControllerDirectDb: true,
   detectOrphanModules: true,
@@ -249806,20 +250334,34 @@ export const CreateOrderBody = t.Object({ name: t.String({ minLength: 1 }) });
 export const OrderResult = t.Object({ id: t.String(), name: t.String() });
 export const HealthResult = t.Object({ ok: t.Boolean() });
 `,
-    "src/orders/orders.ts": `import { Body, Controller, Get, Param, Post, defineFeatureSlice } from "@supacloud/app";
+    "src/orders/orders.ts": `import { Effect } from "effect";
+import { Body, Controller, Get, Param, Post, defineFeatureSlice } from "@supacloud/app";
 import { status } from "elysia";
 import { OrderParams, CreateOrderBody, OrderResult, HealthResult } from "./contracts";
 @Controller("/orders")
 export class OrdersController {
-  @Get("/health", { responses: { 200: HealthResult } })
-  health(): { ok: boolean } { return { ok: true }; }
-
-  @Get("/:id", { params: OrderParams, responses: { 200: OrderResult } })
-  get(@Param("id") id: string): { id: string; name: string } { return { id, name: "demo" }; }
-
-  @Post("/", { body: CreateOrderBody, responses: { 201: OrderResult } })
+  @Get("/health", {
+    responses: { 200: HealthResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  health(): Effect.Effect<{ ok: boolean }, never, never> { return Effect.succeed({ ok: true }); }
+
+  @Get("/:id", {
+    params: OrderParams,
+    responses: { 200: OrderResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  get(@Param("id") id: string): Effect.Effect<{ id: string; name: string }, never, never> {
+    return Effect.succeed({ id, name: "demo" });
+  }
+
+  @Post("/", {
+    body: CreateOrderBody,
+    responses: { 201: OrderResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
   create(@Body() body: { name: string }) {
-    return status(201, { id: "demo", name: body.name });
+    return Effect.succeed(status(201, { id: "demo", name: body.name }));
   }
 }
 
@@ -249993,22 +250535,27 @@ function minimalTemplate(name, sdkDependencies) {
     "src/features/health/contracts.ts": `import { t } from "elysia";
 export const HealthResult = t.Object({ ok: t.Boolean() });
 `,
-    "src/features/health/health.ts": `import { Controller, Get, Module } from "@supacloud/app/core";
+    "src/features/health/health.ts": `import { Effect } from "effect";
+import { Controller, Get, Module } from "@supacloud/app/core";
 import { HealthResult } from "./contracts";
 @Controller("/health")
 export class HealthController {
-  @Get("/", { responses: { 200: HealthResult } })
-  health(): { ok: boolean } { return { ok: true }; }
+  @Get("/", {
+    responses: { 200: HealthResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  health(): Effect.Effect<{ ok: boolean }, never, never> { return Effect.succeed({ ok: true }); }
 }
 
 @Module({ name: "health", tags: ["type:feature"], controllers: [HealthController] })
 export class HealthModule {}
 `,
-    "src/features/health/health.test.ts": `import { expect, test } from "bun:test";
+    "src/features/health/health.test.ts": `import { Effect } from "effect";
+import { expect, test } from "bun:test";
 import { HealthController } from "./health";
 
-test("health is a public, side-effect-free operation", () => {
-  expect(new HealthController().health()).toEqual({ ok: true });
+test("health is a public, side-effect-free operation", async () => {
+  expect(await Effect.runPromise(new HealthController().health())).toEqual({ ok: true });
 });
 `,
     "src/app.module.ts": `import { Module } from "@supacloud/app/core";
@@ -250533,13 +251080,25 @@ export async function createDeliveryWorker(modules: CompiledModule[], lifecycle:
 `;
 
 // src/shared/tools/app-starter-upload.ts
-var STARTER_UPLOAD_FEATURE = `import { Body, Controller, Inject, Injectable, Param, Post, DB_CLIENT, REQUEST_CONTEXT } from "@supacloud/app";
+var STARTER_UPLOAD_FEATURE = `import { Effect } from "effect";
+import { Body, Controller, Inject, Injectable, Param, Post, DB_CLIENT, REQUEST_CONTEXT } from "@supacloud/app";
 import { ApplicationError } from "@supacloud/elysia";
 import { UploadBody, UploadLocation, UploadParams, UploadResult } from "./contracts";
 
 export interface ReviewUploadInput { reviewId: string; artifactId: string; expectedVersion: number }
 export interface ReviewUploadLocation { artifactId: string; bucketId: string; objectPath: string }
 export interface ReviewUploadResult { artifactId: string; runId: string; objectPath: string; sha256: string; bytes: number }
+type PreviewUploadError =
+  | { readonly _tag: "AUTHENTICATION_REQUIRED" }
+  | { readonly _tag: "UPLOAD_INPUT_INVALID" }
+  | { readonly _tag: "UPLOAD_DENIED" }
+  | { readonly _tag: "UPLOADS_UNAVAILABLE" };
+type RegisterUploadError =
+  | PreviewUploadError
+  | { readonly _tag: "UPLOAD_CONTENT_INVALID" }
+  | { readonly _tag: "COMMAND_IDEMPOTENCY_CONFLICT" }
+  | { readonly _tag: "COMMAND_REJECTED" }
+  | { readonly _tag: "UPLOAD_OUTCOME_UNKNOWN" };
 export interface ReviewUploadPort {
   previewUpload(context: unknown, input: ReviewUploadInput): Promise<ReviewUploadLocation>;
   registerUpload(context: unknown, input: ReviewUploadInput): Promise<ReviewUploadResult>;
@@ -250563,13 +251122,47 @@ export class ReviewUploads {
 export class ReviewUploadsController {
   constructor(@Inject(ReviewUploads) private readonly uploads: ReviewUploads) {}
 
-  @Post("/:id/attachment-upload", { params: UploadParams, body: UploadBody, responses: { 200: UploadLocation } })
-  preview(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Promise<ReviewUploadLocation> {
-    return this.uploads.preview({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion });
-  }
-  @Post("/:id/attachment-registration", { params: UploadParams, body: UploadBody, responses: { 200: UploadResult } })
-  register(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Promise<ReviewUploadResult> {
-    return this.uploads.register({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion });
+  @Post("/:id/attachment-upload", {
+    params: UploadParams,
+    body: UploadBody,
+    responses: { 200: UploadLocation },
+    effect: {
+      required: true,
+      dependencies: [],
+      errors: [
+        { tag: "AUTHENTICATION_REQUIRED", status: 401, code: "AUTHENTICATION_REQUIRED" },
+        { tag: "UPLOAD_INPUT_INVALID", status: 400, code: "UPLOAD_INPUT_INVALID" },
+        { tag: "UPLOAD_DENIED", status: 403, code: "UPLOAD_DENIED" },
+        { tag: "UPLOADS_UNAVAILABLE", status: 501, code: "UPLOADS_UNAVAILABLE" },
+      ],
+      retry: "none",
+    },
+  })
+  preview(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Effect.Effect<ReviewUploadLocation, PreviewUploadError, never> {
+    return Effect.promise(() => this.uploads.preview({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion }));
+  }
+  @Post("/:id/attachment-registration", {
+    params: UploadParams,
+    body: UploadBody,
+    responses: { 200: UploadResult },
+    effect: {
+      required: true,
+      dependencies: [],
+      errors: [
+        { tag: "AUTHENTICATION_REQUIRED", status: 401, code: "AUTHENTICATION_REQUIRED" },
+        { tag: "UPLOAD_INPUT_INVALID", status: 400, code: "UPLOAD_INPUT_INVALID" },
+        { tag: "UPLOAD_DENIED", status: 403, code: "UPLOAD_DENIED" },
+        { tag: "UPLOAD_CONTENT_INVALID", status: 400, code: "UPLOAD_CONTENT_INVALID" },
+        { tag: "COMMAND_IDEMPOTENCY_CONFLICT", status: 409, code: "COMMAND_IDEMPOTENCY_CONFLICT" },
+        { tag: "COMMAND_REJECTED", status: 403, code: "COMMAND_REJECTED" },
+        { tag: "UPLOADS_UNAVAILABLE", status: 501, code: "UPLOADS_UNAVAILABLE" },
+        { tag: "UPLOAD_OUTCOME_UNKNOWN", status: 503, code: "UPLOAD_OUTCOME_UNKNOWN" },
+      ],
+      retry: "none",
+    },
+  })
+  register(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Effect.Effect<ReviewUploadResult, RegisterUploadError, never> {
+    return Effect.promise(() => this.uploads.register({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion }));
   }
 }
 `;
@@ -250853,6 +251446,10 @@ function rows(value: unknown): Record<string, unknown>[] {
   if (!Array.isArray(value)) throw new TypeError("Invalid database result");
   return value.map(record);
 }
+function isPublicConflict(value: unknown): boolean {
+  return value instanceof ApplicationError && value.status === 409
+    || isRecord(value) && value.expose === true && value.status === 409 && typeof value.code === "string";
+}
 function input(value: unknown): Approval {
   const item = record(value);
   if (typeof item.id !== "string" || !item.id.length || typeof item.expectedVersion !== "number"
@@ -250967,7 +251564,7 @@ export async function createReviewPostgresAdapters(options: ReviewPostgresOption
           execute: tx => scope.run(tx, async () => {
             try { return await next(); }
             catch (error) {
-              if (error instanceof ApplicationError && error.status === 409) {
+              if (isPublicConflict(error)) {
                 throw new CommandError("COMMAND_IDEMPOTENCY_CONFLICT");
               }
               throw error;
@@ -251276,6 +251873,7 @@ function appStarterFiles(name) {
         "drizzle-orm": dbMetadata.peerDependencies["drizzle-orm"],
         "@supacloud/js": `^${sdkMetadata.version}`,
         "@supabase/supabase-js": sdkMetadata.peerDependencies["@supabase/supabase-js"],
+        effect: "4.0.2",
         elysia: "2.0.0-beta.21",
         rxjs: appMetadata2.dependencies.rxjs
       },
@@ -251331,6 +251929,16 @@ export default defineSupacloudConfig({
   outDir: "generated",
   strict: true,
   moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true,
+    requireTaggedErrorTypes: true,
+    requireExactDependencyTypes: true,
+    requireTimeoutForDependencies: true,
+    forbidDirectRuntimeExecution: true,
+    forbidDirectThrows: true,
+  },
   typeSafety: { scanProductionSource: true, noAnyInGenerated: true },
   disallowControllerDirectDb: true,
   detectOrphanModules: true,
@@ -251531,7 +252139,8 @@ export function createCompiledModules(): never {
   throw new Error("Run bun run compile before starting the application");
 }
 `,
-    "src/review/review.ts": `import {
+    "src/review/review.ts": `import { Effect } from "effect";
+import {
   Body, Command, Controller, DB_CLIENT, Get, Inject, Param, Post,
   defineFeatureSlice, defineFeatureSpec, type Aspect,
 } from "@supacloud/app";
@@ -251597,16 +252206,51 @@ export class ApproveReview {
   }
 }
 
+type ReviewError =
+    | { readonly _tag: "AUTHENTICATION_REQUIRED" }
+    | { readonly _tag: "REVIEW_NOT_FOUND" }
+    | { readonly _tag: "REVIEW_PERMISSION_DENIED" }
+    | { readonly _tag: "REVIEW_CONFLICT" }
+    | { readonly _tag: "FEATURE_TRANSITION_CONFLICT" }
+    | { readonly _tag: "COMMAND_IDEMPOTENCY_CONFLICT" }
+    | { readonly _tag: "COMMAND_REJECTED" }
+    | { readonly _tag: "REVIEW_COMMAND_UNSUPPORTED" }
+    | { readonly _tag: "COMMAND_OUTCOME_UNKNOWN" };
+
 @Controller("/reviews")
 export class ReviewController {
   constructor(@Inject(ApproveReview) private readonly approveReview: ApproveReview) {}
 
-  @Get("/health", { responses: { 200: HealthResult } })
-  health(): { ok: boolean } { return { ok: true }; }
-
-  @Post("/:id/approve", { command: ApproveReview, params: Params, body: ApproveBody, responses: { 200: ReviewResult } })
-  approve(@Param("id") id: string, @Body() body: { expectedVersion: number }): Promise<Review> {
-    return this.approveReview.execute(id, body.expectedVersion);
+  @Get("/health", {
+    responses: { 200: HealthResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  health(): Effect.Effect<{ ok: boolean }, never, never> { return Effect.succeed({ ok: true }); }
+
+  @Post("/:id/approve", {
+    command: ApproveReview,
+    params: Params,
+    body: ApproveBody,
+    responses: { 200: ReviewResult },
+    effect: {
+      required: true,
+      dependencies: [],
+      errors: [
+        { tag: "AUTHENTICATION_REQUIRED", status: 401, code: "AUTHENTICATION_REQUIRED" },
+        { tag: "REVIEW_NOT_FOUND", status: 404, code: "REVIEW_NOT_FOUND" },
+        { tag: "REVIEW_PERMISSION_DENIED", status: 403, code: "REVIEW_PERMISSION_DENIED" },
+        { tag: "REVIEW_CONFLICT", status: 409, code: "REVIEW_CONFLICT" },
+        { tag: "FEATURE_TRANSITION_CONFLICT", status: 409, code: "FEATURE_TRANSITION_CONFLICT" },
+        { tag: "COMMAND_IDEMPOTENCY_CONFLICT", status: 409, code: "COMMAND_IDEMPOTENCY_CONFLICT" },
+        { tag: "COMMAND_REJECTED", status: 403, code: "COMMAND_REJECTED" },
+        { tag: "REVIEW_COMMAND_UNSUPPORTED", status: 501, code: "REVIEW_COMMAND_UNSUPPORTED" },
+        { tag: "COMMAND_OUTCOME_UNKNOWN", status: 503, code: "COMMAND_OUTCOME_UNKNOWN" },
+      ],
+      retry: "none",
+    },
+  })
+  approve(@Param("id") id: string, @Body() body: { expectedVersion: number }): Effect.Effect<Review, ReviewError, never> {
+    return Effect.promise(() => this.approveReview.execute(id, body.expectedVersion));
   }
 }
 
@@ -252145,7 +252789,8 @@ export class ${className}Service {
     }
 }
 `,
-    [`${name}.controller.ts`]: `import { Controller, Get, Inject, Param } from "@supacloud/app";
+    [`${name}.controller.ts`]: `import { Effect } from "effect";
+import { Controller, Get, Inject, Param } from "@supacloud/app";
 import { ${className}Params, ${className}Response, type ${className}Result } from "./${name}.model";
 import { ${className}Service } from "./${name}.service";
 
@@ -252153,9 +252798,13 @@ import { ${className}Service } from "./${name}.service";
 export class ${className}Controller {
     constructor(@Inject(${className}Service) readonly service: Pick<${className}Service, "find">) {}
 
-    @Get("/:id", { params: ${className}Params, responses: { 200: ${className}Response } })
-    find(@Param("id") id: string): Promise<${className}Result> {
-        return this.service.find(id);
+    @Get("/:id", {
+        params: ${className}Params,
+        responses: { 200: ${className}Response },
+        effect: { required: true, dependencies: [], errors: [], retry: "none" },
+    })
+    find(@Param("id") id: string): Effect.Effect<${className}Result, never, never> {
+        return Effect.promise(() => this.service.find(id));
     }
 }
 `,
@@ -252190,19 +252839,20 @@ test("${name} preserves permission denial without a privileged fallback", async
     await expect(service.find("example")).rejects.toBe(denied);
 });
 `,
-    [`${name}.controller.test.ts`]: `import { expect, test } from "bun:test";
+    [`${name}.controller.test.ts`]: `import { Effect } from "effect";
+import { expect, test } from "bun:test";
 import { ${className}Controller } from "./${name}.controller";
 
 test("${name} controller delegates to the supplied asynchronous read port", async () => {
     // Unit-test double only; the generated runtime service remains fail-closed.
     const controller = new ${className}Controller({ find: async (id) => ({ id }) });
-    expect(await controller.find("example")).toEqual({ id: "example" });
+    expect(await Effect.runPromise(controller.find("example"))).toEqual({ id: "example" });
 });
 
 test("${name} controller preserves an asynchronous read failure", async () => {
     const failure = new Error("read port unavailable");
     const controller = new ${className}Controller({ find: async () => { throw failure; } });
-    await expect(controller.find("example")).rejects.toBe(failure);
+    await expect(Effect.runPromise(controller.find("example"))).rejects.toThrow("read port unavailable");
 });
 `
   };
@@ -253726,6 +254376,91 @@ function formatReconcileReport(report) {
   return lines.join(`
 `);
 }
+function moduleObjects2(module) {
+  return [
+    ...module.tables.map((table) => ({
+      kind: "table",
+      name: table,
+      module: module.name,
+      source: null,
+      tests: []
+    })),
+    ...module.policies.map((policy) => ({
+      kind: "policy",
+      name: policy.name,
+      module: module.name,
+      table: policy.table,
+      source: policy.source,
+      tests: policy.tests ?? []
+    })),
+    ...module.functions.map((fn) => ({
+      kind: "function",
+      name: fn.name,
+      module: module.name,
+      source: fn.source,
+      tests: fn.tests ?? [],
+      security: fn.security,
+      permission: fn.permission,
+      transaction: fn.transaction,
+      audit: fn.audit,
+      idempotency: fn.idempotency
+    })),
+    ...module.triggers.map((trigger) => ({
+      kind: "trigger",
+      name: trigger.name,
+      module: module.name,
+      table: trigger.table,
+      source: trigger.source,
+      tests: []
+    })),
+    ...module.grants.map((grant) => ({
+      kind: "grant",
+      name: `${grant.object}:${grant.privilege}:${grant.role}`,
+      module: module.name,
+      source: grant.source,
+      tests: []
+    }))
+  ];
+}
+function objectMatchesTarget(object, target) {
+  return object.name === target || object.table === target || object.kind === "policy" && `${object.table}.${object.name}` === target || object.kind === "grant" && object.name.startsWith(`${target}:`);
+}
+function buildDatabaseAiContext(modules, root, moduleName, target) {
+  const selected = moduleName ? modules.filter((module) => module.name === moduleName) : [...modules];
+  if (moduleName && selected.length === 0) {
+    throw new Error(`未找到数据库模块: ${moduleName}（可用: ${modules.map((module) => module.name).join(", ") || "none"}）`);
+  }
+  const allObjects = selected.flatMap(moduleObjects2);
+  const objects = target ? allObjects.filter((object) => objectMatchesTarget(object, target)) : allObjects;
+  if (target && objects.length === 0)
+    throw new Error(`未找到数据库对象: ${target}`);
+  return {
+    version: 1,
+    scope: "database-ai-context",
+    root,
+    selectedModules: selected.map((module) => module.name),
+    target: target ?? null,
+    objects,
+    maintenance: {
+      structureSource: "drizzle",
+      behaviorSource: "sql",
+      generatedPaths: ["generated/", "bootstrap/schema.sql", "output/database-audit/"],
+      protectedPaths: ["migrations/", "supabase/migrations/", "generated/"],
+      forwardMigrationPath: "migrations/<timestamp>_<intent>.sql",
+      rules: [
+        "Edit the selected maintained source, not a generated snapshot.",
+        "Keep RPC, RLS, trigger and grant behavior in explicit SQL sources.",
+        "Create a new forward migration; never rewrite an applied migration.",
+        "Run lint, focused behavior tests and catalog reconciliation after edits."
+      ]
+    },
+    verification: [
+      "supacloud-cli db lint --module_file db/modules.ts",
+      "supacloud-cli db explain --target <object>",
+      'supacloud-cli db module_check --module_file db/modules.ts --database_url "$DATABASE_URL"'
+    ]
+  };
+}
 async function runModuleCheck(module, executor, schemas = ["public"]) {
   const catalog = await readCatalog(executor, schemas);
   return reconcileModule(module, catalog);
@@ -253769,6 +254504,10 @@ async function runExplain2(args, root) {
   const text = explainObject(manifest, target);
   return textResult2(text, text.startsWith("未找到对象"));
 }
+async function runContext2(args, root) {
+  const modules = await loadDatabaseModules(root, args.module_file);
+  return textResult2(JSON.stringify(buildDatabaseAiContext(modules, root, args.module, args.target), null, 2));
+}
 var defaultLiteSpawn = async (command, cwd) => {
   const proc = Bun.spawn({ cmd: command, cwd, stdout: "pipe", stderr: "pipe" });
   const [exitCode, stdout, stderr] = await Promise.all([
@@ -253826,12 +254565,12 @@ function registerDbGovernanceTools(server2, options = {}) {
   const environment = options.environment || process.env;
   const fallbackRoot = options.currentWorkingDirectory || process.cwd();
   const liteSpawn = options.liteSpawn || defaultLiteSpawn;
-  server2.tool("db", "Local database governance (@supacloud/db): lint declared modules, explain objects, reconcile against a live catalog or a local SupaCloud Lite project. Actions: lint, explain, module_check", {
-    action: withDescription(stringEnum(["lint", "explain", "module_check"]), "Database governance action"),
-    module: optional(String2(), "[lint] Only lint this manifest module (default: all)"),
+  server2.tool("db", "Local database governance (@supacloud/db): provide bounded AI context, lint declared modules, explain objects, reconcile against a live catalog or a local SupaCloud Lite project. Actions: context, lint, explain, module_check", {
+    action: withDescription(stringEnum(["context", "lint", "explain", "module_check"]), "Database governance action"),
+    module: optional(String2(), "[context/lint] Only select this manifest module (default: all)"),
     root: optional(String2(), "[*] Project root (default: current directory)"),
     module_file: optional(String2(), "[*] File exporting defineDatabaseModule(...) (default: <root>/db/modules.ts)"),
-    target: optional(String2(), "[explain] Policy / function / table name to explain"),
+    target: optional(String2(), "[context/explain] Policy / function / table name to explain"),
     database_url: optional(String2(), "[module_check] Postgres connection URL (default: DATABASE_URL)"),
     schema: optional(String2(), "[module_check] Comma-separated schemas to inspect (default: public)"),
     lite: optional(Boolean2(), "[module_check] Reconcile against a local SupaCloud Lite project (runs supacloud-lite db check)"),
@@ -253839,6 +254578,8 @@ function registerDbGovernanceTools(server2, options = {}) {
   }, async (request) => {
     const root = resolve25(request.root || fallbackRoot);
     switch (request.action) {
+      case "context":
+        return runContext2(request, root);
       case "lint":
         return runLint(request, root);
       case "explain":
@@ -256652,7 +257393,7 @@ function registerRemoteDevTools(server2, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.72.0",
+  version: "0.74.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -256686,7 +257427,7 @@ var package_default = {
     directory: "packages/cli"
   },
   dependencies: {
-    "@supacloud/compiler": "^0.40.1",
+    "@supacloud/compiler": "^0.42.0",
     "@supacloud/delivery": "0.8.0",
     "@supacloud/db": "^0.14.0",
     fflate: "^0.8.3",
@@ -256699,6 +257440,7 @@ var package_default = {
   devDependencies: {
     "@supacloud/elysia": "^0.24.1",
     "@types/bun": "^1.4.2",
+    effect: "4.0.2",
     elysia: "2.0.0-beta.21",
     typescript: "^7.0.2"
   }
@@ -256981,6 +257723,8 @@ EXAMPLES
   ${preferredCommand} context --format json
   ${preferredCommand} context --target CaseModule --format json
   ${preferredCommand} doctor
+  ${preferredCommand} db context --root . --module_file db/modules.ts --module cases
+  ${preferredCommand} db context --root . --module_file db/modules.ts --target public.case_create
   ${preferredCommand} db lint --root . --module_file db/modules.ts
   ${preferredCommand} db explain --target public.cases --module_file db/modules.ts
   ${preferredCommand} db module_check --module_file db/modules.ts --database_url "postgresql://..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "directory": "packages/cli"
   },
   "dependencies": {
-    "@supacloud/compiler": "^0.40.1",
+    "@supacloud/compiler": "^0.42.0",
     "@supacloud/delivery": "0.8.0",
     "@supacloud/db": "^0.14.0",
     "fflate": "^0.8.3",
@@ -47,6 +47,7 @@
   "devDependencies": {
     "@supacloud/elysia": "^0.24.1",
     "@types/bun": "^1.4.2",
+    "effect": "4.0.2",
     "elysia": "2.0.0-beta.21",
     "typescript": "^7.0.2"
   }

package/skills/supacloud-cli/SKILL.md

@@ -31,12 +31,21 @@ Use `supacloud-cli` as the project-level control surface and keep durable change
 
 1. Classify the request using [references/command-map.md](references/command-map.md).
 2. For database work, load [references/database-workflow.md](references/database-workflow.md) and choose either new-change or historical-drift reconciliation.
-3. Prefer the smallest read-only inspection that proves current state.
-4. Create or update version-controlled artifacts before remote writes.
-5. Verify locally, inspect the diff, and run the narrowest relevant tests.
-6. Preview remote changes with `--dry_run`.
-7. Apply only within the user-authorized environment and scope.
-8. Read back migration history and affected resources; report exact evidence and any remaining drift.
+3. For AI-assisted database changes, first request bounded context:
+
+   ```bash
+   supacloud-cli db context --module_file db/modules.ts --module <module>
+   supacloud-cli db context --module_file db/modules.ts --target <object>
+   ```
+
+   Use the returned source/test paths and ownership boundary; do not scan or
+   edit the complete schema dump.
+4. Prefer the smallest read-only inspection that proves current state.
+5. Create or update version-controlled artifacts before remote writes.
+6. Verify locally, inspect the diff, and run the narrowest relevant tests.
+7. Preview remote changes with `--dry_run`.
+8. Apply only within the user-authorized environment and scope.
+9. Read back migration history and affected resources; report exact evidence and any remaining drift.
 
 ## Project endpoint inspection