deepdebug-local-agent 1.3.0 → 1.4.0

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);
+});

package/test/la-protocol-v2/tunnel-e2e.test.js

@@ -0,0 +1,124 @@
+// F3-05b end to end: the real agent process (src/server.js) against the reference CP.
+//  - flag unset / false: the v1 client, nothing of v2 on the wire (characterization; the frames are the v1 ones)
+//  - flag true: v2 handshake with a signed ready, v1 commands still answered on the same connection
+//  - flag true against a gateway without v2: falls back to the v1 register on the same connection
+//  - flag true without an agent id: stays v1
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ReferenceCpServer, TENANT, AGENT, waitFor } from "./helpers/reference-cp.js";
+import { runAgent } from "./helpers/spawn-agent.js";
+
+const baseEnv = (srv) => ({
+    TENANT_ID: TENANT,
+    LOCAL_AGENT_SIGNATURE_MODE: "enforce",
+    LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${srv.keyId}=${srv.publicKeyRaw}`,
+});
+
+for (const flag of [undefined, "false", "off", "0", "bogus"]) {
+    test(`flag ${flag === undefined ? "unset" : JSON.stringify(flag)}: the v1 client, exactly: legacy register, no v2 frame, v1 command answered`, async () => {
+        const srv = await new ReferenceCpServer({}).start();
+        try {
+            await runAgent({
+                // everything v2 needs IS configured (UUID tenant, agent id, trusted key): only the flag keeps it off
+                srv, cfg: { authorizationId: AGENT, tenantId: TENANT }, env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: flag },
+                until: async () => {
+                    if (srv.ws && srv.legacy.some((f) => f.type === "register") && !srv.sent) {
+                        srv.sent = true;
+                        srv.ws.send(srv.cp.v1Command("health", {}));
+                    }
+                    return srv.legacy.some((f) => f.command === "health");
+                },
+            });
+            const reg = srv.legacy.find((f) => f.type === "register");
+            assert.deepEqual(Object.keys(reg).sort(), ["port", "tenantId", "type", "workspacePath"]);
+            assert.equal(reg.tenantId, TENANT);
+            const health = srv.legacy.find((f) => f.command === "health");
+            assert.equal(health.status, "ok");
+            assert.equal(srv.cp.rawIn.length, 0, "no v2 frame was ever sent");
+            assert.equal(srv.cp.registers.length, 0);
+            assert.equal(srv.textsFromLa.some((t) => t.includes("schemaVersion")), false);
+        } finally { await srv.stop(); }
+    });
+}
+
+test("flag true: v2 handshake (register, hello, signed ready), no v1 register, and a v1 command is still answered on the same connection", async () => {
+    const srv = await new ReferenceCpServer({ requireEnforce: true }).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT },
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => {
+                if (srv.cp.state === "ready" && !srv.sent) { srv.sent = true; srv.ws.send(srv.cp.v1Command("health", {})); }
+                return srv.legacy.some((f) => f.command === "health");
+            },
+        });
+        assert.equal(srv.connections, 1);
+        const reg = srv.cp.registers[0];
+        assert.equal(reg.protocol, 2);
+        assert.equal(reg.signatureMode, "enforce");
+        assert.match(reg.laVersion, /^\d+\.\d+\.\d+$/);
+        assert.deepEqual(reg.capabilities, ["chunk.base64", "protocol.v2", "v1.commands"]);
+        assert.ok(reg.workspaces.every((w) => /^[0-9a-f]{64}$/.test(w.pathSha256)), "only hashes of paths");
+        assert.equal(JSON.stringify(srv.cp.rawIn).includes("/tmp") || JSON.stringify(srv.cp.rawIn).includes("v2e2e-ws"), false, "no workspace path on the wire");
+        assert.equal(srv.cp.hellos[0].signatureMode, "enforce");
+        assert.equal(srv.legacy.some((f) => f.type === "register"), false, "no v1 register: v2 owns the registration");
+        assert.deepEqual(srv.cp.errorsSent, []);
+        assert.equal(srv.legacy.find((f) => f.command === "health").status, "ok", "v1 command on a v2 connection");
+    } finally { await srv.stop(); }
+});
+
+test("flag true, the CP sends a signed v2 job.cancel: acked `rejected protocol_unsupported` (no handler yet), connection stays up", async () => {
+    const srv = await new ReferenceCpServer({ requireEnforce: true }).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT },
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => {
+                if (srv.cp.state === "ready" && !srv.sent) { srv.sent = true; srv.cp.sendData("job.cancel", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", reason: "user" }); }
+                return srv.cp.acksFromLa.length > 0;
+            },
+        });
+        assert.deepEqual(srv.cp.acksFromLa, [{ ackSeq: 1, status: "rejected", errorCode: "protocol_unsupported" }]);
+        assert.deepEqual(srv.cp.errorsSent, []);
+    } finally { await srv.stop(); }
+});
+
+test("flag true against a gateway that does not speak v2: after the handshake timeout the v1 register goes out on the same connection", async () => {
+    const srv = await new ReferenceCpServer({ v2Disabled: true }).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT },
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true", LOCAL_AGENT_V2_HANDSHAKE_MS: "300" },
+            until: async () => srv.legacy.some((f) => f.type === "register"),
+        });
+        const reg = srv.legacy.find((f) => f.type === "register");
+        assert.deepEqual(Object.keys(reg).sort(), ["port", "tenantId", "type", "workspacePath"]);
+        assert.equal(srv.connections, 1, "same connection");
+    } finally { await srv.stop(); }
+});
+
+test("flag true without an agent id (no authorizationId): v1 only, nothing of v2 on the wire", async () => {
+    const srv = await new ReferenceCpServer({}).start();
+    try {
+        await runAgent({
+            srv, env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => srv.legacy.some((f) => f.type === "register"),
+        });
+        assert.equal(srv.cp.rawIn.length, 0);
+        assert.ok(srv.legacy.some((f) => f.type === "register"));
+    } finally { await srv.stop(); }
+});
+
+test("flag true with a tenant id that is not a UUID: v1 only", async () => {
+    const srv = await new ReferenceCpServer({}).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT },
+            env: { ...baseEnv(srv), TENANT_ID: "tenant-test", LOCAL_AGENT_SIGNATURE_MODE: "off", LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => srv.legacy.some((f) => f.type === "register"),
+        });
+        assert.equal(srv.cp.rawIn.length, 0);
+    } finally { await srv.stop(); }
+});
+
+test("sanity: waitFor is exported", () => assert.equal(typeof waitFor, "function"));

package/tools/graphify-validation/extras/README.md

@@ -0,0 +1,19 @@
+# Graphify validation extras (T4-06, round 2, 2026-10-28)
+
+Evidence scripts used for `10 Library/Plans/Fecho Dados 2026-10-28 T4.md`. They sit beside the harness and read its
+output; nothing here is part of the agent runtime. Layout expected under `$GV_T4_ROOT`:
+`harness/` (a `git archive` of this repo), `out/run1/` (a `run.sh --out` directory: `venv/`, `work/`, `results/`),
+`bin/rg` (ripgrep wrapper), `g10/home/` (empty HOME), `pub/` (shallow clones of public Go/Terraform repos).
+
+| Script | What it measures |
+|---|---|
+| `g10.py` | cold run, network denied, determinism and per-language file coverage for extra repos (Python, TS, Go, Terraform, SQL) |
+| `truth2.py` | `affected` recall against a code-only ground truth (comment, import and test lines removed), class level and class+methods |
+| `bymethod.py` | `affected` by class versus by method, against `rg -w` as the harness does |
+| `hybrid.py` | recall@8 of graph, lexical, reciprocal-rank fusion and lexical-first interleave |
+| `g3aug.py` | G3 Spring fixture with a wrapper-level "call via interface reaches implementations" post-process |
+| `docker/` | G9: image from `requirements-py311.lock` (build context `tools/graphify-validation`), `inner.sh` measures wall time and cgroup peak |
+
+Docker run used for the numbers: `docker run --rm --read-only --network none --user 10001:10001 --cpus=2 --memory=4g
+--tmpfs /tmp -e HOME=/data/home -v DATA:/data -v inner.sh:/inner.sh:ro --entrypoint /bin/sh IMAGE /inner.sh REPO RUN`.
+Public repos are only parsed (tree-sitter), never executed. No customer repository is involved.

package/tools/graphify-validation/extras/bymethod.py

@@ -0,0 +1,35 @@
+import os
+import sys, json, pathlib, subprocess, os
+SP=pathlib.Path(os.environ['GV_T4_ROOT'])
+sys.path.insert(0,str(SP/'harness/tools/graphify-validation/lib'))
+os.environ['RG']=str(SP/'bin/rg')
+import affected_vs_rg as A, gv_common as gc, graph_metrics as gm
+S=json.load(open(SP/'harness/tools/graphify-validation/config/symbols.json'))
+env=gc.clean_env(SP/'g10/home',str(SP/'out/run1/venv/bin')); G=str(SP/'out/run1/venv/bin/graphify')
+out={}
+for repo in ['vh-api-gateway','visionhammer-agents','deepdebug-local-agent']:
+    wd=SP/'out/run1/work'/repo; g=gm.load_graph(wd)
+    syms=S[repo] if isinstance(S,dict) else S
+    rows=[]
+    for sym in syms:
+        cls=[n for n in g['nodes'] if n.get('label')==sym and n.get('source_file') and not n['label']==n['source_file'].rsplit('/',1)[-1]]
+        if not cls: rows.append({'symbol':sym,'status':'nodef'}); continue
+        defs={n['source_file'] for n in cls}
+        ids=[n['id'] for n in cls]
+        for n in g['nodes']:
+            if n.get('source_file') in defs and n.get('label','').startswith('.') and n['label'].endswith('()'):
+                ids.append(n['id'])
+        files=set()
+        for i in ids:
+            r=subprocess.run([G,'affected',i,'--depth','1'],cwd=str(wd),env=env,capture_output=True,text=True,timeout=300)
+            files|=A.parse_affected(r.stdout)
+        files-=defs
+        rgf=gc.files_with_word(wd,sym,include_tests=True)-defs
+        m=lambda s:{f for f in s if not gc.is_test_path(f)}
+        gf,rf=m(files),m(rgf)
+        rows.append({'symbol':sym,'methods':len(ids)-len(cls),'graph':len(gf),'rg':len(rf),'recall':round(100*len(gf&rf)/len(rf),1) if rf else None,'precision':round(100*len(gf&rf)/len(gf),1) if gf else None})
+    rr=[r for r in rows if r.get('recall') is not None]
+    tot_rg=sum(r['rg'] for r in rr); tot_both=sum(round(r['recall']*r['rg']/100) for r in rr)
+    out[repo]={'rows':rows,'agg_recall_pct':round(100*tot_both/tot_rg,1) if tot_rg else None}
+    print(repo,out[repo]['agg_recall_pct'],[(r['symbol'],r.get('methods'),r.get('recall')) for r in rows])
+json.dump(out,open(SP/'g10/bymethod.json','w'),indent=1)

package/tools/graphify-validation/extras/docker/Dockerfile

@@ -0,0 +1,16 @@
+# T4-06 G9 test image: mirrors the python slice of the LA Dockerfile.full (node:20-slim = Debian 12, python3 3.11) + packaging plan 2.2
+FROM node:20-slim AS base
+RUN apt-get update && apt-get install -y --no-install-recommends git python3 python3-pip \
+ && rm -rf /var/lib/apt/lists/*
+
+FROM base AS graphify
+RUN apt-get update && apt-get install -y --no-install-recommends python3-venv ripgrep \
+ && rm -rf /var/lib/apt/lists/*
+COPY requirements-py311.lock /tmp/graphify.lock
+RUN python3 -m venv /opt/vh-graphify \
+ && /opt/vh-graphify/bin/pip install --no-cache-dir --disable-pip-version-check \
+      --require-hashes --no-deps --only-binary=:all: -r /tmp/graphify.lock \
+ && /opt/vh-graphify/bin/python -m compileall -q /opt/vh-graphify/lib \
+ && rm -f /opt/vh-graphify/bin/graphify-mcp /tmp/graphify.lock
+RUN useradd -u 10001 -m -d /nonexistent-home vhga 2>/dev/null || true
+ENV PATH=/opt/vh-graphify/bin:$PATH PYTHONDONTWRITEBYTECODE=1 PYTHONHASHSEED=0

package/tools/graphify-validation/extras/docker/inner.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# runs inside the container: $1 = repo dir under /data/ws
+S=$(date +%s.%N)
+graphify update /data/ws/$1 > /data/log-$1-$2.txt 2>&1; RC=$?
+E=$(date +%s.%N)
+PEAK=$(cat /sys/fs/cgroup/memory.peak 2>/dev/null)
+echo "repo=$1 run=$2 rc=$RC wall=$(echo "$E $S" | awk '{printf "%.1f",$1-$2}')s cgroup_peak_mb=$(echo $PEAK | awk '{printf "%.0f",$1/1048576}')"

package/tools/graphify-validation/extras/g10.py

@@ -0,0 +1,59 @@
+import os
+import sys, os, json, subprocess, shutil, pathlib, collections
+LIB=os.path.join(os.environ['GV_T4_ROOT'],'harness/tools/graphify-validation/lib')
+sys.path.insert(0, LIB)
+import run_graphify as rgf, graph_metrics as gm, gv_common as gc
+SP=pathlib.Path(os.environ['GV_T4_ROOT'])
+VENV=SP/'out/run1/venv'; BIN=str(VENV/'bin'); G=str(VENV/'bin/graphify')
+W=SP/'g10/work'; W.mkdir(exist_ok=True)
+HOME=SP/'g10/home'; HOME.mkdir(exist_ok=True)
+BASE='/Users/eduardooliveira/Documents/visionhammer projects/'
+targets=[
+ ('vh-litellm', BASE+'vh-litellm','origin/main'),
+ ('visionhammer-pentest', BASE+'../x','') ,
+ ('vision-heart-glow','%svision-heart-glow-3478cd8d'%BASE,'origin/main'),
+ ('go-chi-chi', str(SP/'pub/chi'),'HEAD'),
+ ('spf13-cobra', str(SP/'pub/cobra'),'HEAD'),
+ ('tf-aws-vpc', str(SP/'pub/terraform-aws-vpc'),'HEAD'),
+ ('tf-provider-random', str(SP/'pub/terraform-provider-random'),'HEAD'),
+]
+targets=[t for t in targets if t[2]]
+targets.append(('visionhammer-pentest', str(pathlib.Path(os.environ.get('GV_PENTEST_CLONE','/nonexistent'))),'HEAD'))
+wrap,mech=rgf.network_wrapper()
+ok,why=rgf.verify_block(wrap,sys.executable)
+print('network block',mech,ok,why)
+EXTS={'.java':'java','.ts':'ts','.tsx':'ts','.js':'js','.jsx':'js','.mjs':'js','.py':'python','.go':'go','.tf':'terraform','.sql':'sql'}
+res={}
+for name,repo,ref in targets:
+    d=W/name
+    if d.exists(): shutil.rmtree(d)
+    d.mkdir(parents=True)
+    a=subprocess.Popen(['git','-C',repo,'archive',ref],stdout=subprocess.PIPE)
+    subprocess.run(['tar','-x','-C',str(d)],stdin=a.stdout,check=True); a.wait()
+    shutil.rmtree(d/'graphify-out',ignore_errors=True)
+    env=gc.clean_env(HOME,BIN)
+    audit=SP/('g10/audit-%s.tsv'%name)
+    r1=rgf.measure([G,'update','.'],d,env,wrapper=wrap,audit_file=audit)
+    g=gm.load_graph(d)
+    sig1=gm.signature(g)
+    # second cold
+    shutil.rmtree(d/'graphify-out')
+    r2=rgf.measure([G,'update','.'],d,env)
+    sig2=gm.signature(gm.load_graph(d))
+    # per-language coverage (own: includes sql), files with >=1 symbol
+    with_sym,_=gm.file_node_labels(g)
+    cnt=collections.defaultdict(lambda:[0,0])
+    for p in d.rglob('*'):
+        if p.is_file() and p.suffix in EXTS and 'node_modules' not in p.parts and 'graphify-out' not in p.parts and '.git' not in p.parts:
+            rel=str(p.relative_to(d)); lang=EXTS[p.suffix]
+            if gc.is_test_path(rel) and lang!='go': pass
+            cnt[lang][0]+=1
+            if rel in with_sym: cnt[lang][1]+=1
+    cov={k:{'files':v[0],'with_symbols':v[1],'pct':round(100*v[1]/v[0],1) if v[0] else None} for k,v in cnt.items()}
+    g2=gm.g2_edges(g)
+    rel=collections.Counter(e.get('relation') for e in gm.edges_of(g))
+    res[name]={'ref':ref,'cold':{k:r1[k] for k in ('exit_code','wall_s','peak_tree_rss_mb','max_child_rss_mb')},
+       'network_events':r1.get('audit'),'deterministic':sig1==sig2,'signature':sig1,'coverage_by_lang':cov,
+       'g1_harness':gm.g1_extraction(g,d),'inferred_pct':g2['inferred_pct'],'inferred_by_relation':g2['inferred_by_relation'],'relations_top':dict(rel.most_common(8))}
+    print(name, json.dumps({k:res[name][k] for k in ('cold','deterministic','coverage_by_lang','inferred_pct')}))
+json.dump(res,open(SP/'g10/g10.json','w'),indent=1)

package/tools/graphify-validation/extras/g3aug.py

@@ -0,0 +1,49 @@
+import os
+import sys, json, pathlib, os, copy, collections
+SP=pathlib.Path(os.environ['GV_T4_ROOT'])
+sys.path.insert(0,str(SP/'harness/tools/graphify-validation/lib'))
+import spring_fixture as sf, graph_metrics as gm
+wd=SP/'out/run1/work/spring-fixture'
+g=gm.load_graph(wd)
+exp=json.load(open(SP/'harness/tools/graphify-validation/fixtures/spring/expected.json'))
+base=sf.check(g,exp)
+print('baseline',{k:(v['found'],v['expected']) for k,v in base['groups'].items()})
+def augment(g):
+    g=copy.deepcopy(g); es=gm.edges_of(g)
+    byid={n['id']:n for n in g['nodes']}
+    # class of a method node = node in same file with non-method label (first)
+    file_cls={}
+    for n in g['nodes']:
+        sfile=n.get('source_file'); lab=n.get('label','')
+        if sfile and not lab.startswith('.') and lab!=os.path.basename(sfile): file_cls.setdefault(sfile,n['id'])
+    impls=collections.defaultdict(list)   # interface class id -> impl class ids
+    for e in es:
+        if e.get('relation') in ('implements','inherits','extends'): impls[e['target']].append(e['source'])
+    methods=collections.defaultdict(dict) # class id -> {label: id}
+    for n in g['nodes']:
+        lab=n.get('label','')
+        if lab.startswith('.') and n.get('source_file') in file_cls: methods[file_cls[n['source_file']]][lab]=n['id']
+    new=[]
+    for e in es:
+        if e.get('relation')!='calls': continue
+        t=byid.get(e['target']); 
+        if not t or t.get('source_file') not in file_cls: continue
+        iface=file_cls[t['source_file']]
+        for c in impls.get(iface,[]):
+            m=methods[c].get(t['label'])
+            if m: new.append({**e,'target':m,'relation':'calls','confidence':'INFERRED','note':'via-interface (wrapper)'})
+    # field-type edges (references) + implements: class A references interface I => A reaches impl classes (depth)
+    for e in es:
+        if e.get('relation')=='references' and e['target'] in impls:
+            for c in impls[e['target']]: new.append({**e,'target':c,'relation':'references','confidence':'INFERRED'})
+    g['links']=es+new if 'links' in g else g.get('edges',[])+new
+    if 'edges' in g and 'links' not in g: g['edges']=es+new
+    return g,len(new)
+g2,n=augment(g)
+aug=sf.check(g2,exp)
+print('augmented (+%d synthetic edges)'%n,{k:(v['found'],v['expected']) for k,v in aug['groups'].items()})
+print('interface_impl pct',base['groups']['interface_impl']['pct'],'->',aug['groups']['interface_impl']['pct'])
+for k,v in aug['groups'].items():
+    for it in v['items']:
+        if not it['found']: print('  still failing',k,it['id'],it['detail'])
+json.dump({'baseline':{k:v['pct'] for k,v in base['groups'].items()},'augmented':{k:v['pct'] for k,v in aug['groups'].items()},'synthetic_edges':n},open(SP/'g10/g3aug.json','w'))

package/tools/graphify-validation/extras/hybrid.py

@@ -0,0 +1,34 @@
+import os
+import sys, json, pathlib
+SP=pathlib.Path(os.environ['GV_T4_ROOT'])
+sys.path.insert(0,str(SP/'harness/tools/graphify-validation/lib'))
+import recall as R, gv_common as gc
+import os
+os.environ['RG']=str(SP/'bin/rg')
+Q=json.load(open(SP/'harness/tools/graphify-validation/config/questions.json'))
+env=gc.clean_env(SP/'g10/home',str(SP/'out/run1/venv/bin'))
+G=str(SP/'out/run1/venv/bin/graphify')
+def rrf(*ranks,k=60):
+    s={}
+    for r in ranks:
+        for i,f in enumerate(R.clean(r)): s[f]=s.get(f,0)+1/(k+i+1)
+    return [f for f,_ in sorted(s.items(),key=lambda kv:-kv[1])]
+def interleave(a,b):
+    out=[]
+    for x,y in zip(R.clean(a),R.clean(b)):
+        for z in (y,x):
+            if z not in out: out.append(z)
+    return out + [f for f in R.clean(a)+R.clean(b) if f not in out]
+res={}
+for repo,wd in [('vh-api-gateway',SP/'out/run1/work/vh-api-gateway'),('visionhammer-agents',SP/'out/run1/work/visionhammer-agents'),('deepdebug-local-agent',SP/'out/run1/work/deepdebug-local-agent')]:
+    rows=[]
+    for q in Q[repo]:
+        g,_=R.rank_graph(G,wd,q['question'],env)
+        l=R.rank_lexical(wd,R.auto_keywords(q['question']),whole_word=False,ignore_case=True)
+        rows.append({'kind':q['kind'],'graph':R.recall_at(g,q['truth'])[0],'lex':R.recall_at(l,q['truth'])[0],
+                     'rrf':R.recall_at(rrf(g,l),q['truth'])[0],'inter':R.recall_at(interleave(l,g),q['truth'])[0]})
+    def avg(sel,k): return round(100*sum(r[k] for r in sel)/len(sel),1) if sel else None
+    res[repo]={kind:{k:avg([r for r in rows if kind=='all' or r['kind']==kind],k) for k in ('graph','lex','rrf','inter')}|{'n':len([r for r in rows if kind=='all' or r['kind']==kind])} for kind in ('all','symbolic','conceptual')}
+    print(repo,json.dumps(res[repo]))
+tot=[];
+json.dump(res,open(SP/'g10/hybrid.json','w'),indent=1)