@nanobpm/urban-agent-client 0.1.0 → 0.1.4

package/dist/client.d.ts

@@ -31,6 +31,20 @@ export interface AgenticClientOptions {
     readonly serveTimeoutMs?: number;
     /** Reconnect/backoff policy. Enabled by default. */
     readonly reconnect?: ReconnectOptions;
+    /**
+     * The producer generation stamped on every `produce` relay frame. The hub's
+     * incarnation fence admits a frame only when its incarnation is `>=` the
+     * highest seen for that stream, so a successor producer (a retried job on a
+     * fresh runner taking over the same stream) MUST present a strictly higher
+     * value to fence its stale predecessor. Defaults to `Date.now()`, which a
+     * later-started process naturally exceeds — but that default is best-effort:
+     * clock skew, a backwards clock adjustment, or two restarts inside the same
+     * millisecond can break strict monotonicity. A caller that needs a hard
+     * fencing guarantee MUST supply an explicit monotonic `incarnation` (e.g. a
+     * persisted per-takeover counter) rather than rely on the clock. Must be a
+     * non-negative integer.
+     */
+    readonly incarnation?: number;
     /** Injectable scheduler for reconnect backoff (tests). Defaults to setTimeout. */
     readonly schedule?: (fn: () => void, ms: number) => void;
 }
@@ -62,6 +76,7 @@ export declare class AgenticClient {
     private readonly serveTimeoutMs;
     private readonly reconnectPolicy;
     private readonly schedule;
+    private readonly incarnation;
     private capability;
     private transport;
     private state;
@@ -73,7 +88,6 @@ export declare class AgenticClient {
     private heartbeatTimer;
     private pendingServe;
     private lastServe;
-    private readonly relayOffsets;
     private readonly serveListeners;
     private readonly frameListeners;
     private readonly openListeners;
@@ -106,9 +120,12 @@ export declare class AgenticClient {
     heartbeat(): void;
     /**
      * Produce relay bytes on the bulk lane. `chunk` is the terminal/command output
-     * for `stream`; the client tracks a monotonic per-stream byte offset so the
-     * hub-side ring can resume-from-offset after a consumer reconnect (S5). Bytes
-     * are UTF-8-encoded on the wire as the payload's `chunk` string.
+     * for `stream`, sent as an op-tagged `produce` frame — `produce` is the payload
+     * op, carried on the bulk lane (not the QoS control lane) — stamped with this
+     * client's {@link incarnation} so the hub can fence a stale predecessor. The
+     * hub assigns the authoritative chunk offset from its ring — a per-chunk,
+     * monotonic, gap-free counter (not a byte offset); the producer never carries
+     * one. Bytes are UTF-8-encoded on the wire as the payload's `chunk`.
      */
     relay(stream: string, chunk: string): void;
     /**

package/dist/client.js

@@ -53,6 +53,7 @@ export class AgenticClient {
     serveTimeoutMs;
     reconnectPolicy;
     schedule;
+    incarnation;
     capability;
     transport;
     state = "idle";
@@ -64,7 +65,6 @@ export class AgenticClient {
     heartbeatTimer;
     pendingServe;
     lastServe = [];
-    relayOffsets = new Map();
     serveListeners = new Set();
     frameListeners = new Set();
     openListeners = new Set();
@@ -86,6 +86,10 @@ export class AgenticClient {
             factor: options.reconnect?.factor ?? DEFAULT_RECONNECT.factor,
         };
         this.reconnectDelay = this.reconnectPolicy.initialDelayMs;
+        this.incarnation = options.incarnation ?? Date.now();
+        if (!Number.isInteger(this.incarnation) || this.incarnation < 0) {
+            throw new RangeError(`incarnation must be a non-negative integer, got ${this.incarnation}`);
+        }
         // Reject timing/backoff options that Node would coerce into a 0ms hot loop.
         // heartbeat/serveTimeout accept 0 as a "disabled" sentinel (guarded with > 0
         // at use), but reconnect delays have no such sentinel — enabled:false disables
@@ -207,28 +211,21 @@ export class AgenticClient {
     }
     /**
      * Produce relay bytes on the bulk lane. `chunk` is the terminal/command output
-     * for `stream`; the client tracks a monotonic per-stream byte offset so the
-     * hub-side ring can resume-from-offset after a consumer reconnect (S5). Bytes
-     * are UTF-8-encoded on the wire as the payload's `chunk` string.
+     * for `stream`, sent as an op-tagged `produce` frame — `produce` is the payload
+     * op, carried on the bulk lane (not the QoS control lane) — stamped with this
+     * client's {@link incarnation} so the hub can fence a stale predecessor. The
+     * hub assigns the authoritative chunk offset from its ring — a per-chunk,
+     * monotonic, gap-free counter (not a byte offset); the producer never carries
+     * one. Bytes are UTF-8-encoded on the wire as the payload's `chunk`.
      */
     relay(stream, chunk) {
-        // Terminal client: refuse before touching the per-stream offset map (which
-        // close() already released) so a post-close relay neither re-grows that map
-        // nor buffers a frame that can never drain.
+        // Terminal client: refuse post-close so a relay neither buffers a frame that
+        // can never drain nor is emitted after deregister.
         if (this.refuseWhenClosed("relay")) {
             return;
         }
-        const offset = this.relayOffsets.get(stream) ?? 0;
-        const payload = { stream, offset, chunk };
-        // Advance the per-stream offset only if the frame was actually accepted
-        // for sending. A relay rejected for invalid payload, refused because the
-        // client is closed, OR dropped by the QoS overflow policy (ring full of
-        // higher-priority traffic) must not consume offset space, or every
-        // subsequent relay's offset would be inconsistent with the bytes the hub
-        // actually received.
-        if (this.enqueue("relay", OUTBOUND_LANE.relay, payload)) {
-            this.relayOffsets.set(stream, offset + byteLength(chunk));
-        }
+        const payload = { op: "produce", stream, incarnation: this.incarnation, chunk };
+        this.enqueue("relay", OUTBOUND_LANE.relay, payload);
     }
     /**
      * Deregister and close. Sends a deregister frame best-effort — only when the
@@ -256,18 +253,16 @@ export class AgenticClient {
         // we drive handleClose directly to guarantee onClose fires. handleClose is
         // idempotent per connection attempt, so it de-duplicates against any onClose
         // the transport also fires.
-        // Terminal: the outbound ring and per-stream relay offsets can never be
-        // drained again, so release them here rather than pinning a large outage
-        // backlog (buffered frames, many relay streams) in memory for the lifetime
-        // of the now-dead client. Clear BEFORE anything can fire the close event —
-        // both the transport (an injectable seam that may legally fire onClose
-        // synchronously from close(), as FakeTransport does when open) and our own
-        // handleClose below emit onClose synchronously. A subscriber that reads
-        // `buffered` (or the relay-offset state) must observe the released,
-        // self-consistent terminal state that close() documents — not a stale
-        // non-zero backlog — regardless of which path surfaces the close first.
+        // Terminal: the outbound ring can never be drained again, so release it here
+        // rather than pinning a large outage backlog (buffered frames) in memory for
+        // the lifetime of the now-dead client. Clear BEFORE anything can fire the
+        // close event — both the transport (an injectable seam that may legally fire
+        // onClose synchronously from close(), as FakeTransport does when open) and our
+        // own handleClose below emit onClose synchronously. A subscriber that reads
+        // `buffered` must observe the released, self-consistent terminal state that
+        // close() documents — not a stale non-zero backlog — regardless of which path
+        // surfaces the close first.
         this.ring.clear();
-        this.relayOffsets.clear();
         const transport = this.transport;
         this.transport = undefined;
         try {
@@ -672,18 +667,6 @@ export function connectAgenticChannel(options) {
     client.connect();
     return client;
 }
-const utf8Encoder = new TextEncoder();
-// UTF-8 byte length of `text`. Prefer Node's `Buffer.byteLength`, which computes
-// the length without allocating, on the `relay()` hot path where the extra
-// per-call `Uint8Array` allocation from `TextEncoder.encode()` would add
-// measurable GC/CPU overhead during bulk output storms. Fall back to
-// `TextEncoder` where `Buffer` is unavailable (non-Node hosts).
-function byteLength(text) {
-    if (typeof Buffer !== "undefined") {
-        return Buffer.byteLength(text, "utf8");
-    }
-    return utf8Encoder.encode(text).length;
-}
 function isServePayload(payload) {
     if (typeof payload !== "object" || payload === null) {
         return false;

package/dist/index.d.ts

@@ -35,4 +35,4 @@ export type { EnqueueResult, OutboundRingOptions } from "./ring.ts";
 export { websocketTransport, normaliseIncoming } from "./transport.ts";
 export type { Transport, TransportCloseInfo, TransportFactory, TransportHooks, } from "./transport.ts";
 export { MESSAGE_FAMILIES, QOS_LANES, encodeFrame, decodeFrame, parseToken, isValidToken, validatePayload, } from "./protocol.ts";
-export type { Capability, Frame, MessageFamily, QosLane, RegisterPayload, HeartbeatPayload, DeregisterPayload, ServePayload, RelayPayload, } from "./protocol.ts";
+export type { Capability, Frame, MessageFamily, QosLane, RegisterPayload, HeartbeatPayload, DeregisterPayload, ServePayload, RelayPayload, RelayProducePayload, } from "./protocol.ts";

package/dist/protocol.d.ts

@@ -13,4 +13,4 @@
  * client imports it, it never redefines it.
  */
 export { MESSAGE_FAMILIES, isMessageFamily, QOS_LANES, isQosLane, compareFrameOrder, encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, MAX_SEQ, parseToken, isValidToken, validatePayload, bytesToHex, hexToBytes, } from "@nanobpm/agentic/source/protocol";
-export type { MessageFamily, QosLane, Frame, FrameDecodeErrorCode, Capability, RegisterPayload, HeartbeatPayload, DeregisterPayload, ServePayload, RelayPayload, BlackboardPayload, DemandPayload, } from "@nanobpm/agentic/source/protocol";
+export type { MessageFamily, QosLane, Frame, FrameDecodeErrorCode, Capability, RegisterPayload, HeartbeatPayload, DeregisterPayload, ServePayload, RelayPayload, RelayProducePayload, BlackboardPayload, DemandPayload, } from "@nanobpm/agentic/source/protocol";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban-agent-client",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Worker-side client for the Nano agentic channel (ADR 0056, S9): REGISTER→SERVE, heartbeat/deregister, produce relay bytes, and a local buffer / flush-on-reconnect ring that tolerates a hub outage. Speaks the @nanobpm/agentic wire contract (via its @nanobpm/agentic/protocol subpath) and is held to its shared conformance corpus.",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,7 +45,7 @@
     "test:conformance": "node --test --experimental-strip-types \"src/conformance.test.ts\""
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.1.0"
+    "@nanobpm/agentic": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/client.test.ts

@@ -66,7 +66,7 @@ test("a SERVE addressed to a different instance is ignored", async () => {
 });
 
 test("heartbeat, relay and deregister emit correctly-shaped frames", () => {
-  const { client, t } = newClient();
+  const { client, t } = newClient({ incarnation: 7 });
   client.connect();
   t.last().fireOpen();
 
@@ -83,9 +83,10 @@ test("heartbeat, relay and deregister emit correctly-shaped frames", () => {
   const relays = frames.filter((f) => f.family === "relay");
   assert.equal(relays.length, 2);
   assert.equal(relays[0]?.lane, "bulk");
-  // Per-stream byte offset advances by the UTF-8 length of each chunk.
-  assert.deepEqual(relays[0]?.payload, { stream: "stdout", offset: 0, chunk: "hello" });
-  assert.deepEqual(relays[1]?.payload, { stream: "stdout", offset: 5, chunk: "world!" });
+  // Producer emits op-tagged `produce` control frames stamped with the client's
+  // incarnation; the hub assigns authoritative offsets, so the producer carries none.
+  assert.deepEqual(relays[0]?.payload, { op: "produce", stream: "stdout", incarnation: 7, chunk: "hello" });
+  assert.deepEqual(relays[1]?.payload, { op: "produce", stream: "stdout", incarnation: 7, chunk: "world!" });
 
   const dereg = frames.find((f) => f.family === "deregister");
   assert.deepEqual(dereg?.payload, { instance: "worker-1", reason: "done" });
@@ -146,8 +147,7 @@ test("close() releases the outbound buffer so a terminal client pins no backlog"
   client.close();
 
   // Terminal close must not pin the outage backlog in memory forever — the ring
-  // (and the per-stream relay offsets) can never be drained again, so they are
-  // released.
+  // can never be drained again, so it is released.
   assert.equal(client.buffered, 0, "close() cleared the outbound ring");
 });
 
@@ -175,36 +175,12 @@ test("a closed client refuses every outbound-producing call instead of buffering
   );
 });
 
-test("relay offset tracks UTF-8 byte length per stream, independently", () => {
-  const { client, t } = newClient();
-  client.connect();
-  t.last().fireOpen();
-  client.relay("a", "é"); // 2 bytes UTF-8
-  client.relay("b", "x"); // separate stream, offset 0
-  client.relay("a", "z"); // offset now 2
-  // Astral char (U+1F600) is 4 UTF-8 bytes but 2 UTF-16 code units, so the
-  // offset must advance by the UTF-8 byte count (4), never the JS string length
-  // (2) — guards the byte-length helper against surrogate-pair miscounting.
-  client.relay("a", "😀"); // offset now 3
-  client.relay("a", "!"); // offset now 3 + 4 = 7
-  const relays = t.last().sentFrames.filter((f) => f.family === "relay");
-  assert.deepEqual(relays.map((f) => f.payload), [
-    { stream: "a", offset: 0, chunk: "é" },
-    { stream: "b", offset: 0, chunk: "x" },
-    { stream: "a", offset: 2, chunk: "z" },
-    { stream: "a", offset: 3, chunk: "😀" },
-    { stream: "a", offset: 7, chunk: "!" },
-  ]);
-  client.close();
-});
-
-test("a relay dropped by the QoS overflow policy does not advance the stream offset", () => {
+test("a relay dropped by the QoS overflow policy is not emitted", () => {
   // With a single ring slot, the register buffered while the hub is down (control
   // lane) fills the ring. A relay (bulk) enqueued now is the least-important frame
   // in play, so the overflow policy DROPS the incoming relay rather than evict the
-  // higher-priority register. A dropped relay must consume no offset space, or the
-  // hub-side resume-from-offset (S5) would see a phantom gap for bytes never sent.
-  const { client, t } = newClient({ bufferCapacity: 1 });
+  // higher-priority register. The dropped relay must never reach the wire.
+  const { client, t } = newClient({ incarnation: 7, bufferCapacity: 1 });
   client.connect(); // transport built, hub still down
   client.register({ capability: { cognition: "high" } }).catch(() => {}); // control frame fills the slot; rejected on close()
   assert.equal(client.buffered, 1, "the buffered register occupies the single ring slot");
@@ -217,8 +193,8 @@ test("a relay dropped by the QoS overflow policy does not advance the stream off
   const relays = t.last().sentFrames.filter((f) => f.family === "relay");
   assert.deepEqual(
     relays.map((f) => f.payload),
-    [{ stream: "s", offset: 0, chunk: "sent" }],
-    "offset starts at 0 — the earlier dropped relay consumed no offset space",
+    [{ op: "produce", stream: "s", incarnation: 7, chunk: "sent" }],
+    "only the accepted produce frame reached the wire",
   );
   client.close();
 });
@@ -248,7 +224,7 @@ test("buffers while the hub is down and drains in QoS order on reconnect", () =>
 });
 
 test("survives a mid-stream drop: unsent frames stay buffered and drain on the next open", () => {
-  const { client, t } = newClient({ reconnect: { enabled: false } });
+  const { client, t } = newClient({ incarnation: 7, reconnect: { enabled: false } });
   client.connect();
   t.last().fireOpen();
   client.relay("stdout", "a");
@@ -267,8 +243,8 @@ test("survives a mid-stream drop: unsent frames stay buffered and drain on the n
   assert.equal(client.buffered, 0);
   const chunks = t.last().sentFrames.filter((f) => f.family === "relay").map((f) => f.payload);
   assert.deepEqual(chunks, [
-    { stream: "stdout", offset: 1, chunk: "b" },
-    { stream: "stdout", offset: 2, chunk: "c" },
+    { op: "produce", stream: "stdout", incarnation: 7, chunk: "b" },
+    { op: "produce", stream: "stdout", incarnation: 7, chunk: "c" },
   ]);
 });
 
@@ -427,8 +403,8 @@ test("an invalid outbound relay payload is dropped with onError, not buffered",
   client.close();
 });
 
-test("a rejected relay consumes no offset space (advance-only-on-accept)", () => {
-  const { client, t } = newClient({ reconnect: { enabled: false } });
+test("a rejected relay does not disrupt subsequent produce frames", () => {
+  const { client, t } = newClient({ incarnation: 7, reconnect: { enabled: false } });
   client.connect();
   t.last().fireOpen();
 
@@ -436,21 +412,21 @@ test("a rejected relay consumes no offset space (advance-only-on-accept)", () =>
   client.onError((e) => errors.push(e));
 
   // An empty stream fails the S0 relay contract, so the frame is rejected at
-  // enqueue time. The offset for a real stream must be untouched by it, and a
-  // rejected relay must never advance its own (empty-stream) offset bucket.
-  client.relay("stdout", "ok"); // accepted → stdout offset advances to 2
+  // enqueue time. Subsequent valid produce frames must be emitted unaffected —
+  // the hub, not the producer, assigns offsets from the produce stream.
+  client.relay("stdout", "ok"); // accepted
   client.relay("", "dropped"); // rejected: empty stream
-  client.relay("stdout", "next"); // must resume at offset 2, unaffected by the reject
+  client.relay("stdout", "next"); // accepted, unaffected by the reject
 
   assert.ok(errors.some((e) => /relay payload failed validation/.test(e.message)));
   const relays = t.last().sentFrames.filter((f) => f.family === "relay").map((f) => f.payload);
   assert.deepEqual(
     relays,
     [
-      { stream: "stdout", offset: 0, chunk: "ok" },
-      { stream: "stdout", offset: 2, chunk: "next" },
+      { op: "produce", stream: "stdout", incarnation: 7, chunk: "ok" },
+      { op: "produce", stream: "stdout", incarnation: 7, chunk: "next" },
     ],
-    "the rejected relay neither advanced nor corrupted any offset",
+    "the rejected relay neither dropped nor corrupted a subsequent produce frame",
   );
   client.close();
 });
@@ -649,7 +625,7 @@ test("close() releases the outbound buffer BEFORE it emits onClose, so subscribe
   const { client } = newClient({ capability: { cognition: "high" } });
   client.connect(); // transport built but never opened
 
-  // Accumulate an outage backlog: buffered relay frames + per-stream offsets.
+  // Accumulate an outage backlog of buffered relay frames.
   for (let i = 0; i < 4; i++) {
     client.relay("stdout", `chunk-${i}`);
   }

package/src/client.ts

@@ -14,7 +14,7 @@ import type {
   MessageFamily,
   QosLane,
   RegisterPayload,
-  RelayPayload,
+  RelayProducePayload,
   ServePayload,
 } from "./protocol.ts";
 import { websocketTransport } from "./transport.ts";
@@ -86,6 +86,20 @@ export interface AgenticClientOptions {
   readonly serveTimeoutMs?: number;
   /** Reconnect/backoff policy. Enabled by default. */
   readonly reconnect?: ReconnectOptions;
+  /**
+   * The producer generation stamped on every `produce` relay frame. The hub's
+   * incarnation fence admits a frame only when its incarnation is `>=` the
+   * highest seen for that stream, so a successor producer (a retried job on a
+   * fresh runner taking over the same stream) MUST present a strictly higher
+   * value to fence its stale predecessor. Defaults to `Date.now()`, which a
+   * later-started process naturally exceeds — but that default is best-effort:
+   * clock skew, a backwards clock adjustment, or two restarts inside the same
+   * millisecond can break strict monotonicity. A caller that needs a hard
+   * fencing guarantee MUST supply an explicit monotonic `incarnation` (e.g. a
+   * persisted per-takeover counter) rather than rely on the clock. Must be a
+   * non-negative integer.
+   */
+  readonly incarnation?: number;
   /** Injectable scheduler for reconnect backoff (tests). Defaults to setTimeout. */
   readonly schedule?: (fn: () => void, ms: number) => void;
 }
@@ -126,6 +140,7 @@ export class AgenticClient {
   private readonly serveTimeoutMs: number;
   private readonly reconnectPolicy: Required<ReconnectOptions>;
   private readonly schedule: (fn: () => void, ms: number) => void;
+  private readonly incarnation: number;
 
   private capability: Capability | undefined;
   private transport: Transport | undefined;
@@ -138,7 +153,6 @@ export class AgenticClient {
   private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
   private pendingServe: PendingServe | undefined;
   private lastServe: readonly string[] = [];
-  private readonly relayOffsets = new Map<string, number>();
 
   private readonly serveListeners = new Set<Listener<ServePayload>>();
   private readonly frameListeners = new Set<Listener<Frame>>();
@@ -162,6 +176,10 @@ export class AgenticClient {
       factor: options.reconnect?.factor ?? DEFAULT_RECONNECT.factor,
     };
     this.reconnectDelay = this.reconnectPolicy.initialDelayMs;
+    this.incarnation = options.incarnation ?? Date.now();
+    if (!Number.isInteger(this.incarnation) || this.incarnation < 0) {
+      throw new RangeError(`incarnation must be a non-negative integer, got ${this.incarnation}`);
+    }
     // Reject timing/backoff options that Node would coerce into a 0ms hot loop.
     // heartbeat/serveTimeout accept 0 as a "disabled" sentinel (guarded with > 0
     // at use), but reconnect delays have no such sentinel — enabled:false disables
@@ -294,28 +312,21 @@ export class AgenticClient {
 
   /**
    * Produce relay bytes on the bulk lane. `chunk` is the terminal/command output
-   * for `stream`; the client tracks a monotonic per-stream byte offset so the
-   * hub-side ring can resume-from-offset after a consumer reconnect (S5). Bytes
-   * are UTF-8-encoded on the wire as the payload's `chunk` string.
+   * for `stream`, sent as an op-tagged `produce` frame — `produce` is the payload
+   * op, carried on the bulk lane (not the QoS control lane) — stamped with this
+   * client's {@link incarnation} so the hub can fence a stale predecessor. The
+   * hub assigns the authoritative chunk offset from its ring — a per-chunk,
+   * monotonic, gap-free counter (not a byte offset); the producer never carries
+   * one. Bytes are UTF-8-encoded on the wire as the payload's `chunk`.
    */
   relay(stream: string, chunk: string): void {
-    // Terminal client: refuse before touching the per-stream offset map (which
-    // close() already released) so a post-close relay neither re-grows that map
-    // nor buffers a frame that can never drain.
+    // Terminal client: refuse post-close so a relay neither buffers a frame that
+    // can never drain nor is emitted after deregister.
     if (this.refuseWhenClosed("relay")) {
       return;
     }
-    const offset = this.relayOffsets.get(stream) ?? 0;
-    const payload: RelayPayload = { stream, offset, chunk };
-    // Advance the per-stream offset only if the frame was actually accepted
-    // for sending. A relay rejected for invalid payload, refused because the
-    // client is closed, OR dropped by the QoS overflow policy (ring full of
-    // higher-priority traffic) must not consume offset space, or every
-    // subsequent relay's offset would be inconsistent with the bytes the hub
-    // actually received.
-    if (this.enqueue("relay", OUTBOUND_LANE.relay, payload)) {
-      this.relayOffsets.set(stream, offset + byteLength(chunk));
-    }
+    const payload: RelayProducePayload = { op: "produce", stream, incarnation: this.incarnation, chunk };
+    this.enqueue("relay", OUTBOUND_LANE.relay, payload);
   }
 
   /**
@@ -345,18 +356,16 @@ export class AgenticClient {
     // we drive handleClose directly to guarantee onClose fires. handleClose is
     // idempotent per connection attempt, so it de-duplicates against any onClose
     // the transport also fires.
-    // Terminal: the outbound ring and per-stream relay offsets can never be
-    // drained again, so release them here rather than pinning a large outage
-    // backlog (buffered frames, many relay streams) in memory for the lifetime
-    // of the now-dead client. Clear BEFORE anything can fire the close event —
-    // both the transport (an injectable seam that may legally fire onClose
-    // synchronously from close(), as FakeTransport does when open) and our own
-    // handleClose below emit onClose synchronously. A subscriber that reads
-    // `buffered` (or the relay-offset state) must observe the released,
-    // self-consistent terminal state that close() documents — not a stale
-    // non-zero backlog — regardless of which path surfaces the close first.
+    // Terminal: the outbound ring can never be drained again, so release it here
+    // rather than pinning a large outage backlog (buffered frames) in memory for
+    // the lifetime of the now-dead client. Clear BEFORE anything can fire the
+    // close event — both the transport (an injectable seam that may legally fire
+    // onClose synchronously from close(), as FakeTransport does when open) and our
+    // own handleClose below emit onClose synchronously. A subscriber that reads
+    // `buffered` must observe the released, self-consistent terminal state that
+    // close() documents — not a stale non-zero backlog — regardless of which path
+    // surfaces the close first.
     this.ring.clear();
-    this.relayOffsets.clear();
     const transport = this.transport;
     this.transport = undefined;
     try {
@@ -789,20 +798,6 @@ export function connectAgenticChannel(options: AgenticClientOptions): AgenticCli
   return client;
 }
 
-const utf8Encoder = new TextEncoder();
-
-// UTF-8 byte length of `text`. Prefer Node's `Buffer.byteLength`, which computes
-// the length without allocating, on the `relay()` hot path where the extra
-// per-call `Uint8Array` allocation from `TextEncoder.encode()` would add
-// measurable GC/CPU overhead during bulk output storms. Fall back to
-// `TextEncoder` where `Buffer` is unavailable (non-Node hosts).
-function byteLength(text: string): number {
-  if (typeof Buffer !== "undefined") {
-    return Buffer.byteLength(text, "utf8");
-  }
-  return utf8Encoder.encode(text).length;
-}
-
 function isServePayload(payload: unknown): payload is ServePayload {
   if (typeof payload !== "object" || payload === null) {
     return false;

package/src/index.ts

@@ -74,4 +74,5 @@ export type {
   DeregisterPayload,
   ServePayload,
   RelayPayload,
+  RelayProducePayload,
 } from "./protocol.ts";

package/src/protocol.ts

@@ -41,6 +41,7 @@ export type {
   DeregisterPayload,
   ServePayload,
   RelayPayload,
+  RelayProducePayload,
   BlackboardPayload,
   DemandPayload,
 } from "@nanobpm/agentic/source/protocol";

package/src/relay-roundtrip.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Cross-package contract test: the REAL worker client's produced relay frames,
+ * as they go on the wire, must be accepted by the REAL hub relay state machine.
+ *
+ * This is the test that was missing when the agentic-protocol epic (S0–S10)
+ * landed: the hub relay-family adopted an op-tagged `produce`/`incarnation`
+ * sub-protocol while this client kept emitting the legacy `{ stream, offset,
+ * chunk }` delivery shape, so every worker chunk was rejected at the hub as
+ * "malformed relay message payload". Each side's own unit tests were green
+ * because each mocked the other; nothing fed a real producer frame into the
+ * real hub. This test closes that gap and fails if the produce frame drifts.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { RelayHub } from "@nanobpm/agentic/source/relay";
+import type { RelayConnection } from "@nanobpm/agentic/source/relay";
+import type { Frame } from "./protocol.ts";
+import { AgenticClient } from "./client.ts";
+import { fakeTransportFactory } from "./testkit.ts";
+
+class FakeRegistry {
+  readonly live = new Set<string>();
+  has(id: string): boolean {
+    return this.live.has(id);
+  }
+}
+
+class FakeConn implements RelayConnection {
+  readonly id: string;
+  readonly registry: FakeRegistry;
+  readonly sent: Frame[] = [];
+  constructor(id: string, registry: FakeRegistry) {
+    this.id = id;
+    this.registry = registry;
+    registry.live.add(id);
+  }
+  send(frame: Frame): void {
+    this.sent.push(frame);
+  }
+}
+
+function field(payload: unknown, key: string): unknown {
+  return typeof payload === "object" && payload !== null ? Reflect.get(payload, key) : undefined;
+}
+
+/** Data chunks the hub delivered to a consumer, in order. */
+function dataChunks(conn: FakeConn): string[] {
+  return conn.sent
+    .filter((f) => f.lane === "bulk" && field(f.payload, "op") === undefined)
+    .map((f) => String(field(f.payload, "chunk")));
+}
+
+function subscribeFrame(stream: string, from: number, credit: number): Frame {
+  return { lane: "control", family: "relay", seq: 0, payload: { op: "subscribe", stream, from, credit } };
+}
+
+function producedRelayFrames(chunks: string[], incarnation: number): Frame[] {
+  const t = fakeTransportFactory();
+  const client = new AgenticClient({
+    url: "ws://test/agentic",
+    instance: "worker-1",
+    transport: t.factory,
+    reconnect: { enabled: false },
+    serveTimeoutMs: 0,
+    incarnation,
+  });
+  client.connect();
+  t.last().fireOpen();
+  for (const c of chunks) client.relay("job-1", c);
+  // sentFrames decodes the actual wire bytes the client emitted — a true
+  // producer-wire round-trip, not a peek at the pre-encode payload object.
+  const relays = t.last().sentFrames.filter((f) => f.family === "relay");
+  client.close();
+  return relays;
+}
+
+test("the hub admits the client's produced relay frames and delivers the bytes", () => {
+  const produced = producedRelayFrames(["hello ", "world"], 42);
+  assert.equal(produced.length, 2);
+  // Every produced frame is an op-tagged `produce` frame (the `produce` payload
+  // op — carried on the bulk lane, not the QoS control lane).
+  for (const f of produced) {
+    assert.equal(field(f.payload, "op"), "produce");
+    assert.equal(field(f.payload, "incarnation"), 42);
+  }
+
+  const errors: unknown[] = [];
+  const hub = new RelayHub({ onError: (e) => errors.push(e) });
+  const reg = new FakeRegistry();
+  const prod = new FakeConn("producer", reg);
+  const cons = new FakeConn("consumer", reg);
+
+  hub.handle(subscribeFrame("job-1", 0, 1024), cons);
+  for (const f of produced) hub.handle(f, prod);
+
+  // The regression: before the fix, each produce frame tripped
+  // RelayMessageError("malformed relay message payload") here.
+  assert.deepEqual(errors, [], "hub rejected a produced relay frame");
+  assert.deepEqual(dataChunks(cons), ["hello ", "world"]);
+  assert.equal(hub.ring("job-1")?.nextOffset, 2);
+});
+
+test("a later producer incarnation fences a stale predecessor on the hub", () => {
+  const stale = producedRelayFrames(["from-old"], 1);
+  const fresh = producedRelayFrames(["from-new"], 2);
+
+  const fenced: Array<{ stream: string; incarnation: number; current: number }> = [];
+  const hub = new RelayHub({ onFenced: (stream, incarnation, current) => fenced.push({ stream, incarnation, current }) });
+  const reg = new FakeRegistry();
+  const prod = new FakeConn("producer", reg);
+
+  // The fresh (higher) incarnation takes over the stream; the stale one is fenced.
+  for (const f of fresh) hub.handle(f, prod);
+  for (const f of stale) hub.handle(f, prod);
+
+  assert.equal(hub.ring("job-1")?.nextOffset, 1, "only the fresh incarnation's byte was admitted");
+  assert.equal(fenced.length, 1);
+  assert.deepEqual(fenced[0], { stream: "job-1", incarnation: 1, current: 2 });
+});