@supacloud/compiler 0.58.0 → 0.60.0

package/README.md

@@ -86,7 +86,8 @@ attempts. The default policy requires `requireRouteEffects`,
 ## Unified Database Contracts
 
 Database contracts are protocol-aware: configure only the database sources the
-application uses (`postgrestTypes`, `modelSchema`, or `graphql`). The generated
+application uses (`postgrestTypes`, `modelSchema`, `graphql`, `rpcRegistry` or
+`rpcCatalog`). The generated
 `database.manifest.json` is a TypeBox-validated, fingerprinted build boundary;
 consumers must reject it when its schema or migration fingerprint is stale.
 
@@ -99,6 +100,8 @@ type entry point while preserving PostgREST, ZModel and GraphQL native types:
   "outDir": "generated",
   "postgrestTypes": "database.types.ts",
   "modelSchema": "zenstack/generated/schema.ts",
+  "rpcRegistry": "db/rpc-registry.json",
+  "rpcCatalog": "db/contracts/rpc-catalog.json",
   "role": "authenticated",
   "graphql": {
     "schema": "graphql/schema.graphql",
@@ -114,11 +117,14 @@ snapshot and a role-scoped `pg_graphql` schema snapshot. The generated barrel
 exports `Database`, `QueryData`, ZModel schema types and GraphQL contracts.
 Consumers need `@supabase/supabase-js` and their ZenStack dependencies.
 
-`--check` detects drift in supplied snapshots, local ZModel imports, migration
-content/order and generated artifacts without writing. This is an offline check,
-not proof of live database parity or authorization. Refresh snapshots from the
-intended database and role before running it. Keep runtime decoders at untrusted
-boundaries; protocol result shapes are not interchangeable.
+`--check` detects drift in supplied snapshots, local ZModel imports, RPC
+registry/catalog inputs, migration content/order and generated artifacts without
+writing. This is an offline check, not proof of live database parity or
+authorization. Refresh snapshots from the intended database and role before
+running it. Keep runtime decoders at untrusted boundaries; protocol result shapes
+are not interchangeable. When `databaseGovernance.rpcBoundary` is configured,
+the compiler also fails if a named Command RPC capability has no registry/catalog
+source or explicit historical entry.
 
 Architecture references: Micronaut for compile-time AOP, NestJS for feature modules,
 and Angular for DI semantics. Compiled DI requires constructor injection and generated scope factories.

package/dist/cli.js

@@ -1090,7 +1090,13 @@ function validateGraph(graph, options = false) {
       if (command.rpc && command.branches) {
         error("command-rpc-branches-conflict", `Command ${command.name} cannot declare both rpc and branches.`, module.file, module.line);
       }
+      if (command.branchesFallback !== undefined && command.branchesFallback !== "reject" && command.branchesFallback !== "command") {
+        error("command-branches-fallback-invalid", `Command ${command.name} has an invalid branches fallback.`, module.file, module.line);
+      }
       const branchAdapters = command.branches ?? [];
+      if (command.branchesFallback === "command" && branchAdapters.length === 0) {
+        error("command-branches-fallback-without-branches", `Command ${command.name} declares a fallback without branches.`, module.file, module.line);
+      }
       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);
@@ -1120,7 +1126,7 @@ function validateGraph(graph, options = false) {
             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)) {
+        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.branchesFallback === "command" && (!command.audit || command.idempotency !== "required" || command.transaction !== "required" || hostCaps.audit !== true || hostCaps.idempotency !== true || hostCaps.transaction !== 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)) {
@@ -1673,6 +1679,7 @@ function buildContractManifest(graph, artifacts) {
         module: module.name,
         ...command.permission === undefined ? {} : { permission: command.permission },
         ...command.rpc === undefined ? {} : { rpc: command.rpc },
+        ...command.branchesFallback === undefined ? {} : { branchesFallback: command.branchesFallback },
         ...command.branches === undefined ? {} : {
           branches: command.branches.map((branch) => ({
             when: branch.when,
@@ -2090,6 +2097,47 @@ function allAspects(module) {
     ...(module.jobs ?? []).flatMap((job) => job.aspects ?? [])
   ];
 }
+function uniqueStages(paths) {
+  return [...new Set(paths.flat())];
+}
+function commandStagePaths(command, aspects) {
+  const prefix = ["commandExecutor", "authorize"];
+  if (command.branches?.length) {
+    const branchPaths = command.branches.map((branch) => [
+      ...prefix,
+      `rpc:${branch.rpc}`,
+      ...aspects,
+      "handler"
+    ]);
+    if (command.branchesFallback === "command") {
+      branchPaths.push([
+        ...prefix,
+        ...command.idempotency === "required" ? ["idempotency"] : [],
+        ...command.transaction === "required" ? ["transaction"] : [],
+        ...aspects,
+        "handler",
+        ...command.audit ? ["audit"] : []
+      ]);
+    }
+    return branchPaths;
+  }
+  return [[
+    ...prefix,
+    ...command.rpc ? [`rpc:${command.rpc}`] : [
+      ...command.idempotency === "required" ? ["idempotency"] : [],
+      ...command.transaction === "required" ? ["transaction"] : []
+    ],
+    ...aspects,
+    "handler",
+    ...command.audit && !command.rpc ? ["audit"] : []
+  ]];
+}
+function planStages(paths, branches) {
+  const stages = uniqueStages(paths);
+  if (branches && !stages.includes("rpc:selected-branch"))
+    stages.splice(2, 0, "rpc:selected-branch");
+  return paths.length > 1 ? { stages, stagePaths: paths } : { stages };
+}
 function createExecutionPlans(graph) {
   const aspects = (boundary, refs = []) => refs.map((ref, index) => `${boundary}.aspect[${index}]:${ref.name}`);
   return graph.modules.flatMap((module) => [
@@ -2099,46 +2147,34 @@ function createExecutionPlans(graph) {
       const command = module.commands.find((item) => item.className === commandRef || item.name === commandRef);
       const boundCommand = route.command === undefined ? undefined : command;
       const path = `${controller.path}/${route.path}`.replace(/\/+/g, "/");
+      const routeAspects = [
+        ...aspects(`module:${module.name}`, module.aspects),
+        ...aspects("route", route.aspects),
+        ...aspects("command", boundCommand?.aspects)
+      ];
+      const stagePaths = boundCommand === undefined ? undefined : commandStagePaths(boundCommand, routeAspects);
+      const plannedStages = stagePaths === undefined ? { stages: [...routeAspects, "handler"] } : planStages(stagePaths, Boolean(boundCommand?.branches?.length));
       return {
         module: module.name,
         kind: "route",
         name: `${route.method} ${path.length > 1 ? path.replace(/\/+$/, "") : path}`,
         ...command ? { command: command.name } : {},
-        stages: [
-          ...boundCommand ? [
-            "commandExecutor",
-            "authorize",
-            ...boundCommand.branches?.length ? ["rpc:selected-branch"] : boundCommand.rpc ? [`rpc:${boundCommand.rpc}`] : [
-              ...boundCommand.idempotency === "required" ? ["idempotency"] : [],
-              ...boundCommand.transaction === "required" ? ["transaction"] : []
-            ]
-          ] : [],
-          ...aspects(`module:${module.name}`, module.aspects),
-          ...aspects("route", route.aspects),
-          ...aspects("command", boundCommand?.aspects),
-          "handler",
-          ...boundCommand?.audit && !boundCommand.rpc && !boundCommand.branches?.length ? ["audit"] : []
-        ]
+        ...plannedStages
       };
     })),
-    ...module.commands.map((command) => ({
-      module: module.name,
-      kind: "command",
-      name: command.name,
-      command: command.name,
-      stages: [
-        "commandExecutor",
-        "authorize",
-        ...command.branches?.length ? ["rpc:selected-branch"] : command.rpc ? [`rpc:${command.rpc}`] : [
-          ...command.idempotency === "required" ? ["idempotency"] : [],
-          ...command.transaction === "required" ? ["transaction"] : []
-        ],
+    ...module.commands.map((command) => {
+      const stagePaths = commandStagePaths(command, [
         ...aspects(`module:${module.name}`, module.aspects),
-        ...aspects("command", command.aspects),
-        "handler",
-        ...command.audit && !command.rpc && !command.branches?.length ? ["audit"] : []
-      ]
-    })),
+        ...aspects("command", command.aspects)
+      ]);
+      return {
+        module: module.name,
+        kind: "command",
+        name: command.name,
+        command: command.name,
+        ...planStages(stagePaths, Boolean(command.branches?.length))
+      };
+    }),
     ...(module.jobs ?? []).map((job) => ({
       module: module.name,
       kind: "job",
@@ -2404,6 +2440,7 @@ function renderApplication(graph, options) {
     permission: command.permission ?? null,
     rpc: command.rpc ?? null,
     branches: command.branches ?? [],
+    branchesFallback: command.branchesFallback ?? "reject",
     transaction: command.transaction ?? null,
     audit: command.audit ?? null,
     idempotency: command.idempotency ?? null
@@ -2472,25 +2509,29 @@ function renderApplication(graph, options) {
           }
         };
       }));
-      const commands = module.commands.map((command) => ({
-        name: command.name,
-        className: command.className,
-        executor: "commandExecutor",
-        adapter: command.rpc ?? null,
-        permission: command.permission ?? null,
-        audit: command.audit ?? null,
-        transaction: command.transaction,
-        idempotency: command.idempotency,
-        branches: command.branches ?? [],
-        ...command.tenantScope === undefined ? {} : { tenantScope: command.tenantScope },
-        requiredCapabilities: {
-          permission: true,
-          audit: command.branches?.length ? command.branches.some((branch) => Boolean(branch.audit)) : Boolean(command.audit),
-          idempotency: command.branches?.length ? command.branches.some((branch) => branch.idempotency === "required") : command.idempotency === "required",
-          transaction: command.branches?.length ? command.branches.some((branch) => branch.transaction === "required") : command.transaction === "required"
-        },
-        aspects: (command.aspects ?? []).map((aspect) => aspect.name)
-      })).sort((left, right) => left.name.localeCompare(right.name));
+      const commands = module.commands.map((command) => {
+        const fallbackCommand = command.branchesFallback === "command";
+        return {
+          name: command.name,
+          className: command.className,
+          executor: "commandExecutor",
+          adapter: command.rpc ?? null,
+          permission: command.permission ?? null,
+          audit: command.audit ?? null,
+          transaction: command.transaction,
+          idempotency: command.idempotency,
+          branches: command.branches ?? [],
+          branchesFallback: command.branchesFallback ?? "reject",
+          ...command.tenantScope === undefined ? {} : { tenantScope: command.tenantScope },
+          requiredCapabilities: {
+            permission: true,
+            audit: Boolean(command.audit) && fallbackCommand || (command.branches?.length ? command.branches.some((branch) => Boolean(branch.audit)) : Boolean(command.audit)),
+            idempotency: command.idempotency === "required" && fallbackCommand || (command.branches?.length ? command.branches.some((branch) => branch.idempotency === "required") : command.idempotency === "required"),
+            transaction: command.transaction === "required" && fallbackCommand || (command.branches?.length ? command.branches.some((branch) => branch.transaction === "required") : command.transaction === "required")
+          },
+          aspects: (command.aspects ?? []).map((aspect) => aspect.name)
+        };
+      }).sort((left, right) => left.name.localeCompare(right.name));
       const jobs = (module.jobs ?? []).map((job) => ({
         name: job.name,
         className: job.className,
@@ -2974,6 +3015,7 @@ ${indent(item, 2)}`).join(",")}
         `idempotency: ${JSON.stringify(command.idempotency)}`,
         ...command.tenantScope ? [`tenantScope: ${JSON.stringify(command.tenantScope)}`] : [],
         ...command.rpc ? [`rpc: ${JSON.stringify(command.rpc)}`] : [],
+        ...command.branchesFallback ? [`branchesFallback: ${JSON.stringify(command.branchesFallback)}`] : [],
         ...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)}`] : []
@@ -4733,6 +4775,7 @@ var HEADER = "// GENERATED BY @supacloud/compiler — do not edit", INTERFACES =
 export interface CompiledCommand {
   rpc?: string;
   branches?: readonly CompiledCommandBranch[];
+  branchesFallback?: "reject" | "command";
   className: string;
   name: string;
   permission: string;
@@ -4865,7 +4908,7 @@ async function compiledAspectStep(context: CompiledAspectContext, handler: () =>
     }
     called = true;
     pending = Promise.resolve().then(handler).then(result => {
-      if (strict) freezeCompiledAspectData(result);
+      if (strict && !(result instanceof Response)) freezeCompiledAspectData(result);
       value = result;
       return result;
     });
@@ -15812,7 +15855,8 @@ var init_execution_snapshot = __esm(() => {
       kind,
       name: text,
       command: Optional(text),
-      stages: _Array_(text)
+      stages: _Array_(text),
+      stagePaths: Optional(_Array_(_Array_(text)))
     }, closed)),
     commandAliases: _Array_(_Object_({ module: text, name: text, alias: text }, closed)),
     contexts: _Array_(_Object_({
@@ -15981,7 +16025,8 @@ function buildTimeline(events, matchedPlans) {
           attempts: [],
           omittedAttempts: 0
         },
-        attempts: new Map
+        attempts: new Map,
+        ...plan === undefined ? {} : { plan }
       };
       groups.set(key, group);
     }
@@ -16009,13 +16054,16 @@ function buildTimeline(events, matchedPlans) {
     const declared = group.entry.declaredStages;
     const attempts = [...group.attempts.values()].sort((left, right) => Number(hasFailure(right)) - Number(hasFailure(left)) || left.attempt - right.attempt).slice(0, EXECUTION_CONTEXT_LIMITS.timelineAttempts).sort((left, right) => left.attempt - right.attempt).map((attempt) => {
       const stages = [...attempt.stages].sort((left, right) => Number(right.phase === "failed") - Number(left.phase === "failed") || left.index - right.index).slice(0, EXECUTION_CONTEXT_LIMITS.timelineStages).sort((left, right) => left.index - right.index);
-      const terminal = declared[declared.length - 1];
+      const paths = group.plan?.stagePaths && group.plan.stagePaths.length > 0 ? group.plan.stagePaths : [declared];
+      const bestPath = [...paths].sort((left, right) => right.filter((stage) => attempt.observed.has(stage)).length - left.filter((stage) => attempt.observed.has(stage)).length)[0] ?? declared;
+      const terminal = bestPath[bestPath.length - 1];
+      const complete = terminal !== undefined && attempt.stages.some((stage) => stage.stage === terminal && stage.phase === "succeeded");
       return {
         attempt: attempt.attempt,
         stages,
         failed: hasFailure(attempt),
-        complete: terminal !== undefined && attempt.stages.some((stage) => stage.stage === terminal && stage.phase === "succeeded"),
-        missingStages: declared.filter((stage) => !attempt.observed.has(stage)),
+        complete,
+        missingStages: bestPath.filter((stage) => !attempt.observed.has(stage)),
         unexpectedStages: [],
         traceIds: [...attempt.traceIds].sort(),
         omittedStages: attempt.stages.length - stages.length
@@ -16494,23 +16542,49 @@ var init_application_development2 = __esm(() => {
 });
 
 // node_modules/@supacloud/delivery/src/worker-execution.ts
+function workerShardCount(group) {
+  return group.shardCount ?? 1;
+}
+function shardSuffix(shard) {
+  if (!Number.isSafeInteger(shard) || shard < 0 || shard >= 64) {
+    throw new Error("WORKER_SHARD_INVALID");
+  }
+  return `s${shard.toString(36).padStart(2, "0")}`;
+}
+function workerShardQueue(group, shard) {
+  const count = workerShardCount(group);
+  if (!Number.isSafeInteger(shard) || shard < 0 || shard >= count) {
+    throw new Error("WORKER_SHARD_INVALID");
+  }
+  if (count === 1)
+    return group.queue;
+  const queue = `${group.queue}_${shardSuffix(shard)}`;
+  if (!/^scw_[a-z0-9_]{1,40}$/.test(queue))
+    throw new Error("WORKER_QUEUE_INVALID");
+  return queue;
+}
 function parseWorkerExecutionGroup(value) {
   if (!Check2(WorkerExecutionGroupSchema, value) || value.replicas > value.maxReplicas || !value.queue.endsWith(`_v${value.definitionVersion}`) || value.lifecycle.visibilityTimeoutSeconds < value.lifecycle.executionTimeoutSeconds + value.lifecycle.shutdownGraceSeconds + 30) {
     throw new Error("WORKER_EXECUTION_INVALID");
   }
-  return structuredClone(value);
+  const group = structuredClone(value);
+  for (let shard = 0;shard < workerShardCount(group); shard += 1)
+    workerShardQueue(group, shard);
+  return group;
 }
 function validateWorkerExecution(groups) {
   const names = new Set, targets = new Set, queues = new Set, routes = new Set;
   for (const candidate of groups) {
     const group = parseWorkerExecutionGroup(candidate);
     const route = `${group.taskKey}:${group.definitionVersion}`;
-    if (names.has(group.name) || targets.has(group.target) || queues.has(group.queue) || routes.has(route)) {
+    const physicalQueues = Array.from({ length: workerShardCount(group) }, (_, shard) => workerShardQueue(group, shard));
+    if (names.has(group.name) || targets.has(group.target) || queues.has(group.queue) || physicalQueues.some((queue) => queues.has(queue)) || routes.has(route)) {
       throw new Error("WORKER_EXECUTION_CONFLICT");
     }
     names.add(group.name);
     targets.add(group.target);
     queues.add(group.queue);
+    physicalQueues.forEach((queue) => queues.add(queue));
     routes.add(route);
   }
 }
@@ -16534,6 +16608,7 @@ var init_worker_execution = __esm(() => {
     definitionVersion: String2({ pattern: "^[1-9][0-9]{0,8}$" }),
     replicas: positive(16),
     maxReplicas: positive(16),
+    shardCount: Optional(positive(64)),
     concurrencyPerReplica: positive(32),
     resources: ComputeResourcesSchema,
     database: _Object_({
@@ -16943,7 +17018,7 @@ function parseDeliveryBuildManifest(value) {
   if (!Check2(DeliveryBuildManifestSchema, value))
     throw new Error("Invalid delivery build manifest.");
   validateWorkerExecution(value.plan.targets.flatMap((target) => target.execution ? [target.execution] : []));
-  if (value.plan.targets.reduce((count, target) => count + (target.execution?.replicas ?? 1), 0) > 32) {
+  if (value.plan.targets.reduce((count, target) => count + (target.execution ? (target.execution.replicas ?? 1) * workerShardCount(target.execution) : 1), 0) > 256) {
     throw new Error("Invalid delivery replica count.");
   }
   for (const target of value.plan.targets) {
@@ -18515,7 +18590,7 @@ function importPath(out, path) {
 function parseDatabaseContractsOptions(value, directory) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new TypeError("Expected database contracts configuration");
-  const allowed = ["rootDir", "outDir", "postgrestTypes", "modelSchema", "role", "graphql", "migrations"];
+  const allowed = ["rootDir", "outDir", "postgrestTypes", "modelSchema", "role", "graphql", "rpcRegistry", "rpcCatalog", "migrations"];
   if (Object.keys(value).some((name) => !allowed.includes(name)))
     throw new TypeError("Unknown database contracts option");
   const field = (name) => {
@@ -18531,6 +18606,8 @@ function parseDatabaseContractsOptions(value, directory) {
   };
   const postgrestTypes = optionalPath("postgrestTypes");
   const modelSchema = optionalPath("modelSchema");
+  const rpcRegistry = optionalPath("rpcRegistry");
+  const rpcCatalog = optionalPath("rpcCatalog");
   const graphqlPresent = Object.hasOwn(value, "graphql");
   if (!postgrestTypes && !modelSchema && !graphqlPresent) {
     throw new TypeError("Database contracts require postgrestTypes, modelSchema, or graphql");
@@ -18552,6 +18629,8 @@ function parseDatabaseContractsOptions(value, directory) {
     ...modelSchema ? { modelSchema: resolve25(directory, modelSchema) } : {},
     role: field("role"),
     ...graphql ? { graphql } : {},
+    ...rpcRegistry ? { rpcRegistry: resolve25(directory, rpcRegistry) } : {},
+    ...rpcCatalog ? { rpcCatalog: resolve25(directory, rpcCatalog) } : {},
     migrations: migrations.map((file) => resolve25(directory, file))
   };
 }
@@ -18627,6 +18706,10 @@ async function generateDatabaseContracts(options, check = false) {
   }
   if (options.graphql)
     await addInput(resolve25(rootDir, options.graphql.schema));
+  if (options.rpcRegistry)
+    await addInput(options.rpcRegistry);
+  if (options.rpcCatalog)
+    await addInput(options.rpcCatalog);
   if (new Set(options.migrations.map((path) => resolve25(rootDir, path))).size !== options.migrations.length) {
     throw new Error("Duplicate migration in database contracts configuration");
   }
@@ -19879,6 +19962,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths, effectOptio
             const permission = stringLiteralProp(meta, "permission");
             const rpc = checkedRpc(meta, ctx);
             const branches = checkedBranches(meta, ctx);
+            const branchesFallback = checkedBranchesFallback(meta, ctx);
             const audit = stringLiteralProp(meta, "audit");
             const standaloneName = stringLiteralProp(meta, "name") ?? classInfo.decl.name?.text ?? name;
             const standaloneUses = await parseInfraResourceUseRefs(infraResourceProp(meta, "uses", ctx), ctx, `command ${standaloneName}`, sourcePath(ctx.rootDir, classInfo.file), lineOf(classInfo.decl));
@@ -19889,6 +19973,7 @@ async function analyzeProject(rootDir, include, cache, changedPaths, effectOptio
               ...permission === undefined ? {} : { permission },
               ...rpc === undefined ? {} : { rpc },
               ...branches === undefined ? {} : { branches },
+              ...branchesFallback === undefined ? {} : { branchesFallback },
               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",
@@ -20263,6 +20348,7 @@ async function parseModule(candidate, nameByNode, ctx) {
         const permission = stringLiteralProp(meta, "permission");
         const rpc = checkedRpc(meta, ctx);
         const branches = checkedBranches(meta, ctx);
+        const branchesFallback = checkedBranchesFallback(meta, ctx);
         const audit = stringLiteralProp(meta, "audit");
         const commandName = stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>";
         const uses = await parseInfraResourceUseRefs(infraResourceProp(meta, "uses", ctx), ctx, `command ${commandName}`, sourcePath(ctx.rootDir, cls.getSourceFile().fileName), lineOf(cls));
@@ -20274,6 +20360,7 @@ async function parseModule(candidate, nameByNode, ctx) {
           ...permission === undefined ? {} : { permission },
           ...rpc === undefined ? {} : { rpc },
           ...branches === undefined ? {} : { branches },
+          ...branchesFallback === undefined ? {} : { branchesFallback },
           transaction: checkedCommandMode(meta, "transaction", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
           ...audit === undefined ? {} : { audit },
           idempotency: checkedCommandMode(meta, "idempotency", ctx, cls.name?.text ?? "<anonymous>") ?? "none",
@@ -22112,6 +22199,23 @@ function checkedBranches(meta, ctx) {
   }
   return branches;
 }
+function checkedBranchesFallback(meta, ctx) {
+  const expression = getProp(meta, "branchesFallback");
+  if (!expression)
+    return;
+  const value = stringLiteralProp(meta, "branchesFallback");
+  if (value === "reject" || value === "command")
+    return value;
+  ctx.diagnostics.push({
+    severity: "error",
+    code: "invalid-command-branches-fallback",
+    file: sourcePath(ctx.rootDir, expression.getSourceFile().fileName),
+    line: lineOf(expression),
+    message: "Command branchesFallback must be 'reject' or 'command'.",
+    suggestion: "Use branchesFallback: 'command' only when the command handler owns the unmatched-input boundary."
+  });
+  return;
+}
 async function classDeps(cls, ctx) {
   const injectable = await parseInjectableOptions(cls, ctx);
   const ctor = cls.members.find(ts8.isConstructorDeclaration);
@@ -23457,11 +23561,13 @@ function assertDatabaseGovernance(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("Invalid databaseGovernance configuration.");
   const entry = value;
-  if (entry["mode"] !== "off" && entry["mode"] !== "check" && entry["mode"] !== "enforce" || Object.keys(entry).some((key) => !["mode", "projectRoot", "moduleFile", "databaseUrl", "databaseUrlEnv", "schemas"].includes(key)) || ["projectRoot", "moduleFile", "databaseUrl", "databaseUrlEnv"].some((key) => entry[key] !== undefined && (typeof entry[key] !== "string" || !entry[key].trim())) || entry["databaseUrlEnv"] !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(entry["databaseUrlEnv"])) || entry["schemas"] !== undefined && (!Array.isArray(entry["schemas"]) || !entry["schemas"].length || !entry["schemas"].every((schema) => typeof schema === "string" && schema.trim()))) {
+  const rpcBoundary = entry["rpcBoundary"];
+  const validRpcBoundary = rpcBoundary === undefined || rpcBoundary !== null && typeof rpcBoundary === "object" && !Array.isArray(rpcBoundary) && Object.keys(rpcBoundary).every((key) => ["registry", "catalog", "legacy"].includes(key)) && Object.values(rpcBoundary).length > 0 && Object.values(rpcBoundary).every((path) => typeof path === "string" && path.trim() !== "" && !path.includes("\\") && !path.startsWith("/"));
+  if (entry["mode"] !== "off" && entry["mode"] !== "check" && entry["mode"] !== "enforce" || Object.keys(entry).some((key) => !["mode", "projectRoot", "moduleFile", "databaseUrl", "databaseUrlEnv", "schemas", "rpcBoundary"].includes(key)) || ["projectRoot", "moduleFile", "databaseUrl", "databaseUrlEnv"].some((key) => entry[key] !== undefined && (typeof entry[key] !== "string" || !entry[key].trim())) || entry["databaseUrlEnv"] !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(entry["databaseUrlEnv"])) || entry["schemas"] !== undefined && (!Array.isArray(entry["schemas"]) || !entry["schemas"].length || !entry["schemas"].every((schema) => typeof schema === "string" && schema.trim())) || !validRpcBoundary) {
     throw new Error("Invalid databaseGovernance mode, paths, connection or schemas.");
   }
 }
-async function checkDatabaseGovernance(rootDir, value) {
+async function checkDatabaseGovernance(rootDir, value, rpcCapabilities = []) {
   if (value === undefined)
     return [];
   const failure = () => [{
@@ -23478,7 +23584,7 @@ async function checkDatabaseGovernance(rootDir, value) {
     const output = await new Promise((accept, reject) => {
       const child = execFile(process.versions.bun ? process.execPath : "bun", ["--no-env-file", worker], { timeout: 30000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024 }, (error, stdout) => error ? reject(error) : accept(stdout));
       child.stdin?.on("error", reject);
-      child.stdin?.end(JSON.stringify(options));
+      child.stdin?.end(JSON.stringify({ options, rpcCapabilities }));
     });
     const report = JSON.parse(output);
     if (!report || typeof report !== "object" || !("diagnostics" in report) || !Array.isArray(report.diagnostics))
@@ -23524,7 +23630,7 @@ async function compileProject(options) {
     ...validateEffectPolicies(graph, options.effect),
     ...validateJobPolicies(graph)
   ];
-  const databaseDiagnostics = await checkDatabaseGovernance(options.rootDir, options.databaseGovernance);
+  const databaseDiagnostics = await checkDatabaseGovernance(options.rootDir, options.databaseGovernance, Object.keys(options.commandCapabilities?.rpc ?? {}));
   diagnostics.push(...databaseDiagnostics);
   if (databaseDiagnostics.length)
     return { diagnostics, graph, written: [] };
@@ -23594,7 +23700,7 @@ async function checkProject(options) {
     ...validateEffectPolicies(graph, options.effect),
     ...validateJobPolicies(graph)
   ];
-  const databaseDiagnostics = await checkDatabaseGovernance(options.rootDir, options.databaseGovernance);
+  const databaseDiagnostics = await checkDatabaseGovernance(options.rootDir, options.databaseGovernance, Object.keys(options.commandCapabilities?.rpc ?? {}));
   diagnostics.push(...databaseDiagnostics);
   if (databaseDiagnostics.length) {
     return { diagnostics, graph, upToDate: false, mismatches: ["Database governance verification failed."] };
@@ -25292,8 +25398,8 @@ function createDeliveryPlan(graph, input, validation) {
       target.execution = group;
     }
   }
-  if ([...targets.values()].reduce((count, target) => count + (target.execution?.replicas ?? 1), 0) > 32) {
-    fail("delivery-execution-replica-limit", "A release supports at most 32 runtime targets including replicas.", "Reduce the replica count or split independent applications.");
+  if ([...targets.values()].reduce((count, target) => count + (target.execution ? (target.execution.replicas ?? 1) * (target.execution.shardCount ?? 1) : 1), 0) > 256) {
+    fail("delivery-execution-replica-limit", "A release supports at most 256 runtime targets including replicas and queue shards.", "Reduce the replica or shard count, or split independent applications.");
   }
   const canonicalDiagnostics = [...new Map(diagnostics.map((item) => [JSON.stringify(item), item])).values()].sort((a, b) => compare2(JSON.stringify(a), JSON.stringify(b)));
   if (canonicalDiagnostics.some((item) => item.severity === "error")) {
@@ -25384,6 +25490,7 @@ function validateExecutionManifest(plan, capabilities = {}) {
         ...command.adapter === null ? {} : { rpc: command.adapter },
         ...command.audit === null ? {} : { audit: command.audit },
         ...command.branches.length === 0 ? {} : { branches: command.branches },
+        ...command.branchesFallback === undefined ? {} : { branchesFallback: command.branchesFallback },
         transaction: command.transaction,
         idempotency: command.idempotency
       }))
@@ -26450,10 +26557,10 @@ import { readFileSync as readFileSync4 } from "node:fs";
 import { resolve as resolve19 } from "node:path";
 
 // src/migration-app-version.ts
-var MIGRATION_APP_VERSION = "0.39.0";
+var MIGRATION_APP_VERSION = "0.39.1";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.41.0";
+var MIGRATION_ELYSIA_VERSION = "0.42.1";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

package/dist/contract-manifest.d.ts

@@ -7,6 +7,7 @@ export interface ContractManifest {
         module: string;
         permission?: string;
         rpc?: string;
+        branchesFallback?: "reject" | "command";
         branches?: Array<{
             when: string;
             adapter: string;

package/dist/database-contracts.d.ts

@@ -11,6 +11,10 @@ export interface DatabaseContractsOptions {
     role: string;
     /** Role-scoped pg_graphql snapshot exported by graphql-schema. Omit when GraphQL is unused. */
     graphql?: GraphqlOptions;
+    /** Registry emitted by application or database code generation. Tracked for contract freshness. */
+    rpcRegistry?: string;
+    /** Generated or exported RPC catalog. Tracked for contract freshness. */
+    rpcCatalog?: string;
     /** Ordered complete migration history. */
     migrations: readonly string[];
 }

package/dist/database-governance-runtime.d.ts

@@ -1,4 +1,4 @@
 import type { DatabaseGovernanceOptions, Diagnostic } from "./types";
-export declare function enforceDatabaseGovernance(options: DatabaseGovernanceOptions): Promise<{
+export declare function enforceDatabaseGovernance(options: DatabaseGovernanceOptions, rpcCapabilities?: readonly string[]): Promise<{
     diagnostics: Diagnostic[];
 }>;