@openwop/openwop-conformance 1.0.0 → 1.1.1

package/src/lib/a2a-fake-peer.ts

@@ -3,24 +3,29 @@
  *
  * The A2A protocol (https://a2a-protocol.org/) defines an `AgentCard` for
  * discovery plus a Task lifecycle whose `TaskState` enum drives most of
- * the conformance burden. We expose just enough of the HTTP+JSON
+ * the conformance burden. We expose just enough of A2A v0.3 JSON-RPC
  * transport to let conformance scenarios drive the host through the
  * four documented drift points from `spec/v1/a2a-integration.md`
  * §"State projection".
  *
- * Endpoints (minimal):
- *   GET  /agent.json                 — AgentCard
- *   POST /tasks                      — create a task; returns { taskId, state: 'SUBMITTED' }
- *   GET  /tasks/{taskId}             — poll task state + last message
- *   POST /tasks/{taskId}/messages    — append a message (used by host to resume an INPUT_REQUIRED task)
+ * Endpoints (A2A v0.3 wire shape):
+ *   GET  /.well-known/agent-card.json — AgentCard at the spec-mandated
+ *                                       well-known path (per
+ *                                       @a2a-js/sdk@0.3.13 `AGENT_CARD_PATH`)
+ *   POST /a2a/jsonrpc                  — JSON-RPC dispatch:
+ *                                          - method `message/send` →
+ *                                            creates a Task, returns Task obj
+ *                                          - method `tasks/get` → fetches Task
  *
  * Test fixtures set the *next* state transition via `setNextState(...)`
  * so a single scenario can walk the peer through SUBMITTED → WORKING →
  * INPUT_REQUIRED → COMPLETED (or AUTH_REQUIRED, or REJECTED) without
- * implementing a real agent.
+ * implementing a real agent. The internal API uses the UPPERCASE enum
+ * from openwop's a2a-integration.md (which references the gRPC enum);
+ * wire responses use the v0.3 JSON-RPC lowercase-hyphen form.
  *
  * @see spec/v1/a2a-integration.md §"State projection"
- * @see https://a2a-protocol.org/latest/specification/
+ * @see https://a2a-protocol.org/v0.3.0/specification
  */
 
 import { createServer, type Server } from 'node:http';
@@ -37,16 +42,32 @@ export type A2ATaskState =
   | 'CANCELED'
   | 'REJECTED';
 
+/** Translate internal UPPERCASE state to A2A v0.3 wire form (lowercase + hyphen). */
+function wireState(s: A2ATaskState): string {
+  switch (s) {
+    case 'UNSPECIFIED': return 'unknown';
+    case 'SUBMITTED': return 'submitted';
+    case 'WORKING': return 'working';
+    case 'INPUT_REQUIRED': return 'input-required';
+    case 'AUTH_REQUIRED': return 'auth-required';
+    case 'COMPLETED': return 'completed';
+    case 'FAILED': return 'failed';
+    case 'CANCELED': return 'canceled';
+    case 'REJECTED': return 'rejected';
+  }
+}
+
 interface A2ATask {
-  taskId: string;
+  id: string;
+  contextId: string;
   state: A2ATaskState;
-  messages: Array<{ role: 'user' | 'agent'; content: unknown }>;
-  metadata?: Record<string, unknown>;
+  history: Array<{ role: 'user' | 'agent'; parts: unknown[] }>;
 }
 
 export interface A2APeerInvocation {
   readonly method: string;
   readonly path: string;
+  readonly rpcMethod: string | null;
   readonly body: unknown;
   readonly timestamp: number;
 }
@@ -61,7 +82,14 @@ export class A2AFakePeer {
 
   async start(port: number = 0): Promise<void> {
     return new Promise((resolve, reject) => {
-      const server = createServer((req, res) => this._handle(req, res));
+      const server = createServer((req, res) => {
+        this._handle(req, res).catch((err) => {
+          if (!res.headersSent) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(err) }));
+          }
+        });
+      });
       server.on('error', reject);
       server.listen(port, '127.0.0.1', () => {
         const addr = server.address() as AddressInfo;
@@ -121,6 +149,21 @@ export class A2AFakePeer {
     return this._tasks.get(taskId);
   }
 
+  private _taskToWire(t: A2ATask): Record<string, unknown> {
+    return {
+      id: t.id,
+      kind: 'task',
+      contextId: t.contextId,
+      status: { state: wireState(t.state) },
+      history: t.history.map((m) => ({
+        kind: 'message',
+        role: m.role,
+        parts: m.parts,
+        messageId: `msg-${t.id}-${t.history.indexOf(m)}`,
+      })),
+    };
+  }
+
   private async _handle(
     req: import('node:http').IncomingMessage,
     res: import('node:http').ServerResponse,
@@ -138,82 +181,126 @@ export class A2AFakePeer {
       }
     }
 
+    const rpcMethod =
+      body && typeof body === 'object' && body !== null && 'method' in body
+        ? String((body as { method: unknown }).method)
+        : null;
+
     this._invocations.push({
       method: req.method ?? 'GET',
       path: url,
+      rpcMethod,
       body,
       timestamp: Date.now(),
     });
 
-    // GET /agent.json
-    if (req.method === 'GET' && url.startsWith('/agent.json')) {
+    // GET /.well-known/agent-card.json  — A2A v0.3 well-known path
+    if (req.method === 'GET' && url.startsWith('/.well-known/agent-card.json')) {
       const card = {
         protocolVersion: '0.3.0',
         name: 'openwop-conformance-fake-a2a',
         description: 'Synthetic A2A peer for openwop conformance suite',
-        url: this.endpoint(),
+        url: `${this.endpoint()}/a2a/jsonrpc`,
         version: '1.0.0',
-        capabilities: { streaming: false },
+        capabilities: { streaming: false, pushNotifications: false },
         skills: [
           {
             id: 'echo',
             name: 'echo',
             description: 'Returns input verbatim',
+            tags: ['echo'],
           },
         ],
+        defaultInputModes: ['text'],
+        defaultOutputModes: ['text'],
+        additionalInterfaces: [
+          { url: `${this.endpoint()}/a2a/jsonrpc`, transport: 'JSONRPC' },
+        ],
       };
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify(card));
       return;
     }
 
-    // POST /tasks — create task
-    if (req.method === 'POST' && url === '/tasks') {
-      const taskId = `task-${++this._taskIdCounter}`;
-      const initial: A2ATaskState = this._nextStateOverride ?? 'SUBMITTED';
-      this._nextStateOverride = null;
-      const task: A2ATask = {
-        taskId,
-        state: initial,
-        messages: body && typeof body === 'object' ? [{ role: 'user', content: body }] : [],
-      };
-      this._tasks.set(taskId, task);
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ taskId, state: task.state }));
-      return;
-    }
+    // POST /a2a/jsonrpc  — A2A v0.3 JSON-RPC transport
+    if (req.method === 'POST' && url === '/a2a/jsonrpc') {
+      if (
+        !body ||
+        typeof body !== 'object' ||
+        (body as { jsonrpc?: unknown }).jsonrpc !== '2.0'
+      ) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32600, message: 'Invalid JSON-RPC envelope' },
+          }),
+        );
+        return;
+      }
+      const rpc = body as { id?: string | number; method?: string; params?: unknown };
 
-    // GET /tasks/{taskId}
-    const getMatch = url.match(/^\/tasks\/([^/?]+)$/);
-    if (req.method === 'GET' && getMatch) {
-      const task = this._tasks.get(decodeURIComponent(getMatch[1]));
-      if (!task) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'not_found' }));
+      if (rpc.method === 'message/send') {
+        const taskId = `task-${++this._taskIdCounter}`;
+        const contextId = `ctx-${taskId}`;
+        const initial: A2ATaskState = this._nextStateOverride ?? 'SUBMITTED';
+        this._nextStateOverride = null;
+        const userMessage = (rpc.params as { message?: { parts?: unknown[] } } | undefined)
+          ?.message;
+        const task: A2ATask = {
+          id: taskId,
+          contextId,
+          state: initial,
+          history: userMessage
+            ? [{ role: 'user', parts: userMessage.parts ?? [] }]
+            : [],
+        };
+        this._tasks.set(taskId, task);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            id: rpc.id ?? null,
+            result: this._taskToWire(task),
+          }),
+        );
         return;
       }
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify(task));
-      return;
-    }
 
-    // POST /tasks/{taskId}/messages — host resumes an INPUT_REQUIRED task
-    const msgMatch = url.match(/^\/tasks\/([^/?]+)\/messages$/);
-    if (req.method === 'POST' && msgMatch) {
-      const task = this._tasks.get(decodeURIComponent(msgMatch[1]));
-      if (!task) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'not_found' }));
+      if (rpc.method === 'tasks/get') {
+        const params = (rpc.params ?? {}) as { id?: string };
+        const task = params.id ? this._tasks.get(params.id) : undefined;
+        if (!task) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(
+            JSON.stringify({
+              jsonrpc: '2.0',
+              id: rpc.id ?? null,
+              error: { code: -32001, message: 'Task not found' },
+            }),
+          );
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            id: rpc.id ?? null,
+            result: this._taskToWire(task),
+          }),
+        );
         return;
       }
-      task.messages.push({ role: 'user', content: body });
-      // Move from INPUT_REQUIRED back to WORKING then to COMPLETED for the
-      // simple roundtrip. Tests that need a different next-state set it
-      // via setNextState() before posting the message.
-      task.state = this._nextStateOverride ?? 'COMPLETED';
-      this._nextStateOverride = null;
+
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ taskId: task.taskId, state: task.state }));
+      res.end(
+        JSON.stringify({
+          jsonrpc: '2.0',
+          id: rpc.id ?? null,
+          error: { code: -32601, message: `Method not found: ${rpc.method}` },
+        }),
+      );
       return;
     }
 

package/src/lib/behavior-gate.ts

@@ -0,0 +1,107 @@
+/**
+ * Behavior-gate helper for capability-gated conformance scenarios.
+ *
+ * Some scenarios in `conformance/src/scenarios/` validate optional profiles
+ * — audit-log integrity, rate-limit envelope, multi-region idempotency,
+ * `configurableSchema`, webhook signature versioning, pause/resume, etc.
+ * When a host doesn't advertise the profile, those scenarios have two
+ * defensible modes:
+ *
+ *   - **Default (skip):** log a warning and return early. The suite still
+ *     passes overall, reflecting what the host has implemented. This is
+ *     what `@openwop/openwop-conformance` runs by default so a v1.0-only
+ *     host doesn't suddenly fail the suite when new optional profiles ship.
+ *
+ *   - **Behavior-required (fail):** set `OPENWOP_REQUIRE_BEHAVIOR=true` to
+ *     turn missing advertisements into hard failures. A "passing" run with
+ *     this flag means the host advertises every optional profile AND every
+ *     scenario exercises real behavior — useful for hosts that want to
+ *     claim full coverage in `INTEROP-MATRIX.md`.
+ *
+ *   - **Strict-mode opt-out (skip in strict mode too):** set
+ *     `OPENWOP_OPTED_OUT_PROFILES=name1,name2,...` to declare that the
+ *     host operator has deliberately chosen NOT to implement those
+ *     profiles. In strict mode the gate skips them with a "honest
+ *     opt-out" log line instead of failing — minimal hosts that
+ *     advertise only what they implement can still go strict-mode
+ *     green without falsifying capability claims. Conflict check:
+ *     if a profile appears in BOTH `OPENWOP_OPTED_OUT_PROFILES` AND
+ *     the host's discovery `capabilities.auth.profiles[]` (or
+ *     equivalent), the gate logs a loud warning — opt-outs and
+ *     advertisements are mutually exclusive.
+ *
+ * Usage:
+ *
+ *   ```ts
+ *   import { behaviorGate } from '../lib/behavior-gate.js';
+ *
+ *   it('host that claims the profile advertises the right fields', async () => {
+ *     const advertised = await isProfileAdvertised();
+ *     if (!behaviorGate('openwop-audit-log-integrity', advertised)) {
+ *       return; // skipped in default mode; FAIL'd in strict mode
+ *     }
+ *
+ *     // ... assertions ...
+ *   });
+ *   ```
+ *
+ * In strict mode, `behaviorGate` throws an assertion error with a citation
+ * to the relevant spec section so the failure message is self-explanatory.
+ */
+
+import { expect } from 'vitest';
+import { loadEnv } from './env.js';
+
+/**
+ * Returns true if the scenario should proceed with assertions (advertised),
+ * false if the scenario should `return` early (default-mode skip OR
+ * strict-mode honest opt-out). In strict mode (`OPENWOP_REQUIRE_BEHAVIOR=true`)
+ * with `profileName` NOT in `OPENWOP_OPTED_OUT_PROFILES`, throws — so the
+ * caller never receives `false` in that combination.
+ *
+ * If the host BOTH advertises the profile AND the operator listed it in
+ * the opt-out env var, surface a warning (likely typo) and treat as
+ * advertised (proceed). Advertisement always wins over opt-out: opting
+ * out of a profile you actually implement is meaningless.
+ */
+export function behaviorGate(profileName: string, advertised: boolean): boolean {
+  const env = loadEnv();
+  const optedOut = env.optedOutProfiles.has(profileName);
+
+  if (advertised && optedOut) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[${profileName}] both ADVERTISED by the host AND listed in OPENWOP_OPTED_OUT_PROFILES — ` +
+        `opt-out is ignored. Remove from the env var to clear this warning.`,
+    );
+  }
+
+  if (advertised) return true;
+
+  if (optedOut) {
+    // Honest opt-out: the operator declared the host does not implement
+    // this profile. Skip in BOTH default and strict mode.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[${profileName}] honest opt-out (OPENWOP_OPTED_OUT_PROFILES); skipping`,
+    );
+    return false;
+  }
+
+  if (env.requireBehavior) {
+    expect(
+      advertised,
+      `OPENWOP_REQUIRE_BEHAVIOR=true: host MUST advertise the ${profileName} profile for this scenario to run, ` +
+        `or declare opt-out via OPENWOP_OPTED_OUT_PROFILES=${profileName}. ` +
+        `See conformance/coverage.md §"Capability-gated scenarios".`,
+    ).toBe(true);
+    // expect.toBe(true) throws; we won't reach here.
+  }
+
+  // Default-mode soft-skip.
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[${profileName}] profile not advertised; skipping (set OPENWOP_REQUIRE_BEHAVIOR=true to fail)`,
+  );
+  return false;
+}

package/src/lib/env.ts

@@ -8,6 +8,23 @@
  * Optional (cosmetic — surfaced in failure messages):
  *   OPENWOP_IMPLEMENTATION_NAME    — e.g., "acme-openwop-server"
  *   OPENWOP_IMPLEMENTATION_VERSION — e.g., "1.0"
+ *
+ * Optional (behavior-gate strictness):
+ *   OPENWOP_REQUIRE_BEHAVIOR=true — capability-gated scenarios (audit-log
+ *     integrity, rate-limit envelope, multi-region idempotency, etc.) FAIL
+ *     instead of skipping when the host doesn't advertise the profile.
+ *     Default is false — scenarios skip with a warning so default conformance
+ *     runs cover what the host has implemented. See `lib/behavior-gate.ts`
+ *     and `conformance/coverage.md` §"Capability-gated scenarios".
+ *
+ *   OPENWOP_OPTED_OUT_PROFILES — comma-separated profile names the host
+ *     operator has DELIBERATELY chosen not to implement. In strict mode
+ *     these scenarios skip (logged as "honest opt-out") rather than
+ *     failing — distinguishes "host doesn't claim this surface" (good)
+ *     from "host claims but doesn't deliver" (bug). Lets honest minimal
+ *     hosts go strict-mode green without falsifying capability claims.
+ *     Example for SQLite:
+ *       OPENWOP_OPTED_OUT_PROFILES=openwop-production,openwop-auth-mtls
  */
 
 export interface ConformanceEnv {
@@ -15,6 +32,16 @@ export interface ConformanceEnv {
   readonly apiKey: string;
   readonly implementationName: string;
   readonly implementationVersion: string;
+  readonly requireBehavior: boolean;
+  /**
+   * Profiles the host operator has declared the host does NOT claim. Set
+   * via `OPENWOP_OPTED_OUT_PROFILES=name1,name2`. In strict mode, the
+   * behavior-gate honors this set as PASS-by-opt-out rather than failing
+   * the scenario. Never include a profile the host actually advertises —
+   * that's a typo, not an opt-out, and `behaviorGate` will surface a
+   * warning if it detects the conflict.
+   */
+  readonly optedOutProfiles: ReadonlySet<string>;
 }
 
 let cached: ConformanceEnv | null = null;
@@ -39,11 +66,21 @@ export function loadEnv(): ConformanceEnv {
   // Strip trailing slash so URL composition is consistent.
   const normalizedBase = baseUrl.replace(/\/$/, '');
 
+  const optedOutRaw = process.env.OPENWOP_OPTED_OUT_PROFILES?.trim() ?? '';
+  const optedOutProfiles = new Set(
+    optedOutRaw
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0),
+  );
+
   cached = {
     baseUrl: normalizedBase,
     apiKey,
     implementationName: process.env.OPENWOP_IMPLEMENTATION_NAME?.trim() ?? 'unknown',
     implementationVersion: process.env.OPENWOP_IMPLEMENTATION_VERSION?.trim() ?? 'unknown',
+    requireBehavior: process.env.OPENWOP_REQUIRE_BEHAVIOR === 'true',
+    optedOutProfiles,
   };
   return cached;
 }

package/src/lib/grpc-framing.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Unit tests for `grpc-framing.ts` — gRPC HTTP/2 message framing.
+ *
+ * @see grpc-framing.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import { frameMessage, unframeMessages } from './grpc-framing.js';
+
+describe('grpc-framing: frameMessage', () => {
+  it('prepends a 5-byte header to a single payload', () => {
+    const payload = new Uint8Array([0xab, 0xcd, 0xef]);
+    const framed = frameMessage(payload);
+    expect(framed.byteLength).toBe(8);
+    expect(framed[0]).toBe(0); // identity compression
+    expect(framed[1]).toBe(0);
+    expect(framed[2]).toBe(0);
+    expect(framed[3]).toBe(0);
+    expect(framed[4]).toBe(3); // length = 3
+    expect(framed[5]).toBe(0xab);
+    expect(framed[6]).toBe(0xcd);
+    expect(framed[7]).toBe(0xef);
+  });
+
+  it('frames a zero-length payload as a 5-byte header alone', () => {
+    const framed = frameMessage(new Uint8Array(0));
+    expect(framed.byteLength).toBe(5);
+    expect(framed[0]).toBe(0);
+    expect(framed[4]).toBe(0);
+  });
+
+  it('encodes lengths > 256 in big-endian order', () => {
+    const payload = new Uint8Array(300);
+    const framed = frameMessage(payload);
+    // length = 300 = 0x0000012C, big-endian: 00 00 01 2C
+    expect(framed[1]).toBe(0);
+    expect(framed[2]).toBe(0);
+    expect(framed[3]).toBe(1);
+    expect(framed[4]).toBe(0x2c);
+  });
+});
+
+describe('grpc-framing: unframeMessages', () => {
+  it('parses a single frame', () => {
+    const payload = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+    const framed = frameMessage(payload);
+    const messages = unframeMessages(framed);
+    expect(messages.length).toBe(1);
+    expect(Array.from(messages[0]!)).toEqual([0x01, 0x02, 0x03, 0x04]);
+  });
+
+  it('parses multiple concatenated frames', () => {
+    const a = frameMessage(new Uint8Array([0xaa, 0xab]));
+    const b = frameMessage(new Uint8Array([0xbb]));
+    const c = frameMessage(new Uint8Array([0xcc, 0xcd, 0xce, 0xcf]));
+    const combined = new Uint8Array(a.byteLength + b.byteLength + c.byteLength);
+    combined.set(a, 0);
+    combined.set(b, a.byteLength);
+    combined.set(c, a.byteLength + b.byteLength);
+    const messages = unframeMessages(combined);
+    expect(messages.length).toBe(3);
+    expect(Array.from(messages[0]!)).toEqual([0xaa, 0xab]);
+    expect(Array.from(messages[1]!)).toEqual([0xbb]);
+    expect(Array.from(messages[2]!)).toEqual([0xcc, 0xcd, 0xce, 0xcf]);
+  });
+
+  it('parses an empty buffer as zero frames', () => {
+    expect(unframeMessages(new Uint8Array(0))).toEqual([]);
+  });
+
+  it('throws on truncated header', () => {
+    // Only 3 bytes of a 5-byte header.
+    const buf = new Uint8Array([0, 0, 0]);
+    expect(() => unframeMessages(buf)).toThrow(/frame truncated/i);
+  });
+
+  it('throws on truncated payload', () => {
+    // 5-byte header declares 10 bytes of payload but only 4 follow.
+    const buf = new Uint8Array([0, 0, 0, 0, 10, 1, 2, 3, 4]);
+    expect(() => unframeMessages(buf)).toThrow(/payload truncated/i);
+  });
+
+  it('throws on unsupported compression flag', () => {
+    // Flag = 1 → compression negotiated, which we don't implement.
+    const buf = new Uint8Array([1, 0, 0, 0, 0]);
+    expect(() => unframeMessages(buf)).toThrow(/compression flag/i);
+  });
+
+  it('round-trips: frame → unframe yields original payload', () => {
+    const original = new Uint8Array([0x0a, 0x05, 0x68, 0x65, 0x6c, 0x6c, 0x6f]); // protobuf "hello"
+    const framed = frameMessage(original);
+    const unframed = unframeMessages(framed);
+    expect(unframed.length).toBe(1);
+    expect(Array.from(unframed[0]!)).toEqual(Array.from(original));
+  });
+});

package/src/lib/grpc-framing.ts

@@ -0,0 +1,76 @@
+/**
+ * gRPC HTTP/2 message framing primitive — Track 11 OTLP/gRPC.
+ *
+ * gRPC over HTTP/2 wraps each protobuf message in a 5-byte frame
+ * prefix:
+ *
+ *   ┌──────────┬───────────────────────┬─────────────────────┐
+ *   │ 1 byte   │ 4 bytes               │ N bytes             │
+ *   │ flags    │ length (big-endian)   │ payload             │
+ *   └──────────┴───────────────────────┴─────────────────────┘
+ *
+ * `flags` is `0x00` for uncompressed (the only mode we implement).
+ * `0x01` indicates a per-message compression scheme negotiated via
+ * the `grpc-encoding` header; we reject this since the conformance
+ * collector advertises identity encoding only.
+ *
+ * Multiple frames MAY be concatenated in a stream; for OTLP Export
+ * unary calls the request and response both carry exactly one frame.
+ *
+ * Pure stdlib — no `@grpc/grpc-js` dependency. Matches the
+ * zero-new-deps stance of `otlp-protobuf.ts` (the hand-rolled
+ * decoder for the OTLP message bodies).
+ *
+ * @see https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
+ */
+
+/** Length-prefix a single protobuf payload with the gRPC 5-byte frame. */
+export function frameMessage(payload: Uint8Array): Uint8Array {
+  const out = new Uint8Array(5 + payload.byteLength);
+  out[0] = 0; // compression flag — identity
+  // Big-endian 32-bit length
+  out[1] = (payload.byteLength >>> 24) & 0xff;
+  out[2] = (payload.byteLength >>> 16) & 0xff;
+  out[3] = (payload.byteLength >>> 8) & 0xff;
+  out[4] = payload.byteLength & 0xff;
+  out.set(payload, 5);
+  return out;
+}
+
+/**
+ * Parse one or more gRPC-framed messages from a concatenated buffer.
+ * Throws if any frame uses a compression scheme we don't implement,
+ * or if the buffer truncates mid-frame.
+ */
+export function unframeMessages(buf: Uint8Array): Uint8Array[] {
+  const out: Uint8Array[] = [];
+  let i = 0;
+  while (i < buf.byteLength) {
+    if (i + 5 > buf.byteLength) {
+      throw new Error(
+        `gRPC frame truncated: need 5-byte header at offset ${i}, have ${buf.byteLength - i}`,
+      );
+    }
+    const flag = buf[i]!;
+    if (flag !== 0) {
+      throw new Error(
+        `gRPC frame at offset ${i} has compression flag ${flag}; only identity (0) is supported`,
+      );
+    }
+    const len =
+      ((buf[i + 1]! << 24) >>> 0) |
+      ((buf[i + 2]! << 16) >>> 0) |
+      ((buf[i + 3]! << 8) >>> 0) |
+      buf[i + 4]!;
+    const payloadStart = i + 5;
+    const payloadEnd = payloadStart + len;
+    if (payloadEnd > buf.byteLength) {
+      throw new Error(
+        `gRPC frame payload truncated: declared length ${len} at offset ${i + 1}, but only ${buf.byteLength - payloadStart} bytes remain`,
+      );
+    }
+    out.push(buf.subarray(payloadStart, payloadEnd));
+    i = payloadEnd;
+  }
+  return out;
+}