@voltro/protocol 0.67.0 → 0.69.0

package/dist/index.d.ts

@@ -806,6 +806,13 @@ export declare interface ClientTarget {
     readonly relations?: TargetRelations | undefined;
 }
 
+/**
+ * Compare two shape maps. Tags present only HERE are not reported: a browser
+ * client group legitimately omits server-only routes, and reporting that as a
+ * mismatch is how a check earns the reputation that gets it turned off.
+ */
+export declare const compareSurfaces: (mine: Readonly<Record<string, string>>, theirs: Readonly<Record<string, string>>) => SurfaceMismatch;
+
 export declare const composeAuthStrategies: (strategies: ReadonlyArray<AuthStrategy>, options?: {
     /** Fallback when no strategy matched. Default: returns the input's
      *  tenant from `x-tenant` header or null. */
@@ -2243,6 +2250,18 @@ export declare const getResourceScopeResolver: () => ResourceScopeResolver | und
  */
 export declare const getWorkflowAccess: (definition: unknown) => WorkflowAccess;
 
+/**
+ * Per-rpc-tag shape digests for a whole group.
+ *
+ * Per TAG rather than one digest for the group, for two reasons. A server's
+ * bound group and a browser's client group are not the same set — server-only
+ * routes exist — so a single digest would differ by construction and prove
+ * nothing. And a mismatch is far more useful when it can name the procedure.
+ */
+export declare const groupShapeDigests: (group: {
+    readonly requests?: unknown;
+}) => Readonly<Record<string, string>>;
+
 /** Ask for default-deny semantics on one `checkGuards` call. */
 export declare interface GuardCheckOptions {
     /** Refuse a procedure that declares no access decision at all. */
@@ -2822,6 +2841,46 @@ export declare interface OpenAccessSpec {
  *  `openAccess: '<why>'` on the descriptor and never sees the spec. */
 export declare const openAccessSpec: (reason: string) => OpenAccessSpec;
 
+/**
+ * Order the chain so a strategy that DECLARES a bearer prefix gets first
+ * refusal on a token carrying it.
+ *
+ * WHY THIS EXISTS. The chain is first-non-skip-wins, and a `failed` ENDS it —
+ * deliberately, because a credential another IdP rejected could be an attack
+ * masquerading as ours. Two reasonable pieces then combined into a third thing
+ * nobody chose:
+ *
+ *   1. `apiKeys:` appends the framework key strategy LAST.
+ *   2. `jwtBearerStrategy` — and therefore all six catalog strategies
+ *      (supabase, auth0, clerk, kinde, oidc, workos) — claims EVERY
+ *      `Authorization: Bearer`. A token it cannot verify is `failed`, not
+ *      `skip`.
+ *
+ * So a valid API key was rejected by the JWT verifier before the key strategy
+ * was ever asked. Nothing logged an error; the key simply never worked. A
+ * consumer measured the chain as `['skip', 'failed', 'skip']` — device,
+ * supabase, anonymous — with the key strategy never reached, and worked around
+ * it by wrapping their own verifier to skip tokens carrying the prefix
+ * `apiKeys.prefix` already declares.
+ *
+ * The existing boot check cannot see this: it warns when TWO strategies declare
+ * the SAME prefix, and the JWT strategy declares none while claiming
+ * everything. `claimsBearerPrefix`'s own doc says a JWKS strategy "claims no
+ * prefix and omits it" — that combination IS the bug.
+ *
+ * The rule, and why it is this one rather than "continue past a failure":
+ * `failed` ending the chain is a security property and stays untouched. A
+ * declared prefix is a strategy saying "this token shape is MINE", which is
+ * strictly more specific than a strategy that claims everything by declaring
+ * nothing — so specificity decides who is asked first, and a token matching no
+ * declared prefix leaves the order exactly as the app wrote it.
+ *
+ * Stable within each group, so two strategies sharing a prefix keep their
+ * declared relative order and `assertNoBearerPrefixCollision`'s warning still
+ * describes what happens.
+ */
+export declare const orderByBearerPrefix: (strategies: ReadonlyArray<AuthStrategy>, headers: Readonly<Record<string, string | undefined>>) => ReadonlyArray<AuthStrategy>;
+
 /** Split a route back into its three parts. */
 export declare const parseEventRoute: (route: string) => {
     readonly tenantId: string | null;
@@ -3493,6 +3552,10 @@ export declare interface PluginInspectEndpoint {
      * optional. `health` → `/_voltro/inspect/plugins/<slug>/health`.
      */
     readonly path: string;
+    /** Evidence scope for successful JSON reads. When declared, the inspect
+     * router attaches origin, capture time and completeness. Omit only when the
+     * endpoint supplies its own observation metadata. */
+    readonly scope?: 'process' | 'shared-store' | 'declaration';
     /** Optional human-readable description; surfaced in the dashboard. */
     readonly description?: string;
     /**
@@ -3991,6 +4054,22 @@ export declare interface PolicyGuardSpec<Input = unknown> {
 
 export declare type ProcedureDescriptor = QueryProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | MutationProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | ActionProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All> | StreamProcedureDescriptor<string, Schema.Schema.Any, Schema.Schema.Any, Schema.Schema.All>;
 
+/** The shape of one procedure, as the pair of peers must agree on it. */
+export declare interface ProcedureLike {
+    readonly _tag: string;
+    readonly payloadSchema?: {
+        readonly ast?: unknown;
+    } | undefined;
+    readonly successSchema?: {
+        readonly ast?: unknown;
+    } | undefined;
+    readonly errorSchema?: {
+        readonly ast?: unknown;
+    } | undefined;
+}
+
+export declare const procedureShapeDigest: (rpc: ProcedureLike) => string;
+
 export declare const PROTOCOL_VERSION: 1;
 
 export declare type ProtocolVersion = typeof PROTOCOL_VERSION;
@@ -4541,6 +4620,15 @@ export declare interface ScheduleFireContext {
  */
 export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: ScheduleFireContext) => Promise<void>;
 
+/**
+ * A structural rendering of one schema's AST: property names, optionality and
+ * nested shape, with declared names deliberately NOT standing in for content.
+ *
+ * Stable across two identical declarations, and it moves for any change to the
+ * shape a peer would decode against.
+ */
+export declare const schemaShape: (ast: unknown, depth?: number) => string;
+
 export declare interface ScopeCache {
     /** The effective window in milliseconds. */
     readonly ttlMs: number;
@@ -4700,6 +4788,13 @@ export declare const setPolicyGuardResolver: (resolver: PolicyGuardResolver | un
  */
 export declare const setResourceScopeResolver: (resolver: ResourceScopeResolver | undefined) => void;
 
+/**
+ * FNV-1a, 32-bit, hex. Synchronous, dependency-free, works identically in a
+ * browser and in node — see the header for why a cryptographic digest is the
+ * wrong tool here.
+ */
+export declare const shapeDigest: (text: string) => string;
+
 /**
  * Every routing key a `source:` names, flattened.
  *
@@ -5048,6 +5143,13 @@ export declare const subscriptionEvent: <D extends Schema.Schema.Any>(data: D) =
     revision: Schema.optional<typeof Schema.Number>;
 }>]>;
 
+export declare interface SurfaceMismatch {
+    /** Tags both sides carry whose shapes disagree — the stale-bundle signal. */
+    readonly differing: ReadonlyArray<string>;
+    /** Tags the peer binds that this side does not have. */
+    readonly missingHere: ReadonlyArray<string>;
+}
+
 export declare const systemSubject: (id: string, scopes?: ReadonlyArray<string>) => Subject;
 
 /**
@@ -6469,11 +6571,11 @@ export declare type WorkflowStepInterceptor = <Success, ErrorE, R>(next: Effect.
  * error union with `ScopeError` / `Unauthenticated`, exactly as it does for a
  * mutation, and labels the strict-input refusal as a guarded procedure's.
  */
-export declare const workflowToRpc: (workflow: {
-    readonly name: string;
-    readonly payloadSchema: Schema.Schema.Any;
+export declare const workflowToRpc: <const Name extends string, Payload extends Schema.Schema.Any>(workflow: {
+    readonly name: Name;
+    readonly payloadSchema: Payload;
     readonly errorSchema: Schema.Schema.All;
-}, extraErrors?: ExtraErrors) => Rpc.Rpc<string, Schema.Schema.Any, Schema.Struct<{
+}, extraErrors?: ExtraErrors) => Rpc.Rpc<Name, Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload, Schema.Struct<{
     /** Stable handle callers pass to `useWorkflowRun(...)`. The durable execution
      *  id for a started run; the pending-intent id for a queued one. */
     id: typeof Schema.String;