@supacloud/compiler 0.47.3 → 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) => {
@@ -263,6 +267,9 @@ function validateFeatureSpec(spec, module) {
   if (!spec.name.trim() || spec.states.length === 0 || spec.states.some((state) => !state.trim()) || new Set(spec.states).size !== spec.states.length) {
     error("invalid-feature-states", "Feature name and states must be non-empty; states must be unique.");
   }
+  if (spec.tenantField !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(spec.tenantField)) {
+    error("feature-tenant-boundary-invalid", `Feature ${spec.name} declares an unsafe tenant field.`);
+  }
   const names = new Set;
   for (const transition of spec.transitions) {
     if (!transition.name.trim() || names.has(transition.name)) {
@@ -275,8 +282,46 @@ 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")) {
+        error("feature-persistence-invalid", `Database transition ${transition.name} requires distinct safe tenant/version/state fields, optimistic locking, and a receipt, without reconciliation.`);
+      }
+      if (persistence.boundary === "database" && spec.tenantField !== persistence.tenantField) {
+        error("feature-tenant-boundary-drift", `Database transition ${transition.name} tenant field must match Feature ${spec.name} tenantField.`);
+      }
+      if (persistence.boundary === "external" && (persistence.optimisticLock !== "none" || persistence.versionField !== undefined || persistence.tenantField !== undefined || persistence.stateField !== undefined || persistence.receipt !== "required" || persistence.reconciliation !== "required")) {
+        error("feature-persistence-invalid", `External transition ${transition.name} requires a receipt and reconciliation, without database optimistic locking.`);
+      }
+      if (persistence.boundary === "external" && !transition.job) {
+        error("feature-job-unresolved", `External transition ${transition.name} must bind a reconciliation Job.`);
+      }
+      if (!transition.command) {
+        error("feature-command-unresolved", `Persistent transition ${transition.name} must reference a command.`);
+      }
+      if (!transition.permission?.trim()) {
+        error("feature-governance-drift", `Persistent transition ${transition.name} must declare a permission.`);
+      }
+    }
     if (!module)
       continue;
+    if (transition.persistence?.boundary === "database") {
+      for (const query of module.queries) {
+        if (query.tenantScope !== "required") {
+          error("feature-query-tenant-boundary", `Query ${query.className} in Feature ${spec.name} must declare tenantScope: "required".`);
+        }
+      }
+      for (const job of module.jobs ?? []) {
+        if (job.tenantScope !== "required") {
+          error("feature-job-tenant-boundary", `Job ${job.className} in Feature ${spec.name} must declare tenantScope: "required".`);
+        }
+      }
+    }
     const commands = module.commands.filter((command) => command.className === transition.command || command.name === transition.command);
     const command = commands[0];
     if (transition.command && commands.length !== 1) {
@@ -291,23 +336,59 @@ function validateFeatureSpec(spec, module) {
           error("feature-governance-drift", `Transition ${transition.name} ${key} differs from command ${command.className}.`);
         }
       }
+      if (transition.persistence) {
+        if (transition.persistence.boundary === "database" && command.transaction !== "required") {
+          error("feature-persistence-drift", `Database transition ${transition.name} requires command ${command.className} to declare transaction: "required".`);
+        }
+        if (command.tenantScope !== "required") {
+          error("feature-command-tenant-boundary", `Command ${command.className} in Feature ${spec.name} must declare tenantScope: "required".`);
+        }
+        if (transition.persistence.boundary === "external" && command.transaction !== "none") {
+          error("feature-persistence-drift", `External transition ${transition.name} requires command ${command.className} to declare transaction: "none".`);
+        }
+        if (command.idempotency !== "required" || !command.audit) {
+          error("feature-persistence-drift", `Persistent transition ${transition.name} requires command ${command.className} to declare idempotency and audit.`);
+        }
+      }
+    }
+    if (transition.job) {
+      const jobs = (module.jobs ?? []).filter((job) => job.className === transition.job || job.name === transition.job);
+      if (jobs.length !== 1) {
+        error("feature-job-unresolved", `Transition ${transition.name} must reference exactly one Job in module ${module.name}.`);
+      } else {
+        const job = jobs[0];
+        if (job.tenantScope !== "required") {
+          error("feature-job-tenant-boundary", `Job ${job.className} in Feature ${spec.name} must declare tenantScope: "required".`);
+        }
+        if (job.idempotency !== "required") {
+          error("feature-job-idempotency", `Job ${job.className} in Feature ${spec.name} must declare idempotency: "required".`);
+        }
+        if (job.mode === undefined) {
+          error("feature-job-mode", `Job ${job.className} in Feature ${spec.name} must declare mode: "task" or "workflow".`);
+        }
+        if (job.input === undefined || job.schemaKinds?.input !== "declared") {
+          error("feature-job-contract", `Job ${job.className} in Feature ${spec.name} must declare a non-opaque input schema.`);
+        }
+        const provider = module.providers.find((candidate) => candidate.token === job.className || candidate.useClass === job.className);
+        if (job.tenantScope === "required" && provider && !provider.deps.some((token) => isJobContextToken(token))) {
+          error("feature-job-context", `Job ${job.className} in Feature ${spec.name} must inject JOB_CONTEXT for trusted tenant execution.`);
+        }
+      }
     }
     if (transition.route) {
       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 && 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.`);
       }
     }
   }
   return diagnostics;
 }
 function generateFeatureSource(spec) {
-  const errors = validateFeatureSpec(spec);
-  if (errors.length)
-    throw new Error(errors.map((error) => error.message).join(`
-`));
   if (spec.transitions.some((transition) => !transition.permission)) {
     throw new Error("Spec-to-Code requires an explicit permission for every transition.");
   }
@@ -315,13 +396,34 @@ function generateFeatureSource(spec) {
     ...transition,
     command: `Transition${index + 1}Command`
   }));
+  const errors = validateFeatureSpec({ ...spec, transitions });
+  if (errors.length)
+    throw new Error(errors.map((error) => error.message).join(`
+`));
   if (transitions.some((transition) => transition.route)) {
     throw new Error("Generate the command slice first; existing HTTP routes require explicit schema and handler implementations.");
   }
-  const sourceSpec = { name: spec.name, states: spec.states, transitions: Object.fromEntries(transitions.map((transition) => {
-    const { name, ...options } = transition;
-    return [name, options];
-  })) };
+  const sourceSpec = {
+    name: spec.name,
+    states: spec.states,
+    tenantField: spec.tenantField ?? "tenant_id",
+    transitions: Object.fromEntries(transitions.map((transition) => {
+      const { name, ...options } = transition;
+      const persistence = transition.persistence ?? {
+        boundary: "database",
+        optimisticLock: "required",
+        versionField: "version",
+        tenantField: "tenant_id",
+        stateField: "state",
+        receipt: "required",
+        reconciliation: "none"
+      };
+      return [name, {
+        ...options,
+        persistence
+      }];
+    }))
+  };
   return [
     'import { Command, defineFeatureSlice, defineFeatureSpec } from "@supacloud/app";',
     "",
@@ -332,9 +434,10 @@ function generateFeatureSource(spec) {
       `@Command(${JSON.stringify({
         name: `${spec.name}.${transition.name}`,
         permission: transition.permission,
-        transaction: transition.transaction ?? "none",
-        idempotency: transition.idempotency ?? "none",
-        audit: transition.audit
+        transaction: transition.transaction ?? (transition.persistence?.boundary === "external" ? "none" : "required"),
+        idempotency: transition.idempotency ?? "required",
+        audit: transition.audit ?? `${spec.name}.${transition.name}`,
+        tenantScope: "required"
       })})`,
       `export class ${transition.command} {`,
       `  execute(state: FeatureState): never {`,
@@ -521,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) {
@@ -598,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);
         }
@@ -802,13 +912,40 @@ function validateGraph(graph, options = false) {
           permission: `${module.name}.${command.name}`
         });
       }
+      if (command.rpc && command.branches) {
+        error("command-rpc-branches-conflict", `Command ${command.name} cannot declare both rpc and branches.`, module.file, module.line);
+      }
+      const branchAdapters = command.branches ?? [];
+      for (const branch of branchAdapters) {
+        if (typeof options !== "object" || !Object.hasOwn(options.commandCapabilities?.rpc ?? {}, branch.rpc)) {
+          error("command-rpc-unavailable", `Command ${command.name} requires configured RPC adapter '${branch.rpc}'.`, module.file, module.line);
+        }
+      }
       if (command.rpc && (typeof options !== "object" || !Object.hasOwn(options.commandCapabilities?.rpc ?? {}, command.rpc))) {
         error("command-rpc-unavailable", `Command ${command.name} requires configured RPC adapter '${command.rpc}'.`, module.file, module.line);
       }
       if (typeof options === "object" && options.commandCapabilities) {
         const hostCaps = options.commandCapabilities;
         const rpcCaps = command.rpc && Object.hasOwn(hostCaps.rpc ?? {}, command.rpc) ? hostCaps.rpc?.[command.rpc] : undefined;
-        if (hostCaps.requirePersistentAdapters && (command.rpc !== undefined && (!rpcCaps?.boundary || rpcCaps.audit !== true || rpcCaps.idempotency !== true) || hostCaps.permission !== true || !command.permission || !command.audit || command.idempotency !== "required" || command.rpc !== undefined && rpcCaps?.boundary === "database" && (rpcCaps.transaction !== true || command.transaction !== "required") || command.rpc === undefined && (hostCaps.audit !== true || hostCaps.idempotency !== true || hostCaps.transaction !== true || command.transaction !== "required") || command.rpc !== undefined && rpcCaps?.boundary === "external" && rpcCaps.reconcile !== true)) {
+        const branchCaps = branchAdapters.map((branch) => ({
+          branch,
+          capabilities: Object.hasOwn(hostCaps.rpc ?? {}, branch.rpc) ? hostCaps.rpc?.[branch.rpc] : undefined
+        }));
+        for (const { branch, capabilities } of branchCaps) {
+          if (capabilities?.boundary === "external" && (branch.transaction === "required" || capabilities.transaction === true)) {
+            error("command-external-transaction", `Command ${command.name} branch '${branch.when}' calls an external service; use transaction: 'none'.`, module.file, module.line, "Use transaction: 'none' with durable intent and reconciliation.");
+          }
+          if (branch.audit && capabilities?.audit !== true) {
+            error("command-audit-unsupported", `Command ${command.name} branch '${branch.when}' declares audit, but runtime audit persistence is unavailable.`, module.file, module.line);
+          }
+          if (branch.idempotency === "required" && capabilities?.idempotency !== true) {
+            error("command-idempotency-unsupported", `Command ${command.name} branch '${branch.when}' declares idempotency, but receipt persistence is unavailable.`, module.file, module.line);
+          }
+          if (branch.transaction === "required" && capabilities?.transaction !== true) {
+            error("command-transaction-unsupported", `Command ${command.name} branch '${branch.when}' declares transaction, but transaction support is unavailable.`, module.file, module.line);
+          }
+        }
+        if (hostCaps.requirePersistentAdapters && (command.rpc !== undefined && (!rpcCaps?.boundary || rpcCaps.audit !== true || rpcCaps.idempotency !== true) || branchCaps.length > 0 && branchCaps.some(({ branch, capabilities }) => !capabilities?.boundary || capabilities.audit !== true || capabilities.idempotency !== true || capabilities.boundary === "database" && (capabilities.transaction !== true || branch.transaction !== "required")) || hostCaps.permission !== true || !command.permission || branchCaps.length === 0 && (!command.audit || command.idempotency !== "required") || branchCaps.length > 0 && branchCaps.some(({ branch }) => !branch.audit || branch.idempotency !== "required") || branchCaps.length > 0 && branchCaps.some(({ capabilities }) => capabilities?.boundary === "external" && capabilities.reconcile !== true) || command.rpc !== undefined && rpcCaps?.boundary === "database" && (rpcCaps.transaction !== true || command.transaction !== "required") || command.rpc === undefined && branchCaps.length === 0 && (hostCaps.audit !== true || hostCaps.idempotency !== true || hostCaps.transaction !== true || command.transaction !== "required") || command.rpc !== undefined && rpcCaps?.boundary === "external" && rpcCaps.reconcile !== true)) {
           error("command-persistence-required", `Command ${command.name} requires an explicit persistent adapter, permission, audit and idempotency policy.`, module.file, module.line, "Register a named database/external adapter, enable permission checks and declare permission, audit and required idempotency on the command.");
         }
         if (rpcCaps?.boundary === "external" && (command.transaction === "required" || rpcCaps.transaction === true)) {
@@ -1245,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" },
@@ -1284,6 +1422,18 @@ var init_validate = __esm(() => {
     "invalid-feature-transition": { code: "SC6103", docsUrl: "https://supacloud.dev/errors/SC6103" },
     "feature-command-unresolved": { code: "SC6104", docsUrl: "https://supacloud.dev/errors/SC6104" },
     "feature-governance-drift": { code: "SC6105", docsUrl: "https://supacloud.dev/errors/SC6105" },
+    "feature-persistence-invalid": { code: "SC6110", docsUrl: "https://supacloud.dev/errors/SC6110" },
+    "feature-persistence-drift": { code: "SC6111", docsUrl: "https://supacloud.dev/errors/SC6111" },
+    "feature-tenant-boundary-invalid": { code: "SC6112", docsUrl: "https://supacloud.dev/errors/SC6112" },
+    "feature-tenant-boundary-drift": { code: "SC6113", docsUrl: "https://supacloud.dev/errors/SC6113" },
+    "feature-query-tenant-boundary": { code: "SC6114", docsUrl: "https://supacloud.dev/errors/SC6114" },
+    "feature-job-tenant-boundary": { code: "SC6115", docsUrl: "https://supacloud.dev/errors/SC6115" },
+    "feature-command-tenant-boundary": { code: "SC6116", docsUrl: "https://supacloud.dev/errors/SC6116" },
+    "feature-job-unresolved": { code: "SC6117", docsUrl: "https://supacloud.dev/errors/SC6117" },
+    "feature-job-idempotency": { code: "SC6118", docsUrl: "https://supacloud.dev/errors/SC6118" },
+    "feature-job-mode": { code: "SC6119", docsUrl: "https://supacloud.dev/errors/SC6119" },
+    "feature-job-contract": { code: "SC6120", docsUrl: "https://supacloud.dev/errors/SC6120" },
+    "feature-job-context": { code: "SC6121", docsUrl: "https://supacloud.dev/errors/SC6121" },
     "feature-route-unresolved": { code: "SC6106", docsUrl: "https://supacloud.dev/errors/SC6106" },
     "feature-route-drift": { code: "SC6107", docsUrl: "https://supacloud.dev/errors/SC6107" },
     "invalid-feature-spec": { code: "SC6108", docsUrl: "https://supacloud.dev/errors/SC6108" }
@@ -1294,6 +1444,8 @@ var init_validate = __esm(() => {
 function buildContractManifest(graph, artifacts) {
   const commands = [];
   const queries = [];
+  const jobs = [];
+  const features = [];
   const routes = [];
   const permissions = new Set;
   const rpc = [];
@@ -1305,27 +1457,107 @@ function buildContractManifest(graph, artifacts) {
         permissions.add(command.permission);
       if (command.rpc)
         rpc.push({ command: command.name, adapter: command.rpc });
+      for (const branch of command.branches ?? []) {
+        rpc.push({ command: `${command.name} [${branch.when}]`, adapter: branch.rpc });
+      }
       if (command.audit)
         events.push({ name: command.audit, source: "command.audit", command: command.name });
+      for (const branch of command.branches ?? []) {
+        if (branch.audit)
+          events.push({ name: branch.audit, source: "command.branch.audit", command: command.name });
+      }
       commands.push({
         name: command.name,
         className: command.className,
         module: module.name,
         ...command.permission === undefined ? {} : { permission: command.permission },
         ...command.rpc === undefined ? {} : { rpc: command.rpc },
+        ...command.branches === undefined ? {} : {
+          branches: command.branches.map((branch) => ({
+            when: branch.when,
+            adapter: branch.rpc,
+            transaction: branch.transaction,
+            idempotency: branch.idempotency,
+            ...branch.audit === undefined ? {} : { auditEvent: branch.audit },
+            ...branch.boundary === undefined ? {} : { boundary: branch.boundary }
+          }))
+        },
         transaction: command.transaction,
         idempotency: command.idempotency,
+        ...command.tenantScope === undefined ? {} : { tenantScope: command.tenantScope },
         ...command.audit === undefined ? {} : { auditEvent: command.audit }
       });
     }
     for (const query of module.queries) {
-      queries.push({ name: query.name, className: query.className, module: module.name });
+      queries.push({
+        name: query.name,
+        className: query.className,
+        module: module.name,
+        ...query.tenantScope === undefined ? {} : { tenantScope: query.tenantScope }
+      });
+    }
+    for (const job of module.jobs ?? []) {
+      jobs.push({
+        name: job.name,
+        className: job.className,
+        module: module.name,
+        ...job.input === undefined ? {} : { input: job.input },
+        ...job.schemaKinds?.input === undefined ? {} : { inputKind: job.schemaKinds.input },
+        ...job.output === undefined ? {} : { output: job.output },
+        ...job.schemaKinds?.output === undefined ? {} : { outputKind: job.schemaKinds.output },
+        ...job.mode === undefined ? {} : { mode: job.mode },
+        ...job.idempotency === undefined ? {} : { idempotency: job.idempotency },
+        ...job.tenantScope === undefined ? {} : { tenantScope: job.tenantScope }
+      });
+    }
+    if (module.featureSpec) {
+      features.push({
+        name: module.featureSpec.name,
+        states: [...module.featureSpec.states],
+        ...module.featureSpec.tenantField === undefined ? {} : { tenantField: module.featureSpec.tenantField },
+        transitions: module.featureSpec.transitions.map((transition) => {
+          const job = transition.job === undefined ? undefined : (module.jobs ?? []).find((candidate) => candidate.className === transition.job || candidate.name === transition.job);
+          return {
+            name: transition.name,
+            from: transition.from,
+            to: transition.to,
+            ...transition.permission === undefined ? {} : { permission: transition.permission },
+            ...transition.command === undefined ? {} : { command: transition.command },
+            ...transition.route === undefined ? {} : { route: transition.route },
+            ...transition.routeBinding === undefined ? {} : { routeBinding: transition.routeBinding },
+            ...transition.transaction === undefined ? {} : { transaction: transition.transaction },
+            ...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,
+                className: job.className,
+                ...job.input === undefined ? {} : { input: job.input },
+                ...job.schemaKinds?.input === undefined ? {} : { inputKind: job.schemaKinds.input },
+                ...job.output === undefined ? {} : { output: job.output },
+                ...job.schemaKinds?.output === undefined ? {} : { outputKind: job.schemaKinds.output },
+                ...job.mode === undefined ? {} : { mode: job.mode },
+                ...job.idempotency === undefined ? {} : { idempotency: job.idempotency },
+                ...job.tenantScope === undefined ? {} : { tenantScope: job.tenantScope }
+              }
+            },
+            ...transition.persistence === undefined ? {} : { persistence: transition.persistence }
+          };
+        })
+      });
     }
     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({
@@ -1334,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 ? {} : {
@@ -1350,6 +1584,8 @@ function buildContractManifest(graph, artifacts) {
   }
   commands.sort((left, right) => left.name.localeCompare(right.name));
   queries.sort((left, right) => left.name.localeCompare(right.name));
+  jobs.sort((left, right) => left.name.localeCompare(right.name));
+  features.sort((left, right) => left.name.localeCompare(right.name));
   routes.sort((left, right) => `${left.method} ${left.path}`.localeCompare(`${right.method} ${right.path}`));
   rpc.sort((left, right) => left.command.localeCompare(right.command));
   events.sort((left, right) => left.name.localeCompare(right.name));
@@ -1357,6 +1593,8 @@ function buildContractManifest(graph, artifacts) {
     version: 1,
     commands,
     queries,
+    jobs,
+    features,
     routes,
     permissions: [...permissions].sort(),
     rpc,
@@ -1370,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";
@@ -1504,6 +1744,7 @@ function renderApplication(graph, options) {
     name: command.name,
     permission: command.permission ?? null,
     rpc: command.rpc ?? null,
+    branches: command.branches ?? [],
     transaction: command.transaction ?? null,
     audit: command.audit ?? null,
     idempotency: command.idempotency ?? null
@@ -1781,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 = [
@@ -1807,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) {
@@ -1930,7 +2177,9 @@ ${indent(item, 2)}`).join(",")}
         `transaction: ${JSON.stringify(command.transaction)}`,
         ...command.audit ? [`audit: ${JSON.stringify(command.audit)}`] : [],
         `idempotency: ${JSON.stringify(command.idempotency)}`,
+        ...command.tenantScope ? [`tenantScope: ${JSON.stringify(command.tenantScope)}`] : [],
         ...command.rpc ? [`rpc: ${JSON.stringify(command.rpc)}`] : [],
+        ...command.branches && command.branches.length > 0 ? [`branches: ${JSON.stringify(command.branches)}`] : [],
         ...command.standalone ? ["standalone: true"] : [],
         ...command.aspects && command.aspects.length > 0 ? [`aspects: ${this.renderAspects(command.aspects)}`, `aspectPipeline: ${this.renderAspectPipeline(command.aspects)}`] : []
       ];
@@ -1963,6 +2212,8 @@ ${indent(item, 2)}`).join(",")}
         fields.push(`maxAttempts: ${job.maxAttempts}`);
       if (job.idempotency !== undefined)
         fields.push(`idempotency: ${JSON.stringify(job.idempotency)}`);
+      if (job.tenantScope !== undefined)
+        fields.push(`tenantScope: ${JSON.stringify(job.tenantScope)}`);
       if (job.aspects && job.aspects.length > 0) {
         fields.push(`aspects: ${this.renderAspects(job.aspects)}`);
         fields.push(`aspectPipeline: ${this.renderAspectPipeline(job.aspects)}`);
@@ -2285,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) => {
@@ -2363,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)}`,
@@ -2370,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],
@@ -2384,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)}`);
@@ -2417,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,
@@ -2427,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,
@@ -2435,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)}),`);
@@ -2491,6 +2765,8 @@ ${procedureMethods.join(`
     "  handler: string;",
     "  kind: Kind;",
     "  idempotency: Idempotency;",
+    "  tags?: readonly string[];",
+    "  invalidateTags?: readonly string[];",
     "}",
     "",
     "export interface ProcedureExecutionOptions {",
@@ -2596,6 +2872,8 @@ ${procedureMethods.join(`
     "  command?: string;",
     "  permission?: string;",
     "  idempotency: IdempotencyMode;",
+    "  tags?: readonly string[];",
+    "  invalidateTags?: readonly string[];",
     "}",
     "",
     ...routeTypes,
@@ -3095,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) {
@@ -3117,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 = {
@@ -3142,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 } : {},
@@ -3221,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[];",
@@ -3473,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),',
@@ -3495,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 }),",
@@ -3505,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] } : {}),",
@@ -3555,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({
@@ -3567,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 }
         });
       }
     }
@@ -3594,6 +3899,7 @@ function renderPermissions(graph) {
     "  handler: string;",
     "  command?: string;",
     "  permission?: string;",
+    '  idempotency?: "required" | "none";',
     "}",
     "",
     "export const RoutePermissions: RoutePermissionBinding[] = " + JSON.stringify(bindings, null, 2) + ";",
@@ -3637,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[];
@@ -3666,17 +3974,28 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
 
 export interface CompiledCommand {
   rpc?: string;
+  branches?: readonly CompiledCommandBranch[];
   className: string;
   name: string;
   permission: string;
   transaction: "required" | "none";
   audit?: string;
   idempotency: "required" | "none";
+  tenantScope?: "required" | "none";
   standalone?: boolean;
   aspects?: CompiledAspect[];
   aspectPipeline?: CompiledAspectPipeline;
 }
 
+export interface CompiledCommandBranch {
+  when: string;
+  rpc: string;
+  transaction?: "required" | "none" | string;
+  audit?: string;
+  idempotency?: "required" | "none" | string;
+  boundary?: "database" | "external";
+}
+
 export interface CompiledJob {
   className: string;
   name: string;
@@ -3688,6 +4007,7 @@ export interface CompiledJob {
   timeoutSec?: number;
   maxAttempts?: number;
   idempotency?: "required" | "none";
+  tenantScope?: "required" | "none";
   aspects?: CompiledAspect[];
   aspectPipeline?: CompiledAspectPipeline;
 }
@@ -3862,6 +4182,7 @@ async function destroyServiceInstances(
 `;
 var init_generate = __esm(() => {
   init_contract_manifest();
+  init_feature();
 });
 
 // src/route-contracts.ts
@@ -4715,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,
@@ -4865,6 +5188,7 @@ function exportGraphDot(graph) {
 }
 var init_inspect = __esm(() => {
   init_route_contracts();
+  init_feature();
 });
 
 // node_modules/typebox/build/system/memory/metrics.mjs
@@ -15432,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,
@@ -15554,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,
@@ -15563,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 }
         });
@@ -15683,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;
@@ -15784,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();
@@ -15794,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_.-]*$"
@@ -15867,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_({
@@ -16125,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.");
@@ -16176,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);
@@ -16219,7 +16558,7 @@ async function readDeliverySelection(manifestPath, target) {
   return { root, object, planned };
 }
 async function readVerifiedDeliveryFiles(root, object, target, selectedPaths) {
-  if (object.files.length > 1024 || object.files.some((file) => file.bytes > 64 * 1024 * 1024) || object.files.reduce((bytes, file) => bytes + file.bytes, 0) > 128 * 1024 * 1024) {
+  if (object.files.length > 1024 || object.files.some((file) => file.bytes > DELIVERY_ARTIFACT_MAX_FILE_BYTES) || object.files.reduce((bytes, file) => bytes + file.bytes, 0) > DELIVERY_ARTIFACT_MAX_TOTAL_BYTES) {
     throw new Error("Artifact inventory exceeds limits.");
   }
   const objectRoot = join7(root, "objects", object.objectId);
@@ -16258,10 +16597,12 @@ async function readVerifiedDeliveryFiles(root, object, target, selectedPaths) {
   }
   return retained;
 }
-var JSON_LIMIT = 1048576;
+var JSON_LIMIT = 1048576, DELIVERY_ARTIFACT_MAX_FILE_BYTES, DELIVERY_ARTIFACT_MAX_TOTAL_BYTES;
 var init_delivery_artifact = __esm(() => {
   init_delivery_build_schema();
   init_delivery_files();
+  DELIVERY_ARTIFACT_MAX_FILE_BYTES = 500 * 1024 * 1024;
+  DELIVERY_ARTIFACT_MAX_TOTAL_BYTES = 500 * 1024 * 1024;
 });
 
 // src/delivery-artifact.ts
@@ -17426,6 +17767,7 @@ var init_delivery_migration_plan = () => {};
 
 // node_modules/@supacloud/delivery/src/index.ts
 var init_src = __esm(() => {
+  init_delivery_artifact();
   init_delivery_artifact();
   init_worker_execution();
   init_worker_execution();
@@ -18807,6 +19149,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths, effectOptio
         if (meta && booleanProp(meta, "standalone")) {
           const permission = stringLiteralProp(meta, "permission");
           const rpc = checkedRpc(meta, ctx);
+          const branches = checkedBranches(meta, ctx);
           const audit = stringLiteralProp(meta, "audit");
           const standaloneName = stringLiteralProp(meta, "name") ?? classInfo.decl.name?.text ?? name;
           const standaloneUses = parseInfraResourceUseRefs(infraResourceProp(meta, "uses", ctx), ctx, `command ${standaloneName}`, sourcePath(ctx.rootDir, classInfo.file), lineOf(classInfo.decl));
@@ -18816,6 +19159,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths, effectOptio
             name: standaloneName,
             ...permission === undefined ? {} : { permission },
             ...rpc === undefined ? {} : { rpc },
+            ...branches === undefined ? {} : { branches },
             transaction: checkedCommandMode(meta, "transaction", ctx, classInfo.decl.name?.text ?? name) ?? "none",
             ...audit === undefined ? {} : { audit },
             idempotency: checkedCommandMode(meta, "idempotency", ctx, classInfo.decl.name?.text ?? name) ?? "none",
@@ -19147,18 +19491,22 @@ function parseModule(candidate, nameByNode, ctx) {
         const aspects = parseAspectRefs(getProp(meta, "aspects"), ctx, `command ${cls.name?.text ?? "<anonymous>"}`);
         const permission = stringLiteralProp(meta, "permission");
         const rpc = checkedRpc(meta, ctx);
+        const branches = checkedBranches(meta, ctx);
         const audit = stringLiteralProp(meta, "audit");
         const commandName = stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>";
         const uses = parseInfraResourceUseRefs(infraResourceProp(meta, "uses", ctx), ctx, `command ${commandName}`, sourcePath(ctx.rootDir, cls.getSourceFile().fileName), lineOf(cls));
         rejectUndeclaredResourceUses(uses, moduleResourceNames, ctx, `command ${commandName}`, sourcePath(ctx.rootDir, cls.getSourceFile().fileName), lineOf(cls));
+        const tenantScope = commandModeProp(meta, "tenantScope");
         commands.push({
           className: cls.name?.text ?? "<anonymous>",
           name: commandName,
           ...permission === undefined ? {} : { permission },
           ...rpc === undefined ? {} : { rpc },
+          ...branches === undefined ? {} : { branches },
           transaction: checkedCommandMode(meta, "transaction", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
           ...audit === undefined ? {} : { audit },
           idempotency: checkedCommandMode(meta, "idempotency", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
+          ...tenantScope === undefined ? {} : { tenantScope },
           ...booleanProp(meta, "standalone") ? { standalone: true } : {},
           ...uses.length > 0 ? { uses } : {},
           ...aspects.length > 0 ? { aspects } : {}
@@ -19189,12 +19537,14 @@ function parseModule(candidate, nameByNode, ctx) {
         const contract = parseJobOptions(meta, className, ctx);
         const jobUses = parseInfraResourceUseRefs(infraResourceProp(meta, "uses", ctx), ctx, `job ${stringLiteralProp(meta, "name") ?? className}`, sourcePath(ctx.rootDir, cls.getSourceFile().fileName), lineOf(cls));
         rejectUndeclaredResourceUses(jobUses, moduleResourceNames, ctx, `job ${stringLiteralProp(meta, "name") ?? className}`, sourcePath(ctx.rootDir, cls.getSourceFile().fileName), lineOf(cls));
+        const tenantScope = commandModeProp(meta, "tenantScope");
         jobs.push({
           className,
           name: stringLiteralProp(meta, "name") ?? className,
           serviceKey: camelName(provider?.token ?? className),
           scope,
           ...contract,
+          ...tenantScope === undefined ? {} : { tenantScope },
           ...jobUses.length > 0 ? { uses: jobUses } : {},
           ...aspects.length > 0 ? { aspects } : {}
         });
@@ -19204,9 +19554,11 @@ function parseModule(candidate, nameByNode, ctx) {
     if (queryDec) {
       const meta = decoratorObjectArg(queryDec);
       if (meta) {
+        const tenantScope = commandModeProp(meta, "tenantScope");
         queries.push({
           className: cls.name?.text ?? "<anonymous>",
-          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>"
+          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
+          ...tenantScope === undefined ? {} : { tenantScope }
         });
       }
     }
@@ -19261,6 +19613,7 @@ function parseFeatureSpec(input, ctx, seen = new Set) {
   if (!ts7.isObjectLiteralExpression(input))
     return invalid();
   const name = stringLiteralProp(input, "name");
+  const tenantField = stringLiteralProp(input, "tenantField");
   const statesExpr = getProp(input, "states");
   const transitionObject = getProp(input, "transitions");
   if (!name || !statesExpr || !ts7.isArrayLiteralExpression(statesExpr) || statesExpr.elements.some((state) => !ts7.isStringLiteral(state)) || !transitionObject || !ts7.isObjectLiteralExpression(transitionObject) || input.properties.some((property) => !ts7.isPropertyAssignment(property))) {
@@ -19279,15 +19632,27 @@ function parseFeatureSpec(input, ctx, seen = new Set) {
     const options = property.initializer;
     const from = stringLiteralProp(options, "from");
     const to = stringLiteralProp(options, "to");
-    if (!from || !to || options.properties.some((prop) => !ts7.isPropertyAssignment(prop)) || ["permission", "command", "route", "audit"].some((key) => getProp(options, key) && !stringLiteralProp(options, key)) || ["transaction", "idempotency"].some((key) => getProp(options, key) && !commandModeProp(options, key))) {
+    if (!from || !to || options.properties.some((prop) => !ts7.isPropertyAssignment(prop)) || ["permission", "command", "route", "routeBinding", "audit", "job"].some((key) => getProp(options, key) && !stringLiteralProp(options, key)) || ["transaction", "idempotency"].some((key) => getProp(options, key) && !commandModeProp(options, key))) {
       return invalid();
     }
     const permission = stringLiteralProp(options, "permission");
     const command = stringLiteralProp(options, "command");
     const route = stringLiteralProp(options, "route");
+    const routeBinding = stringLiteralProp(options, "routeBinding");
+    if (routeBinding !== undefined && routeBinding !== "command" && routeBinding !== "controller")
+      return invalid();
     const transaction = commandModeProp(options, "transaction");
     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)
+      return invalid();
     transitions.push({
       name: propertyName(property.name),
       from,
@@ -19295,12 +19660,45 @@ function parseFeatureSpec(input, ctx, seen = new Set) {
       ...permission === undefined ? {} : { permission },
       ...command === undefined ? {} : { command },
       ...route === undefined ? {} : { route },
+      ...routeBinding === undefined ? {} : { routeBinding },
       ...transaction === undefined ? {} : { transaction },
       ...idempotency === undefined ? {} : { idempotency },
-      ...audit === undefined ? {} : { audit }
+      ...audit === undefined ? {} : { audit },
+      ...job === undefined ? {} : { job },
+      ...invalidateTags === undefined ? {} : { invalidateTags },
+      ...persistence === undefined ? {} : { persistence }
     });
   }
-  return { name, states, transitions, file: sourcePath(ctx.rootDir, input.getSourceFile().fileName), line: lineOf(input) };
+  return {
+    name,
+    states,
+    ...tenantField === undefined ? {} : { tenantField },
+    transitions,
+    file: sourcePath(ctx.rootDir, input.getSourceFile().fileName),
+    line: lineOf(input)
+  };
+}
+function parseFeaturePersistence(input) {
+  if (input.properties.some((property) => !ts7.isPropertyAssignment(property)))
+    return;
+  const boundary = stringLiteralProp(input, "boundary");
+  const optimisticLock = commandModeProp(input, "optimisticLock");
+  const versionField = stringLiteralProp(input, "versionField");
+  const tenantField = stringLiteralProp(input, "tenantField");
+  const stateField = stringLiteralProp(input, "stateField");
+  const receipt = commandModeProp(input, "receipt");
+  const reconciliation = commandModeProp(input, "reconciliation");
+  if (boundary !== "database" && boundary !== "external" || optimisticLock !== "required" && optimisticLock !== "none" || receipt !== "required" && receipt !== "none" || reconciliation !== "required" && reconciliation !== "none")
+    return;
+  return {
+    boundary,
+    optimisticLock,
+    ...versionField === undefined ? {} : { versionField },
+    ...tenantField === undefined ? {} : { tenantField },
+    ...stateField === undefined ? {} : { stateField },
+    receipt,
+    reconciliation
+  };
 }
 function resolveStaticObjectLiteral(input, ctx, seen = new Set) {
   if (!input || seen.has(input))
@@ -19370,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);
@@ -20149,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",
@@ -20157,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")
@@ -20727,6 +21180,75 @@ function checkedRpc(meta, ctx) {
   });
   return;
 }
+function checkedBranches(meta, ctx) {
+  const expression = getProp(meta, "branches");
+  if (!expression)
+    return;
+  if (!ts7.isArrayLiteralExpression(expression)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "invalid-command-branches",
+      file: sourcePath(ctx.rootDir, expression.getSourceFile().fileName),
+      line: lineOf(expression),
+      message: "Command branches must be an explicit object array.",
+      suggestion: "Declare each branch as { when, rpc, transaction, audit, idempotency, boundary }."
+    });
+    return;
+  }
+  const branches = [];
+  for (const item of expression.elements) {
+    if (!ts7.isObjectLiteralExpression(item)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        code: "invalid-command-branches",
+        file: sourcePath(ctx.rootDir, item.getSourceFile().fileName),
+        line: lineOf(item),
+        message: "Command branches entries must be object literals."
+      });
+      continue;
+    }
+    const when = stringLiteralProp(item, "when");
+    const rpc = stringLiteralProp(item, "rpc");
+    const transaction = checkedCommandMode(item, "transaction", ctx, "command branch") ?? "none";
+    const audit = stringLiteralProp(item, "audit");
+    const idempotency = checkedCommandMode(item, "idempotency", ctx, "command branch") ?? "none";
+    const boundary = stringLiteralProp(item, "boundary");
+    const validBoundary = boundary === undefined || boundary === "database" || boundary === "external";
+    const validWhen = when !== undefined && /^(?:[A-Za-z_$][\w$]*)(?:\.[A-Za-z_$][\w$]*)*\s*===\s*(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')$/.test(when);
+    if (!when || !validWhen || !rpc?.trim() || !validBoundary) {
+      ctx.diagnostics.push({
+        severity: "error",
+        code: "invalid-command-branches",
+        file: sourcePath(ctx.rootDir, item.getSourceFile().fileName),
+        line: lineOf(item),
+        message: "Command branches require a restricted equality selector, a non-empty rpc, and a valid boundary.",
+        suggestion: `Use when: 'resource === "value"' (or body.resource/params.resource/query.resource), plus a named RPC adapter.`
+      });
+      continue;
+    }
+    branches.push({
+      when,
+      rpc,
+      transaction,
+      ...audit === undefined ? {} : { audit },
+      idempotency,
+      ...boundary === undefined ? {} : { boundary }
+    });
+  }
+  if (branches.length === 0)
+    return [];
+  if (new Set(branches.map((branch) => branch.when)).size !== branches.length) {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "duplicate-command-branch",
+      file: sourcePath(ctx.rootDir, expression.getSourceFile().fileName),
+      line: lineOf(expression),
+      message: "Command branches must use distinct selectors.",
+      suggestion: "Make each branch selector mutually distinct."
+    });
+  }
+  return branches;
+}
 function classDeps(cls, ctx) {
   const injectable = parseInjectableOptions(cls, ctx);
   const ctor = cls.members.find(ts7.isConstructorDeclaration);
@@ -21936,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 {
@@ -21973,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".'));
           }
@@ -23191,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);
@@ -23310,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,
@@ -23317,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"
         });
       }
@@ -24349,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";
@@ -24415,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.28.3";
+var MIGRATION_APP_VERSION = "0.30.0";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.33.5";
+var MIGRATION_ELYSIA_VERSION = "0.35.0";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;
@@ -25388,6 +25924,175 @@ function isRecord2(value) {
 function arrayLength(value) {
   return Array.isArray(value) ? value.length : undefined;
 }
+function safeField(value) {
+  return typeof value === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function validFeaturePersistence(value) {
+  if (!isRecord2(value))
+    return false;
+  const boundary = value["boundary"];
+  const receipt = value["receipt"];
+  const reconciliation = value["reconciliation"];
+  if (boundary === "database") {
+    const fields = [value["tenantField"], value["versionField"], value["stateField"]];
+    return value["optimisticLock"] === "required" && fields.every(safeField) && new Set(fields).size === 3 && receipt === "required" && reconciliation === "none";
+  }
+  if (boundary === "external") {
+    return value["optimisticLock"] === "none" && value["versionField"] === undefined && value["tenantField"] === undefined && value["stateField"] === undefined && receipt === "required" && reconciliation === "required";
+  }
+  return false;
+}
+function validCommandInventory(value) {
+  const names = new Set;
+  const classes = new Set;
+  return Array.isArray(value) && value.every((command) => {
+    if (!isRecord2(command) || typeof command["name"] !== "string" || command["name"].trim() === "" || typeof command["className"] !== "string" || command["className"].trim() === "" || typeof command["module"] !== "string" || command["module"].trim() === "" || typeof command["permission"] !== "string" || command["permission"].trim() === "" || command["transaction"] !== "required" && command["transaction"] !== "none" || command["idempotency"] !== "required" && command["idempotency"] !== "none" || command["tenantScope"] !== undefined && command["tenantScope"] !== "required" && command["tenantScope"] !== "none")
+      return false;
+    if (names.has(command["name"]) || classes.has(command["className"]))
+      return false;
+    if (command["rpc"] !== undefined && (typeof command["rpc"] !== "string" || command["rpc"].trim() === ""))
+      return false;
+    if (command["auditEvent"] !== undefined && (typeof command["auditEvent"] !== "string" || command["auditEvent"].trim() === ""))
+      return false;
+    names.add(command["name"]);
+    classes.add(command["className"]);
+    return true;
+  });
+}
+function validFeatureInventory(value, jobs, commands, routes, rpc) {
+  const featureNames = new Set;
+  return Array.isArray(value) && value.every((feature) => {
+    if (!isRecord2(feature) || typeof feature["name"] !== "string" || feature["name"].trim() === "")
+      return false;
+    if (featureNames.has(feature["name"]))
+      return false;
+    featureNames.add(feature["name"]);
+    if (feature["tenantField"] !== undefined && !safeField(feature["tenantField"]))
+      return false;
+    const states = feature["states"];
+    const transitions = feature["transitions"];
+    if (!Array.isArray(states) || states.length === 0 || states.some((state) => typeof state !== "string" || state.trim() === "") || new Set(states).size !== states.length || !Array.isArray(transitions))
+      return false;
+    const transitionNames = new Set;
+    return transitions.every((transition) => {
+      if (!isRecord2(transition) || typeof transition["name"] !== "string" || transition["name"].trim() === "" || typeof transition["from"] !== "string" || !states.includes(transition["from"]) || typeof transition["to"] !== "string" || !states.includes(transition["to"]))
+        return false;
+      if (transitionNames.has(transition["name"]))
+        return false;
+      transitionNames.add(transition["name"]);
+      const persistence = transition["persistence"];
+      if (persistence !== undefined) {
+        if (!isRecord2(persistence) || !validFeaturePersistence(persistence))
+          return false;
+        if (typeof transition["command"] !== "string" || transition["command"].trim() === "" || typeof transition["permission"] !== "string" || transition["permission"].trim() === "")
+          return false;
+        if (persistence["boundary"] === "database" && feature["tenantField"] !== persistence["tenantField"])
+          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) {
+        if (!isRecord2(command))
+          return false;
+        if (transition["permission"] !== undefined && command["permission"] !== transition["permission"])
+          return false;
+        if (transition["transaction"] !== undefined && command["transaction"] !== transition["transaction"])
+          return false;
+        if (transition["idempotency"] !== undefined && command["idempotency"] !== transition["idempotency"])
+          return false;
+        if (transition["audit"] !== undefined && command["auditEvent"] !== transition["audit"])
+          return false;
+        if (persistence !== undefined) {
+          const adapter = command["rpc"];
+          if (typeof adapter !== "string" || adapter.trim() === "" || !rpc.some((candidate) => isRecord2(candidate) && candidate["command"] === command["name"] && candidate["adapter"] === adapter) || command["idempotency"] !== "required" || command["tenantScope"] !== "required" || typeof command["auditEvent"] !== "string" || command["auditEvent"].trim() === "")
+            return false;
+          const expectedTransaction = persistence["boundary"] === "database" ? "required" : "none";
+          if (command["transaction"] !== expectedTransaction)
+            return false;
+        }
+      }
+      const routeName = transition["route"];
+      const routeBinding = transition["routeBinding"];
+      if (routeBinding !== undefined && routeBinding !== "command" && routeBinding !== "controller")
+        return false;
+      if (routeName !== undefined) {
+        const route = routes.find((candidate) => isRecord2(candidate) && `${candidate["method"]} ${candidate["path"]}` === routeName);
+        if (!isRecord2(route))
+          return false;
+        if (routeBinding === "controller") {
+          if (route["command"] !== undefined)
+            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)
+        return true;
+      const details = transition["jobDetails"];
+      const inventory = jobs.find((candidate) => isRecord2(candidate) && (candidate["name"] === job || candidate["className"] === job));
+      const contractFields = ["input", "inputKind", "output", "outputKind", "mode", "idempotency", "tenantScope"];
+      return typeof job === "string" && job.trim() !== "" && isRecord2(details) && isRecord2(inventory) && (details["name"] === job || details["className"] === job) && typeof details["className"] === "string" && details["className"].trim() !== "" && details["inputKind"] === "declared" && (details["mode"] === "task" || details["mode"] === "workflow") && details["idempotency"] === "required" && details["tenantScope"] === "required" && contractFields.every((field) => details[field] === inventory[field]);
+    });
+  });
+}
+function validJobInventory(value) {
+  const names = new Set;
+  const classes = new Set;
+  return Array.isArray(value) && value.every((job) => {
+    if (!isRecord2(job) || typeof job["name"] !== "string" || job["name"].trim() === "" || typeof job["className"] !== "string" || job["className"].trim() === "" || typeof job["module"] !== "string" || job["module"].trim() === "")
+      return false;
+    if (names.has(job["name"]) || classes.has(job["className"]))
+      return false;
+    names.add(job["name"]);
+    classes.add(job["className"]);
+    if (job["input"] !== undefined && (typeof job["input"] !== "string" || job["input"].trim() === ""))
+      return false;
+    if (job["inputKind"] !== undefined && job["inputKind"] !== "opaque" && job["inputKind"] !== "declared")
+      return false;
+    if (job["output"] !== undefined && (typeof job["output"] !== "string" || job["output"].trim() === ""))
+      return false;
+    if (job["outputKind"] !== undefined && job["outputKind"] !== "opaque" && job["outputKind"] !== "declared")
+      return false;
+    if (job["mode"] !== undefined && job["mode"] !== "task" && job["mode"] !== "workflow")
+      return false;
+    if (job["idempotency"] !== undefined && job["idempotency"] !== "required" && job["idempotency"] !== "none")
+      return false;
+    return job["tenantScope"] === undefined || job["tenantScope"] === "required" || job["tenantScope"] === "none";
+  });
+}
+function validRpcInventory(value, commandInventory) {
+  const commandNames = new Set;
+  const adapters = new Set;
+  return Array.isArray(value) && value.every((rpc) => {
+    if (!isRecord2(rpc) || typeof rpc["command"] !== "string" || rpc["command"].trim() === "" || typeof rpc["adapter"] !== "string" || rpc["adapter"].trim() === "")
+      return false;
+    if (commandNames.has(rpc["command"]) || adapters.has(rpc["adapter"]))
+      return false;
+    const command = commandInventory.find((candidate) => isRecord2(candidate) && candidate["name"] === rpc["command"] && candidate["rpc"] === rpc["adapter"]);
+    if (!isRecord2(command))
+      return false;
+    commandNames.add(rpc["command"]);
+    adapters.add(rpc["adapter"]);
+    return true;
+  }) && commandInventory.every((command) => {
+    if (!isRecord2(command) || command["rpc"] === undefined)
+      return true;
+    return value.some((rpc) => isRecord2(rpc) && rpc["command"] === command["name"] && rpc["adapter"] === command["rpc"]);
+  });
+}
 async function sha2566(path) {
   return createHash11("sha256").update(await readFile11(path)).digest("hex");
 }
@@ -25457,19 +26162,24 @@ async function assessMigration(options) {
   };
   try {
     const parsed = JSON.parse(await readFile11(contractsManifestPath, "utf8"));
-    if (!isRecord2(parsed) || parsed["version"] !== 1)
+    if (!isRecord2(parsed) || parsed["version"] !== 1 || !validJobInventory(parsed["jobs"]) || !validCommandInventory(parsed["commands"]) || !Array.isArray(parsed["routes"]) || !validRpcInventory(parsed["rpc"], parsed["commands"]) || !validFeatureInventory(parsed["features"], parsed["jobs"], parsed["commands"], parsed["routes"], parsed["rpc"])) {
       throw new Error("invalid manifest");
+    }
     const commands = arrayLength(parsed["commands"]);
+    const jobs = arrayLength(parsed["jobs"]);
     const routes = arrayLength(parsed["routes"]);
     const permissions = arrayLength(parsed["permissions"]);
+    const features = arrayLength(parsed["features"]);
     contractsManifest = {
       path: contractsManifestPath,
       present: true,
       sha256: await sha2566(contractsManifestPath),
       version: 1,
       ...commands === undefined ? {} : { commands },
+      ...jobs === undefined ? {} : { jobs },
       ...routes === undefined ? {} : { routes },
-      ...permissions === undefined ? {} : { permissions }
+      ...permissions === undefined ? {} : { permissions },
+      ...features === undefined ? {} : { features }
     };
   } catch {
     findings.push({