@supacloud/compiler 0.59.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

@@ -2097,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) => [
@@ -2106,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",
@@ -2480,26 +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 ?? [],
-        branchesFallback: command.branchesFallback ?? "reject",
-        ...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,
@@ -15823,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_({
@@ -15992,7 +16025,8 @@ function buildTimeline(events, matchedPlans) {
           attempts: [],
           omittedAttempts: 0
         },
-        attempts: new Map
+        attempts: new Map,
+        ...plan === undefined ? {} : { plan }
       };
       groups.set(key, group);
     }
@@ -16020,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
@@ -18553,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) => {
@@ -18569,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");
@@ -18590,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))
   };
 }
@@ -18665,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");
   }
@@ -23516,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 = () => [{
@@ -23537,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))
@@ -23583,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: [] };
@@ -23653,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."] };
@@ -26513,7 +26560,7 @@ import { resolve as resolve19 } from "node:path";
 var MIGRATION_APP_VERSION = "0.39.1";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.42.0";
+var MIGRATION_ELYSIA_VERSION = "0.42.1";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

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[];
 }>;

package/dist/database-governance-worker.js

@@ -3,6 +3,7 @@ import { readFile, realpath } from "node:fs/promises";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  checkRpcBoundary,
   lintModule,
   readCatalog,
   reconcileModule
@@ -34,13 +35,31 @@ function governanceDiagnostic(message, code = "database-governance") {
     suggestion: "Fix the database source contract, module manifest or live catalog before compiling."
   };
 }
-async function enforceDatabaseGovernance(options) {
+async function enforceDatabaseGovernance(options, rpcCapabilities = []) {
   const projectRoot = await realpath(options.projectRoot ?? ".");
   const sourceReport = await databaseSources(projectRoot, "check");
   const diagnostics = sourceReport.findings.map((finding) => governanceDiagnostic(`${finding.file}: ${finding.message}`, "database-source-contract"));
   if (!sourceReport.ok && diagnostics.length === 0) {
     diagnostics.push(governanceDiagnostic("Database source contract check failed without findings."));
   }
+  if (diagnostics.length > 0)
+    return { diagnostics };
+  if (options.rpcBoundary) {
+    try {
+      const readJson = async (path) => path === undefined ? undefined : JSON.parse(await readFile(await withinRoot(projectRoot, path), "utf8"));
+      const report = checkRpcBoundary({
+        capabilities: rpcCapabilities,
+        registry: await readJson(options.rpcBoundary.registry),
+        catalog: await readJson(options.rpcBoundary.catalog),
+        legacy: await readJson(options.rpcBoundary.legacy)
+      });
+      if (!report.ok) {
+        diagnostics.push(governanceDiagnostic(`RPC capabilities have no registry/catalog source or historical entry: ${report.missing.join(", ")}`, "database-rpc-boundary"));
+      }
+    } catch {
+      diagnostics.push(governanceDiagnostic("RPC boundary artifacts could not be read or parsed.", "database-rpc-boundary"));
+    }
+  }
   if (diagnostics.length > 0)
     return { diagnostics };
   if (options.mode === "check")
@@ -107,11 +126,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 = () => [{
@@ -128,7 +149,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))
@@ -147,9 +168,11 @@ async function checkDatabaseGovernance(rootDir, value) {
 
 // src/database-governance-worker.ts
 try {
-  const options = JSON.parse(await Bun.stdin.text());
+  const payload = JSON.parse(await Bun.stdin.text());
+  const options = payload && typeof payload === "object" && !Array.isArray(payload) && "options" in payload ? payload.options : payload;
+  const rpcCapabilities = payload && typeof payload === "object" && !Array.isArray(payload) && "rpcCapabilities" in payload && Array.isArray(payload.rpcCapabilities) ? payload.rpcCapabilities : [];
   assertDatabaseGovernance(options);
-  process.stdout.write(JSON.stringify(await enforceDatabaseGovernance(options)));
+  process.stdout.write(JSON.stringify(await enforceDatabaseGovernance(options, rpcCapabilities)));
 } catch {
   process.stdout.write(JSON.stringify({ diagnostics: [{
     severity: "error",

package/dist/database-governance.d.ts

@@ -1,4 +1,4 @@
 import type { DatabaseGovernanceOptions, Diagnostic } from "./types";
 export declare function assertDatabaseGovernance(value: unknown): asserts value is DatabaseGovernanceOptions;
 /** A fresh, bounded process avoids stale module imports during incremental compilation. */
-export declare function checkDatabaseGovernance(rootDir: string, value: DatabaseGovernanceOptions | undefined): Promise<Diagnostic[]>;
+export declare function checkDatabaseGovernance(rootDir: string, value: DatabaseGovernanceOptions | undefined, rpcCapabilities?: readonly string[]): Promise<Diagnostic[]>;

package/dist/execution-snapshot.d.ts

@@ -8,6 +8,7 @@ declare const SnapshotSchema: Type.TObject<{
         name: Type.TString;
         command: Type.TOptional<Type.TString>;
         stages: Type.TArray<Type.TString>;
+        stagePaths: Type.TOptional<Type.TArray<Type.TArray<Type.TString>>>;
     }>>;
     commandAliases: Type.TArray<Type.TObject<{
         module: Type.TString;

package/dist/index.js

@@ -2096,6 +2096,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) => [
@@ -2105,46 +2146,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",
@@ -2479,26 +2508,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 ?? [],
-        branchesFallback: command.branchesFallback ?? "reject",
-        ...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,
@@ -16410,7 +16442,8 @@ var init_execution_snapshot = __esm(() => {
       kind: kind2,
       name: text,
       command: Optional(text),
-      stages: _Array_(text)
+      stages: _Array_(text),
+      stagePaths: Optional(_Array_(_Array_(text)))
     }, closed3)),
     commandAliases: _Array_(_Object_({ module: text, name: text, alias: text }, closed3)),
     contexts: _Array_(_Object_({
@@ -18129,7 +18162,8 @@ function buildTimeline(events, matchedPlans) {
           attempts: [],
           omittedAttempts: 0
         },
-        attempts: new Map
+        attempts: new Map,
+        ...plan === undefined ? {} : { plan }
       };
       groups.set(key, group);
     }
@@ -18157,13 +18191,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
@@ -18585,7 +18622,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) => {
@@ -18601,6 +18638,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");
@@ -18622,6 +18661,8 @@ function parseDatabaseContractsOptions(value, directory) {
     ...modelSchema ? { modelSchema: resolve24(directory, modelSchema) } : {},
     role: field("role"),
     ...graphql ? { graphql } : {},
+    ...rpcRegistry ? { rpcRegistry: resolve24(directory, rpcRegistry) } : {},
+    ...rpcCatalog ? { rpcCatalog: resolve24(directory, rpcCatalog) } : {},
     migrations: migrations.map((file) => resolve24(directory, file))
   };
 }
@@ -18697,6 +18738,10 @@ async function generateDatabaseContracts(options, check = false) {
   }
   if (options.graphql)
     await addInput(resolve24(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) => resolve24(rootDir, path))).size !== options.migrations.length) {
     throw new Error("Duplicate migration in database contracts configuration");
   }
@@ -23477,11 +23522,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 = () => [{
@@ -23498,7 +23545,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))
@@ -23544,7 +23591,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: [] };
@@ -23614,7 +23661,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."] };
@@ -25765,7 +25812,7 @@ import { resolve as resolve17 } from "node:path";
 var MIGRATION_APP_VERSION = "0.39.1";
 
 // src/migration-elysia-version.ts
-var MIGRATION_ELYSIA_VERSION = "0.42.0";
+var MIGRATION_ELYSIA_VERSION = "0.42.1";
 
 // src/migration-policy.ts
 var cachedCompilerVersion;

package/dist/inspect.d.ts

@@ -7,6 +7,8 @@ export interface ExecutionPlan {
     command?: string;
     /** Standard governance contract. Audit success follows the handler; custom executors may short-circuit. */
     stages: string[];
+    /** Alternative stage sequences for commands with conditional execution paths. */
+    stagePaths?: string[][];
 }
 export interface ContextPack {
     version: 1;

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

@@ -1 +1 @@
-export declare const MIGRATION_ELYSIA_VERSION = "0.42.0";
+export declare const MIGRATION_ELYSIA_VERSION = "0.42.1";

package/dist/types.d.ts

@@ -775,6 +775,15 @@ export interface DatabaseGovernanceOptions {
     databaseUrlEnv?: string;
     /** Schemas included in the live Catalog query. */
     schemas?: string[];
+    /** Optional offline gate connecting named RPC capabilities to maintained artifacts. */
+    rpcBoundary?: {
+        /** JSON registry produced by application or database code generation. */
+        registry?: string;
+        /** Generated or exported RPC catalog JSON. */
+        catalog?: string;
+        /** JSON list/object containing explicitly historical RPC capability names. */
+        legacy?: string;
+    };
 }
 export interface ModuleBoundaryRule {
     /** Source module tag pattern or tag (for example, 'type:ui', 'scope:case', or '*'). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.59.0",
+  "version": "0.60.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,7 +57,7 @@
     "directory": "packages/compiler"
   },
   "dependencies": {
-    "@supacloud/db": "0.23.1",
+    "@supacloud/db": "0.24.0",
     "@supacloud/delivery": "0.26.0",
     "typebox": "1.4.3",
     "@graphql-codegen/core": "^6.2.2",
@@ -68,7 +68,7 @@
     "typescript": "7.1.0-beta"
   },
   "overrides": {
-    "@supacloud/contracts": "0.16.0",
+    "@supacloud/contracts": "0.16.1",
     "@graphql-tools/utils": "^12.0.4",
     "@whatwg-node/promise-helpers": "2.0.0",
     "deepmerge-ts": "8.0.2",