@canonical/pragma-cli 0.36.0 → 0.38.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.37.0\",\"sourceRef\":\"@canonical/design-system@git:d65f8bacdf2a209b1b33746893c807e5370e1042, @canonical/anatomy-dsl@npm:0.6.0, @canonical/token-ontology@npm:0.10.1, @canonical/code-standards@git:fcd3ac2dea458775e5b79344b3237a3fcb37add9, @canonical/ds-implementations@self:v0.37.0\",\"contentHash\":\"e54849397af95dadd4b37e7d6ddf1d984c92ac27cac4c943db694c361feeb2c5\",\"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\":\"https://anatomy.canonical.com/\",\"dt\":\"https://dt.canonical.com/\",\"graphql\":\"https://pragma.canonical.com/graphql#\",\"w3c-tokens\":\"https://dt.canonical.com/w3c-tokens/\",\"dt-web\":\"https://dt.canonical.com/platform/web/\",\"cs\":\"http://pragma.canonical.com/codestandards#\"},\"createdAt\":\"2026-09-16T10:11:25.934Z\",\"tripleCount\":65298,\"entityCount\":4377}";

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

@@ -39,7 +39,8 @@ function packUnavailable(reason: string): PragmaError {
  * Read a pack directory into a bootable store session.
  *
  * @param dir - The pack directory (must hold a complete pack).
- * @returns The store session: store, schema, context factory, prefixes, index.
+ * @returns The store session: store, schema, context factory, prefixes, index,
+ *   and the pack's own manifest (its provenance, carried rather than re-read).
  * @throws PragmaError STORE_UNAVAILABLE when the pack is incomplete.
  * @note Impure — creates a store from the cached n-quads dump.
  */
@@ -80,15 +81,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.`);
   }
@@ -99,13 +110,6 @@ export async function readPack(dir: string): Promise<StoreSession> {
     createContext: compiled.createContext,
     prefixes: manifest.prefixes,
     index,
+    manifest,
   };
 }
-
-/** 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/readEntity.ts

@@ -82,8 +82,13 @@ type Term = import("@canonical/ke").Term;
  * Membership edges behave identically — this graph's `ds:tier` fans in 141 deep
  * — and a rule keyed on `rdf:type` would have left a `detailed` read of one tier
  * at 20.9 KB while congratulating itself on having fixed classes.
+ *
+ * EXPORTED because it has a second consumer: `graph connect` decides which
+ * edges it may WALK by the same rule this reader decides what to list. One
+ * constant with two consumers, never two constants that agree today — a copied
+ * `20` would let the traversal drift from the doctrine it claims to obey.
  */
-const ROSTER_THRESHOLD = 20;
+export const ROSTER_THRESHOLD = 20;
 
 /** How many subjects each level lists for a genuine ANSWER (fan-in ≤ threshold). */
 const ANSWER_CAP: Readonly<Record<DetailLevel, number>> = {
@@ -254,16 +259,26 @@ export interface InspectResult {
  * word twice. A graph whose labels are real prose (a concept at `ds:concept.pd`
  * named "Progressive disclosure") still keeps them, so this thins noise without
  * deciding that labels are worthless.
+ *
+ * Exported beside {@link nameIndex}: the two are ONE rule for naming a
+ * neighbour, and a consumer that took the map without the filter would print
+ * exactly the noise this function exists to drop.
  */
-function isInformativeName(name: string, short: string): boolean {
+export function isInformativeName(name: string, short: string): boolean {
   const normalize = (value: string): string =>
     value.replace(/[\s._:-]/g, "").toLowerCase();
   const local = short.split(/[:.]/).pop() ?? short;
   return normalize(name) !== normalize(local);
 }
 
-/** Index lookup for a neighbour's human name (`label`, else the first alt name). */
-function nameIndex(index: PackIndex): ReadonlyMap<string, string> {
+/**
+ * Index lookup for a neighbour's human name (`label`, else the first alt name).
+ *
+ * EXPORTED for the same reason as {@link ROSTER_THRESHOLD}: `graph connect`
+ * names the nodes on a path, and it must name them the way this reader does or
+ * the same neighbour reads differently depending on which verb showed it.
+ */
+export function nameIndex(index: PackIndex): ReadonlyMap<string, string> {
   const names = new Map<string, string>();
   for (const entity of index.entities) {
     if (!entity.uri) continue;

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

@@ -184,6 +184,34 @@ function readStorySources(
  */
 const PREFIX_DECL = /(?:^|\s)@?prefix\s+([^\s:]+):\s*<([^>]*)>/gi;
 
+/**
+ * Blank out every Turtle string literal, so a prefix scan reads declarations
+ * and not prose.
+ *
+ * A long literal can legally contain the text `@prefix ex: <iri> .`, and one
+ * genuinely does: the code-standards pack ships guidance ABOUT Turtle, whose
+ * `cs:code` examples include a deliberately discouraged declaration. Scanning
+ * raw text saw it as real, which made `sources update` report a `ds:` clash on
+ * every run for a file that asserts no `ds:` triple at all — and worse, let a
+ * code sample win the last-wins race in {@link harvestPrefixes} and rebind a
+ * real prefix.
+ *
+ * Long forms are blanked before short ones, so the `"""` delimiters are not
+ * mistaken for an empty `""` followed by prose. Newlines inside a literal are
+ * preserved so a later `^`-anchored match still sees the true line structure.
+ *
+ * @param content - Turtle source text.
+ * @returns The same text with literal contents replaced by blanks.
+ */
+function blankLiterals(content: string): string {
+  const keepNewlines = (text: string): string => text.replace(/[^\n]/g, " ");
+  return content
+    .replace(/"""[\s\S]*?"""/g, keepNewlines)
+    .replace(/'''[\s\S]*?'''/g, keepNewlines)
+    .replace(/"(?:[^"\\\n]|\\.)*"/g, keepNewlines)
+    .replace(/'(?:[^'\\\n]|\\.)*'/g, keepNewlines);
+}
+
 /**
  * Harvest a package's own `@prefix` / `PREFIX` declarations from its TTL text.
  *
@@ -201,7 +229,7 @@ export function harvestPrefixes(
 ): Record<string, string> {
   const prefixes: Record<string, string> = {};
   for (const { content } of sources) {
-    for (const match of content.matchAll(PREFIX_DECL)) {
+    for (const match of blankLiterals(content).matchAll(PREFIX_DECL)) {
       const [, label, iri] = match;
       if (label !== undefined && iri !== undefined) prefixes[label] = iri;
     }
@@ -234,7 +262,7 @@ export function detectPrefixClashes(
 ): PrefixClash[] {
   const byLabel = new Map<string, string[]>();
   for (const { content } of sources) {
-    for (const match of content.matchAll(PREFIX_DECL)) {
+    for (const match of blankLiterals(content).matchAll(PREFIX_DECL)) {
       const [, label, iri] = match;
       if (label === undefined || iri === undefined) continue;
       const iris = byLabel.get(label) ?? [];
@@ -383,13 +411,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";
 
@@ -53,6 +54,19 @@ export interface StoreSession {
   readonly prefixes: Readonly<Record<string, string>>;
   /** The storeless entity index shipped with the pack. */
   readonly index: import("./graphpack/types.js").PackIndex;
+  /**
+   * The provenance of the pack this session was booted from — the parsed
+   * `manifest.json` the boot ALREADY read to get {@link prefixes}.
+   *
+   * Carried rather than re-read because an answer that depends on WHICH packs
+   * were searched has to be able to say so from the session it was answered
+   * from. `graph connect`'s most common answer is "these two are not
+   * connected", and a missing pack makes the honest and the dishonest form of
+   * that answer byte-identical — so the answer names `sourceRef`, and it must
+   * be the loaded session's, not one re-resolved from config a caller could
+   * have changed since.
+   */
+  readonly manifest: import("./graphpack/types.js").Manifest;
 }
 
 /**
@@ -221,4 +235,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

@@ -556,7 +556,7 @@ const CONFIG_FIELD_DOCS: Record<keyof RawConfig, ConfigFieldDoc> = {
   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>` and clear it with `config unset tier`; `none`, `default` and `-` are refused as values, so no string doubles as a remove-marker.",
+      "The DEFAULT TIER SCOPE for every read of a tiered entity (blocks, modifier families, concepts): reads answer from this tier and its ancestors — `apps_lxd` reads `global`, `apps` and `apps_lxd`. Unset, they answer from the top-level tiers; set to `all`, from every tier. A per-call `--tier <name>` (the `tier` tool parameter) replaces it for that call, and every scoped answer states the scope it used. Name a tier the way `tier list` or a `Tier` column spells it (`apps_lxd`, `Apps/LXD` and `apps/lxd` all resolve); an unknown name is an `INVALID_INPUT` listing the tiers that exist. Set it with `config set tier <name>` and clear it with `config unset tier`; `none`, `default` and `-` are refused as values, so no string doubles as a remove-marker.",
   },
   channel: {
     type: "`normal` | `experimental` | `prerelease` (optional)",

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

@@ -84,8 +84,8 @@ describe("surface conformance (PROTECTED)", () => {
     );
   });
 
-  it("freezes exactly 42 designed MCP tools including info, the config family, colophon", () => {
-    expect(golden.mcpSurface.tools).toHaveLength(42);
+  it("freezes exactly 49 designed MCP tools including info, the config family, colophon", () => {
+    expect(golden.mcpSurface.tools).toHaveLength(49);
     expect(golden.mcpSurface.tools).toContain("info");
     expect(golden.mcpSurface.tools).toContain("config_show");
     expect(golden.mcpSurface.tools).toContain("config_get");

package/src/kernel/spec/types.ts

@@ -192,6 +192,23 @@ export interface Formatters<T> {
   readonly llm: (d: T) => string;
   readonly json: (d: T) => string;
   readonly notice?: (d: T) => string | undefined;
+  /**
+   * The MACHINE half of the notice seam: facts about the read that belong in
+   * the envelope's `meta` as DATA, merged there by both projectors under the
+   * keys this returns.
+   *
+   * `notice` is a sentence, and a sentence is the right shape for a human
+   * reading stderr and the wrong shape for an agent deciding what to do next.
+   * The standing case is the tier scope: `meta.scope` names the tiers a list
+   * answered from, so a caller that wants the rest can widen the read without
+   * parsing prose for tier names. Both machine surfaces read this ONE seam, the
+   * way they already read one `notice`, so CLI-JSON and MCP stay byte-equal.
+   *
+   * Plain and llm ignore it — they carry the same facts in their own register
+   * (the notice on stderr, the heading in the condensed form). Return
+   * `undefined` (or omit the member) when the read has nothing to add.
+   */
+  readonly meta?: (d: T) => Record<string, unknown> | undefined;
 }
 
 /** A usage example shown in verb help. */

package/src/testing/PARITY_GAPS.ts

@@ -48,7 +48,7 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "no-empty-hook-on-free-filter",
     area: "pack list / empty-state",
     description:
-      "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.",
+      "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/filterValues.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,13 +84,13 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "block-lookup-not-tier-scoped",
     area: "block",
     description:
-      "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.",
+      "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 USED TO REMAIN, now closed: `lookup` was not tier-SCOPED — the ranking decided which answer came first, and there was no way to ask for one tier's answer only. The TIER SCOPE is that ask: `block lookup button` answers with the global Button alone under the default scope, `--tier apps_launchpad` answers with Launchpad's, `--tier all` answers with both (the ranking still orders whatever the scope admits, so the two rules compose rather than compete). A name whose every match is out of scope is still ANSWERED, from the tiers it does live in, with one line saying so — a scope decides which of several blocks a name means, never whether the block exists. `config.channel` is still not a filter. 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",
     area: "block",
     description:
-      "L-OPEN-9 (owner-signed): `block list` is the block story's compiled, UNFILTERED list — it shows every block, including experimental/alpha ones, for everyone, until filtering returns in declared form. The old tier-chain inheritance, channel visibility, and `--all-tiers` escape were hand-written filtering the pack grammar has no term for, and the ruling removed them rather than growing the grammar to keep them. `config.tier` consequently scopes nothing (reported by `config show`/`info` only); `config.channel` keeps only its npm dist-tag role for `upgrade`/`info`.",
+      "HALF CLOSED, and the half that closed is the tier. This gap read: `block list` is the block story's compiled, UNFILTERED list — every block, experimental ones included, for everyone, until filtering returns in declared form; the old tier-chain inheritance, channel visibility and `--all-tiers` escape were hand-written filtering the pack grammar had no term for, and the ruling removed them rather than grow the grammar to keep them. Filtering has now returned for the TIER, and in declared form: the `block` story declares its tier hierarchy (`PackDefinition.tierScope`) and the kernel compiles a scope into the same query the filters ride, so the list answers from the top-level tiers by default, from a chosen tier plus its ancestors with `--tier <name>`, and from every tier with `--tier all` (which is this entry's old behaviour, on request). `config.tier` is what sets that default — no longer inert, and `config show` reports the scope it puts reads under. An UNTIERED block stays visible under every scope (A2 — `ds:button.icon`), because an entity the scope cannot place is not one it may hide. WHAT REMAINS: `config.channel` still scopes nothing and keeps only its npm dist-tag role for `upgrade`/`info`, so an experimental block is still visible to everyone in whatever tier it sits.",
   },
   {
     id: "graph-query-deferred",
@@ -120,7 +120,7 @@ export const PARITY_GAPS: readonly ParityGapEntry[] = [
     id: "config-tier-no-ontology-validation",
     area: "config setters",
     description:
-      "The covenant `config_tier` has no `needsStore`, so it is storeless — the old store-backed `validateTier` (which queried the ontology for valid tier paths) is DROPPED. `config tier <anything>` writes the value verbatim; an unknown tier simply yields empty scoped reads later. `config/fields.ts`.",
+      "`config set tier <anything>` is STORELESS and writes the value verbatim: the old store-backed `validateTier` (which queried the ontology for valid tier paths) is dropped, and the covenant's `config_set` declares no `needsStore` to bring it back. What changed with the tier scope is the CONSEQUENCE of a bad value — it used to yield nothing at all (the key scoped nothing), and it is now refused at the first tiered READ, with an INVALID_INPUT naming the tiers the pack does carry and a `config unset tier` recovery. Validation at the read rather than at the write is deliberate: the write has no store, and the pack a value is valid against can change under a machine that set it months ago. `config/fields.ts`, `kernel/packs/tierScope.ts`.",
   },
   {
     id: "doctor-exit-zero-with-failures",