@arbitro/client 0.4.1 → 0.5.0

package/README.md

@@ -248,6 +248,74 @@ await client.publishDelayed("ORDERS", "orders.reminder", payload, 5000); // 5s d
 
 Messages are persisted immediately — survives broker restart.
 
+## Workflow Orchestration
+
+Client-side linear pipelines over Arbitro streams. The broker has no workflow-specific code -- everything uses streams, consumer groups, and idempotent publish.
+
+### WorkflowBuilder API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `trigger` | `(subject: string) => this` | Subject pattern that triggers new instances. Required. |
+| `triggerStream` | *(not yet implemented)* | Planned: auto-subscribe to an external stream for trigger. |
+| `step` | `(name: string, handler: StepHandler) => this` | Append a processing step. |
+| `compensate` | *(not yet implemented)* | Planned: rollback handler per step (saga pattern). |
+| `maxRetries` | *(not yet implemented)* | Planned: attempts before DLQ. |
+| `maxContextSize` | *(not yet implemented)* | Planned: max context payload in bytes. |
+| `ackWait` | `(ms: number) => this` | Ack timeout for failover (default: 30000). |
+| `inflight` | `(n: number) => this` | Concurrent tasks per worker (default: 10). |
+| `start` | `() => Promise<WorkflowHandle>` | Register streams, consumer, and start processing. |
+
+### WorkflowHandle API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `trigger` | `(client: ArbitroClient, context: Buffer) => Promise<number>` | Trigger a new workflow instance. Returns the instance ID. |
+| `name` | `string` (getter) | Workflow name. |
+
+### Complete Example
+
+```typescript
+import { ArbitroClient, WorkflowBuilder } from '@arbitro/client'
+import type { StepContext, StepResult } from '@arbitro/client'
+
+const client = new ArbitroClient({ servers: ['127.0.0.1:9898'] })
+await client.connect()
+
+const wf = await new WorkflowBuilder(client, 'order-process')
+  .trigger('orders.created')
+  // Step 1: validate
+  .step('validate', async (ctx: StepContext): Promise<StepResult> => {
+    const validated = await validateOrder(ctx.context)
+    return { context: validated }
+  })
+  // Step 2: charge
+  .step('charge', async (ctx: StepContext): Promise<StepResult> => {
+    const receipt = await chargePayment(ctx.context)
+    return { context: receipt }
+  })
+  // Step 3: ship
+  .step('ship', async (ctx: StepContext): Promise<StepResult> => {
+    const tracking = await createShipment(ctx.context)
+    return { context: tracking }
+  })
+  .ackWait(30_000)
+  .inflight(10)
+  .start()
+
+// Manual trigger
+const instanceId = await wf.trigger(client, Buffer.from('order-123-payload'))
+console.log(`started instance ${instanceId}`)
+```
+
+### Internals
+
+- Tasks flow through `_wf.{name}.tasks` stream with a consumer `_wf.{name}.workers`.
+- Each step transition publishes with `msgId` format `wf:{instance}:{step}:{attempt}` for deduplication.
+- `ackWait` enables failover: if a worker dies, the broker redelivers to another subscriber.
+
+> **Note:** The TypeScript workflow module currently implements the core step pipeline. Compensation (saga), DLQ, `triggerStream`, `maxRetries`, and `maxContextSize` are available in the Rust client and planned for the TS client.
+
 ## Reconnect behavior
 
 The TS client reconnects transport automatically and reattaches active subscriptions and cron jobs after reconnect. That behavior lives in the client, not in the benchmarks. This matters for:

package/dist/{chunk-6BCX2E2R.mjs → chunk-C2QLJBAC.mjs}

@@ -99,4 +99,4 @@ export {
   EntryFlag,
   Action
 };
-//# sourceMappingURL=chunk-6BCX2E2R.mjs.map
+//# sourceMappingURL=chunk-C2QLJBAC.mjs.map

package/dist/{chunk-6BCX2E2R.mjs.map → chunk-C2QLJBAC.mjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/proto/constants.ts"],"sourcesContent":["// V2 wire protocol constants — must match arbitro-proto/src/action.rs exactly.\n\n// ── Hello handshake (only frame without a Header) ───────────────────────\nexport const MAGIC_V2       = 0x32425241  // \"ARB2\" as u32 LE\nexport const HELLO_SIZE     = 8\nexport const CURRENT_VERSION = 2\n\nexport const enum Role {\n  Client = 0,\n  Server = 1,\n}\n\nexport const enum Cap {\n  Headers          = 1 << 0,\n  Reply            = 1 << 1,\n  BatchHeaders     = 1 << 2,\n  CompressedPayload = 1 << 3,\n}\n\n// ── Header (16 bytes, every frame after Hello) ──────────────────────────\nexport const HEADER_SIZE     = 16\n\n// Byte offsets within the 16-byte header\nexport const OFF_ACTION      = 0   // u16 LE\nexport const OFF_FLAGS       = 2   // u8\nexport const OFF_ENTRY_FLAGS = 3   // u8\nexport const OFF_MSG_LEN     = 4   // u32 LE\nexport const OFF_SEQ         = 8   // u64 LE\n\n// ── Transport flags (header.flags, offset 2) ────────────────────────────\nexport const enum Flag {\n  None         = 0x00,\n  AckReq       = 0x01,\n  Dup          = 0x02,\n  PriorityHigh = 0x04,\n}\n\n// ── Per-message flags (header.entry_flags, offset 3) ────────────────────\nexport const enum EntryFlag {\n  None           = 0x00,\n  Retain         = 0x01,\n  Compressed     = 0x02,\n  NoBackpressure = 0x04,\n}\n\n// ── Action codes (0xFFGG: FF=family, GG=variant) ────────────────────────\nexport const enum Action {\n  // 0x00xx — Handshake / control\n  Hello           = 0x0001,\n  Auth            = 0x0002,\n\n  // 0x01xx — Publish family\n  Publish                 = 0x0101,\n  PublishAccumulate       = 0x0102,\n  PublishBatch            = 0x0103,\n  PublishWithReply        = 0x0104,\n  PublishWithHeaders      = 0x0105,\n  PublishBatchWithHeaders = 0x0106,\n\n  // 0x02xx — Delivery / Ack\n  Deliver      = 0x0200,\n  Ack          = 0x0201,\n  Nack         = 0x0202,\n  RepOk        = 0x0203,\n  RepError     = 0x0204,\n  RepBatch     = 0x0205,\n  BatchAck     = 0x0206,\n  FanoutBatch  = 0x0207,\n  AckSync      = 0x0208,\n  BatchAckSync = 0x0209,\n  BatchNack    = 0x020A,\n\n  // 0x03xx — Subscription\n  Subscribe   = 0x0301,\n  Unsubscribe = 0x0302,\n\n  // 0x04xx — Stream management\n  CreateStream = 0x0401,\n  DeleteStream = 0x0402,\n  GetStream    = 0x0403,\n  ListStreams  = 0x0404,\n  PurgeStream  = 0x0405,\n  DrainSubject = 0x0406,\n\n  // 0x05xx — Consumer management\n  CreateConsumer = 0x0501,\n  DeleteConsumer = 0x0502,\n  GetConsumer    = 0x0503,\n  ListConsumers  = 0x0504,\n  ConsumerStats  = 0x0505,\n  PauseConsumer  = 0x0506,\n  ResumeConsumer = 0x0507,\n\n  // 0x08xx — Delayed publish\n  PublishDelayed = 0x0801,\n\n  // 0x06xx — System\n  Ping       = 0x0601,\n  Pong       = 0x0602,\n  Connect    = 0x0603,\n  Connected  = 0x0604,\n  Disconnect = 0x0605,\n\n  // 0x07xx — Cron scheduling\n  CreateCron = 0x0701,\n  DeleteCron = 0x0702,\n  ListCrons  = 0x0703,\n  CronFire   = 0x0704,\n  CronAck    = 0x0705,\n}\n"],"mappings":"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","names":["Role","Cap","Flag","EntryFlag","Action"]}
+{"version":3,"sources":["../src/proto/constants.ts"],"sourcesContent":["// V2 wire protocol constants — must match arbitro-proto/src/action.rs exactly.\n\n// ── Hello handshake (only frame without a Header) ───────────────────────\nexport const MAGIC_V2       = 0x32425241  // \"ARB2\" as u32 LE\nexport const HELLO_SIZE     = 8\nexport const CURRENT_VERSION = 2\n\nexport const enum Role {\n  Client = 0,\n  Server = 1,\n}\n\nexport const enum Cap {\n  Headers          = 1 << 0,\n  Reply            = 1 << 1,\n  BatchHeaders     = 1 << 2,\n  CompressedPayload = 1 << 3,\n}\n\n// ── Header (16 bytes, every frame after Hello) ──────────────────────────\nexport const HEADER_SIZE     = 16\n\n// Byte offsets within the 16-byte header\nexport const OFF_ACTION      = 0   // u16 LE\nexport const OFF_FLAGS       = 2   // u8\nexport const OFF_ENTRY_FLAGS = 3   // u8\nexport const OFF_MSG_LEN     = 4   // u32 LE\nexport const OFF_SEQ         = 8   // u64 LE\n\n// ── Transport flags (header.flags, offset 2) ────────────────────────────\nexport const enum Flag {\n  None         = 0x00,\n  AckReq       = 0x01,\n  Dup          = 0x02,\n  PriorityHigh = 0x04,\n}\n\n// ── Per-message flags (header.entry_flags, offset 3) ────────────────────\nexport const enum EntryFlag {\n  None           = 0x00,\n  Retain         = 0x01,\n  Compressed     = 0x02,\n  NoBackpressure = 0x04,\n}\n\n// ── Action codes (0xFFGG: FF=family, GG=variant) ────────────────────────\nexport const enum Action {\n  // 0x00xx — Handshake / control\n  Hello           = 0x0001,\n  Auth            = 0x0002,\n\n  // 0x01xx — Publish family\n  Publish                 = 0x0101,\n  PublishAccumulate       = 0x0102,\n  PublishBatch            = 0x0103,\n  PublishWithReply        = 0x0104,\n  PublishWithHeaders      = 0x0105,\n  PublishBatchWithHeaders = 0x0106,\n\n  // 0x02xx — Delivery / Ack\n  Deliver      = 0x0200,\n  Ack          = 0x0201,\n  Nack         = 0x0202,\n  RepOk        = 0x0203,\n  RepError     = 0x0204,\n  RepBatch     = 0x0205,\n  BatchAck     = 0x0206,\n  FanoutBatch  = 0x0207,\n  AckSync      = 0x0208,\n  BatchAckSync = 0x0209,\n  BatchNack    = 0x020A,\n\n  // 0x03xx — Subscription\n  Subscribe   = 0x0301,\n  Unsubscribe = 0x0302,\n\n  // 0x04xx — Stream management\n  CreateStream = 0x0401,\n  DeleteStream = 0x0402,\n  GetStream    = 0x0403,\n  ListStreams  = 0x0404,\n  PurgeStream  = 0x0405,\n  DrainSubject = 0x0406,\n\n  // 0x05xx — Consumer management\n  CreateConsumer = 0x0501,\n  DeleteConsumer = 0x0502,\n  GetConsumer    = 0x0503,\n  ListConsumers  = 0x0504,\n  ConsumerStats  = 0x0505,\n  PauseConsumer  = 0x0506,\n  ResumeConsumer = 0x0507,\n\n  // 0x08xx — Delayed publish\n  PublishDelayed = 0x0801,\n\n  // 0x06xx — System\n  Ping       = 0x0601,\n  Pong       = 0x0602,\n  Connect    = 0x0603,\n  Connected  = 0x0604,\n  Disconnect = 0x0605,\n\n  // 0x07xx — Cron scheduling\n  CreateCron = 0x0701,\n  DeleteCron = 0x0702,\n  ListCrons  = 0x0703,\n  CronFire   = 0x0704,\n  CronAck    = 0x0705,\n\n  // 0x09xx reserved (workflow removed — now a client-side library).\n}\n"],"mappings":"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","names":["Role","Cap","Flag","EntryFlag","Action"]}

package/dist/{chunk-SKCXQO7R.mjs → chunk-GW36GP2C.mjs}

@@ -8,7 +8,7 @@ import {
   OFF_FLAGS,
   OFF_MSG_LEN,
   OFF_SEQ
-} from "./chunk-6BCX2E2R.mjs";
+} from "./chunk-C2QLJBAC.mjs";
 
 // src/proto/frame.ts
 function frame(action, seq, bodyLen, flags = 0, entryFlags = 0) {
@@ -121,4 +121,4 @@ export {
   packPublishDelayed,
   packPublishBatch
 };
-//# sourceMappingURL=chunk-SKCXQO7R.mjs.map
+//# sourceMappingURL=chunk-GW36GP2C.mjs.map

package/dist/{constants-KF57DJ2L.mjs → constants-57DO6N3H.mjs}

@@ -13,7 +13,7 @@ import {
   OFF_MSG_LEN,
   OFF_SEQ,
   Role
-} from "./chunk-6BCX2E2R.mjs";
+} from "./chunk-C2QLJBAC.mjs";
 export {
   Action,
   CURRENT_VERSION,
@@ -30,4 +30,4 @@ export {
   OFF_SEQ,
   Role
 };
-//# sourceMappingURL=constants-KF57DJ2L.mjs.map
+//# sourceMappingURL=constants-57DO6N3H.mjs.map

package/dist/index.d.mts

@@ -86,6 +86,8 @@ interface SubjectInflightLimit {
 }
 interface ConsumerConfig {
     name?: string;
+    /** Shared consumer group name for round-robin delivery. Defaults to `name`. */
+    group?: string;
     filter?: string;
     fanout?: boolean;
     /** Consumer-side ACK policy. None = fire-and-forget delivery, Explicit = consumer must ACK. */
@@ -654,6 +656,64 @@ declare class Topic<T extends Record<string, unknown>> {
 
 declare function streamId(name: Buffer | string): number;
 
+declare class WorkflowHandle {
+    private readonly workflowName;
+    private readonly taskStreamName;
+    private readonly dlqStreamName;
+    private readonly sub;
+    private readonly triggerSub;
+    constructor(workflowName: string, taskStreamName: string, dlqStreamName: string, sub: unknown, triggerSub: unknown | undefined);
+    get name(): string;
+    get taskStream(): string;
+    get dlqStream(): string;
+    trigger(client: ArbitroClient, context: Buffer): Promise<number>;
+}
+
+interface StepContext {
+    readonly name: string;
+    readonly instanceId: number;
+    readonly stepIndex: number;
+    readonly attempt: number;
+    readonly context: Buffer;
+}
+interface StepResult {
+    readonly context: Buffer;
+}
+type StepHandler = (ctx: StepContext) => Promise<StepResult>;
+declare class WorkflowBuilder {
+    private readonly client;
+    private readonly workflowName;
+    private triggerSubject;
+    private triggerStreamName;
+    private readonly steps;
+    private ackWaitMs;
+    private maxInflightVal;
+    private maxRetriesVal;
+    private maxContextSizeVal;
+    constructor(client: ArbitroClient, workflowName: string);
+    trigger(subject: string): this;
+    triggerStream(streamName: string): this;
+    step(name: string, handler: StepHandler): this;
+    /** Compensation handler for the most recently added step. */
+    compensate(_stepName: string, handler: StepHandler): this;
+    ackWait(ms: number): this;
+    inflight(n: number): this;
+    maxRetries(n: number): this;
+    maxContextSize(bytes: number): this;
+    start(): Promise<WorkflowHandle>;
+    private subscribeWorker;
+    private subscribeTrigger;
+}
+
+/** Bit flag set on stepIndex to mark compensation tasks. */
+declare const COMPENSATION_BIT = 32768;
+interface DecodedTask {
+    readonly instanceId: number;
+    readonly stepIndex: number;
+    readonly attempt: number;
+    readonly context: Buffer;
+}
+
 /** Wraps a ZodObject schema as an Encoding<T>.
  *
  *  - encode: msgpack (no Zod overhead — bytes out)
@@ -667,4 +727,4 @@ declare function zodCodec<S extends ZodRawShape>(zodSchema: ZodObject<S>): Encod
     readonly fields: string[];
 };
 
-export { AckPolicy, ArbitroClient, ArbitroError, type BatchPublishEntry, type ClientConfig, type ClientMetricsSnapshot, Codec, Consumer, type ConsumerConfig, type ConsumerInfo, CronBuilder, type CronContext, CronHandle, type CronHandler, type DeleteStreamOpts, DeliverPolicy, type Encoding, ErrorCode, type ErrorCodeValue, type FieldType, type FieldTypeMap, type FlushConfig, type InferSchema, type JournalConfig, JournalType, JsonCodec, type LazyMessage, type LogFn, type Logger, Message, type PublishOpts, type ReconnectConfig, type Schema, Stream, type StreamConfig, type StreamInfo, StringCodec, type SubjectInflightLimit, type SubscribeOptions, Subscription, type TlsConfig, Topic, decodeJson, decodeString, encodeJson, encodeString, makeLazyMessage, schema, streamId, zodCodec };
+export { AckPolicy, ArbitroClient, ArbitroError, type BatchPublishEntry, COMPENSATION_BIT, type ClientConfig, type ClientMetricsSnapshot, Codec, Consumer, type ConsumerConfig, type ConsumerInfo, CronBuilder, type CronContext, CronHandle, type CronHandler, type DecodedTask, type DeleteStreamOpts, DeliverPolicy, type Encoding, ErrorCode, type ErrorCodeValue, type FieldType, type FieldTypeMap, type FlushConfig, type InferSchema, type JournalConfig, JournalType, JsonCodec, type LazyMessage, type LogFn, type Logger, Message, type PublishOpts, type ReconnectConfig, type Schema, type StepContext, type StepHandler, type StepResult, Stream, type StreamConfig, type StreamInfo, StringCodec, type SubjectInflightLimit, type SubscribeOptions, Subscription, type TlsConfig, Topic, WorkflowBuilder, WorkflowHandle, decodeJson, decodeString, encodeJson, encodeString, makeLazyMessage, schema, streamId, zodCodec };

package/dist/index.d.ts

@@ -86,6 +86,8 @@ interface SubjectInflightLimit {
 }
 interface ConsumerConfig {
     name?: string;
+    /** Shared consumer group name for round-robin delivery. Defaults to `name`. */
+    group?: string;
     filter?: string;
     fanout?: boolean;
     /** Consumer-side ACK policy. None = fire-and-forget delivery, Explicit = consumer must ACK. */
@@ -654,6 +656,64 @@ declare class Topic<T extends Record<string, unknown>> {
 
 declare function streamId(name: Buffer | string): number;
 
+declare class WorkflowHandle {
+    private readonly workflowName;
+    private readonly taskStreamName;
+    private readonly dlqStreamName;
+    private readonly sub;
+    private readonly triggerSub;
+    constructor(workflowName: string, taskStreamName: string, dlqStreamName: string, sub: unknown, triggerSub: unknown | undefined);
+    get name(): string;
+    get taskStream(): string;
+    get dlqStream(): string;
+    trigger(client: ArbitroClient, context: Buffer): Promise<number>;
+}
+
+interface StepContext {
+    readonly name: string;
+    readonly instanceId: number;
+    readonly stepIndex: number;
+    readonly attempt: number;
+    readonly context: Buffer;
+}
+interface StepResult {
+    readonly context: Buffer;
+}
+type StepHandler = (ctx: StepContext) => Promise<StepResult>;
+declare class WorkflowBuilder {
+    private readonly client;
+    private readonly workflowName;
+    private triggerSubject;
+    private triggerStreamName;
+    private readonly steps;
+    private ackWaitMs;
+    private maxInflightVal;
+    private maxRetriesVal;
+    private maxContextSizeVal;
+    constructor(client: ArbitroClient, workflowName: string);
+    trigger(subject: string): this;
+    triggerStream(streamName: string): this;
+    step(name: string, handler: StepHandler): this;
+    /** Compensation handler for the most recently added step. */
+    compensate(_stepName: string, handler: StepHandler): this;
+    ackWait(ms: number): this;
+    inflight(n: number): this;
+    maxRetries(n: number): this;
+    maxContextSize(bytes: number): this;
+    start(): Promise<WorkflowHandle>;
+    private subscribeWorker;
+    private subscribeTrigger;
+}
+
+/** Bit flag set on stepIndex to mark compensation tasks. */
+declare const COMPENSATION_BIT = 32768;
+interface DecodedTask {
+    readonly instanceId: number;
+    readonly stepIndex: number;
+    readonly attempt: number;
+    readonly context: Buffer;
+}
+
 /** Wraps a ZodObject schema as an Encoding<T>.
  *
  *  - encode: msgpack (no Zod overhead — bytes out)
@@ -667,4 +727,4 @@ declare function zodCodec<S extends ZodRawShape>(zodSchema: ZodObject<S>): Encod
     readonly fields: string[];
 };
 
-export { AckPolicy, ArbitroClient, ArbitroError, type BatchPublishEntry, type ClientConfig, type ClientMetricsSnapshot, Codec, Consumer, type ConsumerConfig, type ConsumerInfo, CronBuilder, type CronContext, CronHandle, type CronHandler, type DeleteStreamOpts, DeliverPolicy, type Encoding, ErrorCode, type ErrorCodeValue, type FieldType, type FieldTypeMap, type FlushConfig, type InferSchema, type JournalConfig, JournalType, JsonCodec, type LazyMessage, type LogFn, type Logger, Message, type PublishOpts, type ReconnectConfig, type Schema, Stream, type StreamConfig, type StreamInfo, StringCodec, type SubjectInflightLimit, type SubscribeOptions, Subscription, type TlsConfig, Topic, decodeJson, decodeString, encodeJson, encodeString, makeLazyMessage, schema, streamId, zodCodec };
+export { AckPolicy, ArbitroClient, ArbitroError, type BatchPublishEntry, COMPENSATION_BIT, type ClientConfig, type ClientMetricsSnapshot, Codec, Consumer, type ConsumerConfig, type ConsumerInfo, CronBuilder, type CronContext, CronHandle, type CronHandler, type DecodedTask, type DeleteStreamOpts, DeliverPolicy, type Encoding, ErrorCode, type ErrorCodeValue, type FieldType, type FieldTypeMap, type FlushConfig, type InferSchema, type JournalConfig, JournalType, JsonCodec, type LazyMessage, type LogFn, type Logger, Message, type PublishOpts, type ReconnectConfig, type Schema, type StepContext, type StepHandler, type StepResult, Stream, type StreamConfig, type StreamInfo, StringCodec, type SubjectInflightLimit, type SubscribeOptions, Subscription, type TlsConfig, Topic, WorkflowBuilder, WorkflowHandle, decodeJson, decodeString, encodeJson, encodeString, makeLazyMessage, schema, streamId, zodCodec };

package/dist/index.js

@@ -267,6 +267,7 @@ __export(index_exports, {
   AckPolicy: () => AckPolicy,
   ArbitroClient: () => ArbitroClient,
   ArbitroError: () => ArbitroError,
+  COMPENSATION_BIT: () => COMPENSATION_BIT,
   Codec: () => Codec,
   Consumer: () => Consumer,
   CronBuilder: () => CronBuilder,
@@ -280,6 +281,8 @@ __export(index_exports, {
   StringCodec: () => StringCodec,
   Subscription: () => Subscription,
   Topic: () => Topic,
+  WorkflowBuilder: () => WorkflowBuilder,
+  WorkflowHandle: () => WorkflowHandle,
   decodeJson: () => decodeJson,
   decodeString: () => decodeString,
   encodeJson: () => encodeJson,
@@ -1706,7 +1709,7 @@ var ArbitroClient = class {
   async createConsumerRaw(streamName, config) {
     const sid = await this.resolveStreamId(streamName);
     const name = Buffer.from(config.name ?? streamName);
-    const group = Buffer.from(config.name ?? streamName);
+    const group = Buffer.from(config.group ?? config.name ?? streamName);
     const filter = Buffer.from(config.filter ?? "");
     const ackPolicyByte = config.ackPolicy === "none" /* None */ ? 0 : 1;
     const opts = {
@@ -1916,6 +1919,257 @@ function streamId(name) {
   return h >>> 0;
 }
 
+// src/workflow/task.ts
+var TASK_HEADER = 7;
+var COMPENSATION_BIT = 32768;
+function encodeTask(instanceId, stepIndex, attempt, context) {
+  const buf = Buffer.allocUnsafe(TASK_HEADER + context.length);
+  buf.writeUInt32LE(instanceId, 0);
+  buf.writeUInt16LE(stepIndex, 4);
+  buf[6] = attempt;
+  context.copy(buf, TASK_HEADER);
+  return buf;
+}
+function decodeTask(payload) {
+  if (payload.length < TASK_HEADER) return void 0;
+  return {
+    instanceId: payload.readUInt32LE(0),
+    stepIndex: payload.readUInt16LE(4),
+    attempt: payload[6],
+    context: payload.subarray(TASK_HEADER)
+  };
+}
+
+// src/workflow/handle.ts
+var nextInstanceId = 1;
+function allocInstanceId() {
+  return nextInstanceId++;
+}
+var WorkflowHandle = class {
+  constructor(workflowName, taskStreamName, dlqStreamName, sub, triggerSub) {
+    this.workflowName = workflowName;
+    this.taskStreamName = taskStreamName;
+    this.dlqStreamName = dlqStreamName;
+    this.sub = sub;
+    this.triggerSub = triggerSub;
+  }
+  get name() {
+    return this.workflowName;
+  }
+  get taskStream() {
+    return this.taskStreamName;
+  }
+  get dlqStream() {
+    return this.dlqStreamName;
+  }
+  async trigger(client, context) {
+    const instanceId = allocInstanceId();
+    const msgId = `wf:${instanceId}:0:0`;
+    const subject = `_wf.${this.workflowName}.step.0`;
+    const task = encodeTask(instanceId, 0, 0, context);
+    await client.publish(this.taskStreamName, subject, task, { msgId });
+    return instanceId;
+  }
+};
+
+// src/workflow/processor.ts
+async function processMessage(cfg, msg) {
+  const task = decodeTask(msg.data());
+  if (!task) {
+    msg.ack();
+    return;
+  }
+  if (task.context.length > cfg.maxContextSize) {
+    msg.ack();
+    return;
+  }
+  const isCompensation = (task.stepIndex & COMPENSATION_BIT) !== 0;
+  if (isCompensation) {
+    await runCompensation(cfg, msg, task);
+    return;
+  }
+  if (task.stepIndex >= cfg.steps.length) {
+    msg.ack();
+    return;
+  }
+  await runStep(cfg, msg, task);
+}
+async function runCompensation(cfg, msg, task) {
+  const idx = task.stepIndex & ~COMPENSATION_BIT;
+  const comp = cfg.steps[idx]?.compensation;
+  if (comp) {
+    try {
+      await comp({ name: cfg.name, instanceId: task.instanceId, stepIndex: idx, attempt: task.attempt, context: task.context });
+    } catch {
+    }
+  }
+  msg.ack();
+}
+async function runStep(cfg, msg, task) {
+  const handler = cfg.steps[task.stepIndex].handler;
+  try {
+    const result = await handler({
+      name: cfg.name,
+      instanceId: task.instanceId,
+      stepIndex: task.stepIndex,
+      attempt: task.attempt,
+      context: task.context
+    });
+    if (result.context.length > cfg.maxContextSize) {
+      msg.nack();
+      return;
+    }
+    await advance(cfg, msg, task, result);
+  } catch (err) {
+    await onFailure(cfg, msg, task, err);
+  }
+}
+async function advance(cfg, msg, task, result) {
+  const nextStep = task.stepIndex + 1;
+  if (nextStep < cfg.steps.length) {
+    const msgId = `wf:${task.instanceId}:${nextStep}:0`;
+    const subject = `_wf.${cfg.name}.step.${nextStep}`;
+    const buf = encodeTask(task.instanceId, nextStep, 0, result.context);
+    await cfg.client.publish(cfg.taskStreamName, subject, buf, { msgId });
+  }
+  msg.ack();
+}
+async function onFailure(cfg, msg, task, err) {
+  if (task.attempt >= cfg.maxRetries) {
+    await publishDlq(cfg, task, err);
+    await publishCompensations(cfg, task);
+    msg.ack();
+  } else {
+    msg.nack();
+  }
+}
+async function publishDlq(cfg, task, err) {
+  const dlqSubject = `_wf.${cfg.name}.dlq.${task.stepIndex}`;
+  const errBytes = Buffer.from(String(err));
+  const buf = Buffer.allocUnsafe(7 + 4 + errBytes.length + task.context.length);
+  buf.writeUInt32LE(task.instanceId, 0);
+  buf.writeUInt16LE(task.stepIndex, 4);
+  buf[6] = task.attempt;
+  buf.writeUInt32LE(errBytes.length, 7);
+  errBytes.copy(buf, 11);
+  task.context.copy(buf, 11 + errBytes.length);
+  const msgId = `wf:${task.instanceId}:dlq:${task.stepIndex}`;
+  await cfg.client.publish(cfg.dlqStreamName, dlqSubject, buf, { msgId }).catch(() => {
+  });
+}
+async function publishCompensations(cfg, task) {
+  for (let i = task.stepIndex - 1; i >= 0; i--) {
+    const compStep = COMPENSATION_BIT | i;
+    const subject = `_wf.${cfg.name}.compensate.${i}`;
+    const buf = encodeTask(task.instanceId, compStep, 0, task.context);
+    const msgId = `wf:${task.instanceId}:comp:${i}`;
+    await cfg.client.publish(cfg.taskStreamName, subject, buf, { msgId }).catch(() => {
+    });
+  }
+}
+
+// src/workflow/workflow.ts
+var nextWorkerUid = 1;
+var WorkflowBuilder = class {
+  constructor(client, workflowName) {
+    this.client = client;
+    this.workflowName = workflowName;
+  }
+  triggerSubject;
+  triggerStreamName;
+  steps = [];
+  ackWaitMs = 3e4;
+  maxInflightVal = 10;
+  maxRetriesVal = 3;
+  maxContextSizeVal = 256 * 1024;
+  trigger(subject) {
+    this.triggerSubject = subject;
+    return this;
+  }
+  triggerStream(streamName) {
+    this.triggerStreamName = streamName;
+    return this;
+  }
+  step(name, handler) {
+    this.steps.push({ name, handler, compensation: void 0 });
+    return this;
+  }
+  /** Compensation handler for the most recently added step. */
+  compensate(_stepName, handler) {
+    const last = this.steps[this.steps.length - 1];
+    if (last) last.compensation = handler;
+    return this;
+  }
+  ackWait(ms) {
+    this.ackWaitMs = ms;
+    return this;
+  }
+  inflight(n) {
+    this.maxInflightVal = n;
+    return this;
+  }
+  maxRetries(n) {
+    this.maxRetriesVal = n;
+    return this;
+  }
+  maxContextSize(bytes) {
+    this.maxContextSizeVal = bytes;
+    return this;
+  }
+  async start() {
+    if (!this.triggerSubject) throw new Error("trigger subject required");
+    if (this.steps.length === 0) throw new Error("at least one step required");
+    const name = this.workflowName;
+    const taskStream = `_wf.${name}.tasks`;
+    const taskSubject = `_wf.${name}.>`;
+    const dlqStream = `_wf.${name}.dlq`;
+    const dlqSubject = `_wf.${name}.dlq.>`;
+    await this.client.upsertStream(taskStream, { subjectFilter: taskSubject, idempotencyWindowMs: 3e5 });
+    await this.client.upsertStream(dlqStream, { subjectFilter: dlqSubject });
+    const cfg = {
+      client: this.client,
+      name,
+      taskStreamName: taskStream,
+      dlqStreamName: dlqStream,
+      steps: this.steps,
+      maxContextSize: this.maxContextSizeVal,
+      maxRetries: this.maxRetriesVal
+    };
+    const sub = await this.subscribeWorker(cfg, taskStream, taskSubject);
+    const triggerSub = await this.subscribeTrigger(taskStream, name);
+    return new WorkflowHandle(name, taskStream, dlqStream, sub, triggerSub);
+  }
+  async subscribeWorker(cfg, taskStream, taskSubject) {
+    const uid = nextWorkerUid++;
+    return this.client.subscribe(taskStream, {
+      name: `_wf_${cfg.name}_w${uid}`,
+      group: `_wf_${cfg.name}_workers`,
+      filter: taskSubject,
+      ackPolicy: "explicit" /* Explicit */,
+      ackWaitMs: this.ackWaitMs,
+      maxAckPending: this.maxInflightVal
+    }, (msg) => {
+      void processMessage(cfg, msg);
+    });
+  }
+  async subscribeTrigger(taskStream, name) {
+    if (!this.triggerSubject || !this.triggerStreamName) return void 0;
+    const subject = this.triggerSubject;
+    return this.client.subscribe(this.triggerStreamName, {
+      name: `_wf_${name}_trigger`,
+      filter: subject,
+      ackPolicy: "explicit" /* Explicit */,
+      ackWaitMs: this.ackWaitMs,
+      maxAckPending: 1
+    }, async (msg) => {
+      const id = allocInstanceId();
+      const taskBuf = encodeTask(id, 0, 0, msg.data());
+      await this.client.publish(taskStream, `_wf.${name}.step.0`, taskBuf, { msgId: `wf:${id}:0:0` });
+      msg.ack();
+    });
+  }
+};
+
 // src/utils/zod.ts
 var import_msgpackr2 = require("msgpackr");
 var packr = new import_msgpackr2.Packr({ structuredClone: false, useRecords: false });
@@ -1937,6 +2191,7 @@ function zodCodec(zodSchema) {
   AckPolicy,
   ArbitroClient,
   ArbitroError,
+  COMPENSATION_BIT,
   Codec,
   Consumer,
   CronBuilder,
@@ -1950,6 +2205,8 @@ function zodCodec(zodSchema) {
   StringCodec,
   Subscription,
   Topic,
+  WorkflowBuilder,
+  WorkflowHandle,
   decodeJson,
   decodeString,
   encodeJson,