@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/kernel/runtime/graphpack/embedded/pack.manifest.generated.ts

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by scripts/bundle.ts — do not edit by hand.
+// Regenerate from the packs pragma.conf.ts declares: `bun run bundle`.
+export const manifestJson = "{\"name\":\"pragma\",\"version\":\"0.36.0\",\"sourceRef\":\"@canonical/design-system@git:ce00818852628857da9c4a67bf8556c7cfda287d, @canonical/anatomy-dsl@npm:0.3.0, @canonical/token-ontology@npm:0.8.1, @canonical/code-standards@git:fcd3ac2dea458775e5b79344b3237a3fcb37add9, @canonical/ds-implementations@self:v0.36.0\",\"contentHash\":\"7ff2bbd5fd059584ad3285c7b1c7d59c734efef8006fb0bba726db03254392e8\",\"prefixes\":{\"rdf\":\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\",\"rdfs\":\"http://www.w3.org/2000/01/rdf-schema#\",\"owl\":\"http://www.w3.org/2002/07/owl#\",\"xsd\":\"http://www.w3.org/2001/XMLSchema#\",\"skos\":\"http://www.w3.org/2004/02/skos/core#\",\"sh\":\"http://www.w3.org/ns/shacl#\",\"dcterms\":\"http://purl.org/dc/terms/\",\"ds\":\"https://ds.canonical.com/\",\"anatomy\":\"http://anatomy-dsl.example.org/ontology#\",\"graphql\":\"https://pragma.canonical.com/graphql#\",\"w3c-tokens\":\"https://dt.canonical.com/w3c-tokens/\",\"dt\":\"https://dt.canonical.com/\",\"cs\":\"http://pragma.canonical.com/codestandards#\",\"dso\":\"https://ds.canonical.com/ontology#\"},\"createdAt\":\"2026-09-01T20:29:05.995Z\",\"tripleCount\":30346,\"entityCount\":2906}";

package/src/kernel/runtime/graphpack/embedded.ts

@@ -18,10 +18,12 @@
  *
  * The inlined strings are materialized into the ordinary content-addressed pack
  * cache on first use and then read back through {@link readPack}, so the
- * embedded pack and a built pack share one boot path. The story records live in
- * their OWN generated module (like the index): dispatch reads them on every
- * command, and pulling them out of `pack.generated.ts` would load its ~1.9 MB
- * of n-quads with them — a measured +28 ms on every invocation. Inlining as JS strings
+ * embedded pack and a built pack share one boot path. The story records, the
+ * index and the MANIFEST each live in their own generated module: every one of
+ * them is read on a path that does not need the n-quads, and leaving any of
+ * them beside `pack.generated.ts` would load its ~2.1 MB with them — a measured
+ * +28 ms on every invocation for the stories, and ~370 ms per CLI invocation
+ * for the manifest at a 30,340-triple pack. Inlining as JS strings
  * (rather than file assets) means the pack travels with the emitted modules —
  * it needs no asset step in any build, and no file lookup at run time.
  */
@@ -36,8 +38,8 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { packDir, packsCacheDir } from "../paths.js";
-import { dataNq, manifestJson, schemaJson } from "./embedded/pack.generated.js";
 import { indexJson } from "./embedded/pack.index.generated.js";
+import { manifestJson } from "./embedded/pack.manifest.generated.js";
 import { storiesJson } from "./embedded/pack.stories.generated.js";
 import { packIsComplete } from "./manifest.js";
 import { manifestSchema } from "./schemas.js";
@@ -72,10 +74,16 @@ export function embeddedManifest(): Manifest {
  * @returns The pack directory, ready for {@link readPack}.
  * @note Impure — writes the inlined pack files into the cache.
  */
-export function materializeEmbeddedPack(): string {
+export async function materializeEmbeddedPack(): Promise<string> {
   const dir = packDir(embeddedManifest().contentHash);
   if (packIsComplete(dir)) return dir;
 
+  // Loaded HERE, not at module scope: this is the only branch that needs the
+  // payload, and it is the branch that does NOT run once the pack is cached.
+  // A static import would parse ~2.1 MB of inlined n-quads on every boot to
+  // reach a return statement six lines above.
+  const { dataNq, schemaJson } = await import("./embedded/pack.generated.js");
+
   mkdirSync(packsCacheDir(), { recursive: true });
   const temp = mkdtempSync(join(packsCacheDir(), ".embed-"));
   try {

package/src/kernel/runtime/graphpack/graphpack.test.ts

@@ -144,15 +144,21 @@ describe("the committed embedded pack (PROTECTED)", () => {
     // directory holds — which the next build then reuses, silently dropping the
     // difference. Comparing the two directories catches that on the day it lands.
     const built = await build([{ path: "a.ttl", content: TTL }]);
-    expect(readdirSync(materializeEmbeddedPack()).sort()).toEqual(
+    expect(readdirSync(await materializeEmbeddedPack()).sort()).toEqual(
       readdirSync(built.dir).sort(),
     );
-  });
-
-  it("is self-consistent: complete, content-addressed, and non-empty", () => {
+    // 60s, not the 5s default. This test does real work twice: it BUILDS a
+    // pack from source, and it materialises the embedded one — which on a cold
+    // cache takes the miss branch and imports the multi-megabyte payload. Both
+    // costs grow with the pack, and the pack grows whenever a source is added.
+    // A default that a pack size can outgrow turns a real assertion into an
+    // intermittent one.
+  }, 60_000);
+
+  it("is self-consistent: complete, content-addressed, and non-empty", async () => {
     // No network, so CI runs it: the committed strings really do materialize a
     // bootable pack whose parts agree with each other.
-    const dir = materializeEmbeddedPack();
+    const dir = await materializeEmbeddedPack();
     const manifest = embeddedManifest();
     expect(packIsComplete(dir)).toBe(true);
     expect(basename(dir)).toBe(manifest.contentHash);
@@ -162,6 +168,26 @@ describe("the committed embedded pack (PROTECTED)", () => {
     expect(index.contentHash).toBe(manifest.contentHash);
     expect(manifest.tripleCount ?? 0).toBeGreaterThan(0);
     expect(manifest.entityCount ?? 0).toBeGreaterThan(0);
+
+    // EXACT, not "> 0", and it earns its keep twice.
+    //
+    // The manifest and the n-quads now live in SEPARATE generated modules, so
+    // a partial regeneration or a one-file `git add` can leave them describing
+    // different packs — a skew that could not exist while they shared a
+    // module. `read.ts` tolerates a superset deliberately, so it would serve
+    // the skew rather than refuse it.
+    //
+    // It also pins the equivalence `read.ts` depends on but cannot state:
+    // `store.size` (quads) against a `tripleCount` that `build.ts` computes
+    // with `SELECT (COUNT(*))` over the union graph. They agree on oxigraph
+    // 0.5.6; oxigraph is pinned by caret, so this is where a future version
+    // that deduplicates the union would be caught.
+    const session = await readPack(dir);
+    try {
+      expect(session.store.size).toBe(manifest.tripleCount);
+    } finally {
+      session.store.dispose();
+    }
   });
 });
 

package/src/kernel/runtime/graphpack/read.ts

@@ -80,15 +80,25 @@ export async function readPack(dir: string): Promise<StoreSession> {
   // "populated index but empty store" check (via the now-empty dump,
   // `packIsComplete` turns false so recovery rebuilds) rather than serving an
   // empty graph as the pack.
-  const actualTriples = await countTriples(store);
+  // `store.size` is a field oxigraph maintains. The equivalent query —
+  // `SELECT (COUNT(*)) WHERE { ?s ?p ?o }`, which is what `build.ts` still runs
+  // to WRITE `tripleCount` — is a scan, and it ran on every boot to read a
+  // number the store already knew.
+  //
+  // The two agree: ke queries with `use_default_graph_as_union`, and oxigraph
+  // does not deduplicate across that union, so a quad count and the union's
+  // solution count are the same number even for a triple repeated across
+  // graphs. Verified against 0.5.6 rather than assumed — and the guard is `<`,
+  // which tolerates the direction a set-semantic union would drift.
+  const actualQuads = store.size;
   if (manifest.tripleCount !== undefined) {
-    if (actualTriples < manifest.tripleCount) {
+    if (actualQuads < manifest.tripleCount) {
       store.dispose();
       throw packUnavailable(
-        `The pack at ${dir} has a corrupt data cache (expected at least ${manifest.tripleCount} triples, loaded ${actualTriples}).`,
+        `The pack at ${dir} has a corrupt data cache (expected at least ${manifest.tripleCount} triples, loaded ${actualQuads}).`,
       );
     }
-  } else if (index.entities.length > 0 && actualTriples === 0) {
+  } else if (index.entities.length > 0 && actualQuads === 0) {
     store.dispose();
     throw packUnavailable(`The pack at ${dir} has a corrupt data cache.`);
   }
@@ -101,11 +111,3 @@ export async function readPack(dir: string): Promise<StoreSession> {
     index,
   };
 }
-
-/** Count the booted store's triples (a cheap aggregate over the union graph). */
-async function countTriples(store: StoreSession["store"]): Promise<number> {
-  const result = (await store.query(
-    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
-  )) as import("@canonical/ke").SelectResult;
-  return Number(result.bindings.at(0)?.n ?? 0);
-}

package/src/kernel/runtime/loadSession.ts

@@ -43,6 +43,8 @@ export async function loadStoreSession(
   }
 
   const dir =
-    decision.kind === "embedded" ? materializeEmbeddedPack() : decision.dir;
+    decision.kind === "embedded"
+      ? await materializeEmbeddedPack()
+      : decision.dir;
   return readPack(dir);
 }

package/src/kernel/runtime/probe.ts

@@ -21,7 +21,7 @@ export async function runStoreProbe(): Promise<string> {
     import("./graphpack/embedded.js"),
     import("./graphpack/read.js"),
   ]);
-  const session = await readPack(materializeEmbeddedPack());
+  const session = await readPack(await materializeEmbeddedPack());
   try {
     const result = await session.store.query(
       "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,

package/src/kernel/runtime/refs/parseRef.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { redactUrl } from "./parseRef.js";
+import { parsePackDeclaration, redactUrl } from "./parseRef.js";
 
 describe("redactUrl", () => {
   it("strips user:password userinfo so an inlined token never reaches output", () => {
@@ -32,3 +32,51 @@ describe("redactUrl", () => {
     );
   });
 });
+
+describe("parsePackDeclaration — a git source may name a subdirectory", () => {
+  const url = "git+https://github.com/org/repo.git";
+
+  it("reaches a package nested in a monorepo", () => {
+    expect(
+      parsePackDeclaration({
+        name: "@org/thing",
+        source: `${url}#main:pkgs/thing`,
+      }),
+    ).toEqual({
+      kind: "git",
+      pkg: "@org/thing",
+      url: "https://github.com/org/repo.git",
+      ref: "main",
+      subdir: "pkgs/thing",
+      source: `${url}#main:pkgs/thing`,
+    });
+  });
+
+  it("leaves a plain ref untouched, with no subdir key", () => {
+    const ref = parsePackDeclaration({
+      name: "@org/thing",
+      source: `${url}#main`,
+    });
+    expect(ref).toEqual({
+      kind: "git",
+      pkg: "@org/thing",
+      url: "https://github.com/org/repo.git",
+      ref: "main",
+      source: `${url}#main`,
+    });
+    expect("subdir" in ref).toBe(false);
+  });
+
+  it("splits on the FIRST colon, so a nested path survives", () => {
+    // The ref cannot contain a colon; the subdirectory can contain slashes.
+    expect(
+      parsePackDeclaration({ name: "@org/t", source: `${url}#v1.2:a/b/c` }),
+    ).toMatchObject({ ref: "v1.2", subdir: "a/b/c" });
+  });
+
+  it("rejects an empty subdirectory rather than silently ignoring it", () => {
+    expect(() =>
+      parsePackDeclaration({ name: "@org/thing", source: `${url}#main:` }),
+    ).toThrow(/subdirectory after : is empty/);
+  });
+});

package/src/kernel/runtime/refs/parseRef.ts

@@ -25,6 +25,8 @@ export type PackageRef =
       readonly pkg: string;
       readonly url: string;
       readonly ref: string;
+      /** Package root WITHIN the clone, for a package nested in a monorepo. */
+      readonly subdir?: string;
       readonly source: string;
     };
 
@@ -72,11 +74,33 @@ export function parsePackDeclaration(entry: PackDeclaration): PackageRef {
         },
       );
     }
+    // `#<ref>` or `#<ref>:<subdir>`. A git ref cannot contain a colon
+    // (git check-ref-format), so the split is unambiguous.
+    const fragment = source.slice(hashIdx + 1);
+    const colonIdx = fragment.indexOf(":");
+    if (colonIdx !== -1 && colonIdx === fragment.length - 1) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": the subdirectory after : is empty.`,
+        {
+          recovery: {
+            message:
+              "Example: git+https://github.com/org/repo.git#main:packages/thing",
+          },
+        },
+      );
+    }
+    const ref = colonIdx === -1 ? fragment : fragment.slice(0, colonIdx);
+    if (ref.length === 0) {
+      throw PragmaError.configError(
+        `Invalid source for "${name}": git URL must include a ref after #.`,
+      );
+    }
     return {
       kind: "git",
       pkg: name,
       url: source.slice("git+".length, hashIdx),
-      ref: source.slice(hashIdx + 1),
+      ref,
+      ...(colonIdx === -1 ? {} : { subdir: fragment.slice(colonIdx + 1) }),
       source,
     };
   }

package/src/kernel/runtime/refs/resolve.ts

@@ -383,13 +383,19 @@ export async function resolvePackage(
           },
         );
       }
+      // The clone lives at `dir`; the PACKAGE may be nested within it. A git
+      // source names a repository, so a package inside a monorepo is reached
+      // by its subdirectory — without which `readTtlSources` would scan a
+      // repository root that has no `definitions/` or `data/` and contribute
+      // nothing at all.
+      const packageRoot = ref.subdir ? join(dir, ref.subdir) : dir;
       return {
         name: ref.pkg,
         source: ref.source,
         resolved,
-        root: dir,
-        sources: readTtlSources(dir, ref.pkg),
-        stories: readStorySources(dir, ref.pkg),
+        root: packageRoot,
+        sources: readTtlSources(packageRoot, ref.pkg),
+        stories: readStorySources(packageRoot, ref.pkg),
       };
     }
   }

package/src/kernel/runtime/types.ts

@@ -8,6 +8,7 @@
  * that are actually populated by the time it runs.
  */
 
+import type { UndoOutcome } from "@canonical/task/node";
 import type { DetailLevel, OutputFormat } from "../../constants.js";
 import type { ConfigLayers } from "../config/types.js";
 
@@ -221,4 +222,20 @@ export interface PragmaRuntime {
    * plan of its own, which is what keeps the raw-effect render the default.
    */
   planData?: unknown;
+  /**
+   * The post-undo projection seam. `--undo` is two-phase: the undo
+   * interpreter WALKS the verb's task with every effect mocked to collect the
+   * reversals, and only then executes what it collected — so nothing the task
+   * body says while it is interpreted describes what the reversals did (the
+   * body only ever runs under the mocked walk). What DOES describe them is
+   * the interpreter's own per-undo outcomes, correlated by the `undoKey` each
+   * reversal was declared with. A verb that reports per-target results sets
+   * this (the same way it sets `exec`/`planData`, before returning its Task);
+   * the projector's undo branch awaits it with those outcomes AFTER the
+   * collected undos executed and before the `Undid N step(s).` line, so the
+   * verb projects them onto its own rows through the same path its forward
+   * run uses. A throw here is rendered as the run's error (nonzero exit) —
+   * the honest outcome when a reversal did not take.
+   */
+  undoReport?: (outcomes: readonly UndoOutcome[]) => void | Promise<void>;
 }

package/src/kernel/spec/emitReference.ts

@@ -541,7 +541,7 @@ const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
   logo: {
     type: "string[] (optional)",
     notes:
-      "Distribution-only — see below. ASCII-art wordmark lines shown above the header on root `--help`, tinted with the terminal palette's orange slot. Declared content, not code: a wordmark spells the distribution's name, so a fork ships its own art or omits the field and gets no wordmark. Omit or leave empty for a bare header.",
+      "Distribution-only — see below. ASCII-art wordmark lines shown above the header on root `--help`, tinted with the terminal palette's orange slot. Shown to a HUMAN reader only: the front door omits the art for MACHINE-ORIENTED output — `--format llm` or `--format json`, plus the `llm` a non-interactive stdout auto-infers — so a piped `--help` spends none of an agent's budget on a picture of the name it just typed. The gate is the output SHAPE, not whether stdout is a terminal, and explicit beats inferred in both directions: `--format plain` keeps the art down a pipe (as does `PRAGMA_NO_AUTO_LLM`, which turns the inference off), and `--format llm` drops it on a TTY. Declared content, not code: a wordmark spells the distribution's name, so a fork ships its own art or omits the field and gets no wordmark. Omit or leave empty for a bare header.",
   },
   colophon: {
     type: "object (optional)",

package/src/kernel/spec/types.ts

@@ -149,11 +149,40 @@ export type ParamSpec =
  * list-shaped formatters read it; `llm` (the byte-frozen agent contract) and
  * `json` (the envelope) never see it.
  *
- * `emptyNotice` is the empty-state seam: when the data amounts to zero
- * records, return the calm notice — the dispatcher routes it to STDERR with
- * exit 0, keeping the stdout data stream free of human sentences a pipe
- * would read as records. Return `undefined` (or omit the member) for data
- * that has content; only the plain mode routes it.
+ * `notice` is the seam for what the DATA cannot say about itself. Return the
+ * calm sentence when the payload would otherwise misrepresent the read; return
+ * `undefined` (or omit the member) when it speaks for itself.
+ *
+ * Two shapes qualify, and they are the same failure. A zero-record result
+ * ("empty ≠ silence"): an unbuilt store, a mistyped filter and a genuinely empty
+ * result were all `{"ok":true,"data":[],"meta":{}}`. And a result that is one of
+ * several it could have been — a `lookup` whose name reached more entities than
+ * the one it answers with. A caller shown Launchpad's `Button` has no way to
+ * discover the global one from a payload that looks exactly like an unambiguous
+ * hit; the notice names the IRIs the answer did not take, which is the only
+ * address that reaches them.
+ *
+ * It was called `emptyNotice` while emptiness was the only case. The channel is
+ * unchanged — same key, same three surfaces — so this is one seam covering both,
+ * not a second one grown beside it.
+ *
+ * Three surfaces route it, each in its own register — it is one seam, not a
+ * plain-mode courtesy:
+ * - `plain`: the dispatcher writes it to STDERR with exit 0, keeping the stdout
+ *   data stream free of human sentences a pipe would read as records. `--quiet`
+ *   mutes it (success-path guidance).
+ * - `--format json` AND the MCP tool result: it rides the envelope as
+ *   `meta.notice` (`project/cli/dispatch.ts#renderData`,
+ *   `project/mcp/registerVerb.ts#emptyMeta` — the same key from the same seam,
+ *   so the two MACHINE surfaces stay byte-equal). `data` keeps its uniform empty
+ *   shape; `[]` stays `[]`. Without it an agent could not tell an unbuilt store,
+ *   a mistyped filter and a genuinely empty result apart — all three were
+ *   `{"ok":true,"data":[],"meta":{}}`.
+ * - `llm` (the byte-frozen agent contract) is the ONE mode that still ignores
+ *   it: it renders one stream and its bytes are frozen.
+ *
+ * The formatters themselves never see the notice: `json(d)` renders the data
+ * alone, and the ENVELOPE layer carries the notice beside it.
  */
 export interface Formatters<T> {
   readonly plain: (
@@ -162,7 +191,7 @@ export interface Formatters<T> {
   ) => string;
   readonly llm: (d: T) => string;
   readonly json: (d: T) => string;
-  readonly emptyNotice?: (d: T) => string | undefined;
+  readonly notice?: (d: T) => string | undefined;
 }
 
 /** A usage example shown in verb help. */

package/src/testing/PARITY_GAPS.ts

@@ -42,13 +42,13 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "read-meta-always-empty",
     area: "envelope",
     description:
-      "`dispatch.ts#executeVerb`'s read branch always renders with `meta: {}` — there is no `meta.count`/`meta.total` field on a list/lookup envelope (verified empirically). An empty (possibly filtered) list is `{ok:true, data:[], meta:{}}`; the only way to know it's empty is `data.length === 0`, not a meta field.",
+      "NARROWED: a read envelope still carries no `meta.count`/`meta.total` — the only way to know a list is empty is `data.length === 0`, not a count field. But `meta` is no longer ALWAYS `{}` on a read. A zero-record read now carries the verb's own `notice` as `meta.notice` on BOTH machine surfaces (`project/cli/dispatch.ts#renderData` for `--format json`, `project/mcp/registerVerb.ts#emptyMeta` for MCP — one seam, the same key, so the two stay byte-equal). `data` keeps its uniform empty shape; `[]` is still `[]`. The divergence this entry records is the ABSENCE of counts, not the emptiness of `meta`: without the notice an agent could not tell an unbuilt store, a mistyped filter and a genuinely empty result apart, all three being `{ok:true,data:[],meta:{}}`.",
   },
   {
     id: "no-empty-hook-on-free-filter",
     area: "pack list / empty-state",
     description:
-      "A zero-row pack list — whether narrowed by a declared filter, an unmatched `--search`, or unconditionally empty — returns `ok:true, data:[], meta:{}` at exit 0 with a calm `emptyMessage`/`emptyHint`; pragma v2 never raises a typed EMPTY_RESULTS error for an empty list. (U5 removed the former enum-filter-only `buildListEmptyError` hook, making the empty-state uniform across every list verb.)",
+      "STILL TRUE OF EMPTINESS, NARROWED ON BAD ARGUMENTS. A zero-row pack list — narrowed by a declared filter, by an unmatched `--search`, or unconditionally empty — is a SUCCESS: `ok:true, data:[]` at exit 0 with a calm notice (stderr in plain mode, `meta.notice` on the machine surfaces). pragma v2 still never raises EMPTY_RESULTS for an empty list, and U5's removal of the enum-filter-only `buildListEmptyError` hook stands. What is no longer true is that an UNMATCHED free-filter value stays successful: a value-free filter now rejects a value its vocabulary does not admit with INVALID_INPUT and the admissible values as `validOptions`, the same courtesy a declared-`values` filter always extended (`packs/sparql/applyFilters.ts`). The vocabulary is the graph's, not the returned rows' — a filter declares where it lives (`PackFilter.vocabulary`), so a real value that happens to match no row (a category with zero standards, a `ds:ConceptType` no concept uses) is a calm empty list, and only a value the graph does not know is an error.",
   },
   {
     id: "raw-iri-in-data",
@@ -84,7 +84,7 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "block-lookup-not-tier-scoped",
     area: "block",
     description:
-      "`block lookup` resolves by `ds:name` GLOBALLY, with no tier or channel filtering. A same-named block declared at two tiers cannot be disambiguated by plain name (the old shell's tier-scoped lookup disambiguation has no v2 equivalent) — address it by prefixed IRI instead. Since L-OPEN-9 NOTHING is tier/channel-aware: the hand-written, tier-chain-filtered `block list` was removed with its `tierChain.ts`.",
+      "CLOSED, by REVERSAL of the entry it used to be. This gap read: `block lookup` resolves by `ds:name` globally, a same-named block at two tiers cannot be disambiguated by plain name, address it by prefixed IRI instead. That was accepted while the answer was merely arbitrary; it stopped being acceptable once measured — 25 live block names are carried by 2–3 blocks, and EVERY one of them was answered with whichever IRI sorted first and no sign the others existed (`block lookup button` returned Launchpad's Button, because `apps_launchpad…` precedes `global…`). 'Address it by IRI' is not a recovery an agent can reach when nothing tells it there is a second block to address. Two things replace it, and neither is a change of arity — one name still answers with one entity, and a glob is still the declared multi-entity form. (1) The discard is no longer SILENT: the resolve is unlimited, the winner is answered with, and the IRIs it outranked ride the verb's `notice` — the same seam a zero-record read uses (stderr in plain mode, `meta.notice` on `--format json` and MCP), because an ambiguous hit is the same failure as an empty one, a result that misrepresents itself. `LookupOutput.ambiguous` carries them in `data` for the machine surfaces, and is ABSENT (not `[]`) when nothing was ambiguous, so every unambiguous read keeps the payload it had. Note the recovery is not reachable any other way: a glob expands over DISTINCT names, so `block lookup 'Butt*'` returned Launchpad's Button and ButtonLink and the global Button appeared nowhere. (2) The order is a declared, derived RANKING (`PackLookup.scopeWeight` in `pragma.conf.ts`, generated by `packs/sparql/buildLookupQuery.ts#rankingClause`): a tier's depth comes from the `/` count in its OWN `ds:name` (`\"Apps/Launchpad\"` → 2, never from the `_` in `ds:apps_launchpad`), and it MULTIPLIES the existing type weight rather than tiebreaking above it, so a whole component in a nested tier still outranks a global SUBcomponent (`TextInput`). Nothing is enumerated, so a tier added upstream is placed without an edit here; an asserted `ds:tierRank` would take precedence over the derived depth and retire the config declaration with no code change. WHAT REMAINS a gap: `lookup` is still not tier-SCOPED — there is no way to ask for one tier's answer only, the ranking merely decides which comes first — and since L-OPEN-9 nothing is tier/channel-FILTERED (the hand-written `block list` went with its `tierChain.ts`; see `block-list-unfiltered`). Two top-level tiers still cannot be ordered against each other by depth alone, which today leaves `Navigation` (`global` vs `apps`) and `InfoTable` (`global` vs `sites`) decided by the IRI fallback; naming a precedence among the depth-1 tiers is an ontology question, deliberately NOT invented here.",
   },
   {
     id: "block-list-unfiltered",
@@ -182,4 +182,10 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     description:
       "The native MCP `prompts/list` (and the `prompt_list`/`prompt_lookup` content tools) project `ds:Prompt` KG entities read from the ACTIVE pack index (`kernel/project/mcp/prompts/source.ts#listPromptSummaries`) — project-supplied data, NOT shipped in the embedded/bundled pack. A bare install (no project-authored `ds:Prompt`) advertises the prompts capability but lists ZERO prompts, never booting the store on the list path. Non-empty listings are exercised only against the seeded fixture graph (`testing/fixtures/graph/canonical.ts`); the storeless empty-by-default case is pinned by `prompts.test.ts` ('lists zero prompts … when no prompt entities exist').",
   },
+  {
+    id: "scope-not-band-in-machine-output",
+    area: "setup / doctor `--format json`",
+    description:
+      "A setup plan row and a doctor check carry their config scope under the key `scope` (values `global`/`project`), not `band`. The old shell's type layer said `band` (`ScopeBand`, `PlanRow.band`, `CheckResult.band`) while every user-facing string had already moved to the scope vocabulary the `--global`/`--local` flags use; the type-layer rename (kernel/render/vocabulary.ts) finished the move, and `--format json`/MCP emit the model verbatim, so the machine key moved with it. Any consumer reading `.band` off `setup --format json` or `doctor --format json` reads `.scope` now — `setup.render.test.ts` pins that neither spelling of `band` can return through any render, JSON included.",
+  },
 ] as const;

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

@@ -164,9 +164,11 @@ const READ_CASES: readonly ReadCase[] = [
   },
   { command: "pragma standard list", key: "standard list", params: {} },
   {
-    command: "pragma standard list --category react",
+    // The doc's headline example, and the one the roll-up is about: a parent
+    // category answering for its whole branch.
+    command: "pragma standard list --category testing",
     key: "standard list",
-    params: { category: ["react"] },
+    params: { category: ["testing"] },
   },
   {
     command: "pragma standard categories",

package/src/testing/behavioral/errorMatrix.mcp.test.ts

@@ -11,10 +11,16 @@
  *    a total miss; only a PARTIAL batch reports the miss while staying
  *    `ok:true` (that shape is B1's job, `agentSession.mcp.test.ts`). See
  *    PARITY_GAPS `single-lookup-miss-fails-batch-partial-reports`.
- * 2. A filtered list narrowed to zero rows is `{ok:true, data:[], meta:{}}` —
- *    there is no `meta.count` field on any read envelope (`dispatch.ts`
- *    always renders reads with `meta:{}`). See PARITY_GAPS
- *    `read-meta-always-empty`.
+ * 2. A filtered list narrowed to zero rows is `{ok:true, data:[]}` — there is
+ *    still no `meta.count` field on any read envelope, which is the divergence
+ *    `read-meta-always-empty` now records (it no longer claims `meta` is always
+ *    `{}`: a zero-record read carries the list's own `notice` as
+ *    `meta.notice` on both machine surfaces, asserted below).
+ * 3. A value-free filter given a value its vocabulary does not admit is
+ *    INVALID_INPUT, not a successful empty list — the narrowing recorded in
+ *    PARITY_GAPS `no-empty-hook-on-free-filter`. Emptiness itself is still a
+ *    success: a value the GRAPH admits but no row carries (a category with zero
+ *    standards) is a calm empty list, asserted below.
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -88,7 +94,22 @@ describe("lookup miss — total miss fails the call (B3, adapted)", () => {
   });
 });
 
-describe("list — a narrowing filter to zero rows is a plain empty list (B3, adapted)", () => {
+/**
+ * CHANGED DELIBERATELY. This used to assert that ANY filter value narrowed to a
+ * plain `{"ok":true,"data":[],"meta":{}}`, which was written when no value-free
+ * filter could tell a typo from an empty answer. It could: the rows it is
+ * filtering carry the vocabulary. Over MCP the old shape made a mistyped
+ * `--category`, an unbuilt store and a genuinely empty category byte-identical —
+ * the silence a model has no way to recover from.
+ *
+ * A value the graph does not know is now INVALID_INPUT with the admissible
+ * values as `validOptions`, exactly as a filter declaring `values` has always
+ * behaved; the difference is that the vocabulary is READ FROM THE GRAPH rather
+ * than copied into the story. Zero rows for a value that DOES exist stays a calm
+ * empty list — that is a real answer, not a bad argument — and "exists" means
+ * the graph declares it, not that some returned row happened to carry it.
+ */
+describe("list — a filter value the graph does not carry is INVALID_INPUT (B3, adapted)", () => {
   it("has at least one filtered list verb to sweep", () => {
     // A guard, not a no-op: if this ever goes empty the sweep below silently
     // covers nothing, which would be a silent coverage loss worth noticing.
@@ -97,16 +118,98 @@ describe("list — a narrowing filter to zero rows is a plain empty list (B3, ad
 
   it.each(
     filteredListVerbs,
-  )("$tool: an unmatched filter value narrows to [] (no EMPTY_RESULTS)", async ({
+  )("$tool: an unobserved filter value is rejected, naming the observed ones", async ({
     tool,
     param,
   }) => {
     const result = await mcp.callTool(tool, {
       [param]: "zzz-definitely-not-a-real-value",
     });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string; validOptions?: string[] };
+    expect(error.code).toBe("INVALID_INPUT");
+    expect(error.validOptions?.length).toBeGreaterThan(0);
+    expect(error.validOptions).not.toContain("zzz-definitely-not-a-real-value");
+  });
+
+  it.each(
+    filteredListVerbs,
+  )("$tool: every value the graph DOES carry narrows to a calm list", async ({
+    tool,
+    param,
+  }) => {
+    const rejected = await mcp.callTool(tool, { [param]: "zzz-nope" });
+    const admissible = (rejected.error as { validOptions: string[] })
+      .validOptions;
+    expect(admissible.length).toBeGreaterThan(0);
+    // EVERY admissible value is accepted, and at least one is populated. Not
+    // "the first one returns rows": the vocabulary is the graph's, so it can
+    // legitimately contain a value no row carries (a category with zero
+    // standards) — that value is a calm empty list, not a rejection, and the
+    // sweep would otherwise read a real answer as a failure.
+    let populated = 0;
+    for (const value of admissible) {
+      const result = await mcp.callTool(tool, { [param]: value });
+      expect(result.ok).toBe(true);
+      if ((result.data as unknown[]).length > 0) populated += 1;
+    }
+    expect(populated).toBeGreaterThan(0);
+  });
+
+  it("standard_list: a declared category with NO standards is a calm empty list", async () => {
+    // The case that separates "the graph is the vocabulary" from "the returned
+    // rows are the vocabulary". `standard_categories` publishes every declared
+    // slug with its count, zeros included, and tells the agent to pick one —
+    // so rejecting a zero-count slug as INVALID_INPUT tells it the slug the
+    // tool just handed it was a typo. Validity read off the rows did exactly
+    // that, because a category with no standards appears in no row.
+    const categories = await mcp.callTool("standard_categories");
+    const zero = (categories.data as { name: string; count: string }[]).filter(
+      (row) => Number(row.count) === 0,
+    );
+    expect(zero.length).toBeGreaterThan(0);
+    for (const row of zero) {
+      const result = await mcp.callTool("standard_list", {
+        category: row.name,
+      });
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
+      // And it is a real empty answer, so it carries the calm notice rather
+      // than passing in silence.
+      expect((result.meta as { notice?: string }).notice ?? "").not.toBe("");
+    }
+  });
+
+  it("standard_list: the rejection names the declared slugs, not just the used ones", async () => {
+    const result = await mcp.callTool("standard_list", {
+      category: "zzz-definitely-not-a-slug",
+    });
+    expect(result.ok).toBe(false);
+    const error = result.error as { code: string; validOptions: string[] };
+    expect(error.code).toBe("INVALID_INPUT");
+    const categories = await mcp.callTool("standard_categories");
+    const declared = (categories.data as { name: string }[]).map((r) => r.name);
+    // Same vocabulary, both surfaces: whatever `standard_categories` lists is
+    // what `--category` accepts. Read from `cs:Category`/`cs:slug` on both
+    // sides, so the two cannot drift.
+    expect([...error.validOptions].sort()).toEqual([...declared].sort());
+  });
+});
+
+describe("empty ≠ silence on the machine surfaces", () => {
+  it("carries the list's empty-state guidance in the envelope meta", async () => {
+    // `notice` had exactly one consumer — the CLI dispatcher's stderr — so
+    // an agent received `{"ok":true,"data":[],"meta":{}}` and nothing else. The
+    // search path is the honest way to reach an empty list without a bad
+    // argument.
+    const result = await mcp.callTool("standard_list", {
+      search: "zzz-nothing-matches-this",
+    });
     expect(result.ok).toBe(true);
     expect(result.data).toEqual([]);
-    expect(result.meta).toEqual({});
+    const notice = (result.meta as { notice?: string }).notice ?? "";
+    expect(notice).toContain("No standard entries found.");
+    expect(notice).toContain("pragma standard categories");
   });
 });
 

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

@@ -158,10 +158,15 @@ describe("first install — the surfaces say where the answers come from", () =>
     expect(status.entityCount).toBeGreaterThan(0);
   });
 
-  it("doctor passes, naming the embedded snapshot rather than the config", async () => {
+  it("doctor passes, saying the packs came with the CLI rather than from the config", async () => {
     const result = await checkPackageRefs(bootRuntime(JSON_FLAGS, emptyCwd()));
     expect(result.status).toBe("pass");
-    expect(result.detail).toContain("embedded snapshot @ ");
+    // What is pinned is the DISTINCTION — a fresh install reads packs it
+    // shipped with, not packs this project configured — and that the row says
+    // how to change that. The wording is the reader's ("shipped with the CLI"),
+    // not the build's ("embedded snapshot"); the per-pack revisions moved to
+    // the row's sub-items when each pack got its own line.
+    expect(result.detail).toContain("shipped with the CLI");
     expect(result.detail).toContain("pragma sources update");
   });
 });