@voltro/protocol 0.85.0 → 0.87.0

package/dist/rest.d.ts

@@ -1,5 +1,6 @@
 import * as AST from 'effect/SchemaAST';
 import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
 import { Schema } from 'effect';
 
 declare interface ActionProcedureDescriptor<Name extends string, Input extends Schema.Top, Output extends Schema.Top, Error extends Schema.Top> {
@@ -76,7 +77,12 @@ declare interface AnyApprovalPolicy {
 }
 
 /** A guard is a scope check, a relationship check, or an identity check. */
-declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input> | AuthenticatedGuardSpec;
+declare type AnyGuardSpec<Input = unknown> = GuardSpec<Input> | PolicyGuardSpec<Input> | AuthenticatedGuardSpec | UpgradedGuardSpec;
+
+/** Work performed by an API process; schema and descriptor loading is separate. */
+declare const API_WORKLOADS: readonly ["rpc", "subscriptions", "events", "presence", "workflows", "schedules", "directors", "drainers", "reapers", "retention", "rest", "webhooks", "inspect", "cdc"];
+
+declare type ApiWorkload = typeof API_WORKLOADS[number];
 
 /**
  * "The caller must have an identity" — and nothing narrower.
@@ -208,6 +214,13 @@ export declare const encodeRestError: (format: RestFormat, error: RestFormatErro
  */
 export declare const encodeRestSuccess: (format: RestFormat, value: unknown, ctx: RestFormatContext) => RestFormatResponse;
 
+declare interface EnqueueOptions {
+    /** Deduplicate while an earlier intent is still pending, not permanently. */
+    readonly idempotencyKey?: string;
+    readonly maxAttempts?: number;
+    readonly delayMs?: number;
+}
+
 /** The member of an error union that declares `tag`, as a schema of its own —
  *  for the spec's per-status responses. */
 export declare const errorMemberSchema: (error: Schema.Top | undefined, tag: string) => Schema.Top | undefined;
@@ -238,40 +251,43 @@ declare interface GuardSpec<Input = unknown> {
     /** How an array of scopes combines. `'all'` (default) = AND (hold every
      *  scope); `'any'` = OR (hold at least one). Ignored for a single scope. */
     readonly mode?: 'all' | 'any';
-    /**
-     * PURE `input → resource id` extractor. Browser-safe (no DB, no server
-     * import) — exactly like `target.identify`. Omit for a plain subject-scope
-     * guard.
-     *
-     * **On a `GuardSpec` this id is ADVISORY.** A scope guard answers "what may
-     * this subject do at all", against the subject's global scope set; the id is
-     * carried for logging and for a future subject-scope resolver that narrows by
-     * resource. It does not, on its own, make the check per-resource.
-     *
-     * **If your authority is per-resource, you want {@link PolicyGuardSpec}, not
-     * this field** — `guards: [{ action, resourceType, resource }]`, backed by
-     * `defineResourcePolicy` + a tuple source you register. That is built, wired
-     * on both boot paths, fail-closed without a resolver, and documented under
-     * *Authentication → Authorization*. An app whose relationships already live
-     * in its own tables (a `teamMembers` row, say) registers its own tuple source
-     * rather than copying data across; see `policyGuardResolver.ts`.
-     *
-     * That paragraph is here because its absence cost a deployment their access
-     * gate. This comment used to describe the resolver as "a future ReBAC /
-     * `accessPolicy()` resolver" — written before the ReBAC path shipped and
-     * never updated. They read the type, quoted the sentence, concluded there was
-     * "nothing in between" declaring an untruth and turning the gate off, and set
-     * `security: { defaultDeny: false }` on an app with 565 undecided procedures.
-     * The capability they needed was two fields away. A doc comment that says
-     * "future" about something shipped is not a small inaccuracy: it is the only
-     * thing a careful reader has, and it argued them out of a feature.
-     */
+    /** Pure browser-safe input → target resource id selector. With a registered
+     * setResourceScopeResolver, scopes can be checked on this resource. Without
+     * resourceOnly, an existing global scope or admin:full may satisfy the guard
+     * without consulting that resolver. For per-resource authority over relationships use
+     * PolicyGuardSpec: `defineResourcePolicy` plus a registered tuple source. That is built, wired
+     * on both boot paths and fail-closed without a resolver — an earlier comment called it "future"
+     * and argued a deployment out of its access gate. */
     readonly resource?: (input: Input) => string | undefined;
+    /** Require an explicit current resource verdict, including for globally held
+     * scopes or admin:full. Missing resolver/resource refuses access. */
+    readonly resourceOnly?: boolean;
 }
 
+/** Identity of one acquired execution, never reused when a key is reclaimed.
+ * This is receipt ownership, not authority to perform a business side effect. */
+declare interface IdempotencyClaim {
+    readonly scope: string;
+    readonly key: string;
+    readonly id: string;
+    readonly inputHash: string;
+}
+
+declare type IdempotencyClaimResult = {
+    readonly kind: 'claimed';
+    readonly claim: IdempotencyClaim;
+} | {
+    readonly kind: 'existing';
+    readonly record: IdempotencyRecord;
+} | {
+    readonly kind: 'conflict';
+};
+
 declare interface IdempotencyRecord {
     readonly scope: string;
     readonly key: string;
+    /** Null means a retained receipt predates declared-input binding. */
+    readonly inputHash: string | null;
     readonly status: 'in_flight' | 'completed';
     readonly response: IdempotencyResponse | null;
     /** epoch ms */
@@ -281,34 +297,24 @@ declare interface IdempotencyRecord {
 declare interface IdempotencyResponse {
     readonly status: number;
     readonly body: unknown;
+    /** Framework-owned REST qualification metadata. Custom stores preserve it
+     * unchanged, separately from the arbitrary application output in body. */
+    readonly rest?: unknown;
 }
 
 declare interface IdempotencyStore {
-    /** Current record for (scope, key), or null. Read-side (inspect/dashboard). */
     readonly get: (scope: string, key: string) => Promise<IdempotencyRecord | null>;
-    /**
-     * Atomically claim (scope, key) IF absent OR stale — a COMPLETED record older
-     * than `ttlMs` (the replay window), or an IN-FLIGHT one whose lease
-     * (`inFlightLeaseMs`, renewed by the live handler) lapsed:
-     * write a fresh `in_flight` row and return `'claimed'`. Otherwise return the
-     * EXISTING (still-fresh) record. The atomicity here is the whole game — two
-     * concurrent same-key requests both hit this, exactly one gets `'claimed'`,
-     * the loser reads the winner's record. In SQL this is one
-     * `INSERT … ON CONFLICT DO UPDATE … WHERE existing.createdAt < now - ttl`.
-     */
-    readonly claim: (scope: string, key: string, now: number, ttlMs: number, inFlightLeaseMs: number) => Promise<'claimed' | IdempotencyRecord>;
-    /**
-     * Extend a RUNNING claim's lease: bump its timestamp while it is still
-     * `in_flight` (a completed or released claim is left alone). The server calls
-     * it while the handler runs; a process that dies stops calling it, and its
-     * claim goes stale after `inFlightLeaseMs` instead of after the whole replay
-     * window.
-     */
-    readonly renew: (scope: string, key: string, now: number) => Promise<void>;
-    /** Flip the claim to `completed` and store the response. */
-    readonly complete: (scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
-    /** Drop the claim (handler errored → a retry may re-process). */
-    readonly release: (scope: string, key: string) => Promise<void>;
+    /** Atomically acquire an absent/stale key with a new, never-reused identity.
+     * Otherwise return the existing receipt, or conflict if contention prevents
+     * observing a stable record. Expiry does not prove an old executor stopped. */
+    readonly claim: (scope: string, key: string, inputHash: string, now: number, ttlMs: number, inFlightLeaseMs: number) => Promise<IdempotencyClaimResult>;
+    /** Atomically match original scope/key/id AND in_flight status. False means
+     * this execution no longer owns a running receipt; never touch its successor. */
+    readonly renew: (claim: IdempotencyClaim, now: number) => Promise<boolean>;
+    /** Complete only the original running claim and start its replay window now. */
+    readonly complete: (claim: IdempotencyClaim, response: IdempotencyResponse, now: number) => Promise<boolean>;
+    /** Release only the original running claim. Completed receipts are retained. */
+    readonly release: (claim: IdempotencyClaim) => Promise<boolean>;
 }
 
 declare interface InsertTarget<Input = unknown, Row = unknown, Item = Record<string, unknown>> extends NestedTargetFields<Input> {
@@ -371,6 +377,12 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
     readonly idempotencyScope?: MutationIdempotencyScope | undefined;
     /** Same-key calls run in invocation order on the client — see `defineMutation`. */
     readonly serialize?: MutationSerialization<Schema.Schema.Type<Input>> | undefined;
+    /** Exclude this invocation from automatic row-image undo capture, with an
+     * explicit domain reason. Does not disable transactions, guards or audit. */
+    readonly undo?: {
+        readonly capture: false;
+        readonly reason: string;
+    } | undefined;
     /** Declarative target(s) — drives auto-optimistic on the client AND
      *  surfaces which tables this mutation touches (debug, future
      *  query-invalidation analytics). Mutations without a target run
@@ -478,6 +490,12 @@ declare interface OpenAccessSpec {
 /** The rpc tag as an `operationId`: `teams.list` → `teamsList`. */
 export declare const operationIdOf: (tag: string) => string;
 
+/** Enqueue-only capability bound to the caller's actual transaction store. */
+declare interface OutboxEnqueueFacade {
+    /** Returns the stable delivery identity. Delivery happens after commit. */
+    enqueue(effect: string, payload: Record<string, unknown>, options?: EnqueueOptions): Promise<string>;
+}
+
 /** The parameter names a route pattern binds, in order. */
 export declare const pathParamNames: (path: string) => ReadonlyArray<string>;
 
@@ -521,6 +539,12 @@ declare interface PluginErrorSchema {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
+    /** Executable API workload owning this route. Omitted means `rpc`.
+     * Discovery and descriptor generation remain independent of role selection. */
+    readonly workload?: ApiWorkload;
+    /** The already-mounted REST projection, retained for SDK/schema inspection.
+     * Do not remount it through generic REST auth or idempotency bindings. */
+    readonly restContract?: RestRouteDescriptor<any, any>;
     /** HTTP method, or `'*'` for any (the handler decides). The server mounts the
      *  path for exactly the methods its routes declare; `'*'` mounts it for every
      *  method the router knows (34), so keep that for a route that really serves
@@ -549,6 +573,13 @@ declare interface PluginHttpRoute {
      */
     readonly match?: 'prefix' | 'exact';
     readonly handle: (req: PluginHttpRouteRequest) => Promise<PluginHttpRouteResult>;
+    /** Lazy, backpressured input instead of a buffered rawBody on real HTTP.
+     * Requires match: 'exact' and exclusive ownership of the router-equivalent
+     * path (including other methods). The required handle remains the buffered
+     * in-process entry. Both entries must apply the same authorization/codec.
+     * maxBodyBytes counts consumed bytes; overflow overrides the handler's
+     * response with 413 even when the handler catches the read error. */
+    readonly handleStream?: (req: PluginHttpRouteStreamRequest) => Promise<PluginHttpRouteResult>;
     /** Per-route body cap override (bytes) — wins over the listener's shared
      *  `maxBodyBytes`. NOTE: routes SHARING a path share one body read, so the
      *  widest override on the path's group applies to the whole group. */
@@ -589,6 +620,9 @@ declare interface PluginHttpRoute {
      * handler branches on: exempting `/saml` exempts `POST /saml/anything`.
      */
     readonly originGuard?: 'exempt';
+    readonly cors?: RestCors;
+    /** Bearer-only routes must discard cookie authority before authentication. */
+    readonly credentials?: 'bearer';
 }
 
 /**
@@ -748,11 +782,23 @@ declare interface PluginHttpRouteResult {
  */
 declare interface PluginHttpRouteStream {
     readonly subscribe: (emit: (chunk: string) => void) => () => void;
+    /** Per-connection lifetime in milliseconds (1..2147483647). Ending the
+     * response releases the subscription and keep-alive timer. Absent: no cap. */
+    readonly maxDurationMs?: number;
     /** Keep-alive comment interval in ms (default 15000; `0` disables). Without
      *  it an idle SSE connection is dropped by proxies after ~30–60s. */
     readonly keepAliveMs?: number;
 }
 
+/** A lazy binary request on the framework listener. No body bytes are read
+ * before the handler runs. Consume once, through EOF, before accepting an
+ * upload; returning early drains the unread body without validating it.
+ * The signal ends on disconnect, interruption or handler completion. */
+declare interface PluginHttpRouteStreamRequest extends Omit<PluginHttpRouteRequest, 'rawBody'> {
+    readonly body: AsyncIterable<Uint8Array>;
+    readonly signal: AbortSignal;
+}
+
 /**
  * A relationship (ReBAC) guard — "may this subject perform ACTION on THIS row?"
  *
@@ -945,6 +991,10 @@ declare interface PublicApiSpec {
     /** Streaming queries over request/response: 'snapshot' (default — first
      *  snapshot, like POST /rpc) | 'sse' (Server-Sent Events of snapshot+deltas). */
     readonly stream?: 'snapshot' | 'sse';
+    /** Per-connection SSE lifetime in milliseconds (1..2147483647). Requires
+     * an SSE query projection. Clients may reconnect for a freshly authorized
+     * snapshot; expiry does not cancel a domain operation. */
+    readonly streamMaxDurationMs?: number;
     /**
      * HTTP status per DECLARED typed error tag, for the projection. A typed
      * error the handler fails with — one of the descriptor's `error:` union —
@@ -956,6 +1006,11 @@ declare interface PublicApiSpec {
      *     publicApi: { errorStatus: { AccessDeniedError: 403, NotFoundError: 404 } }
      */
     readonly errorStatus?: Readonly<Record<string, number>>;
+    /** Additional HTTP failure statuses for the same declared error schema.
+     * Documents dedicated handlers that choose a status from the error's fields;
+     * does not change `errorStatus` or the generic projection's runtime mapping.
+     * Values must be integer HTTP error statuses (400–599); duplicates are omitted. */
+    readonly additionalErrorStatuses?: Readonly<Record<string, ReadonlyArray<number>>>;
     /**
      * The spec's tag group(s) for this operation. Default: the rpc tag's prefix
      * (`teams.list` → `teams`) — the first path segment, what a consumer looks
@@ -1059,6 +1114,16 @@ declare interface QueryCacheConfig {
      * cardinality of a cache the author sized per org.
      */
     readonly scope: 'subject' | 'tenant' | 'global';
+    /**
+     * The handler's result also depends on something no table write
+     * invalidates — the clock, randomness, `ctx.connections`, an outgoing HTTP
+     * call, `ctx.kv`. Applies to a COMPUTED query (a handler that returns a
+     * value): without it such a result is computed but NOT kept, and the dev log
+     * names what was used. With it, `ttl` is the bound on how stale that part may
+     * be. `Date.now()`, `Math.random()` and a `fetch` outside the framework's
+     * HTTP client are not observable — a handler that uses them must say so here.
+     */
+    readonly volatile?: boolean | undefined;
 }
 
 declare interface QueryProcedureDescriptor<Name extends string, Input extends Schema.Top, Output extends Schema.Top, Error extends Schema.Top> {
@@ -1073,6 +1138,9 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
      *  listed table changes (pass an array to depend on several). Optional:
      *  queries without a source never receive auto-patches (joins, aggregates). */
     readonly source: string | ReadonlyArray<string> | undefined;
+    /** Optional integration observers, all also present in source. They keep
+     *  invalidation active when installed; absence is a visible graph warning. */
+    readonly optionalSource?: ReadonlyArray<string>;
     /** Server-side snapshot cache config. Absent → never cached (the
      *  default; the dispatcher already keeps live subscriptions fresh). */
     readonly cache: QueryCacheConfig | undefined;
@@ -1134,13 +1202,9 @@ export declare const requireAnyScope: (scopes: ReadonlyArray<string>) => RestGua
  *  guards remain authorization failures (403). */
 export declare const requireAuthenticated: () => RestGuard;
 
-/**
- * Guard that requires the resolved subject to carry `scope`. Anonymous /
- * scope-less subjects are rejected with `403`. The blanket admin scope
- * (`ADMIN_SCOPE` = `'admin:full'`) satisfies any required scope — the SAME
- * bypass the rpc-handler `requireScope`/`hasScope` (`./scopes`) honours, so
- * a subject granted admin is admin on both surfaces.
- */
+/** Require an effective scope, including derived roles. Callers without it
+ * receive 403; add requireAuthenticated when authenticated identity is required.
+ * The admin:full bypass is the same one used by native scope guards. */
 export declare const requireScope: (scope: string) => RestGuard;
 
 /**
@@ -1225,6 +1289,22 @@ export declare interface RestCache {
     readonly audience?: (output: unknown, input: unknown, subject: Subject) => 'public' | 'private';
 }
 
+/** Cross-origin browser access for one route. Origins are exact, including opaque `null`. */
+export declare interface RestCors {
+    readonly origins: ReadonlyArray<string>;
+    readonly headers?: ReadonlyArray<string>;
+    readonly methods?: ReadonlyArray<RestMethod>;
+    /** Preflight cache lifetime in seconds. */
+    readonly maxAge?: number;
+    readonly exposeHeaders?: ReadonlyArray<string>;
+}
+
+/** Shared by the descriptor adapter and listener, including early transport refusals. */
+export declare const restCorsHeaders: (cors: RestCors | undefined, origin: string | undefined) => Record<string, string>;
+
+/** Preflight never authenticates, consumes quota, reads a body or executes a handler. */
+export declare const restCorsPreflight: (cors: RestCors, method: string, headers: Readonly<Record<string, string>>) => PluginHttpRouteResult;
+
 export declare type RestDates = 'iso' | 'epoch-ms';
 
 export declare type RestEnvelope = 'none' | 'data' | 'jsonapi';
@@ -1304,7 +1384,7 @@ export declare interface RestFormatResponse {
     readonly contentType?: string;
 }
 
-export declare type RestGuard = (ctx: RestRouteContext) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
+export declare type RestGuard = (ctx: RestRouteContext, request?: RestGuardRequest) => RestGuardRejection | undefined | Promise<RestGuardRejection | undefined>;
 
 /**
  * A guard runs after input decode + ctx resolution, before the handler.
@@ -1316,6 +1396,13 @@ export declare interface RestGuardRejection {
     readonly message: string;
 }
 
+/** Guard input is the decoded execution snapshot. Guards are read-only
+ * admission checks and may run again after awaited admission/storage work. */
+export declare interface RestGuardRequest {
+    readonly input: unknown;
+    readonly defaultDeny: boolean;
+}
+
 /** What a REST handler may return: the decoded output, a `response(...)` with
  *  its own status and headers, an `sse(...)` stream, or `bytes(...)` for a
  *  non-JSON body (a file, an export, an XML document). */
@@ -1327,6 +1414,13 @@ export declare type RestNaming = 'camelCase' | 'snake_case';
 
 export declare type RestPagination = 'link-header' | 'body-cursor';
 
+/** Uses the mounted rate-limit plugin's store, algorithms and dynamic policy. */
+export declare interface RestRateLimit {
+    readonly limit: number;
+    readonly window: string;
+    readonly by?: 'subject' | 'tenant' | 'apiKey' | 'ip' | 'global';
+}
+
 /** A schema-encoded REST body with an application-selected HTTP status and
  *  response headers. The marker keeps ordinary domain objects unambiguous.
  *  `output` still validates/encodes `body`; use `Schema.Void` with a 204 when
@@ -1348,6 +1442,8 @@ export declare interface RestResponse<O> {
  * stays free of the database dep).
  */
 export declare interface RestRouteContext {
+    /** Server-owned invocation trace, stable through readmission and projection. */
+    readonly traceId: string;
     readonly subject: Subject;
     readonly headers: Readonly<Record<string, string>>;
     /** Request metadata and the byte-exact body as received by the HTTP
@@ -1372,6 +1468,9 @@ export declare interface RestRouteContext {
 }
 
 export declare interface RestRouteDescriptor<I, O> {
+    /** Original schemas for client generation. Metadata only: never mounts a
+     * second handler or selects authentication/idempotency bindings. */
+    readonly publicApiDescriptor?: PublicApiDescriptor;
     readonly method: RestMethod;
     /** Absolute path, e.g. `/v1/customers`. Matches that path exactly. */
     readonly path: string;
@@ -1385,6 +1484,12 @@ export declare interface RestRouteDescriptor<I, O> {
      *  encodes it to JSON for the `200` response. */
     readonly output: Schema.Codec<O, any, never, never>;
     readonly handler: (input: I, ctx: RestRouteContext) => Promise<RestHandlerResult<O>> | RestHandlerResult<O>;
+    /** Pure synchronous normalization of thrown admission/handler failures.
+     * Return a mapped thrown value (for example RestRouteError), not an HTTP
+     * response; undefined keeps the original failure. Available before authentication,
+     * so only request metadata is given.
+     * Public projections supply their existing typed/profile error mapper here. */
+    readonly mapFailure?: (error: unknown, request: Pick<PluginHttpRouteRequest, 'method' | 'path' | 'query'>) => unknown;
     readonly summary?: string;
     readonly description?: string;
     readonly example?: RestRouteExample;
@@ -1425,6 +1530,10 @@ export declare interface RestRouteDescriptor<I, O> {
      */
     readonly version?: `v${number}`;
     readonly guards?: ReadonlyArray<RestGuard>;
+    readonly cors?: RestCors;
+    /** Only an explicit bearer header may authenticate; cookies are removed before auth and context construction. */
+    readonly credentials?: 'bearer';
+    readonly rateLimit?: RestRateLimit;
     /**
      * This route STREAMS (Server-Sent Events) rather than resolving one value — its
      * handler returns `sse(...)`. Declared on the descriptor, not left implicit in
@@ -1510,12 +1619,23 @@ export declare const restRoutesToHttpRoutes: (routes: ReadonlyArray<RestRouteDes
  * auth subject + the bound DataStore.
  */
 export declare interface RestServeBindings {
-    /** Resolve the calling subject from the request headers. */
-    readonly resolveSubject?: (headers: Readonly<Record<string, string>>) => Subject | Promise<Subject>;
+    /** Pure scope-refresher registration, shared with native RPC admission. */
+    readonly bindReplayAuthority?: RpcReplayAuthorityBinding;
+    /** Actual host policy for projected procedure guards; raw routes own guards. */
+    readonly defaultDeny?: boolean;
+    /** Full runtime hosts supply their existing trace generator. */
+    readonly traceId?: () => string;
+    /** Bound once from the app's mounted rate-limit plugin. */
+    readonly rateLimit?: (policy: RestRateLimit, ctx: RestRouteContext, route: RestRouteDescriptor<any, any>) => Effect.Effect<void, unknown>;
+    /** Resolve the calling subject and request-local selection before guards. */
+    readonly resolveSubject?: (headers: Readonly<Record<string, string>>, request: {
+        readonly path: string;
+        readonly query: string;
+    }) => Subject | Promise<Subject>;
     /** The bound framework DataStore. */
     readonly store?: unknown;
     /** Build the full per-request app context after authentication. */
-    readonly buildContext?: (subject: Subject, headers: Readonly<Record<string, string>>) => unknown | Promise<unknown>;
+    readonly buildContext?: (subject: Subject, headers: Readonly<Record<string, string>>, request: Pick<RestRouteContext, 'traceId' | 'remoteAddr'>) => unknown | Promise<unknown>;
     /**
      * HTTP idempotency — when set, a mutating request (POST/PUT/PATCH/DELETE)
      * carrying the `header` is deduplicated: the first call runs + caches its
@@ -1570,6 +1690,72 @@ export declare const routeAcceptsPath: (route: {
     readonly match?: "prefix" | "exact" | undefined;
 }, path: string) => boolean;
 
+/**
+ * Per-call context passed to every rpc interceptor. The fields are
+ * deliberately shallow — plugins shouldn't need the full AppContext +
+ * DataStore to do their job. For runtime services (DataStore, custom
+ * Tags, etc.) declare them via `definePlugin({ services })` and read
+ * via `yield* MyTag` in the interceptor body; the framework provides
+ * them automatically.
+ */
+declare interface RpcInterceptorContext {
+    /** Enqueue a settled invocation outcome on the host's root store, outside
+     * the business transaction. Required transactional success capture must use
+     * MutationCommitContext.outbox instead. Older/custom hosts may omit this. */
+    readonly enqueueOutcome?: OutboxEnqueueFacade['enqueue'];
+    /** Procedure tag, e.g. `todos.create`. */
+    readonly tag: string;
+    /** Procedure kind, including finite stream admission. */
+    readonly kind: RpcKind;
+    /** The validated input the executor is about to (or already did) receive. */
+    readonly input: unknown;
+    /** The resolved subject (user / apiKey / serviceAccount / anonymous). */
+    readonly subject: Subject;
+    /** Per-call trace id (matches OTel spans + inspect events). */
+    readonly traceId: string;
+    /** Active OTel span id (16-hex), when tracing is on. Lets observability
+     *  plugins (Sentry/Datadog) attach an error to the exact span, not just
+     *  the trace. Absent when no tracer is installed. */
+    readonly spanId?: string;
+    /**
+     * `'rest'` when the call came through the `publicApi` projection (`/v1`);
+     * absent on the rpc wire. A per-endpoint policy on the projection — the
+     * descriptor's `publicApi.rateLimit` — applies to these calls only.
+     */
+    readonly surface?: 'rest';
+    /** The descriptor's `publicApi` spec, on a projected call. */
+    readonly publicApi?: PublicApiSpec;
+    /**
+     * The caller's address — the same value the pre-auth IP shield counts, resolved
+     * by the listener through `security.trustedProxies` (and
+     * `security.clientAddressHeader`). A client cannot set it: the listener
+     * writes it, and any copy the client sends is discarded.
+     *
+     * Absent when the call did not arrive over the network (a workflow step, a
+     * schedule, an in-process invocation) or the socket address is unknown.
+     */
+    readonly remoteAddr?: string;
+}
+
+/**
+ * Which kind of rpc the interceptor is wrapping. The runtime passes
+ * `kind: 'mutation'` to interceptors registered as `interceptMutation`,
+ * `kind: 'query'` to `interceptQuery`, `kind: 'action'` to
+ * `interceptAction`, `kind: 'workflow'` to `interceptWorkflow`, and
+ * `kind: 'stream'` to `interceptStream` — one
+ * plugin can implement any combination.
+ */
+declare type RpcKind = 'mutation' | 'query' | 'action' | 'workflow' | 'stream';
+
+declare type RpcReplayAuthorityBinding = (context: RpcReplayAuthorityContext) => undefined;
+
+/** Pure synchronous authority-refresher binding for RPC and REST admission.
+ * No business work, I/O, grants or side effects belong in this hook. The host
+ * calls the existing guard rechecker after every binding. */
+declare interface RpcReplayAuthorityContext extends Pick<RpcInterceptorContext, 'tag' | 'input' | 'subject' | 'traceId' | 'surface' | 'publicApi' | 'remoteAddr'> {
+    readonly kind: RpcKind | 'rest';
+}
+
 /**
  * The runtime-erased form of a procedure's `service: { callers }` — "only these
  * apps of the project may call this, and nobody else".
@@ -1613,6 +1799,7 @@ declare interface ServiceSpec {
  */
 export declare const sse: (subscribe: (emit: (chunk: string) => void) => () => void, options?: {
     readonly keepAliveMs?: number;
+    readonly maxDurationMs?: number;
 }) => RestStreamResponse;
 
 /** Frame ONE SSE event. Newlines in `data` are split across `data:` lines, as
@@ -1621,6 +1808,9 @@ export declare const sseFrame: (event: string, data: unknown) => string;
 
 declare const Subject: Schema.Union<readonly [Schema.Struct<{
     readonly type: Schema.Literal<"user">;
+    /** A guest has a stable identity but has not linked a registered account.
+     * This identity mark survives session signing; it never grants authority. */
+    readonly kind: Schema.optional<Schema.Literal<"guest">>;
     readonly id: Schema.String;
     readonly tenantId: Schema.String;
     readonly scopes: Schema.optional<Schema.$Array<Schema.String>>;
@@ -1749,6 +1939,12 @@ declare interface UpdateTarget<Input = unknown, Row = unknown, Item = Record<str
     readonly shapeItem?: ((input: Input, current: Item) => Item) | undefined;
 }
 
+/** Require a registered human identity. Guest and machine credentials cannot
+ * satisfy this requirement, including credentials holding admin scopes. */
+declare interface UpgradedGuardSpec {
+    readonly upgraded: true;
+}
+
 export declare const wireExample: (example: {
     readonly request?: unknown;
     readonly response?: unknown;