@arbitro/client 0.4.1 → 0.5.2

package/README.md

@@ -111,6 +111,11 @@ await client.upsertConsumer('orders', { name: 'workers', filter: 'orders.>' })
 await client.deleteConsumer('workers')
 await client.deleteStream('orders')                        // default: delete metadata + data
 await client.deleteStream('orders', { deleteData: false }) // preserve journal bytes
+
+// Per-message deletion (tombstones a single message by sequence number)
+await client.deleteMessage('orders', 42n)                  // true if deleted, false if not found/already deleted
+await stream.deleteMessage(42n)                            // convenience — delegates to client.deleteMessage
+await consumer.deleteMessage(42n)                          // convenience — delegates to client.deleteMessage
 ```
 
 ## Stream / consumer sugar
@@ -248,6 +253,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:
@@ -271,6 +344,10 @@ npm run test:integration   # requires Docker
 - `.agent/rules/*.md` — internal coding rules (hot-path discipline, wire protocol, etc.).
 - `CLAUDE.md` — index pointing at the rule files.
 
+## Replication
+
+Replication is transparent to the client -- `replicas` is set at `create_stream` time. The client publishes normally; the broker handles replication internally.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

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

@@ -62,6 +62,7 @@ var Action = /* @__PURE__ */ ((Action2) => {
   Action2[Action2["ListStreams"] = 1028] = "ListStreams";
   Action2[Action2["PurgeStream"] = 1029] = "PurgeStream";
   Action2[Action2["DrainSubject"] = 1030] = "DrainSubject";
+  Action2[Action2["DeleteMessage"] = 1031] = "DeleteMessage";
   Action2[Action2["CreateConsumer"] = 1281] = "CreateConsumer";
   Action2[Action2["DeleteConsumer"] = 1282] = "DeleteConsumer";
   Action2[Action2["GetConsumer"] = 1283] = "GetConsumer";
@@ -99,4 +100,4 @@ export {
   EntryFlag,
   Action
 };
-//# sourceMappingURL=chunk-6BCX2E2R.mjs.map
+//# sourceMappingURL=chunk-3EHQPPLU.mjs.map

package/dist/chunk-3EHQPPLU.mjs.map

@@ -0,0 +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  DeleteMessage = 0x0407,\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-BSPQZJHF.mjs}

@@ -8,7 +8,7 @@ import {
   OFF_FLAGS,
   OFF_MSG_LEN,
   OFF_SEQ
-} from "./chunk-6BCX2E2R.mjs";
+} from "./chunk-3EHQPPLU.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-BSPQZJHF.mjs.map

package/dist/{constants-KF57DJ2L.mjs → constants-LWTWKOBZ.mjs}

@@ -13,7 +13,7 @@ import {
   OFF_MSG_LEN,
   OFF_SEQ,
   Role
-} from "./chunk-6BCX2E2R.mjs";
+} from "./chunk-3EHQPPLU.mjs";
 export {
   Action,
   CURRENT_VERSION,
@@ -30,4 +30,4 @@ export {
   OFF_SEQ,
   Role
 };
-//# sourceMappingURL=constants-KF57DJ2L.mjs.map
+//# sourceMappingURL=constants-LWTWKOBZ.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. */
@@ -461,6 +463,8 @@ declare class Consumer {
      * from `streamName + name`. Equivalent of NATS `num_ack_pending`.
      */
     getPendings(): Promise<number>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     subscribe(cb?: RawCallback, opts?: SubscribeOptions): Promise<Subscription>;
     subscribe<T extends Record<string, unknown>>(codec: Encoding<T>, cb: (msg: LazyMessage<T>) => void, opts?: SubscribeOptions): Promise<Subscription>;
 }
@@ -572,6 +576,14 @@ declare class ArbitroClient {
     streamExists(name: string): Promise<boolean>;
     purgeStream(name: string): Promise<number>;
     drainSubject(streamName: string, subject: string): Promise<number>;
+    /**
+     * Tombstone a single message by sequence number.
+     *
+     * The broker marks the entry as deleted — it will never be delivered
+     * to any consumer. Returns `true` if the message was found and
+     * tombstoned, `false` if not found or already tombstoned.
+     */
+    deleteMessage(streamName: string, seq: bigint): Promise<boolean>;
     createConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
     private createConsumerRaw;
     upsertConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
@@ -636,6 +648,8 @@ declare class Stream {
      *  with the broker; the caller decides whether to wait via `await`. */
     publishBatch(messages: BatchPublishEntry[]): Promise<bigint>;
     request(subject: string, data: Buffer, timeoutMs?: number): Promise<Buffer>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     consumer(overrides?: Partial<ConsumerConfig>): Consumer;
     topic<T extends Record<string, unknown>>(subject: string, codec: Encoding<T>): Topic<T>;
 }
@@ -654,6 +668,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 +739,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. */
@@ -461,6 +463,8 @@ declare class Consumer {
      * from `streamName + name`. Equivalent of NATS `num_ack_pending`.
      */
     getPendings(): Promise<number>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     subscribe(cb?: RawCallback, opts?: SubscribeOptions): Promise<Subscription>;
     subscribe<T extends Record<string, unknown>>(codec: Encoding<T>, cb: (msg: LazyMessage<T>) => void, opts?: SubscribeOptions): Promise<Subscription>;
 }
@@ -572,6 +576,14 @@ declare class ArbitroClient {
     streamExists(name: string): Promise<boolean>;
     purgeStream(name: string): Promise<number>;
     drainSubject(streamName: string, subject: string): Promise<number>;
+    /**
+     * Tombstone a single message by sequence number.
+     *
+     * The broker marks the entry as deleted — it will never be delivered
+     * to any consumer. Returns `true` if the message was found and
+     * tombstoned, `false` if not found or already tombstoned.
+     */
+    deleteMessage(streamName: string, seq: bigint): Promise<boolean>;
     createConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
     private createConsumerRaw;
     upsertConsumer(streamName: string, config: ConsumerConfig): Promise<Consumer>;
@@ -636,6 +648,8 @@ declare class Stream {
      *  with the broker; the caller decides whether to wait via `await`. */
     publishBatch(messages: BatchPublishEntry[]): Promise<bigint>;
     request(subject: string, data: Buffer, timeoutMs?: number): Promise<Buffer>;
+    /** Tombstone a single message by seq. Returns true if found. */
+    deleteMessage(seq: bigint): Promise<boolean>;
     consumer(overrides?: Partial<ConsumerConfig>): Consumer;
     topic<T extends Record<string, unknown>>(subject: string, codec: Encoding<T>): Topic<T>;
 }
@@ -654,6 +668,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 +739,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 };