@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/kernel/completion/entitySource.ts

@@ -4,46 +4,59 @@
  * browser (`info`, `doctor`, MCP prompts, the resource provider) shares.
  *
  * {@link indexCompletionEnv} is the one source-dispatched reader wired at the
- * `__complete` fast path (bin) and the `__complete` verb. It resolves five
+ * `__complete` fast path (bin) and the `__complete` verb. It resolves three
  * storeless sources — all disk-readable, never a store/SPARQL:
- * - `index`    → the active pack's `index.json` entity names of a prefixed type.
+ * - `index`    → the active pack's `index.json`, filtered by a prefixed `type`
+ *                and read from the declared `field` (`name` by default).
  * - `skills`   → SKILL.md names via {@link discoverSkills} (filesystem walk).
- * - `prompts`  → the pack index's `ds:Prompt` entities (`label || name`).
- * - `tiers`    → the pack index's `ds:Tier` entities (their `ds:name`, else
- *                `label ?? name` when the index carries no `ds:name`).
  * - `prefixes` → the pack index's prefixes ∪ the default display prefixes.
  *
+ * There is no per-family source. An entity family IS a `type` filter plus the
+ * field that family is addressed by, and both are declared at the verb, so this
+ * module names no entity type at all.
+ *
  * The index is loaded once (lazy `readFileSync` + plain `JSON.parse` — never a
  * store, facade, config evaluator, or zod schema; any I/O or parse error
- * degrades to `[]`) and shared across the index/prompts/tiers/prefixes sources;
+ * degrades to `[]`) and shared across the index and prefixes sources;
  * the skills walk is memoized to one walk per `__complete` process.
  * {@link createIndexEntityReader} exposes the index read for the storeless
  * behavioural/safety tests; {@link emptyNameSource} is the default (no names).
  *
  * {@link readPackIndex} and {@link entityTotal} expose the same storeless read
- * to `info`/`doctor` and the resource surfaces. Everything here relies only on
- * the FROZEN `{ name, type }` index minimum (plus optional enrichment like
- * `label`/`altNames`), so the index can grow without breaking completion.
+ * to `info`/`doctor` and the resource surfaces — but those callers are NOT on
+ * the fast path, so `readPackIndex` takes the boot decision rather than
+ * re-deriving one. Everything here relies only on the FROZEN `{ name, type }`
+ * index minimum (plus optional enrichment like `label`/`altNames`), so the
+ * index can grow without breaking completion.
  *
  * Storeless-graph notes:
  * - The embedded fallback is read from `pack.index.generated` — its OWN
  *   generated module (only the index string) — so the storeless `__complete`
- *   path never pulls the n-quads/schema/manifest strings that live in
- *   `pack.generated`.
- * - The pack-cache path is INLINED here rather than imported from
- *   `kernel/runtime/paths` — that module reaches `kernel/config`, which the
- *   storeless-guarantee test (`safety.test.ts`) forbids on the completion
- *   import graph. The two lines of XDG resolution are duplicated on purpose to
- *   keep the fast path free of the config layer; `PackIndex`/`PackIndexEntity`
- *   are imported type-only, so no zod schema is loaded at runtime.
- * - `discoverSkills` (`node:fs/os/path` only) and `DEFAULT_PREFIX_MAP` (a pure
- *   const) are the only new edges — both leaf-clean, so the fast path stays free
- *   of boot/config/store/zod. The `ds:Prompt`/`ds:Tier` filters are INLINED
- *   (importing `prompts/source.ts` would cycle back into this module).
+ *   path never EVALUATES the n-quads/schema/manifest strings that live in
+ *   `pack.generated`. It does not avoid parsing them: `bun build --compile`
+ *   emits one script, so the whole embed is parsed at process start on every
+ *   invocation (~+25 ms here, measured on `--version` against a toy-embed
+ *   binary; BUDGETS.md records it). What the split buys is that a completion
+ *   never allocates the 1.87 MB.
+ * - The active pack is resolved through `kernel/runtime/paths` — a LEAF module
+ *   (node builtins only) that shares the pointer read with `resolveSources`.
+ *   `resolveSources` itself is unreachable from here: it pulls the graphpack
+ *   manifest schema (zod), which `safety.test.ts` forbids on this graph, and
+ *   `origins.packs` needs the config evaluator. So {@link loadActiveIndex}
+ *   implements only the POINTER half of the decision table — pointer → that
+ *   pack (else nothing), no pointer → the embedded snapshot. It cannot tell a
+ *   fresh install from a project that declared its own packs and never built
+ *   them, so a `__complete` in the latter still offers the snapshot's names.
+ *   That is the price of a config-free fast path, and it is bounded to
+ *   completion candidates: every read, and every surface that takes the
+ *   decision, refuses. `PackIndex`/`PackIndexEntity` are imported type-only, so
+ *   no zod schema is loaded at runtime.
+ * - `discoverSkills` (`node:fs/os/path` only) and `DEFAULT_PREFIX_MAP` (whose
+ *   domain half the distribution declares) are the only new edges — both
+ *   leaf-clean, so the fast path stays free of boot/config/store/zod.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { discoverSkills } from "../../capabilities/skill/discover.js";
 // Inlined embedded index — its OWN generated module (only the index string), so
@@ -52,91 +65,97 @@ import { discoverSkills } from "../../capabilities/skill/discover.js";
 import { DEFAULT_PREFIX_MAP } from "../render/prefixes.js";
 import { indexJson as EMBEDDED_INDEX_JSON } from "../runtime/graphpack/embedded/pack.index.generated.js";
 import type { PackIndex, PackIndexEntity } from "../runtime/graphpack/types.js";
-import type { CompletionSourceRef } from "../spec/types.js";
+import { packDir, readActivePack } from "../runtime/paths.js";
+import type { SourcesDecision } from "../runtime/resolveSources.js";
+import type { CompletionField, CompletionSourceRef } from "../spec/types.js";
 import type { CompletionEnv } from "./types.js";
 
-/** The prefixed KG type every prompt entity carries (inlined; no cycle). */
-const PROMPT_TYPE = "ds:Prompt";
-/** The prefixed KG type every tier entity carries (inlined; no cycle). */
-const TIER_TYPE = "ds:Tier";
-
 /** The default name source: no index tier, so no candidates. */
 export const emptyNameSource: CompletionEnv["names"] = () => [];
 
-/** The committed project lock basename (mirrors `kernel/runtime/paths`). */
-const LOCK_BASENAME = "pragma.lock.json";
 /** The pack index filename (kept local so this path never imports the zod schema). */
 const INDEX_FILE = "index.json";
 
 /**
- * `$XDG_CACHE_HOME/pragma/packs/<hash>` — a pack's cache directory.
+ * Read the storeless index of the pack the BOOT DECISION names — for `info`,
+ * `doctor`, the MCP resource browser, and native `prompts/list`. Never boots the
+ * store, never validates with zod — a plain `JSON.parse` off disk.
  *
- * Inlined from `kernel/config/paths` + `kernel/runtime/paths` so the completion
- * fast path stays off the config layer (see the module docblock).
- */
-function packDir(contentHash: string): string {
-  const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
-  return join(base, "pragma", "packs", contentHash);
-}
-
-/** The committed project lock file for a working directory. */
-function lockPath(cwd: string): string {
-  return join(cwd, LOCK_BASENAME);
-}
-
-/**
- * Read the active pack's storeless index (the locked pack, else the embedded
- * fallback), for the resource browser's list/autocomplete. Never boots the
- * store, never validates with zod — a plain `JSON.parse` off disk. Returns
- * `undefined` when no index is reachable, so callers degrade to a recovery hint.
+ * It takes the decision rather than re-deriving one so these surfaces cannot
+ * list entities the same project's reads refuse: `unavailable` yields
+ * `undefined`, and callers degrade to a recovery hint (`buildResourceList`
+ * emits the `pragma:sources` entry, `info` omits the total).
  *
- * @param cwd - The project directory (to resolve the active pack).
- * @returns The active pack index, or `undefined` when none is reachable.
+ * @param decision - The boot decision from `resolveSources`.
+ * @returns The answering pack's index, or `undefined` when none answers.
  */
-export function readPackIndex(cwd: string): PackIndex | undefined {
-  return loadActiveIndex(cwd);
+export function readPackIndex(
+  decision: SourcesDecision,
+): PackIndex | undefined {
+  switch (decision.kind) {
+    case "pack":
+      return readIndexFile(decision.dir);
+    case "embedded":
+      return parseIndex(EMBEDDED_INDEX_JSON);
+    case "unavailable":
+      return undefined;
+  }
 }
 
 /**
- * Sum a pack index's per-type instance counts — the "total entities" figure
+ * Count a pack index's DISTINCT abox subjects — the "total entities" figure
  * `info` and `doctor` report. Works over any {@link PackIndex}, whether read
  * storelessly via {@link readPackIndex} or taken from a booted store session.
  *
+ * NOT a sum of `instanceCountByType`: on a real OWL/Protégé export that raw
+ * multiset double-counts — every individual is typed as both its domain class
+ * AND `owl:NamedIndividual`, and the `owl:Class`/property meta-buckets pile on
+ * top — so the total ran ~2× the real entity count (A1). Counting distinct
+ * abox subjects (the individuals, each once) is the figure users expect; the
+ * tbox schema classes/properties are not "entities" in this count.
+ *
  * @param index - A pack index.
- * @returns The total number of indexed entity instances across every type.
+ * @returns The number of distinct abox subjects indexed.
  */
 export function entityTotal(index: PackIndex): number {
-  return Object.values(index.instanceCountByType).reduce(
-    (sum, n) => sum + n,
-    0,
-  );
+  const subjects = new Set<string>();
+  for (const entity of index.entities) {
+    if (entity.box === "abox") subjects.add(entity.uri ?? entity.name);
+  }
+  return subjects.size;
 }
 
-/** Load the active pack's index: the locked pack, else the embedded fallback. */
-function loadActiveIndex(cwd: string): PackIndex | undefined {
+/** Parse an index JSON string; any malformed input degrades to `undefined`. */
+function parseIndex(json: string): PackIndex | undefined {
   try {
-    const path = lockPath(cwd);
-    if (existsSync(path)) {
-      const lock = JSON.parse(readFileSync(path, "utf-8")) as {
-        contentHash?: unknown;
-      };
-      if (typeof lock.contentHash === "string") {
-        const indexPath = join(packDir(lock.contentHash), INDEX_FILE);
-        if (existsSync(indexPath)) {
-          return JSON.parse(readFileSync(indexPath, "utf-8")) as PackIndex;
-        }
-      }
-    }
+    return JSON.parse(json) as PackIndex;
   } catch {
-    // Fall through to the embedded fallback on any read/parse failure.
+    return undefined;
   }
+}
+
+/** Read a pack directory's `index.json`; any I/O or parse error is `undefined`. */
+function readIndexFile(dir: string): PackIndex | undefined {
   try {
-    return JSON.parse(EMBEDDED_INDEX_JSON) as PackIndex;
+    return parseIndex(readFileSync(join(dir, INDEX_FILE), "utf-8"));
   } catch {
     return undefined;
   }
 }
 
+/**
+ * The fast path's index — the POINTER half of the decision table (see the module
+ * docblock). A project with a pointer reads that pack and nothing else: a
+ * pointer whose pack the cache lost yields no candidates rather than the
+ * snapshot's, which is what the boot decision does with the same state.
+ */
+function loadActiveIndex(cwd: string): PackIndex | undefined {
+  const contentHash = readActivePack(cwd);
+  return contentHash === undefined
+    ? parseIndex(EMBEDDED_INDEX_JSON)
+    : readIndexFile(packDir(contentHash));
+}
+
 /** Whether an entity matches a prefixed type filter (primary type or any type). */
 function matchesType(entity: PackIndexEntity, type: string): boolean {
   if (!type) return true;
@@ -172,42 +191,45 @@ export function createIndexEntityReader(
   };
 }
 
-/** All names of a prefixed type in the index (empty type = any), sorted. */
-function indexNames(index: PackIndex | undefined, type: string): string[] {
-  if (!index) return [];
-  const names = new Set<string>();
-  for (const entity of index.entities) {
-    if (matchesType(entity, type)) names.add(entity.name);
-  }
-  return [...names].sort();
-}
-
-/** The `ds:Prompt` entities' completable names (`label || name`), sorted. */
-function promptNames(index: PackIndex | undefined): string[] {
-  if (!index) return [];
-  const names = new Set<string>();
-  for (const entity of index.entities) {
-    if (matchesType(entity, PROMPT_TYPE))
-      names.add(entity.label || entity.name);
+/**
+ * One entity's completable tokens for a declared field, with NO fallback.
+ *
+ * A verb declares the field because that is the one its lookup matches on, so
+ * an entity the pack did not enrich contributes nothing. Standing a label in
+ * for an absent alt name would offer a token the lookup provably cannot resolve
+ * — a completion that hands the user a value and then refuses it — which is the
+ * complete-but-cannot-resolve split this whole declaration exists to close.
+ * Offering nothing for an under-enriched entity is the honest answer.
+ *
+ * @param entity - One index entity.
+ * @param field - The declared field to read.
+ * @returns The tokens that entity contributes; empty when it carries none.
+ */
+function readEntityNames(
+  entity: PackIndexEntity,
+  field: CompletionField,
+): readonly string[] {
+  switch (field) {
+    case "name":
+      return [entity.name];
+    case "label":
+      return entity.label ? [entity.label] : [];
+    case "altNames":
+      return entity.altNames ?? [];
   }
-  return [...names].sort();
 }
 
-/**
- * The `ds:Tier` entities' completable names, sorted. `tier lookup` matches
- * `ds:name`, so when the index carries it (projected by `buildIndex` into
- * `altNames`) those are emitted exactly; a pack whose tiers were indexed without
- * `ds:name` falls back to `label ?? name` (empty rather than wrong).
- */
-function tierNames(index: PackIndex | undefined): string[] {
+/** A ref's candidates: entities of its type, read from its field, sorted. */
+function indexNames(
+  index: PackIndex | undefined,
+  ref: CompletionSourceRef,
+): string[] {
   if (!index) return [];
   const names = new Set<string>();
   for (const entity of index.entities) {
-    if (!matchesType(entity, TIER_TYPE)) continue;
-    if (entity.altNames && entity.altNames.length > 0) {
-      for (const alt of entity.altNames) names.add(alt);
-    } else {
-      names.add(entity.label || entity.name);
+    if (!matchesType(entity, ref.type ?? "")) continue;
+    for (const name of readEntityNames(entity, ref.field ?? "name")) {
+      names.add(name);
     }
   }
   return [...names].sort();
@@ -227,8 +249,8 @@ function prefixNames(index: PackIndex | undefined): string[] {
  * reader every name family shares. Wired at the `__complete` fast path (bin) and
  * the `__complete` verb; storeless throughout (see the module docblock).
  *
- * The pack index is loaded once, lazily, and reused across the index/prompts/
- * tiers/prefixes sources; the skills filesystem walk is memoized to one walk per
+ * The pack index is loaded once, lazily, and reused across the index and
+ * prefixes sources; the skills filesystem walk is memoized to one walk per
  * process (the design's perf caveat). Every source returns the FULL candidate
  * list in canonical casing — the resolver ranks/filters against the partial.
  *
@@ -254,13 +276,9 @@ export function indexCompletionEnv(cwd: string): CompletionEnv {
     names(ref: CompletionSourceRef): readonly string[] {
       switch (ref.from) {
         case "index":
-          return indexNames(getIndex(), ref.type ?? "");
+          return indexNames(getIndex(), ref);
         case "skills":
           return getSkills();
-        case "prompts":
-          return promptNames(getIndex());
-        case "tiers":
-          return tierNames(getIndex());
         case "prefixes":
           return prefixNames(getIndex());
       }

package/src/kernel/completion/model.test.ts

@@ -236,7 +236,7 @@ describe("buildCompletionModel — flags and sources", () => {
             positional: true,
             complete: {
               kind: "names",
-              source: { from: "tiers" },
+              source: { from: "index", type: "ex:Tier", field: "altNames" },
               enabled: false,
             },
           },
@@ -264,13 +264,13 @@ describe("buildCompletionModel — flags and sources", () => {
     const flags = Object.fromEntries(model.globalFlags.map((f) => [f.flag, f]));
     expect(flags["--format"]?.source).toEqual({
       kind: "values",
-      values: ["plain", "json"],
+      values: ["plain", "llm", "json"],
     });
     expect(flags["--detail"]?.source).toEqual({
       kind: "values",
       values: ["summary", "standard", "detailed"],
     });
-    expect(flags["--llm"]?.takesValue).toBe(false);
+    expect(flags["--llm"]).toBeUndefined();
     expect(flags["--version"]?.rootOnly).toBe(true);
     expect(flags["--help"]?.rootOnly).toBeUndefined();
   });

package/src/kernel/completion/model.ts

@@ -40,6 +40,17 @@ import type {
  * The allowlist every inlined completion token must match: an alphanumeric
  * head, then word/URI-ish characters. No whitespace, quotes, `$`, backticks,
  * semicolons, or globs — nothing a shell could expand or split.
+ *
+ * KNOWN GAP, deliberately not closed: it admits shell RESERVED WORDS — `esac`,
+ * `in`, `do`, `done`, `fi`. A noun so named emits a `case` arm bash and zsh both
+ * refuse to parse, so `_pragma` is never defined and the user gets NO completion
+ * at all rather than a wrong candidate (`fish -n` does not catch it either). The
+ * gap is owned by the syntax gates, not by this regex: `shellDrive.test.ts`
+ * runs `bash -n`/`zsh -n` over the emitted scripts, so the day a live noun is
+ * named `done` the build fails loudly and names the file. A denylist here would
+ * be new production code guarding a case nothing in the tree exhibits — and a
+ * partial one (reserved words differ across families and versions) reads as
+ * more protection than it gives.
  */
 export const SAFE_TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9@/:._+-]*$/;
 
@@ -61,7 +72,6 @@ export function assertSafeToken(token: string, where: string): void {
 
 /** The global flags completion offers, mirroring the surface's globalFlags. */
 const GLOBAL_FLAGS: readonly FlagEntry[] = [
-  { flag: "--llm", takesValue: false, repeatable: false, source: none() },
   {
     flag: "--format",
     takesValue: true,

package/src/kernel/completion/parse.test.ts

@@ -73,7 +73,7 @@ describe("parseWords — nouns and verbs (PROTECTED)", () => {
       context: { kind: "noun" },
       partial: "blo",
     });
-    expect(parse(["--llm", "block", ""]).context).toEqual({
+    expect(parse(["--verbose", "block", ""]).context).toEqual({
       kind: "verb",
       noun: "block",
     });
@@ -83,7 +83,6 @@ describe("parseWords — nouns and verbs (PROTECTED)", () => {
 describe("parseWords — flag names (PROTECTED)", () => {
   it("offers only globals (with --version) at the root", () => {
     expect(flagsOf(parse(["--"]).context)).toEqual([
-      "--llm",
       "--format",
       "--verbose",
       "--detail",
@@ -105,7 +104,6 @@ describe("parseWords — flag names (PROTECTED)", () => {
       "--out",
       "--with-meta",
       "--note",
-      "--llm",
       "--format",
       "--verbose",
       "--detail",
@@ -192,7 +190,7 @@ describe("parseWords — flag values (PROTECTED)", () => {
       context: {
         kind: "flag-value",
         flag: "--format",
-        source: { kind: "values", values: ["plain", "json"] },
+        source: { kind: "values", values: ["plain", "llm", "json"] },
       },
     });
     expect(parse(["block", "get", "--detail", "s"])).toMatchObject({

package/src/kernel/completion/safety.test.ts

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createStore } from "@canonical/ke";
 import { describe, expect, it, vi } from "vitest";
@@ -207,6 +207,8 @@ function staticImportGraph(
 }
 
 const here = dirname(fileURLToPath(import.meta.url));
+/** The package root, so a failure names `src/…` instead of an absolute path. */
+const pkgRoot = resolve(here, "../../..");
 const has = (graph: Set<string>, fragment: string): boolean =>
   [...graph].some((file) => file.includes(fragment));
 
@@ -224,16 +226,25 @@ describe("storeless guarantee (PROTECTED)", () => {
       // Runtime boot (bootRuntime) — never on the completion path.
       expect(has(graph, "kernel/runtime/boot.ts")).toBe(false);
       // The config LAYER (reader, evaluator, paths, schema) — storeless means
-      // no read. PR2's pure-leaf `config/types.ts` (the ConfigLayers type,
-      // imported type-only via VerbSpec.run's PragmaRuntime and erased at
-      // runtime) is the lone tolerated seam — as spec/types.ts and
-      // runtime/types.ts already sit in this graph as type-only.
-      const configModules = [...graph].filter(
-        (file) =>
-          file.includes("kernel/config/") &&
-          !file.endsWith("kernel/config/types.ts"),
-      );
-      expect(configModules).toEqual([]);
+      // no read. Its tolerated seams are POSITIVE-LISTED, not filtered out by a
+      // path fragment: the distribution config sits at the package root, so a
+      // `kernel/config/`-shaped filter would not see it and this guard would
+      // keep passing after it stopped being true.
+      //  - `kernel/config/types.ts` — the ConfigLayers type, imported type-only
+      //    via VerbSpec.run's PragmaRuntime and erased at runtime, as
+      //    spec/types.ts and runtime/types.ts already are in this graph.
+      //  - `pragma.conf.ts` — the distribution config, statically imported by
+      //    `constants.ts` (identity), `render/prefixes.ts` (the domain
+      //    namespaces) and `kernel/vocabulary.ts` (the domain terms). Safe only
+      //    while it stays inert data; `capabilities/lazy.test.ts` pins that.
+      const configModules = [...graph]
+        .filter((file) => /config|\.conf\./.test(file))
+        .map((file) => relative(pkgRoot, file))
+        .sort();
+      expect(configModules).toEqual([
+        "pragma.conf.ts",
+        "src/kernel/config/types.ts",
+      ]);
       // zod stays off the fast path (validate.ts is the registration seam).
       expect(has(graph, "kernel/spec/validate.ts")).toBe(false);
       // No store/graph modules, present or future.
@@ -266,7 +277,7 @@ describe("storeless guarantee (PROTECTED)", () => {
               required: true,
               complete: {
                 kind: "names",
-                source: { from: "index", type: "ex:Component" },
+                source: { from: "index", type: "ds:Component" },
               },
             },
           ],
@@ -286,23 +297,23 @@ describe("storeless guarantee (PROTECTED)", () => {
         } as VerbSpec,
       ],
     };
-    // Fresh cwd → no lock → the reader falls back to the embedded pack index.
+    // Fresh cwd → no pointer → the reader falls back to the embedded index.
     const cwd = mkdtempSync(join(tmpdir(), "pragma-storespy-"));
     const matches = await runComplete(
-      ["block", "lookup", "ex:B"],
+      ["block", "lookup", "ds:global.component.but"],
       [lookupModule],
       indexCompletionEnv(cwd),
     );
     // It DID read the index (a real name came back)…
-    expect(matches).toEqual(["ex:Button"]);
+    expect(matches).toContain("ds:global.component.button");
     // …and it did so without ever constructing the store.
     expect(vi.mocked(createStore)).not.toHaveBeenCalled();
   });
 
-  it("the non-index name sources resolve without constructing the store", async () => {
-    // skills (filesystem), prompts/tiers (index filter), prefixes (index ∪
-    // default map) — every family completes storelessly against the live
-    // capabilities. A fresh cwd → no lock → the embedded fallback index.
+  it("every declared name source resolves without constructing the store", async () => {
+    // skills (filesystem), prefixes (index ∪ default map) and the index's own
+    // `label`/`altNames` fields — every family completes storelessly against
+    // the live capabilities. A fresh cwd → no pointer → the embedded index.
     const cwd = mkdtempSync(join(tmpdir(), "pragma-storeless-src-"));
     const env = indexCompletionEnv(cwd);
 
@@ -311,16 +322,23 @@ describe("storeless guarantee (PROTECTED)", () => {
       runComplete(["ontology", "show", "d"], capabilities, env),
     ).resolves.toContain("ds");
 
-    // skills / prompts / tiers: no data here, but the point is they never boot
-    // the store — an empty list is the correct storeless answer.
+    // index (derived, no field): the tier lookup is a declared pack lookup
+    // (L-OPEN-9), so its candidates are the index's entity NAMES for the
+    // declared type — prefixed IRIs, like every other declared lookup's
+    // (D9-A). `ds:apps` is a real `ds:Tier` subject in the embedded index,
+    // and the lookup resolves a prefixed-IRI candidate directly.
+    await expect(
+      runComplete(["tier", "lookup", "ap"], capabilities, env),
+    ).resolves.toContain("ds:apps");
+
+    // skills (no skills root here) and prompt labels (this graph carries no
+    // prompt entities) have nothing to offer, and the honest storeless answer
+    // is an empty list rather than a store boot.
     for (const words of [
       ["skill", "lookup", "do"],
       ["prompt", "lookup", "bu"],
-      ["tier", "lookup", "ap"],
     ]) {
-      await expect(
-        runComplete(words, capabilities, env),
-      ).resolves.toBeInstanceOf(Array);
+      await expect(runComplete(words, capabilities, env)).resolves.toEqual([]);
     }
 
     expect(vi.mocked(createStore)).not.toHaveBeenCalled();
@@ -328,31 +346,59 @@ describe("storeless guarantee (PROTECTED)", () => {
 
   it("the spawned __complete fast path answers without touching any state", () => {
     // The perf globalSetup guarantees dist/pragma exists.
+    // A FRESH INSTALL, reproduced: nothing is inherited from this process's
+    // environment, the cwd holds no config, and $HOME plus all three XDG roots
+    // are empty temps. Anything the binary answers here it answered from
+    // itself. (The suite before this inherited `...process.env`, so it could
+    // not tell a compiled-in answer from an ambient one.)
     const binary = fileURLToPath(
       new URL("../../../dist/pragma", import.meta.url),
     );
+    const home = mkdtempSync(join(tmpdir(), "pragma-storeless-home-"));
     const xdgConfig = mkdtempSync(join(tmpdir(), "pragma-storeless-cfg-"));
     const xdgState = mkdtempSync(join(tmpdir(), "pragma-storeless-state-"));
     const xdgCache = mkdtempSync(join(tmpdir(), "pragma-storeless-cache-"));
+    const emptyCwd = mkdtempSync(join(tmpdir(), "pragma-storeless-cwd-"));
+    const env = {
+      HOME: home,
+      XDG_CONFIG_HOME: xdgConfig,
+      XDG_STATE_HOME: xdgState,
+      XDG_CACHE_HOME: xdgCache,
+    };
 
-    const result = spawnSync(binary, ["__complete", "--", "co"], {
+    const nouns = spawnSync(binary, ["__complete", "--", "co"], {
       encoding: "utf-8",
-      env: {
-        ...process.env,
-        XDG_CONFIG_HOME: xdgConfig,
-        XDG_STATE_HOME: xdgState,
-        XDG_CACHE_HOME: xdgCache,
-      },
+      cwd: emptyCwd,
+      env,
     });
+    expect(nouns.status).toBe(0);
+    expect(nouns.stdout).toBe("colophon\nconfig\n");
+    expect(nouns.stderr).toBe("");
+
+    // The headline guarantee of the embedded pack: a user who has installed
+    // the binary and nothing else gets ENTITY candidates on the first TAB.
+    // Every other pin on the embedded index runs in-process, where a bundler
+    // change that made `pack.index.generated.ts` unreachable FROM THE BINARY
+    // would leave the whole suite green.
+    const entities = spawnSync(
+      binary,
+      ["__complete", "--", "block", "lookup", "ds:global.component.but"],
+      { encoding: "utf-8", cwd: emptyCwd, env },
+    );
+    expect(entities.status).toBe(0);
+    expect(entities.stderr).toBe("");
+    expect(entities.stdout.split("\n").at(0)).toBe(
+      "ds:global.component.button",
+    );
 
-    expect(result.status).toBe(0);
-    expect(result.stdout).toBe("colophon\nconfig\n");
-    expect(result.stderr).toBe("");
     // Storeless and config-free: no first-run marker, no config cache, no
-    // store artifacts — the fast path must leave the environment untouched.
+    // store artifacts — the fast path must leave the environment untouched,
+    // after BOTH kinds of context.
+    expect(readdirSync(home)).toEqual([]);
     expect(readdirSync(xdgConfig)).toEqual([]);
     expect(readdirSync(xdgState)).toEqual([]);
     expect(readdirSync(xdgCache)).toEqual([]);
+    expect(readdirSync(emptyCwd)).toEqual([]);
   });
 
   it("the spawned fast path emits zero bytes for zero candidates, exit 0", () => {