@supacloud/compiler 0.48.0 → 0.49.0

package/dist/cli.js

@@ -249,6 +249,10 @@ function findClosestMatch(target, candidates) {
 var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context", JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
 
 // src/feature.ts
+function featureTransitionForRoute(module, controller, route) {
+  const routePath = `${route.method} ${joinRoutePaths(controller.path, route.path)}`;
+  return module.featureSpec?.transitions.find((transition) => transition.route === routePath);
+}
 function validateFeatureSpec(spec, module) {
   const diagnostics = [];
   const error = (code, message) => {
@@ -278,6 +282,11 @@ function validateFeatureSpec(spec, module) {
     if (transition.permission !== undefined && !transition.permission.trim()) {
       error("feature-governance-drift", `Transition ${transition.name} declares an empty permission.`);
     }
+    if (transition.invalidateTags !== undefined) {
+      if (transition.invalidateTags.length === 0 || transition.invalidateTags.some((tag) => !tag.trim()) || new Set(transition.invalidateTags).size !== transition.invalidateTags.length) {
+        error("feature-invalidation-tags-invalid", `Transition ${transition.name} must declare unique, non-empty invalidateTags.`);
+      }
+    }
     if (transition.persistence) {
       const persistence = transition.persistence;
       if (persistence.boundary === "database" && (persistence.optimisticLock !== "required" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(persistence.versionField ?? "") || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(persistence.tenantField ?? "") || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(persistence.stateField ?? "") || new Set([persistence.tenantField, persistence.versionField, persistence.stateField]).size !== 3 || persistence.receipt !== "required" || persistence.reconciliation !== "none")) {
@@ -370,7 +379,7 @@ function validateFeatureSpec(spec, module) {
       const routes = module.controllers.flatMap((controller) => controller.routes.filter((route) => `${route.method} ${joinRoutePaths(controller.path, route.path)}` === transition.route));
       if (routes.length !== 1) {
         error("feature-route-unresolved", `Transition ${transition.name} must reference exactly one route '${transition.route}' in module ${module.name}.`);
-      } else if (command && transition.routeBinding !== "controller" && routes[0]?.command !== command.className) {
+      } else if (command && transition.routeBinding !== "controller" && routes[0]?.command !== command.className && routes[0]?.command !== command.name) {
         error("feature-route-drift", `Route ${transition.route} is not bound to ${command.className}.`);
       } else if (transition.routeBinding === "controller" && routes[0]?.command !== undefined) {
         error("feature-route-drift", `Controller-bound route ${transition.route} must not also declare a framework command binding.`);
@@ -615,13 +624,17 @@ function validateGraph(graph, options = false) {
           handler: route.handler,
           ...route.redirectTo === undefined ? {} : { redirectTo: route.redirectTo }
         });
-        if (route.command && !module.commands.some((command) => command.className === route.command)) {
-          error("route-command-unresolved", `路由 ${key} 绑定的 command 类 ${route.command} 未在模块 ${module.name} 声明`, controller.file);
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const effectiveCommandRef = route.command ?? featureTransition?.command;
+        const effectiveCommand = effectiveCommandRef === undefined ? undefined : module.commands.find((command) => command.className === effectiveCommandRef || command.name === effectiveCommandRef);
+        const effectiveIdempotency = route.idempotency ?? featureTransition?.idempotency;
+        if (route.command && !effectiveCommand) {
+          error("route-command-unresolved", `路由 ${key} 绑定的 command ${route.command} 未在模块 ${module.name} 声明`, controller.file);
         }
-        if ((route.method === "GET" || route.method === "HEAD") && route.command) {
-          const boundCommand = module.commands.find((c) => c.className === route.command);
+        if ((route.method === "GET" || route.method === "HEAD") && effectiveCommand) {
+          const boundCommand = effectiveCommand;
           if (boundCommand && boundCommand.transaction === "required") {
-            error("command-transaction-readonly", `GET route '${route.path}' in '${controller.className}.${route.handler}' binds mutating command '${route.command}' with transaction: 'required'. Mutating transactions are not permitted on read-only HTTP GET requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for mutating command routes, or set transaction: 'none'.`);
+            error("command-transaction-readonly", `GET route '${route.path}' in '${controller.className}.${route.handler}' binds mutating command '${boundCommand.name}' with transaction: 'required'. Mutating transactions are not permitted on read-only HTTP GET requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for mutating command routes, or set transaction: 'none'.`);
           }
         }
         if (typeof options === "object" && options.allowRouteCommandBindings === false && route.command) {
@@ -692,6 +705,9 @@ function validateGraph(graph, options = false) {
         if (route.allowDeleteBody && (route.method !== "DELETE" || !route.body)) {
           error("invalid-delete-body-opt-in", `Route ${controller.className}.${route.handler} allowDeleteBody requires DELETE and an explicit body schema.`, controller.file);
         }
+        if (effectiveIdempotency === "required" && (route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS")) {
+          error("invalid-route-idempotency", `Route ${controller.className}.${route.handler} cannot require idempotency on HTTP ${route.method}.`, controller.file, undefined, `Use idempotency: "required" only on a mutation route.`);
+        }
         if (route.parse === "none" && (route.body || route.hasBodyBinding || route.contract?.body !== "domain" || !route.contract.evidence?.trim())) {
           error("invalid-raw-body-contract", `Route ${controller.className}.${route.handler} parse: "none" requires domain body ownership and evidence, without a parsed body schema or @Body binding.`, controller.file);
         }
@@ -1366,6 +1382,7 @@ var init_validate = __esm(() => {
     "command-transaction-unsupported": { code: "SC4026", docsUrl: "https://supacloud.dev/errors/SC4026" },
     "command-reconcile-required": { code: "SC4028", docsUrl: "https://supacloud.dev/errors/SC4028" },
     "invalid-route-contract": { code: "SC3020", docsUrl: "https://supacloud.dev/errors/SC3020" },
+    "invalid-route-idempotency": { code: "SC3028", docsUrl: "https://supacloud.dev/errors/SC3028" },
     "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" },
@@ -1512,6 +1529,7 @@ function buildContractManifest(graph, artifacts) {
             ...transition.idempotency === undefined ? {} : { idempotency: transition.idempotency },
             ...transition.audit === undefined ? {} : { audit: transition.audit },
             ...transition.job === undefined ? {} : { job: transition.job },
+            ...transition.invalidateTags === undefined ? {} : { invalidateTags: [...transition.invalidateTags] },
             ...job === undefined ? {} : {
               jobDetails: {
                 name: job.name,
@@ -1532,9 +1550,14 @@ function buildContractManifest(graph, artifacts) {
     }
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
-        const command = route.command ? module.commands.find((candidate) => candidate.className === route.command) : undefined;
-        if (command?.permission)
-          permissions.add(command.permission);
+        const command = route.command ? module.commands.find((candidate) => candidate.className === route.command || candidate.name === route.command) : undefined;
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const featureCommand = featureTransition?.command === undefined ? undefined : module.commands.find((candidate) => candidate.className === featureTransition.command || candidate.name === featureTransition.command);
+        const governedCommand = command ?? featureCommand;
+        const effectiveCommand = route.command ?? featureTransition?.command;
+        const idempotency = route.idempotency ?? command?.idempotency ?? featureTransition?.idempotency;
+        if (governedCommand?.permission)
+          permissions.add(governedCommand.permission);
         if (route.contract?.evidence)
           fixtures.add(route.contract.evidence);
         routes.push({
@@ -1543,8 +1566,10 @@ function buildContractManifest(graph, artifacts) {
           module: module.name,
           controller: controller.className,
           handler: route.handler,
-          ...route.command === undefined ? {} : { command: route.command },
-          ...command?.permission === undefined ? {} : { permission: command.permission },
+          ...effectiveCommand === undefined ? {} : { command: effectiveCommand },
+          ...governedCommand?.permission === undefined ? {} : { permission: governedCommand.permission },
+          ...idempotency === undefined ? {} : { idempotency },
+          ...route.tags === undefined ? {} : { tags: [...route.tags] },
           requestSchemas: Object.fromEntries(["body", "params", "query", "headers", "cookie"].flatMap((key) => route[key] === undefined ? [] : [[key, route[key]]])),
           ...route.response === undefined ? {} : { responseSchema: route.response },
           ...route.responses === undefined ? {} : {
@@ -1583,7 +1608,9 @@ function buildContractManifest(graph, artifacts) {
     }
   };
 }
-var init_contract_manifest = () => {};
+var init_contract_manifest = __esm(() => {
+  init_feature();
+});
 
 // src/generate.ts
 import { createHash as createHash4 } from "node:crypto";
@@ -1995,6 +2022,9 @@ class ModuleGenerator {
       return "[]";
     const items = this.module.controllers.map((controller) => {
       const routes = controller.routes.map((route) => {
+        const command = route.command === undefined ? undefined : this.module.commands.find((candidate) => candidate.className === route.command || candidate.name === route.command);
+        const featureTransition = featureTransitionForRoute(this.module, controller, route);
+        const idempotency = route.idempotency ?? command?.idempotency ?? featureTransition?.idempotency;
         const responseEntries = normalizedResponseEntries(route.responses);
         const hasResponseMap = responseEntries.length > 0;
         const fields = [
@@ -2021,6 +2051,9 @@ class ModuleGenerator {
         if (route.effect !== undefined) {
           fields.push(`effect: ${JSON.stringify(route.effect)}`);
         }
+        if (idempotency !== undefined) {
+          fields.push(`idempotency: ${JSON.stringify(idempotency)}`);
+        }
         if (route.command)
           fields.push(`command: ${JSON.stringify(route.command)}`);
         if (route.guards && route.guards.length > 0) {
@@ -2503,7 +2536,18 @@ function renderClient(graph, options) {
   const usedTypeNames = new Set;
   const allRoutes = [];
   const allProcedures = [];
-  const commandByClassName = new Map(graph.modules.flatMap((module) => module.commands.map((command) => [command.className, command])));
+  const commandByClassName = new Map(graph.modules.flatMap((module) => module.commands.flatMap((command) => [
+    [command.className, command],
+    [command.name, command]
+  ])));
+  const featureInvalidationTags = new Map;
+  for (const module of graph.modules) {
+    for (const transition of module.featureSpec?.transitions ?? []) {
+      if (transition.route && transition.invalidateTags) {
+        featureInvalidationTags.set(`${module.name}:${transition.route}`, [...transition.invalidateTags]);
+      }
+    }
+  }
   let usesStatic = false;
   let usesValue = false;
   const uniqueTypeName = (candidate) => {
@@ -2581,6 +2625,13 @@ function renderClient(graph, options) {
         const requestType = `ClientRequestOptions<${paramsType}, ${queryType}, ${bodyType}, ${headersType}, ${cookieType}>${requiredRequestFields.length > 0 ? ` & { ${requiredRequestFields.join("; ")} }` : ""}`;
         routeTypes.push(`export type ${requestTypeName} = ${requestType};`);
         routeTypes.push(`export type ${responseTypeName} = ${responseType === "never" ? "unknown" : responseType};`);
+        const command = route.command === undefined ? undefined : commandByClassName.get(route.command);
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const featureCommand = featureTransition?.command === undefined ? undefined : commandByClassName.get(featureTransition.command);
+        const governedCommand = command ?? featureCommand;
+        const idempotencyMode = route.idempotency ?? command?.idempotency ?? featureTransition?.idempotency ?? "none";
+        const transitionRoute = `${route.method} ${fullPath}`;
+        const invalidationTags = featureInvalidationTags.get(`${module.name}:${transitionRoute}`);
         const routeFields = [
           `method: ${JSON.stringify(route.method)}`,
           `path: ${JSON.stringify(fullPath)}`,
@@ -2588,7 +2639,7 @@ function renderClient(graph, options) {
           `handler: ${JSON.stringify(route.handler)}`
         ];
         for (const [key, value] of [
-          ["command", route.command],
+          ["command", route.command ?? featureTransition?.command],
           ["guards", route.guards],
           ["canMatch", route.canMatch],
           ["canDeactivate", route.canDeactivate],
@@ -2602,7 +2653,10 @@ function renderClient(graph, options) {
           ["title", route.title],
           ["data", route.data],
           ["parse", route.parse],
-          ["allowDeleteBody", route.allowDeleteBody]
+          ["allowDeleteBody", route.allowDeleteBody],
+          ["idempotency", idempotencyMode === "none" ? undefined : idempotencyMode],
+          ["tags", route.tags],
+          ["invalidateTags", invalidationTags]
         ]) {
           if (value !== undefined)
             routeFields.push(`${key}: ${JSON.stringify(value)}`);
@@ -2635,9 +2689,7 @@ function renderClient(graph, options) {
         const responseSchemaEntries = hasResponseMap ? Object.entries(responseSchemas).map(([status, ref]) => [status, ref.local]) : responseSchema ? [["200", responseSchema.local]] : [];
         const responseSchemaArgument = responseSchemaEntries.length > 0 ? `{ ${responseSchemaEntries.map(([status, local]) => `${JSON.stringify(status)}: ${local}`).join(", ")} }` : "undefined";
         const responseKindArgument = responseKind === undefined ? "undefined" : JSON.stringify(responseKind);
-        const command = route.command === undefined ? undefined : commandByClassName.get(route.command);
         const procedureKind = route.method === "GET" || route.method === "HEAD" ? "query" : "mutation";
-        const idempotencyMode = command?.idempotency ?? "none";
         const procedureMetadata = {
           key: `${controller.className}.${route.handler}`,
           method: route.method,
@@ -2645,7 +2697,9 @@ function renderClient(graph, options) {
           controller: controller.className,
           handler: route.handler,
           kind: procedureKind,
-          idempotency: idempotencyMode
+          idempotency: idempotencyMode,
+          ...route.tags === undefined ? {} : { tags: route.tags },
+          ...invalidationTags === undefined ? {} : { invalidateTags: invalidationTags }
         };
         allProcedures.push({
           method: route.method,
@@ -2653,9 +2707,11 @@ function renderClient(graph, options) {
           controller: controller.className,
           handler: route.handler,
           kind: procedureKind,
-          ...command?.name === undefined ? {} : { command: command.name },
-          ...command?.permission === undefined ? {} : { permission: command.permission },
-          idempotency: idempotencyMode
+          ...governedCommand?.name === undefined ? {} : { command: governedCommand.name },
+          ...governedCommand?.permission === undefined ? {} : { permission: governedCommand.permission },
+          idempotency: idempotencyMode,
+          ...route.tags === undefined ? {} : { tags: [...route.tags] },
+          ...invalidationTags === undefined ? {} : { invalidateTags: [...invalidationTags] }
         });
         routeMethods.push(`
     ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}, ${JSON.stringify(procedureKind)}, ${JSON.stringify(idempotencyMode)}, ${JSON.stringify(procedureMetadata)}),`);
@@ -2709,6 +2765,8 @@ ${procedureMethods.join(`
     "  handler: string;",
     "  kind: Kind;",
     "  idempotency: Idempotency;",
+    "  tags?: readonly string[];",
+    "  invalidateTags?: readonly string[];",
     "}",
     "",
     "export interface ProcedureExecutionOptions {",
@@ -2814,6 +2872,8 @@ ${procedureMethods.join(`
     "  command?: string;",
     "  permission?: string;",
     "  idempotency: IdempotencyMode;",
+    "  tags?: readonly string[];",
+    "  invalidateTags?: readonly string[];",
     "}",
     "",
     ...routeTypes,
@@ -3313,7 +3373,10 @@ function renderOpenApi(graph, options) {
     }
     return schemaComponents.get(key);
   };
-  const commandByClass = new Map(graph.modules.flatMap((module) => module.commands.map((command) => [command.className, command])));
+  const commandByClass = new Map(graph.modules.flatMap((module) => module.commands.flatMap((command) => [
+    [command.className, command],
+    [command.name, command]
+  ])));
   for (const module of graph.modules) {
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
@@ -3335,7 +3398,12 @@ function renderOpenApi(graph, options) {
         const operationBase = pascalName(`${module.name}_${controller.className}_${route.handler}`);
         const operationId = uniqueName(operationBase, operationIds);
         const command = route.command ? commandByClass.get(route.command) : undefined;
-        const requiresAuth = (route.guards?.length ?? 0) > 0 || command !== undefined;
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const featureCommand = featureTransition?.command === undefined ? undefined : commandByClass.get(featureTransition.command);
+        const governedCommand = command ?? featureCommand;
+        const idempotencyMode = route.idempotency ?? command?.idempotency ?? featureTransition?.idempotency ?? "none";
+        const permission = governedCommand?.permission ?? featureTransition?.permission;
+        const requiresAuth = (route.guards?.length ?? 0) > 0 || permission !== undefined || governedCommand !== undefined;
         const responseKind = route.contract?.response;
         const responseContentType = responseKind === "binary" || responseKind === "stream" ? "application/octet-stream" : "application/json";
         const definition = {
@@ -3360,11 +3428,12 @@ function renderOpenApi(graph, options) {
           responseKind: responseKind ?? (route.nativeResponse ? "native-response" : undefined),
           ...route.parse === undefined ? {} : { parse: route.parse },
           ...route.allowDeleteBody === undefined ? {} : { allowDeleteBody: route.allowDeleteBody },
+          ...idempotencyMode === "none" ? {} : { idempotency: idempotencyMode },
           module: module.name,
           controller: controller.className,
           handler: route.handler,
-          ...route.command === undefined ? {} : { command: route.command },
-          ...command?.permission === undefined ? {} : { permission: command.permission },
+          ...route.command === undefined && featureTransition?.command === undefined ? {} : { command: route.command ?? featureTransition?.command },
+          ...permission === undefined ? {} : { permission },
           ...route.guards && route.guards.length > 0 ? { guards: route.guards } : {},
           ...route.canMatch && route.canMatch.length > 0 ? { canMatch: route.canMatch } : {},
           ...route.canDeactivate && route.canDeactivate.length > 0 ? { canDeactivate: route.canDeactivate } : {},
@@ -3439,6 +3508,7 @@ function renderOpenApi(graph, options) {
     "  handler: string;",
     "  command?: string;",
     "  permission?: string;",
+    '  idempotency?: "required" | "none";',
     "  guards?: readonly string[];",
     "  canMatch?: readonly string[];",
     "  canDeactivate?: readonly string[];",
@@ -3691,6 +3761,18 @@ function renderOpenApi(graph, options) {
     "  for (const name of headersSchema ? schemaPropertyNames(headersSchema) : []) parameters.push({",
     '    name, in: "header", required: schemaRequired(headersSchema, name), schema: schemaProperty(headersSchema, name),',
     "  });",
+    '  if (definition.idempotency === "required") {',
+    '    const keySchema = { type: "string", minLength: 1, maxLength: 512, pattern: "^[A-Za-z0-9._:-]{1,512}$" };',
+    '    const declaredHeaders = parameters.filter((parameter) => parameter["in"] === "header" && typeof parameter["name"] === "string" && parameter["name"].toLowerCase() === "idempotency-key");',
+    "    const header = declaredHeaders[0];",
+    "    if (header) {",
+    '      header["required"] = true;',
+    '      header["schema"] = { allOf: [...declaredHeaders.map((parameter) => parameter["schema"]), keySchema] };',
+    "      for (const duplicate of declaredHeaders.slice(1)) parameters.splice(parameters.indexOf(duplicate), 1);",
+    "    } else {",
+    '      parameters.push({ name: "Idempotency-Key", in: "header", required: true, schema: keySchema });',
+    "    }",
+    "  }",
     "  const cookieSchema = definition.cookieSchema ? OPENAPI_SCHEMA_REGISTRY[definition.cookieSchema as keyof typeof OPENAPI_SCHEMA_REGISTRY] : undefined;",
     "  for (const name of cookieSchema ? schemaPropertyNames(cookieSchema) : []) parameters.push({",
     '    name, in: "cookie", required: schemaRequired(cookieSchema, name), schema: schemaProperty(cookieSchema, name),',
@@ -3713,6 +3795,7 @@ function renderOpenApi(graph, options) {
     '    responses["500"] = { description: "Internal server error", content: { "application/json": { schema: { $ref: "#/components/schemas/SupaCloudError" } } } };',
     '    responses["200"] = { description: "Successful response" };',
     "  }",
+    '  if (definition.idempotency === "required" && (!definition.responseSchemas || !responseMapCoversStatus(definition.responseSchemas, 400))) responses["400"] = { description: "Idempotency-Key is missing or invalid", content: { "application/json": { schema: { $ref: "#/components/schemas/SupaCloudError" } } } };',
     "  const operation: Record<string, unknown> = {",
     "    operationId: definition.operationId, tags: [...definition.tags], summary: definition.summary, responses,",
     "    ...(parameters.length === 0 ? {} : { parameters }),",
@@ -3723,6 +3806,7 @@ function renderOpenApi(graph, options) {
     "      module: definition.module, controller: definition.controller, handler: definition.handler,",
     "      ...(definition.command ? { command: definition.command } : {}),",
     "      ...(definition.permission ? { permission: definition.permission } : {}),",
+    "      ...(definition.idempotency ? { idempotency: definition.idempotency } : {}),",
     "      ...(definition.guards ? { guards: [...definition.guards] } : {}),",
     "      ...(definition.canMatch ? { canMatch: [...definition.canMatch] } : {}),",
     "      ...(definition.canDeactivate ? { canDeactivate: [...definition.canDeactivate] } : {}),",
@@ -3773,11 +3857,13 @@ function renderPermissions(graph) {
     }
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
-        let perm;
-        if (route.command) {
-          const cmd = module.commands.find((c) => c.className === route.command);
-          perm = cmd?.permission;
-        }
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const command = route.command === undefined ? undefined : module.commands.find((candidate) => candidate.className === route.command || candidate.name === route.command);
+        const featureCommand = featureTransition?.command === undefined ? undefined : module.commands.find((candidate) => candidate.className === featureTransition.command || candidate.name === featureTransition.command);
+        const governedCommand = command ?? featureCommand;
+        const effectiveCommand = route.command ?? featureTransition?.command;
+        const perm = governedCommand?.permission ?? featureTransition?.permission;
+        const idempotency = route.idempotency ?? command?.idempotency ?? featureTransition?.idempotency;
         if (perm)
           permissions.add(perm);
         bindings.push({
@@ -3785,8 +3871,9 @@ function renderPermissions(graph) {
           path: joinRoutePaths(controller.path, route.path),
           controller: controller.className,
           handler: route.handler,
-          ...route.command === undefined ? {} : { command: route.command },
-          ...perm === undefined ? {} : { permission: perm }
+          ...effectiveCommand === undefined ? {} : { command: effectiveCommand },
+          ...perm === undefined ? {} : { permission: perm },
+          ...idempotency === undefined ? {} : { idempotency }
         });
       }
     }
@@ -3812,6 +3899,7 @@ function renderPermissions(graph) {
     "  handler: string;",
     "  command?: string;",
     "  permission?: string;",
+    '  idempotency?: "required" | "none";',
     "}",
     "",
     "export const RoutePermissions: RoutePermissionBinding[] = " + JSON.stringify(bindings, null, 2) + ";",
@@ -3855,6 +3943,8 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
   /** True when the handler returns a native Response rather than a framework value. */
   nativeResponse?: boolean;
   command?: string;
+  /** Transport-level idempotency contract, independent of route command binding. */
+  idempotency?: "required" | "none";
   guards?: string[];
   canMatch?: string[];
   canDeactivate?: string[];
@@ -4092,6 +4182,7 @@ async function destroyServiceInstances(
 `;
 var init_generate = __esm(() => {
   init_contract_manifest();
+  init_feature();
 });
 
 // src/route-contracts.ts
@@ -4945,7 +5036,9 @@ function createExecutionPlans(graph) {
   const aspects = (boundary, refs = []) => refs.map((ref, index) => `${boundary}.aspect[${index}]:${ref.name}`);
   return graph.modules.flatMap((module) => [
     ...module.controllers.flatMap((controller) => controller.routes.map((route) => {
-      const command = module.commands.find((item) => item.className === route.command);
+      const featureTransition = featureTransitionForRoute(module, controller, route);
+      const commandRef = route.command ?? featureTransition?.command;
+      const command = module.commands.find((item) => item.className === commandRef || item.name === commandRef);
       const path = `${controller.path}/${route.path}`.replace(/\/+/g, "/");
       return {
         module: module.name,
@@ -5095,6 +5188,7 @@ function exportGraphDot(graph) {
 }
 var init_inspect = __esm(() => {
   init_route_contracts();
+  init_feature();
 });
 
 // node_modules/typebox/build/system/memory/metrics.mjs
@@ -15662,6 +15756,7 @@ var init_application_development = __esm(() => {
       controller: text2,
       handler: text2,
       command: Optional(text2),
+      idempotency: Optional(mode),
       aspects: texts,
       schemaKinds: Optional(_Object_({
         body: schemaKind,
@@ -15784,7 +15879,11 @@ function createApplicationDevelopmentContext(graph, options = {}) {
     for (const controller of module.controllers) {
       for (const route of controller.routes) {
         const candidates = module.commands.filter((command) => command.className === route.command || command.name === route.command);
-        const command = candidates.length === 1 ? candidates[0]?.name : undefined;
+        const commandNode = candidates.length === 1 ? candidates[0] : undefined;
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const featureCommandNode = featureTransition?.command === undefined ? undefined : module.commands.find((candidate) => candidate.className === featureTransition.command || candidate.name === featureTransition.command);
+        const command = commandNode?.name ?? featureCommandNode?.name;
+        const idempotency = route.idempotency ?? commandNode?.idempotency ?? featureTransition?.idempotency;
         const kinds = schemaKinds(route);
         routes.push({
           module: module.name,
@@ -15793,6 +15892,7 @@ function createApplicationDevelopmentContext(graph, options = {}) {
           controller: controller.className,
           handler: route.handler,
           ...command === undefined ? {} : { command },
+          ...idempotency === undefined ? {} : { idempotency },
           aspects: (route.aspects ?? []).map((aspect) => aspect.name),
           ...kinds === undefined ? {} : { schemaKinds: kinds }
         });
@@ -15913,6 +16013,7 @@ var init_application_development2 = __esm(() => {
   init_application_development();
   init_inspect();
   init_execution_snapshot();
+  init_feature();
   APPLICATION_DEVELOPMENT_LIMITS2 = APPLICATION_DEVELOPMENT_LIMITS;
   ApplicationDevelopmentError = class ApplicationDevelopmentError extends Error {
     code;
@@ -16014,7 +16115,7 @@ function parseDeliveryPlanResult(value) {
     throw new Error("Invalid delivery plan result.");
   return value;
 }
-var objectOptions, reference2, references, kind2, isolation, DeliveryFilePathSchema, functionTarget, DeliveryOptionsSchema, DeliveryDiagnosticSchema, routeSchema, jobSchema, DeliveryTargetSchema, DeliveryPlanSchema, DeliveryPlanResultSchema, DeliveryConfigurationError;
+var objectOptions, reference2, references, kind2, isolation, mode2, DeliveryFilePathSchema, functionTarget, DeliveryOptionsSchema, DeliveryDiagnosticSchema, routeSchema, jobSchema, DeliveryTargetSchema, DeliveryPlanSchema, DeliveryPlanResultSchema, DeliveryConfigurationError;
 var init_delivery_schema = __esm(() => {
   init_build();
   init_value2();
@@ -16024,6 +16125,7 @@ var init_delivery_schema = __esm(() => {
   references = _Array_(reference2, { uniqueItems: true });
   kind2 = Union([Literal("api"), Literal("jobs"), Literal("webhook"), Literal("function")]);
   isolation = Union([Literal("shared"), Literal("process")]);
+  mode2 = Union([Literal("required"), Literal("none")]);
   DeliveryFilePathSchema = String2({
     maxLength: 512,
     pattern: "^(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*$"
@@ -16097,6 +16199,7 @@ var init_delivery_schema = __esm(() => {
     ]),
     path: String2(),
     command: Optional(String2()),
+    idempotency: Optional(mode2),
     reason: Union([Literal("default-http"), Literal("explicit-module")])
   }, objectOptions);
   jobSchema = _Object_({
@@ -16355,7 +16458,12 @@ function parseDeliveryBuildManifest(value) {
       throw new Error("Invalid delivery object inventory.");
     }
   }
-  const routes = value.plan.targets.flatMap((target) => target.routes.map((route) => ({ method: route.method, path: route.path, target: target.name })));
+  const routes = value.plan.targets.flatMap((target) => target.routes.map((route) => ({
+    method: route.method,
+    path: route.path,
+    target: target.name,
+    ...route.idempotency === undefined ? {} : { idempotency: route.idempotency }
+  })));
   const jobs = value.plan.targets.flatMap((target) => target.jobs.map((job) => ({ name: job.name, target: target.name })));
   if (canonical2(value.routes) !== canonical2(routes) || canonical2(value.jobs) !== canonical2(jobs)) {
     throw new Error("Delivery mappings do not match planned ownership.");
@@ -16406,7 +16514,8 @@ var init_delivery_build_schema = __esm(() => {
     routes: _Array_(_Object_({
       method: String2(),
       path: String2(),
-      target: String2()
+      target: String2(),
+      idempotency: Optional(Union([Literal("required"), Literal("none")]))
     }, closed4)),
     jobs: _Array_(_Object_({ name: String2(), target: String2() }, closed4))
   }, closed4);
@@ -19536,6 +19645,10 @@ function parseFeatureSpec(input, ctx, seen = new Set) {
     const idempotency = commandModeProp(options, "idempotency");
     const audit = stringLiteralProp(options, "audit");
     const job = stringLiteralProp(options, "job");
+    const invalidateTagsExpr = getProp(options, "invalidateTags");
+    const invalidateTags = invalidateTagsExpr === undefined ? undefined : ts7.isArrayLiteralExpression(invalidateTagsExpr) && invalidateTagsExpr.elements.every((element) => ts7.isStringLiteral(element) && element.text.trim().length > 0) ? invalidateTagsExpr.elements.map((element) => element.text) : undefined;
+    if (invalidateTagsExpr !== undefined && invalidateTags === undefined)
+      return invalid();
     const persistenceExpr = getProp(options, "persistence");
     const persistence = persistenceExpr && ts7.isObjectLiteralExpression(persistenceExpr) ? parseFeaturePersistence(persistenceExpr) : undefined;
     if (persistenceExpr && !persistence)
@@ -19552,6 +19665,7 @@ function parseFeatureSpec(input, ctx, seen = new Set) {
       ...idempotency === undefined ? {} : { idempotency },
       ...audit === undefined ? {} : { audit },
       ...job === undefined ? {} : { job },
+      ...invalidateTags === undefined ? {} : { invalidateTags },
       ...persistence === undefined ? {} : { persistence }
     });
   }
@@ -19654,6 +19768,54 @@ function checkedCommandMode(object, property, ctx, command) {
   }
   return value;
 }
+function checkedRouteIdempotency(object, ctx, route) {
+  const expression = getProp(object, "idempotency");
+  const value = stringLiteralProp(object, "idempotency");
+  if (expression && value !== "required" && value !== "none") {
+    const file = sourcePath(ctx.rootDir, expression.getSourceFile().fileName);
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-route-idempotency",
+      errorCode: "SC3028",
+      docsUrl: "https://supacloud.dev/errors/SC3028",
+      message: `${route}.idempotency must be the explicit literal "required" or "none".`,
+      file,
+      line: lineOf(expression),
+      suggestion: `Choose the intended idempotency policy explicitly; use "required" for replayable mutations or "none" for routes without that contract.`
+    });
+  }
+  return value === "required" || value === "none" ? value : undefined;
+}
+function checkedRouteTags(expression, ctx, route) {
+  if (expression === undefined)
+    return;
+  if (!ts7.isArrayLiteralExpression(expression) || expression.elements.some((element) => !ts7.isStringLiteral(element) || element.text.trim().length === 0)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-route-tags",
+      errorCode: "SC3029",
+      docsUrl: "https://supacloud.dev/errors/SC3029",
+      message: `${route}.tags must be a static array of non-empty string literals.`,
+      file: sourcePath(ctx.rootDir, expression.getSourceFile().fileName),
+      line: lineOf(expression),
+      suggestion: 'Declare stable cache tags explicitly, for example tags: ["cases.list"].'
+    });
+    return;
+  }
+  const tags = expression.elements.map((element) => element.text);
+  if (new Set(tags).size !== tags.length) {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "duplicate-route-tags",
+      errorCode: "SC3030",
+      docsUrl: "https://supacloud.dev/errors/SC3030",
+      message: `${route}.tags must not contain duplicate values.`,
+      file: sourcePath(ctx.rootDir, expression.getSourceFile().fileName),
+      line: lineOf(expression)
+    });
+  }
+  return tags;
+}
 function parseProvider(el, exportsSet, ctx) {
   const file = sourcePath(ctx.rootDir, el.getSourceFile().fileName);
   const line = lineOf(el);
@@ -20433,7 +20595,11 @@ function parseController(input, ctx) {
       if (optionsObject) {
         const parsePolicy = routePolicyProperty(optionsObject, "parse", ctx);
         const deletePolicy = routePolicyProperty(optionsObject, "allowDeleteBody", ctx);
-        if (parsePolicy.unresolved || deletePolicy.unresolved) {
+        const idempotency = checkedRouteIdempotency(optionsObject, ctx, route.handler);
+        if (idempotency !== undefined)
+          route.idempotency = idempotency;
+        const tagsPolicy = routePolicyProperty(optionsObject, "tags", ctx);
+        if (parsePolicy.unresolved || deletePolicy.unresolved || tagsPolicy.unresolved) {
           ctx.diagnostics.push({
             severity: "error",
             code: "unresolved-route-body-policy",
@@ -20441,6 +20607,9 @@ function parseController(input, ctx) {
             message: `Route ${route.handler} body policy must be statically resolvable; dynamic spreads, computed keys and shorthand policies are unsupported.`
           });
         }
+        const tags = checkedRouteTags(tagsPolicy.value, ctx, route.handler);
+        if (tags !== undefined)
+          route.tags = tags;
         const parse = parsePolicy.value;
         if (parse) {
           if (ts7.isStringLiteral(parse) && parse.text === "none")
@@ -22289,6 +22458,7 @@ function validateClientSchemaBoundaries(graph, options) {
 
 // src/effect-governance.ts
 init_validate();
+init_feature();
 function diagnostic(code, message, file, suggestion) {
   const metadata = COMPILER_DIAGNOSTIC_CODES[code];
   return {
@@ -22326,8 +22496,10 @@ function validateEffectPolicies(graph, options = {}) {
         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 (effect.retry === "explicit") {
+          const featureTransition = featureTransitionForRoute(module, controller, route);
+          const commandRef = route.command ?? featureTransition?.command;
+          const command = commandRef === undefined ? undefined : commands.get(commandRef) ?? [...commands.values()].find((candidate) => candidate.name === commandRef);
           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".'));
           }
@@ -23544,6 +23716,7 @@ init_graphql_options();
 
 // src/delivery-plan.ts
 import { createHash as createHash10 } from "node:crypto";
+init_feature();
 init_validate();
 var compare2 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 var sorted = (values) => [...new Set(values)].sort(compare2);
@@ -23663,6 +23836,10 @@ function createDeliveryPlan(graph, input, validation) {
           fail("delivery-route-conflict", `Public route "${key}" is owned by both "${existing}" and "${target.name}".`, "Give public routes unambiguous method/path contracts before splitting targets.");
         }
         publicRoutes.set(key, target.name);
+        const command = route.command === undefined ? undefined : module.commands.find((candidate) => candidate.className === route.command || candidate.name === route.command);
+        const featureTransition = featureTransitionForRoute(module, controller, route);
+        const effectiveCommand = route.command ?? featureTransition?.command;
+        const idempotency = route.idempotency ?? command?.idempotency ?? featureTransition?.idempotency;
         target.roots.push(module.name);
         target.routes.push({
           module: module.name,
@@ -23670,7 +23847,8 @@ function createDeliveryPlan(graph, input, validation) {
           handler: route.handler,
           method: route.method,
           path,
-          ...route.command === undefined ? {} : { command: route.command },
+          ...effectiveCommand === undefined ? {} : { command: effectiveCommand },
+          ...idempotency === undefined ? {} : { idempotency },
           reason: owner === undefined ? "default-http" : "explicit-module"
         });
       }
@@ -24702,7 +24880,12 @@ async function buildDeliveryProject(options, delivery) {
       deploymentReady: false,
       plan: planned.plan,
       objects,
-      routes: planned.plan.targets.flatMap((target) => target.routes.map((route) => ({ method: route.method, path: route.path, target: target.name }))),
+      routes: planned.plan.targets.flatMap((target) => target.routes.map((route) => ({
+        method: route.method,
+        path: route.path,
+        target: target.name,
+        ...route.idempotency === undefined ? {} : { idempotency: route.idempotency }
+      }))),
       jobs: planned.plan.targets.flatMap((target) => target.jobs.map((job) => ({ name: job.name, target: target.name })))
     });
     phase = "artifact-integrity";
@@ -24768,10 +24951,10 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { resolve as resolve18 } from "node:path";
 
 // src/migration-app-version.ts
-var MIGRATION_APP_VERSION = "0.29.0";
+var MIGRATION_APP_VERSION = "0.30.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.34.0";
+var MIGRATION_ELYSIA_VERSION = "0.35.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;
@@ -25807,8 +25990,8 @@ function validFeatureInventory(value, jobs, commands, routes, rpc) {
           return false;
       }
       const commandName = transition["command"];
+      const command = commandName === undefined ? undefined : commands.find((candidate) => isRecord2(candidate) && (candidate["name"] === commandName || candidate["className"] === commandName));
       if (commandName !== undefined) {
-        const command = commands.find((candidate) => isRecord2(candidate) && (candidate["name"] === commandName || candidate["className"] === commandName));
         if (!isRecord2(command))
           return false;
         if (transition["permission"] !== undefined && command["permission"] !== transition["permission"])
@@ -25839,9 +26022,21 @@ function validFeatureInventory(value, jobs, commands, routes, rpc) {
         if (routeBinding === "controller") {
           if (route["command"] !== undefined)
             return false;
-        } else if (route["command"] !== commandName) {
-          return false;
+        } else {
+          if (typeof route["command"] !== "string")
+            return false;
+          const routeCommand = commands.find((candidate) => isRecord2(candidate) && (candidate["name"] === route["command"] || candidate["className"] === route["command"]));
+          if (!isRecord2(routeCommand) || !isRecord2(command) || routeCommand["name"] !== command["name"])
+            return false;
         }
+        if (transition["permission"] !== undefined && route["permission"] !== transition["permission"])
+          return false;
+        if (transition["idempotency"] !== undefined && route["idempotency"] !== transition["idempotency"])
+          return false;
+        if (persistence !== undefined && route["idempotency"] !== "required")
+          return false;
+        if (route["idempotency"] === "required" && (route["method"] === "GET" || route["method"] === "HEAD" || route["method"] === "OPTIONS"))
+          return false;
       }
       const job = transition["job"];
       if (job === undefined)