deepdebug-local-agent 1.3.0 → 1.5.0

package/test/la-protocol-v2/session-outbound.test.js

@@ -0,0 +1,382 @@
+// F3-05b: what the Local Agent sends, and what it does about acks, loss, backpressure and resume.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import { ReferenceCp, ReferenceCpServer, TENANT, AGENT, uuid, waitFor } from "./helpers/reference-cp.js";
+import { inMemory, startRig } from "./helpers/la-rig.js";
+import { sendContent, sendContentFailure } from "../../src/la-protocol-v2/content.js";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+
+const JOB = "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f";
+const REQ = "d4e5f6a7-b8c9-4d0e-9f1a-3b4c5d6e7f80";
+const ev = (state = "running", extra = {}) => ({ jobId: JOB, state, ...extra });
+const contract = loadContract();
+
+async function ready(opts = {}) {
+    const cp = new ReferenceCp(opts.cp);
+    const env = inMemory(cp, opts.la).start();
+    await waitFor(() => env.session.state === "ready");
+    return { cp, ...env };
+}
+
+// ------------------------------------------------------------------------------------------ envelope and numbering
+
+test("outbound: every frame is closed, schema-valid, carries the configured tenant/agent and consecutive seq", async () => {
+    const env = await ready();
+    for (let i = 0; i < 5; i++) await env.session.send("job.event", ev("running", { iteration: i }));
+    await env.session.send("alert", { code: "disk_low", severity: "warn" }).catch(() => {});
+    const frames = env.wire.toCp.map((t) => JSON.parse(t));
+    for (const f of frames) {
+        assert.deepEqual(contract.validateFrame(f), { ok: true }, f.type);
+        assert.equal(f.tenantId, TENANT);
+        assert.equal(f.agentId, AGENT);
+        assert.equal(f.schemaVersion, 2);
+        assert.match(f.msgId, /^[0-9a-f-]{36}$/);
+        assert.equal("sig" in f || "paramsRaw" in f, false, "LA frames are never signed");
+    }
+    assert.deepEqual(frames.filter((f) => f.type === "register" || f.type === "hello").map((f) => f.seq), [0, 0]);
+    assert.deepEqual(env.cp.received.filter((f) => f.type === "job.event").map((f) => f.seq), [1, 2, 3, 4, 5]);
+    assert.equal(new Set(env.cp.received.map((f) => f.msgId)).size, env.cp.received.length, "msgId is unique per frame");
+    env.session.close();
+});
+
+test("outbound: our frames piggyback ack = highest contiguous CP seq received", async () => {
+    const env = await ready();
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    env.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => env.session.lastRecvSeq === 2);
+    await env.session.send("job.event", ev());
+    assert.equal(env.cp.received.at(-1).ack, 2);
+    env.session.close();
+});
+
+test("outbound: heartbeat frames go out on their own, with mode/clock/disk/queue (no paths, no content)", async () => {
+    const env = await ready({ la: { options: { heartbeatMs: 40 } } });
+    await waitFor(() => env.cp.received.filter((f) => f.type === "heartbeat").length >= 2);
+    const hb = env.cp.received.find((f) => f.type === "heartbeat");
+    assert.deepEqual(Object.keys(hb.payload).sort(), ["clockEpochMs", "diskFreeBytes", "inflight", "queueDepth", "signatureMode"]);
+    assert.equal(hb.payload.diskFreeBytes, 1234);
+    assert.equal(hb.payload.signatureMode, "enforce");
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ refusals before a byte is written
+
+const REFUSED = [
+    ["a type outside the allowlist", "shell.exec", {}, "unknown_type"],
+    ["a v1 command name", "mcp.execute-command", {}, "unknown_type"],
+    ["a cp->la type", "job.assign", {}, "wrong_direction"],
+    ["a session type (register)", "register", {}, "wrong_direction"],
+    ["a field the schema does not know", "job.event", ev("running", { stack: "x" }), "schema_violation"],
+    ["a state outside the enum", "job.event", ev("exploded"), "schema_violation"],
+    ["a string above its maxLength", "job.result", { jobId: JOB, outcome: "pr_opened", prUrl: "https://example.com/" + "a".repeat(600) }, "payload_too_large"],
+];
+for (const [name, type, payload, code] of REFUSED) {
+    test(`outbound refusal: ${name} -> ${code}, nothing is written`, async () => {
+        const env = await ready();
+        const before = env.wire.toCp.length;
+        await assert.rejects(env.session.enqueue(type, payload), (e) => e.code === code);
+        assert.equal(env.wire.toCp.length, before);
+        assert.equal(env.session.sendSeq, 0, "a refused frame does not consume a seq");
+        env.session.close();
+    });
+}
+
+test("outbound refusal: before the first ready nothing can be sent (not_ready)", async () => {
+    const cp = new ReferenceCp();
+    const env = inMemory(cp);
+    await assert.rejects(env.session.enqueue("job.event", ev()), (e) => e.code === "not_ready");
+    env.session.close();
+});
+
+test("outbound refusal: the send queue is bounded (rate_limited)", async () => {
+    const env = await ready({ cp: { }, la: { options: { maxInFlight: 1, maxQueued: 3 } } });
+    env.cp.silent = true;
+    const ps = [];
+    for (let i = 0; i < 6; i++) ps.push(env.session.enqueue("job.event", ev()).then(() => "ok", (e) => e.code));
+    const res = await Promise.race([Promise.all(ps), new Promise((r) => setTimeout(() => r(null), 100))]);
+    assert.equal(res, null, "waiting frames keep waiting");
+    const refused = await Promise.all(ps.slice(-2));
+    assert.deepEqual(refused, ["rate_limited", "rate_limited"]);
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ acks, loss, backpressure
+
+test("backpressure: at most maxInFlight frames unacked, the rest wait; when acks resume everything arrives once and in order", async () => {
+    const env = await ready({ cp: { limits: { ackTimeoutMs: 150, maxRetries: 3 } }, la: { options: { maxInFlight: 3 } } });
+    env.cp.silent = true; // acks lost
+    const all = [];
+    for (let i = 0; i < 10; i++) all.push(env.session.send("job.event", ev("running", { iteration: i })));
+    await waitFor(() => env.cp.received.length === 3);
+    await new Promise((r) => setTimeout(r, 40));
+    assert.equal(env.cp.received.length, 3, "never more than maxInFlight on the wire");
+    assert.equal(env.session.snapshot.waiting, 7);
+    assert.equal(env.session.snapshot.unacked, 3);
+    env.cp.silent = false; // the retransmissions of 1..3 are now acked (as duplicates)
+    await Promise.all(all);
+    assert.deepEqual(env.cp.received.map((f) => f.payload.iteration), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    assert.deepEqual(env.cp.received.map((f) => f.seq), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+    assert.ok(env.session.stats.retransmits >= 1, "the lost acks forced a retransmission (cumulative acks settle the rest)");
+    env.session.close();
+});
+
+test("ack lost: the SAME bytes (same seq and msgId) are sent again, the CP sees a duplicate, the caller's ack resolves", async () => {
+    const env = await ready({ cp: { limits: { ackTimeoutMs: 100 } } });
+    env.cp.dropAcks = 1;
+    await env.session.send("job.event", ev());
+    const copies = env.wire.toCp.filter((t) => t.includes('"job.event"'));
+    assert.equal(copies.length, 2);
+    assert.equal(copies[0], copies[1], "a retransmission is byte-identical");
+    assert.deepEqual(env.cp.duplicates, [1]);
+    assert.equal(env.cp.received.length, 1);
+    assert.equal(env.session.stats.retransmits, 1);
+    env.session.close();
+});
+
+test("retries exhausted: the caller gets timeout, the connection is closed with 4420, the frame is kept for a resume", async () => {
+    const env = await ready({ cp: { limits: { ackTimeoutMs: 100, maxRetries: 2 } } });
+    env.cp.silent = true;
+    const h = await env.session.enqueue("job.event", ev());
+    await assert.rejects(h.acked, (e) => e.code === "timeout");
+    assert.deepEqual(env.wire.closed[0], [4420, "ack_timeout"]);
+    assert.equal(env.session.stats.retransmits, 2);
+    assert.equal(env.session.state, "detached");
+    assert.equal(env.session.unacked.size, 1, "kept for the resume");
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ content (chunking)
+
+const bytesOf = (n) => crypto.randomBytes(n);
+
+test("chunking: 100 KiB goes out as 4 ordered chunks, each <= 32 KiB raw, each frame <= 48 KiB, and the CP rebuilds it exactly", async () => {
+    const env = await ready();
+    const data = bytesOf(100 * 1024);
+    const r = await sendContent(env.session, { requestId: REQ, source: data, contentType: "application/octet-stream" });
+    assert.deepEqual(r, { chunks: 4, bytes: data.length });
+    const frames = env.cp.received.filter((f) => f.type === "content.response");
+    assert.deepEqual(frames.map((f) => f.chunk), [0, 1, 2, 3].map((index) => ({ index, total: 4, last: index === 3 })));
+    assert.deepEqual(frames.map((f) => f.payload.byteLength), [32768, 32768, 32768, 4096]);
+    assert.ok(env.cp.rawIn.every((t) => Buffer.byteLength(t) <= 49152));
+    assert.ok(Math.max(...env.cp.rawIn.map((t) => Buffer.byteLength(t))) > 43692, "a full chunk really is that big");
+    assert.equal(frames[0].requestId, REQ);
+    assert.ok(frames.every((f) => f.payload.totalBytes === data.length && f.payload.encoding === "base64"));
+    const c = env.cp.contentRequests.get(REQ);
+    assert.equal(c.done, true);
+    assert.ok(Buffer.concat(c.chunks).equals(data));
+    assert.deepEqual(env.cp.errorsSent, []);
+    env.session.close();
+});
+
+test("chunking: exactly 2 MiB = 64 chunks is accepted, 2 MiB + 1 is refused before a single chunk is sent", async () => {
+    const env = await ready();
+    const max = bytesOf(2 * 1024 * 1024);
+    const r = await sendContent(env.session, { requestId: REQ, source: max });
+    assert.equal(r.chunks, 64);
+    assert.ok(Buffer.concat(env.cp.contentRequests.get(REQ).chunks).equals(max));
+    const before = env.wire.toCp.length;
+    await assert.rejects(sendContent(env.session, { requestId: uuid(), source: bytesOf(2 * 1024 * 1024 + 1) }), (e) => e.code === "payload_too_large");
+    assert.equal(env.wire.toCp.length, before);
+    env.session.close();
+});
+
+test("chunking: empty content is one empty chunk; a failure answer is one empty chunk with the status", async () => {
+    const env = await ready();
+    await sendContent(env.session, { requestId: REQ, source: Buffer.alloc(0), contentType: "text/plain" });
+    const rid2 = uuid();
+    await sendContentFailure(env.session, { requestId: rid2, status: "not_found", errorCode: "internal" });
+    const [a, b] = env.cp.received;
+    assert.deepEqual(a.chunk, { index: 0, total: 1, last: true });
+    assert.equal(a.payload.data, "");
+    assert.equal(b.payload.status, "not_found");
+    assert.deepEqual(b.chunk, { index: 0, total: 1, last: true });
+    env.session.close();
+});
+
+test("chunking + backpressure: with a slow CP never more than maxInFlight chunks are unacked", async () => {
+    const env = await ready({ cp: { }, la: { options: { maxInFlight: 3 } } });
+    env.cp.ackDelayMs = 15;
+    let maxUnacked = 0;
+    env.cp.onReceived = () => { maxUnacked = Math.max(maxUnacked, env.session.unacked.size); };
+    const data = bytesOf(40 * 32768);
+    await sendContent(env.session, { requestId: REQ, source: data });
+    assert.ok(maxUnacked <= 3 && maxUnacked >= 2, `max unacked ${maxUnacked}`);
+    assert.ok(Buffer.concat(env.cp.contentRequests.get(REQ).chunks).equals(data));
+    assert.equal(env.session.stats.retransmits, 0);
+    env.session.close();
+});
+
+test("chunking is lazy: the next chunk is not read until a slot opens (bounded memory)", async () => {
+    const env = await ready({ la: { options: { maxInFlight: 2 } } });
+    env.cp.silent = true;
+    let reads = 0;
+    const source = { size: 10 * 32768, async read(offset, length) { reads++; return Buffer.alloc(length, 1); } };
+    const p = sendContent(env.session, { requestId: REQ, source });
+    p.catch(() => {});
+    await waitFor(() => env.cp.received.length === 2);
+    await new Promise((r) => setTimeout(r, 60));
+    assert.ok(reads <= 3, `read ${reads} chunks while only 2 can be in flight`);
+    env.session.close();
+    await assert.rejects(p);
+});
+
+test("chunking: cancelling (AbortSignal) stops reading and drops the chunks still waiting", async () => {
+    const env = await ready({ la: { options: { maxInFlight: 2 } } });
+    env.cp.ackDelayMs = 30;
+    const ac = new AbortController();
+    let reads = 0;
+    const source = { size: 20 * 32768, async read(o, l) { reads++; if (reads === 4) ac.abort(); return Buffer.alloc(l, 2); } };
+    await assert.rejects(sendContent(env.session, { requestId: REQ, source, signal: ac.signal }), (e) => e.code === "agent_offline");
+    assert.ok(reads <= 5);
+    assert.equal(env.session.snapshot.waiting, 0);
+    env.session.close();
+});
+
+// the chunk rules of the contract applied to what we send (the invalid-chunk-* traces, from the sender's side)
+const CHUNK = (data = Buffer.alloc(26, 1)) => ({ status: "ok", contentType: "text/plain", encoding: "base64", data: data.toString("base64"), byteLength: data.length });
+const BAD_CHUNKS = [
+    ["out of order (0 then 2)", [[0, 3, false], [2, 3, true]], "chunk_out_of_order"],
+    ["after last", [[0, 1, true], [1, 2, true]], "chunk_out_of_order"],
+    ["total changes mid-stream", [[0, 3, false], [1, 4, false]], "chunk_inconsistent"],
+    ["last on the wrong index", [[0, 3, false], [1, 3, true]], "chunk_inconsistent"],
+    ["last missing on the last index", [[0, 1, false]], "chunk_inconsistent"],
+    ["a stream that does not start at 0", [[1, 3, false]], "chunk_out_of_order"],
+];
+for (const [name, steps, code] of BAD_CHUNKS) {
+    test(`chunk rules on send: ${name} -> ${code}`, async () => {
+        const env = await ready();
+        let got = null;
+        for (const [index, total, last] of steps) {
+            try { await env.session.send("content.response", CHUNK(), { requestId: uuid() === "" ? "" : REQ, chunk: { index, total, last } }); }
+            catch (e) { got = e.code; break; }
+        }
+        assert.equal(got, code);
+        env.session.close();
+    });
+}
+
+test("chunk rules on send: byteLength must equal the decoded size; data above 32 KiB raw is refused", async () => {
+    const env = await ready();
+    const p = CHUNK();
+    p.byteLength = 27;
+    await assert.rejects(env.session.send("content.response", p, { requestId: REQ, chunk: { index: 0, total: 1, last: true } }), (e) => e.code === "chunk_inconsistent");
+    const big = bytesOf(32769);
+    await assert.rejects(env.session.send("content.response", { ...CHUNK(big) }, { requestId: uuid(), chunk: { index: 0, total: 1, last: true } }),
+        (e) => ["payload_too_large", "schema_violation", "chunk_inconsistent"].includes(e.code));
+    assert.equal(env.cp.received.length, 0);
+    env.session.close();
+});
+
+// ------------------------------------------------------------------------------------------ resume (real sockets)
+
+// every ws test runs inside withRig: sockets and servers are closed even when an assertion throws
+async function withRig(opts, body) {
+    const srv = await new ReferenceCpServer({ requireEnforce: true, ...(opts.cp || {}) }).start();
+    const rig = startRig(srv, opts.rig);
+    try {
+        await rig.connect();
+        await waitFor(() => rig.session.state === "ready");
+        await body({ srv, rig });
+    } finally {
+        await rig.stop();
+        await srv.stop();
+    }
+}
+
+test("resume: after a dropped socket the LA offers {sessionId,lastRecvSeq}, continues numbering, and the CP gets one copy of everything", async () => {
+    await withRig({}, async ({ srv, rig }) => {
+    rig.session.setHandler("job.cancel", () => ({ accept: true }));
+    await rig.session.send("job.event", ev("running", { iteration: 1 }));
+    await rig.session.send("job.event", ev("running", { iteration: 2 }));
+    srv.cp.sendData("job.cancel", { jobId: JOB, reason: "user" });
+    await waitFor(() => rig.session.lastRecvSeq === 1);
+    const sid = rig.session.sessionId;
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    const queued = rig.session.send("job.event", ev("running", { iteration: 3 })); // queued while detached
+    await rig.connect();
+    await queued;
+    const reg = srv.cp.registers.at(-1);
+    assert.deepEqual(reg.resume, { sessionId: sid, lastRecvSeq: 1 });
+    assert.equal(rig.session.sessionId, sid);
+    assert.deepEqual(srv.cp.received.filter((f) => f.type === "job.event").map((f) => [f.seq, f.payload.iteration]), [[1, 1], [2, 2], [3, 3]]);
+    assert.equal(srv.cp.hellos.length, 2);
+});});
+
+test("resume: frames the CP never saw are sent again (same seq and msgId) and are acked after the reconnect", async () => {
+    await withRig({ cp: { limits: { ackTimeoutMs: 5000 } } }, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const h = await rig.session.enqueue("job.event", ev("running", { iteration: 1 }));
+    await waitFor(() => srv.cp.received.length === 1);
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    srv.cp.silent = false;
+    await rig.connect();
+    await h.acked; // ready{peerLastSeq:1} settles it
+    assert.equal(srv.cp.received.length, 1, "no second copy");
+    assert.equal(rig.session.unacked.size, 0);
+});});
+
+test("resume: a frame lost with the socket is delivered after the reconnect (retransmitted once, not twice)", async () => {
+    await withRig({}, async ({ srv, rig }) => {
+    // write the frame, then lose the connection before the CP reads it
+    srv.ws.pause?.();
+    rig.ws.terminate();
+    await waitFor(() => rig.session.state === "detached");
+    const p = rig.session.send("job.event", ev("running", { iteration: 9 }));
+    await rig.connect();
+    await p;
+    assert.deepEqual(srv.cp.received.map((f) => f.payload.iteration), [9]);
+});});
+
+test("resumed:false (the CP lost the session): numbering restarts at 1 and frames that were in flight fail with agent_offline", async () => {
+    await withRig({}, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const a = await rig.session.enqueue("job.event", ev("running", { iteration: 1 }));
+    const b = await rig.session.enqueue("job.event", ev("running", { iteration: 2 }));
+    await waitFor(() => srv.cp.received.length === 2);
+    const old = rig.session.sessionId;
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    srv.cp.sessionId = uuid(); // the CP has no memory of this session
+    srv.cp.silent = false;
+    await rig.connect();
+    await assert.rejects(a.acked, (e) => e.code === "agent_offline");
+    await assert.rejects(b.acked, (e) => e.code === "agent_offline");
+    assert.notEqual(rig.session.sessionId, old);
+    await rig.session.send("job.event", ev("running", { iteration: 3 }));
+    assert.equal(srv.cp.received.at(-1).seq, 1, "both sides restart at 1");
+});});
+
+test("resume window: after resumeWindowMs a dropped session is forgotten (no resume offered, in-flight fail)", async () => {
+    await withRig({ rig: { options: { resumeWindowMs: 80 } } }, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const h = await rig.session.enqueue("job.event", ev());
+    await waitFor(() => srv.cp.received.length === 1);
+    rig.drop();
+    await waitFor(() => rig.session.state === "idle");
+    await assert.rejects(h.acked, (e) => e.code === "agent_offline");
+    srv.cp.silent = false;
+    await rig.connect();
+    await waitFor(() => rig.session.state === "ready");
+    assert.equal(srv.cp.registers.at(-1).resume, undefined);
+});});
+
+test("resume: a content stream does not survive a reset (its chunks would reach a CP that never saw chunk 0)", async () => {
+    await withRig({ rig: { options: { maxInFlight: 1 } } }, async ({ srv, rig }) => {
+    srv.cp.silent = true;
+    const p = sendContent(rig.session, { requestId: REQ, source: bytesOf(5 * 32768) });
+    p.catch(() => {});
+    await waitFor(() => srv.cp.received.length === 1);
+    rig.drop();
+    await waitFor(() => rig.session.state === "detached");
+    srv.cp.sessionId = uuid();
+    srv.cp.silent = false;
+    await rig.connect();
+    await assert.rejects(p, (e) => e.code === "agent_offline");
+    await new Promise((r) => setTimeout(r, 50));
+    assert.equal(srv.cp.received.filter((f) => f.type === "content.response").length, 1);
+    assert.deepEqual(srv.cp.errorsSent, []);
+});});

package/test/la-protocol-v2/traces.test.js

@@ -0,0 +1,270 @@
+// F3-05b: the 24 whole-session traces of the contract (F3-22), reproduced in Node. "Traces are language
+// neutral; the LA must reproduce each expect.error." Three things are shown for them:
+//   1. the reference CP (test helper) reproduces every trace: same error at the same frame (so the model the
+//      other tests use is the model of the contract);
+//   2. the two traces whose error is in a CP->LA frame (params_mismatch, tenant_mismatch of the signature)
+//      are reproduced by the REAL LA session, same error at the same frame;
+//   3. for the others (an LA frame that the CP refuses) the LA's own send path refuses to produce the same
+//      frame, with the same code; the valid traces are replayed with the LA as the LA.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ReferenceCp, uuid, waitFor } from "./helpers/reference-cp.js";
+import { inMemory, signingFor } from "./helpers/la-rig.js";
+import { V2Session } from "../../src/la-protocol-v2/session.js";
+
+const DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "../contract/la-protocol-v2/vectors/traces");
+const traces = fs.readdirSync(DIR).filter((f) => f.endsWith(".json")).sort().map((f) => ({ file: f, name: f.replace(".json", ""), ...JSON.parse(fs.readFileSync(path.join(DIR, f), "utf8")) }));
+
+test("the suite has all 24 traces (20 invalid, 4 valid)", () => {
+    assert.equal(traces.length, 24);
+    assert.equal(traces.filter((t) => t.expect.ok).length, 4);
+});
+
+const textOf = (fr) => {
+    let text = JSON.stringify(fr.frame);
+    if (fr.inflateBytesTo) text += " ".repeat(Math.max(0, fr.inflateBytesTo - Buffer.byteLength(text)));
+    return text;
+};
+
+/** The reference CP in the state the trace starts from (a resumed session when the trace says so). */
+function cpFor(trace) {
+    const s = trace.session;
+    const cp = new ReferenceCp({ tenantId: s.tenantId, agentId: s.agentId, requireEnforce: s.requireEnforce, now: () => Date.parse(s.now) });
+    const ready = trace.frames.map((f) => f.frame).find((f) => f.type === "ready");
+    const reg = trace.frames.map((f) => f.frame).find((f) => f.type === "register");
+    if (ready && ready.payload.resumed) {
+        cp.sessionStarted = true;
+        cp.sessionId = ready.payload.sessionId;
+        cp.laSeq = ready.payload.peerLastSeq;
+        cp.cpSeq = reg.payload.resume.lastRecvSeq;
+    }
+    cp.attach(() => {}, () => {});
+    return cp;
+}
+
+// ------------------------------------------------------------------------------------------ 1. the reference CP
+
+for (const t of traces) {
+    const cpSideError = t.expect.error && t.frames[t.expect.atFrame].dir === "cp->la";
+    test(`reference CP reproduces ${t.name}${cpSideError ? " (n/a: the error is in a CP frame, see 2)" : ""}`, { skip: cpSideError }, () => {
+        const cp = cpFor(t);
+        let failed = null;
+        for (let i = 0; i < t.frames.length && !failed; i++) {
+            const fr = t.frames[i];
+            if (fr.dir === "cp->la") { cp.cpSeq = Math.max(cp.cpSeq, fr.frame.seq); continue; }
+            const r = cp.feed(textOf(fr));
+            if (r) failed = { error: r.code, atFrame: i };
+        }
+        if (t.expect.ok) {
+            assert.equal(failed, null, JSON.stringify(failed));
+            if (t.expect.duplicateFrames) assert.equal(cp.duplicates.length, t.expect.duplicateFrames.length);
+        } else {
+            assert.deepEqual(failed, { error: t.expect.error, atFrame: t.expect.atFrame });
+        }
+    });
+}
+
+// ------------------------------------------------------------------------------------------ 2. errors in CP frames, by the LA
+
+for (const name of ["invalid-params-raw-differs-from-payload", "invalid-sig-tenant-mismatch"]) {
+    test(`the LA reproduces ${name}: ${traces.find((t) => t.name === name).expect.error} at frame ${traces.find((t) => t.name === name).expect.atFrame}`, async () => {
+        const t = traces.find((x) => x.name === name);
+        const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId });
+        // the trace's signatures are placeholders: mode off skips the cryptography, the structural checks still run
+        const env = inMemory(cp, { mode: "off", tenantId: t.session.tenantId, agentId: t.session.agentId });
+        env.session.attach(env.transport);
+        await waitFor(() => env.session.state === "ready");
+        const bad = t.frames[t.expect.atFrame].frame;
+        env.session.setHandler(bad.type, () => ({ accept: true }));
+        env.session.handleText(JSON.stringify(bad), env.transport);
+        await waitFor(() => cp.peerErrors.length > 0);
+        assert.deepEqual(cp.peerErrors, [t.expect.error]);
+        assert.equal(env.session.stats.dataOut, 0);
+        env.session.close();
+    });
+}
+
+// ------------------------------------------------------------------------------------------ 3. the LA never produces them
+
+const LA_FRAMES = (t) => t.frames.map((f, i) => ({ ...f, i })).filter((f) => f.dir === "la->cp");
+
+async function readyLa() {
+    const cp = new ReferenceCp();
+    const env = inMemory(cp).start();
+    await waitFor(() => env.session.state === "ready");
+    return { cp, ...env };
+}
+
+for (const name of ["invalid-chunk-after-last", "invalid-chunk-byte-length-mismatch", "invalid-chunk-last-flag", "invalid-chunk-out-of-order", "invalid-chunk-total-changes", "invalid-payload-above-limit"]) {
+    test(`the LA refuses to send the chunks of ${name}: same code at the same frame`, async () => {
+        const t = traces.find((x) => x.name === name);
+        const { cp, session } = await readyLa();
+        let got = null;
+        for (const fr of LA_FRAMES(t)) {
+            if (fr.frame.type !== "content.response") continue;
+            try {
+                await session.enqueue("content.response", fr.frame.payload, { requestId: fr.frame.requestId, chunk: fr.frame.chunk }).then((h) => h.acked);
+            } catch (e) { got = { error: e.code, atFrame: fr.i }; break; }
+        }
+        // the oversized trace chunk is refused by the schema (payload maxLength), which the CP reports as payload_too_large
+        assert.deepEqual(got, { error: t.expect.error, atFrame: t.expect.atFrame });
+        assert.deepEqual(cp.errorsSent, [], "nothing invalid reached the CP");
+        session.close();
+    });
+}
+
+test("the LA never produces invalid-event-before-ready / invalid-first-frame-not-register: register and hello first, no data before ready", async () => {
+    const cp = new ReferenceCp();
+    const sent = [];
+    const env = inMemory(cp);
+    const swallow = { send: (t) => sent.push(JSON.parse(t)), close() {}, bufferedAmount: () => 0 };
+    env.session.attach(swallow);
+    assert.deepEqual(sent.map((f) => f.type), ["register", "hello"], "the first frame is register, then hello");
+    await assert.rejects(env.session.enqueue("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" }), (e) => e.code === "not_ready");
+    assert.equal(sent.length, 2);
+    env.session.close();
+});
+
+test("the LA never produces invalid-clock-skew: register.ts is the clock of the LA, hello carries clockEpochMs", async () => {
+    const cp = new ReferenceCp();
+    const sent = [];
+    const env = inMemory(cp);
+    env.session.attach({ send: (t) => sent.push(JSON.parse(t)), close() {}, bufferedAmount: () => 0 });
+    assert.ok(Math.abs(Date.parse(sent[0].ts) - Date.now()) < 2000);
+    assert.ok(Math.abs(sent[1].payload.clockEpochMs - Date.now()) < 2000);
+    env.session.close();
+});
+
+test("the LA never produces invalid-signature-warn-with-enforce-required: hello.signatureMode is the real mode, and a CP that requires enforce says so", async () => {
+    const cp = new ReferenceCp({ requireEnforce: true });
+    const env = inMemory(cp, { mode: "warn" }).start();
+    await waitFor(() => cp.errorsSent.length > 0);
+    assert.deepEqual(cp.errorsSent, ["signature_mode_insufficient"]);
+    assert.equal(env.session.state, "await_ready"); // not ready, no data possible
+    assert.equal(cp.hellos.length, 0);
+    env.session.close();
+});
+
+test("the LA never produces invalid-agent-mismatch / invalid-tenant-mismatch: every frame carries the configured ids, never one from a payload", async () => {
+    const { cp, session } = await readyLa();
+    await session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" });
+    for (const f of cp.received) {
+        assert.equal(f.tenantId, cp.tenantId);
+        assert.equal(f.agentId, cp.agentId);
+    }
+    // there is no way to pass an identity to enqueue(); a payload that tries is refused by the closed schema
+    await assert.rejects(session.enqueue("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", tenantId: "99999999-5a4d-4e7b-9c21-0a1b2c3d4e5f" }), (e) => e.code === "schema_violation");
+    session.close();
+});
+
+test("the LA never produces invalid-la-sends-job-assign / invalid-type-outside-allowlist", async () => {
+    const { cp, session } = await readyLa();
+    await assert.rejects(session.enqueue("job.assign", {}), (e) => e.code === "wrong_direction");
+    await assert.rejects(session.enqueue("shell.exec", {}), (e) => e.code === "unknown_type");
+    assert.deepEqual(cp.errorsSent, []);
+    session.close();
+});
+
+test("the LA never produces invalid-seq-gap / invalid-seq-repeated / invalid-resume-restarts-seq: consecutive seq, one msgId per seq, a resume continues", async () => {
+    const { cp, session } = await readyLa();
+    for (let i = 0; i < 4; i++) await session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", iteration: i });
+    assert.deepEqual(cp.received.map((f) => f.seq), [1, 2, 3, 4]);
+    assert.equal(new Set(cp.received.map((f) => f.msgId)).size, 4);
+    assert.deepEqual(cp.errorsSent, []);
+    session.close();
+});
+
+test("the LA never produces invalid-frame-over-48kib: frames are compact JSON and the size is checked before sending", async () => {
+    const { cp, session } = await readyLa();
+    await assert.rejects(session.enqueue("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", phase: "x".repeat(60_000) }), (e) => ["frame_too_large", "payload_too_large", "schema_violation"].includes(e.code));
+    // and the same frame as the trace has it (padded to 50000 bytes) is refused on the way IN as frame_too_large
+    const t = traces.find((x) => x.name === "invalid-frame-over-48kib");
+    const fr = t.frames[t.expect.atFrame];
+    const { transport } = { transport: session.transport };
+    session.handleText(textOf(fr), transport);
+    await waitFor(() => cp.peerErrors.length > 0);
+    assert.deepEqual(cp.peerErrors, ["frame_too_large"]);
+    session.close();
+});
+
+// ------------------------------------------------------------------------------------------ valid traces, LA as the LA
+
+test("valid-handshake-and-job: CP job.assign -> LA acks it (ackSeq 1) and then reports job.event x2 + job.result with seq 1..3", async () => {
+    const t = traces.find((x) => x.name === "valid-handshake-and-job");
+    const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId, requireEnforce: true });
+    const env = inMemory(cp, { tenantId: t.session.tenantId, agentId: t.session.agentId }).start();
+    await waitFor(() => env.session.state === "ready");
+    const assign = t.frames.find((f) => f.frame.type === "job.assign").frame;
+    env.session.setHandler("job.assign", (ctx) => { assert.deepEqual(ctx.params, assign.payload); return { accept: true }; });
+    cp.sendData("job.assign", assign.payload, { workspaceId: assign.workspaceId, requestId: assign.requestId });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.deepEqual(cp.acksFromLa[0], { ackSeq: 1, status: "accepted", errorCode: undefined });
+    for (const fr of LA_FRAMES(t).filter((f) => ["job.event", "job.result"].includes(f.frame.type))) {
+        await env.session.send(fr.frame.type, fr.frame.payload, { workspaceId: fr.frame.workspaceId });
+    }
+    assert.deepEqual(cp.received.map((f) => [f.type, f.seq]), [["job.event", 1], ["job.event", 2], ["job.result", 3]]);
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("valid-content-chunks-in-order: the three chunks of the trace go out in order and the CP accepts them", async () => {
+    const t = traces.find((x) => x.name === "valid-content-chunks-in-order");
+    const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId });
+    const env = inMemory(cp, { tenantId: t.session.tenantId, agentId: t.session.agentId }).start();
+    await waitFor(() => env.session.state === "ready");
+    for (const fr of LA_FRAMES(t).filter((f) => f.frame.type === "content.response")) {
+        await env.session.send("content.response", fr.frame.payload, { requestId: fr.frame.requestId, chunk: fr.frame.chunk, workspaceId: fr.frame.workspaceId });
+    }
+    assert.deepEqual(cp.received.map((f) => [f.seq, f.chunk.index]), [[1, 0], [2, 1], [3, 2]]);
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("valid-retransmit-is-idempotent: an ack lost -> the same frame again -> the CP re-acks and counts one event", async () => {
+    const cp = new ReferenceCp({ limits: { ackTimeoutMs: 100 } });
+    const env = inMemory(cp).start();
+    await waitFor(() => env.session.state === "ready");
+    cp.dropAcks = 1;
+    await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" });
+    await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "succeeded" });
+    assert.deepEqual(cp.duplicates, [1]);
+    assert.deepEqual(cp.received.map((f) => f.seq), [1, 2]);
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("valid-resume-continues-seq: after a resumed ready the LA continues at peerLastSeq+1", async () => {
+    const t = traces.find((x) => x.name === "valid-resume-continues-seq");
+    const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId });
+    const env = inMemory(cp, { tenantId: t.session.tenantId, agentId: t.session.agentId });
+    // first life: 5 events delivered
+    env.session.attach(env.transport);
+    await waitFor(() => env.session.state === "ready");
+    for (let i = 0; i < 5; i++) await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", iteration: i });
+    // the CP also sent 4 frames
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    for (let i = 0; i < 4; i++) cp.sendData("job.cancel", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", reason: "user" });
+    await waitFor(() => env.session.lastRecvSeq === 4);
+    // second life: same session object (the LA process kept it), new connection
+    const t2 = { send: (x) => { env.wire.toCp.push(x); cp.feed(x); }, close() {}, bufferedAmount: () => 0 };
+    env.session.detach(env.transport);
+    cp.attach((x) => queueMicrotask(() => env.session.handleText(x, t2)), () => {});
+    env.session.attach(t2);
+    await waitFor(() => env.session.state === "ready");
+    assert.deepEqual(cp.registers.at(-1).resume, { sessionId: cp.sessionId, lastRecvSeq: 4 });
+    await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", iteration: 5 });
+    assert.equal(cp.received.at(-1).seq, 6, "continues at peerLastSeq + 1");
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("V2Session is exported and constructible without side effects (no timers left running)", () => {
+    const cp = new ReferenceCp();
+    const s = new V2Session({ tenantId: cp.tenantId, agentId: cp.agentId, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }), laVersion: "1.3.0" });
+    assert.equal(s.state, "idle");
+    s.close();
+    assert.equal(uuid().length, 36);
+});