@relayflows/sdk 2.0.35 → 2.0.36

package/src/protocol.ts

@@ -53,8 +53,16 @@ export type Verb =
   | 'effect.confirm'
   | 'step.complete'
   | 'step.wait'
+  | 'subscription.park'
   | 'event.emit'
   | 'event.submit'
+  | 'subscription.open'
+  | 'subscription.activate'
+  | 'subscription.deliver'
+  | 'subscription.inspect'
+  | 'subscription.fence_overflow'
+  | 'subscription.next'
+  | 'subscription.close'
   | 'channel.append'
   | 'channel.receive'
   | 'channel.ack'
@@ -362,6 +370,10 @@ export interface EventEmitParams {
   run_id: string;
   event_key: string;
   payload: unknown;
+  /** Provider delivery id for body activities. Required by Cloud; optional for legacy exact waits. */
+  delivery_id?: string;
+  /** Provider actor identity, used by the local router adapter for self filtering. */
+  actor?: string;
 }
 export interface EventEmitResult {
   matched: number;
@@ -388,6 +400,111 @@ export interface EventSubmitResult {
   run?: unknown;
 }
 
+/** Body-level activity open; the server acknowledges only after its fenced binding is durable. */
+export interface SubscriptionOpenParams {
+  run_id: string;
+  subscription_id: string;
+  event_types: string[];
+  pattern?: Record<string, unknown>;
+  settle_ms: number;
+  idle_ms: number;
+  deadline_ms: number;
+  include_self: boolean;
+}
+export type SubscriptionOpenResult =
+  | {
+    /** Immutable snapshot from the durable `subscription.prepared` entry. */
+    state: 'prepared';
+    subscription_id: string;
+    event_types: string[];
+    pattern?: Record<string, unknown>;
+    stream: string;
+    settle_ms: number;
+    idle_ms: number;
+    deadline_at_ms: number;
+    include_self: boolean;
+  }
+  | {
+    state: 'active';
+    subscription_id: string;
+    stream: string;
+    deadline_at_ms: number;
+  };
+
+/** Cloud supplies this receipt only after it has durably fenced its binding. */
+export interface SubscriptionActivateParams {
+  run_id: string;
+  subscription_id: string;
+  ingress_offset: number;
+  router_binding: Record<string, unknown>;
+}
+export interface SubscriptionActivateResult {
+  state: 'active';
+  subscription_id: string;
+  stream: string;
+  deadline_at_ms: number;
+}
+
+/** Targeted Cloud ingress; receipt must equal the journaled activation receipt. */
+export interface SubscriptionDeliverParams {
+  run_id: string;
+  subscription_id: string;
+  router_binding: Record<string, unknown>;
+  delivery_id: string;
+  frame: unknown;
+}
+export interface SubscriptionDeliverResult {
+  /** False for an idempotent duplicate or a frame that closes on overflow. */
+  appended: boolean;
+  reason?: 'duplicate' | 'overflow';
+}
+
+/** Read-only projection of the kernel's durable subscription records. */
+export interface SubscriptionSnapshot {
+  subscriptionId: string;
+  state: 'prepared' | 'active' | 'closed';
+  completionReason?: 'closed' | 'run_completed' | 'canceled' | 'deadline' | 'overflow';
+  routerBinding?: Record<string, unknown>;
+  ingressOffset?: number;
+  unreadFrames: number;
+  unreadBytes: number;
+  settleMs: number;
+  idleAtMs?: number;
+  deadlineAtMs: number;
+}
+export interface SubscriptionInspectParams { run_id: string }
+export interface SubscriptionInspectResult { subscriptions: SubscriptionSnapshot[] }
+export interface SubscriptionFenceOverflowParams {
+  run_id: string;
+  subscription_id: string;
+  router_binding: Record<string, unknown>;
+}
+export interface SubscriptionFenceOverflowResult { fenced: true }
+
+export interface SubscriptionNextParams {
+  run_id: string;
+  subscription_id: string;
+  /** Internal durable receipt for the prior normal wake, supplied with the next pull. */
+  acknowledge_wait_id?: string;
+  /** Body call ordinal: replay this pull's durable wake across process restarts. */
+  sequence?: number;
+}
+export type SubscriptionNextResult =
+  | { kind: 'suspended'; subscription_id: string; stream: string; deadline_at_ms: number }
+  | { kind: 'events'; events: unknown[]; offset: number; acknowledge_wait_id?: string }
+  | { kind: 'idle'; acknowledge_wait_id?: string }
+  | { kind: 'deadline'; pending: { from: number; to: number } | null }
+  | { kind: 'overflow'; retained: number; bytes: number; from: number };
+
+export interface SubscriptionCloseParams {
+  run_id: string;
+  subscription_id: string;
+  completion_reason: 'closed' | 'run_completed' | 'canceled';
+}
+export interface SubscriptionCloseResult {
+  closed: string;
+}
+
 export interface StreamAppendParams {
   run_id: string;
   stream: string;
@@ -441,8 +558,20 @@ export interface VerbContract {
   'effect.confirm': { params: EffectConfirmParams; result: EffectConfirmResult };
   'step.complete': { params: StepCompleteParams; result: StepCompleteResult };
   'step.wait': { params: StepWaitParams; result: StepWaitResult };
+  'subscription.park': {
+    params: { run_id: string; step_id: string; attempt: number; idempotency_key: string;
+      subscription_id: string; phase: 'activation' | 'event_wait' };
+    result: RunOutcome;
+  };
   'event.emit': { params: EventEmitParams; result: EventEmitResult };
   'event.submit': { params: EventSubmitParams; result: EventSubmitResult };
+  'subscription.open': { params: SubscriptionOpenParams; result: SubscriptionOpenResult };
+  'subscription.activate': { params: SubscriptionActivateParams; result: SubscriptionActivateResult };
+  'subscription.deliver': { params: SubscriptionDeliverParams; result: SubscriptionDeliverResult };
+  'subscription.inspect': { params: SubscriptionInspectParams; result: SubscriptionInspectResult };
+  'subscription.fence_overflow': { params: SubscriptionFenceOverflowParams; result: SubscriptionFenceOverflowResult };
+  'subscription.next': { params: SubscriptionNextParams; result: SubscriptionNextResult };
+  'subscription.close': { params: SubscriptionCloseParams; result: SubscriptionCloseResult };
   'stream.append': { params: StreamAppendParams; result: StreamAppendResult };
   'stream.read': { params: StreamReadParams; result: StreamReadResult };
   'journal.read': { params: JournalReadParams; result: JournalReadResult };

package/src/step-settling.ts

@@ -0,0 +1,19 @@
+/**
+ * A step's LAST settling `step.completed`: the verdict the kernel settled the
+ * step on. `retry` and `park` completions record an attempt the kernel did
+ * NOT settle it on (relayflowd-core `Disposition`) — crash recovery's
+ * `crashed`, a `worker_error` with iterations left — and precede the attempt
+ * that did, so neither the first completion nor a completion count is the
+ * step's verdict. Shared by the authored reader and the Bun result verifier,
+ * which must agree on which completion a claim is judged against.
+ */
+export function settlingCompletion<T>(entries: readonly T[], stepId: string): T | undefined {
+  return entries.filter(entry => {
+    if (typeof entry !== 'object' || entry === null) return false;
+    const { entry_type: type, step_id: step, payload } = entry as Record<string, unknown>;
+    if (type !== 'step.completed' || step !== stepId) return false;
+    const disposition = typeof payload === 'object' && payload !== null
+      ? (payload as Record<string, unknown>)['disposition'] : undefined;
+    return disposition !== 'retry' && disposition !== 'park';
+  }).at(-1);
+}