@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/capabilities/listBudget.shipped.exec.test.ts

@@ -0,0 +1,239 @@
+/**
+ * The response-size budget for a list-shaped answer, measured over the SHIPPED
+ * pack (PROTECTED).
+ *
+ * No list had a size budget before this. The five enforced performance
+ * constants are all latency, none of them runs a story's list query, and the
+ * only size ceiling in the package covered the MCP resource listing rather than
+ * a verb — so a story could grow its payload without limit and nothing turned
+ * red. The largest answer the distribution ships today is 78 KB from one call,
+ * and an agent pays for it twice: once in transfer, once in the context window
+ * it can no longer spend on the task.
+ *
+ * WHY A BUDGET AND NOT JUST PAGINATION. `--limit` gives a caller a way to ask
+ * for less. A budget is what fails the build when a story forgets that its
+ * DEFAULT answer is the one every speculative call gets. The two are
+ * complementary: the default page (500 rows) bounds the row count, and this
+ * bounds the bytes those rows turn into — because a row's width is a story's
+ * choice and no row count implies a payload size.
+ *
+ * WHERE IT IS ENFORCED. Where the payload is BUILT — the `json` formatter, the
+ * one seam both machine surfaces serialise through (`--format json` parses it
+ * into the envelope; the MCP tool result parses it into `toolSuccess`). Not in
+ * the timed perf pass: that pass is deliberately not run by CI (owner ruling
+ * 2026-08-30), and a budget nothing runs is not a gate. This is the same choice
+ * the resource listing's ceiling made, for the same reason.
+ *
+ * WHAT IT DOES NOT COVER. Latency. Declaring stories is measurably free — when
+ * five read stories moved into the distribution's configuration and grew it
+ * from 55 to 513 lines, the fast-path deltas straddled zero — and no latency
+ * constant moves for this either.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compileStoryModule } from "../kernel/packs/compile.js";
+import { DEFAULT_LIST_LIMIT, MAX_LIST_WINDOW } from "../kernel/packs/paging.js";
+import {
+  distributionSource,
+  type PackList,
+  type PackPage,
+} from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
+import { declaredStories } from "./distribution.js";
+
+/**
+ * The ceiling on ONE list-shaped answer, in bytes of the serialised payload.
+ *
+ * **Derived from measurement, 2026-09-10**, over the pack the distribution
+ * actually ships: the largest answer is `standard list` at 147 rows and 78,129
+ * bytes, whose rows are fat rather than many, and the most ROWS is `block list`
+ * at 252 for 32,956 bytes. 1.6 × 78,129 = 125,006, rounded to 125,000 — the
+ * same shape of derivation the resource listing used (60,000 → 100,000 at a
+ * measured 65,119, i.e. 1.54×), and headroom enough that ordinary upstream
+ * growth in the code-standards pack does not turn this red on a pack bump.
+ * Every figure and the full table are in BUDGETS.md.
+ *
+ * **When this is next reached, the fix is not a bigger number.** A ceiling
+ * raised on demand is a formality. The fix is either a narrower default page
+ * for the story that blew it — which is the kernel decision K-1 deliberately
+ * left un-taken, there being no story that needs it yet — or narrower columns,
+ * which trades an honest surface for an arithmetic one and is the worse of the
+ * two. Whichever is chosen, it is a decision with a reason, which is what a
+ * budget exists to force.
+ */
+const LIST_PAYLOAD_BUDGET_BYTES = 125_000;
+
+const SOURCE = distributionSource("pragma.conf.ts");
+
+/** One list-shaped body of a declared story, with the verb that runs it. */
+interface Body {
+  readonly label: string;
+  readonly verb: VerbSpec;
+}
+
+/**
+ * Every list-shaped body the distribution declares, DERIVED from the config —
+ * a story declared tomorrow is held to this budget by the author who declares
+ * it, without their help and without an entry in a list here.
+ */
+const BODIES: readonly Body[] = [...declaredStories].flatMap(
+  ([noun, story]) => {
+    const module = compileStoryModule(story, SOURCE, {});
+    const find = (verb: string): Body => {
+      const found = module.verbs.find(
+        (v) => verbKey(v.path) === `${noun} ${verb}`,
+      );
+      if (!found) throw new Error(`no compiled "${noun} ${verb}" verb`);
+      return { label: `${noun} ${verb}`, verb: found };
+    };
+    const bodies: Body[] = [];
+    if ((story.list as PackList | undefined) !== undefined) {
+      bodies.push(find("list"));
+    }
+    for (const verb of story.verbs ?? []) bodies.push(find(verb.verb));
+    return bodies;
+  },
+);
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  rt = bootRuntime(TEST_FLAGS);
+  await rt.store.get();
+}, 60_000);
+
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+/**
+ * The payload one call transmits, in bytes.
+ *
+ * The `json` formatter's own output is indented — it is read by humans through
+ * `--format json | jq` as often as by machines — but neither machine surface
+ * sends those spaces: both parse it and re-serialise into their envelope. So
+ * the budget measures what crosses the wire, not what the formatter's string
+ * happens to weigh.
+ */
+async function payloadBytes(
+  body: Body,
+  params: Record<string, unknown>,
+): Promise<{ rows: number; bytes: number }> {
+  const page = (await body.verb.run(params, rt)) as { rows: unknown[] };
+  const built = body.verb.output.formatters.json(page as never);
+  return {
+    rows: page.rows.length,
+    bytes: Buffer.byteLength(JSON.stringify(JSON.parse(built))),
+  };
+}
+
+describe("list response budget, shipped pack (PROTECTED)", () => {
+  it("derives every list-shaped body from the config", () => {
+    // A guard, not a no-op: an empty derivation would make the sweep below
+    // vacuously green, which is the failure mode a budget can least afford.
+    expect(BODIES.map((body) => body.label)).toContain("standard list");
+    expect(BODIES.length).toBeGreaterThanOrEqual(9);
+  });
+
+  it.each(BODIES.map((body) => [body.label, body] as const))(
+    "%s: the default answer is inside the budget",
+    async (_label, body) => {
+      const { rows, bytes } = await payloadBytes(body, {});
+      expect(bytes).toBeLessThanOrEqual(LIST_PAYLOAD_BUDGET_BYTES);
+      // The row half of the budget: the default page is the ceiling, and a
+      // body answering more of them would mean the page was not applied.
+      expect(rows).toBeLessThanOrEqual(DEFAULT_LIST_LIMIT);
+    },
+    60_000,
+  );
+
+  it.each(BODIES.map((body) => [body.label, body] as const))(
+    "%s: a population past the budget is PAGED, and each page is inside it",
+    async (_label, body) => {
+      // This case used to assert that the whole population also fitted one
+      // answer, and recorded that the two measurements were the same number
+      // because every story fitted one default page. Its own note said the day
+      // a story outgrew the page they would diverge and that this assertion
+      // would be what said so. They have diverged: the token-graph stories
+      // brought populations of 745, 1,156, 1,237 and 1,746 rows, and asking one
+      // of them for everything at once now measures 158 KB to 273 KB.
+      //
+      // So the claim moves to the one that survives, and it is the stronger of
+      // the two for exactly the bodies that broke the old one. The budget
+      // bounds an ANSWER, never a population — a population outgrowing it is
+      // what pagination is for, and the promise is that every page a caller can
+      // reach is inside the budget and that the pages together are the whole
+      // answer. A story still inside the budget is held to the old assertion
+      // unchanged, so nothing is given up where nothing had to be.
+      const whole = await payloadBytes(body, { limit: MAX_LIST_WINDOW });
+      if (whole.bytes <= LIST_PAYLOAD_BUDGET_BYTES) {
+        expect(whole.bytes).toBeLessThanOrEqual(LIST_PAYLOAD_BUDGET_BYTES);
+        return;
+      }
+      // Past the budget: every page inside it, and the pages exhaust the
+      // population rather than stopping short of it.
+      let after: string | undefined;
+      let seen = 0;
+      let pages = 0;
+      do {
+        const page = (await body.verb.run(
+          after === undefined ? {} : { after },
+          rt,
+        )) as PackPage;
+        const bytes = Buffer.byteLength(
+          JSON.stringify(
+            JSON.parse(body.verb.output.formatters.json(page as never)),
+          ),
+        );
+        expect(
+          bytes,
+          `page ${pages + 1} of ${body.label} is outside the budget`,
+        ).toBeLessThanOrEqual(LIST_PAYLOAD_BUDGET_BYTES);
+        expect(page.rows.length).toBeLessThanOrEqual(DEFAULT_LIST_LIMIT);
+        seen += page.rows.length;
+        after = page.nextAfter;
+        pages += 1;
+        // A guard against a cursor that never terminates: the kernel's own row
+        // ceiling bounds how far a caller may walk, so a walk needing more
+        // pages than that is a defect in the cursor rather than a big corpus.
+        expect(pages).toBeLessThan(MAX_LIST_WINDOW / DEFAULT_LIST_LIMIT);
+      } while (after !== undefined);
+      expect(pages).toBeGreaterThan(1);
+      expect(seen).toBe(whole.rows);
+    },
+    120_000,
+  );
+
+  it("the budget has headroom over the largest answer, and is not slack", async () => {
+    // A ceiling that no longer bounds anything catches nothing, and one sitting
+    // on the measurement flakes. Both halves are asserted so a future edit to
+    // the constant has to face them.
+    //
+    // The effective headroom is the 0.8 factor, not the 1.6 the ceiling was
+    // derived from: the largest answer may grow by 28 per cent before this
+    // turns red, and BUDGETS.md says 28 per cent for that reason. The two
+    // numbers answer different questions — 1.6 is how the ceiling was chosen,
+    // 0.8 is what the suite enforces — and the tighter one is the gate.
+    const measured = await Promise.all(
+      BODIES.map((body) => payloadBytes(body, {})),
+    );
+    const largest = Math.max(...measured.map((entry) => entry.bytes));
+    expect(largest).toBeGreaterThan(LIST_PAYLOAD_BUDGET_BYTES / 4);
+    expect(largest).toBeLessThan(LIST_PAYLOAD_BUDGET_BYTES * 0.8);
+  }, 60_000);
+
+  it("the kernel's row ceiling cannot ask for an answer above the budget", () => {
+    // The arithmetic that makes `MAX_LIST_WINDOW` a derived number rather than
+    // a taste: the narrowest row a story can serialise is `{}` and its
+    // separating comma, three bytes, so a limit above BUDGET/3 could not
+    // produce a legal answer whatever the story's columns are — and a limit
+    // that cannot produce a legal answer is not a legal limit. Asserted here
+    // because the ceiling lives in `paging.ts`, which cannot import a test.
+    expect(MAX_LIST_WINDOW * 3).toBeLessThanOrEqual(LIST_PAYLOAD_BUDGET_BYTES);
+    // And it is not so tight that it refuses a caller who wants everything.
+    expect(MAX_LIST_WINDOW).toBeGreaterThan(DEFAULT_LIST_LIMIT);
+  });
+});

package/src/capabilities/listLookup.shipped.exec.test.ts

@@ -0,0 +1,387 @@
+/**
+ * The list→lookup grammar, EXECUTED against the shipped pack, for every noun
+ * that has both halves (PROTECTED).
+ *
+ * The tool descriptions instruct an agent to take a row's `name` VERBATIM from
+ * `<noun>_list` to `<noun>_lookup`. That promise broke for `standard` when the
+ * shipped data and the story keyed the two halves on different properties:
+ * `standard list` published names synthesized from the IRI while
+ * `standard lookup` answered only the ~13% of standards carrying an asserted
+ * `cs:name` — a closed loop where every published address missed (#1047). The
+ * fixture suites could not see it, because a fixture obligingly asserts
+ * whatever the story reads; only the corpus the release actually ships can
+ * falsify the promise the release actually makes.
+ *
+ * So this file boots the SHIPPED graph and asserts the round trip over the
+ * WHOLE corpus, not a sample, for every noun with a list+lookup pair — the
+ * defect class is not standard-specific, since every pair shares this
+ * machinery. Three guarantees per noun:
+ *
+ * - every name `list` publishes resolves through `lookup` (executed through
+ *   the real verb bodies, so glob/IRI argument-shape dispatch is exercised
+ *   with the very strings an agent would paste);
+ * - every published name is in the addressable population (`listEntityNames`
+ *   — the ONE pool that feeds miss-suggestions, glob expansion AND `sample`'s
+ *   draw), so a suggestion can never offer a name the resolve cannot answer;
+ * - for a story that derives names (`nameFallback: "iri"`), that pool covers
+ *   the WHOLE class population — `sample` is presented as "see real data
+ *   shapes", and drawing only from the subset carrying an asserted name would
+ *   be the #1047 defect wearing sample's clothes.
+ *
+ * The final describe is the negative control: the same assertions run against
+ * a fixture compiled in the exact pre-#1047 shape (a list that synthesizes
+ * names over a lookup that requires the asserted property) and are shown to
+ * FAIL. A guard whose failing case no longer fails is worse than no guard.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compileStoryModule } from "../kernel/packs/compile.js";
+import { DEFAULT_LIST_LIMIT, MAX_LIST_WINDOW } from "../kernel/packs/paging.js";
+import { listEntityNames } from "../kernel/packs/resolveEntity.js";
+import {
+  distributionSource,
+  type PackDefinition,
+  type PackPage,
+} from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { CapabilityModule, VerbSpec } from "../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { TEST_FLAGS } from "../testing/helpers/projectCli.js";
+import { declaredStories, storyModules } from "./distribution.js";
+
+/** The provenance label the distribution's own compiled stories carry. */
+const SOURCE = distributionSource("pragma.conf.ts");
+
+/**
+ * Every noun declaring BOTH halves of the grammar, derived from the config
+ * rather than listed — a story added tomorrow is covered the moment it is
+ * declared, by the author who declares it and without their help.
+ */
+const NOUNS: readonly string[] = [...declaredStories]
+  .filter(([, story]) => story.list !== undefined && story.lookup !== undefined)
+  .map(([noun]) => noun);
+
+/**
+ * Nouns whose shipped corpus is empty TODAY — a data-content gap this suite
+ * does not own.
+ *
+ * EMPTY, and that is the allowlist working as designed rather than a list
+ * nobody maintains. `token` was its only entry, because the noun addressed
+ * `ds:Token` — a class no shipped graph asserted. Repointed at the token
+ * SYMBOLS, and with the token-ontology pack now publishing the name literal
+ * both halves of the grammar key on, the noun answers 745 rows and the entry
+ * had to go: an entry here is ASSERTED to have zero rows, so it goes red the
+ * moment the corpus arrives.
+ *
+ * The allowlist EXPIRES BY CONSTRUCTION, which is why it is kept rather than
+ * deleted. A list that merely skipped the non-empty assertion would be a
+ * permanent blind spot — a noun gains data, nobody removes the entry, a later
+ * regression back to zero rows stays vacuously green — which is exactly the
+ * hidden-empty case this guard exists to prevent, sitting inside the guard
+ * itself.
+ */
+const EMPTY_CORPUS_TODAY: readonly string[] = [];
+
+/** The verb `<noun> <verb>` from a compiled module, or throw naming the gap. */
+function verbOf(
+  module: CapabilityModule,
+  noun: string,
+  verb: string,
+): VerbSpec {
+  const found = module.verbs.find((v) => verbKey(v.path) === `${noun} ${verb}`);
+  if (!found) throw new Error(`no compiled "${noun} ${verb}" verb`);
+  return found;
+}
+
+/**
+ * Run `<noun> list` and return every name it publishes, verbatim, deduped.
+ *
+ * WALKS THE PAGES, and it has to. This file's promise is the round trip over the
+ * WHOLE corpus rather than a sample, and that used to come free: every declared
+ * population fitted inside one default page, so one call was the corpus. Three
+ * populations now exceed it — the token symbols, the platform variables and the
+ * chain — so reading one page would quietly turn this suite into a test of the
+ * first 300 names in alphabetical order, which is the sampling it exists to
+ * refuse.
+ *
+ * The walk is bounded by the kernel's own row ceiling for the same reason the
+ * budget sweep's is: a list needing more pages than that is a cursor defect, not
+ * a large corpus, and an unbounded `while` over a broken cursor would hang the
+ * suite instead of failing it.
+ */
+async function publishedNames(
+  rt: PragmaRuntime,
+  module: CapabilityModule,
+  noun: string,
+): Promise<string[]> {
+  const verb = verbOf(module, noun, "list");
+  const names = new Set<string>();
+  let after: string | undefined;
+  let pages = 0;
+  do {
+    const page = (await verb.run(
+      after === undefined ? {} : { after },
+      rt,
+    )) as PackPage;
+    for (const row of page.rows) {
+      const name = row.name ?? "";
+      if (name !== "") names.add(name);
+    }
+    after = page.nextAfter;
+    pages += 1;
+    if (pages > MAX_LIST_WINDOW / DEFAULT_LIST_LIMIT) {
+      throw new Error(
+        `${noun} list did not terminate after ${pages} pages — the cursor is not advancing`,
+      );
+    }
+  } while (after !== undefined);
+  return [...names];
+}
+
+/**
+ * Take every published name VERBATIM through the real lookup verb, exactly as
+ * the tool description instructs an agent to, and return the per-name errors.
+ * One batched call: the resolver treats each name independently, and a total
+ * miss throws — surfaced as one synthetic error so the assertion that reads
+ * this stays a set comparison rather than a try/catch.
+ */
+async function lookupErrors(
+  rt: PragmaRuntime,
+  module: CapabilityModule,
+  noun: string,
+  names: readonly string[],
+): Promise<{ query: string; code: string }[]> {
+  if (names.length === 0) return [];
+  try {
+    const output = (await verbOf(module, noun, "lookup").run(
+      { name: [...names] },
+      rt,
+    )) as { errors: { query: string; code: string }[] };
+    return output.errors;
+  } catch (error) {
+    return [
+      {
+        query: `(all ${names.length})`,
+        code: error instanceof Error ? error.message : String(error),
+      },
+    ];
+  }
+}
+
+// ONE store for the file — booting the shipped pack is the expensive part, and
+// this package already contends under parallel runs.
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  rt = bootRuntime(TEST_FLAGS);
+  await rt.store.get();
+}, 60_000);
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+/** One scalar from the shipped graph, queried directly. */
+async function scalar(query: string): Promise<string | undefined> {
+  const result = await rt.query.sparql(query);
+  if (result.type !== "select") return undefined;
+  const row = result.bindings[0];
+  return row === undefined ? undefined : Object.values(row)[0];
+}
+
+describe("every list-published name resolves through lookup, whole corpus (PROTECTED)", () => {
+  it("derives at least one list+lookup noun from the config", () => {
+    expect(NOUNS.length).toBeGreaterThan(0);
+    // The two nouns this guarantee has already been broken for / leaned on.
+    expect(NOUNS).toContain("standard");
+    expect(NOUNS).toContain("block");
+  });
+
+  it.each(NOUNS.map((noun) => [noun] as const))(
+    "%s: every published name round-trips, and its corpus is not silently empty",
+    async (noun) => {
+      const module = storyModules.get(noun) as CapabilityModule;
+      const names = await publishedNames(rt, module, noun);
+      if (EMPTY_CORPUS_TODAY.includes(noun)) {
+        // Asserted empty, not skipped: this is what expires the allowlist.
+        expect(
+          names,
+          `${noun} is allowlisted as an empty corpus but published rows — ` +
+            "delete it from EMPTY_CORPUS_TODAY so a later regression to zero rows cannot hide behind the entry",
+        ).toEqual([]);
+      } else {
+        expect(
+          names.length,
+          `${noun} list published no rows at all from the shipped pack`,
+        ).toBeGreaterThan(0);
+      }
+
+      const errors = await lookupErrors(rt, module, noun, names);
+      expect(
+        errors,
+        `${noun} list published ${errors.length} name(s) its own lookup cannot resolve — ` +
+          "the two-step grammar the tool descriptions document is broken for every agent following it",
+      ).toEqual([]);
+    },
+    120_000,
+  );
+
+  it.each(NOUNS.map((noun) => [noun] as const))(
+    "%s: every published name is in the pool that feeds suggestions, globs and sample",
+    async (noun) => {
+      const story = declaredStories.get(noun) as PackDefinition;
+      const lookup = story.lookup;
+      if (!lookup) throw new Error(`no "${noun}" lookup`);
+      const module = storyModules.get(noun) as CapabilityModule;
+
+      const names = await publishedNames(rt, module, noun);
+      const pool = await listEntityNames(rt, lookup, SOURCE);
+      // The resolve matches case-insensitively; hold the pool to the same bar.
+      const addressable = new Set(pool.map((name) => name.toLowerCase()));
+      const missing = names.filter(
+        (name) => !addressable.has(name.toLowerCase()),
+      );
+      expect(
+        missing,
+        `${noun}: published but not addressable — a miss-suggestion or glob over this pool can hand out none of these, and sample can never draw them`,
+      ).toEqual([]);
+    },
+    60_000,
+  );
+
+  it.each(
+    NOUNS.filter(
+      (noun) => declaredStories.get(noun)?.lookup?.nameFallback === "iri",
+    ).map((noun) => [noun] as const),
+  )(
+    "%s: the derived-name pool covers the WHOLE class population (sample is representative)",
+    async (noun) => {
+      const story = declaredStories.get(noun) as PackDefinition;
+      const lookup = story.lookup;
+      if (!lookup?.type && !lookup?.types?.length) {
+        throw new Error(`"${noun}" derives names without a class constraint`);
+      }
+      const types = (lookup.types ?? [lookup.type as string]).join(" ");
+      // The pool is DISTINCT NAMES, and a name may be legitimately shared (two
+      // shipped standards carry the same upstream rdfs:label; the ranked
+      // resolve answers a shared name with every entity it reaches). So the
+      // full-population claim is counted the way the pool is built: one name
+      // per asserted `by` value, plus one derived name per instance carrying
+      // none. A pool smaller than that is the #1047 defect — sample and
+      // suggestions drawing from the labelled subset only. (A prose label
+      // colliding with a slash-derived name would make this one too strict;
+      // that collision would itself be a data defect worth the red bar.)
+      const labelled = Number(
+        await scalar(
+          [
+            "SELECT (COUNT(DISTINCT ?name) AS ?n) WHERE {",
+            `  VALUES ?class { ${types} }`,
+            `  ?uri a ?class ; ${lookup.by} ?name .`,
+            "}",
+          ].join("\n"),
+        ),
+      );
+      const bare = Number(
+        await scalar(
+          [
+            "SELECT (COUNT(DISTINCT ?uri) AS ?n) WHERE {",
+            `  VALUES ?class { ${types} }`,
+            "  ?uri a ?class .",
+            `  FILTER NOT EXISTS { ?uri ${lookup.by} ?any . }`,
+            "}",
+          ].join("\n"),
+        ),
+      );
+      const pool = await listEntityNames(rt, lookup, SOURCE);
+
+      expect(labelled + bare).toBeGreaterThan(0);
+      expect(
+        pool.length,
+        `${noun}: ${labelled} asserted name(s) + ${bare} instance(s) with none, but only ` +
+          `${pool.length} addressable names — sample's draw pool is an unrepresentative slice of the corpus`,
+      ).toBe(labelled + bare);
+    },
+    60_000,
+  );
+});
+
+describe("negative control: the pre-#1047 shape fails these assertions", () => {
+  // The exact divergence that shipped: a list that COALESCEs an OPTIONAL
+  // display name with an IRI-derived one, over a lookup that requires the
+  // asserted property (no nameFallback). One fixture standard carries the
+  // property; the other is published under a name the lookup cannot reach.
+  const PREFIXES = {
+    rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    cs: "http://pragma.canonical.com/codestandards#",
+  };
+  const TTL = `
+    @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+    @prefix owl: <http://www.w3.org/2002/07/owl#> .
+    @prefix cs: <http://pragma.canonical.com/codestandards#> .
+
+    cs:name a owl:DatatypeProperty .
+    cs:description a owl:DatatypeProperty .
+
+    cs:react.component.tsdoc a cs:CodeStandard ;
+      cs:description "Published under a derived name; carries no cs:name." .
+    cs:code.function.purity a cs:CodeStandard ;
+      cs:name "Function purity" ;
+      cs:description "Carries an asserted cs:name." .
+  `;
+  const BROKEN_STORY: PackDefinition = {
+    noun: "standard",
+    description: "pre-#1047 shape",
+    list: {
+      query: [
+        "SELECT ?uri ?name ?description WHERE {",
+        "  ?uri a cs:CodeStandard ;",
+        "       cs:description ?description .",
+        "  OPTIONAL { ?uri cs:name ?n . }",
+        '  BIND(COALESCE(?n, REPLACE(STRAFTER(STR(?uri), "#"), "\\\\.", "/")) AS ?name)',
+        "}",
+        "ORDER BY ?name",
+      ].join("\n"),
+      columns: [
+        { field: "name", label: "Name" },
+        { field: "description", label: "Description" },
+      ],
+    },
+    lookup: {
+      source: "sparql",
+      by: "cs:name", // required — no nameFallback: the pre-#1047 population
+      type: "cs:CodeStandard",
+      fields: [
+        {
+          name: "description",
+          property: "cs:description",
+          label: "Description",
+        },
+      ],
+    },
+  };
+
+  it("publishes a name its own lookup cannot resolve, and these assertions catch it", async () => {
+    const { rt: fixtureRt } = await buildFixtureRuntime({
+      ttl: TTL,
+      prefixes: PREFIXES,
+    });
+    const module = compileStoryModule(BROKEN_STORY, SOURCE, PREFIXES);
+
+    const names = await publishedNames(fixtureRt, module, "standard");
+    expect(names).toContain("react/component/tsdoc");
+    expect(names).toContain("Function purity");
+
+    // The round-trip assertion goes RED on the synthesized name…
+    const errors = await lookupErrors(fixtureRt, module, "standard", names);
+    expect(errors.map((error) => error.query)).toEqual([
+      "react/component/tsdoc",
+    ]);
+
+    // …and so does the pool-inclusion assertion: the addressable population
+    // is only the labelled subset.
+    const lookup = BROKEN_STORY.lookup;
+    if (!lookup) throw new Error("fixture story has no lookup");
+    const pool = await listEntityNames(fixtureRt, lookup, SOURCE);
+    expect(pool).toEqual(["Function purity"]);
+  }, 60_000);
+});