@arbitro/client 0.2.0 → 0.5.0

package/dist/index.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,14 +30,248 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/proto/constants.ts
+var constants_exports = {};
+__export(constants_exports, {
+  Action: () => Action,
+  CURRENT_VERSION: () => CURRENT_VERSION,
+  Cap: () => Cap,
+  EntryFlag: () => EntryFlag,
+  Flag: () => Flag,
+  HEADER_SIZE: () => HEADER_SIZE,
+  HELLO_SIZE: () => HELLO_SIZE,
+  MAGIC_V2: () => MAGIC_V2,
+  OFF_ACTION: () => OFF_ACTION,
+  OFF_ENTRY_FLAGS: () => OFF_ENTRY_FLAGS,
+  OFF_FLAGS: () => OFF_FLAGS,
+  OFF_MSG_LEN: () => OFF_MSG_LEN,
+  OFF_SEQ: () => OFF_SEQ,
+  Role: () => Role
+});
+var MAGIC_V2, HELLO_SIZE, CURRENT_VERSION, Role, Cap, HEADER_SIZE, OFF_ACTION, OFF_FLAGS, OFF_ENTRY_FLAGS, OFF_MSG_LEN, OFF_SEQ, Flag, EntryFlag, Action;
+var init_constants = __esm({
+  "src/proto/constants.ts"() {
+    "use strict";
+    MAGIC_V2 = 843207233;
+    HELLO_SIZE = 8;
+    CURRENT_VERSION = 2;
+    Role = /* @__PURE__ */ ((Role2) => {
+      Role2[Role2["Client"] = 0] = "Client";
+      Role2[Role2["Server"] = 1] = "Server";
+      return Role2;
+    })(Role || {});
+    Cap = /* @__PURE__ */ ((Cap2) => {
+      Cap2[Cap2["Headers"] = 1] = "Headers";
+      Cap2[Cap2["Reply"] = 2] = "Reply";
+      Cap2[Cap2["BatchHeaders"] = 4] = "BatchHeaders";
+      Cap2[Cap2["CompressedPayload"] = 8] = "CompressedPayload";
+      return Cap2;
+    })(Cap || {});
+    HEADER_SIZE = 16;
+    OFF_ACTION = 0;
+    OFF_FLAGS = 2;
+    OFF_ENTRY_FLAGS = 3;
+    OFF_MSG_LEN = 4;
+    OFF_SEQ = 8;
+    Flag = /* @__PURE__ */ ((Flag3) => {
+      Flag3[Flag3["None"] = 0] = "None";
+      Flag3[Flag3["AckReq"] = 1] = "AckReq";
+      Flag3[Flag3["Dup"] = 2] = "Dup";
+      Flag3[Flag3["PriorityHigh"] = 4] = "PriorityHigh";
+      return Flag3;
+    })(Flag || {});
+    EntryFlag = /* @__PURE__ */ ((EntryFlag2) => {
+      EntryFlag2[EntryFlag2["None"] = 0] = "None";
+      EntryFlag2[EntryFlag2["Retain"] = 1] = "Retain";
+      EntryFlag2[EntryFlag2["Compressed"] = 2] = "Compressed";
+      EntryFlag2[EntryFlag2["NoBackpressure"] = 4] = "NoBackpressure";
+      return EntryFlag2;
+    })(EntryFlag || {});
+    Action = /* @__PURE__ */ ((Action2) => {
+      Action2[Action2["Hello"] = 1] = "Hello";
+      Action2[Action2["Auth"] = 2] = "Auth";
+      Action2[Action2["Publish"] = 257] = "Publish";
+      Action2[Action2["PublishAccumulate"] = 258] = "PublishAccumulate";
+      Action2[Action2["PublishBatch"] = 259] = "PublishBatch";
+      Action2[Action2["PublishWithReply"] = 260] = "PublishWithReply";
+      Action2[Action2["PublishWithHeaders"] = 261] = "PublishWithHeaders";
+      Action2[Action2["PublishBatchWithHeaders"] = 262] = "PublishBatchWithHeaders";
+      Action2[Action2["Deliver"] = 512] = "Deliver";
+      Action2[Action2["Ack"] = 513] = "Ack";
+      Action2[Action2["Nack"] = 514] = "Nack";
+      Action2[Action2["RepOk"] = 515] = "RepOk";
+      Action2[Action2["RepError"] = 516] = "RepError";
+      Action2[Action2["RepBatch"] = 517] = "RepBatch";
+      Action2[Action2["BatchAck"] = 518] = "BatchAck";
+      Action2[Action2["FanoutBatch"] = 519] = "FanoutBatch";
+      Action2[Action2["AckSync"] = 520] = "AckSync";
+      Action2[Action2["BatchAckSync"] = 521] = "BatchAckSync";
+      Action2[Action2["BatchNack"] = 522] = "BatchNack";
+      Action2[Action2["Subscribe"] = 769] = "Subscribe";
+      Action2[Action2["Unsubscribe"] = 770] = "Unsubscribe";
+      Action2[Action2["CreateStream"] = 1025] = "CreateStream";
+      Action2[Action2["DeleteStream"] = 1026] = "DeleteStream";
+      Action2[Action2["GetStream"] = 1027] = "GetStream";
+      Action2[Action2["ListStreams"] = 1028] = "ListStreams";
+      Action2[Action2["PurgeStream"] = 1029] = "PurgeStream";
+      Action2[Action2["DrainSubject"] = 1030] = "DrainSubject";
+      Action2[Action2["CreateConsumer"] = 1281] = "CreateConsumer";
+      Action2[Action2["DeleteConsumer"] = 1282] = "DeleteConsumer";
+      Action2[Action2["GetConsumer"] = 1283] = "GetConsumer";
+      Action2[Action2["ListConsumers"] = 1284] = "ListConsumers";
+      Action2[Action2["ConsumerStats"] = 1285] = "ConsumerStats";
+      Action2[Action2["PauseConsumer"] = 1286] = "PauseConsumer";
+      Action2[Action2["ResumeConsumer"] = 1287] = "ResumeConsumer";
+      Action2[Action2["PublishDelayed"] = 2049] = "PublishDelayed";
+      Action2[Action2["Ping"] = 1537] = "Ping";
+      Action2[Action2["Pong"] = 1538] = "Pong";
+      Action2[Action2["Connect"] = 1539] = "Connect";
+      Action2[Action2["Connected"] = 1540] = "Connected";
+      Action2[Action2["Disconnect"] = 1541] = "Disconnect";
+      Action2[Action2["CreateCron"] = 1793] = "CreateCron";
+      Action2[Action2["DeleteCron"] = 1794] = "DeleteCron";
+      Action2[Action2["ListCrons"] = 1795] = "ListCrons";
+      Action2[Action2["CronFire"] = 1796] = "CronFire";
+      Action2[Action2["CronAck"] = 1797] = "CronAck";
+      return Action2;
+    })(Action || {});
+  }
+});
+
+// src/proto/frame.ts
+function frame(action, seq, bodyLen, flags = 0, entryFlags = 0) {
+  const buf = Buffer.allocUnsafe(HEADER_SIZE + bodyLen);
+  buf.writeUInt16LE(action, OFF_ACTION);
+  buf[OFF_FLAGS] = flags;
+  buf[OFF_ENTRY_FLAGS] = entryFlags;
+  buf.writeUInt32LE(bodyLen, OFF_MSG_LEN);
+  buf.writeBigUInt64LE(seq, OFF_SEQ);
+  return buf;
+}
+function packHello(caps = 2 /* Reply */) {
+  const buf = Buffer.allocUnsafe(HELLO_SIZE);
+  buf.writeUInt32LE(MAGIC_V2, 0);
+  buf[4] = CURRENT_VERSION;
+  buf[5] = 0 /* Client */;
+  buf.writeUInt16LE(caps, 6);
+  return buf;
+}
+function packDisconnect(seq) {
+  return frame(1541 /* Disconnect */, seq, 0);
+}
+var init_frame = __esm({
+  "src/proto/frame.ts"() {
+    "use strict";
+    init_constants();
+  }
+});
+
+// src/proto/publish.ts
+var publish_exports = {};
+__export(publish_exports, {
+  packPublish: () => packPublish,
+  packPublishBatch: () => packPublishBatch,
+  packPublishDelayed: () => packPublishDelayed,
+  packPublishWithReply: () => packPublishWithReply
+});
+function packPublish(seq, streamId2, subject, payload, flags = 0, entryFlags = 0, msgId = EMPTY) {
+  const buf = frame(
+    257 /* Publish */,
+    seq,
+    8 + subject.length + msgId.length + payload.length,
+    flags,
+    entryFlags
+  );
+  buf.writeUInt32LE(streamId2, HEADER_SIZE);
+  buf.writeUInt16LE(subject.length, HEADER_SIZE + 4);
+  buf.writeUInt16LE(msgId.length, HEADER_SIZE + 6);
+  let off = HEADER_SIZE + 8;
+  subject.copy(buf, off);
+  off += subject.length;
+  msgId.copy(buf, off);
+  off += msgId.length;
+  payload.copy(buf, off);
+  return buf;
+}
+function packPublishWithReply(seq, streamId2, subject, replyTo, payload, flags = 0, entryFlags = 0) {
+  const tail = subject.length + replyTo.length + payload.length;
+  const buf = frame(260 /* PublishWithReply */, seq, 12 + tail, flags, entryFlags);
+  buf.writeUInt32LE(streamId2, HEADER_SIZE);
+  buf.writeUInt16LE(subject.length, HEADER_SIZE + 4);
+  buf.writeUInt16LE(replyTo.length, HEADER_SIZE + 6);
+  buf.writeUInt32LE(0, HEADER_SIZE + 8);
+  let off = HEADER_SIZE + 12;
+  subject.copy(buf, off);
+  off += subject.length;
+  replyTo.copy(buf, off);
+  off += replyTo.length;
+  payload.copy(buf, off);
+  return buf;
+}
+function packPublishDelayed(seq, streamId2, subject, payload, delayMs, flags = 0, entryFlags = 0) {
+  const buf = frame(
+    2049 /* PublishDelayed */,
+    seq,
+    16 + subject.length + payload.length,
+    flags,
+    entryFlags
+  );
+  buf.writeUInt32LE(streamId2, HEADER_SIZE);
+  buf.writeUInt16LE(subject.length, HEADER_SIZE + 4);
+  buf.writeUInt16LE(0, HEADER_SIZE + 6);
+  buf.writeBigUInt64LE(delayMs, HEADER_SIZE + 8);
+  let off = HEADER_SIZE + 16;
+  subject.copy(buf, off);
+  off += subject.length;
+  payload.copy(buf, off);
+  return buf;
+}
+function packPublishBatch(seq, streamId2, entries, flags = 0, entryFlags = 0) {
+  let tail = 0;
+  for (const e of entries) {
+    const midLen = e.msgId ? e.msgId.length : 0;
+    tail += 8 + e.subject.length + midLen + e.payload.length;
+  }
+  const buf = frame(259 /* PublishBatch */, seq, 8 + tail, flags, entryFlags);
+  buf.writeUInt32LE(streamId2, HEADER_SIZE);
+  buf.writeUInt32LE(entries.length, HEADER_SIZE + 4);
+  let off = HEADER_SIZE + 8;
+  for (const e of entries) {
+    const mid = e.msgId ?? EMPTY;
+    buf.writeUInt16LE(e.subject.length, off);
+    buf.writeUInt16LE(mid.length, off + 2);
+    buf.writeUInt32LE(e.payload.length, off + 4);
+    off += 8;
+    buf.write(e.subject, off);
+    off += e.subject.length;
+    mid.copy(buf, off);
+    off += mid.length;
+    e.payload.copy(buf, off);
+    off += e.payload.length;
+  }
+  return buf;
+}
+var EMPTY;
+var init_publish = __esm({
+  "src/proto/publish.ts"() {
+    "use strict";
+    init_constants();
+    init_frame();
+    EMPTY = Buffer.alloc(0);
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   AckPolicy: () => AckPolicy,
   ArbitroClient: () => ArbitroClient,
   ArbitroError: () => ArbitroError,
+  COMPENSATION_BIT: () => COMPENSATION_BIT,
   Codec: () => Codec,
   Consumer: () => Consumer,
+  CronBuilder: () => CronBuilder,
+  CronHandle: () => CronHandle,
   DeliverPolicy: () => DeliverPolicy,
   ErrorCode: () => ErrorCode,
   JournalType: () => JournalType,
@@ -44,6 +281,8 @@ __export(index_exports, {
   StringCodec: () => StringCodec,
   Subscription: () => Subscription,
   Topic: () => Topic,
+  WorkflowBuilder: () => WorkflowBuilder,
+  WorkflowHandle: () => WorkflowHandle,
   decodeJson: () => decodeJson,
   decodeString: () => decodeString,
   encodeJson: () => encodeJson,
@@ -234,102 +473,16 @@ function makeLazyMessage(raw, codec, fields, onAck, onNack, onNackDelay) {
   return msg;
 }
 
-// src/proto/constants.ts
-var MAGIC_V2 = 843207233;
-var HELLO_SIZE = 8;
-var CURRENT_VERSION = 2;
-var HEADER_SIZE = 16;
-var OFF_ACTION = 0;
-var OFF_FLAGS = 2;
-var OFF_ENTRY_FLAGS = 3;
-var OFF_MSG_LEN = 4;
-var OFF_SEQ = 8;
-
-// src/proto/frame.ts
-function frame(action, seq, bodyLen, flags = 0, entryFlags = 0) {
-  const buf = Buffer.allocUnsafe(HEADER_SIZE + bodyLen);
-  buf.writeUInt16LE(action, OFF_ACTION);
-  buf[OFF_FLAGS] = flags;
-  buf[OFF_ENTRY_FLAGS] = entryFlags;
-  buf.writeUInt32LE(bodyLen, OFF_MSG_LEN);
-  buf.writeBigUInt64LE(seq, OFF_SEQ);
-  return buf;
-}
-function packHello(caps = 2 /* Reply */) {
-  const buf = Buffer.allocUnsafe(HELLO_SIZE);
-  buf.writeUInt32LE(MAGIC_V2, 0);
-  buf[4] = CURRENT_VERSION;
-  buf[5] = 0 /* Client */;
-  buf.writeUInt16LE(caps, 6);
-  return buf;
-}
-function packDisconnect(seq) {
-  return frame(1541 /* Disconnect */, seq, 0);
-}
+// src/message/message.ts
+init_constants();
 
-// src/proto/publish.ts
-var EMPTY = Buffer.alloc(0);
-function packPublish(seq, streamId2, subject, payload, flags = 0, entryFlags = 0, msgId = EMPTY) {
-  const buf = frame(
-    257 /* Publish */,
-    seq,
-    8 + subject.length + msgId.length + payload.length,
-    flags,
-    entryFlags
-  );
-  buf.writeUInt32LE(streamId2, HEADER_SIZE);
-  buf.writeUInt16LE(subject.length, HEADER_SIZE + 4);
-  buf.writeUInt16LE(msgId.length, HEADER_SIZE + 6);
-  let off = HEADER_SIZE + 8;
-  subject.copy(buf, off);
-  off += subject.length;
-  msgId.copy(buf, off);
-  off += msgId.length;
-  payload.copy(buf, off);
-  return buf;
-}
-function packPublishWithReply(seq, streamId2, subject, replyTo, payload, flags = 0, entryFlags = 0) {
-  const tail = subject.length + replyTo.length + payload.length;
-  const buf = frame(260 /* PublishWithReply */, seq, 12 + tail, flags, entryFlags);
-  buf.writeUInt32LE(streamId2, HEADER_SIZE);
-  buf.writeUInt16LE(subject.length, HEADER_SIZE + 4);
-  buf.writeUInt16LE(replyTo.length, HEADER_SIZE + 6);
-  buf.writeUInt32LE(0, HEADER_SIZE + 8);
-  let off = HEADER_SIZE + 12;
-  subject.copy(buf, off);
-  off += subject.length;
-  replyTo.copy(buf, off);
-  off += replyTo.length;
-  payload.copy(buf, off);
-  return buf;
-}
-function packPublishBatch(seq, streamId2, entries, flags = 0, entryFlags = 0) {
-  let tail = 0;
-  for (const e of entries) {
-    const midLen = e.msgId ? e.msgId.length : 0;
-    tail += 8 + e.subject.length + midLen + e.payload.length;
-  }
-  const buf = frame(259 /* PublishBatch */, seq, 8 + tail, flags, entryFlags);
-  buf.writeUInt32LE(streamId2, HEADER_SIZE);
-  buf.writeUInt32LE(entries.length, HEADER_SIZE + 4);
-  let off = HEADER_SIZE + 8;
-  for (const e of entries) {
-    const mid = e.msgId ?? EMPTY;
-    buf.writeUInt16LE(e.subject.length, off);
-    buf.writeUInt16LE(mid.length, off + 2);
-    buf.writeUInt32LE(e.payload.length, off + 4);
-    off += 8;
-    buf.write(e.subject, off);
-    off += e.subject.length;
-    mid.copy(buf, off);
-    off += mid.length;
-    e.payload.copy(buf, off);
-    off += e.payload.length;
-  }
-  return buf;
-}
+// src/proto/v2.ts
+init_frame();
+init_publish();
 
 // src/proto/delivery.ts
+init_constants();
+init_frame();
 function packCold(action, seq, body) {
   const utf8 = Buffer.from(JSON.stringify(body), "utf8");
   const buf = frame(action, seq, utf8.length);
@@ -376,6 +529,8 @@ function packBatchNack(seq, consumerId, entries) {
 }
 
 // src/proto/manage.ts
+init_constants();
+init_frame();
 function packCold2(action, seq, body) {
   const utf8 = Buffer.from(JSON.stringify(body), "utf8");
   const buf = frame(action, seq, utf8.length);
@@ -583,6 +738,7 @@ var net = __toESM(require("net"));
 var tls = __toESM(require("tls"));
 
 // src/proto/framer.ts
+init_constants();
 var ENVELOPE_MSG_LEN_OFF = 8;
 var Framer = class {
   buf = Buffer.allocUnsafe(65536);
@@ -614,6 +770,9 @@ var Framer = class {
   }
 };
 
+// src/net/connection.ts
+init_constants();
+
 // src/common/logger.ts
 var noop = (() => {
 });
@@ -629,6 +788,39 @@ function resolveLogger(logger) {
   return logger ?? NOOP;
 }
 
+// src/cron/cron-frame.ts
+init_constants();
+init_frame();
+function packCreateCron(seq, body) {
+  const json = Buffer.from(JSON.stringify(body), "utf8");
+  const buf = frame(1793 /* CreateCron */, seq, json.length);
+  json.copy(buf, HEADER_SIZE);
+  return buf;
+}
+function packDeleteCron(seq, name) {
+  const buf = frame(1794 /* DeleteCron */, seq, name.length);
+  name.copy(buf, HEADER_SIZE);
+  return buf;
+}
+var CRON_FIRE_FIXED = 2 + 8 + 8;
+function decodeCronFire(body) {
+  if (body.length < CRON_FIRE_FIXED) return void 0;
+  const nameLen = body.readUInt16LE(0);
+  if (body.length < CRON_FIRE_FIXED + nameLen) return void 0;
+  const fireTimeMs = body.readBigUInt64LE(2);
+  const fireCount = body.readBigUInt64LE(10);
+  const name = body.subarray(18, 18 + nameLen).toString();
+  return { name, fireTimeMs, fireCount };
+}
+function packCronAck(seq, name, ok) {
+  const bodyLen = 3 + name.length;
+  const buf = frame(1797 /* CronAck */, seq, bodyLen);
+  buf.writeUInt16LE(name.length, HEADER_SIZE);
+  buf[HEADER_SIZE + 2] = ok ? 0 : 1;
+  name.copy(buf, HEADER_SIZE + 3);
+  return buf;
+}
+
 // src/net/connection.ts
 function parseAddr(addr) {
   const i = addr.lastIndexOf(":");
@@ -652,6 +844,7 @@ var Connection = class _Connection {
   log;
   activeSubs = /* @__PURE__ */ new Map();
   metrics;
+  cronState;
   attachSocket(socket) {
     socket.setNoDelay(true);
     socket.on("data", (chunk) => this.framer.push(chunk, (f) => this.onFrame(f)));
@@ -706,6 +899,10 @@ var Connection = class _Connection {
   setMetrics(m) {
     this.metrics = m;
   }
+  /** Attach cron state so the connection can dispatch CronFire frames. */
+  setCronState(s) {
+    this.cronState = s;
+  }
   // ── Frame routing ─────────────────────────────────────────────────────────
   // Seq-based dispatch: match reply.header.seq → pending request. O(1).
   resolvePending(frame2) {
@@ -757,6 +954,10 @@ var Connection = class _Connection {
         this.handleBatchDeliver(frame2);
         return;
       }
+      case 1796 /* CronFire */: {
+        this.dispatchCronFire(frame2);
+        return;
+      }
       case 1538 /* Pong */:
         return;
       default: {
@@ -806,6 +1007,19 @@ var Connection = class _Connection {
       off = tailEnd;
     }
   }
+  // ── Cron dispatch ──────────────────────────────────────────────────────────
+  dispatchCronFire(frame2) {
+    const body = frame2.subarray(HEADER_SIZE);
+    const view = decodeCronFire(body);
+    if (!view) return;
+    const handler = this.cronState?.getHandler(view.name);
+    const nameBuf = Buffer.from(view.name);
+    if (!handler) {
+      this.send(packCronAck(this.nextSeq(), nameBuf, false));
+      return;
+    }
+    handler({ name: view.name, fireTime: view.fireTimeMs, fireCount: view.fireCount }).then(() => this.send(packCronAck(this.nextSeq(), nameBuf, true))).catch(() => this.send(packCronAck(this.nextSeq(), nameBuf, false)));
+  }
   // ── Subscriptions ─────────────────────────────────────────────────────────
   async sendSubscribeV2(consumerId, filter, handler, onRenew) {
     return new Promise((resolve, reject) => {
@@ -848,6 +1062,14 @@ var Connection = class _Connection {
       }).catch(() => {
       });
     }
+    this.replayCrons();
+  }
+  replayCrons() {
+    if (!this.cronState) return;
+    for (const { config } of this.cronState.allConfigs()) {
+      const seq = this.nextSeq();
+      this.socket.write(packCreateCron(seq, config));
+    }
   }
   // ── Routes (internal use) ─────────────────────────────────────────────────
   registerRoute(consumerId, handler) {
@@ -1131,6 +1353,7 @@ var ClientMetrics = class {
 };
 
 // src/stream/publish.ts
+init_constants();
 var EMPTY2 = Buffer.alloc(0);
 function toMsgIdBuf(id) {
   if (id == null) return EMPTY2;
@@ -1162,6 +1385,89 @@ async function streamRequest(conn, sid, subject, data, timeoutMs) {
   return Buffer.alloc(0);
 }
 
+// src/client/client.ts
+init_constants();
+
+// src/cron/cron-builder.ts
+var CronBuilder = class {
+  constructor(conn, cronState, cronName) {
+    this.conn = conn;
+    this.cronState = cronState;
+    this.cronName = cronName;
+  }
+  expr;
+  timezone;
+  timeoutMs = 3e4;
+  allowOverlap = false;
+  every(expression) {
+    this.expr = expression;
+    return this;
+  }
+  tz(timezone) {
+    this.timezone = timezone;
+    return this;
+  }
+  timeout(ms) {
+    this.timeoutMs = ms;
+    return this;
+  }
+  overlap(allow) {
+    this.allowOverlap = allow;
+    return this;
+  }
+  async run(handler) {
+    if (!this.expr) throw new Error("cron expression required \u2014 call .every()");
+    const body = {
+      name: this.cronName,
+      every: this.expr,
+      tz: this.timezone,
+      timeout_ms: this.timeoutMs,
+      overlap: this.allowOverlap
+    };
+    const seq = this.conn.nextSeq();
+    await this.conn.sendExpectReply(packCreateCron(seq, body));
+    this.cronState.register(this.cronName, body, handler);
+    return new CronHandle(this.conn, this.cronState, this.cronName);
+  }
+};
+var CronHandle = class {
+  constructor(conn, cronState, cronName) {
+    this.conn = conn;
+    this.cronState = cronState;
+    this.cronName = cronName;
+  }
+  get name() {
+    return this.cronName;
+  }
+  async stop() {
+    const nameBuf = Buffer.from(this.cronName);
+    const seq = this.conn.nextSeq();
+    await this.conn.sendExpectReply(packDeleteCron(seq, nameBuf));
+    this.cronState.remove(this.cronName);
+  }
+};
+
+// src/cron/cron-state.ts
+var CronState = class {
+  handlers = /* @__PURE__ */ new Map();
+  register(name, config, handler) {
+    this.handlers.set(name, { handler, config });
+  }
+  remove(name) {
+    this.handlers.delete(name);
+  }
+  getHandler(name) {
+    return this.handlers.get(name)?.handler;
+  }
+  allConfigs() {
+    const out = [];
+    for (const [name, entry] of this.handlers) {
+      out.push({ name, config: entry.config });
+    }
+    return out;
+  }
+};
+
 // src/client/client.ts
 var DEFAULT_CONFIG = {
   servers: ["127.0.0.1:9898"],
@@ -1176,6 +1482,7 @@ var ArbitroClient = class {
   logger;
   sidCache = /* @__PURE__ */ new Map();
   _metrics = new ClientMetrics();
+  _cronState = new CronState();
   constructor(config) {
     this.cfg = { ...DEFAULT_CONFIG, ...config };
     this.tls = config.tls;
@@ -1192,6 +1499,7 @@ var ArbitroClient = class {
       this.logger
     );
     this.conn.setMetrics(this._metrics);
+    this.conn.setCronState(this._cronState);
     return this;
   }
   /**
@@ -1277,6 +1585,22 @@ var ArbitroClient = class {
     const sid = await this.resolveStreamId(streamName);
     return streamRequest(this.conn, sid, subject, data, timeoutMs);
   }
+  /**
+   * Publish a message with a delivery delay. The broker parks the message
+   * in its delayed journal and delivers it to consumers after `delayMs`
+   * milliseconds. Returns a Promise that resolves once the broker confirms
+   * receipt.
+   */
+  async publishDelayed(streamName, subject, data, delayMs) {
+    const sid = await this.resolveStreamId(streamName);
+    const { packPublishDelayed: packPublishDelayed2 } = await Promise.resolve().then(() => (init_publish(), publish_exports));
+    const { Flag: Flag3 } = await Promise.resolve().then(() => (init_constants(), constants_exports));
+    const subj = Buffer.from(this.prefixed(subject));
+    await this.conn.sendExpectReply(
+      packPublishDelayed2(this.conn.nextSeq(), sid, subj, data, BigInt(delayMs), Flag3.AckReq)
+    );
+    this._metrics.publishesSent++;
+  }
   async subscribe(streamName, configOrCb, callbackOrOpts, opts) {
     let config;
     let callback;
@@ -1385,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 = {
@@ -1396,7 +1720,7 @@ var ArbitroClient = class {
       maxInflight: config.maxAckPending ?? 0,
       ackPolicy: ackPolicyByte,
       deliverPolicy: deliverPolicyToU8(config.deliverPolicy),
-      deliverMode: config.fanout ? 1 : 0,
+      deliverMode: config.fanout ? 0 : 1,
       ackWaitMs: config.ackWaitMs ?? 0,
       startSeq: BigInt(config.startSeq ?? 0)
     };
@@ -1511,6 +1835,11 @@ var ArbitroClient = class {
   stream(name, config) {
     return new Stream(this, name, config);
   }
+  // ── Cron ──────────────────────────────────────────────────────────────────
+  /** Start building a cron job. Call `.every()` then `.run()` to register. */
+  cron(name) {
+    return new CronBuilder(this.conn, this._cronState, name);
+  }
   // ── Lifecycle ─────────────────────────────────────────────────────────────
   async close() {
     await this.conn.close();
@@ -1590,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 });
@@ -1611,8 +2191,11 @@ function zodCodec(zodSchema) {
   AckPolicy,
   ArbitroClient,
   ArbitroError,
+  COMPENSATION_BIT,
   Codec,
   Consumer,
+  CronBuilder,
+  CronHandle,
   DeliverPolicy,
   ErrorCode,
   JournalType,
@@ -1622,6 +2205,8 @@ function zodCodec(zodSchema) {
   StringCodec,
   Subscription,
   Topic,
+  WorkflowBuilder,
+  WorkflowHandle,
   decodeJson,
   decodeString,
   encodeJson,