@vincentt-xr/cli 0.7.0 → 0.9.0

package/dist/library/qa.f5-cli.spec.js

@@ -0,0 +1,433 @@
+// QA f5 · 4C — the CLI surface. QA-F5-C1 and QA-F5-C2.
+//
+// This is the tier a BLIND CONSUMER's control flow depends on. Two properties of
+// this file are load-bearing:
+//
+//  1. QA-F5-C1 asserts that exit 1 and exit 4 DIFFER, not merely that each has
+//     the right value. "We answered and something is missing" and "we did not
+//     answer" have different correct recoveries (re-search vs retry later), and
+//     a build that collapses them passes every per-code assertion.
+//
+//  2. QA-F5-C2(a) is a CONTROL, not advice. The prose in AGENTS.md is advice;
+//     iteration 2 shipped exactly that guardrail prose and it is the same class
+//     as the alphaMap hallucination it cites. Under print-by-default the agent
+//     handles URLs as strings BY DESIGN, so the only thing standing between a
+//     hallucinated URL and a fetch is a parser that refuses one.
+//
+// Written from features/f5-asset-library/qa.md, not from the implementation.
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { assetsAdd, assetsSearch, assetsShow } from "./assetsCommand.js";
+import { LibraryError, LibraryUnreachableError } from "./client.js";
+import { looksLikeUrl, parseIdArgs } from "./parse.js";
+// ---------------------------------------------------------------------------
+// fixtures — VALID base32-lower ids
+// ---------------------------------------------------------------------------
+//
+// ⚠ The record's example ids (lib_7f3a2c67d4e5b6a7, lib_2b7e6d4a4c7f2537) are
+// 16-char HEX and contain 0/1/8/9 — characters ABSENT from base32-lower. They do
+// not satisfy the record's own ^lib_[a-z2-7]{16}$, which the API enforces at
+// three places. Fixtures here use ids the SERVER would actually mint, so a
+// resolution that works here works against a real API.
+const PUMPKIN = {
+    id: "lib_75eokepbmoh4g6ol",
+    url: "https://assets.vincentt.studio/library/v1/props/pastel-pumpkin-75eokepbmoh4g6ol.png",
+    kind: "prop",
+    aspect: "1:1",
+    width: 1024,
+    height: 1024,
+    has_alpha: true,
+    bytes: 184320,
+    format: "png",
+    subject: "pumpkin",
+    description: "A soft pastel-orange pumpkin with a cream stem.",
+    usage_hint: "Place as a standalone prop.",
+};
+const TRIO = {
+    ...PUMPKIN,
+    id: "lib_2b7e6dqa4c5fzs37",
+    url: "https://assets.vincentt.studio/library/v1/props/pumpkin-trio-2b7e6dqa4c5fzs37.png",
+    subject: "pumpkin trio",
+};
+const LANTERN = {
+    ...PUMPKIN,
+    id: "lib_lanternqqqqqqqq",
+    url: "https://assets.vincentt.studio/library/v1/props/lantern-lanternqqqqqqqq.png",
+    subject: "paper lantern",
+};
+const FRAME = {
+    ...PUMPKIN,
+    id: "lib_frameaqqqqqqqqq",
+    url: "https://assets.vincentt.studio/library/v1/frames/gold-frameaqqqqqqqqq.png",
+    kind: "frame",
+    aspect: "9:16",
+    width: 720,
+    height: 1280,
+    subject: "gold frame border",
+};
+const GAPS = [
+    { tag: "wearable", message: "the library has no wearable or face-filter assets yet" },
+    { tag: "face-filter", message: "the library has no wearable or face-filter assets yet" },
+];
+const tempDirs = [];
+async function tempCwd() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "qa-f5-"));
+    tempDirs.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir)
+            await fs.rm(dir, { recursive: true, force: true });
+    }
+});
+function harness(client, cwd = "/tmp/qa-f5-nonexistent") {
+    const stdout = [];
+    const stderr = [];
+    const calls = [];
+    const downloaded = [];
+    const full = {
+        search: async (p) => {
+            calls.push("search");
+            if (client.search)
+                return client.search(p);
+            throw new Error("search not stubbed");
+        },
+        fetchOne: async (id) => {
+            calls.push("fetchOne");
+            if (client.fetchOne)
+                return client.fetchOne(id);
+            throw new Error("fetchOne not stubbed");
+        },
+        batch: async (ids) => {
+            calls.push(`batch:${ids.join(",")}`);
+            if (client.batch)
+                return client.batch(ids);
+            throw new Error("batch not stubbed");
+        },
+        download: async (url) => {
+            calls.push("download");
+            downloaded.push(url);
+            if (client.download)
+                return client.download(url);
+            return new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+        },
+    };
+    return {
+        deps: { out: (l) => stdout.push(l), err: (l) => stderr.push(l), client: full, cwd },
+        stdout,
+        stderr,
+        calls,
+        downloaded,
+        cwd,
+    };
+}
+const search = (res) => ({
+    resultCount: res.results?.length ?? 0,
+    results: [],
+    gaps: [],
+    ...res,
+});
+const batch = (res) => ({
+    resolved: [],
+    unknown: [],
+    ...res,
+});
+// ---------------------------------------------------------------------------
+// QA-F5-C1 · The exit-code contract, across all five outcomes
+// ---------------------------------------------------------------------------
+describe("QA-F5-C1 · the exit-code contract", () => {
+    it("(a) search WITH results exits 0", async () => {
+        const h = harness({ search: async () => search({ results: [PUMPKIN], resultCount: 1 }) });
+        expect(await assetsSearch(h.deps, { query: "pastel pumpkin", json: false })).toBe(0);
+    });
+    it("(b) search with ZERO results exits 0, carries NO glyph, and --json is valid", async () => {
+        const h = harness({ search: async () => search({ resultCount: 0, gaps: GAPS }) });
+        const code = await assetsSearch(h.deps, { query: "christmas face filter", json: false });
+        // THE SINGLE MOST IMPORTANT EXIT CODE IN f5. A non-zero exit here teaches an
+        // agent that an empty library is a TOOL FAILURE — and an agent's move on a
+        // tool failure is to retry or route around, where "route around" means
+        // inventing a URL or shipping a box geometry. That is the exact behavior the
+        // feature exists to prevent.
+        expect(code).toBe(0);
+        const screen = h.stderr.join("\n");
+        for (const glyph of ["✗", "⚠", "Error", "error:", "failed"]) {
+            expect(screen.includes(glyph), `the zero-result screen contains ${JSON.stringify(glyph)}. A well-formed question with ` +
+                `no matching inventory is a CORRECT ANSWER; styling it as an error is what teaches ` +
+                `the agent to treat an honest empty as a failure:\n${screen}`).toBe(false);
+        }
+        // The gap message is VERBATIM from the corpus — the CLI reports an inventory
+        // claim, it does not compose one.
+        expect(screen).toContain(GAPS[0].message);
+        // --json: stdout is a SINGLE valid JSON document, and stderr carries nothing
+        // that could contaminate it.
+        const j = harness({ search: async () => search({ resultCount: 0, gaps: GAPS }) });
+        expect(await assetsSearch(j.deps, { query: "christmas face filter", json: true })).toBe(0);
+        expect(j.stdout).toHaveLength(1);
+        const doc = JSON.parse(j.stdout[0]);
+        expect(doc.resultCount).toBe(0);
+        expect(doc.results).toEqual([]);
+        expect(doc.gaps.length, "`gaps` is empty under --json on a zero-result search. The keys must ALWAYS be " +
+            "present and populated here: a key that appears only sometimes is a key nobody handles.").toBeGreaterThan(0);
+        expect(doc.gaps[0]).toHaveProperty("tag");
+        expect(doc.gaps[0]).toHaveProperty("message");
+    });
+    it("(c) a PARTIAL add exits 1, prints the good URLs FIRST and in full, and says nothing was written", async () => {
+        const h = harness({
+            batch: async () => batch({ resolved: [PUMPKIN, TRIO, LANTERN, FRAME], unknown: ["lib_ffffffffffffffff"] }),
+        });
+        const code = await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, TRIO.id, LANTERN.id, FRAME.id, "lib_ffffffffffffffff"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).toBe(1);
+        const screen = h.stderr.join("\n");
+        // The four good URLs print FIRST and IN FULL.
+        for (const a of [PUMPKIN, TRIO, LANTERN, FRAME]) {
+            expect(screen, `the URL for ${a.id} is missing from the add screen`).toContain(a.url);
+        }
+        const firstUrlAt = screen.indexOf(PUMPKIN.url);
+        const failureAt = screen.indexOf("✗");
+        expect(failureAt, "the failure block is not last. An agent skimming the screen must see its four usable " +
+            "URLs before the thing that went wrong, or it discards the whole turn.").toBeGreaterThan(firstUrlAt);
+        // The header is a DIFFERENT SHAPE, not just a different number — a shape
+        // survives a skim and a number does not.
+        expect(screen).toContain("4 of 5 assets");
+        // The bad id is echoed VERBATIM so an agent can diff against what it sent.
+        expect(screen).toContain("lib_ffffffffffffffff");
+        // "Nothing was written." is present — `add` is a verb that SOUNDS like it
+        // writes files, and this is the honest statement of "the platform informs,
+        // never performs" (B35).
+        expect(screen).toContain("Nothing was written.");
+    });
+    it("(d) a TRANSPORT failure exits 4, with an empty stdout and the B36 paragraph on stderr", async () => {
+        const h = harness({
+            search: async () => {
+                throw new LibraryUnreachableError(new Error("ECONNREFUSED"));
+            },
+        });
+        const code = await assetsSearch(h.deps, { query: "pastel pumpkin", json: false });
+        expect(code).toBe(4);
+        expect(h.stdout, "stdout is not empty on a failure. Under --json an agent pipes stdout into a parser; " +
+            "any human line there corrupts the document.").toEqual([]);
+        const screen = h.stderr.join("\n").toLowerCase();
+        expect(screen.includes("publish") || screen.includes("preview") || screen.includes("build"), "the unreachable screen does not carry the B36 paragraph. A creator whose library call " +
+            "just failed needs to know that build, preview and publish are unaffected — otherwise " +
+            "an f5 outage reads as a toolchain outage:\n" + h.stderr.join("\n")).toBe(true);
+    });
+    it("(e) a 503 library_unavailable exits 4 and is NEVER rendered as a zero-result answer", async () => {
+        const h = harness({
+            search: async () => {
+                throw new LibraryError("library search failed (503)", 503, "library_unavailable");
+            },
+        });
+        const code = await assetsSearch(h.deps, { query: "pastel pumpkin", json: false });
+        expect(code).toBe(4);
+        expect(h.stdout).toEqual([]);
+        const screen = h.stderr.join("\n");
+        expect(screen.includes("No assets match"), "a 503 rendered as the ZERO-RESULT screen. \"we could not look\" and \"there is nothing " +
+            "there\" must never collapse: the agent's recovery from an honest empty (stop asking, " +
+            "build from props) is the WRONG move when the truth is that the corpus failed to load.").toBe(false);
+    });
+    it("the pair that must never collapse: (c) is 1 and (d)/(e) are 4, and they DIFFER", async () => {
+        const partial = harness({
+            batch: async () => batch({ resolved: [PUMPKIN], unknown: ["lib_ffffffffffffffff"] }),
+        });
+        const partialCode = await assetsAdd(partial.deps, {
+            ids: [PUMPKIN.id, "lib_ffffffffffffffff"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        const down = harness({
+            batch: async () => {
+                throw new LibraryUnreachableError();
+            },
+        });
+        const downCode = await assetsAdd(down.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(partialCode).toBe(1);
+        expect(downCode).toBe(4);
+        expect(partialCode, "the partial-resolution and did-not-answer exit codes are EQUAL. They must differ: " +
+            "\"we answered and something is missing\" is re-search, \"we did not answer\" is retry " +
+            "later, and an agent that cannot tell them apart takes the wrong recovery every time.").not.toBe(downCode);
+    });
+});
+// ---------------------------------------------------------------------------
+// QA-F5-C2 · Ids and only ids, batching at 2+, and writing nothing
+// ---------------------------------------------------------------------------
+describe("QA-F5-C2 · the CLI accepts ids and only ids, and writes nothing", () => {
+    it("(a) a URL is an arg-parse error with ZERO network calls — the CONTROL", async () => {
+        const h = harness({});
+        const code = await assetsAdd(h.deps, {
+            ids: ["https://assets.vincentt.studio/library/v1/props/x.png"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).not.toBe(0);
+        expect(h.calls, "a caller-supplied URL reached the network layer. THIS IS THE CONTROL, and the prose in " +
+            "AGENTS.md is advice: under print-by-default the agent handles URLs as strings BY " +
+            "DESIGN, so a parser that refuses one is the only thing standing between a " +
+            "hallucinated URL and a fetch.").toEqual([]);
+        expect(h.stderr.join("\n")).toContain("ids, not URLs");
+        // There is NO --url flag anywhere in the accepted set. Asserted over the
+        // parser's own predicate rather than over a help string, because the help
+        // string is not what admits an argument.
+        //
+        // The set below is the catalog's scope: SCHEME-FUL and SCHEME-RELATIVE forms,
+        // i.e. the shapes that are unmistakably a URL and that a fetch would follow.
+        for (const u of [
+            "https://assets.vincentt.studio/library/v1/props/x.png",
+            "http://evil.test/x.png",
+            "//assets.vincentt.studio/x.png",
+            "file:///etc/passwd",
+            "ftp://evil.test/x.png",
+        ]) {
+            expect(looksLikeUrl(u), `${u} is not recognized as a URL by the parser`).toBe(true);
+            expect(parseIdArgs([u]).ok, `${u} was accepted as an id`).toBe(false);
+        }
+        // THE STRONGER FORM OF THE SAME CONTROL, and the one that actually closes the
+        // hole: whatever the parser admits, the only string that ever reaches a fetch
+        // is a SERVER-RETURNED record.url.
+        //
+        // A `data:` or bare-path argument is NOT refused by looksLikeUrl (it has no
+        // `//`), and that is acceptable precisely because of this: it goes to the
+        // server as an id, comes back in unknown[], and never reaches download(). The
+        // refusal above is the cheap first line; this is the property.
+        const smuggleCwd = await tempCwd();
+        const smuggle = harness({ batch: async () => batch({ resolved: [PUMPKIN], unknown: ["data:image/png;base64,AAAA"] }) }, smuggleCwd);
+        await assetsAdd(smuggle.deps, {
+            ids: [PUMPKIN.id, "data:image/png;base64,AAAA"],
+            json: false,
+            download: true,
+            force: false,
+        });
+        for (const url of smuggle.downloaded) {
+            expect(url, `download() was called with ${url}, which is not a url the SERVER returned. Every ` +
+                `byte fetched by --download must come from a record the API resolved; a ` +
+                `caller-supplied string reaching a fetch is the hallucinated-URL failure this ` +
+                `control exists to prevent.`).toBe(PUMPKIN.url);
+        }
+    });
+    it("(b) a MALFORMED id goes to unknown[] via the SERVER, not a client-side 400", async () => {
+        const h = harness({
+            batch: async () => batch({ resolved: [PUMPKIN], unknown: ["pastel-pumpkin.png"] }),
+        });
+        const code = await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, "pastel-pumpkin.png"],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).toBe(1);
+        // The id REACHED the wire. A merely malformed id is NOT a shape the CLI must
+        // refuse to transmit: refusing it client-side would destroy its siblings,
+        // which D-multi-asset-is-mandatory forbids.
+        expect(h.calls.some((c) => c.startsWith("batch:") && c.includes("pastel-pumpkin.png")), `the malformed id never reached the server. calls=${JSON.stringify(h.calls)}`).toBe(true);
+        // The teaching line prints — advice that AGREES with a control, at the moment
+        // the agent is actually making the mistake.
+        expect(h.stderr.join("\n")).toContain("Ids look like lib_");
+    });
+    it("(c) three ids issue EXACTLY ONE batch call, never three fetches", async () => {
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO, LANTERN] }) });
+        await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, TRIO.id, LANTERN.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        const batchCalls = h.calls.filter((c) => c.startsWith("batch:"));
+        const fetchCalls = h.calls.filter((c) => c === "fetchOne");
+        expect(batchCalls.length, `expected ONE batch call, got calls=${JSON.stringify(h.calls)}. N sequential fetches is ` +
+            `the behavior D-multi-asset-is-mandatory exists to eliminate — and the limiter's ` +
+            `ceil(n/2) discount only rewards batching if the CLI actually batches.`).toBe(1);
+        expect(fetchCalls).toHaveLength(0);
+    });
+    it("(d) duplicates go out AS GIVEN and are de-duplicated for DISPLAY only", async () => {
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, PUMPKIN, TRIO] }) });
+        await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, PUMPKIN.id, TRIO.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        const call = h.calls.find((c) => c.startsWith("batch:"));
+        expect(call, "no batch call was recorded").toBeDefined();
+        expect(call, "the duplicate was stripped BEFORE the wire. The server charges PRE-DEDUP, so trimming " +
+            "here hides the cost from the operator — and it is the CLI deciding what the caller " +
+            "pays.").toBe(`batch:${PUMPKIN.id},${PUMPKIN.id},${TRIO.id}`);
+        // Displayed once.
+        const urlCount = h.stderr.filter((l) => l.includes(PUMPKIN.url)).length;
+        expect(urlCount).toBe(1);
+    });
+    it("(e) without --download, ZERO files are written anywhere under the cwd", async () => {
+        const cwd = await tempCwd();
+        const before = await fs.readdir(cwd);
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) }, cwd);
+        const code = await assetsAdd(h.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: false,
+            force: false,
+        });
+        expect(code).toBe(0);
+        const after = await fs.readdir(cwd);
+        expect(after, "`add` wrote to the creator's project without --download. B35: the platform INFORMS, " +
+            "never PERFORMS — no code, no generation, no writes into creator source.").toEqual(before);
+        expect(h.downloaded, "download() was called without --download").toEqual([]);
+        expect(h.stderr.join("\n")).toContain("Nothing was written.");
+    });
+    it("(f) --download writes once, names the path, then REFUSES with the B37 reason", async () => {
+        const cwd = await tempCwd();
+        const first = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) }, cwd);
+        const firstCode = await assetsAdd(first.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: true,
+            force: false,
+        });
+        expect(firstCode).toBe(0);
+        // Every downloaded url is one the SERVER returned — never a string the
+        // caller typed.
+        expect(first.downloaded.sort()).toEqual([PUMPKIN.url, TRIO.url].sort());
+        // The written paths are ANNOUNCED: a state-changing command names its side
+        // effects on the creator's disk.
+        expect(first.stderr.join("\n")).toContain("✓ Wrote");
+        const second = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) }, cwd);
+        const secondCode = await assetsAdd(second.deps, {
+            ids: [PUMPKIN.id, TRIO.id],
+            json: false,
+            download: true,
+            force: false,
+        });
+        expect(secondCode).toBe(1);
+        const screen = second.stderr.join("\n");
+        // It names the B37 REASON, not "file exists". The library never changes a
+        // file at a URL, so a re-download can only ever produce the same bytes —
+        // which is why the refusal is about YOUR edits, not about our bytes.
+        expect(/never changes|already have|your (own )?(copy|edits|file)/i.test(screen), "the overwrite refusal does not name the B37 reason. \"file exists\" tells a creator to " +
+            "pass --force; the real reason is that the library never changes a file at a URL, so " +
+            "the only thing an overwrite can destroy is the creator's OWN edit:\n" + screen).toBe(true);
+    });
+    it("(g) `show` with 2+ ids issues ONE batch call, same as add", async () => {
+        const h = harness({ batch: async () => batch({ resolved: [PUMPKIN, TRIO] }) });
+        await assetsShow(h.deps, { ids: [PUMPKIN.id, TRIO.id], json: false });
+        expect(h.calls.filter((c) => c.startsWith("batch:"))).toHaveLength(1);
+        expect(h.calls.filter((c) => c === "fetchOne")).toHaveLength(0);
+    });
+    it("a SINGLE id uses the fetch route — batching at 2+ is the rule, not at 1", async () => {
+        const h = harness({ fetchOne: async () => PUMPKIN });
+        await assetsShow(h.deps, { ids: [PUMPKIN.id], json: false });
+        expect(h.calls).toEqual(["fetchOne"]);
+    });
+});

package/dist/library/qa.f5-contract.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/library/qa.f5-contract.spec.js

@@ -0,0 +1,206 @@
+// QA-F5-G6 · The cross-repo contract — the API's REAL output through the CLI's
+// REAL parser. EXEMPT from the guardrail budget and always written.
+//
+// This is HALF the case. The other half is
+// api/internal/httpapi/qa_f5_contract_test.go, which boots the real router over
+// the real corpus and writes the API's ACTUAL response bytes into
+// __fixtures__/api-golden/. This file feeds those exact bytes to the CLI's real
+// parser and renderers — never to a hand-written stub.
+//
+// WHY. A per-repo suite green against its OWN stub hides a param-name or casing
+// mismatch. On f1 the CLI emitted `redirect` while the console read
+// `redirect_uri`: every suite was green and login was broken end to end, and it
+// surfaced only at the security pass. f5 is the highest-probability casing bug
+// in the product, because it is the ONE response in this API with a mixed
+// convention — camelCase envelope, snake_case record — in a single body.
+//
+// ⚠ THE GOLDEN FILES ARE NOT HAND-EDITABLE. Editing one turns this case back
+// into a per-repo stub test, which is precisely the failure it exists to catch.
+// Regenerate them by running the Go half.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { searchLines, showLines, unknownBlockLines } from "./render.js";
+import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
+const GOLDEN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__", "api-golden");
+/**
+ * Read one captured response.
+ *
+ * A MISSING file FAILS rather than skips. A contract case that quietly tests
+ * five of seven arms is worse than no case: it reports green while the two arms
+ * that were dropped are exactly the ones nobody looked at.
+ */
+function golden(name) {
+    const file = path.join(GOLDEN, `${name}.json`);
+    if (!existsSync(file)) {
+        throw new Error(`the captured API response ${name}.json is MISSING from ${GOLDEN}.\n\n` +
+            `Regenerate it from the api worktree:\n` +
+            `  go test -C <api> ./internal/httpapi/ -run TestQAF5G6 -count=1\n\n` +
+            `These files are the API's ACTUAL bytes. Do NOT hand-write one to make this pass — ` +
+            `a hand-written fixture turns the cross-repo contract case back into a per-repo stub ` +
+            `test, which is the exact failure it exists to catch.`);
+    }
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+/** The raw object, for key-presence assertions a typed parse cannot make. */
+function rawGolden(name) {
+    return golden(name);
+}
+describe("QA-F5-G6 · every arm of the contract table round-trips", () => {
+    it("the capture manifest is complete — a missing arm FAILS rather than skips", () => {
+        const manifest = rawGolden("manifest");
+        expect(manifest.arms, "the capture manifest names no arms").toBeDefined();
+        for (const arm of manifest.arms ?? []) {
+            expect(existsSync(path.join(GOLDEN, `${arm}.json`)), `the manifest names ${arm} but the capture is missing`).toBe(true);
+        }
+        expect(manifest.arms?.length).toBeGreaterThanOrEqual(7);
+    });
+    it("(a) search WITH results — the camelCase envelope and the snake_case record BOTH survive", () => {
+        const raw = rawGolden("search-results");
+        // THE ENVELOPE IS camelCase. Asserted on the RAW bytes, because the parser
+        // would happily read either spelling and report nothing.
+        expect(Object.keys(raw), "the API's search envelope does not carry `resultCount`").toContain("resultCount");
+        expect(Object.keys(raw), "the API's search envelope carries a snake_case `result_count`. THE ENVELOPE IS " +
+            "camelCase and the RECORD is snake_case, in ONE body. Someone normalized both layers " +
+            "to one convention — which reads like a fix and silently breaks every agent prompt in " +
+            "the wild that was told the field is `usage_hint`.").not.toContain("result_count");
+        const res = parseSearchResponse(raw);
+        expect(res.resultCount).toBeGreaterThan(0);
+        expect(res.results.length).toBe(res.resultCount);
+        expect(res.gaps, "`gaps` is absent on a non-empty result set").toEqual([]);
+        // THE RECORD IS snake_case, and each of these is a field the renderer reads.
+        const rec = raw.results[0];
+        for (const k of ["id", "url", "has_alpha", "usage_hint", "occupies_canvas"]) {
+            expect(Object.keys(rec), `the API's record does not carry ${k}`).toContain(k);
+        }
+        for (const k of ["hasAlpha", "usageHint", "occupiesCanvas", "textInImage"]) {
+            expect(Object.keys(rec), `the API's record carries the camelCase key ${k}. The record is snake_case.`).not.toContain(k);
+        }
+        // The PARSER carried the values through, not merely the keys. A parser that
+        // read a key and dropped its value passes every key assertion above.
+        const parsed = res.results[0];
+        expect(parsed.id).toBe(rec.id);
+        expect(parsed.url).toBe(rec.url);
+        expect(parsed.usage_hint).toBe(rec.usage_hint);
+        expect(parsed.has_alpha).toBe(rec.has_alpha);
+        expect(parsed.occupies_canvas).toBe(rec.occupies_canvas);
+        // And the RENDERER prints the url — the one thing `add`/`search` exist to
+        // produce.
+        const screen = searchLines(res, "pumpkin").join("\n");
+        expect(screen).toContain(parsed.url);
+    });
+    it("(b) search with ZERO results — gaps[].tag AND gaps[].message BOTH survive", () => {
+        const raw = rawGolden("search-zero-gaps");
+        const res = parseSearchResponse(raw);
+        expect(res.resultCount).toBe(0);
+        expect(res.results).toEqual([]);
+        expect(res.gaps.length, "the API's zero-result response carried NO gaps through the CLI's parser. The honest " +
+            "empty is the whole feature: without gaps, an unexplained empty is what teaches an " +
+            "agent to invent a URL.").toBeGreaterThan(0);
+        for (const g of res.gaps) {
+            expect(g.tag, "a gap survived without its `tag`. An agent BRANCHES on tag and QUOTES message; " +
+                "shipping one means it branches on prose.").toBeTruthy();
+            expect(g.message, "a gap survived without its `message`").toBeTruthy();
+        }
+        // VERBATIM: the rendered sentence is byte-identical to the corpus's, not one
+        // the CLI composed.
+        const rawGaps = raw.gaps;
+        const screen = searchLines(res, "christmas face filter").join("\n");
+        // The renderer wraps at 70 columns, so compare on the collapsed whitespace.
+        const collapsed = screen.replace(/\s+/g, " ");
+        expect(collapsed, "the rendered zero-result screen does not carry the corpus's gap message VERBATIM. The " +
+            "moment the CLI edits this string it is COMPOSING an inventory claim rather than " +
+            "REPORTING one — and closing a gap stops being a corpus change.").toContain(rawGaps[0].message.replace(/\s+/g, " "));
+    });
+    it("(c) the 503 body carries NO gaps, NO results and NO resultCount — the CLI cannot render it as an empty answer", () => {
+        const raw = rawGolden("search-503");
+        for (const forbidden of ["gaps", "results", "resultCount"]) {
+            expect(Object.keys(raw), `the API's 503 body carries ${forbidden}. A LOAD FAILURE MUST NOT WEAR AN INVENTORY ` +
+                `FACT'S CLOTHES: with a \`gaps\` key present the CLI could render "the library has ` +
+                `no wearable assets" about a ~500-record library whose corpus merely failed to load.`).not.toContain(forbidden);
+        }
+        expect(raw.code).toBe("library_unavailable");
+    });
+    it("(d) batch PARTIAL — resolved and unknown are disjoint, and unknown echoes VERBATIM", () => {
+        const raw = rawGolden("batch-partial");
+        expect(Object.keys(raw)).toContain("resolved");
+        expect(Object.keys(raw)).toContain("unknown");
+        const res = parseBatchResponse(raw);
+        expect(res.resolved.length).toBeGreaterThan(0);
+        expect(res.unknown.length).toBeGreaterThan(0);
+        const resolvedIds = new Set(res.resolved.map((r) => r.id));
+        for (const u of res.unknown) {
+            expect(resolvedIds.has(u), `${u} is in BOTH arrays`).toBe(false);
+        }
+        // The echo is the caller's own input, verbatim, so an agent can diff against
+        // what it sent without parsing our prose.
+        expect(res.unknown).toContain("nope");
+        expect(res.unknown).toContain("lib_ffffffffffffffff");
+        // The renderer does not throw on a partial and names the offending strings.
+        const block = unknownBlockLines(res.unknown, res.resolved.length, true).join("\n");
+        expect(block).toContain("nope");
+    });
+    it("(e) fetch-one RETIRED — `retired` rides fetch and survives the parser", () => {
+        const raw = rawGolden("fetch-retired");
+        expect(Object.keys(raw), "the fetch response for a RETIRED asset carries no `retired` key. Without it a caller " +
+            "cannot tell a de-listed asset from a current one, which is the one fact they need to " +
+            "decide whether to keep using it — and the URL keeps serving forever either way (B37).").toContain("retired");
+        const rec = parseFetchResponse(raw);
+        expect(rec).toBeDefined();
+        expect(rec?.retired).toBe(true);
+        expect(() => showLines(rec)).not.toThrow();
+    });
+    it("(f) a record with NO kind renders FEWER lines and does NOT throw", () => {
+        const raw = rawGolden("fetch-no-kind");
+        expect(Object.keys(raw), "the unclassifiable record carries a `kind` key. It must be ABSENT — not \"\", not " +
+            "\"unknown\". `kind: \"\"` is a PLACEMENT CONTRACT that reads as a value, and an agent " +
+            "branching on it places an unclassifiable asset as a prop.").not.toContain("kind");
+        const rec = parseFetchResponse(raw);
+        expect(rec).toBeDefined();
+        expect(rec?.kind).toBeUndefined();
+        // The renderer READS EVERY FIELD DEFENSIVELY: a missing optional field must
+        // degrade to a MISSING LINE, never to an exception. The CLI and the API are
+        // versioned separately on a creator's machine — `npx vincentt` fetches
+        // whatever the registry has and points it at whatever API the config
+        // resolves to.
+        let lines = [];
+        expect(() => {
+            lines = showLines(rec);
+        }).not.toThrow();
+        const full = parseFetchResponse(rawGolden("fetch-retired"));
+        const fullLines = showLines(full);
+        expect(lines.length, "the record with no kind rendered the SAME number of lines as a full record — the " +
+            "renderer is emitting a line for a field that is not there.").toBeLessThan(fullLines.length);
+    });
+    it("(g) stage's 202 carries every field the operator's process must transport", () => {
+        const raw = rawGolden("stage-202");
+        // The camelCase envelope of the admin surface. `confirmationDigest` is the
+        // ONE wire value both sides COMPUTE rather than copy, which is why a
+        // differing key order or float format silently makes EVERY commit fail.
+        for (const k of ["revisionId", "counts", "diff", "confirmationDigest", "ratio", "expiresAt"]) {
+            expect(Object.keys(raw), `the stage response omits ${k}`).toContain(k);
+        }
+        expect(typeof raw.confirmationDigest).toBe("string");
+        expect(raw.confirmationDigest.length).toBeGreaterThan(16);
+        // The diff's own shape, which the ratio tripwire and the digest are computed
+        // over.
+        const diff = raw.diff;
+        for (const k of ["added", "removed", "changed", "ratio"]) {
+            expect(Object.keys(diff), `the diff omits ${k}`).toContain(k);
+        }
+        // The server's ratio and the envelope's agree. Two numbers for one fact is
+        // how a client ends up trusting the wrong one.
+        expect(raw.ratio).toBe(diff.ratio);
+        // ⚠ THE CLI DOES NOT RECOMPUTE THE DIGEST IN v1.
+        //
+        // The catalog's (g) called for the CLI to recompute confirmationDigest from
+        // the diff bytes and match the server's, pinned to a golden vector. That arm
+        // was RETIRED with `vincentt library publish`
+        // (D-cli-does-not-publish-the-corpus-admin-panel-will): there is no CLI code
+        // that computes a digest, so there is nothing to compare. The SERVER-side
+        // half of the pin — that the value is present, stable and computed over the
+        // diff — is asserted here and in the Go contract test; the CLIENT-side half
+        // belongs to the admin panel's groom.
+    });
+});