@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/fn-context/rpc/integration/list-surfaces.d.ts

@@ -0,0 +1,21 @@
+import { type IntegrationSurfaceMeta } from '../../../core/context/types.js';
+import { type RpcContext } from '../trpc-init.js';
+export type ListSurfacesHandler = (opts: {
+    ctx: RpcContext;
+}) => Promise<IntegrationSurfaceMeta[]>;
+export declare function createListSurfacesProcedure(handler: ListSurfacesHandler): import("@trpc/server").TRPCQueryProcedure<{
+    input: void;
+    output: {
+        surfaceKey: "emails" | "envs";
+        target: {
+            kind: "account" | "resource";
+            id: string;
+        };
+        name: string;
+        methods: string[];
+        credentials: Record<string, unknown>;
+        config: Record<string, unknown>;
+    }[];
+    meta: object;
+}>;
+//# sourceMappingURL=list-surfaces.d.ts.map

package/dist/fn-context/rpc/integration/{list-bindings.js → list-surfaces.js}

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { integrationSurfaceKeys } from '../../../core/context/types.js';
 import { publicProcedure } from '../trpc-init.js';
-const boundIntegrationMeta = z.object({
+const integrationSurfaceMeta = z.object({
     surfaceKey: z.enum(integrationSurfaceKeys),
     target: z.object({
         kind: z.enum(['account', 'resource']),
@@ -12,7 +12,7 @@ const boundIntegrationMeta = z.object({
     credentials: z.record(z.string(), z.unknown()),
     config: z.record(z.string(), z.unknown()),
 });
-export function createListBindingsProcedure(handler) {
-    return publicProcedure.output(z.array(boundIntegrationMeta)).query(async (opts) => handler(opts));
+export function createListSurfacesProcedure(handler) {
+    return publicProcedure.output(z.array(integrationSurfaceMeta)).query(async (opts) => handler(opts));
 }
-//# sourceMappingURL=list-bindings.js.map
+//# sourceMappingURL=list-surfaces.js.map

package/dist/fn-context/rpc/log.d.ts

@@ -20,7 +20,17 @@ export type LogEmitHandler = (input: {
 export declare function createLogRouter(emit: LogEmitHandler): import("@trpc/server").TRPCBuiltRouter<{
     ctx: RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
     emit: import("@trpc/server").TRPCMutationProcedure<{

package/dist/fn-context/rpc/platform.d.ts

@@ -6,20 +6,30 @@ import { type RpcContext } from './trpc-init.js';
 export type PlatformInvokeHandler = (input: {
     surface: string;
     method: string;
-    params: Record<string, unknown>;
+    params: unknown;
     ctx: RpcContext;
 }) => Promise<unknown>;
 export declare function createPlatformRouter(invoke: PlatformInvokeHandler): import("@trpc/server").TRPCBuiltRouter<{
     ctx: RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
     invoke: import("@trpc/server").TRPCMutationProcedure<{
         input: {
             surface: string;
             method: string;
-            params?: Record<string, unknown> | undefined;
+            params?: unknown;
         };
         output: unknown;
         meta: object;

package/dist/fn-context/rpc/platform.js

@@ -3,7 +3,7 @@ import { publicProcedure, router } from './trpc-init.js';
 const platformInvokeInput = z.object({
     surface: z.string(),
     method: z.string(),
-    params: z.record(z.string(), z.unknown()).optional(),
+    params: z.unknown().optional(),
 });
 export function createPlatformRouter(invoke) {
     return router({

package/dist/fn-context/rpc/records.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { type RpcContext } from './trpc-init.js';
+/**
+ * `ctx.api.db` of every function and the Orchestrator (15 §10.16): the same
+ * reads and writes as a page script and its actions, over RPC, one call per request. A write is done
+ * each time it is sent (38 §2.7): the platform keeps no key to answer a repeat with the first answer.
+ */
+declare const readInput: z.ZodObject<{
+    table: z.ZodString;
+    method: z.ZodEnum<{
+        count: "count";
+        findFirst: "findFirst";
+        findMany: "findMany";
+        findUnique: "findUnique";
+    }>;
+    args: z.ZodUnknown;
+}, z.core.$strip>;
+declare const writeInput: z.ZodObject<{
+    table: z.ZodString;
+    method: z.ZodEnum<{
+        create: "create";
+        delete: "delete";
+        update: "update";
+        upsert: "upsert";
+    }>;
+    args: z.ZodUnknown;
+}, z.core.$strip>;
+export type RecordsReadInput = z.infer<typeof readInput>;
+export type RecordsWriteInput = z.infer<typeof writeInput>;
+/** What a read or write answers: its value, or the reason it was refused (with its code for a write). */
+export type RecordsResult = {
+    ok: true;
+    value?: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type RecordsHandlers = {
+    read(input: RecordsReadInput & {
+        ctx: RpcContext;
+    }): Promise<RecordsResult>;
+    write(input: RecordsWriteInput & {
+        ctx: RpcContext;
+    }): Promise<RecordsResult>;
+};
+export declare function createRecordsRouter(handlers: RecordsHandlers): import("@trpc/server").TRPCBuiltRouter<{
+    ctx: RpcContext;
+    meta: object;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
+    transformer: false;
+}, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+    read: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            table: string;
+            method: "count" | "findFirst" | "findMany" | "findUnique";
+            args: unknown;
+        };
+        output: RecordsResult;
+        meta: object;
+    }>;
+    write: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            table: string;
+            method: "create" | "delete" | "update" | "upsert";
+            args: unknown;
+        };
+        output: RecordsResult;
+        meta: object;
+    }>;
+}>>;
+export {};
+//# sourceMappingURL=records.d.ts.map

package/dist/fn-context/rpc/records.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { publicProcedure, router } from './trpc-init.js';
+/**
+ * `ctx.api.db` of every function and the Orchestrator (15 §10.16): the same
+ * reads and writes as a page script and its actions, over RPC, one call per request. A write is done
+ * each time it is sent (38 §2.7): the platform keeps no key to answer a repeat with the first answer.
+ */
+const readInput = z.object({
+    table: z.string().min(1),
+    method: z.enum(['findUnique', 'findFirst', 'findMany', 'count']),
+    args: z.unknown(),
+});
+const writeInput = z.object({
+    table: z.string().min(1),
+    method: z.enum(['create', 'update', 'upsert', 'delete']),
+    args: z.unknown(),
+});
+export function createRecordsRouter(handlers) {
+    return router({
+        read: publicProcedure.input(readInput).mutation(({ ctx, input }) => handlers.read({ ...input, ctx })),
+        write: publicProcedure.input(writeInput).mutation(({ ctx, input }) => handlers.write({ ...input, ctx })),
+    });
+}
+//# sourceMappingURL=records.js.map

package/dist/fn-context/rpc/trpc-client.d.ts

@@ -1,4 +1,41 @@
-import type { ApiHost } from '../types.js';
+import type { ApiHost, CaseOrchestratorApiHost } from '../types.js';
+/**
+ * A request that got no answer from the platform itself (74 §3.2): the platform always answers JSON, so any
+ * other answer is a gateway's. `reached: false` only when the request certainly never got to the platform.
+ */
+export declare class RpcTransportError extends Error {
+    readonly reached: boolean | 'unknown';
+    readonly name = "RpcTransportError";
+    constructor(message: string, reached: boolean | 'unknown');
+}
+/**
+ * `fetch` for the platform's RPC: a failure to connect, or an answer that is not the platform's (not JSON),
+ * becomes an {@link RpcTransportError} saying whether the request reached it. The answer is read whole here:
+ * one that breaks as it is read (a body cut off, bad JSON) is an {@link RpcTransportError} too, so whatever
+ * fails before this is called (the code's arguments that cannot be sent as JSON) stays the code's.
+ */
+export declare function platformFetch(input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]): Promise<Response>;
+/** Sent again: the platform was busy (`TOO_MANY_REQUESTS`), or the request never reached it. */
+export declare function shouldRetryRpc(error: {
+    data?: {
+        code?: string;
+    } | null;
+    cause?: unknown;
+}, attempts: number): boolean;
+/**
+ * A failed call as company code sees it: an `Error` with the platform's message and, when the platform
+ * refused it for a reason of the business (`subject_busy`, `run_ended`, a write's code), that reason as
+ * `error.code` (64 §12).
+ */
+export declare function rpcSafe<T>(promise: Promise<T>): Promise<T>;
+/**
+ * A read's arguments as sent, `after` cut down to the place the platform reads off it (18 §4.6): the
+ * row's `id`, `createdAt` and `updatedAt`, and of each field this read's `orderBy` names, the slot's
+ * `value`. `after: rows.at(-1)` is a row with whatever it `include`d; sent whole, a big include tree
+ * could pass the request's size limit for nothing. Anything that is no row goes as given, for the
+ * platform to refuse with its reason.
+ */
+export declare function placeOnly(args: unknown): unknown;
 export declare function createRpcApiHost(options: {
     baseUrl: string;
     getToken: () => string | Promise<string>;
@@ -7,5 +44,10 @@ export declare function createRpcApiHost(options: {
     getRequestId?: () => string | undefined;
     getTags?: () => string[] | undefined;
     waitUntil?: (promise: Promise<unknown>) => void;
-}): ApiHost;
+    /**
+     * Asked before each call is sent, with its procedure's path (`platform.invoke`, `log.emit`, …): throws
+     * to refuse it. The Worker refuses a `ctx` kept from another call (64 §6).
+     */
+    checkCall?: (path: string) => void;
+}): ApiHost & CaseOrchestratorApiHost;
 //# sourceMappingURL=trpc-client.d.ts.map

package/dist/fn-context/rpc/trpc-client.js

@@ -1,9 +1,95 @@
-import { createTRPCClient, httpLink } from '@trpc/client';
+import { createTRPCClient, httpLink, retryLink } from '@trpc/client';
 import { platformSurfaces } from '../../core/context/platform-registry.js';
-import { defaultHttpApi } from '../../core/context/http.js';
 import { integrationSurfaceKeys, } from '../../core/context/types.js';
 import { bindEnvService } from '../../core/context/env.js';
-import { REQUEST_ID_HEADER, RUNTIME_VERSION_HEADER, formatRuntimeVersion, } from './request-id.js';
+import { CASE_ORCHESTRATOR_TOOL_NAMES, } from '../../core/case-orchestrator/types.js';
+import { getLogger } from '../../logger.js';
+import { PlatformUnavailableError } from '../../core/functions/errors.js';
+import { REQUEST_ID_HEADER, RUNTIME_VERSION_HEADER, formatRuntimeVersion } from './request-id.js';
+const logger = getLogger(['runtime', 'rpc']);
+/**
+ * A call the platform turned away before doing anything (its company over the rate, or no free slot:
+ * `TOO_MANY_REQUESTS`) is sent again after a growing pause, long enough together to outlast a rate window.
+ */
+const BUSY_RETRIES = 5;
+const busyDelayMs = (attempt) => Math.min(500 * 2 ** attempt, 5_000) + Math.floor(Math.random() * 250);
+/**
+ * A call that certainly never reached the platform (a gateway's error page, a refused connection, a name that
+ * did not resolve) is sent again this many times, after the same growing pause (74 §3.2). One that may have
+ * reached it (504, a connection cut after it was sent) is not, read or write alike.
+ */
+const UNREACHED_RETRIES = 3;
+/**
+ * A request that got no answer from the platform itself (74 §3.2): the platform always answers JSON, so any
+ * other answer is a gateway's. `reached: false` only when the request certainly never got to the platform.
+ */
+export class RpcTransportError extends Error {
+    reached;
+    name = 'RpcTransportError';
+    constructor(message, reached) {
+        super(message);
+        this.reached = reached;
+    }
+}
+/** A gateway's own answer that may come after the platform got the request: its timeouts (504; Cloudflare 520, 524). */
+const MAYBE_REACHED_STATUSES = new Set([504, 520, 524]);
+/** Fetch failures where no connection was ever made. */
+const NOT_CONNECTED = /ECONNREFUSED|ENOTFOUND|EAI_AGAIN|getaddrinfo/;
+function connectFailure(error) {
+    for (let current = error, depth = 0; current && depth < 5; depth += 1) {
+        const { code, message, errors } = current;
+        if (NOT_CONNECTED.test(`${String(code ?? '')} ${String(message ?? '')}`))
+            return true;
+        if (Array.isArray(errors) && errors.some(connectFailure))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/**
+ * `fetch` for the platform's RPC: a failure to connect, or an answer that is not the platform's (not JSON),
+ * becomes an {@link RpcTransportError} saying whether the request reached it. The answer is read whole here:
+ * one that breaks as it is read (a body cut off, bad JSON) is an {@link RpcTransportError} too, so whatever
+ * fails before this is called (the code's arguments that cannot be sent as JSON) stays the code's.
+ */
+export async function platformFetch(input, init) {
+    let response;
+    try {
+        response = await fetch(input, init);
+    }
+    catch (error) {
+        const reached = connectFailure(error) ? false : 'unknown';
+        throw new RpcTransportError(`the platform could not be reached: ${error instanceof Error ? error.message : String(error)}`, reached);
+    }
+    if (!/json/i.test(response.headers.get('content-type') ?? '')) {
+        const body = (await response.text().catch(() => '')).slice(0, 120).replace(/\s+/g, ' ');
+        throw new RpcTransportError(`HTTP ${response.status} from a gateway, not the platform: ${body}`, MAYBE_REACHED_STATUSES.has(response.status) ? 'unknown' : false);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        throw new RpcTransportError(`the platform's answer was cut off: ${error instanceof Error ? error.message : String(error)}`, 'unknown');
+    }
+    try {
+        JSON.parse(text);
+    }
+    catch {
+        throw new RpcTransportError(`the platform's answer is not valid JSON: ${text.slice(0, 120)}`, 'unknown');
+    }
+    return new Response(text, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+function transportErrorOf(error) {
+    const cause = error?.cause;
+    return cause instanceof RpcTransportError ? cause : null;
+}
+/** Sent again: the platform was busy (`TOO_MANY_REQUESTS`), or the request never reached it. */
+export function shouldRetryRpc(error, attempts) {
+    if (error.data?.code === 'TOO_MANY_REQUESTS')
+        return attempts <= BUSY_RETRIES;
+    return transportErrorOf(error)?.reached === false && attempts <= UNREACHED_RETRIES;
+}
 function rpcLogger(c, getTags, waitUntil) {
     const emit = (level, message, extra) => {
         const pending = c.log.emit.mutate({ level, message, extra, tags: getTags?.() }).catch(() => { });
@@ -20,10 +106,25 @@ function rpcLogger(c, getTags, waitUntil) {
         error: (message, extra) => emit('error', message, extra),
     };
 }
-function rpcSafe(promise) {
+/**
+ * A failed call as company code sees it: an `Error` with the platform's message and, when the platform
+ * refused it for a reason of the business (`subject_busy`, `run_ended`, a write's code), that reason as
+ * `error.code` (64 §12).
+ */
+export function rpcSafe(promise) {
     return promise.catch((err) => {
         if (err instanceof Error && err.constructor?.name === 'TRPCClientError') {
-            throw new Error(`RPC call failed: ${err.message}`);
+            // No answer from the platform, one that broke as it was read (`platformFetch` says so), or its own
+            // failure (5xx): the platform's (74 §3.2), marked so. What failed before the request was sent (the
+            // code's arguments that are no JSON, a ctx kept from another call) stays the code's.
+            const status = err.data?.httpStatus;
+            const platform = transportErrorOf(err) !== null || (typeof status === 'number' && status >= 500);
+            const message = `RPC call failed: ${transportErrorOf(err)?.message ?? err.message}`;
+            const failed = (platform ? new PlatformUnavailableError(message) : new Error(message));
+            const reason = err.data?.reason;
+            if (typeof reason === 'string')
+                failed.code = reason;
+            throw failed;
         }
         throw err;
     });
@@ -48,6 +149,13 @@ function stubSurface(c, meta) {
     if (meta.surfaceKey === 'envs') {
         return bindEnvService(stub);
     }
+    if (meta.surfaceKey === 'emails') {
+        return {
+            ...stub,
+            address: typeof meta.config.address === 'string' ? meta.config.address : meta.name,
+            provider: meta.config.provider === 'hotmail' ? 'hotmail' : 'gmail',
+        };
+    }
     return stub;
 }
 function buildSurfaces(c, metas) {
@@ -74,6 +182,81 @@ function buildPlatformApis(c) {
     // The registry is what guarantees the shape; TS cannot follow it through Object.fromEntries.
     return Object.fromEntries(surfaces);
 }
+/** Every Case Orchestrator tool routes through one procedure; the platform validates and executes it. */
+function buildCaseOrchestratorTools(c) {
+    const tools = CASE_ORCHESTRATOR_TOOL_NAMES.map((tool) => [
+        tool,
+        (input) => rpcSafe(c.caseOrchestratorTools.invoke.mutate({ tool, input })),
+    ]);
+    // The tool registry guarantees the shape; TS cannot follow it through Object.fromEntries.
+    return Object.fromEntries(tools);
+}
+/** A records answer: its value, or the error it was refused with (a write's with its code). */
+function unwrapRecords(result) {
+    if (result.ok)
+        return result.value;
+    const error = new Error(result.error.message);
+    error.code = result.error.code;
+    throw error;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The keys of a row the platform always reads off `after`: its id and times. */
+const PLACE_KEYS = new Set(['id', 'createdAt', 'updatedAt']);
+/**
+ * A read's arguments as sent, `after` cut down to the place the platform reads off it (18 §4.6): the
+ * row's `id`, `createdAt` and `updatedAt`, and of each field this read's `orderBy` names, the slot's
+ * `value`. `after: rows.at(-1)` is a row with whatever it `include`d; sent whole, a big include tree
+ * could pass the request's size limit for nothing. Anything that is no row goes as given, for the
+ * platform to refuse with its reason.
+ */
+export function placeOnly(args) {
+    if (!isPlainObject(args) || !isPlainObject(args.after))
+        return args;
+    const ordered = new Set();
+    for (const entry of Array.isArray(args.orderBy) ? args.orderBy : [args.orderBy]) {
+        if (isPlainObject(entry))
+            for (const field of Object.keys(entry))
+                ordered.add(field);
+    }
+    const place = Object.entries(args.after).flatMap(([key, value]) => {
+        if (PLACE_KEYS.has(key))
+            return [[key, value]];
+        if (!ordered.has(key))
+            return [];
+        // A slot: only its value places the row (a lookup's included `row` does not).
+        return [[key, isPlainObject(value) ? (Object.hasOwn(value, 'value') ? { value: value.value } : {}) : value]];
+    });
+    return { ...args, after: Object.fromEntries(place) };
+}
+/**
+ * `ctx.api.db` of every function and the Orchestrator (15 §10.15 task 4, §10.16): every table, as a
+ * page script and its actions see them, one request per call; a write is done each time (38 §2.7). A
+ * read's `after` goes as its place only ({@link placeOnly}).
+ */
+function buildDbApi(c) {
+    const db = new Proxy({}, {
+        get(_, table) {
+            if (typeof table !== 'string')
+                return undefined;
+            const read = (method) => async (args) => unwrapRecords(await rpcSafe(c.records.read.mutate({ table, method, args: placeOnly(args ?? {}) })));
+            const write = (method) => async (args) => unwrapRecords(await rpcSafe(c.records.write.mutate({ table, method, args: args ?? {} })));
+            return {
+                $table: table,
+                findUnique: read('findUnique'),
+                findFirst: read('findFirst'),
+                findMany: read('findMany'),
+                count: read('count'),
+                create: write('create'),
+                update: write('update'),
+                upsert: write('upsert'),
+                delete: write('delete'),
+            };
+        },
+    });
+    return { db };
+}
 export function createRpcApiHost(options) {
     let client;
     let lastBaseUrl;
@@ -81,9 +264,15 @@ export function createRpcApiHost(options) {
         if (!client || lastBaseUrl !== baseUrl) {
             client = createTRPCClient({
                 links: [
+                    retryLink({
+                        retry: ({ error, attempts }) => shouldRetryRpc(error, attempts),
+                        retryDelayMs: busyDelayMs,
+                    }),
                     httpLink({
                         url: baseUrl,
-                        headers: async () => {
+                        fetch: platformFetch,
+                        headers: async ({ op }) => {
+                            options.checkCall?.(op.path);
                             const headers = {
                                 authorization: `Bearer ${await options.getToken()}`,
                                 [RUNTIME_VERSION_HEADER]: formatRuntimeVersion(options.runtimeVersion, options.runtimeSource),
@@ -100,18 +289,39 @@ export function createRpcApiHost(options) {
         }
         return client;
     }
+    /** The integrations the call brought; without them, the backend lists them. */
+    async function surfacesOf(c, given) {
+        if (given.surfaces)
+            return given.surfaces;
+        const started = Date.now();
+        logger.info('integration.listSurfaces start', { url: options.baseUrl });
+        const metas = await rpcSafe(c.integration.listSurfaces.query());
+        logger.info('integration.listSurfaces ok', { durationMs: Date.now() - started, count: metas.length });
+        return metas;
+    }
     return {
-        async buildApi(_run) {
+        async buildApi(_run, given = {}) {
+            const c = getClient(options.baseUrl);
+            const metas = await surfacesOf(c, given);
+            return {
+                ...buildPlatformApis(c),
+                integration: buildSurfaces(c, metas),
+                log: rpcLogger(c, options.getTags, options.waitUntil),
+                // Every function's (38 §2.7): each call names its instance.
+                tools: buildCaseOrchestratorTools(c),
+                ...buildDbApi(c),
+            };
+        },
+        async buildCaseOrchestratorApi(_run, given = {}) {
             const c = getClient(options.baseUrl);
-            const started = Date.now();
-            console.log(`[rpc timing] integration.listBindings start url=${options.baseUrl}`);
-            const metas = await rpcSafe(c.integration.listBindings.query());
-            console.log(`[rpc timing] integration.listBindings ok ${Date.now() - started}ms count=${metas.length}`);
+            // A function's api (25 §7), so a function called from the Orchestrator with its ctx works the same.
+            const metas = await surfacesOf(c, given);
             return {
                 ...buildPlatformApis(c),
                 integration: buildSurfaces(c, metas),
                 log: rpcLogger(c, options.getTags, options.waitUntil),
-                http: defaultHttpApi(),
+                tools: buildCaseOrchestratorTools(c),
+                ...buildDbApi(c),
             };
         },
     };

package/dist/fn-context/rpc/trpc-init.d.ts

@@ -1,13 +1,31 @@
-import type { RunScope } from '../types.js';
+import type { RunClaims } from '../types.js';
 export type RpcContext = {
-    run: RunScope;
+    run: RunClaims;
     requestId?: string;
     runtimeVersion?: string;
+    /**
+     * The platform's gate around every procedure (64 §5): the rate, and whether an Orchestrator's task still
+     * runs. Set by the platform's context; every procedure built on {@link publicProcedure} passes through it,
+     * so a new one cannot miss it. Absent (a test calling one router directly), the procedure just runs.
+     */
+    around?: <T>(call: {
+        path: string;
+    }, next: () => Promise<T>) => Promise<T>;
 };
 export declare const router: import("@trpc/server").TRPCRouterBuilder<{
     ctx: RpcContext;
     meta: object;
-    errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+    errorShape: import("@trpc/server").TRPCDefaultErrorShape | {
+        message: string;
+        code: import("@trpc/server").TRPC_ERROR_CODE_NUMBER;
+        data: {
+            code: import("@trpc/server").TRPC_ERROR_CODE_KEY;
+            httpStatus: number;
+            path?: string;
+            stack?: string;
+            reason: string;
+        };
+    };
     transformer: false;
 }>;
 /**

package/dist/fn-context/rpc/trpc-init.js

@@ -1,13 +1,19 @@
 import { initTRPC, TRPCError } from '@trpc/server';
-import { isRpcCodedError } from './errors.js';
-const t = initTRPC.context().create();
+import { isRpcCodedError, rpcErrorReason } from './errors.js';
+const t = initTRPC.context().create({
+    // A refusal's business code (`subject_busy`, `run_ended`, …) goes back beside its message (64 §12).
+    errorFormatter({ shape, error }) {
+        const reason = rpcErrorReason(error.cause);
+        return reason ? { ...shape, data: { ...shape.data, reason } } : shape;
+    },
+});
 export const router = t.router;
 /**
  * Applied to every procedure so domain errors reach the caller with the status they declared,
  * without each dispatcher wrapping its own body in try/catch.
  */
-export const publicProcedure = t.procedure.use(async ({ next }) => {
-    const result = await next();
+export const publicProcedure = t.procedure.use(async ({ ctx, path, next }) => {
+    const result = ctx.around ? await ctx.around({ path }, () => next()) : await next();
     if (!result.ok && isRpcCodedError(result.error.cause)) {
         const cause = result.error.cause;
         throw new TRPCError({ code: cause.rpcCode, message: cause.message, cause });