@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/testing/behavioral/journeys.implementation.test.ts

@@ -0,0 +1,206 @@
+/**
+ * The `implementation` story's SEMANTICS, in-process through the real CLI
+ * dispatch path (`executeVerb`), against the canonical fixture.
+ *
+ * The generic live-surface tests call `implementation_list` with empty
+ * parameters and check the envelope, so they stay green whether or not the
+ * story means anything: the block-name join could resolve to the wrong subject,
+ * the IRI fallback could never fire, and `--platform` / `--library` could
+ * filter nothing at all. Those are the four claims the noun actually makes, so
+ * they are pinned here rather than left to the envelope.
+ *
+ * The join is the reason this noun exists and the reason it is worth a
+ * fixture-backed test: `ds:implementsBlock` points from an implementation
+ * collected in THIS repository at a block declared by a DIFFERENT pack, and the
+ * row's `block` column is the design system's own `ds:name` reached across that
+ * edge — not a string this repository holds anywhere.
+ */
+
+import { afterAll, describe, expect, it } from "vitest";
+import { storyModules } from "../../capabilities/distribution.js";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  CANONICAL_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { JSON_FLAGS, NO_MUTATION } from "../helpers/parity.js";
+
+const implementationModule = storyModules.get("implementation");
+if (!implementationModule) {
+  throw new Error('pragma.conf.ts declares no story for "implementation"');
+}
+
+const verbOf = (key: string): VerbSpec =>
+  implementationModule.verbs.find((v) => verbKey(v.path) === key) as VerbSpec;
+
+const listVerb = verbOf("implementation list");
+const librariesVerb = verbOf("implementation libraries");
+
+const fixtures: FixtureGraph[] = [];
+afterAll(async () => {
+  await Promise.all(fixtures.map((f) => f.dispose()));
+});
+
+/** Boot one tracked canonical fixture, for auto-disposal. */
+async function boot(): Promise<FixtureGraph> {
+  const fixture = await bootFixtureRuntime({
+    ttl: CANONICAL_TTL,
+    config: CANONICAL_CONFIG,
+  });
+  fixtures.push(fixture);
+  return fixture;
+}
+
+type Row = Record<string, string>;
+
+async function rows(
+  verb: VerbSpec,
+  params: Record<string, unknown> = {},
+): Promise<Row[]> {
+  const fixture = await boot();
+  const out = await executeVerb(
+    verb,
+    params,
+    NO_MUTATION,
+    bootRuntime(JSON_FLAGS, fixture.cwd),
+  );
+  return JSON.parse(out.stdout as string).data as Row[];
+}
+
+/**
+ * What the fixture's implementation graph says, as pairs: Button is
+ * implemented TWICE, on two platforms, and Modal once.
+ */
+const EVERY_PAIR = [
+  "Button|@canonical/react-ds-global",
+  "Button|@canonical/svelte-ds-global",
+  "Modal|@canonical/react-ds-global",
+];
+
+const pairs = (list: Row[]): string[] =>
+  list.map((r) => `${r.block}|${r.library}`).sort();
+
+describe("implementation list — the cross-pack join", () => {
+  it("names each block by the design system's ds:name, not by its IRI", async () => {
+    // `ds:implementsBlock ds:button` carries no name; `Button` exists only on
+    // the block node BLOCK_TTL declares. A row reading `button` here would mean
+    // the join silently degraded to the IRI fallback and nobody noticed.
+    const list = await rows(listVerb);
+    expect(pairs(list)).toEqual(EVERY_PAIR);
+    expect(list.map((r) => r.block)).not.toContain("button");
+  });
+
+  it("one block implemented twice yields two rows, one per library", async () => {
+    // The row is the EDGE, not the block: collapsing the two Button rows into
+    // one would answer "is this implemented?" while losing "by whom", which is
+    // the question the noun exists for.
+    const list = await rows(listVerb);
+    expect(list.filter((r) => r.block === "Button")).toHaveLength(2);
+  });
+
+  it("carries the source link and the implementation's own IRI", async () => {
+    const list = await rows(listVerb);
+    const react = list.find(
+      (r) => r.block === "Button" && r.platform === "react",
+    );
+    expect(react?.source).toBe("https://example.test/react/Button.tsx");
+    expect(react?.uri).toBe(
+      "https://ds.canonical.com/implementation.react-ds-global.button",
+    );
+  });
+
+  it("falls back to the IRI local name for a block the store does not declare", async () => {
+    // The design-system pack can be absent while this one is present — a
+    // `sources` config carrying only the implementation graph. The row must
+    // stay readable, so the fallback is exercised against an edge whose target
+    // is a bare IRI with no `ds:name` anywhere in the store.
+    const fixture = await bootFixtureRuntime({
+      ttl: `${CANONICAL_TTL}
+ds:implementation.library.orphan-lib a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/orphan-lib" ;
+  ds:platform "react" ;
+  ds:hasImplementation ds:implementation.orphan-lib.unnamed .
+
+ds:implementation.orphan-lib.unnamed a ds:ImplementationObject ;
+  ds:implementsBlock ds:global.component.unnamed_block ;
+  ds:headLink "https://example.test/orphan/Unnamed.tsx" .
+`,
+      config: CANONICAL_CONFIG,
+    });
+    fixtures.push(fixture);
+    const out = await executeVerb(
+      listVerb,
+      {},
+      NO_MUTATION,
+      bootRuntime(JSON_FLAGS, fixture.cwd),
+    );
+    const list = JSON.parse(out.stdout as string).data as Row[];
+    const orphan = list.find((r) => r.library === "@canonical/orphan-lib");
+    expect(orphan?.block).toBe("global.component.unnamed_block");
+  });
+});
+
+describe("implementation list — the declared filters", () => {
+  it("--platform keeps only that platform's rows", async () => {
+    expect(pairs(await rows(listVerb, { platform: "svelte" }))).toEqual([
+      "Button|@canonical/svelte-ds-global",
+    ]);
+  });
+
+  it("--library keeps only that library's rows", async () => {
+    expect(
+      pairs(await rows(listVerb, { library: "@canonical/react-ds-global" })),
+    ).toEqual([
+      "Button|@canonical/react-ds-global",
+      "Modal|@canonical/react-ds-global",
+    ]);
+  });
+
+  it("--search matches the block name and the library name alike", async () => {
+    expect(pairs(await rows(listVerb, { search: "modal" }))).toEqual([
+      "Modal|@canonical/react-ds-global",
+    ]);
+    expect(pairs(await rows(listVerb, { search: "svelte" }))).toEqual([
+      "Button|@canonical/svelte-ds-global",
+    ]);
+  });
+});
+
+describe("implementation libraries — the library rows", () => {
+  it("lists every library with its platform, tier, version and block count", async () => {
+    const list = await rows(librariesVerb);
+    expect(list.map((r) => r.name).sort()).toEqual([
+      "@canonical/react-ds-global",
+      "@canonical/svelte-ds-global",
+    ]);
+    const react = list.find((r) => r.name === "@canonical/react-ds-global");
+    expect(react).toMatchObject({
+      platform: "react",
+      tier: "global",
+      version: "0.34.0",
+      count: "2",
+    });
+  });
+
+  it("the counts agree with the rows `implementation list` returns", async () => {
+    // `ds:implementationCount` is asserted by the aggregate INDEX, on the same
+    // subject the per-library file describes. The two files can drift apart in
+    // the generator, and a count that disagrees with the edges is worse than no
+    // count at all — so the two halves are compared rather than each pinned.
+    const [libraries, list] = await Promise.all([
+      rows(librariesVerb),
+      rows(listVerb),
+    ]);
+    for (const library of libraries) {
+      const actual = list.filter((r) => r.library === library.name).length;
+      expect(Number(library.count)).toBe(actual);
+    }
+  });
+});

package/src/testing/behavioral/journeys.interactiveTty.e2e.test.ts

@@ -24,8 +24,8 @@
  *
  * TODO(AV-231/E4): when `node-pty` (or an equivalent PTY shim) is on the
  * devDependency set, replace each `it.todo` with a PTY-driven `it` that spawns
- * `dist/pragma create …` under a pty, writes the keystroke, and asserts the exit
- * code + "Cancelled." line. The compiled binary is already provisioned for the
+ * the shipped `pragma create …` under a pty, writes the keystroke, and asserts the exit
+ * code + "Cancelled." line. The shipped entry is already provisioned for the
  * spawn-e2e layer by `testing/perf/globalSetup.ts`.
  */
 

package/src/testing/behavioral/journeys.packageStories.test.ts

@@ -1,11 +1,11 @@
 /**
- * The package tier, end to end: a noun the binary never shipped.
+ * The package tier, end to end: a noun the distribution never shipped.
  *
  * A package that ships `stories/*.json` and is declared as a `file:` pack
  * contributes a working command to a project that declares it — resolved by
  * `sources update`, hashed into the pack, written into the pack directory, read
  * back storelessly at dispatch, and answered from the fixture graph. Proven both
- * in-process and through the COMPILED binary in a real subprocess.
+ * in-process and through the SHIPPED entry in a real subprocess.
  *
  * The same package also ships a malformed story and a schema-invalid one. Those
  * must be DROPPED, not fatal: package stories reach dispatch before the command
@@ -43,7 +43,7 @@ ex:soup a ex:Recipe ; ex:name "Soup" .
 ex:stew a ex:Recipe ; ex:name "Stew" .
 `;
 
-/** A valid read story — the noun the binary never shipped. */
+/** A valid read story — the noun the distribution never shipped. */
 const RECIPE_STORY = JSON.stringify({
   noun: "recipe",
   description: "List recipes.",
@@ -147,7 +147,7 @@ describe("the two recoveries still run with bad stories in the pack", () => {
   });
 });
 
-describe("the compiled binary answers the package's noun (subprocess)", () => {
+describe("the shipped entry answers the package's noun (subprocess)", () => {
   it("pragma recipe list --format json returns the package's rows", () => {
     const result = runCli(["recipe", "list", "--format", "json"], {
       cwd: graph.cwd,

package/src/testing/behavioral/mcpServe.e2e.test.ts

@@ -1,10 +1,17 @@
 /**
- * A7 — `pragma mcp` serve boot, observed through the real compiled binary.
+ * A7 — `pragma mcp serve` boot, observed through the real shipped entry.
  *
  * Replaces the old mocked-SIGINT unit test: `runCli` spawns with no `input`,
  * which gives the child an immediately-EOF stdin (verified equivalent to
  * `< /dev/null`) — the shape a host that closes the pipe on shutdown produces.
  * The server must connect and exit cleanly, not hang or crash.
+ *
+ * The other half of the contract is the one the bin's narrow short-circuit
+ * exists to keep honest: only the exact serve invocation serves. `pragma mcp`,
+ * any help form, and any argv with a token after `serve` print text or an
+ * error and start NO server — which is only observable across the process
+ * boundary, because in-process dispatch never reaches the short-circuit at
+ * all.
  */
 
 import { describe, expect, it } from "vitest";
@@ -12,10 +19,58 @@ import { runCli } from "../helpers/runCli.js";
 
 describe("mcp serve — stdin close boots and exits cleanly (A7, e2e)", () => {
   it("exits 0 with no output and no signal", () => {
-    const result = runCli(["mcp"]);
+    const result = runCli(["mcp", "serve"]);
     expect(result.exitCode).toBe(0);
     expect(result.signal).toBeNull();
     expect(result.stdout).toBe("");
     expect(result.stderr).toBe("");
   });
 });
+
+describe("mcp — the noun is ordinary grammar (e2e)", () => {
+  it("bare `mcp` prints the noun help and exits 0, serving nothing", () => {
+    const result = runCli(["mcp"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("Usage: pragma mcp");
+    expect(result.stdout).toContain("serve");
+    // A JSON-RPC handshake would have started with `{`; help never does.
+    expect(result.stdout.startsWith("{")).toBe(false);
+  });
+
+  it("`mcp --help` prints help rather than starting the server", () => {
+    const result = runCli(["mcp", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("serve");
+  });
+
+  it("`mcp serve --help` documents the verb rather than starting it", () => {
+    const result = runCli(["mcp", "serve", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("Start the MCP server over stdio");
+    expect(result.stdout).toContain("Usage: pragma mcp serve");
+  });
+});
+
+/**
+ * The short-circuit matches argv EXACTLY. A prefix match would extend the
+ * stdio-purity budget — no flag parsing, no first-run, nothing on stdout but
+ * JSON-RPC — to argv the server was never asked to answer, so a suffixed line
+ * would serve instead of being parsed. These are the two suffixes that prove
+ * the fall-through: a global flag the program owns, and a stray operand.
+ */
+describe("mcp serve — anything suffixed falls through to the grammar (e2e)", () => {
+  it("`mcp serve --version` answers the global flag, serving nothing", () => {
+    const result = runCli(["mcp", "serve", "--version"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+    // A JSON-RPC handshake would have started with `{`; a version never does.
+    expect(result.stdout.startsWith("{")).toBe(false);
+  });
+
+  it("`mcp serve extra` is parsed, so its bad global value is rejected", () => {
+    const result = runCli(["mcp", "serve", "extra", "--format", "bogus"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid format "bogus"');
+    expect(result.stdout).toBe("");
+  });
+});

package/src/testing/behavioral/mcpSurface.test.ts

@@ -13,7 +13,7 @@
  * Representative args are built structurally: a lookup/sample's positional
  * resolves through its noun's OWN `list` (browse-then-address, same as B1); a
  * `prefix`/`uri`-named positional (the grammar's TBox/entity-inspection
- * convention, used today by `ontology show`/`graph inspect`) resolves from the
+ * convention, used today by `ontology lookup`/`graph inspect`) resolves from the
  * pack index generically, not by noun name. A mutating tool is called WITHOUT
  * `confirm` (a safe plan-only preview).
  */

package/src/testing/behavioral/rootCli.e2e.test.ts

@@ -22,8 +22,32 @@ describe("--version at every level (A2, e2e)", () => {
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
   });
 
-  it("-v is equivalent to --version", () => {
-    expect(runCli(["-v"]).stdout.trim()).toBe(VERSION);
+  it("-v is rejected — --version is the one spelling", () => {
+    const result = runCli(["-v"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Unknown option "-v"');
+  });
+});
+
+describe("global value flags reject bad values loudly (e2e)", () => {
+  it("--format text is not a format", () => {
+    const result = runCli(["config", "show", "--format", "text"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid format "text"');
+    expect(result.stderr).toContain("plain, llm, json");
+  });
+
+  it("--detail rejects an unrecognized level, naming the valid ones", () => {
+    const result = runCli(["config", "show", "--detail", "bogus"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain('Invalid detail "bogus"');
+    expect(result.stderr).toContain("summary, standard, detailed");
+  });
+
+  it("--verbose=<x> is rejected — the flag takes no value", () => {
+    const result = runCli(["config", "show", "--verbose=true"]);
+    expect(result.exitCode).toBe(2);
+    expect(result.stderr).toContain("`--verbose` takes no value");
   });
 });
 

package/src/testing/eval/cases/effectful.ts

@@ -88,7 +88,7 @@ export const effectfulEvalCases: readonly EvalCase[] = [
     id: "tool-doctor-reports-check-tallies",
     kind: "tool",
     input:
-      "doctor returns a { checks, passed, failed, skipped } diagnostic report where the tallies sum to the checks.",
+      "doctor returns a { checks, passed, failed, available, skipped } diagnostic report where the tallies sum to the checks.",
     async expect({ mcp }) {
       const result = await mcp.callTool("doctor");
       assert.equal(result.ok, true);
@@ -96,11 +96,12 @@ export const effectfulEvalCases: readonly EvalCase[] = [
         checks: unknown[];
         passed: number;
         failed: number;
+        available: number;
         skipped: number;
       };
       assert.ok(Array.isArray(data.checks), "expected a checks array");
       assert.equal(
-        data.passed + data.failed + data.skipped,
+        data.passed + data.failed + data.available + data.skipped,
         data.checks.length,
       );
     },

package/src/testing/fixtures/blockGraph.ts

@@ -21,6 +21,18 @@ export const BLOCK_PREFIXES: Readonly<Record<string, string>> = {
   xsd: "http://www.w3.org/2001/XMLSchema#",
 };
 
+/**
+ * A membership roster deep enough to cross the entity read's fan-in threshold,
+ * so the fixture exercises the SAMPLED branch and not only the listed one.
+ * Generated rather than written out: the count is the whole point of the case,
+ * and 22 hand-copied lines invite someone to "tidy" one away.
+ */
+const ROSTER_MEMBER_COUNT = 22;
+const ROSTER_MEMBERS = Array.from(
+  { length: ROSTER_MEMBER_COUNT },
+  (_, index) => `ds:probe.member${index} a ds:Probe ; ds:tier ds:rosterHub .`,
+).join("\n");
+
 /** The fixture ontology + individuals as Turtle. */
 export const BLOCK_TTL = `
 @prefix ds: <https://ds.canonical.com/> .
@@ -109,4 +121,71 @@ ds:mod.importance.secondary a ds:Modifier ; ds:name "secondary" ; ds:modifierFam
 ds:mod.density.compact a ds:Modifier ; ds:name "compact" ; ds:modifierFamily ds:family.density .
 ds:mod.size.small a ds:Modifier ; ds:name "small" ; ds:modifierFamily ds:family.size .
 ds:mod.size.large a ds:Modifier ; ds:name "large" ; ds:modifierFamily ds:family.size .
+
+# ---- Neighbourhood-read probes ----
+# Typed \`ds:Probe\`, which is deliberately NOT declared as an owl:Class and is
+# outside the block VALUES set, so these individuals reach the entity reader
+# without entering any block list or the ontology class listing.
+#
+# literalTrap holds a STRING that begins with the ds: namespace. Read through
+# the lossy string view it was indistinguishable from an IRI and got compacted
+# into something that read back as one; the term view is what tells them apart.
+ds:literalTrap a ds:Probe ;
+  ds:name "literal trap" ;
+  ds:figmaLink "https://ds.canonical.com/not-an-iri" .
+
+# blankHolder carries blank-node objects — store-local handles that re-mint on
+# every load — so the read must inline them as records AND order those records
+# by content rather than by the label that grouped them.
+ds:blankHolder a ds:Probe ;
+  ds:name "blank holder" ;
+  ds:changeLog [ a ds:ChangeLogEntry ; ds:changeType "decision" ; ds:change "Split the button." ] ;
+  ds:changeLog [ a ds:ChangeLogEntry ; ds:changeType "revision" ; ds:change "Renamed the slot." ] .
+
+# One blank node reached by TWO predicates — keyed by node alone, the second
+# edge silently vanished.
+ds:doubleLinked a ds:Probe ;
+  ds:name "double linked" ;
+  ds:changeLog [ a ds:ChangeLogEntry ; ds:changeType "decision" ] ;
+  ds:usageNote [ a ds:ChangeLogEntry ; ds:changeType "note" ] .
+
+# An RDF 1.2 directional literal — dropped, it reads as a plain @ar literal.
+ds:directional a ds:Probe ;
+  ds:name "\u0645\u0631\u062D\u0628\u0627"@ar--rtl .
+
+# The roster hub also carries ONE edge under a different predicate, so a read
+# can prove that a 22-deep neighbour does not evict its quieter sibling.
+ds:rosterHub a ds:Probe ; ds:name "roster hub" .
+ds:probe.quiet a ds:Probe ; ds:hasSubcomponent ds:rosterHub .
+${ROSTER_MEMBERS}
+`;
+
+/**
+ * An OPT-IN overlay for the lookup-addressing suite, appended to
+ * {@link BLOCK_TTL} by the tests that need it and by nothing else — the block
+ * parity, ontology and GraphQL-engine suites assert over the base graph and
+ * must keep seeing exactly two components.
+ *
+ * It models the three shapes the addressing path gets wrong: two components
+ * sharing one `ds:name` (declared zeta-first so the store's enumeration order
+ * and IRI order DISAGREE — an unordered `LIMIT 1` picks the zeta one), and a
+ * component carrying no `ds:name` at all (reachable only by IRI, the way 131 of
+ * the 144 live code standards are).
+ */
+export const AMBIGUOUS_TTL = `
+ds:apps a ds:Tier ; ds:name "apps" .
+
+ds:zeta.chip a ds:Component ;
+  ds:name "Chip" ;
+  ds:tier ds:global ;
+  ds:summary "The zeta chip — declared first, sorts last." .
+
+ds:alpha.chip a ds:Component ;
+  ds:name "Chip" ;
+  ds:tier ds:apps ;
+  ds:summary "The alpha chip — declared last, sorts first." .
+
+ds:nameless.widget a ds:Component ;
+  ds:tier ds:global ;
+  ds:summary "Carries no ds:name; addressable only by IRI." .
 `;

package/src/testing/fixtures/graph/canonical.ts

@@ -160,11 +160,97 @@ ds:prompt.configure a ds:Prompt ;
 ds:prompt.scaffold-component a ds:Prompt ;
   rdfs:label "scaffold-component" ;
   rdfs:comment "Scaffold a new component and align it to the standards." ;
-  ds:promptBody "Scaffold the {{componentName}} component in {{framework}}. Use create_component with the component path and --framework {{framework}}, then review the generated files against the react/component standards via standard_lookup." ;
+  ds:promptBody "Scaffold the {{componentName}} component in {{framework}}. Use create_component with framework {{framework}} and the component path, then review the generated files against the react/component standards via standard_lookup." ;
   ds:promptArgument [ ds:argName "componentName" ; rdfs:comment "Component name/path (e.g. Button)." ; ds:argRequired true ] ;
   ds:promptArgument [ ds:argName "framework" ; rdfs:comment "react | svelte | lit." ; ds:argRequired false ] .
 `;
 
+/** The `ds:Concept` section — long-form documentation entries the `concept`
+ * story reads. Mirrors the real design-system data shape (canonical/design-system#64):
+ * `ds:name`/`ds:summary`/`ds:tier` base, the Markdown body in `ds:content`
+ * (standard disclosure), `ds:knownEdgeCases` (detailed), and `ds:conceptType`
+ * → a named `ds:ConceptType` individual carrying its own `ds:name`. */
+const CONCEPT_TTL = `
+ds:Concept a owl:Class .
+ds:ConceptType a owl:Class .
+ds:content a owl:DatatypeProperty ; rdfs:domain ds:Concept ; rdfs:range xsd:string .
+ds:knownEdgeCases a owl:DatatypeProperty ; rdfs:domain ds:Concept ; rdfs:range xsd:string .
+ds:conceptType a owl:ObjectProperty ; rdfs:domain ds:Concept ; rdfs:range ds:ConceptType .
+
+ds:concepttype.Explanation a ds:ConceptType ;
+  ds:name "Explanation" ;
+  ds:summary "Concept documentation that deepens understanding of a topic." .
+
+ds:concepttype.How-to-guide a ds:ConceptType ;
+  ds:name "How-to guide" ;
+  ds:summary "Concept documentation that walks through solving a problem." .
+
+ds:concept.Foundations-Grid a ds:Concept ;
+  ds:name "Foundations: Grid" ;
+  ds:summary "How the grid system underpins every layout." ;
+  ds:tier ds:global ;
+  ds:conceptType ds:concepttype.Explanation ;
+  ds:content "The grid is the shared spatial contract every block lays out against." ;
+  ds:knownEdgeCases "Nested grids inherit the outer gutter unless re-declared." .
+
+ds:concept.Question-mark-vs-information-icon a ds:Concept ;
+  ds:name "Question mark vs information icon" ;
+  ds:summary "Deciding between the information icon and the question mark icon." ;
+  ds:tier ds:global ;
+  ds:conceptType ds:concepttype.How-to-guide ;
+  ds:content "The information icon offers context proactively; the question mark answers a question the user already has." ;
+  ds:knownEdgeCases "Icon interpretation depends on the user's prior conventions." .
+`;
+
+/**
+ * The implementation graph: two libraries whose `ds:implementsBlock` edges point
+ * at `BLOCK_TTL`'s own Button/Modal IRIs, so a test can prove the cross-pack
+ * join (an implementation collected from source resolving to a block declared by
+ * the design system) rather than just the shape of a row. Button is implemented
+ * TWICE, on two platforms — the case `--platform` has to separate.
+ */
+const IMPLEMENTATION_TTL = `
+ds:ImplementationLibrary a owl:Class .
+ds:ImplementationObject a owl:Class .
+ds:hasImplementation a owl:ObjectProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range ds:ImplementationObject .
+ds:implementsBlock a owl:ObjectProperty ; rdfs:domain ds:ImplementationObject ; rdfs:range ds:UIBlock .
+ds:libraryName a owl:DatatypeProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range xsd:string .
+ds:platform a owl:DatatypeProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range xsd:string .
+ds:libraryTier a owl:ObjectProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range ds:Tier .
+ds:implementationCount a owl:DatatypeProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range xsd:integer .
+ds:headLink a owl:DatatypeProperty ; rdfs:domain ds:ImplementationObject ; rdfs:range xsd:string .
+ds:versionedLink a owl:DatatypeProperty ; rdfs:domain ds:ImplementationObject ; rdfs:range xsd:string .
+
+ds:implementation.library.react-ds-global a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/react-ds-global" ;
+  ds:platform "react" ;
+  ds:libraryTier ds:global ;
+  ds:version "0.34.0" ;
+  ds:implementationCount 2 ;
+  ds:hasImplementation ds:implementation.react-ds-global.button,
+                       ds:implementation.react-ds-global.modal .
+
+ds:implementation.react-ds-global.button a ds:ImplementationObject ;
+  ds:implementsBlock ds:button ;
+  ds:headLink "https://example.test/react/Button.tsx" .
+
+ds:implementation.react-ds-global.modal a ds:ImplementationObject ;
+  ds:implementsBlock ds:modal ;
+  ds:headLink "https://example.test/react/Modal.tsx" .
+
+ds:implementation.library.svelte-ds-global a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/svelte-ds-global" ;
+  ds:platform "svelte" ;
+  ds:libraryTier ds:global ;
+  ds:version "0.34.0" ;
+  ds:implementationCount 1 ;
+  ds:hasImplementation ds:implementation.svelte-ds-global.button .
+
+ds:implementation.svelte-ds-global.button a ds:ImplementationObject ;
+  ds:implementsBlock ds:button ;
+  ds:headLink "https://example.test/svelte/Button.svelte" .
+`;
+
 /** The prefixes the canonical store is built and queried with. */
 export const CANONICAL_PREFIXES: Readonly<Record<string, string>> = {
   ...BLOCK_PREFIXES,
@@ -172,7 +258,7 @@ export const CANONICAL_PREFIXES: Readonly<Record<string, string>> = {
 };
 
 /** The full canonical Turtle: PR3's `BLOCK_TTL` verbatim, plus the sections above. */
-export const CANONICAL_TTL = `${BLOCK_TTL}\n${DS_EXTRA_TTL}\n${CS_TTL}\n${PROMPT_TTL}`;
+export const CANONICAL_TTL = `${BLOCK_TTL}\n${DS_EXTRA_TTL}\n${CS_TTL}\n${PROMPT_TTL}\n${CONCEPT_TTL}\n${IMPLEMENTATION_TTL}`;
 
 /** Default viewing config: no tier set, `normal` channel — drops the beta-only block. */
 export const CANONICAL_CONFIG = { channel: "normal" as const };

package/src/testing/fixtures/graph/defaultPack.ts

@@ -171,7 +171,7 @@ ex:beta ex:name "Beta" .
 /**
  * A malformed Turtle source — a subject/predicate with no object — drives the
  * `sources update` data-error classification path (a NAMED `CONFIG_ERROR`, not
- * an INTERNAL "please report this issue").
+ * an INTERNAL "report this issue").
  */
 export const MALFORMED_TTL = `@prefix ex: <https://ex.test/#> .
 ex:One a ex:Widget .

package/src/testing/helpers/blankCanonicalRanges.ts

@@ -0,0 +1,36 @@
+/**
+ * Blank the @canonical/* dependency ranges inside a scaffolded application's
+ * `my-app/package.json` — identically on every snapshot — before a byte
+ * comparison. The application generator resolves its range through each
+ * producer's OWN `npm view` call (no timeout, no shared cache), so an
+ * asymmetric registry outcome (one producer reaches npm and another does
+ * not, or a @canonical/* release lands between the calls) would turn
+ * `^0.34.0` vs `^0.33.0` across all 11 ranges into a red that says nothing
+ * about the code under test. The networked cases prove the TEMPLATE surface;
+ * range truth belongs to the offline cells, where the outcome is forced
+ * (`capabilities/create/shippedCreate.subprocess.test.ts`).
+ *
+ * The regex preserves the dependency KEY (`$1`), so a key-set or
+ * non-@canonical divergence still fails; only the range value collapses.
+ * Deliberately import-free — a pure string transform no module-graph guard
+ * can ever see.
+ *
+ * @param tree - A tree snapshot (relative path → contents).
+ * @param manifestPath - The scaffolded manifest's path within the tree.
+ * @returns A NEW map with the manifest's @canonical/* ranges blanked; the
+ *   input is untouched. A tree without the manifest comes back copied as-is.
+ */
+export function blankCanonicalRanges(
+  tree: ReadonlyMap<string, string>,
+  manifestPath = "my-app/package.json",
+): Map<string, string> {
+  const out = new Map(tree);
+  const manifest = out.get(manifestPath);
+  if (manifest !== undefined) {
+    out.set(
+      manifestPath,
+      manifest.replaceAll(/("@canonical\/[^"]+": )"[^"]+"/g, '$1"<range>"'),
+    );
+  }
+  return out;
+}