deepdebug-local-agent 1.6.0 → 1.7.0

package/test/la-protocol-v2/content-file-list.test.js

@@ -0,0 +1,385 @@
+// F3-07c: `file.list`, the producer of the opaque ids. Real V2Session, real handler, real folders on disk; the control plane is the
+// in-memory ReferenceCp. Against the REAL gateway: tools/interop/LaV2NodeContentRelayE2ETest.java (F3-07c section).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { ReferenceCp, TENANT, AGENT, waitFor } from "./helpers/reference-cp.js";
+import { signingFor } from "./helpers/la-rig.js";
+import { setup, write, tmpDir } from "./helpers/content-rig.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+import { listFolder } from "../../src/la-protocol-v2/content-handlers/file-list.js";
+import { ContentRefRegistry } from "../../src/la-protocol-v2/content-handlers/ref-registry.js";
+import { resolveContentHandlersConfig } from "../../src/la-protocol-v2/content-handlers/config.js";
+
+const ID43 = /^[A-Za-z0-9_-]{43}$/;
+const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+const contract = loadContract();
+
+async function withRig(opts, body) {
+    const rig = await setup(opts);
+    try { await body(rig); } finally { await rig.stop(); }
+}
+const list = (rig, ref = "root", extra = {}) => rig.request({ kind: "file.list", ref, ...extra });
+const body = (r) => JSON.parse(r.text);
+const names = (r) => body(r).entries.map((e) => e.name);
+
+/** A workspace with everything the listing must and must not show. */
+function seed(root) {
+    write(root, "README.md", `# readme\ntoken ${GH}\n`);
+    write(root, "a.txt", "aaa");
+    write(root, "credentials.service.ts", "export const x = 1;\n");
+    write(root, "src/main.ts", "export {};\n");
+    write(root, "src/credentials/index.ts", "export {};\n");
+    // never listed
+    write(root, ".env", "A=1");
+    write(root, "credentials.json", "{}");
+    write(root, ".envrc", "export A=1");
+    write(root, "secrets/api.txt", "x");
+    write(root, ".git/config", "[core]");
+    write(root, "id_rsa", "x");
+    write(root, "server.pem", "x");
+}
+
+test("file.list: the root lists what may be served, dirs first then names by bytes; credentials.service.ts is there, .env and credentials.json are not (not even their names)", async () => {
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        const r = await list(rig);
+        assert.deepEqual([r.status, r.contentType], ["ok", "application/json"]);
+        assert.deepEqual(names(r), ["src", "README.md", "a.txt", "credentials.service.ts"]);
+        for (const never of [".env", "credentials.json", ".envrc", "secrets", ".git", "id_rsa", "server.pem"]) assert.equal(r.text.includes(never), false, never);
+        const b = body(r);
+        assert.equal(contract.validateBody("file.list.body.schema.json", b), true, "the body is the contract's body");
+        assert.deepEqual(b.entries.map((e) => e.type), ["dir", "file", "file", "file"]);
+        assert.equal(b.nextRef, undefined);
+        for (const e of b.entries) assert.match(e.id, ID43);
+        assert.equal(new Set(b.entries.map((e) => e.id)).size, 4, "one id per entry");
+        const a = b.entries.find((e) => e.name === "a.txt");
+        assert.equal(a.size, 3);
+        assert.ok(Math.abs(Date.parse(a.mtime) - fs.statSync(path.join(rig.root(), "a.txt")).mtimeMs) < 2000);
+        assert.equal(b.entries[0].size, 0, "a folder has size 0");
+    });
+});
+
+test("file.list: an id of the listing opens the file (masked by the DLP) and the folder id lists the folder; nothing outside the listing can be asked for", async () => {
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        const b = body(await list(rig));
+        const readme = b.entries.find((e) => e.name === "README.md");
+        const f = await rig.request({ kind: "file", ref: readme.id });
+        assert.equal(f.status, "ok");
+        assert.match(f.text, /# readme/);
+        assert.equal(f.text.includes(GH), false, "DLP second layer on the content");
+        const src = b.entries.find((e) => e.name === "src");
+        const sub = await list(rig, src.id);
+        assert.deepEqual(names(sub), ["credentials", "main.ts"]);
+        const cred = body(sub).entries.find((e) => e.name === "credentials");
+        assert.deepEqual(names(await list(rig, cred.id)), ["index.ts"]);
+        // kinds do not mix
+        assert.equal((await list(rig, readme.id)).status, "not_found", "a file id is not a folder id");
+        assert.equal((await rig.request({ kind: "file", ref: src.id })).status, "not_found", "a folder id is not a file id");
+        assert.equal((await rig.request({ kind: "diff", ref: src.id })).status, "not_found");
+        // other workspace / unknown / path-like
+        assert.equal((await list(rig, src.id, { workspaceId: "ws-2" })).status, "not_found");
+        assert.equal((await list(rig, "root", { workspaceId: "ws-nope" })).status, "not_found");
+        for (const ref of ["src", "../x", "/etc", "A".repeat(43), "cr1_" + "A".repeat(22), "ROOT", "root/", "%2e%2e", ".", "worktree"]) {
+            assert.equal((await list(rig, ref)).status, "not_found", ref);
+        }
+        // the ids of a file the listing did not show cannot be had: there is none for .env
+        assert.equal(rig.registry.live().filter((e) => e.kind === "file").length, 5, "exactly the files shown so far: README.md, a.txt, credentials.service.ts, main.ts, index.ts");
+    });
+});
+
+test("file.list: dlp + blocked entries: a name with a secret is masked (the id still works), a blocked class withholds the entry and mints nothing", async () => {
+    await withRig({}, async (rig) => {
+        write(rig.root(), `${GH}.txt`, "named after a token");
+        write(rig.root(), "plain.txt", "p");
+        const r = await list(rig);
+        assert.equal(r.text.includes(GH), false);
+        const b = body(r);
+        const masked = b.entries.find((e) => e.name.includes("REDACTED"));
+        assert.ok(masked, "the name was masked: " + names(r));
+        assert.equal(contract.validateBody("file.list.body.schema.json", b), true, "a masked name keeps the body valid (the ids are not masked)");
+        assert.equal((await rig.request({ kind: "file", ref: masked.id })).text, "named after a token");
+    });
+    await withRig({ env: { LOCAL_AGENT_DLP_BLOCK_CLASSES: "vcs-token" } }, async (rig) => {
+        write(rig.root(), `${GH}.txt`, "x");
+        write(rig.root(), "plain.txt", "p");
+        const r = await list(rig);
+        assert.deepEqual(names(r), ["plain.txt"]);
+        assert.equal(rig.registry.size, 1, "no id was minted for the withheld entry");
+    });
+});
+
+test("file.list: only with DLP enforce (nothing is read, nothing minted otherwise); a range makes no sense; the flag-off path is the old one", async () => {
+    for (const dlp of ["off", "warn"]) {
+        await withRig({ dlp }, async (rig) => {
+            seed(rig.root());
+            const r = await list(rig);
+            assert.deepEqual([r.status, r.errorCode, r.body.length], ["error", "protocol_unsupported", 0], dlp);
+            assert.equal(rig.registry.size, 0);
+        });
+    }
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        const r = await list(rig, "root", { range: { offset: 0, length: 10 } });
+        assert.deepEqual([r.status, r.errorCode], ["error", "protocol_unsupported"]);
+        assert.equal(rig.registry.size, 0);
+    });
+});
+
+test("file.list: paging by count: limit N gives N entries and a nextRef (a folder id that remembers the position); the pages add up to the folder, in order, once each", async () => {
+    await withRig({}, async (rig) => {
+        for (let i = 0; i < 25; i++) write(rig.root(), `f${String(i).padStart(2, "0")}.txt`, "x");
+        for (let i = 0; i < 3; i++) fs.mkdirSync(path.join(rig.root(), `d${i}`));
+        const all = [];
+        let ref = "root";
+        let pages = 0;
+        const refs = new Set();
+        for (; ref && pages < 10; pages++) {
+            const r = await list(rig, ref, { limit: 10 });
+            assert.equal(r.status, "ok");
+            const b = body(r);
+            assert.ok(b.entries.length <= 10);
+            all.push(...b.entries.map((e) => e.name));
+            if (b.nextRef) { assert.match(b.nextRef, ID43); assert.equal(refs.has(b.nextRef), false); refs.add(b.nextRef); }
+            else assert.equal(pages, 2, "the third page is the last");
+            ref = b.nextRef;
+        }
+        assert.equal(pages, 3);
+        assert.deepEqual(all, [...["d0", "d1", "d2"], ...Array.from({ length: 25 }, (_, i) => `f${String(i).padStart(2, "0")}.txt`)]);
+        // the nextRef belongs to the workspace and to the listing kind
+        const first = body(await list(rig, "root", { limit: 10 }));
+        assert.equal((await list(rig, first.nextRef, { workspaceId: "ws-2" })).status, "not_found");
+        assert.equal((await rig.request({ kind: "file", ref: first.nextRef })).status, "not_found");
+        // a continuation inside a sub folder stays in that folder
+        write(rig.root(), "sub/a.txt", "1"); write(rig.root(), "sub/b.txt", "1"); write(rig.root(), "sub/c.txt", "1");
+        const sub = body(await list(rig, "root", { limit: 1000 })).entries.find((e) => e.name === "sub");
+        const p1 = body(await list(rig, sub.id, { limit: 2 }));
+        assert.deepEqual(p1.entries.map((e) => e.name), ["a.txt", "b.txt"]);
+        assert.deepEqual(names(await list(rig, p1.nextRef, { limit: 2 })), ["c.txt"]);
+    });
+});
+
+test("file.list: paging by size: 255-character names do not fit 1000 to a page; every page is within the byte budget and the pages still add up", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_MAX_BYTES: "8192" } }, async (rig) => {
+        const N = 40;
+        const long = (i) => `${String(i).padStart(3, "0")}-${"n".repeat(240)}.txt`;
+        for (let i = 0; i < N; i++) write(rig.root(), long(i), "x");
+        const all = [];
+        let ref = "root";
+        let pages = 0;
+        while (ref && pages < 40) {
+            const r = await list(rig, ref, { limit: 1000 });
+            assert.equal(r.status, "ok", r.errorCode);
+            assert.ok(r.body.length <= 8192, `page ${pages}: ${r.body.length} bytes`);
+            assert.ok(body(r).entries.length >= 1);
+            all.push(...names(r));
+            ref = body(r).nextRef;
+            pages++;
+        }
+        assert.ok(pages >= 3, "several pages");
+        assert.deepEqual(all, Array.from({ length: N }, (_, i) => long(i)));
+        assert.equal(rig.registry.size, N + (pages - 1), "ids exist only for what was shown (+ one continuation per page but the last): an entry that did not fit left no id behind");
+    });
+});
+
+test("file.list: a folder with more than LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES entries is payload_too_large (never 'the first N the disk returned'); the limit itself is fine", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES: "100" } }, async (rig) => {
+        for (let i = 0; i < 100; i++) write(rig.root(), `big/f${i}.txt`, "x");
+        const big = body(await list(rig)).entries.find((e) => e.name === "big");
+        assert.equal(body(await list(rig, big.id, { limit: 1000 })).entries.length, 100);
+        write(rig.root(), "big/one-more.txt", "x");
+        const r = await list(rig, big.id);
+        assert.deepEqual([r.status, r.errorCode, r.body.length], ["error", "payload_too_large", 0]);
+    });
+});
+
+test("file.list: links, hard links, devices and odd names: a link that leaves the root, a link to a secret, a hard link, a fifo and a name with a newline are simply not there", async () => {
+    await withRig({}, async (rig) => {
+        const root = rig.root();
+        const out = tmpDir("f307c-out-");
+        rig.dirs.push(out);
+        write(out, "outside.txt", "outside secret");
+        write(out, "dir/inner.txt", "x");
+        write(root, "ok.txt", "ok");
+        write(root, "real/inner.txt", "i");
+        write(root, ".env", "A=1");
+        write(root, "secrets/x.txt", "s");
+        fs.symlinkSync(path.join(out, "outside.txt"), path.join(root, "link-out.txt"));
+        fs.symlinkSync(path.join(out, "dir"), path.join(root, "link-outdir"));
+        fs.symlinkSync(path.join(root, ".env"), path.join(root, "innocent.txt"));
+        fs.symlinkSync(path.join(root, "secrets"), path.join(root, "innocent-dir"));
+        fs.symlinkSync(path.join(root, "ok.txt"), path.join(root, "link-in.txt"));
+        fs.symlinkSync(path.join(root, "real"), path.join(root, "link-indir"));
+        fs.symlinkSync(path.join(root, "missing"), path.join(root, "dangling"));
+        fs.symlinkSync("../outside.txt", path.join(root, "rel-out.txt"));
+        fs.symlinkSync(root, path.join(root, "loop"));                                  // a link to the root itself
+        try { fs.linkSync(path.join(root, "ok.txt"), path.join(root, "hard.txt")); } catch { /* no hard links here */ }
+        try { execFileSync("mkfifo", [path.join(root, "pipe")]); } catch { /* no mkfifo */ }
+        try { write(root, "bad\nname.txt", "x"); } catch { /* a file system that refuses it */ }
+        try { write(root, "repl\ufffdchar.txt", "x"); } catch { /* idem: a name with U+FFFD is what invalid UTF-8 looks like after decoding, so it is never listed */ }
+        const r = await list(rig);
+        assert.equal(r.status, "ok");
+        const n = names(r);
+        // ok.txt itself is hard-linked now (hard.txt is its second name): both are left out by the default hard link rule
+        const hard = fs.statSync(path.join(root, "ok.txt")).nlink > 1;
+        assert.deepEqual(n.filter((x) => !["ok.txt", "link-in.txt"].includes(x)), ["link-indir", "real"], n.join(","));
+        assert.equal(n.includes("ok.txt"), !hard);
+        assert.equal(n.includes("link-in.txt"), !hard, "a link to a hard-linked file is a name of it: same rule");
+        for (const never of ["link-out", "link-outdir", "innocent", "dangling", "rel-out", "pipe", "bad", "repl", "loop", ".env", "secrets", "hard.txt"]) assert.equal(r.text.includes(never), false, never);
+        // a link to a folder inside the root lists as a folder, and the ids it hands out are for the real folder
+        const li = body(r).entries.find((e) => e.name === "link-indir");
+        assert.equal(li.type, "dir");
+        assert.deepEqual(names(await list(rig, li.id)), ["inner.txt"]);
+        // a folder swapped for a link out of the root / to a secret after its id was minted is forbidden at list time
+        const real = body(r).entries.find((e) => e.name === "real");
+        fs.rmSync(path.join(root, "real"), { recursive: true });
+        fs.symlinkSync(path.join(out, "dir"), path.join(root, "real"));
+        assert.equal((await list(rig, real.id)).status, "forbidden");
+        fs.rmSync(path.join(root, "real"));
+        fs.symlinkSync(path.join(root, "secrets"), path.join(root, "real"));
+        assert.equal((await list(rig, real.id)).status, "forbidden");
+        assert.equal(r.text.includes(out), false);
+    });
+});
+
+test("file.list: the hard link rule can be lifted by LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS (as for file)", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS: "true" } }, async (rig) => {
+        write(rig.root(), "a.txt", "x");
+        try { fs.linkSync(path.join(rig.root(), "a.txt"), path.join(rig.root(), "b.txt")); } catch { return; }
+        assert.deepEqual(names(await list(rig)), ["a.txt", "b.txt"]);
+    });
+});
+
+test("file.list: unicode, spaces and a root reached through a link; an empty folder is an empty page; a folder that is not there is not_found", async () => {
+    await withRig({}, async (rig) => {
+        write(rig.root(), "ação final.txt", "x"); write(rig.root(), "日本語.md", "x"); write(rig.root(), "with space/a b.txt", "x"); fs.mkdirSync(path.join(rig.root(), "empty"));
+        const b = body(await list(rig));
+        assert.deepEqual(b.entries.map((e) => e.name), ["empty", "with space", "ação final.txt", "日本語.md"]);
+        const empty = b.entries.find((e) => e.name === "empty");
+        const e = await list(rig, empty.id);
+        assert.deepEqual([e.status, body(e)], ["ok", { entries: [] }]);
+        fs.rmdirSync(path.join(rig.root(), "empty"));
+        assert.equal((await list(rig, empty.id)).status, "not_found");
+    });
+    const base = tmpDir(); const real = path.join(base, "real"); const link = path.join(base, "link");
+    fs.mkdirSync(real); write(real, "x.txt", "x"); fs.symlinkSync(real, link);
+    await withRig({ workspaces: { "ws-1": { root: link } } }, async (rig) => {
+        assert.deepEqual(names(await list(rig)), ["x.txt"]);
+    });
+    fs.rmSync(base, { recursive: true, force: true });
+});
+
+test("file.list: nothing but codes in errors, audit and logs: no name, no path and no id of a listing is ever in them", async () => {
+    await withRig({}, async (rig) => {
+        seed(rig.root());
+        write(rig.root(), "very-private-customer-name.txt", "x");
+        const r = await list(rig);
+        const ids = body(r).entries.map((e) => e.id);
+        await list(rig, "A".repeat(43)); await list(rig, ids[0]); await list(rig, "root", { workspaceId: "ws-nope" });
+        const noise = JSON.stringify([rig.handler.audit.tail(1000), rig.logs]);
+        for (const leak of ["very-private-customer-name", "README", "credentials", "main.ts", rig.root(), path.basename(rig.root()), ...ids, GH]) assert.equal(noise.includes(leak), false, `leaked ${leak}`);
+        const rec = rig.handler.audit.tail(1000).find((x) => x.kind === "file.list" && x.status === "ok");
+        assert.ok(rec && rec.bytes > 0 && rec.chunks >= 1);
+    });
+});
+
+test("file.list: a folder of 3000 entries gives a page of `limit`, and the slot and the memory reserved for the request come back", async () => {
+    await withRig({ env: { LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES: "20000" } }, async (rig) => {
+        for (let i = 0; i < 3000; i++) fs.writeFileSync(path.join(rig.root(), `f${i}.txt`), "x");
+        const r = await list(rig, "root", { limit: 1000 });
+        assert.equal(r.status, "ok");
+        assert.equal(body(r).entries.length, 1000);
+        assert.equal(rig.handler.inflight, 0);
+        assert.equal(rig.handler.reservedBytes, 0);
+    });
+});
+
+test("file.list: a cursor belongs to a folder id only (a file id with a cursor, or a bad cursor, is refused by the registry); listFolder stops when the request is aborted", async () => {
+    const reg = new ContentRefRegistry({ tenantId: TENANT });
+    const q = { workspaceId: "w", root: "/r" };
+    assert.equal(reg.mint({ ...q, kind: "file", rel: "a.txt", after: { dir: false, name: "a" } }), null);
+    assert.equal(reg.mint({ ...q, kind: "diff", rel: null, after: { dir: false, name: "a" } }), null);
+    for (const bad of ["x", 1, {}, { name: "" }, { name: "x".repeat(2000) }]) assert.equal(reg.mint({ ...q, kind: "file.list", rel: null, after: bad }), null, JSON.stringify(bad).slice(0, 20));
+    assert.ok(reg.mint({ ...q, kind: "file.list", rel: null, after: { dir: true, name: "d" } }));
+    const root = tmpDir();
+    write(root, ".env", "A=1");                      // nothing listable: only the loop that reads the folder can notice the abort
+    const o = { root, limit: 10, maxBytes: 1 << 20, maxDirEntries: 1000, mint: () => null, maskName: (n) => ({ name: n, blocked: false, denied: false, total: 0, redactions: {} }) };
+    assert.deepEqual(await listFolder({ ...o }), { ok: true, body: Buffer.from('{"entries":[]}'), entries: 0, dlp: { total: 0, redactions: {} } });
+    assert.deepEqual(await listFolder({ ...o, signal: AbortSignal.abort() }), { ok: false, status: "error", errorCode: "agent_offline" });
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("config (F3-07c): LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES is clamped to 100..200000, a bad value is the default (20000), never unlimited", () => {
+    const c = (v) => resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_MAX_DIR_ENTRIES: v }, () => {}).maxDirEntries;
+    assert.deepEqual([c(undefined), c("abc"), c("99"), c("200001"), c("999999999999"), c("-5"), c("100"), c("200000"), c("5000")], [20_000, 20_000, 20_000, 20_000, 20_000, 20_000, 100, 200_000, 5_000]);
+});
+
+// ------------------------------------------------------------------------------------------ the real wiring: content.index
+
+async function linkFor(cp, { env, root }) {
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m), error: (m) => logs.push(m) };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: TENANT }] };
+    const link = await buildV2Link({ tenantId: TENANT, agentId: AGENT, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, "enforce"), wsManager,
+        getWorkspaceRoot: () => root, log, env: { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "enforce", ...env } });
+    const transport = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready");
+    return { link, logs };
+}
+
+test("wiring: a listing mints through mintRef, so every id it hands out is announced with content.index ({kind, ref, size}: no names), and the register announces content.file.list", async () => {
+    const root = tmpDir(); seed(root); write(root, "very-private-customer-name.txt", "12345");
+    const cp = new ReferenceCp();
+    const { link, logs } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_INDEX_BATCH_MS: "0" } });
+    assert.ok(cp.registers[0].capabilities.includes("content.file.list"));
+    const requestId = (await import("./helpers/reference-cp.js")).uuid();
+    cp.sendData("content.request", { kind: "file.list", ref: "root", actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+    await waitFor(() => cp.contentRequests.get(requestId)?.done);
+    const b = JSON.parse(Buffer.concat(cp.contentRequests.get(requestId).chunks).toString("utf8"));
+    assert.equal(b.entries.length, 5);
+    await waitFor(() => cp.received.filter((f) => f.type === "content.index").flatMap((f) => f.payload.entries).length === 5);
+    const idx = cp.received.filter((f) => f.type === "content.index").flatMap((f) => f.payload.entries);
+    const byRef = new Map(idx.map((e) => [e.ref, e]));
+    for (const e of b.entries) {
+        const i = byRef.get(e.id);
+        assert.ok(i, "announced: " + e.name.length);
+        assert.deepEqual(Object.keys(i).sort(), ["kind", "ref", "size"]);
+        assert.equal(i.kind, e.type === "dir" ? "file.list" : "file");
+        assert.equal(i.size, e.size);
+    }
+    const wire = JSON.stringify(cp.received.filter((f) => f.type === "content.index"));
+    for (const leak of ["very-private-customer-name", "README", "main.ts", root, path.basename(root)]) assert.equal(wire.includes(leak), false, `leaked ${leak}`);
+    assert.equal(logs.join("\n").includes("very-private"), false);
+    assert.deepEqual(cp.errorsSent, []);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("wiring: the nextRef of the real link works (the continuation is minted through mintRef with its cursor): page 2 continues where page 1 stopped", async () => {
+    const root = tmpDir();
+    for (const n of ["a", "b", "c", "d", "e"]) write(root, `${n}.txt`, n);
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root, env: {} });
+    const { uuid } = await import("./helpers/reference-cp.js");
+    const ask = async (ref, limit) => {
+        const requestId = uuid();
+        cp.sendData("content.request", { kind: "file.list", ref, limit, actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+        await waitFor(() => cp.contentRequests.get(requestId)?.done);
+        return JSON.parse(Buffer.concat(cp.contentRequests.get(requestId).chunks).toString("utf8"));
+    };
+    const p1 = await ask("root", 2);
+    assert.deepEqual(p1.entries.map((e) => e.name), ["a.txt", "b.txt"]);
+    assert.match(p1.nextRef, ID43);
+    const p2 = await ask(p1.nextRef, 2);
+    assert.deepEqual(p2.entries.map((e) => e.name), ["c.txt", "d.txt"]);
+    const p3 = await ask(p2.nextRef, 2);
+    assert.deepEqual([p3.entries.map((e) => e.name), p3.nextRef], [["e.txt"], undefined]);
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});

package/test/la-protocol-v2/content-path-guard.test.js

@@ -176,7 +176,7 @@ test("ids (F3-07b): 43 base64url chars, no prefix, 256 random bits, not derived
 test("ids: resolve only for the same tenant, workspace, root and kind; anything else is null (indistinguishable from unknown)", () => {
     const reg = new ContentRefRegistry({ tenantId: "t1" });
     const { id } = reg.mint({ workspaceId: "w1", root: "/r1", kind: "file", rel: "src/a.txt" });
-    assert.deepEqual(reg.resolve(id, { workspaceId: "w1", root: "/r1", kind: "file" }), { rel: "src/a.txt" });
+    assert.deepEqual(reg.resolve(id, { workspaceId: "w1", root: "/r1", kind: "file" }), { rel: "src/a.txt", after: null });
     assert.equal(reg.resolve(id, { workspaceId: "w2", root: "/r1", kind: "file" }), null, "other workspace");
     assert.equal(reg.resolve(id, { workspaceId: "w1", root: "/r2", kind: "file" }), null, "same workspace id, re-opened on another root");
     assert.equal(reg.resolve(id, { workspaceId: "w1", root: "/r1", kind: "diff" }), null, "other kind");

package/test/la-protocol-v2/content-wiring.test.js

@@ -69,11 +69,11 @@ test("flag off (unset or any non-true value): content.request is acked `rejected
     }
 });
 
-test("flag on: the handler is installed, the register announces content.file and content.diff, mintRef gives the hook for future inventories", async () => {
+test("flag on: the handler is installed, the register announces content.file, content.file.list and content.diff, mintRef is the hook the listing mints through", async () => {
     const root = tmpDir(); write(root, "src/a.txt", "hello"); write(root, ".env", "X=1");
     const cp = new ReferenceCp();
     const { link, logs } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "enforce" } });
-    assert.deepEqual(cp.registers[0].capabilities, ["chunk.base64", "content.diff", "content.file", "protocol.v2", "v1.commands"]);
+    assert.deepEqual(cp.registers[0].capabilities, ["chunk.base64", "content.diff", "content.file", "content.file.list", "protocol.v2", "v1.commands"]);
     assert.equal(logs.some((l) => l.includes("not enforce")), false, "enforce: no warning");
     const m = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "src/a.txt" });
     assert.match(m.id, /^[A-Za-z0-9_-]{43}$/);

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

@@ -52,9 +52,18 @@ test("vectors: the suite is complete (every type has a file, plus cross-type)",
 
 let valid = 0;
 let invalid = 0;
+let bodyVectors = 0;
 for (const file of vectorFiles) {
     const doc = JSON.parse(fs.readFileSync(path.join(VECTORS, file), "utf8"));
     for (const v of doc.vectors) {
+        // F3-07c: `file.list.body.vectors.json` holds bodies (the decoded data of a content.response), not frames: they name their schema
+        if (typeof doc.schema === "string" && doc.schema.endsWith(".body.schema.json")) {
+            test(`vector ${file.replace(".vectors.json", "")} :: ${v.name}`, () => {
+                assert.equal(contract.validateBody(doc.schema, v.message), v.expect.valid === true);
+                bodyVectors++;
+            });
+            continue;
+        }
         test(`vector ${file.replace(".vectors.json", "")} :: ${v.name}`, () => {
             const r = contract.validateFrame(v.message);
             if (v.expect.valid) {
@@ -73,10 +82,11 @@ for (const file of vectorFiles) {
     }
 }
 
-test("vectors: counts (168 = 30 valid + 138 invalid in this copy)", () => {
-    assert.equal(valid + invalid, 168);
-    assert.equal(valid, 30);
-    assert.equal(invalid, 138);
+test("vectors: counts (176 frames = 34 valid + 142 invalid in this copy, plus the bodies of file.list)", () => {
+    assert.equal(valid + invalid, 176);
+    assert.equal(valid, 34);
+    assert.equal(invalid, 142);
+    assert.equal(bodyVectors, 54, "file.list.body.vectors.json (F3-07c): 54 bodies");
 });
 
 // ------------------------------------------------------------------------------------------------ tables