@canonical/pragma-cli 0.33.0 → 0.34.0

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

@@ -1,45 +1,68 @@
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { readConfig } from "../config/readConfig.js";
+import { embeddedManifest } from "../runtime/graphpack/embedded.js";
+import { activePackPath, packDir } from "../runtime/paths.js";
+import { resolveSources } from "../runtime/resolveSources.js";
 import type { CapabilityModule, VerbSpec } from "../spec/types.js";
 import { runComplete } from "./complete.js";
-import { createIndexEntityReader, indexCompletionEnv } from "./entitySource.js";
+import {
+  createIndexEntityReader,
+  indexCompletionEnv,
+  readPackIndex,
+} from "./entitySource.js";
 
-/** A fresh cwd with no lock → the reader falls back to the embedded pack. */
+/** A fresh cwd with no pointer → the reader falls back to the embedded pack. */
 const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-entity-"));
 
-/** A project whose lock points at a crafted index.json in a temp pack cache. */
+/** The 64-hex content hash the crafted pack is filed under. */
+const CRAFTED_HASH = "1".repeat(64);
+
+/** A project pointed at a crafted index.json in a temp pack cache. */
 function projectWithIndex(index: unknown): string {
   const cwd = mkdtempSync(join(tmpdir(), "pragma-idx-cwd-"));
   const cache = mkdtempSync(join(tmpdir(), "pragma-idx-cache-"));
   vi.stubEnv("XDG_CACHE_HOME", cache);
-  writeFileSync(
-    join(cwd, "pragma.lock.json"),
-    JSON.stringify({ contentHash: "testhash" }),
-  );
-  const packDir = join(cache, "pragma", "packs", "testhash");
+  const pointer = activePackPath(cwd);
+  mkdirSync(dirname(pointer), { recursive: true });
+  writeFileSync(pointer, CRAFTED_HASH);
+  const packDir = join(cache, "pragma", "packs", CRAFTED_HASH);
   mkdirSync(packDir, { recursive: true });
   writeFileSync(join(packDir, "index.json"), JSON.stringify(index));
   return cwd;
 }
 
-/** A crafted index exercising the index / prompts / tiers / prefixes sources. */
+/**
+ * A crafted index exercising the index / prefixes sources. Deliberately in a
+ * NEUTRAL namespace: the reader knows no entity families any more, so a test
+ * proving it reads `label` or `altNames` must not need this distribution's
+ * vocabulary to say so. Since L-OPEN-9 no live verb declares the `altNames`
+ * field (the tier lookup completes entity names like every declared lookup),
+ * so this crafted index is where the field's read contract is held.
+ *
+ * Real-vocabulary coverage lives in two places, and neither is here: the
+ * PROTECTED contract describe below reads the shipped index for plain entity
+ * NAMES, and `safety.test.ts`'s "every declared name source resolves without
+ * constructing the store" drives the live grammar over the shipped index for
+ * entity names (`tier lookup ap` → `ds:apps`) and for `prefixes`.
+ */
 const CRAFTED_INDEX = {
   version: 2,
-  contentHash: "testhash",
-  prefixes: { ex: "https://example.com/", ds: "https://ds.canonical.com/" },
+  contentHash: CRAFTED_HASH,
+  prefixes: { ex: "https://example.com/" },
   instanceCountByType: {},
   entities: [
     { name: "ex:Button", type: "ex:Component" },
-    { name: "ds:prompt.build", type: "ds:Prompt", label: "build-a-block" },
+    { name: "ex:prompt.build", type: "ex:Prompt", label: "build-a-block" },
     {
-      name: "ds:tier.lxd",
-      type: "ds:Tier",
+      name: "ex:tier.lxd",
+      type: "ex:Tier",
       label: "LXD",
       altNames: ["apps/lxd"],
     },
-    { name: "ds:tier.core", type: "ds:Tier", label: "core" },
+    { name: "ex:tier.core", type: "ex:Tier", label: "core" },
   ],
 };
 
@@ -55,15 +78,27 @@ describe("indexCompletionEnv — multi-source names(ref)", () => {
     ]);
   });
 
-  it("prompts: ds:Prompt entities emit label || name", async () => {
+  it("index + field label: emits the label, and nothing for an entity without one", async () => {
     const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
-    expect(await env.names({ from: "prompts" })).toEqual(["build-a-block"]);
+    expect(
+      await env.names({ from: "index", type: "ex:Prompt", field: "label" }),
+    ).toEqual(["build-a-block"]);
+    // `ex:Button` carries no label. The lookup that declared this field matches
+    // on the label, so standing the name in would offer a token that lookup
+    // cannot resolve.
+    expect(
+      await env.names({ from: "index", type: "ex:Component", field: "label" }),
+    ).toEqual([]);
   });
 
-  it("tiers: emit ds:name (altNames) when present, else label ?? name", async () => {
+  it("index + field altNames: emits only the alt names, never a label in their place", async () => {
     const env = indexCompletionEnv(projectWithIndex(CRAFTED_INDEX));
-    // apps/lxd from altNames (the ds:name); core from the label fallback.
-    expect(await env.names({ from: "tiers" })).toEqual(["apps/lxd", "core"]);
+    // `ex:tier.lxd` carries `apps/lxd`; `ex:tier.core` carries none, so its
+    // label `core` is NOT offered — a bespoke tier lookup filters on the
+    // declared alt-name property and would refuse it.
+    expect(
+      await env.names({ from: "index", type: "ex:Tier", field: "altNames" }),
+    ).toEqual(["apps/lxd"]);
   });
 
   it("prefixes: the index's prefixes ∪ the default display map", async () => {
@@ -92,18 +127,23 @@ describe("indexCompletionEnv — multi-source names(ref)", () => {
     expect(await env.names({ from: "skills" })).toEqual(["docx"]);
   });
 
-  it("missing sources degrade to [] (prefixes still lists the default map)", async () => {
+  it("a type nothing matches yields [] (prefixes still list the default map)", async () => {
     const env = indexCompletionEnv(
       projectWithIndex({
         version: 2,
-        contentHash: "testhash",
+        contentHash: CRAFTED_HASH,
         prefixes: {},
         instanceCountByType: {},
         entities: [{ name: "ex:Button", type: "ex:Component" }],
       }),
     );
-    expect(await env.names({ from: "prompts" })).toEqual([]);
-    expect(await env.names({ from: "tiers" })).toEqual([]);
+    expect(
+      await env.names({ from: "index", type: "ex:Prompt", field: "label" }),
+    ).toEqual([]);
+    expect(
+      await env.names({ from: "index", type: "ex:Tier", field: "altNames" }),
+    ).toEqual([]);
+    // The display map is compiled in, so it answers with no index at all.
     expect(await env.names({ from: "prefixes" })).toContain("ds");
   });
 });
@@ -112,16 +152,18 @@ describe("entity source contract (PROTECTED)", () => {
   it("reads the embedded index storelessly, filtering by type + partial", () => {
     const read = createIndexEntityReader(freshCwd());
 
-    // Abox individuals of ex:Component, sorted.
-    expect(read("ex:Component", "")).toEqual([
-      "ex:Button",
-      "ex:Card",
-      "ex:Dialog",
-    ]);
+    // An abox individual of ds:Component. Membership, not the full 100+ list:
+    // the roster moves whenever the design system does, but a design system
+    // without a button is a change a human should look at.
+    expect(read("ds:Component", "")).toContain("ds:global.component.button");
     // Tbox class.
-    expect(read("owl:Class", "")).toEqual(["ex:Component"]);
-    // Partial-prefix filter.
-    expect(read("ex:Component", "ex:B")).toEqual(["ex:Button"]);
+    expect(read("owl:Class", "")).toContain("ds:Component");
+    // Partial-prefix filter: every candidate starts with what was typed.
+    const partial = read("ds:Component", "ds:global.component.but");
+    expect(partial).toContain("ds:global.component.button");
+    for (const name of partial) {
+      expect(name.startsWith("ds:global.component.but")).toBe(true);
+    }
     // Unknown type → no matches (never throws).
     expect(read("ds:Nope", "")).toEqual([]);
   });
@@ -129,16 +171,16 @@ describe("entity source contract (PROTECTED)", () => {
   it("relies only on the frozen { name, type } minimum", () => {
     const read = createIndexEntityReader(freshCwd());
     // Every result is a bare name token (string), usable with no other field.
-    for (const name of read("ex:Component", "")) {
+    for (const name of read("ds:Component", "")) {
       expect(typeof name).toBe("string");
-      expect(name.startsWith("ex:")).toBe(true);
+      expect(name.startsWith("ds:")).toBe(true);
     }
   });
 
   it("is fast (well under the 50ms storeless budget)", () => {
     const read = createIndexEntityReader(freshCwd());
     const start = performance.now();
-    read("ex:Component", "");
+    read("ds:Component", "");
     expect(performance.now() - start).toBeLessThan(50);
   });
 });
@@ -159,7 +201,7 @@ describe("__complete entity tier wiring", () => {
             required: true,
             complete: {
               kind: "names",
-              source: { from: "index", type: "ex:Component" },
+              source: { from: "index", type: "ds:Component" },
             },
           },
         ],
@@ -185,14 +227,116 @@ describe("__complete entity tier wiring", () => {
     // index-backed reader over cwd, adapted to the resolver's EntityNameReader.
     await expect(
       runComplete(
-        ["block", "lookup", "ex:B"],
+        ["block", "lookup", "ds:global.component.but"],
         [lookupModule],
         indexCompletionEnv(freshCwd()),
       ),
-    ).resolves.toEqual(["ex:Button"]);
+    ).resolves.toContain("ds:global.component.button");
     // Without the env, the entity tier yields nothing (grammar-only).
     await expect(
-      runComplete(["block", "lookup", "ex:B"], [lookupModule]),
+      runComplete(
+        ["block", "lookup", "ds:global.component.but"],
+        [lookupModule],
+      ),
     ).resolves.toEqual([]);
   });
 });
+
+describe("readPackIndex answers the boot decision, never around it", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  // `info`, `doctor`, the MCP resource browser and native `prompts/list` all
+  // read through this. It takes the decision rather than re-deriving one, so it
+  // covers all three arms — including the one a re-derivation gets wrong.
+  it("reads the pack the decision names", () => {
+    projectWithIndex(CRAFTED_INDEX); // plants the pack under a stubbed cache
+    const index = readPackIndex({
+      kind: "pack",
+      dir: packDir(CRAFTED_HASH),
+      contentHash: CRAFTED_HASH,
+    });
+    expect(index?.contentHash).toBe(CRAFTED_HASH);
+    expect(index?.entities.map((entity) => entity.name)).toContain("ex:Button");
+  });
+
+  it("reads the embedded snapshot on the embedded arm", () => {
+    const index = readPackIndex({ kind: "embedded" });
+    expect(index?.contentHash).toBe(embeddedManifest().contentHash);
+  });
+
+  it("reads NOTHING when the store is unavailable", () => {
+    // The row that matters: a project that declared its own packs and never
+    // built them must not be listed the distribution's graph while every read
+    // of it fails STORE_UNAVAILABLE.
+    expect(readPackIndex({ kind: "unavailable", reason: "not built" })).toBe(
+      undefined,
+    );
+  });
+});
+
+describe("the storeless fast path implements the pointer half", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  // `__complete` cannot see `origins.packs` (the config evaluator is banned on
+  // this graph), so it cannot distinguish a fresh install from a configured-but-
+  // unbuilt project. It CAN see the pointer, and must not prefer the snapshot
+  // over a pointer whose pack the cache lost — that is the decision table's
+  // second row, where the two readers used to disagree.
+  it("offers no candidates when the pointed-at pack is gone", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-idx-cwd-"));
+    const cache = mkdtempSync(join(tmpdir(), "pragma-idx-cache-"));
+    vi.stubEnv("XDG_CACHE_HOME", cache);
+    const pointer = activePackPath(cwd);
+    mkdirSync(dirname(pointer), { recursive: true });
+    writeFileSync(pointer, CRAFTED_HASH); // …but no pack directory for it.
+
+    expect(createIndexEntityReader(cwd)("ds:Component", "")).toEqual([]);
+    expect(
+      await indexCompletionEnv(cwd).names({ from: "index", type: "" }),
+    ).toEqual([]);
+  });
+
+  it("still offers the snapshot's names in a configured-but-unbuilt project (the documented price)", async () => {
+    // The bounded exception `entitySource.ts` documents, pinned as it IS and
+    // not as it should be. The fast path is deliberately denied the config
+    // layer, so a `pragma.config.ts` declaring packs is invisible to it: with
+    // no pointer it cannot tell this project from a fresh install, and it
+    // answers from the embedded snapshot.
+    //
+    // Both halves are asserted against the SAME cwd, because the ASYMMETRY is
+    // the whole claim — asserting only that the snapshot answers would restate
+    // the fresh-install case the PROTECTED contract describe already covers,
+    // and would pass with the config file deleted. The read half refusing is
+    // what makes this directory a configured-but-unbuilt project rather than a
+    // fresh install. (`doctor` says so too, in the same words: verified against
+    // the compiled binary, where `block list` raises STORE_UNAVAILABLE while
+    // this same completion still answers.)
+    //
+    // If a later change gives the fast path a config-free way to see
+    // `origins.packs`, THIS is the test that must move, deliberately.
+    const cwd = mkdtempSync(join(tmpdir(), "pragma-unbuilt-cwd-"));
+    vi.stubEnv(
+      "XDG_CACHE_HOME",
+      mkdtempSync(join(tmpdir(), "pragma-unbuilt-")),
+    );
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      'export default { packs: [{ name: "unbuilt", source: "file:///pragma-never-built" }] };\n',
+    );
+
+    const decision = resolveSources(await readConfig(cwd), cwd);
+    expect(decision).toEqual({
+      kind: "unavailable",
+      reason: "packs are configured but the store has not been built",
+    });
+    expect(readPackIndex(decision)).toBeUndefined();
+
+    expect(createIndexEntityReader(cwd)("ds:Component", "")).toContain(
+      "ds:global.component.button",
+    );
+  });
+});

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,49 +65,41 @@ 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;
+  }
 }
 
 /**
@@ -120,31 +125,37 @@ export function entityTotal(index: PackIndex): number {
   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;
@@ -180,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();
@@ -235,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.
  *
@@ -262,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,
             },
           },