@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/capabilities/sources/status.render.ts

@@ -2,14 +2,20 @@
  * Formatters for `pragma sources status` — plain, llm, json.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 import type { SourcesStatusData } from "./types.js";
 
-const STALENESS_MARK: Record<string, string> = {
-  "up-to-date": "ok",
-  "config-drift": "config drift",
-  uncached: "not built",
+/**
+ * The headline for each boot decision. The `embedded` case names the update
+ * explicitly: the distribution's snapshot answers reads, but it is a snapshot,
+ * so reporting it as "up to date" would be a lie.
+ */
+const STORE_HEADLINE: Record<SourcesStatusData["store"], string> = {
+  built: "ready",
+  embedded: `embedded snapshot (run \`${BIN_NAME} sources update\` to build from the configured packs)`,
+  unavailable: `not built (run \`${BIN_NAME} sources update\`)`,
 };
 
 /**
@@ -18,22 +24,19 @@ const STALENESS_MARK: Record<string, string> = {
  * @param data - The resolved sources-status payload.
  * @param style - TTY styling; defaults to the process style. On a color-capable
  *   terminal the `Sources:` heading is bold, source names align into a column,
- *   and each staleness marker is tinted (green up-to-date, else yellow); off a
- *   TTY the styler is inert, so the output is byte-identical to the plain form.
+ *   and each configured ref is dimmed; off a TTY the styler is inert, so the
+ *   output is byte-identical to the plain form.
  * @returns The formatted status block.
  */
 export function renderSourcesStatusPlain(
   data: SourcesStatusData,
   style: RenderStyle = defaultStyle(),
 ): string {
-  const lines = [
-    data.lockPresent
-      ? `Store: ${data.cached ? "ready" : "locked but not cached"}`
-      : "Store: no lock (run `pragma sources update`)",
-  ];
-  if (data.cached) {
+  const lines = [`Store: ${STORE_HEADLINE[data.store]}`];
+  if (data.contentHash !== null) {
     lines.push(
-      `  pack: ${data.contentHash?.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
+      `  pack: ${data.contentHash.slice(0, 12)} — ${data.entityCount ?? "?"} entities, built ${data.builtAt ?? "?"}`,
+      `  from: ${data.sourceRef ?? "?"}`,
     );
   }
   lines.push("", style.enabled ? style.bold("Sources:") : "Sources:");
@@ -44,17 +47,10 @@ export function renderSourcesStatusPlain(
     ? Math.max(0, ...data.sources.map((source) => source.name.length))
     : 0;
   for (const source of data.sources) {
-    const mark = STALENESS_MARK[source.staleness] ?? source.staleness;
-    const resolved = source.resolved
-      ? ` @ ${source.resolved.slice(0, 12)}`
-      : "";
-    if (!style.enabled) {
-      lines.push(`  ${source.name} [${mark}]${resolved}`);
-      continue;
-    }
-    const tint = source.staleness === "up-to-date" ? style.green : style.yellow;
     lines.push(
-      `  ${source.name.padEnd(nameWidth)}  ${tint(`[${mark}]`)}${style.dim(resolved)}`,
+      style.enabled
+        ? `  ${source.name.padEnd(nameWidth)}  ${style.dim(source.ref)}`
+        : `  ${source.name}  ${source.ref}`,
     );
   }
   return lines.join("\n");
@@ -66,13 +62,12 @@ export const statusFormatters: Formatters<SourcesStatusData> = {
   },
 
   llm(data) {
-    const lines = [
-      `# sources`,
-      `- Store: ${data.lockPresent ? (data.cached ? "ready" : "locked, not cached") : "no lock"}`,
-      ...(data.cached ? [`- Entities: ${data.entityCount ?? "?"}`] : []),
-    ];
+    const lines = [`# sources`, `- Store: ${data.store}`];
+    if (data.sourceRef !== null) lines.push(`- From: ${data.sourceRef}`);
+    if (data.entityCount !== null)
+      lines.push(`- Entities: ${data.entityCount}`);
     for (const source of data.sources) {
-      lines.push(`- ${source.name}: ${source.staleness}`);
+      lines.push(`- ${source.name}: ${source.ref}`);
     }
     return lines.join("\n");
   },

package/src/capabilities/sources/status.verb.ts

@@ -2,12 +2,13 @@
  * The `sources status` verb — a storeless read.
  *
  * `needsStore: false` is load-bearing: status must report even a cold or
- * unbuilt store (staleness `uncached`), so it must NOT boot the store — booting
- * a cold store would throw STORE_UNAVAILABLE before status could say so. Its
- * `run` is a lazy thunk (the collector is dynamic-imported), keeping the config
- * reader off the fast path, exactly like `info`.
+ * unbuilt store (`store: "unavailable"`), so it must NOT boot the store —
+ * booting a cold store would throw STORE_UNAVAILABLE before status could say
+ * so. Its `run` is a lazy thunk (the collector is dynamic-imported), keeping
+ * the config reader off the fast path, exactly like `info`.
  */
 
+import { BIN_NAME } from "../../constants.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { statusFormatters } from "./status.render.js";
 import type { SourcesStatusData } from "./types.js";
@@ -18,13 +19,19 @@ export const statusVerb: VerbSpec<
   SourcesStatusData
 > = {
   path: ["sources", "status"],
-  summary: "Report the local store's readiness and per-source staleness.",
-  doc: "Storeless — reads the lock, config, and pack cache without booting the store, so it works even when the store is cold.",
+  summary: "Report which pack answers reads, and the packs it was built from.",
+  doc: "Storeless — reads config and the pack cache without booting the store, so it works even when the store is cold. Reports whether reads are answered by a locally built pack, by the embedded snapshot, or not at all.",
   params: [],
   output: { formatters: statusFormatters },
   examples: [
-    { cmd: "pragma sources status", note: "human-readable readiness summary" },
-    { cmd: "pragma sources status --format json", note: "the full envelope" },
+    {
+      cmd: `${BIN_NAME} sources status`,
+      note: "human-readable readiness summary",
+    },
+    {
+      cmd: `${BIN_NAME} sources status --format json`,
+      note: "the full envelope",
+    },
   ],
   capability: {
     needsStore: false,

package/src/capabilities/sources/types.ts

@@ -1,37 +1,29 @@
 /**
  * Data shapes for the `sources` noun — `status` (storeless read) and `update`
- * (the Task that resolves, builds, and locks the store).
+ * (the Task that resolves, builds, and points the project at a pack).
  */
 
-/** How a configured source stands relative to the lock and the pack cache. */
-export type SourceStaleness = "up-to-date" | "config-drift" | "uncached";
-
-/** One configured source's status. */
-export interface SourceStatusEntry {
-  /** Package name. */
-  readonly name: string;
-  /** The config `packages` source ref (verbatim). */
-  readonly ref: string;
-  /** The lock's resolved revision, or null when not locked. */
-  readonly resolved: string | null;
-  /** Whether the config ref matches the lock and the pack is cached. */
-  readonly staleness: SourceStaleness;
-}
-
 /** The `sources status` payload — assembled without booting the store. */
 export interface SourcesStatusData {
   readonly cwd: string;
-  /** Whether a `pragma.lock.json` is present. */
-  readonly lockPresent: boolean;
-  /** The locked combined-pack content hash, or null. */
+  /**
+   * Which pack answers reads, straight from the boot decision: the project's
+   * own `built` pack, the distribution's `embedded` snapshot, or none at all.
+   */
+  readonly store: "embedded" | "built" | "unavailable";
+  /** The answering pack's content hash, or null when there is none. */
   readonly contentHash: string | null;
-  /** Whether the locked pack is present in the cache. */
-  readonly cached: boolean;
-  /** When the cached pack was built (manifest `createdAt`), or null. */
+  /** The answering pack's provenance label (manifest `sourceRef`), or null. */
+  readonly sourceRef: string | null;
+  /** When the answering pack was built (manifest `createdAt`), or null. */
   readonly builtAt: string | null;
-  /** Total indexed entity count from the cached pack, or null. */
+  /** Total indexed entity count from the answering pack, or null. */
   readonly entityCount: number | null;
-  readonly sources: readonly SourceStatusEntry[];
+  /** The configured pack declarations, as written in the config. */
+  readonly sources: readonly {
+    readonly name: string;
+    readonly ref: string;
+  }[];
 }
 
 /** One resolved source in the `sources update` result. */
@@ -39,6 +31,8 @@ export interface UpdatedSource {
   readonly name: string;
   readonly resolved: string;
   readonly sourceCount: number;
+  /** How many `stories/*.json` files this package contributed to the pack. */
+  readonly storyCount: number;
 }
 
 /** The `sources update` result payload. */
@@ -46,6 +40,5 @@ export interface SourcesUpdateData {
   readonly contentHash: string;
   /** Whether the pack was reused from cache rather than rebuilt. */
   readonly reused: boolean;
-  readonly lockPath: string;
   readonly packs: readonly UpdatedSource[];
 }

package/src/capabilities/sources/update.render.ts

@@ -11,11 +11,18 @@ export const updateFormatters: Formatters<SourcesUpdateData> = {
       data.reused
         ? `Store up to date (pack ${data.contentHash.slice(0, 12)}).`
         : `Built pack ${data.contentHash.slice(0, 12)}.`,
-      `Wrote ${data.lockPath}.`,
     ];
     for (const pack of data.packs) {
+      // FILES, not usable stories: `sources update` carries them verbatim and
+      // never validates them (zod would have to run per record, in the build).
+      // `doctor` is where "2 stories ignored" comes from — saying "stories"
+      // here would put a green count next to a broken file.
+      const stories =
+        pack.storyCount > 0
+          ? `, ${pack.storyCount} story file${pack.storyCount === 1 ? "" : "s"}`
+          : "";
       lines.push(
-        `  ${pack.name} @ ${pack.resolved.slice(0, 12)} (${pack.sourceCount} source${pack.sourceCount === 1 ? "" : "s"})`,
+        `  ${pack.name} @ ${pack.resolved.slice(0, 12)} (${pack.sourceCount} source${pack.sourceCount === 1 ? "" : "s"}${stories})`,
       );
     }
     return lines.join("\n");

package/src/capabilities/sources/update.verb.ts

@@ -1,35 +1,32 @@
 /**
- * The `sources update` verb — resolve, build, and lock the store.
+ * The `sources update` verb — resolve the configured packs, build the store,
+ * and point the project at it.
  *
  * A mutation (`mutates: true`) that needs the network (`needsNetwork: true`)
  * but NOT the pre-booted store (`needsStore: false`): update is what *creates*
  * the store, so the dispatcher must not try to boot it first (a cold boot would
  * throw STORE_UNAVAILABLE). `run` returns a `Promise<Task<R>>` — the union's
  * third arm — which the dispatcher awaits: for a real execution it resolves and
- * builds before handing back the lock-writing Task; for a preview
+ * builds before handing back the pointer-writing Task; for a preview
  * (`runtime.mutation.preview`) it stays network-free and hands back a
- * plan-only Task. `--frozen` re-resolves to the lock's pinned revisions.
+ * plan-only Task.
  */
 
 import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import type { SourcesUpdateData } from "./types.js";
 import { updateFormatters } from "./update.render.js";
 
 /** The `sources update` verb spec. */
 export const updateVerb: VerbSpec<
-  { frozen?: boolean; skipInvalid?: boolean },
+  { skipInvalid?: boolean },
   SourcesUpdateData
 > = {
   path: ["sources", "update"],
-  summary: "Resolve configured packages, build the local store, and lock it.",
-  doc: "Resolves each configured package (git/file/npm), builds one content-addressed pack, and writes pragma.lock.json. Networkless boots then load from the lock.",
+  summary: "Resolve configured packs and build the local store from them.",
+  doc: "Resolves each configured pack (git/file/npm) and builds one content-addressed pack, which every later boot reads with no network access. Pin a revision by putting a commit SHA in the pack's source ref.",
   params: [
-    {
-      kind: "boolean",
-      name: "frozen",
-      doc: "Re-resolve to the lock's pinned revisions exactly; never advance.",
-    },
     {
       kind: "boolean",
       name: "skipInvalid",
@@ -38,13 +35,9 @@ export const updateVerb: VerbSpec<
   ],
   output: { formatters: updateFormatters },
   examples: [
-    { cmd: "pragma sources update", note: "resolve, build, and lock" },
-    {
-      cmd: "pragma sources update --frozen",
-      note: "reproduce the locked state",
-    },
+    { cmd: `${BIN_NAME} sources update`, note: "resolve and build" },
     {
-      cmd: "pragma sources update --skip-invalid",
+      cmd: `${BIN_NAME} sources update --skip-invalid`,
       note: "build from the parseable sources, warning about any dropped",
     },
   ],
@@ -59,7 +52,7 @@ export const updateVerb: VerbSpec<
   },
   // `run` really returns `Promise<Task<R>>`: `buildUpdateTask` awaits config
   // (and, on a real execution, resolves + builds) before handing back the
-  // lock-writing Task — or, when `runtime.mutation.preview` is set, a
+  // pointer-writing Task — or, when `runtime.mutation.preview` is set, a
   // network-free plan Task. The dispatcher and MCP handler both `await` this
   // promise into a `Task`. The `VerbSpec.run` union is deliberately two-armed
   // (`Promise<R> | Task<R>`) — a third `Promise<Task<R>>` arm would poison async
@@ -67,10 +60,6 @@ export const updateVerb: VerbSpec<
   // `Task<R>` arm by this single, honest cast.
   run: (params, runtime) =>
     import("./runUpdate.js").then((module) =>
-      module.buildUpdateTask(
-        runtime,
-        params.frozen === true,
-        params.skipInvalid === true,
-      ),
+      module.buildUpdateTask(runtime, params.skipInvalid === true),
     ) as unknown as Task<SourcesUpdateData>,
 };

package/src/capabilities/surface.test.ts

@@ -1,11 +1,13 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
+import { MCP_SERVER_NAME, VERSION } from "../constants.js";
 import { emitSurface } from "../kernel/spec/emitSurface.js";
 import {
   assertConforms,
   type Covenant,
 } from "../kernel/spec/surfaceConformance.js";
+import { projectMcp } from "../testing/helpers/projectMcp.js";
 import { capabilities } from "./index.js";
 
 /** The committed covenant, read from disk exactly as a consumer would. */
@@ -42,15 +44,15 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
     expect(emitted.nouns.__complete).toBeUndefined();
   });
 
-  it("emits the read nouns/verbs the packs add (block list hand-written, sample only where declared)", () => {
+  it("emits the read nouns/verbs the packs add (sample only where declared)", () => {
     expect(emitted.nouns.standard?.verbs.map((v) => v.v)).toEqual([
       "list",
       "categories",
       "lookup",
       "sample",
     ]);
-    // PR7 completes the surface: tier gains a bespoke single-name lookup;
-    // block/modifier/token gain no-argument samples (fixedCount).
+    // PR7 completed the surface; block/modifier/token carry no-argument
+    // samples (fixedCount), tier declares no sample.
     expect(emitted.nouns.tier?.verbs.map((v) => v.v)).toEqual([
       "list",
       "lookup",
@@ -60,16 +62,18 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       "lookup",
       "sample",
     ]);
+    // `token` is purely declarative since L-OPEN-9 removed `add-config`: the
+    // three read verbs its story compiles, and no mutation.
     expect(emitted.nouns.token?.verbs.map((v) => v.v)).toEqual([
       "list",
       "lookup",
       "sample",
-      "add-config",
     ]);
+    // block list is the story's compiled, unfiltered list (L-OPEN-9): no
+    // flags — the `--all-tiers` escape died with the hand-written filtering.
     expect(emitted.nouns.block?.verbs).toEqual([
       {
         v: "list",
-        flags: ["--all-tiers"],
         needsStore: true,
         mcp: "block_list",
       },
@@ -81,11 +85,11 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       },
       { v: "sample", needsStore: true, mcp: "block_sample" },
     ]);
-    // The bespoke tier lookup emits the SINGLE-name positional the covenant
-    // freezes (a pack lookup would emit the variadic `<name...>`).
+    // The tier lookup is the story's compiled lookup (L-OPEN-9), so it emits
+    // the variadic `<name...>` positional every pack lookup emits.
     expect(emitted.nouns.tier?.verbs).toContainEqual({
       v: "lookup",
-      args: ["<name>"],
+      args: ["<name...>"],
       needsStore: true,
       mcp: "tier_lookup",
     });
@@ -209,14 +213,14 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
   // The CLOSING direction: assertConforms already proves emitted ⊆ covenant;
   // this proves covenant ⊆ emitted, so together the tool sets are EQUAL — the
   // surface-complete milestone. After PR7, every covenant tool is realized.
-  it("emits every covenant tool (all 38) — set equality with the covenant", () => {
+  it("emits every covenant tool (all 37) — set equality with the covenant", () => {
     const emittedTools = new Set(emitted.mcpSurface.tools);
     const missing = golden.mcpSurface.tools.filter((t) => !emittedTools.has(t));
     expect(missing).toEqual([]);
     expect([...emitted.mcpSurface.tools].sort()).toEqual(
       [...golden.mcpSurface.tools].sort(),
     );
-    expect(emitted.mcpSurface.tools).toHaveLength(38);
+    expect(emitted.mcpSurface.tools).toHaveLength(37);
   });
 
   // The covenant edit: the non-tool MCP surface is frozen too.
@@ -230,4 +234,23 @@ describe("surface COMPLETE — emitted == covenant (PROTECTED)", () => {
       golden.mcpSurface.instructions,
     );
   });
+
+  // The L-PR6 covenant edit (PRA-107 ruling): the wire-identity RULE. The
+  // covenant states serverInfo as placeholders — a PROJECTION, deliberately not
+  // live values, so a release does not churn the covenant — and the live
+  // handshake is asserted to follow it: the server introduces itself with the
+  // distribution's declared name and the package version. The fork half of the
+  // same rule (a renamed distribution introduces itself under ITS name) is
+  // pinned in identity.test.ts, where the conf is mocked.
+  it("states the serverInfo projection rule and serves it on the wire", async () => {
+    expect(golden.mcpSurface.serverInfo).toEqual({
+      name: "<the declared distribution name>",
+      version: "<the package version>",
+    });
+
+    const mcp = await projectMcp([]);
+    const wire = mcp.serverInfo();
+    await mcp.cleanup();
+    expect(wire).toEqual({ name: MCP_SERVER_NAME, version: VERSION });
+  });
 });

package/src/capabilities/tier.parity.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Tier-noun semantic parity (PROTECTED) — the `tier` story `pragma.conf.ts`
+ * declares, over a tier/block fixture graph (the standard-noun pattern).
+ *
+ * The hand-written `tier lookup` is gone (L-OPEN-9): both verbs compile from
+ * the declared story, so parity is asserted directly against the graph — every
+ * tier is reachable through list/lookup with the same names, addressable by
+ * name AND by prefixed IRI (the candidates completion now offers, D9-A), the
+ * `blocks` expand resolves the INVERSE path `^ds:tier` (the members scoped
+ * directly to the tier), a memberless tier still resolves, and a miss carries
+ * "did you mean?" suggestions like every declared lookup.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { compilePack } from "../kernel/packs/compile.js";
+import type { LookupOutput } from "../kernel/packs/resolveEntity.js";
+import type { PackRow } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { declaredStories } from "./distribution.js";
+
+const tierPack = declaredStories.get("tier");
+if (!tierPack) {
+  throw new Error('pragma.conf.ts declares no story for "tier"');
+}
+
+const DS = "https://ds.canonical.com/";
+const PREFIXES = {
+  ds: DS,
+  owl: "http://www.w3.org/2002/07/owl#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  xsd: "http://www.w3.org/2001/XMLSchema#",
+};
+
+const TTL = `
+@prefix ds: <${DS}> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ds:Tier a owl:Class .
+ds:Component a owl:Class .
+ds:name a owl:DatatypeProperty ; rdfs:range xsd:string .
+ds:tier a owl:ObjectProperty ; rdfs:range ds:Tier .
+
+ds:global a ds:Tier ; ds:name "global" .
+ds:apps a ds:Tier ; ds:name "apps" .
+ds:apps_lxd a ds:Tier ; ds:name "apps/lxd" .
+
+ds:button a ds:Component ; ds:name "Button" ; ds:tier ds:global .
+ds:modal a ds:Component ; ds:name "Modal" ; ds:tier ds:global .
+ds:lxdPanel a ds:Component ; ds:name "LXD Panel" ; ds:tier ds:apps_lxd .
+`;
+
+const verbs = () => compilePack(tierPack, "pragma.conf.ts", DEFAULT_PREFIX_MAP);
+const verb = (label: string) =>
+  verbs().find((v) => verbKey(v.path) === `tier ${label}`) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+afterAll(async () => {
+  (await rt.store.get()).store.dispose();
+});
+
+async function lookup(name: string): Promise<Record<string, unknown>> {
+  const out = (await verb("lookup").run({ name: [name] }, rt)) as LookupOutput;
+  expect(out.errors).toEqual([]);
+  return out.results.at(0) as Record<string, unknown>;
+}
+
+/** The `blocks` expand's child names, sorted (the sub-SELECT is unordered). */
+function blockNames(entity: Record<string, unknown>): string[] {
+  return (entity.blocks as { name: string }[]).map((b) => b.name).sort();
+}
+
+describe("tier list parity", () => {
+  it("lists every tier, name-ordered, with the uniform row shape", async () => {
+    const rows = (await verb("list").run({}, rt)) as PackRow[];
+    expect(rows.map((r) => r.name)).toEqual(["apps", "apps/lxd", "global"]);
+    for (const row of rows) {
+      expect(row.uri).toBeTruthy();
+    }
+  });
+});
+
+describe("tier lookup parity — the declared story's compiled lookup", () => {
+  it("resolves a tier by name and expands the blocks scoped directly to it", async () => {
+    const tier = await lookup("apps/lxd");
+    expect(tier.uri).toBe(`${DS}apps_lxd`);
+    expect(tier.name).toBe("apps/lxd");
+    // The `blocks` expand walks the INVERSE `^ds:tier` path (contract:
+    // `PackExpand.relation` admits property paths), so only the DIRECT
+    // members appear — no chain inheritance.
+    expect(blockNames(tier)).toEqual(["LXD Panel"]);
+    const global = await lookup("global");
+    expect(blockNames(global)).toEqual(["Button", "Modal"]);
+  });
+
+  it("a memberless tier still resolves, with an empty blocks expand", async () => {
+    const apps = await lookup("apps");
+    expect(apps.name).toBe("apps");
+    expect(apps.blocks).toEqual([]);
+    // The empty expand renders as an OMITTED section (the generic renderers'
+    // behavior for every declared noun), not a placeholder line.
+    const out = (await verb("lookup").run({ name: ["apps"] }, rt)) as never;
+    expect(verb("lookup").output.formatters.llm(out)).not.toContain("Blocks");
+  });
+
+  it("resolves the same tier by prefixed IRI — the candidates completion offers (D9-A)", async () => {
+    // Completion for the declared lookup serves index entity NAMES (prefixed
+    // IRIs); a candidate is only honest if the lookup resolves it.
+    const byIri = await lookup("ds:apps_lxd");
+    expect(byIri.name).toBe("apps/lxd");
+    expect(byIri.uri).toBe(`${DS}apps_lxd`);
+  });
+
+  it("resolves a variadic batch in one call", async () => {
+    const out = (await verb("lookup").run(
+      { name: ["global", "apps"] },
+      rt,
+    )) as LookupOutput;
+    expect(out.results.map((r) => r.name)).toEqual(["global", "apps"]);
+  });
+
+  it("a miss fails ENTITY_NOT_FOUND with a near-miss suggestion (B6 parity kept)", async () => {
+    // The bespoke lookup earned "did you mean?" in B6; the declared path keeps
+    // it — suggestions come from the same name list every declared lookup uses.
+    let caught: unknown;
+    try {
+      await verb("lookup").run({ name: ["apps/lxdd"] }, rt);
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+    expect((caught as { suggestions: string[] }).suggestions).toContain(
+      "apps/lxd",
+    );
+  });
+});

package/src/capabilities/upgrade/upgrade.verb.ts

@@ -14,6 +14,7 @@
  */
 
 import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
 import type { UpgradeData } from "./types.js";
@@ -21,13 +22,16 @@ import { upgradeFormatters } from "./upgrade.render.js";
 
 const upgradeVerb: VerbSpec<Record<string, unknown>, UpgradeData> = {
   path: ["upgrade"],
-  summary: "Upgrade the pragma CLI to the latest version.",
+  summary: `Upgrade the ${BIN_NAME} CLI to the latest version.`,
   doc: "Checks the registry for the active channel's latest release and runs your package manager's global-update command. Preview the update before applying it.",
   params: [],
   output: { formatters: upgradeFormatters },
   examples: [
-    { cmd: "pragma upgrade" },
-    { cmd: "pragma upgrade --dry-run", note: "show the delta and the command" },
+    { cmd: `${BIN_NAME} upgrade` },
+    {
+      cmd: `${BIN_NAME} upgrade --dry-run`,
+      note: "show the delta and the command",
+    },
   ],
   capability: {
     needsStore: false,

package/src/constants.test.ts

@@ -3,6 +3,7 @@ import {
   BIN_NAME,
   DEFAULT_DETAIL_LEVEL,
   DETAIL_LEVELS,
+  ISSUES_URL,
   MCP_SERVER_NAME,
   OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
@@ -11,23 +12,24 @@ import {
 } from "./constants.js";
 
 describe("constants", () => {
-  it("names the v2 bin and the MCP server pragma", () => {
+  it("projects the shipped distribution's identity", () => {
+    // Every value here is read from `pragma.conf.ts`, so this pins what THIS
+    // distribution ships. That the projection is real — a fork changing the
+    // config changes the CLI — is proven by `src/identity.test.ts`.
     expect(BIN_NAME).toBe("pragma");
     expect(MCP_SERVER_NAME).toBe("pragma");
+    expect(PROGRAM_DESCRIPTION).toBe("Explore the design system");
+    expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
+    expect(ISSUES_URL).toBe("https://github.com/canonical/pragma/issues");
   });
 
   it("reads a semver version from package.json", () => {
     expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
   });
 
-  it("keeps the recovery prefix on the stable command name (D5)", () => {
-    expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
-  });
-
   it("exposes the stable output formats and detail levels", () => {
     expect(OUTPUT_FORMATS).toEqual(["plain", "llm", "json"]);
     expect(DETAIL_LEVELS).toEqual(["summary", "standard", "detailed"]);
     expect(DETAIL_LEVELS).toContain(DEFAULT_DETAIL_LEVEL);
-    expect(PROGRAM_DESCRIPTION.length).toBeGreaterThan(0);
   });
 });