@canonical/pragma-cli 0.36.0 → 0.37.0

package/src/capabilities/doctor/checks/checkNodeVersion.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Covers the two things `checkNodeVersion` owns beyond the range comparison:
+ * the shape of the CheckResult, and that the failure path quotes the declared
+ * range rather than a number of its own. The range logic itself is pinned in
+ * `isSupportedNodeVersion.test.ts`.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SUPPORTED_NODE_RANGE } from "../../../constants.js";
+import { checkNodeVersion } from "./checkNodeVersion.js";
+
+/** Swap `process.versions.node`, which is read-only in the normal way. */
+function withNodeVersion(version: string) {
+  vi.spyOn(process, "versions", "get").mockReturnValue({
+    ...process.versions,
+    node: version,
+  });
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("checkNodeVersion — reports against the declared range", () => {
+  it("passes on a supported version and reports it", async () => {
+    withNodeVersion("24.18.1");
+    const result = await checkNodeVersion();
+    expect(result).toEqual({
+      name: "Node version",
+      status: "pass",
+      detail: "v24.18.1",
+    });
+  });
+
+  it("fails on an unsupported version and quotes the declared range", async () => {
+    withNodeVersion("20.19.0");
+    const result = await checkNodeVersion();
+    expect(result.status).toBe("fail");
+    expect(result.detail).toContain("v20.19.0");
+    // The range must come from the manifest, never from a literal in the check.
+    expect(result.detail).toContain(SUPPORTED_NODE_RANGE);
+    expect(result.remedy).toContain(SUPPORTED_NODE_RANGE);
+  });
+
+  it("fails inside the 23.0-23.5 window the range excludes", async () => {
+    withNodeVersion("23.2.0");
+    expect((await checkNodeVersion()).status).toBe("fail");
+  });
+});

package/src/capabilities/doctor/checks/checkNodeVersion.ts

@@ -1,25 +1,29 @@
+import { SUPPORTED_NODE_RANGE } from "../../../constants.js";
 import type { CheckResult } from "../types.js";
-
-const MIN_NODE_MAJOR = 20;
+import { isSupportedNodeVersion } from "./isSupportedNodeVersion.js";
 
 /**
- * Check that the Node.js major version is at least {@link MIN_NODE_MAJOR}.
+ * Check that the running Node.js version satisfies this package's declared
+ * `engines.node` range.
+ *
+ * The floor is a property of the manifest, not of this file: a check that
+ * hardcodes its own number can disagree with the range the package publishes,
+ * and a consumer then passes a check the install contract would have failed.
  *
  * @returns A CheckResult with the current version and pass/fail status.
  * @note Impure — reads `process.versions`.
  */
 export async function checkNodeVersion(): Promise<CheckResult> {
   const version = process.versions.node;
-  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
 
-  if (major >= MIN_NODE_MAJOR) {
+  if (isSupportedNodeVersion(version)) {
     return { name: "Node version", status: "pass", detail: `v${version}` };
   }
 
   return {
     name: "Node version",
     status: "fail",
-    detail: `v${version} (requires >= ${MIN_NODE_MAJOR})`,
-    remedy: `Install Node.js >= ${MIN_NODE_MAJOR}`,
+    detail: `v${version} (requires ${SUPPORTED_NODE_RANGE})`,
+    remedy: `Install Node.js ${SUPPORTED_NODE_RANGE}`,
   };
 }

package/src/capabilities/doctor/checks/isSupportedNodeVersion.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Pins the hand-written comparison in `isSupportedNodeVersion` to the range the
+ * package actually declares.
+ *
+ * The implementation encodes `engines.node` as a chain of comparisons rather
+ * than parsing it, so nothing structural stops the two drifting apart. This
+ * suite closes that by building a SECOND, independent predicate directly from
+ * the declared range string and requiring both to agree across a version grid.
+ * A change to `engines.node` therefore moves the oracle and fails here until the
+ * implementation is moved with it — which a table of hand-written expectations
+ * could not do, since its cheapest repair is editing the expectations.
+ */
+
+import { describe, expect, it } from "vitest";
+import { SUPPORTED_NODE_RANGE } from "../../../constants.js";
+import { isSupportedNodeVersion } from "./isSupportedNodeVersion.js";
+
+/**
+ * Evaluate a version against a range of the form `>=22.18 <23 || >=23.6`.
+ *
+ * Deliberately naive and deliberately separate from the implementation: it is
+ * an oracle, not a utility, and it throws on any comparator shape it was not
+ * written for so a widened range fails loudly instead of silently passing.
+ */
+function satisfiesDeclaredRange(version: string, range: string): boolean {
+  // Semver excludes prereleases from a range unless a comparator opts in, and
+  // none of ours does. Encoded here too, so the oracle and the implementation
+  // are held to the same rule rather than agreeing by omission.
+  if (version.includes("-")) return false;
+
+  const rank = (major: number, minor: number) => major * 1_000_000 + minor;
+  const [major = Number.NaN, minor = Number.NaN] = version
+    .split(".")
+    .map(Number);
+
+  return range.split("||").some((clause) =>
+    clause
+      .trim()
+      .split(/\s+/)
+      .every((comparator) => {
+        // A comparator may be major-only (`<23`) or major.minor (`>=22.18`).
+        const parsed = /^(>=|<)(\d+)(?:\.(\d+))?$/.exec(comparator);
+        if (!parsed)
+          throw new Error(`oracle cannot parse comparator: ${comparator}`);
+        const [, operator, boundMajor, boundMinor] = parsed;
+        const actual = rank(major, minor);
+        const bound = rank(Number(boundMajor), Number(boundMinor ?? 0));
+        return operator === ">=" ? actual >= bound : actual < bound;
+      }),
+  );
+}
+
+const GRID = [
+  "20.19.0",
+  "21.7.3",
+  "22.0.0",
+  "22.12.0",
+  "22.17.9",
+  "22.18.0",
+  "22.18.1",
+  "22.99.0",
+  "23.0.0",
+  "23.5.9",
+  "23.6.0",
+  "23.9.0",
+  "24.0.0",
+  "24.18.1",
+  "25.0.0",
+  "26.0.0",
+  // Prereleases: numerically inside the range, excluded by semver.
+  "22.18.0-pre",
+  "23.6.0-nightly",
+  "24.0.0-rc.1",
+];
+
+describe("isSupportedNodeVersion — agrees with the declared engines range", () => {
+  it.each(GRID)("matches the oracle for %s", (version) => {
+    expect(isSupportedNodeVersion(version)).toBe(
+      satisfiesDeclaredRange(version, SUPPORTED_NODE_RANGE),
+    );
+  });
+
+  // The oracle is only trustworthy if it can disagree; prove it discriminates
+  // rather than returning a constant.
+  it("uses an oracle that actually discriminates", () => {
+    const verdicts = GRID.map((v) =>
+      satisfiesDeclaredRange(v, SUPPORTED_NODE_RANGE),
+    );
+    expect(verdicts).toContain(true);
+    expect(verdicts).toContain(false);
+  });
+
+  it("rejects prerelease builds whose numeric part is in range", () => {
+    // Asserted directly, not only through the oracle: if both sides dropped the
+    // rule together the grid would still agree and prove nothing.
+    for (const pre of ["22.18.0-pre", "23.6.0-nightly", "24.0.0-rc.1"]) {
+      expect(isSupportedNodeVersion(pre)).toBe(false);
+    }
+    // The same versions without the suffix are supported, so it is the suffix
+    // doing the work and not the numbers.
+    for (const stable of ["22.18.0", "23.6.0", "24.0.0"]) {
+      expect(isSupportedNodeVersion(stable)).toBe(true);
+    }
+  });
+
+  it("fails closed on a version it cannot parse", () => {
+    for (const bad of ["not-a-version", "", "v24.1.0", "24"]) {
+      expect(isSupportedNodeVersion(bad)).toBe(false);
+    }
+  });
+});

package/src/capabilities/doctor/checks/isSupportedNodeVersion.ts

@@ -0,0 +1,34 @@
+/**
+ * Whether a Node.js version satisfies the range this package declares in its
+ * own `engines.node`, surfaced as `SUPPORTED_NODE_RANGE` in `constants.ts`.
+ *
+ * The range is expressed here as a comparison rather than parsed: the CLI
+ * carries no semver dependency, and one range does not justify a range parser.
+ * What keeps the two honest is `isSupportedNodeVersion.test.ts`, which builds an
+ * independent predicate straight from the declared range string and requires
+ * the two to agree across a version grid — so a change to `engines.node` that
+ * is not mirrored here fails the suite rather than shipping.
+ *
+ * A major-only comparison cannot express this range: it cannot say "22.18 but
+ * not 22.0", and it cannot exclude the 23.0–23.5 window.
+ *
+ * @param version - A Node version string, e.g. `process.versions.node`.
+ * @returns Whether the version falls inside the declared range.
+ */
+export function isSupportedNodeVersion(version: string): boolean {
+  // A semver range excludes prereleases unless a comparator opts into them, and
+  // `engines.node` opts into none. So `22.18.0-pre` is outside the declared
+  // range even though its numeric part is inside it, and reporting it as
+  // supported would be doctor passing a runtime the install contract rejects.
+  if (version.includes("-")) return false;
+
+  const [rawMajor, rawMinor] = version.split(".");
+  const major = Number(rawMajor);
+  const minor = Number(rawMinor);
+
+  if (!Number.isInteger(major) || !Number.isInteger(minor)) return false;
+  if (major < 22) return false;
+  if (major === 22) return minor >= 18;
+  if (major === 23) return minor >= 6;
+  return true;
+}

package/src/capabilities/doctor/checks/mcpCommand.test.ts

@@ -45,6 +45,12 @@ describe("commandOf — one executable, either entry shape", () => {
   });
 });
 
+// Every test in this suite writes into a temp directory and then resolves
+// against it, so each one is bound by filesystem latency rather than by any
+// work of its own. Vitest's 5s default is comfortable on an idle machine and
+// marginal on a loaded one — this suite has timed out in CI while asserting
+// nothing slow. Ten seconds keeps the assertions meaningful without making a
+// genuine hang cheap to ignore.
 describe("commandResolves — the host's own resolution rules", () => {
   const dirs: string[] = [];
   const tmp = (): string => {
@@ -97,4 +103,4 @@ describe("commandResolves — the host's own resolution rules", () => {
       await commandResolves("./local-bin", dir, hostOf("linux", dir)),
     ).toBe(true);
   });
-});
+}, 10_000);

package/src/capabilities/lazy.test.ts

@@ -88,8 +88,9 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
 
   it("the dispatch path never reaches the embedded n-quads module (PROTECTED)", () => {
     // `activeStories` reads the pack's carried stories from their OWN generated
-    // module rather than through `graphpack/embedded.ts`, which statically
-    // imports the ~1.9 MB `pack.generated.ts`. Restoring that edge costs a
+    // module rather than through `graphpack/embedded.ts`, which reaches the
+    // ~2.1 MB `pack.generated.ts` (dynamically since the manifest split, but
+    // this path must not reach it at all). Restoring that edge costs a
     // measured +23 ms on EVERY dispatched command, and the whole test suite
     // passes with it restored — the split is prose in three docblocks and
     // nothing else. This is the constraint those docblocks describe.
@@ -104,6 +105,29 @@ describe("lazy dispatch — module-graph probe (PROTECTED)", () => {
     }
   });
 
+  it("`embedded.ts` itself never statically imports the payload (PROTECTED)", () => {
+    // The store-boot path DOES go through `graphpack/embedded.ts`, so the test
+    // above cannot cover it. `materializeEmbeddedPack` reads the manifest to
+    // name the cache directory and then returns early when the pack is already
+    // there — the common case — so a static import of `pack.generated.ts` would
+    // parse ~2.1 MB of n-quads to reach that return, on every boot.
+    //
+    // Restoring `import { dataNq } from "./embedded/pack.generated.js"` at
+    // module scope costs a measured ~370 ms per CLI invocation on a
+    // 30,340-triple pack, and every other test still passes. This is the only
+    // thing standing between that edit and a silent regression.
+    for (const entry of [
+      "../kernel/runtime/graphpack/embedded.ts",
+      "../kernel/runtime/loadSession.ts",
+    ]) {
+      const graph = staticImportGraph(resolve(here, entry));
+      expect(has(graph, "embedded/pack.manifest.generated.ts"), entry).toBe(
+        true,
+      );
+      expect(has(graph, "embedded/pack.generated.ts"), entry).toBe(false);
+    }
+  });
+
   it("the help path (buildProgram) imports no zod schema module", () => {
     const graph = staticImportGraph(
       resolve(here, "../kernel/project/cli/buildProgram.ts"),

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

@@ -0,0 +1,340 @@
+/**
+ * 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 { listEntityNames } from "../kernel/packs/resolveEntity.js";
+import {
+  distributionSource,
+  type PackDefinition,
+} 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 (`ds:Token` has no instances in
+ * the current packs) — a data-content gap this suite does not own.
+ *
+ * The allowlist EXPIRES BY CONSTRUCTION: an entry here is asserted to have
+ * ZERO rows, so the moment upstream ships instances the entry goes red and
+ * must be deleted. A list that merely skipped the non-empty assertion would
+ * be a permanent blind spot — `token` 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[] = ["token"];
+
+/** 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 the names it publishes, verbatim, deduped. */
+async function publishedNames(
+  rt: PragmaRuntime,
+  module: CapabilityModule,
+  noun: string,
+): Promise<string[]> {
+  const rows = (await verbOf(module, noun, "list").run({}, rt)) as Record<
+    string,
+    string
+  >[];
+  return [
+    ...new Set(rows.map((row) => row.name ?? "").filter((name) => name !== "")),
+  ];
+}
+
+/**
+ * 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);
+});