@supacloud/compiler 0.32.0 → 0.34.0

package/README.md

@@ -495,6 +495,11 @@ route 会自动按 HTTP status 执行内置 response decoder，并返回 schema
 OpenAPI。`buildRouteUrl` 和 `createApiClient` 可直接复用，也支持动态 headers
 和请求拦截器。
 
+每个生成 route 还会按 HTTP 方法暴露 `.query()` 或 `.mutate()` procedure
+facade，并在 `API_PROCEDURES` 中输出 Command/幂等元数据。声明
+`idempotency: "required"` 的 mutation 必须显式传入稳定的 `idempotencyKey`；
+客户端不会静默生成新 key。
+
 ### Migration from manual decoders
 
 旧版本要求调用方为每个有响应 schema 的 route 传入 decoder。升级后删除该

package/dist/cli.js

@@ -2245,6 +2245,8 @@ function renderClient(graph, options) {
   const schemaLocals = new Map;
   const usedTypeNames = new Set;
   const allRoutes = [];
+  const allProcedures = [];
+  const commandByClassName = new Map(graph.modules.flatMap((module) => module.commands.map((command) => [command.className, command])));
   let usesStatic = false;
   let usesValue = false;
   const uniqueTypeName = (candidate) => {
@@ -2375,8 +2377,30 @@ 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,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          kind: procedureKind,
+          idempotency: idempotencyMode
+        };
+        allProcedures.push({
+          method: route.method,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          kind: procedureKind,
+          ...command?.name === undefined ? {} : { command: command.name },
+          ...command?.permission === undefined ? {} : { permission: command.permission },
+          idempotency: idempotencyMode
+        });
         routeMethods.push(`
-    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}),`);
+    ${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)}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -2407,6 +2431,66 @@ function renderClient(graph, options) {
     "",
     "export type ResponseDecoder<T> = (value: unknown) => T;",
     "",
+    'export type ProcedureKind = "query" | "mutation";',
+    'export type IdempotencyMode = "required" | "none";',
+    "",
+    "export interface ProcedureMetadata<",
+    "  Kind extends ProcedureKind = ProcedureKind,",
+    "  Idempotency extends IdempotencyMode = IdempotencyMode,",
+    "> {",
+    "  key: string;",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  kind: Kind;",
+    "  idempotency: Idempotency;",
+    "}",
+    "",
+    "export interface ProcedureExecutionOptions {",
+    "  /** Reuse the same key when retrying an uncertain mutation. */",
+    "  idempotencyKey?: string;",
+    "  signal?: AbortSignal;",
+    "}",
+    "",
+    "export type RequiredProcedureExecutionOptions = ProcedureExecutionOptions & { idempotencyKey: string };",
+    "",
+    "type ProcedureResult<Result> = [Result] extends [never] ? unknown : Result;",
+    "",
+    "type ProcedureArgs<Options extends ClientRequestOptions, Idempotency extends IdempotencyMode> =",
+    '  Idempotency extends "required"',
+    "    ? {} extends Options",
+    "      ? [execution: RequiredProcedureExecutionOptions] | [input: Options, execution: RequiredProcedureExecutionOptions]",
+    "      : [input: Options, execution: RequiredProcedureExecutionOptions]",
+    "    : {} extends Options",
+    "      ? [input?: Options, execution?: ProcedureExecutionOptions]",
+    "      : [input: Options, execution?: ProcedureExecutionOptions];",
+    "",
+    "export type ProcedureCall<",
+    "  Options extends ClientRequestOptions = ClientRequestOptions,",
+    "  Result = never,",
+    '  Idempotency extends IdempotencyMode = "none",',
+    "> = (...args: ProcedureArgs<Options, Idempotency>) => Promise<ProcedureResult<Result>>;",
+    "",
+    "export type QueryableProcedure<",
+    "  Options extends ClientRequestOptions,",
+    "  Result,",
+    "  Idempotency extends IdempotencyMode,",
+    "  Kind extends ProcedureKind,",
+    "> = ProcedureCall<Options, Result, Idempotency> & {",
+    "  readonly __supacloudProcedure: ProcedureMetadata<Kind, Idempotency>;",
+    "  readonly __supacloudInput?: Options;",
+    "};",
+    "",
+    "export type ProcedureMember<",
+    "  Options extends ClientRequestOptions,",
+    "  Result,",
+    "  Kind extends ProcedureKind,",
+    "  Idempotency extends IdempotencyMode,",
+    '> = Kind extends "query"',
+    '  ? { query: QueryableProcedure<Options, Result, Idempotency, "query"> }',
+    '  : { mutate: QueryableProcedure<Options, Result, Idempotency, "mutation"> };',
+    "",
     'export type ApiClientErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED";',
     "",
     "export interface ApiClientErrorDetails {",
@@ -2450,6 +2534,17 @@ function renderClient(graph, options) {
     "    : { (options: Options): Promise<Result>; <T>(options: Options, decode: ResponseDecoder<T>): Promise<T> }",
     ") & ((...args: {} extends Options ? [options?: Options] : [options: Options]) => Promise<[Result] extends [never] ? unknown : Result>);",
     "",
+    "export interface ApiProcedureDefinition {",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  kind: ProcedureKind;",
+    "  command?: string;",
+    "  permission?: string;",
+    "  idempotency: IdempotencyMode;",
+    "}",
+    "",
     ...routeTypes,
     ...routeTypes.length > 0 ? [""] : [],
     "export interface HttpInterceptorRequest {",
@@ -2457,6 +2552,7 @@ function renderClient(graph, options) {
     "  url: string;",
     "  headers: Record<string, string>;",
     "  body?: unknown;",
+    "  signal?: AbortSignal;",
     "}",
     "",
     "export type HttpInterceptorFn = (",
@@ -2475,6 +2571,8 @@ function renderClient(graph, options) {
     "",
     "export const API_ROUTES = " + JSON.stringify(allRoutes, null, 2) + " as const;",
     "",
+    "export const API_PROCEDURES: readonly ApiProcedureDefinition[] = " + JSON.stringify(allProcedures, null, 2) + ";",
+    "",
     "export type AppRoutePath = typeof API_ROUTES[number]['path'];",
     "",
     "export const API_SCHEMAS = [",
@@ -2700,6 +2798,7 @@ function renderClient(graph, options) {
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
     "    raw?: boolean,",
+    "    execution?: ProcedureExecutionOptions,",
     "  ): Promise<T>;",
     "  async function request<T>(",
     "    method: string,",
@@ -2709,6 +2808,7 @@ function renderClient(graph, options) {
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
     "    raw?: boolean,",
+    "    execution?: ProcedureExecutionOptions,",
     "  ): Promise<T | unknown>;",
     "  async function request(",
     "    method: string,",
@@ -2723,6 +2823,7 @@ function renderClient(graph, options) {
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
     "    raw = false,",
+    "    execution?: ProcedureExecutionOptions,",
     "  ): Promise<T | unknown> {",
     "    const url = `${baseUrl}${buildRouteUrl(path, options.params, options.query)}`;",
     '    const customHeaders = typeof config.headers === "function" ? await config.headers() : config.headers;',
@@ -2748,9 +2849,10 @@ function renderClient(graph, options) {
     "        headers: reqPayload.headers,",
     "        ...(reqPayload.body === undefined ? {} : { body: raw ? rawBody(reqPayload.body) : JSON.stringify(reqPayload.body) }),",
     '        ...(raw && reqPayload.body instanceof ReadableStream ? { duplex: "half" } : {}),',
+    "        ...(reqPayload.signal === undefined ? {} : { signal: reqPayload.signal }),",
     "      });",
     "    };",
-    "    const response = await executeChain(0, { method, url, headers, body: options.body });",
+    "    const response = await executeChain(0, { method, url, headers, body: options.body, ...(execution?.signal === undefined ? {} : { signal: execution.signal }) });",
     "    const declaredSchema = responseSchemas ? selectResponseSchema(response.status, responseSchemas) : undefined;",
     "    const failure = (code: ApiClientErrorCode, message: string) => new ApiClientError(message, {",
     '      code, method, path, status: response.status, requestId: response.headers.get("x-request-id"),',
@@ -2788,7 +2890,44 @@ function renderClient(graph, options) {
     "    return decode ? decode(checked) : checked;",
     "  }",
     "",
-    `  function makeRoute<Options extends ClientRequestOptions, Result = never>(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): RouteMethod<Options, Result> {`,
+    "  function hasHeader(headers: Record<string, string>, name: string): boolean {",
+    "    return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());",
+    "  }",
+    "",
+    "  function withProcedureExecution(",
+    "    options: ClientRequestOptions,",
+    "    execution: ProcedureExecutionOptions | undefined,",
+    "    idempotency: IdempotencyMode,",
+    "  ): ClientRequestOptions {",
+    "    const headers = { ...(options.headers as Record<string, string> | undefined) };",
+    "    if (execution?.idempotencyKey !== undefined) {",
+    "      if (!/^[A-Za-z0-9._:-]{1,512}$/.test(execution.idempotencyKey)) {",
+    '        throw new TypeError("idempotencyKey must contain only safe header characters and be at most 512 characters");',
+    "      }",
+    '      headers["idempotency-key"] = execution.idempotencyKey;',
+    "    }",
+    '    if (idempotency === "required" && !hasHeader(headers, "idempotency-key")) {',
+    '      throw new TypeError("This mutation requires an idempotencyKey");',
+    "    }",
+    "    return Object.keys(headers).length === 0 ? options : { ...options, headers };",
+    "  }",
+    "",
+    "  function isProcedureExecution(value: unknown): value is ProcedureExecutionOptions {",
+    '    if (value === null || typeof value !== "object" || Array.isArray(value)) return false;',
+    '    return Object.hasOwn(value, "idempotencyKey") || Object.hasOwn(value, "signal");',
+    "  }",
+    "",
+    `  function makeProcedure<Options extends ClientRequestOptions, Result = never, Idempotency extends IdempotencyMode = "none", Kind extends ProcedureKind = ProcedureKind>(metadata: ProcedureMetadata<Kind, Idempotency>, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): QueryableProcedure<Options, Result, Idempotency, Kind> {`,
+    "    const procedure = async (first?: Options | ProcedureExecutionOptions, second?: ProcedureExecutionOptions): Promise<unknown> => {",
+    "      const execution = second ?? (isProcedureExecution(first) ? first : undefined);",
+    "      const input = (execution === first ? undefined : first) ?? {};",
+    "      const requestOptions = withProcedureExecution(input as ClientRequestOptions, execution, metadata.idempotency);",
+    "      return request(metadata.method, metadata.path, requestOptions, undefined, responseSchemas, responseKind, raw, execution);",
+    "    };",
+    "    return Object.assign(procedure, { __supacloudProcedure: Object.freeze(metadata) }) as QueryableProcedure<Options, Result, Idempotency, Kind>;",
+    "  }",
+    "",
+    `  function makeRoute<Options extends ClientRequestOptions, Result = never, Kind extends ProcedureKind = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, kind?: Kind, idempotency: Idempotency = "none" as Idempotency, metadata?: ProcedureMetadata<Kind, Idempotency>): RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency> {`,
     "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
     "    function route(options: Options): Promise<Result>;",
     "    function route(options?: Options): Promise<unknown>;",
@@ -2796,13 +2935,16 @@ function renderClient(graph, options) {
     "      const requestOptions = options ?? {};",
     "      return request(method, path, requestOptions, decode, responseSchemas, responseKind, raw);",
     "    }",
-    "    return route as RouteMethod<Options, Result>;",
+    '    if (kind === "query" && metadata) Object.assign(route, { query: makeProcedure<Options, Result, Idempotency, "query">(metadata as ProcedureMetadata<"query", Idempotency>, responseSchemas, responseKind, raw) });',
+    '    if (kind === "mutation" && metadata) Object.assign(route, { mutate: makeProcedure<Options, Result, Idempotency, "mutation">(metadata as ProcedureMetadata<"mutation", Idempotency>, responseSchemas, responseKind, raw) });',
+    "    return route as RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency>;",
     "  }",
     "",
     "  return {",
     "    request,",
     "    buildRouteUrl,",
     "    routes: API_ROUTES,",
+    "    procedures: API_PROCEDURES,",
     ...controllerEntries,
     "  };",
     "}",
@@ -15670,6 +15812,9 @@ 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) {
+    throw new Error("Invalid delivery replica count.");
+  }
   for (const target of value.plan.targets) {
     if (target.execution && (target.kind !== "jobs" || target.isolation !== "process" || target.execution.target !== target.name || target.jobs.length !== 1 || target.jobs[0]?.name !== target.execution.taskKey || value.objects.find((object) => object.name === target.name)?.entryKind !== "bun-worker-application")) {
       throw new Error("Invalid delivery execution binding.");
@@ -15683,7 +15828,7 @@ function parseDeliveryBuildManifest(value) {
   }
   for (const object of value.objects) {
     const target = value.plan.targets.find((target) => target.name === object.name);
-    if (object.entryKind === "bun-worker-application" && target?.kind !== "jobs" || object.entryKind === "bun-http-application" && target?.kind === "jobs") {
+    if (["bun-worker-application", "go-worker-application", "scriptc-worker-application"].includes(object.entryKind) && target?.kind !== "jobs" || object.entryKind === "bun-http-application" && target?.kind === "jobs") {
       throw new Error("Delivery executable kind does not match its target.");
     }
     if (new Set(object.files.map((file) => file.path)).size !== object.files.length || !object.files.some((file) => file.path === object.entrypoint) || deliveryObjectDigest(object) !== object.objectId) {
@@ -15721,7 +15866,9 @@ var init_delivery_build_schema = __esm(() => {
     entryKind: Union([
       Literal("compiled-module-factory"),
       Literal("bun-http-application"),
-      Literal("bun-worker-application")
+      Literal("bun-worker-application"),
+      Literal("go-worker-application"),
+      Literal("scriptc-worker-application")
     ]),
     runtimeImports: _Array_(String2()),
     files: _Array_(_Object_({
@@ -16252,6 +16399,107 @@ var init_application_activation = __esm(() => {
   }, { additionalProperties: false });
 });
 
+// node_modules/@supacloud/delivery/src/deployment-evidence.ts
+var closed6, sha256, isoDate, status, evidenceStatus, DEPLOYMENT_EVIDENCE_SCHEMA = "supacloud.deployment-evidence.v1", DatabaseProviderSchema, componentName, DeploymentComponentEvidenceSchema, DeploymentEvidenceSchema;
+var init_deployment_evidence = __esm(() => {
+  init_build();
+  init_value2();
+  init_application_configuration();
+  init_application_release();
+  closed6 = { additionalProperties: false };
+  sha256 = String2({ pattern: "^[a-f0-9]{64}$" });
+  isoDate = String2({ minLength: 20, maxLength: 40 });
+  status = Union([
+    Literal("confirmed"),
+    Literal("failed"),
+    Literal("unknown")
+  ]);
+  evidenceStatus = Union([
+    Literal("confirmed"),
+    Literal("failed"),
+    Literal("unknown"),
+    Literal("incomplete")
+  ]);
+  DatabaseProviderSchema = _Object_({
+    provider: String2({ minLength: 1, maxLength: 64, pattern: "^[a-z][a-z0-9_.-]*$" }),
+    version: String2({ minLength: 1, maxLength: 64 }),
+    topology: Union([Literal("single-node"), Literal("distributed")]),
+    migration: _Object_({
+      status,
+      inventory_sha256: Union([sha256, Null()]),
+      compatibility: Union([
+        Literal("verified"),
+        Literal("not-proven"),
+        Literal("failed")
+      ])
+    }, closed6),
+    backup: _Object_({
+      status,
+      latest_success_at: Union([isoDate, Null()]),
+      freshness_seconds: Union([Integer({ minimum: 0 }), Null()])
+    }, closed6),
+    recovery: _Object_({
+      status,
+      drill_id: Union([String2({ minLength: 1, maxLength: 128 }), Null()]),
+      rpo_seconds: Union([Integer({ minimum: 0 }), Null()]),
+      rto_seconds: Union([Integer({ minimum: 0 }), Null()])
+    }, closed6)
+  }, closed6);
+  componentName = Union([
+    Literal("management-api"),
+    Literal("web-console"),
+    Literal("edge-runtime"),
+    Literal("worker"),
+    Literal("postgres"),
+    Literal("postgrest"),
+    Literal("gotrue"),
+    Literal("storage"),
+    Literal("realtime")
+  ]);
+  DeploymentComponentEvidenceSchema = _Object_({
+    name: componentName,
+    version: Union([String2({ minLength: 1, maxLength: 128 }), Null()]),
+    status,
+    health_check: Union([String2({ minLength: 1, maxLength: 256 }), Null()]),
+    checked_at: Union([isoDate, Null()])
+  }, closed6);
+  DeploymentEvidenceSchema = _Object_({
+    schema: Literal(DEPLOYMENT_EVIDENCE_SCHEMA),
+    status: evidenceStatus,
+    recorded_at: isoDate,
+    scope: _Object_({
+      project_ref: String2({ pattern: "^[a-z0-9-]{1,20}$" }),
+      application_id: ApplicationIdSchema,
+      environment_id: ApplicationIdSchema
+    }, closed6),
+    source: _Object_({
+      commit_sha: Union([String2({ pattern: "^[0-9a-f]{7,64}$" }), Null()]),
+      manifest_sha256: sha256,
+      contract_schema: Union([String2({ minLength: 1, maxLength: 128 }), Null()]),
+      environment_binding_version: Union([sha256, Null()])
+    }, closed6),
+    database: DatabaseProviderSchema,
+    components: _Array_(DeploymentComponentEvidenceSchema, { minItems: 1, maxItems: 32 }),
+    activation: _Object_({
+      release_id: ApplicationReleaseIdSchema,
+      configuration_id: ApplicationConfigurationIdSchema,
+      activation_id: ApplicationConfigurationIdSchema
+    }, closed6),
+    health: _Object_({
+      status,
+      checked_at: Union([isoDate, Null()]),
+      authenticated_smoke: status
+    }, closed6),
+    rollback: _Object_({
+      release_id: Union([ApplicationReleaseIdSchema, Null()]),
+      configuration_id: Union([ApplicationConfigurationIdSchema, Null()]),
+      status: Union([Literal("ready"), Literal("not-ready"), Literal("unknown")]),
+      result: Union([status, Null()])
+    }, closed6),
+    notes: _Array_(String2({ minLength: 1, maxLength: 512 }), { maxItems: 32 })
+  }, closed6);
+});
+
 // node_modules/@supacloud/delivery/src/application-runtime-identity.ts
 var APPLICATION_RUNTIME_PROBE_PATH = "/.well-known/supacloud/runtime", ApplicationRuntimeIdentitySchema, ApplicationReadinessReportSchema;
 var init_application_runtime_identity = __esm(() => {
@@ -16374,6 +16622,7 @@ var init_src = __esm(() => {
   init_application_activation();
   init_application_release();
   init_application_configuration();
+  init_deployment_evidence();
   init_application_runtime_identity();
   init_delivery_build_schema();
   init_delivery_migration_archive();
@@ -23408,7 +23657,7 @@ function isRecord2(value) {
 function arrayLength(value) {
   return Array.isArray(value) ? value.length : undefined;
 }
-async function sha256(path) {
+async function sha2562(path) {
   return createHash10("sha256").update(await readFile11(path)).digest("hex");
 }
 function overallStatus(findings) {
@@ -23482,7 +23731,7 @@ async function assessMigration(options) {
     contractsManifest = {
       path: contractsManifestPath,
       present: true,
-      sha256: await sha256(contractsManifestPath),
+      sha256: await sha2562(contractsManifestPath),
       version: 1,
       ...arrayLength(parsed.commands) === undefined ? {} : { commands: arrayLength(parsed.commands) },
       ...arrayLength(parsed.routes) === undefined ? {} : { routes: arrayLength(parsed.routes) },
@@ -23505,9 +23754,9 @@ async function assessMigration(options) {
       const diff = diffOpenApiDocuments(await readOpenApiJson(baselinePath), await readOpenApiJson(currentPath));
       openApi = {
         baselinePath,
-        baselineSha256: await sha256(baselinePath),
+        baselineSha256: await sha2562(baselinePath),
         currentPath,
-        currentSha256: await sha256(currentPath),
+        currentSha256: await sha2562(currentPath),
         diff
       };
       if (!diff.ok) {

package/dist/index.js

@@ -2244,6 +2244,8 @@ function renderClient(graph, options) {
   const schemaLocals = new Map;
   const usedTypeNames = new Set;
   const allRoutes = [];
+  const allProcedures = [];
+  const commandByClassName = new Map(graph.modules.flatMap((module) => module.commands.map((command) => [command.className, command])));
   let usesStatic = false;
   let usesValue = false;
   const uniqueTypeName = (candidate) => {
@@ -2374,8 +2376,30 @@ 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,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          kind: procedureKind,
+          idempotency: idempotencyMode
+        };
+        allProcedures.push({
+          method: route.method,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          kind: procedureKind,
+          ...command?.name === undefined ? {} : { command: command.name },
+          ...command?.permission === undefined ? {} : { permission: command.permission },
+          idempotency: idempotencyMode
+        });
         routeMethods.push(`
-    ${route.handler}: makeRoute<${requestTypeName}, ${responseType === "never" ? "never" : responseTypeName}>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, ${responseSchemaArgument}, ${responseKindArgument}, ${route.parse === "none"}),`);
+    ${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)}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -2406,6 +2430,66 @@ function renderClient(graph, options) {
     "",
     "export type ResponseDecoder<T> = (value: unknown) => T;",
     "",
+    'export type ProcedureKind = "query" | "mutation";',
+    'export type IdempotencyMode = "required" | "none";',
+    "",
+    "export interface ProcedureMetadata<",
+    "  Kind extends ProcedureKind = ProcedureKind,",
+    "  Idempotency extends IdempotencyMode = IdempotencyMode,",
+    "> {",
+    "  key: string;",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  kind: Kind;",
+    "  idempotency: Idempotency;",
+    "}",
+    "",
+    "export interface ProcedureExecutionOptions {",
+    "  /** Reuse the same key when retrying an uncertain mutation. */",
+    "  idempotencyKey?: string;",
+    "  signal?: AbortSignal;",
+    "}",
+    "",
+    "export type RequiredProcedureExecutionOptions = ProcedureExecutionOptions & { idempotencyKey: string };",
+    "",
+    "type ProcedureResult<Result> = [Result] extends [never] ? unknown : Result;",
+    "",
+    "type ProcedureArgs<Options extends ClientRequestOptions, Idempotency extends IdempotencyMode> =",
+    '  Idempotency extends "required"',
+    "    ? {} extends Options",
+    "      ? [execution: RequiredProcedureExecutionOptions] | [input: Options, execution: RequiredProcedureExecutionOptions]",
+    "      : [input: Options, execution: RequiredProcedureExecutionOptions]",
+    "    : {} extends Options",
+    "      ? [input?: Options, execution?: ProcedureExecutionOptions]",
+    "      : [input: Options, execution?: ProcedureExecutionOptions];",
+    "",
+    "export type ProcedureCall<",
+    "  Options extends ClientRequestOptions = ClientRequestOptions,",
+    "  Result = never,",
+    '  Idempotency extends IdempotencyMode = "none",',
+    "> = (...args: ProcedureArgs<Options, Idempotency>) => Promise<ProcedureResult<Result>>;",
+    "",
+    "export type QueryableProcedure<",
+    "  Options extends ClientRequestOptions,",
+    "  Result,",
+    "  Idempotency extends IdempotencyMode,",
+    "  Kind extends ProcedureKind,",
+    "> = ProcedureCall<Options, Result, Idempotency> & {",
+    "  readonly __supacloudProcedure: ProcedureMetadata<Kind, Idempotency>;",
+    "  readonly __supacloudInput?: Options;",
+    "};",
+    "",
+    "export type ProcedureMember<",
+    "  Options extends ClientRequestOptions,",
+    "  Result,",
+    "  Kind extends ProcedureKind,",
+    "  Idempotency extends IdempotencyMode,",
+    '> = Kind extends "query"',
+    '  ? { query: QueryableProcedure<Options, Result, Idempotency, "query"> }',
+    '  : { mutate: QueryableProcedure<Options, Result, Idempotency, "mutation"> };',
+    "",
     'export type ApiClientErrorCode = "API_HTTP_ERROR" | "API_RESPONSE_INVALID" | "API_RESPONSE_UNDECLARED";',
     "",
     "export interface ApiClientErrorDetails {",
@@ -2449,6 +2533,17 @@ function renderClient(graph, options) {
     "    : { (options: Options): Promise<Result>; <T>(options: Options, decode: ResponseDecoder<T>): Promise<T> }",
     ") & ((...args: {} extends Options ? [options?: Options] : [options: Options]) => Promise<[Result] extends [never] ? unknown : Result>);",
     "",
+    "export interface ApiProcedureDefinition {",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  kind: ProcedureKind;",
+    "  command?: string;",
+    "  permission?: string;",
+    "  idempotency: IdempotencyMode;",
+    "}",
+    "",
     ...routeTypes,
     ...routeTypes.length > 0 ? [""] : [],
     "export interface HttpInterceptorRequest {",
@@ -2456,6 +2551,7 @@ function renderClient(graph, options) {
     "  url: string;",
     "  headers: Record<string, string>;",
     "  body?: unknown;",
+    "  signal?: AbortSignal;",
     "}",
     "",
     "export type HttpInterceptorFn = (",
@@ -2474,6 +2570,8 @@ function renderClient(graph, options) {
     "",
     "export const API_ROUTES = " + JSON.stringify(allRoutes, null, 2) + " as const;",
     "",
+    "export const API_PROCEDURES: readonly ApiProcedureDefinition[] = " + JSON.stringify(allProcedures, null, 2) + ";",
+    "",
     "export type AppRoutePath = typeof API_ROUTES[number]['path'];",
     "",
     "export const API_SCHEMAS = [",
@@ -2699,6 +2797,7 @@ function renderClient(graph, options) {
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
     "    raw?: boolean,",
+    "    execution?: ProcedureExecutionOptions,",
     "  ): Promise<T>;",
     "  async function request<T>(",
     "    method: string,",
@@ -2708,6 +2807,7 @@ function renderClient(graph, options) {
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
     "    raw?: boolean,",
+    "    execution?: ProcedureExecutionOptions,",
     "  ): Promise<T | unknown>;",
     "  async function request(",
     "    method: string,",
@@ -2722,6 +2822,7 @@ function renderClient(graph, options) {
     `    responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>,`,
     "    responseKind?: string,",
     "    raw = false,",
+    "    execution?: ProcedureExecutionOptions,",
     "  ): Promise<T | unknown> {",
     "    const url = `${baseUrl}${buildRouteUrl(path, options.params, options.query)}`;",
     '    const customHeaders = typeof config.headers === "function" ? await config.headers() : config.headers;',
@@ -2747,9 +2848,10 @@ function renderClient(graph, options) {
     "        headers: reqPayload.headers,",
     "        ...(reqPayload.body === undefined ? {} : { body: raw ? rawBody(reqPayload.body) : JSON.stringify(reqPayload.body) }),",
     '        ...(raw && reqPayload.body instanceof ReadableStream ? { duplex: "half" } : {}),',
+    "        ...(reqPayload.signal === undefined ? {} : { signal: reqPayload.signal }),",
     "      });",
     "    };",
-    "    const response = await executeChain(0, { method, url, headers, body: options.body });",
+    "    const response = await executeChain(0, { method, url, headers, body: options.body, ...(execution?.signal === undefined ? {} : { signal: execution.signal }) });",
     "    const declaredSchema = responseSchemas ? selectResponseSchema(response.status, responseSchemas) : undefined;",
     "    const failure = (code: ApiClientErrorCode, message: string) => new ApiClientError(message, {",
     '      code, method, path, status: response.status, requestId: response.headers.get("x-request-id"),',
@@ -2787,7 +2889,44 @@ function renderClient(graph, options) {
     "    return decode ? decode(checked) : checked;",
     "  }",
     "",
-    `  function makeRoute<Options extends ClientRequestOptions, Result = never>(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): RouteMethod<Options, Result> {`,
+    "  function hasHeader(headers: Record<string, string>, name: string): boolean {",
+    "    return Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase());",
+    "  }",
+    "",
+    "  function withProcedureExecution(",
+    "    options: ClientRequestOptions,",
+    "    execution: ProcedureExecutionOptions | undefined,",
+    "    idempotency: IdempotencyMode,",
+    "  ): ClientRequestOptions {",
+    "    const headers = { ...(options.headers as Record<string, string> | undefined) };",
+    "    if (execution?.idempotencyKey !== undefined) {",
+    "      if (!/^[A-Za-z0-9._:-]{1,512}$/.test(execution.idempotencyKey)) {",
+    '        throw new TypeError("idempotencyKey must contain only safe header characters and be at most 512 characters");',
+    "      }",
+    '      headers["idempotency-key"] = execution.idempotencyKey;',
+    "    }",
+    '    if (idempotency === "required" && !hasHeader(headers, "idempotency-key")) {',
+    '      throw new TypeError("This mutation requires an idempotencyKey");',
+    "    }",
+    "    return Object.keys(headers).length === 0 ? options : { ...options, headers };",
+    "  }",
+    "",
+    "  function isProcedureExecution(value: unknown): value is ProcedureExecutionOptions {",
+    '    if (value === null || typeof value !== "object" || Array.isArray(value)) return false;',
+    '    return Object.hasOwn(value, "idempotencyKey") || Object.hasOwn(value, "signal");',
+    "  }",
+    "",
+    `  function makeProcedure<Options extends ClientRequestOptions, Result = never, Idempotency extends IdempotencyMode = "none", Kind extends ProcedureKind = ProcedureKind>(metadata: ProcedureMetadata<Kind, Idempotency>, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false): QueryableProcedure<Options, Result, Idempotency, Kind> {`,
+    "    const procedure = async (first?: Options | ProcedureExecutionOptions, second?: ProcedureExecutionOptions): Promise<unknown> => {",
+    "      const execution = second ?? (isProcedureExecution(first) ? first : undefined);",
+    "      const input = (execution === first ? undefined : first) ?? {};",
+    "      const requestOptions = withProcedureExecution(input as ClientRequestOptions, execution, metadata.idempotency);",
+    "      return request(metadata.method, metadata.path, requestOptions, undefined, responseSchemas, responseKind, raw, execution);",
+    "    };",
+    "    return Object.assign(procedure, { __supacloudProcedure: Object.freeze(metadata) }) as QueryableProcedure<Options, Result, Idempotency, Kind>;",
+    "  }",
+    "",
+    `  function makeRoute<Options extends ClientRequestOptions, Result = never, Kind extends ProcedureKind = never, Idempotency extends IdempotencyMode = "none">(method: string, path: string, responseSchemas?: Readonly<Record<string, ${responseSchemaType}>>, responseKind?: string, raw = false, kind?: Kind, idempotency: Idempotency = "none" as Idempotency, metadata?: ProcedureMetadata<Kind, Idempotency>): RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency> {`,
     "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
     "    function route(options: Options): Promise<Result>;",
     "    function route(options?: Options): Promise<unknown>;",
@@ -2795,13 +2934,16 @@ function renderClient(graph, options) {
     "      const requestOptions = options ?? {};",
     "      return request(method, path, requestOptions, decode, responseSchemas, responseKind, raw);",
     "    }",
-    "    return route as RouteMethod<Options, Result>;",
+    '    if (kind === "query" && metadata) Object.assign(route, { query: makeProcedure<Options, Result, Idempotency, "query">(metadata as ProcedureMetadata<"query", Idempotency>, responseSchemas, responseKind, raw) });',
+    '    if (kind === "mutation" && metadata) Object.assign(route, { mutate: makeProcedure<Options, Result, Idempotency, "mutation">(metadata as ProcedureMetadata<"mutation", Idempotency>, responseSchemas, responseKind, raw) });',
+    "    return route as RouteMethod<Options, Result> & ProcedureMember<Options, Result, Kind, Idempotency>;",
     "  }",
     "",
     "  return {",
     "    request,",
     "    buildRouteUrl,",
     "    routes: API_ROUTES,",
+    "    procedures: API_PROCEDURES,",
     ...controllerEntries,
     "  };",
     "}",
@@ -14551,6 +14693,9 @@ 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) {
+    throw new Error("Invalid delivery replica count.");
+  }
   for (const target of value.plan.targets) {
     if (target.execution && (target.kind !== "jobs" || target.isolation !== "process" || target.execution.target !== target.name || target.jobs.length !== 1 || target.jobs[0]?.name !== target.execution.taskKey || value.objects.find((object) => object.name === target.name)?.entryKind !== "bun-worker-application")) {
       throw new Error("Invalid delivery execution binding.");
@@ -14564,7 +14709,7 @@ function parseDeliveryBuildManifest(value) {
   }
   for (const object of value.objects) {
     const target = value.plan.targets.find((target) => target.name === object.name);
-    if (object.entryKind === "bun-worker-application" && target?.kind !== "jobs" || object.entryKind === "bun-http-application" && target?.kind === "jobs") {
+    if (["bun-worker-application", "go-worker-application", "scriptc-worker-application"].includes(object.entryKind) && target?.kind !== "jobs" || object.entryKind === "bun-http-application" && target?.kind === "jobs") {
       throw new Error("Delivery executable kind does not match its target.");
     }
     if (new Set(object.files.map((file) => file.path)).size !== object.files.length || !object.files.some((file) => file.path === object.entrypoint) || deliveryObjectDigest(object) !== object.objectId) {
@@ -14602,7 +14747,9 @@ var init_delivery_build_schema = __esm(() => {
     entryKind: Union([
       Literal("compiled-module-factory"),
       Literal("bun-http-application"),
-      Literal("bun-worker-application")
+      Literal("bun-worker-application"),
+      Literal("go-worker-application"),
+      Literal("scriptc-worker-application")
     ]),
     runtimeImports: _Array_(String2()),
     files: _Array_(_Object_({
@@ -15703,6 +15850,107 @@ var init_application_activation = __esm(() => {
   }, { additionalProperties: false });
 });
 
+// node_modules/@supacloud/delivery/src/deployment-evidence.ts
+var closed6, sha256, isoDate, status, evidenceStatus, DEPLOYMENT_EVIDENCE_SCHEMA = "supacloud.deployment-evidence.v1", DatabaseProviderSchema, componentName, DeploymentComponentEvidenceSchema, DeploymentEvidenceSchema;
+var init_deployment_evidence = __esm(() => {
+  init_build();
+  init_value2();
+  init_application_configuration();
+  init_application_release();
+  closed6 = { additionalProperties: false };
+  sha256 = String2({ pattern: "^[a-f0-9]{64}$" });
+  isoDate = String2({ minLength: 20, maxLength: 40 });
+  status = Union([
+    Literal("confirmed"),
+    Literal("failed"),
+    Literal("unknown")
+  ]);
+  evidenceStatus = Union([
+    Literal("confirmed"),
+    Literal("failed"),
+    Literal("unknown"),
+    Literal("incomplete")
+  ]);
+  DatabaseProviderSchema = _Object_({
+    provider: String2({ minLength: 1, maxLength: 64, pattern: "^[a-z][a-z0-9_.-]*$" }),
+    version: String2({ minLength: 1, maxLength: 64 }),
+    topology: Union([Literal("single-node"), Literal("distributed")]),
+    migration: _Object_({
+      status,
+      inventory_sha256: Union([sha256, Null()]),
+      compatibility: Union([
+        Literal("verified"),
+        Literal("not-proven"),
+        Literal("failed")
+      ])
+    }, closed6),
+    backup: _Object_({
+      status,
+      latest_success_at: Union([isoDate, Null()]),
+      freshness_seconds: Union([Integer({ minimum: 0 }), Null()])
+    }, closed6),
+    recovery: _Object_({
+      status,
+      drill_id: Union([String2({ minLength: 1, maxLength: 128 }), Null()]),
+      rpo_seconds: Union([Integer({ minimum: 0 }), Null()]),
+      rto_seconds: Union([Integer({ minimum: 0 }), Null()])
+    }, closed6)
+  }, closed6);
+  componentName = Union([
+    Literal("management-api"),
+    Literal("web-console"),
+    Literal("edge-runtime"),
+    Literal("worker"),
+    Literal("postgres"),
+    Literal("postgrest"),
+    Literal("gotrue"),
+    Literal("storage"),
+    Literal("realtime")
+  ]);
+  DeploymentComponentEvidenceSchema = _Object_({
+    name: componentName,
+    version: Union([String2({ minLength: 1, maxLength: 128 }), Null()]),
+    status,
+    health_check: Union([String2({ minLength: 1, maxLength: 256 }), Null()]),
+    checked_at: Union([isoDate, Null()])
+  }, closed6);
+  DeploymentEvidenceSchema = _Object_({
+    schema: Literal(DEPLOYMENT_EVIDENCE_SCHEMA),
+    status: evidenceStatus,
+    recorded_at: isoDate,
+    scope: _Object_({
+      project_ref: String2({ pattern: "^[a-z0-9-]{1,20}$" }),
+      application_id: ApplicationIdSchema,
+      environment_id: ApplicationIdSchema
+    }, closed6),
+    source: _Object_({
+      commit_sha: Union([String2({ pattern: "^[0-9a-f]{7,64}$" }), Null()]),
+      manifest_sha256: sha256,
+      contract_schema: Union([String2({ minLength: 1, maxLength: 128 }), Null()]),
+      environment_binding_version: Union([sha256, Null()])
+    }, closed6),
+    database: DatabaseProviderSchema,
+    components: _Array_(DeploymentComponentEvidenceSchema, { minItems: 1, maxItems: 32 }),
+    activation: _Object_({
+      release_id: ApplicationReleaseIdSchema,
+      configuration_id: ApplicationConfigurationIdSchema,
+      activation_id: ApplicationConfigurationIdSchema
+    }, closed6),
+    health: _Object_({
+      status,
+      checked_at: Union([isoDate, Null()]),
+      authenticated_smoke: status
+    }, closed6),
+    rollback: _Object_({
+      release_id: Union([ApplicationReleaseIdSchema, Null()]),
+      configuration_id: Union([ApplicationConfigurationIdSchema, Null()]),
+      status: Union([Literal("ready"), Literal("not-ready"), Literal("unknown")]),
+      result: Union([status, Null()])
+    }, closed6),
+    notes: _Array_(String2({ minLength: 1, maxLength: 512 }), { maxItems: 32 })
+  }, closed6);
+});
+
 // node_modules/@supacloud/delivery/src/application-runtime-identity.ts
 var APPLICATION_RUNTIME_PROBE_PATH = "/.well-known/supacloud/runtime", ApplicationRuntimeIdentitySchema, ApplicationReadinessReportSchema;
 var init_application_runtime_identity = __esm(() => {
@@ -15825,6 +16073,7 @@ var init_src = __esm(() => {
   init_application_activation();
   init_application_release();
   init_application_configuration();
+  init_deployment_evidence();
   init_application_runtime_identity();
   init_delivery_build_schema();
   init_delivery_migration_archive();
@@ -23140,7 +23389,7 @@ function isRecord2(value) {
 function arrayLength(value) {
   return Array.isArray(value) ? value.length : undefined;
 }
-async function sha256(path) {
+async function sha2562(path) {
   return createHash10("sha256").update(await readFile11(path)).digest("hex");
 }
 function overallStatus(findings) {
@@ -23214,7 +23463,7 @@ async function assessMigration(options) {
     contractsManifest = {
       path: contractsManifestPath,
       present: true,
-      sha256: await sha256(contractsManifestPath),
+      sha256: await sha2562(contractsManifestPath),
       version: 1,
       ...arrayLength(parsed.commands) === undefined ? {} : { commands: arrayLength(parsed.commands) },
       ...arrayLength(parsed.routes) === undefined ? {} : { routes: arrayLength(parsed.routes) },
@@ -23237,9 +23486,9 @@ async function assessMigration(options) {
       const diff = diffOpenApiDocuments(await readOpenApiJson(baselinePath), await readOpenApiJson(currentPath));
       openApi = {
         baselinePath,
-        baselineSha256: await sha256(baselinePath),
+        baselineSha256: await sha2562(baselinePath),
         currentPath,
-        currentSha256: await sha256(currentPath),
+        currentSha256: await sha2562(currentPath),
         diff
       };
       if (!diff.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.32.0",
+  "version": "0.34.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",
@@ -54,7 +54,7 @@
     "directory": "packages/compiler"
   },
   "dependencies": {
-    "@supacloud/delivery": "0.5.0",
+    "@supacloud/delivery": "0.7.0",
     "typebox": "1.3.34",
     "@graphql-codegen/core": "^6.2.0",
     "@graphql-codegen/typed-document-node": "^7.1.0",