@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/kernel/spec/emitReference.ts

@@ -15,6 +15,8 @@
  * NOT imported — this is a kernel-layer emitter).
  */
 
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
+import type { RawConfig } from "../config/types.js";
 import { ERROR_CODES } from "../error/constants.js";
 import {
   FIXED_SURFACE,
@@ -86,12 +88,12 @@ function compareDocVerbs(a: VerbSpec, b: VerbSpec): number {
   return labelA < labelB ? -1 : 1;
 }
 
-/** The full CLI invocation head for a verb (`pragma <noun>` or `pragma <noun> <verb>`). */
+/** The full CLI invocation head for a verb (`<bin> <noun>` or `<bin> <noun> <verb>`). */
 function formatInvocation(verb: VerbSpec): string {
   const sub = verb.path[1];
   return sub === undefined
-    ? `pragma ${verb.path[0]}`
-    : `pragma ${verb.path[0]} ${sub}`;
+    ? `${BIN_NAME} ${verb.path[0]}`
+    : `${BIN_NAME} ${verb.path[0]} ${sub}`;
 }
 
 /** Format a positional param as its usage token (`<name>`/`[name]`, `...` when variadic). */
@@ -211,7 +213,7 @@ function formatExamples(examples: readonly Example[] | undefined): string {
 function formatVerbAttributes(verb: VerbSpec): string {
   const bullets = [
     verb.capability.needsStore
-      ? "- Store: reads the local store (`pragma sources update` builds it)."
+      ? `- Store: reads the local store (\`${BIN_NAME} sources update\` builds it).`
       : "- Store: storeless.",
   ];
   if (verb.capability.mutates) {
@@ -251,7 +253,7 @@ function renderCommandSection(verb: VerbSpec): string {
 function renderCommandsPage(verbs: readonly VerbSpec[]): string {
   const blocks = [
     "# CLI command reference",
-    "Every `pragma` command, grouped by noun. Generated from the live capability grammar — do not edit by hand.",
+    `Every \`${BIN_NAME}\` command, grouped by noun. Generated from the live capability grammar — do not edit by hand.`,
     "Global flags apply to every command: `--format <plain|llm|json>` (auto-detected — the llm/condensed-Markdown form turns on when output is piped), `--verbose`, and `--detail <summary|standard|detailed>`.",
   ];
   let currentNoun = "";
@@ -377,12 +379,12 @@ function renderNonToolSurface(modules: readonly CapabilityModule[]): string {
   const bullets: string[] = [];
   if (resources.length > 0) {
     bullets.push(
-      `- **Resources**: ${resources.map((r) => `\`${r}\``).join(", ")} — entity reads addressed by URI (listing and autocomplete are storeless over the pack index).`,
+      `- **Resources**: ${resources.map((r) => `\`${r}\``).join(", ")} — entity reads addressed by URI (listing and autocomplete are storeless over the pack index). The template — its scheme and the \`_meta\` taxonomy keys its entries carry — is frozen protocol identity, served unchanged by every distribution: clients persist resource URIs, so the scheme never follows a fork's name.`,
     );
   }
   if (prompts) {
     bullets.push(
-      "- **Prompts**: the design system's workflow templates are offered natively over `prompts/list` and `prompts/get`, and as the `prompt_list` / `prompt_lookup` content tools.",
+      "- **Prompts**: the workflow prompt templates the active graph declares are offered natively over `prompts/list` and `prompts/get`, and as the `prompt_list` / `prompt_lookup` content tools. A graph declaring none leaves both views empty.",
     );
   }
   bullets.push(
@@ -399,7 +401,7 @@ function renderToolsPage(
   const tools = verbs.filter((verb) => verb.capability.mcp.expose);
   const blocks = [
     "# MCP tool reference",
-    "Every tool the pragma MCP server exposes, plus its non-tool surface. Generated from the live capability grammar — do not edit by hand.",
+    `Every tool the ${BIN_NAME} MCP server exposes, plus its non-tool surface. Generated from the live capability grammar — do not edit by hand. The server's \`serverInfo\` is a projection, not a constant: it introduces itself on the wire under the distribution's declared name at the package version, so a client should read \`serverInfo\` rather than assume a name.`,
     "Mutating tools are plan-first: called without `confirm: true` they return the plan they WOULD apply; called with `confirm: true` they execute. A mutating tool also accepts an optional absolute `cwd`.",
   ];
   for (const verb of tools) {
@@ -442,6 +444,135 @@ function renderErrorsPage(): string {
   ]);
 }
 
+/** One documented config field: the type label a user sees, and the prose. */
+interface ConfigFieldDoc {
+  /** The type as a reader needs it, e.g. `string (optional)`. */
+  readonly type: string;
+  /** What the field does, and anything true about it a reader would not guess. */
+  readonly notes: string;
+}
+
+/**
+ * Every field a config layer may declare. Typed as an exhaustive `Record` over
+ * `keyof RawConfig`, so a field added to the type without a row here — or a row
+ * left behind by a field that was removed — is a COMPILE error, exactly as
+ * {@link ERROR_CODE_DESCRIPTIONS} works for the error kernel. Colocated
+ * (single-use) rather than in a module of its own: only `renderConfigPage`
+ * reads it, and a third artifact for two consumers to keep in step is what this
+ * discipline exists to avoid.
+ *
+ * The `type` column is authored prose; the page says so. Its OPTIONALITY is
+ * checked against the zod validator by `kernel/config/schema.test.ts`.
+ */
+const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
+  name: {
+    type: "string (optional)",
+    notes:
+      "Distribution-only — see below. The binary's own name, read from the distribution config at module load.",
+  },
+  help: {
+    type: "string (optional)",
+    notes:
+      "Distribution-only — see below. The one-line blurb on the front door and in the MCP handshake.",
+  },
+  colophon: {
+    type: "object (optional)",
+    notes:
+      "Distribution-only — see below. The toolchain's own story, rendered first by the `colophon` verb and titled with the distribution's name: `{ markdown, summary? }`, both Markdown bodies with no leading H1 (`summary` is the condensed `--format llm` form). Declared content, not code — a fork edits it to tell its own story.",
+  },
+  issuesUrl: {
+    type: "URL string (optional)",
+    notes:
+      "Distribution-only — see below. Where the first-run note asks users to report problems.",
+  },
+  tier: {
+    type: "string (optional)",
+    notes:
+      "Accepted by the validator and SCOPES NOTHING: since the block list became declared content, no read filters by tier — the value is only reported by `config show` and `info`. Set it with `config set tier <path>`; `none`, `default` or `-` clear it.",
+  },
+  channel: {
+    type: "`normal` | `experimental` | `prerelease` (optional)",
+    notes:
+      "Selects the npm dist-tag `upgrade` and `info` check the registry with. It no longer scopes graph reads — no read filters by channel. Defaults to `normal`. Set it with `config set channel <name>`.",
+  },
+  detail: {
+    type: "`summary` | `standard` | `detailed` (optional)",
+    notes:
+      "Default progressive-disclosure level. A closed enum, like `channel`: any other value fails at load with a `CONFIG_ERROR` naming the file and the three levels. Set it with `config set detail <level>`.",
+  },
+  packs: {
+    type: "array (optional)",
+    notes:
+      "Semantic pack sources built by `sources update`. Each entry is a bare npm name or `{ name, source, stories? }`; `stories` are read stories the pack supplies, in the pack grammar.",
+  },
+  stories: {
+    type: "array (optional)",
+    notes:
+      "Read stories not attached to any pack, in the pack grammar. Compiled at dispatch, and they win over the same noun declared under `packs[].stories`.",
+  },
+  prefixes: {
+    type: "record (optional)",
+    notes:
+      "Namespace prefixes the pack is built with — they win every harvest, so this decides which IRI a prefix binds in the store and the index. Every surface uses the compiled-in display/expansion map to compact and expand prefixed names; only the DISTRIBUTION layer seeds it, because it is also read on the storeless fast path, before any config layer exists.",
+  },
+  completion: {
+    type: "object (optional)",
+    notes:
+      "Completion policy read when `setup completions` emits a script: `minChars` and a per-noun `families` opt-out. It is the one field `config show` carries with NO origin at all.",
+  },
+};
+
+/**
+ * The fields `config show` prints with the layer that supplied them, in the
+ * order it prints them. NOT every field: `prefixes` and `completion` reach only
+ * the JSON payload, `stories` reaches only its `origins` key, and the four
+ * distribution-only fields reach neither. The page said the opposite — that
+ * every field but `completion` was reported — which is the claim this whole
+ * reference exists to make true rather than plausible.
+ *
+ * A literal, because the kernel emitter may not import a capability renderer.
+ * `capabilities/config/show.render.test.ts` derives the same list from the real
+ * formatter and fails if this page and that renderer disagree.
+ */
+const REPORTED_FIELDS = ["tier", "channel", "detail", "packs"];
+
+/** Render the layered-configuration reference: the layers, then the fields. */
+function renderConfigPage(): string {
+  const rows = ["| Field | Type | Notes |", "| --- | --- | --- |"];
+  for (const [field, doc] of Object.entries(CONFIG_FIELD_DOCS)) {
+    rows.push(
+      `| \`${field}\` | ${escapeCell(doc.type)} | ${escapeCell(doc.notes)} |`,
+    );
+  }
+  return assemblePage([
+    "# Configuration reference",
+    `Every field a \`${BIN_NAME}\` config layer may declare. Generated from the config type — do not edit by hand. See [config-model.md](../config-model.md) for the authoring guide.`,
+    "## Layers",
+    "From lowest to highest precedence:",
+    [
+      `1. **Built-in defaults** — the distribution config compiled into the binary.`,
+      `2. **Global config** — \`$XDG_CONFIG_HOME/${BIN_NAME}/config.json\`, written by \`${BIN_NAME} config set\`.`,
+      `3. **Project config** — the nearest \`${PROJECT_CONFIG_FILENAME}\` (or \`${BIN_NAME}.config.js\`, the compiled-binary fallback), walking up from the working directory.`,
+    ].join("\n"),
+    "A higher layer REPLACES a lower one field by field. No field is deep-merged — not `packs`, not `prefixes`, not `completion`. A project declaring one prefix therefore replaces the distribution's whole prefix map, including the namespaces its own packs are built with; declare every prefix you need, not only the new one.",
+    "## Fields",
+    "The `Type` column is prose; the field set and each field's optionality are checked against the validator.",
+    rows.join("\n"),
+    "## Distribution-only fields",
+    `\`name\`, \`help\` and \`issuesUrl\` are read from the distribution config when the program loads, because the surfaces that need them — \`--help\`, shell completion, the MCP handshake, the first-run note — run before or without the config layer. \`colophon\` is read from the same file at render time: the \`colophon\` verb narrates whatever the distribution declares there. The validator ACCEPTS all four in a global or project layer, and they have **no effect there and are not reported** by \`config show\`. Changing them means forking: edit the distribution config and rebuild the binary. The distribution config's \`vocabulary\` export is not a config field at all — no layer may declare it, and a fork changes it in the same file it changes \`name\` in.`,
+    "## What `config show` reports",
+    `\`${BIN_NAME} config show\` prints ${REPORTED_FIELDS.map((field) => `\`${field}\``).join(", ")} — those and only those — each with the layer that supplied it. The rest resolve without being reported that way: \`prefixes\` and \`completion\` appear only in the \`--format json\` payload, \`prefixes\` with an origin and \`completion\` with none; \`stories\` carries an origin whose value the payload leaves out; and the four distribution-only fields above carry neither. The plain and llm forms print those rows and nothing else; \`--format json\` returns the resolved config and the origin map whole.`,
+    "## Renamed: `packages` → `packs`",
+    "The `packages` field was renamed to `packs`. A layer that still declares `packages:` fails loudly: the rename is detected before the schema's unknown-key stripping could hide it, and the error names it. Rename the key — the entry shape is unchanged.",
+    "## Removed: `generators`",
+    "The `generators` field was removed: it was accepted by the validator, layered, and read by nothing — the `create` verbs resolve their generators statically (a compiled binary can only run generators it was linked with), so declaring it changed only what `config show` printed. A layer that still declares it fails loudly at load with an error naming the removed field; delete it. Declared generators may return as a working feature in a later program.",
+    "## Removed: `completion.caseSensitive`",
+    "The `completion.caseSensitive` field was removed: it was accepted by the validator and read by nothing — completion matching is declared per parameter by the capability grammar, never configured. A layer that still sets it fails loudly at load with an error naming the removed field; delete the key. `completion.minChars` and `completion.families` are unchanged.",
+    "## Reading and writing",
+    `\`${BIN_NAME} config show\` prints the resolved config and each field's layer. \`${BIN_NAME} config set <key> <value>\` writes to the **global** layer only — project configs are authored by hand. Both are documented in the [command reference](./commands.md).`,
+  ]);
+}
+
 /** Render the reference index: overview, derived counts, and links. */
 function renderIndexPage(
   verbs: readonly VerbSpec[],
@@ -450,8 +581,8 @@ function renderIndexPage(
   const nouns = new Set(verbs.map((verb) => verb.path[0]));
   const toolCount = verbs.filter((verb) => verb.capability.mcp.expose).length;
   return assemblePage([
-    "# pragma reference",
-    "Machine-generated reference for the `pragma` CLI and MCP server, projected from the live capability grammar. Every page here is regenerated by the build and pinned by a drift-guard test, so it can never fall out of step with the code.",
+    `# ${BIN_NAME} reference`,
+    `Machine-generated reference for the \`${BIN_NAME}\` CLI and MCP server, projected from the live capability grammar. Every page here is regenerated by the build and pinned by a drift-guard test, so it can never fall out of step with the code.`,
     "## At a glance",
     [
       `- **${nouns.size}** command nouns`,
@@ -461,9 +592,10 @@ function renderIndexPage(
     ].join("\n"),
     "## Pages",
     [
-      "- [CLI command reference](./commands.md) — every `pragma <noun> <verb>`, its arguments, flags, and examples.",
+      `- [CLI command reference](./commands.md) — every \`${BIN_NAME} <noun> <verb>\`, its arguments, flags, and examples.`,
       "- [MCP tool reference](./tools.md) — every exposed tool, its input schema, and the non-tool surface.",
       "- [Errors & exit codes](./errors.md) — the exit-code table, response envelope, and error catalog.",
+      "- [Configuration reference](./config.md) — every config field, the three layers, and how they combine.",
     ].join("\n"),
   ]);
 }
@@ -487,5 +619,6 @@ export function emitReference(
     ["commands.md", renderCommandsPage(verbs)],
     ["tools.md", renderToolsPage(verbs, modules)],
     ["errors.md", renderErrorsPage()],
+    ["config.md", renderConfigPage()],
   ]);
 }

package/src/kernel/spec/emitSurface.ts

@@ -8,6 +8,7 @@
  * envelope, exit codes, budgets, ...). Hidden verbs are excluded.
  */
 
+import { BIN_NAME, PROJECT_CONFIG_FILENAME } from "../../constants.js";
 import type { CapabilityModule, ParamSpec, VerbSpec } from "./types.js";
 
 /** kebab-case a camelCase param name for its flag form (`allTiers` -> `all-tiers`). */
@@ -74,7 +75,7 @@ export interface EmittedSurface {
  */
 export const FIXED_SURFACE = {
   bins: {
-    pragma: "pragma v2 CLI and MCP server host (stdio)",
+    [BIN_NAME]: `${BIN_NAME} CLI and MCP server host (stdio)`,
   },
   globalFlags: [
     {
@@ -122,14 +123,17 @@ export const FIXED_SURFACE = {
     paramSource: "ParamSpec.complete",
   },
   configFiles: {
-    project: "pragma.config.ts (evaluated, content-hash cached)",
-    global: "$XDG_CONFIG_HOME/pragma/config.json",
-    lock: "$XDG_STATE_HOME/pragma/config-cache/<sha256>.json",
+    project: `${PROJECT_CONFIG_FILENAME} (evaluated, content-hash cached)`,
+    global: `$XDG_CONFIG_HOME/${BIN_NAME}/config.json`,
+    // Named `configCache` because that is what it is: the evaluated project
+    // config's content-addressed cache. It was called `lock` for a project lock
+    // file that no longer exists.
+    configCache: `$XDG_STATE_HOME/${BIN_NAME}/config-cache/<sha256>.json`,
     defaults: "built-in defaults.ts",
   },
   budgets: {
     $comment:
-      "help/complete are the designed <50ms aspiration; the ENFORCED ceilings (budgets.test.ts) are 130ms help / 100ms complete — ~2× the measured median on the build hardware, recorded in BUDGETS.md. Designed-aspiration vs enforced-measured.",
+      "help/complete/warmStoreVerb are designed aspirations; the ENFORCED ceilings (budgets.test.ts) are 130ms help / 100ms complete / 500ms warmStoreVerb, each derived from measurement on the build hardware and recorded in BUDGETS.md. Designed-aspiration vs enforced-measured. warmStoreVerb joined this list when the embedded pack became the distribution's real graph rather than a sample, which puts the reference box's projected p95 over the designed 300ms; BUDGETS.md carries the arithmetic.",
     help: "<50ms",
     complete: "<50ms",
     projectConfigLoad: "<10ms",

package/src/kernel/spec/surfaceConformance.test.ts

@@ -84,8 +84,8 @@ describe("surface conformance (PROTECTED)", () => {
     );
   });
 
-  it("freezes exactly 38 designed MCP tools including info, config_show, config_set, colophon", () => {
-    expect(golden.mcpSurface.tools).toHaveLength(38);
+  it("freezes exactly 37 designed MCP tools including info, config_show, config_set, colophon", () => {
+    expect(golden.mcpSurface.tools).toHaveLength(37);
     expect(golden.mcpSurface.tools).toContain("info");
     expect(golden.mcpSurface.tools).toContain("config_show");
     expect(golden.mcpSurface.tools).toContain("config_set");

package/src/kernel/spec/surfaceConformance.ts

@@ -36,6 +36,14 @@ export interface Covenant {
     readonly resources?: readonly string[];
     readonly prompts?: boolean;
     readonly instructions?: boolean;
+    /**
+     * The wire-identity RULE (L-PR6 covenant extension): `serverInfo` projects
+     * from the distribution, stated as placeholders rather than live values so
+     * the covenant does not churn per release. Documentation for conformance —
+     * `assertConforms` does not deep-check it; `surface.test.ts` pins the rule
+     * text and the live handshake, `identity.test.ts` pins it from a fork.
+     */
+    readonly serverInfo?: { readonly name: string; readonly version: string };
   };
   readonly [section: string]: unknown;
 }

package/src/kernel/spec/types.ts

@@ -42,19 +42,28 @@ export type Capability = {
  * `__complete` never boots the graph, so every source is disk-readable: the
  * precomputed pack index, the filesystem, or the prefix table.
  */
-export type CompletionFrom =
-  | "index"
-  | "skills"
-  | "tiers"
-  | "prompts"
-  | "prefixes";
-
-/** A reference to one name source (with an optional prefixed type filter). */
+export type CompletionFrom = "index" | "skills" | "prefixes";
+
+/**
+ * Which of an index entity's name-bearing fields a param completes against.
+ * The kernel knows no entity families — a family is a `type` filter plus the
+ * field that family is addressed by, both declared at the verb.
+ */
+export type CompletionField = "name" | "label" | "altNames";
+
+/** A reference to one name source: where from, and which field of it. */
 export interface CompletionSourceRef {
   /** Which storeless source to read candidate names from. */
   readonly from: CompletionFrom;
   /** Prefixed type filter — meaningful only for `from: "index"` (empty = any). */
   readonly type?: string;
+  /**
+   * Which field the candidates come from — `from: "index"` only, default
+   * `"name"`. Declare the field the verb's lookup MATCHES on: `label` and
+   * `altNames` are optional index enrichment, and an entity carrying neither
+   * contributes no candidate rather than a token the lookup would refuse.
+   */
+  readonly field?: CompletionField;
 }
 
 /** How a partial word is matched against candidate names. */
@@ -153,7 +162,8 @@ export interface ErrorSpec {
  * `run` is the effect seam — a read returns `Promise<R>`; a mutation returns a
  * `Task<R>` the dispatcher interprets under the node / dry-run interpreters. A
  * mutation that needs async setup before its effects are known (e.g.
- * `sources update` resolves and builds before locking) actually returns a
+ * `sources update` resolves and builds before pointing the project at the pack)
+ * actually returns a
  * `Promise<Task<R>>`, which the dispatcher and MCP handler both `await` into a
  * `Task<R>` before interpreting. That third shape is presented through the
  * `Task<R>` arm by a cast at the one call site (`update.verb.ts`): adding a
@@ -225,6 +235,16 @@ export interface CapabilityModule {
    * it has zero covenant impact.
    */
   readonly colophon?: string;
+  /**
+   * This module was compiled — wholly or in part — from a declared read story,
+   * so a story in the user's own CONFIG for the same noun REPLACES it. Authored
+   * modules (config, ontology, doctor, …) carry no story and can never be
+   * replaced; neither can any shipped noun be replaced by a PACKAGE story (see
+   * `kernel/packs/collect.validateStories`). Set where a story is compiled
+   * (`capabilities/distribution.ts` and the three composite nouns), read once,
+   * by `kernel/packs/collect.assembleEffectiveModules`.
+   */
+  readonly story?: true;
   readonly boot?: (rt: PragmaRuntime) => void;
   /** An optional MCP resource surface (NOT a VerbSpec field — a module hook). */
   readonly mcpResources?: McpResourceProvider;

package/src/kernel/spec/validate.ts

@@ -17,8 +17,9 @@ const fn = z.custom<(...args: unknown[]) => unknown>(
 );
 
 const completionSourceRefSchema = z.object({
-  from: z.enum(["index", "skills", "tiers", "prompts", "prefixes"]),
+  from: z.enum(["index", "skills", "prefixes"]),
   type: z.string().optional(),
+  field: z.enum(["name", "label", "altNames"]).optional(),
 });
 
 const paramCompleteSchema = z.union([

package/src/kernel/vocabulary.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+import { dataNq } from "./runtime/graphpack/embedded/pack.generated.js";
+import { embeddedManifest } from "./runtime/graphpack/embedded.js";
+import type { DeclaredVocabulary } from "./vocabulary.js";
+import { parseVocabulary, VOCABULARY } from "./vocabulary.js";
+
+/** A valid declaration, cloned per case so one field can be made hostile. */
+const createValidDeclaration = (): DeclaredVocabulary => ({
+  altName: "ex:name",
+  prompt: {
+    type: "ex:Prompt",
+    body: "ex:body",
+    argument: "ex:argument",
+    argName: "ex:argName",
+    argRequired: "ex:argRequired",
+  },
+});
+
+/** The bindings `createValidDeclaration`'s terms resolve against. */
+const BOUND = { ex: "https://ex.test/" };
+
+describe("parseVocabulary", () => {
+  it("returns the same declaration when every term is readable", () => {
+    const declaration = createValidDeclaration();
+    expect(parseVocabulary(declaration, BOUND, "x.conf.ts")).toBe(declaration);
+  });
+
+  it("rejects an absolute IRI, naming the field and the file", () => {
+    // The defect this validator exists for. An absolute IRI written bare is a
+    // SPARQL parse error; caught at the read site it becomes "this graph has no
+    // prompts", indistinguishable from an empty graph. Here it is a startup
+    // CONFIG_ERROR that says which term is wrong and where.
+    let caught: unknown;
+    try {
+      parseVocabulary(
+        { ...createValidDeclaration(), altName: "https://ex.test/name" },
+        BOUND,
+        "x.conf.ts",
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const { message } = caught as { message: string };
+    expect(message).toContain("altName");
+    expect(message).toContain("x.conf.ts");
+    expect(message).toContain("https://ex.test/name");
+  });
+
+  it("rejects a term whose prefix nothing binds, naming that prefix", () => {
+    // The likelier malformation, and the one the shape check alone lets past.
+    // A one-character typo passes `prefix:local` and then makes every read of
+    // that term fail — the index silently loses `altNames`, and the prompt
+    // SELECT fails in a way a caller cannot tell from an empty graph. So the
+    // binding is checked here, where the file that declares both is one place.
+    let caught: unknown;
+    try {
+      parseVocabulary(
+        { ...createValidDeclaration(), altName: "exx:name" },
+        BOUND,
+        "x.conf.ts",
+      );
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const { message, recovery } = caught as {
+      message: string;
+      recovery?: { message: string };
+    };
+    expect(message).toContain("altName");
+    expect(message).toContain("exx:");
+    expect(recovery?.message).toContain("exx");
+  });
+
+  it("rejects a nested prompt term whose prefix nothing binds", () => {
+    const declaration = createValidDeclaration();
+    expect(() =>
+      parseVocabulary(
+        {
+          ...declaration,
+          prompt: { ...declaration.prompt, type: "other:Prompt" },
+        },
+        BOUND,
+        "x.conf.ts",
+      ),
+    ).toThrow(/prompt\.type/);
+  });
+
+  it("rejects a term naming an inherited Object property as its prefix", () => {
+    // `prefixes` is a plain record, so an unbound prefix must be UNBOUND, not
+    // whatever the prototype chain answers. Without an own-key check
+    // `constructor:name` passes and expands to a stringified function.
+    expect(() =>
+      parseVocabulary(
+        { ...createValidDeclaration(), altName: "constructor:name" },
+        BOUND,
+        "x.conf.ts",
+      ),
+    ).toThrow(/constructor:/);
+  });
+
+  it("rejects a nested prompt term, naming its path", () => {
+    const declaration = createValidDeclaration();
+    expect(() =>
+      parseVocabulary(
+        {
+          ...declaration,
+          prompt: { ...declaration.prompt, body: "<ex:body>" },
+        },
+        BOUND,
+        "x.conf.ts",
+      ),
+    ).toThrow(/prompt\.body/);
+  });
+
+  it("rejects an empty, unprefixed, whitespace-bearing or malformed term", () => {
+    for (const term of ["", "name", "ex:", ":name", "ex: name", "ex:na me"]) {
+      expect(() =>
+        parseVocabulary(
+          { ...createValidDeclaration(), altName: term },
+          BOUND,
+          "x.conf.ts",
+        ),
+      ).toThrow(/altName/);
+    }
+  });
+});
+
+describe("the shipped declaration", () => {
+  it("declares the name property entities are addressed by", () => {
+    expect(VOCABULARY.altName).toBe("ds:name");
+  });
+
+  it("names a property the shipped pack actually carries", () => {
+    // The declaration and the committed pack are produced independently, and
+    // NOTHING makes the pack follow the declaration: `contentHash` covers pack
+    // sources only, and `buildPack` reuses any complete cache directory, so
+    // editing `altName` here re-mints no index and `sources update` cannot
+    // repair the mismatch. Left silent, the CLI would offer the old property's
+    // tokens from the index and match the new one in every lookup.
+    //
+    // So expand the declared term through the pack's OWN manifest and look for
+    // it as a predicate in the pack's data. The prompt terms get no such check
+    // — they are a read contract, and this graph carries no prompt entities.
+    const [prefix, local] = VOCABULARY.altName.split(":");
+    const namespace = embeddedManifest().prefixes[prefix ?? ""];
+    expect(namespace, `pack binding for \`${prefix}:\``).toBeDefined();
+    expect(
+      dataNq.includes(` <${namespace}${local}> `),
+      `\`${VOCABULARY.altName}\` used as a predicate in the shipped pack`,
+    ).toBe(true);
+  });
+
+  it("declares the prompt entity shape, value for value", () => {
+    expect(VOCABULARY.prompt).toEqual({
+      type: "ds:Prompt",
+      body: "ds:promptBody",
+      argument: "ds:promptArgument",
+      argName: "ds:argName",
+      argRequired: "ds:argRequired",
+    });
+  });
+});