@robota-sdk/agent-transport 3.0.0-beta.78 → 3.0.0-beta.81

package/src/__tests__/admission.test.ts

@@ -0,0 +1,130 @@
+/**
+ * SEC-008 — the admission seam's own cases.
+ *
+ * `resolveAdmission` had none. It was exercised only THROUGH the four transports that call it, and
+ * both defects review found here are ones that indirection hides: a transport passing a well-formed
+ * config never exhibits either.
+ *
+ * The seam's whole claim is "one place to read and one place to change". A seam nobody tests
+ * directly is one place to read and four places to find out you were wrong.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { bearerCredential, resolveAdmission } from '../node/admission.js';
+
+const OPEN_REASON = 'loopback only, the port is bound to 127.0.0.1';
+
+describe('resolveAdmission is secure by default', () => {
+  it('mints when nothing is asked for', () => {
+    const admission = resolveAdmission();
+
+    expect(admission.token).toMatch(/^[0-9a-f]{64}$/);
+    expect(admission.openReason).toBeUndefined();
+  });
+
+  it('keeps an explicit token', () => {
+    expect(resolveAdmission({ token: 'chosen-by-the-host' })).toEqual({
+      token: 'chosen-by-the-host',
+    });
+  });
+
+  it('opens only with a reason', () => {
+    expect(resolveAdmission({ open: true, openReason: OPEN_REASON })).toEqual({
+      token: null,
+      openReason: OPEN_REASON,
+    });
+    expect(() => resolveAdmission({ open: true })).toThrow(/requires `openReason`/);
+    expect(() => resolveAdmission({ open: true, openReason: '   ' })).toThrow(
+      /requires `openReason`/,
+    );
+  });
+
+  it('MINTS for an empty-string token rather than requiring the empty string', () => {
+    // The value behind the discriminator defect. `{ token: '' }` is documented as "mint a fresh
+    // one", and the HTTP route's `'token' in options.admission` read it as ALREADY RESOLVED and
+    // installed the empty string as the required credential — which a peer sending an empty bearer
+    // then matches. The route no longer discriminates; this pins the value it depends on.
+    expect(resolveAdmission({ token: '' }).token).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe('resolveAdmission is idempotent', () => {
+  // Why it must be: the HTTP route accepts either shape, and BOTH interfaces declare a `token`, so
+  // they cannot be told apart structurally. Making the function accept its own output deletes that
+  // question instead of answering it wrongly.
+  it('returns an already-resolved token admission unchanged', () => {
+    const resolved = resolveAdmission({ token: 'chosen-by-the-host' });
+
+    expect(resolveAdmission(resolved)).toEqual(resolved);
+  });
+
+  it('returns an already-resolved OPEN admission unchanged, reason and all', () => {
+    // The case that made the old code wrong in the dangerous direction: re-resolving an open
+    // admission through a config-shaped path either minted a token nobody holds or dropped the
+    // reason and left an unexplained open transport.
+    const resolved = resolveAdmission({ open: true, openReason: OPEN_REASON });
+
+    expect(resolved).toEqual({ token: null, openReason: OPEN_REASON });
+    expect(resolveAdmission(resolved)).toEqual(resolved);
+  });
+
+  it('REFUSES an open admission that arrives without its reason', () => {
+    // `token: null` is the recorded outcome of a decision. One reaching here with no reason was
+    // hand-built or corrupted, and both are the unexplained-open state the reason exists to
+    // prevent — so it is refused rather than passed through.
+    expect(() => resolveAdmission({ token: null })).toThrow(/requires `openReason`/);
+  });
+});
+
+describe('resolveAdmission refuses a contradiction', () => {
+  it('throws when a token and `open: true` are asked for together', () => {
+    // Review: `WebRtcTransport` already refused the analogous `secret` + `open` pair in its own
+    // constructor, so only WebRTC callers were protected. The old seam gave silent precedence to
+    // the token — the safe DIRECTION, but the wrong ANSWER: a caller that wrote both does not know
+    // what it is asking for, and one of the two things it believes is false.
+    expect(() =>
+      resolveAdmission({ token: 'a-credential', open: true, openReason: OPEN_REASON }),
+    ).toThrow(/contradictory/);
+  });
+
+  it('still accepts `open: false` beside a token, which is not a contradiction', () => {
+    // `open: false` says the same thing the token does. Refusing it would turn a redundant but
+    // coherent config into an error, which is over-blocking for nothing.
+    expect(resolveAdmission({ token: 'a-credential', open: false })).toEqual({
+      token: 'a-credential',
+    });
+  });
+});
+
+describe('bearerCredential reads the header the way RFC 7235 defines it', () => {
+  it('matches the SCHEME without regard to case', () => {
+    // `auth-scheme` is a token, and tokens compare case-insensitively. The exact-case match refused
+    // a conformant client with a 401 it could not act on — a refusal that reads as a server bug and
+    // gets worked around rather than fixed. Review found it.
+    expect(bearerCredential('bearer abc123')).toBe('abc123');
+    expect(bearerCredential('BEARER abc123')).toBe('abc123');
+    expect(bearerCredential('BeArEr abc123')).toBe('abc123');
+  });
+
+  it('leaves the CREDENTIAL exactly as sent', () => {
+    // Only the scheme is case-insensitive. The credential is compared byte for byte, so folding it
+    // would make two different secrets the same secret.
+    expect(bearerCredential('Bearer AbC')).toBe('AbC');
+  });
+
+  it('accepts more than one space between the two', () => {
+    expect(bearerCredential('Bearer   abc123')).toBe('abc123');
+    expect(bearerCredential('Bearer\tabc123')).toBe('abc123');
+  });
+
+  it('refuses a header that merely STARTS with the word', () => {
+    // `Bearerness xyz` is a different scheme, and reading it as a bearer token would admit a peer
+    // that never claimed to be one.
+    expect(bearerCredential('Bearerness xyz')).toBeUndefined();
+    expect(bearerCredential('Basic abc123')).toBeUndefined();
+    expect(bearerCredential('Bearer')).toBeUndefined();
+    expect(bearerCredential('Bearer ')).toBeUndefined();
+    expect(bearerCredential(undefined)).toBeUndefined();
+  });
+});

package/src/__tests__/channel-frames.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  CHANNEL_FRAME_MAGIC,
+  decodeChannelFrame,
+  encodeBinaryFrame,
+  encodeChannelEventFrame,
+} from '../channel-frames.js';
+
+import type { IBinaryFrame, IChannelEventFrame } from '@robota-sdk/agent-interface-transport';
+
+/**
+ * TRANS-001 — payload-agnostic frame codec.
+ *
+ * The codec is the ONLY thing that knows the carrier envelope; it never interprets the opaque body.
+ * These tests pin round-trip integrity, ordering metadata (`seq`), and explicit malformed-input
+ * results (a result union, never a swallowed default).
+ */
+
+function bytes(...values: number[]): Uint8Array {
+  return Uint8Array.from(values);
+}
+
+describe('channel frame codec (TRANS-001)', () => {
+  it('round-trips an opaque binary payload byte-identically', () => {
+    // Deliberately includes bytes that are invalid UTF-8 and JSON-hostile — the carrier must not care.
+    const payload = bytes(0x00, 0xff, 0xfe, 0x7b, 0x22, 0x80, 0x0a, 0xc3, 0x28);
+    const encoded = encodeBinaryFrame({ kind: 'binary', channel: 'audio', seq: 7, payload });
+
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.kind).toBe('binary');
+    const frame = decoded.frame as IBinaryFrame;
+    expect(frame.channel).toBe('audio');
+    expect(frame.seq).toBe(7);
+    expect(Array.from(frame.payload)).toEqual(Array.from(payload));
+  });
+
+  it('round-trips an empty binary payload', () => {
+    const encoded = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'blob',
+      seq: 0,
+      payload: new Uint8Array(0),
+    });
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect((decoded.frame as IBinaryFrame).payload.byteLength).toBe(0);
+  });
+
+  it('preserves per-channel ordering through seq on a chunked stream', () => {
+    const source = new Uint8Array(1024);
+    for (let i = 0; i < source.length; i += 1) source[i] = (i * 31) % 256;
+
+    const chunkSize = 100;
+    const wire: Uint8Array[] = [];
+    for (let offset = 0, seq = 0; offset < source.length; offset += chunkSize, seq += 1) {
+      wire.push(
+        encodeBinaryFrame({
+          kind: 'binary',
+          channel: 'file',
+          seq,
+          payload: source.subarray(offset, Math.min(offset + chunkSize, source.length)),
+        }),
+      );
+    }
+
+    // Deliver out of order; the receiver reassembles by `seq`, not by arrival order.
+    const shuffled = [...wire].reverse();
+    const received: IBinaryFrame[] = [];
+    for (const w of shuffled) {
+      const d = decodeChannelFrame(w);
+      expect(d.ok).toBe(true);
+      if (d.ok && d.frame.kind === 'binary') received.push(d.frame);
+    }
+
+    received.sort((a, b) => a.seq - b.seq);
+    const reassembled = new Uint8Array(source.length);
+    let cursor = 0;
+    for (const frame of received) {
+      reassembled.set(frame.payload, cursor);
+      cursor += frame.payload.byteLength;
+    }
+    expect(cursor).toBe(source.length);
+    expect(Array.from(reassembled)).toEqual(Array.from(source));
+  });
+
+  it('round-trips a consumer-declared structured event frame', () => {
+    const encoded = encodeChannelEventFrame({
+      kind: 'event',
+      channel: 'captions',
+      seq: 3,
+      event: 'caption',
+      payload: { text: 'hello', final: true },
+    });
+
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.kind).toBe('event');
+    const frame = decoded.frame as IChannelEventFrame;
+    expect(frame.channel).toBe('captions');
+    expect(frame.seq).toBe(3);
+    expect(frame.event).toBe('caption');
+    expect(frame.payload).toEqual({ text: 'hello', final: true });
+  });
+
+  it('supports multi-byte UTF-8 channel names', () => {
+    const encoded = encodeBinaryFrame({
+      kind: 'binary',
+      channel: '음성-채널',
+      seq: 1,
+      payload: bytes(1, 2, 3),
+    });
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.channel).toBe('음성-채널');
+  });
+
+  it('rejects a channel name that does not fit the 255-byte header field', () => {
+    expect(() =>
+      encodeBinaryFrame({
+        kind: 'binary',
+        channel: 'x'.repeat(256),
+        seq: 0,
+        payload: new Uint8Array(0),
+      }),
+    ).toThrow(/channel name/i);
+  });
+
+  it('rejects an empty channel name', () => {
+    expect(() =>
+      encodeBinaryFrame({ kind: 'binary', channel: '', seq: 0, payload: new Uint8Array(0) }),
+    ).toThrow(/channel name/i);
+  });
+
+  it('rejects a seq outside the uint32 range', () => {
+    expect(() =>
+      encodeBinaryFrame({
+        kind: 'binary',
+        channel: 'c',
+        seq: 2 ** 32,
+        payload: new Uint8Array(0),
+      }),
+    ).toThrow(/seq/i);
+  });
+
+  it('reports a non-channel frame as a typed error result rather than throwing', () => {
+    const decoded = decodeChannelFrame(bytes(0x01, 0x02, 0x03, 0x04, 0x05));
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/magic|channel frame/i);
+  });
+
+  it('reports a truncated frame as a typed error result', () => {
+    const full = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'audio',
+      seq: 1,
+      payload: bytes(9, 9, 9),
+    });
+    const decoded = decodeChannelFrame(full.subarray(0, 6));
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/truncated/i);
+  });
+
+  it('reports an unknown frame kind as a typed error result', () => {
+    const full = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'audio',
+      seq: 1,
+      payload: bytes(9),
+    });
+    const tampered = Uint8Array.from(full);
+    tampered[4] = 0x7f; // unknown kind byte
+    const decoded = decodeChannelFrame(tampered);
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/kind/i);
+  });
+
+  it('reports a malformed event body as a typed error result', () => {
+    const good = encodeChannelEventFrame({
+      kind: 'event',
+      channel: 'c',
+      seq: 0,
+      event: 'e',
+      payload: null,
+    });
+    const tampered = Uint8Array.from(good);
+    // Corrupt the JSON body (everything after the 10 + channelNameLength header bytes).
+    tampered[tampered.length - 1] = 0x7b; // '{'
+    const decoded = decodeChannelFrame(tampered);
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/body|json/i);
+  });
+
+  it('stamps the shared magic so a carrier can route frames without parsing them', () => {
+    const encoded = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'c',
+      seq: 0,
+      payload: new Uint8Array(0),
+    });
+    expect(Array.from(encoded.subarray(0, CHANNEL_FRAME_MAGIC.length))).toEqual(
+      Array.from(CHANNEL_FRAME_MAGIC),
+    );
+  });
+});

package/src/__tests__/driver-attribution-capability.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { subscribeSessionEvents } from '../session-events.js';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import type { IInteractiveSession, TDriverId } from '@robota-sdk/agent-interface-session';
+
+/**
+ * ARCH-012 — the sharp edge of an optional contract member.
+ *
+ * `IInteractiveSession` declared `getActiveDriverId?()`, and the one consumer read it as
+ * `session.getActiveDriverId?.() ?? undefined`. Two entirely different situations arrived as the same
+ * `undefined`:
+ *
+ * - the host DOES attribute turns and no driver is active right now, and
+ * - the host does not implement attribution at all.
+ *
+ * The second silently loses every co-drive attribution, with no error, no log, and nothing a reader
+ * or a test could use to tell it from the first. The shipped `InteractiveSession` happens to
+ * implement all three optional members, so the defect was latent for it and live for the 51 casts
+ * that stand in for other implementations.
+ *
+ * The fix is not a better fallback. It is removing the optionality: a host either provides the
+ * capability or does not claim the contract. These cases pin that the member is REQUIRED, which is
+ * what makes "no active driver" the only thing `null` can mean.
+ */
+function hostWithAttribution(driverId: TDriverId | null): IInteractiveSession {
+  // The conformant double, not another hand-rolled partial — the cast ratchet objected to the first
+  // draft of this very file, which is the behaviour it exists for.
+  return createTestInteractiveSession({
+    getActiveDriverId: () => driverId,
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+describe('driver attribution is a declared capability, not an optional call (ARCH-012)', () => {
+  it('TYPE-LEVEL: a host that omits the attribution members does not satisfy the contract', () => {
+    // Judged by `pnpm typecheck`, not by this assertion — `@ts-expect-error` fails the BUILD when the
+    // error it expects does not occur.
+    //
+    // `Omit` rather than a hand-written object literal, deliberately. A literal missing the three
+    // members is also missing the forty required ones, so `@ts-expect-error` would be satisfied by
+    // the wrong error and the case would pass whether or not the optionality was ever removed. That
+    // is precisely the accidental-green shape; the first draft of this test had it. This type carries
+    // every other member and differs ONLY in the three.
+    type OmitsAttribution = Omit<
+      IInteractiveSession,
+      'getActiveDriverId' | 'getPendingCount' | 'isInitialized'
+    >;
+    const host = {} as OmitsAttribution;
+    // @ts-expect-error ARCH-012: the three are REQUIRED. If this ever compiles again the optionality
+    // is back, and `undefined` means both "no active driver" and "cannot answer" once more.
+    const asSession: IInteractiveSession = host;
+    expect(asSession).toBeDefined();
+  });
+
+  it('stamps the active driver onto a turn-authored event', () => {
+    const send = vi.fn();
+    const session = hostWithAttribution('driver-7');
+    subscribeSessionEvents(session, createOutboundDelivery(send, vi.fn()));
+
+    const handler = vi.mocked(session.on).mock.calls.find(([name]) => name === 'user_message')?.[1];
+    (handler as (content: string) => void)('hello');
+
+    expect(send).toHaveBeenCalledWith(expect.objectContaining({ driverId: 'driver-7' }));
+  });
+
+  it('omits the driver when the host attributes turns and none is active', () => {
+    // `null` now means exactly one thing: nobody is driving. It used to be indistinguishable from
+    // "this host cannot answer the question".
+    const send = vi.fn();
+    const session = hostWithAttribution(null);
+    subscribeSessionEvents(session, createOutboundDelivery(send, vi.fn()));
+
+    const handler = vi.mocked(session.on).mock.calls.find(([name]) => name === 'user_message')?.[1];
+    (handler as (content: string) => void)('hello');
+
+    expect(send).toHaveBeenCalledWith(expect.not.objectContaining({ driverId: expect.anything() }));
+  });
+});

package/src/__tests__/handoff-chunking.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  chunkCountFor,
+  chunkHandoffPayload,
+  HandoffChunkAssembler,
+  type IHandoffChunk,
+} from '../handoff-chunking.js';
+import { sealHandoffRecord, verifyHandoffPayload } from '../node/handoff-manifest.js';
+
+import type { IInteractiveSessionRecord } from '@robota-sdk/agent-interface-session';
+
+const ID = 'handoff_1';
+
+function assemble(chunks: readonly IHandoffChunk[], assembler = new HandoffChunkAssembler(ID)) {
+  let last;
+  for (const chunk of chunks) last = assembler.accept(chunk);
+  return { assembler, last };
+}
+
+describe('HANDOFF-001 — a payload larger than one frame travels in pieces', () => {
+  it('every chunk fits the byte budget', () => {
+    // The channel's limit is in bytes, so the budget has to be honoured in bytes. A payload of
+    // multi-byte characters is where a character-based cut overflows the frame.
+    const payload = '한글'.repeat(500);
+
+    const chunks = chunkHandoffPayload(ID, payload, 64);
+
+    for (const chunk of chunks) {
+      expect(Buffer.from(chunk.data, 'base64').byteLength).toBeLessThanOrEqual(64);
+    }
+  });
+
+  it('round-trips a payload whose characters do not align to the cut', () => {
+    // The cut lands mid-character by construction here. Reassembly is on bytes, so the boundary
+    // is invisible to the result — which is the property the byte-based design buys.
+    const payload = `${'a'.repeat(30)}😀${'b'.repeat(30)}`;
+
+    const { last } = assemble(chunkHandoffPayload(ID, payload, 16));
+
+    expect(last?.outcome).toBe('complete');
+    expect(last?.serialized).toBe(payload);
+  });
+
+  it('an empty payload is one chunk, not zero', () => {
+    // Zero chunks would leave a receiver unable to tell a completed empty transfer from one that
+    // never started.
+    const chunks = chunkHandoffPayload(ID, '', 64);
+
+    expect(chunks).toHaveLength(1);
+    expect(assemble(chunks).last?.serialized).toBe('');
+  });
+
+  it('every chunk carries the total, so no single lost frame hides the count', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+
+    expect(chunks.every((c) => c.total === chunks.length)).toBe(true);
+  });
+
+  it('refuses a budget that would produce an endless sequence of empty chunks', () => {
+    expect(() => chunkHandoffPayload(ID, 'x', 0)).toThrow(/positive integer/);
+  });
+
+  it('predicts the chunk count from the manifest without building them', () => {
+    const { serialized, integrity } = sealHandoffRecord({
+      id: 's',
+      cwd: '/w',
+      createdAt: 'a',
+      updatedAt: 'b',
+      messages: [],
+    } as IInteractiveSessionRecord);
+
+    expect(chunkCountFor(integrity, 16)).toBe(chunkHandoffPayload(ID, serialized, 16).length);
+  });
+});
+
+describe('HANDOFF-001 — reordering and retries are normal; inconsistency is not', () => {
+  it('accepts chunks out of order', () => {
+    const chunks = [...chunkHandoffPayload(ID, 'x'.repeat(100), 10)].reverse();
+
+    const { last } = assemble(chunks);
+
+    expect(last?.outcome).toBe('complete');
+    expect(last?.serialized).toBe('x'.repeat(100));
+  });
+
+  it('a re-sent chunk is a duplicate, not a problem', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    const again = assembler.accept(chunks[0]);
+
+    expect(again.outcome).toBe('duplicate');
+    expect(again.received).toBe(1);
+  });
+
+  it('different bytes for the same index is refused, not overwritten', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    const conflicting = assembler.accept({
+      ...chunks[0],
+      data: Buffer.from('zz').toString('base64'),
+    });
+
+    expect(conflicting.outcome).toBe('refused');
+  });
+
+  it('a peer that changes its mind about the size is refused', () => {
+    // Either it restarted the transfer under the same id, or it is not the peer we started with.
+    // Both mean the pieces held so far can no longer be assumed to belong together.
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    const result = assembler.accept({ ...chunks[1], total: 3 });
+
+    expect(result.rejection).toBe('inconsistent-total');
+  });
+
+  it('refuses a chunk belonging to a different transfer rather than routing it', () => {
+    const [chunk] = chunkHandoffPayload('other_handoff', 'x', 10);
+
+    expect(new HandoffChunkAssembler(ID).accept(chunk).rejection).toBe('wrong-handoff');
+  });
+
+  it.each([
+    ['a negative index', -1],
+    ['an index beyond the total', 99],
+  ])('refuses %s', (_label, index) => {
+    const [chunk] = chunkHandoffPayload(ID, 'x'.repeat(30), 10);
+
+    expect(new HandoffChunkAssembler(ID).accept({ ...chunk, index }).rejection).toBe(
+      'out-of-range',
+    );
+  });
+
+  it('reports which indices are still missing, so a caller can ask rather than restart', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+    assembler.accept(chunks[3]);
+
+    expect(assembler.missing()).toEqual([1, 2, 4, 5, 6, 7, 8, 9]);
+  });
+
+  it('knows nothing is missing before anything has declared a total', () => {
+    expect(new HandoffChunkAssembler(ID).missing()).toEqual([]);
+  });
+
+  it('discard drops what it held', () => {
+    const chunks = chunkHandoffPayload(ID, 'x'.repeat(100), 10);
+    const assembler = new HandoffChunkAssembler(ID);
+    assembler.accept(chunks[0]);
+
+    assembler.discard();
+
+    expect(assembler.received).toBe(0);
+    expect(assembler.expected).toBeUndefined();
+  });
+});
+
+describe('HANDOFF-001 TC-06 — a mangled chunk is caught where it arrives', () => {
+  it('refuses data that is not decodable base64', () => {
+    // Buffer.from is lenient: it drops what it cannot parse rather than throwing, so a mangled
+    // chunk would silently become a shorter one and corrupt the payload in a way only the final
+    // digest catches — after the whole transfer completed.
+    const [chunk] = chunkHandoffPayload(ID, 'x'.repeat(30), 10);
+
+    const result = new HandoffChunkAssembler(ID).accept({ ...chunk, data: 'not!valid!base64!' });
+
+    expect(result.rejection).toBe('undecodable');
+  });
+
+  it('a corrupt-but-decodable chunk survives here and is caught by the digest', () => {
+    // The two checks are deliberately different questions. This one asks "did the pieces arrive";
+    // the digest asks "are they the pieces that were sent". Asking the second one per chunk would
+    // report each piece intact while the set is not the set that was sent.
+    const record = {
+      id: 's',
+      cwd: '/w',
+      createdAt: 'a',
+      updatedAt: 'b',
+      messages: [],
+    } as IInteractiveSessionRecord;
+    const { serialized, integrity } = sealHandoffRecord(record);
+    const chunks = chunkHandoffPayload(ID, serialized, 16);
+    const swapped = chunks.map((c, i) =>
+      i === 0 ? { ...c, data: Buffer.from('0'.repeat(16)).toString('base64') } : c,
+    );
+
+    const { last } = assemble(swapped);
+
+    expect(last?.outcome).toBe('complete');
+    expect(verifyHandoffPayload(last?.serialized ?? '', integrity).intact).toBe(false);
+  });
+
+  it('the whole path holds: seal, chunk, reassemble, verify', () => {
+    const record = {
+      id: 'session_1',
+      cwd: '/home/alice/project',
+      createdAt: '2026-08-17T00:00:00.000Z',
+      updatedAt: '2026-08-17T01:00:00.000Z',
+      messages: [{ role: 'user', content: '안녕하세요 😀' }],
+    } as unknown as IInteractiveSessionRecord;
+    const { serialized, integrity } = sealHandoffRecord(record);
+
+    const { last } = assemble(chunkHandoffPayload(ID, serialized, 24));
+
+    expect(verifyHandoffPayload(last?.serialized ?? '', integrity).intact).toBe(true);
+    expect(JSON.parse(last?.serialized ?? '{}')).toEqual(record);
+  });
+});