@voltro/protocol 0.74.0 → 0.76.0

package/THIRD-PARTY-NOTICES.md

@@ -65,7 +65,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## jose@6.2.10
+## jose@6.2.12
 
 License: MIT
 

package/dist/index.d.ts

@@ -496,7 +496,7 @@ export declare interface AuthenticatedGuardSpec {
  * an auth resolver before reaching its handler. The application provides
  * the resolver via `Layer.succeed(AuthMiddleware, AuthMiddleware.of(fn))`,
  * where `fn` receives `{headers, payload, rpc, clientId}` and returns an
- * `Effect<Subject>` — typically by inspecting headers / Bearer token and
+ * `Effect<Subject, Unauthenticated>` — typically by inspecting headers / Bearer token and
  * looking the caller up.
  *
  * `provides: SubjectService` means the resolver's return value is placed
@@ -514,6 +514,7 @@ export declare class AuthMiddleware extends AuthMiddleware_base {
 
 declare const AuthMiddleware_base: RpcMiddleware.TagClass<AuthMiddleware, "@voltro/AuthMiddleware", {
     readonly provides: typeof SubjectService;
+    readonly failure: typeof Unauthenticated;
 }>;
 
 export declare type AuthRouteHandler = (req: AuthRouteRequest) => Promise<AuthRouteResponse>;
@@ -3844,7 +3845,7 @@ export declare interface PluginLifecycleContext {
  *  and the artifact's index — so a store that supports resumable puts stores
  *  one object however often the dispatcher is retried. */
 export declare interface PluginMediaPersistCapability {
-    readonly put: (args: {
+    readonly put: (args: PluginMediaPersistMetadata & {
         readonly bytes: Uint8Array;
         readonly mediaType: string;
         readonly tenantId: string | null;
@@ -3854,7 +3855,7 @@ export declare interface PluginMediaPersistCapability {
         readonly refId: string;
     }>;
     /** Re-host a provider URL. Absent → the provider's URL is handed on as-is. */
-    readonly ingestUrl?: (args: {
+    readonly ingestUrl?: (args: PluginMediaPersistMetadata & {
         readonly url: string;
         readonly tenantId: string | null;
         readonly operationId: string;
@@ -3864,6 +3865,19 @@ export declare interface PluginMediaPersistCapability {
     }>;
 }
 
+/**
+ * Who a persisted media artifact belongs to, how it is served, and how it is
+ * found again. The dispatcher knows none of this — the caller of `mediaStep`
+ * does — so it rides the queued job and is handed to the store as-is. Without
+ * it every generated artifact landed owner-less, private and untagged, and an
+ * app whose deletion and restore key on owner and tags could not use it.
+ */
+export declare interface PluginMediaPersistMetadata {
+    readonly ownerId?: string | null;
+    readonly visibility?: 'public' | 'private';
+    readonly tags?: ReadonlyArray<string>;
+}
+
 export declare interface PluginMigration {
     readonly id: string;
     readonly description?: string;
@@ -6707,8 +6721,14 @@ export declare interface VoltroTableNames {
 /** What a gateway's connection handler receives. Transport-agnostic on
  *  purpose — the runtime adapts the platform socket to this. */
 export declare interface WebSocketGatewayConnection {
-    /** Send a text or binary frame. */
+    /** Enqueue a bounded text or binary frame; overflow closes the connection. */
     readonly send: (data: string | Uint8Array) => void;
+    /** Await the local transport write, NOT peer receipt. Rejects on close or
+     * overflow. Await each send to propagate backpressure to the producer. */
+    readonly sendAsync: (data: string | Uint8Array) => Promise<void>;
+    /** Aborted on close, expiry, shutdown or setup failure, including while
+     * onConnection is still awaiting an upstream connection. */
+    readonly signal: AbortSignal;
     /** Close the connection (application close codes 4000-4999 are yours). */
     readonly close: (code?: number, reason?: string) => void;
     /** Register a message listener (binary-safe; text arrives as bytes). */
@@ -6736,12 +6756,23 @@ export declare interface WebSocketGatewayRoute {
      *   protocol-level auth). A decision somebody wrote down, not a default.
      */
     readonly auth: 'subject' | 'public';
+    /** Per-connection bounds. Inbound size is checked before app dispatch,
+     * not before the platform assembles a WebSocket message. */
+    readonly limits?: {
+        /** Maximum inbound/outbound frame bytes; default 1 MiB. */
+        readonly maxMessageBytes?: number;
+        /** Active plus queued outbound bytes; default 4 MiB. */
+        readonly maxPendingBytes?: number;
+        /** Active plus queued outbound messages; default 64. */
+        readonly maxPendingMessages?: number;
+    };
     /**
      * Runs once per accepted connection. The returned function is the
      * connection's TEARDOWN — taken at construction (the `startOutboxRunner`
      * rule): it runs on client disconnect, on credential expiry, and on
      * server shutdown, so whatever the handler opened cannot outlive the
-     * socket.
+     * socket. Message listeners are live during async setup. If setup finishes
+     * after disconnect, its returned teardown still runs exactly once.
      */
     readonly onConnection: (connection: WebSocketGatewayConnection) => void | (() => void) | Promise<void | (() => void)>;
 }
@@ -6819,6 +6850,12 @@ export declare const withRpcTag: <D extends {
 export declare interface WorkflowAccess {
     /** The author's guards, or the erased `openAccess` entry — never both. */
     readonly guards: DeclaredAccess<unknown> | undefined;
+    /** The CONTROL decision: the author's `controls.guards`, or the erased
+     *  `controls.openAccess` entry. `undefined` means undecided — wire control
+     *  is refused (system and `admin:full` aside). */
+    readonly controls: DeclaredAccess<unknown> | undefined;
+    /** The reason text, when control is open. */
+    readonly controlsOpenAccess: string | undefined;
     readonly openAccess: string | undefined;
     readonly internal: boolean;
 }
@@ -6836,6 +6873,8 @@ export declare const workflowAccessDescriptor: (definition: {
     readonly internal: boolean;
     readonly guards: DeclaredAccess<unknown> | undefined;
     readonly openAccess: string | undefined;
+    /** The CONTROL decision — `undefined` means undecided, and wire control is refused. */
+    readonly controls: DeclaredAccess<unknown> | undefined;
 };
 
 /** What an author writes on `workflow({ … })`. */
@@ -6865,6 +6904,32 @@ export declare interface WorkflowAccessOptions<Payload = unknown> {
      * Cannot be combined with `openAccess` (there is no wire to decide about).
      */
     readonly internal?: boolean;
+    /**
+     * WHO MAY DRIVE a RUN of this workflow over the wire — `cancel`, `signal`,
+     * `update`, `resume`, and the queued forms of cancel. Same vocabulary as
+     * `guards:` / `openAccess:`, and a SEPARATE decision on purpose.
+     *
+     * Starting and driving are different authorities. The approval pattern is
+     * the case that shows it: the customer who may START an order must not be
+     * the one who signals its own approval, and the manager who approves may not
+     * place orders at all. Reusing the start decision would get both wrong.
+     *
+     * Declared with NOTHING, wire control is refused for every caller but the
+     * system and a subject holding `admin:full`. That default is what makes the
+     * app's own guarded surface (`orders.approve`, with its `{ scope }`) the only
+     * way in: the built-in used to hand the same decision to anyone in the
+     * tenant who knew the run id, which is the app's authorization undone by a
+     * procedure the app never wrote.
+     *
+     * A resource-scoped guard reads its id from the RUN's start payload, exactly
+     * as the start guard reads it from the start input:
+     * `controls: { guards: [{ action: 'approve', resourceType: 'order', resource: (p) => p.orderId }] }`.
+     */
+    readonly controls?: {
+        readonly guards?: Guards<Payload>;
+        /** Anyone who may see the run may drive it — and WHY. A reason, never a boolean. */
+        readonly openAccess?: string;
+    };
 }
 
 /** The non-enumerable property a `workflow()` definition carries its decision under. */
@@ -7274,6 +7339,85 @@ export declare const workflowResumeDescriptor: ActionProcedureDescriptor<"__volt
     }>;
 }>>, typeof Schema.Never>;
 
+export declare type WorkflowRetryCommand = typeof WorkflowRetryCommandSchema.Type;
+
+/** Transport input for one deliberate retry; ownership is resolved server-side.
+ * The optional override is encoded with the complete workflow payload schema. */
+export declare const WorkflowRetryCommandSchema: Schema.Struct<{
+    payloadOverride: Schema.optional<typeof Schema.Unknown>;
+    runId: Schema.filter<typeof Schema.NonEmptyString>;
+    requestId: Schema.filter<typeof Schema.NonEmptyString>;
+}>;
+
+export declare type WorkflowRetryObservation = typeof WorkflowRetryObservationSchema.Type;
+
+/** Observation of one durable retry intent. Engine acceptance is not workflow
+ * completion. A prepared identity alone never proves that execution started. */
+export declare const WorkflowRetryObservationSchema: Schema.Union<[Schema.Struct<{
+    kind: Schema.Literal<["queued"]>;
+    nextAttemptAt: Schema.NullOr<typeof Schema.Number>;
+    requestId: typeof Schema.NonEmptyString;
+    originalRunId: typeof Schema.NonEmptyString;
+    originalExecutionId: typeof Schema.NonEmptyString;
+    workflowName: typeof Schema.NonEmptyString;
+}>, Schema.filter<Schema.Struct<{
+    kind: Schema.Literal<["accepted"]>;
+    executionId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+    originalRunId: typeof Schema.NonEmptyString;
+    originalExecutionId: typeof Schema.NonEmptyString;
+    workflowName: typeof Schema.NonEmptyString;
+}>>, Schema.filter<Schema.Struct<{
+    kind: Schema.Literal<["unconfirmed"]>;
+    automaticRetryStopped: typeof Schema.Boolean;
+    nextAttemptAt: Schema.NullOr<typeof Schema.Number>;
+    requestId: typeof Schema.NonEmptyString;
+    originalRunId: typeof Schema.NonEmptyString;
+    originalExecutionId: typeof Schema.NonEmptyString;
+    workflowName: typeof Schema.NonEmptyString;
+}>>, Schema.Struct<{
+    kind: Schema.Literal<["not-started"]>;
+    outcome: Schema.Union<[Schema.Struct<{
+        kind: Schema.Literal<["dropped"]>;
+        at: typeof Schema.Number;
+        retryAfterMs: typeof Schema.Number;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["skipped"]>;
+        at: typeof Schema.Number;
+        executionId: typeof Schema.String;
+        runId: typeof Schema.String;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["superseded"]>;
+        at: typeof Schema.Number;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["cancelled"]>;
+        at: typeof Schema.Number;
+    }>, Schema.Struct<{
+        kind: Schema.Literal<["abandoned"]>;
+        at: typeof Schema.Number;
+        failureId: typeof Schema.NonEmptyString;
+    }>]>;
+    requestId: typeof Schema.NonEmptyString;
+    originalRunId: typeof Schema.NonEmptyString;
+    originalExecutionId: typeof Schema.NonEmptyString;
+    workflowName: typeof Schema.NonEmptyString;
+}>, Schema.Struct<{
+    kind: Schema.Literal<["rejected"]>;
+    failureId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+    originalRunId: typeof Schema.NonEmptyString;
+    originalExecutionId: typeof Schema.NonEmptyString;
+    workflowName: typeof Schema.NonEmptyString;
+}>]>;
+
+export declare type WorkflowRetryTarget = typeof WorkflowRetryTargetSchema.Type;
+
+/** Persist the request ID before sending. Reuse this target after a lost reply. */
+export declare const WorkflowRetryTargetSchema: Schema.Struct<{
+    runId: Schema.filter<typeof Schema.NonEmptyString>;
+    requestId: Schema.filter<typeof Schema.NonEmptyString>;
+}>;
+
 export declare type WorkflowRunEventRow = Schema.Schema.Type<typeof WorkflowRunEventRowSchema>;
 
 export declare const WorkflowRunEventRowSchema: Schema.Struct<{