@canonical/pragma-cli 0.33.0 → 0.34.0

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

@@ -5,9 +5,9 @@
  * single-typed 6-entity fixture, never the PRODUCT against a cold, real,
  * multi-typed pack. This file drives the REAL path end to end over the vendored
  * {@link DEFAULT_PACK_TTL} default pack — `sources update` (resolve → build →
- * lock, via `bootFixtureRuntime`) → boot → `graph query` → `block list` /
+ * point, via `bootFixtureRuntime`) → boot → `graph query` → `block list` /
  * `ontology list` (populated AND empty) → the error paths (malformed `.ttl`,
- * corrupt `schema.json`, a missing pinned commit).
+ * a torn `schema.json`, a corrupt `schema.json`).
  *
  * It also pins, in-process, the real-data shapes the clean fixture masked — the
  * `entityTotal` double-count (A1), the untiered block that `block list` drops
@@ -17,7 +17,6 @@
  * use" becomes "CI catches it".
  */
 
-import { execFileSync } from "node:child_process";
 import {
   mkdirSync,
   mkdtempSync,
@@ -27,31 +26,26 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { runTask } from "@canonical/task/node";
 import { afterAll, describe, expect, it } from "vitest";
-import { blockModule } from "../../capabilities/block/index.js";
+import { storyModules } from "../../capabilities/distribution.js";
 import { graphQueryVerb } from "../../capabilities/graph/query.verb.js";
 import {
   ontologyListVerb,
   ontologyShowVerb,
 } from "../../capabilities/ontology/verbs.js";
-import { buildUpdateTask } from "../../capabilities/sources/runUpdate.js";
 import { updateVerb } from "../../capabilities/sources/update.verb.js";
-import { VERSION } from "../../constants.js";
 import {
   entityTotal,
   readPackIndex,
 } from "../../kernel/completion/entitySource.js";
-import type { ConfigLayers, PackageEntry } from "../../kernel/config/types.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
-import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import type { PackIndex } from "../../kernel/runtime/graphpack/types.js";
 import { SCHEMA_FILE } from "../../kernel/runtime/graphpack/types.js";
-import { readLock } from "../../kernel/runtime/lock.js";
-import { packDir } from "../../kernel/runtime/paths.js";
-import { createLazyStore } from "../../kernel/runtime/store.js";
-import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
+import { packDir, readActivePack } from "../../kernel/runtime/paths.js";
+import { resolveSources } from "../../kernel/runtime/resolveSources.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import {
   DEFAULT_PACK_ALL_VISIBLE_CONFIG,
@@ -76,6 +70,11 @@ const JSON_FLAGS: GlobalFlags = {
 };
 const NO_MUTATION = { dryRun: false, undo: false, yes: false };
 
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+
 const blockListVerb = blockModule.verbs.find(
   (verb) => verb.path.join(" ") === "block list",
 ) as VerbSpec;
@@ -99,6 +98,15 @@ afterAll(async () => {
   await Promise.all(fixtures.map((fixture) => fixture.dispose()));
 });
 
+/** The index of the pack a fixture's boot decision names — what `info` reads. */
+async function activeIndex(
+  fixture: FixtureGraph,
+): Promise<PackIndex | undefined> {
+  return readPackIndex(
+    resolveSources(await fixture.runtime.loadConfig(), fixture.cwd),
+  );
+}
+
 /** The `--format json` envelope a read verb renders. */
 interface Envelope {
   readonly ok: boolean;
@@ -122,21 +130,16 @@ async function readVerb(
 }
 
 /** The sorted `name` column of a `block list` invocation. */
-async function blockListNames(
-  cwd: string,
-  allTiers: boolean,
-): Promise<string[]> {
-  const envelope = await readVerb(blockListVerb, { allTiers }, cwd);
+async function blockListNames(cwd: string): Promise<string[]> {
+  const envelope = await readVerb(blockListVerb, {}, cwd);
   const rows = envelope.data as { name: string }[];
   return rows.map((row) => row.name).sort();
 }
 
 describe("default-pack journey — sources update, build, boot (E1)", () => {
-  it("bootFixtureRuntime runs the real resolve/build/lock and writes a content-addressed lock", async () => {
+  it("bootFixtureRuntime runs the real resolve/build and points the project at the pack", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
-    const lock = readLock(fixture.cwd);
-    expect(lock?.contentHash).toMatch(/^[0-9a-f]{64}$/);
-    expect(lock?.packs).toHaveLength(1);
+    expect(readActivePack(fixture.cwd)).toMatch(/^[0-9a-f]{64}$/);
     // The booted store answers a read against the freshly built pack.
     const ask = await fixture.runtime.query.sparql(
       "ASK { ds:button a ds:Component }",
@@ -145,17 +148,17 @@ describe("default-pack journey — sources update, build, boot (E1)", () => {
   });
 
   it("drives the literal `sources update` verb over a cold project, then boots a read", async () => {
-    // A cold file-package project with NO lock yet — the real CLI command path.
+    // A cold file-package project with nothing built yet — the real CLI path.
     const pkg = mkdtempSync(join(tmpdir(), "e1-pkg-"));
     mkdirSync(join(pkg, "definitions"), { recursive: true });
     writeFileSync(join(pkg, "definitions", "pack.ttl"), DEFAULT_PACK_TTL);
     const cwd = mkdtempSync(join(tmpdir(), "e1-proj-"));
     writeFileSync(
       join(cwd, "pragma.config.ts"),
-      `export default { packages: [{ name: "default", source: "file://${pkg}" }] };\n`,
+      `export default { packs: [{ name: "default", source: "file://${pkg}" }] };\n`,
     );
     try {
-      // `sources update` is a real mutation — resolve, build, write the lock.
+      // `sources update` is a real mutation — resolve, build, point the project.
       const outcome = await executeVerb(
         updateVerb,
         {},
@@ -163,18 +166,18 @@ describe("default-pack journey — sources update, build, boot (E1)", () => {
         bootRuntime(JSON_FLAGS, cwd),
       );
       expect(outcome.exitCode).toBe(0);
-      expect(readLock(cwd)?.contentHash).toMatch(/^[0-9a-f]{64}$/);
-      // A SEPARATE, fresh runtime boots the just-built pack from the lock. No
-      // channel is configured, so the default `normal` channel hides the
-      // beta-gated Beta Badge. Assert the two global blocks are present while
-      // staying TOLERANT of the untiered Orphan Widget: whether it appears under
-      // --all-tiers is the A2 behavior, asserted in exactly one place below (the
-      // A2 regression guard). Filtering Orphan out keeps this test focused on the
-      // two global blocks, and still pins that Beta Badge is hidden.
-      const globalBlocks = (await blockListNames(cwd, true)).filter(
-        (name) => name !== UNTIERED_BLOCK_NAME,
-      );
-      expect(globalBlocks).toEqual(["Button", "Card"]);
+      expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
+      // A SEPARATE, fresh runtime boots the just-built pack from the pointer and
+      // answers a read over it. Since L-OPEN-9 the list is unfiltered, so the
+      // cold-boot read returns the pack's WHOLE block set — the beta-gated Beta
+      // Badge and the untiered Orphan Widget included. That makes this the
+      // strictest form of the assert (an exact set, not a tolerant subset).
+      expect(await blockListNames(cwd)).toEqual([
+        "Beta Badge",
+        "Button",
+        "Card",
+        UNTIERED_BLOCK_NAME,
+      ]);
     } finally {
       rmSync(pkg, { recursive: true, force: true });
       rmSync(cwd, { recursive: true, force: true });
@@ -233,52 +236,52 @@ describe("default-pack journey — graph query over the real pack (E1)", () => {
 });
 
 describe("default-pack journey — block list, populated and empty (E1)", () => {
-  it("normal channel lists the two global blocks, hiding the beta-gated one", async () => {
+  /** The pack's WHOLE block set — what the declared list returns, always. */
+  const ALL_FOUR = ["Beta Badge", "Button", "Card", UNTIERED_BLOCK_NAME];
+
+  it("the `normal` channel lists the beta-gated block too (L-OPEN-9)", async () => {
+    // This used to answer ["Button", "Card"]: the hand-written query hid Beta
+    // Badge behind the channel and Orphan Widget behind the required tier join.
+    // The declared list has neither filter, so the signed-off consequence is
+    // pinned right where the old scoping was.
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
-    expect(await blockListNames(fixture.cwd, false)).toEqual([
-      "Button",
-      "Card",
-    ]);
+    expect(await blockListNames(fixture.cwd)).toEqual(ALL_FOUR);
   });
 
-  it("prerelease channel reveals the beta-gated block across the tier chain", async () => {
+  it("the `prerelease` channel returns the SAME rows — channel scopes nothing", async () => {
     const fixture = await boot(
       DEFAULT_PACK_TTL,
       DEFAULT_PACK_ALL_VISIBLE_CONFIG,
     );
-    // Same inputs as the A2 regression guard below (ALL_VISIBLE + allTiers).
-    // Assert the tiered blocks (prerelease reveals the beta-gated Beta Badge)
-    // while staying TOLERANT of the untiered Orphan Widget — its --all-tiers
-    // visibility is the A2 truth, asserted in exactly one place below. Filtering
-    // Orphan out keeps this green pre-A2 (absent) and post-A2 (present), so it
-    // never contradicts that hand-off.
-    const tieredBlocks = (await blockListNames(fixture.cwd, true)).filter(
-      (name) => name !== UNTIERED_BLOCK_NAME,
-    );
-    expect(tieredBlocks).toEqual(["Beta Badge", "Button", "Card"]);
+    expect(await blockListNames(fixture.cwd)).toEqual(ALL_FOUR);
   });
 
-  it("the apps tier inherits its parent chain (global) plus its own block", async () => {
+  it("a configured tier returns the SAME rows — there is no chain to walk", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, {
       tier: "apps",
       channel: "prerelease",
     });
-    // resolveTierChain("apps") = [global, apps]: Button/Card (global, inherited)
-    // + Beta Badge (apps, own).
-    expect(await blockListNames(fixture.cwd, false)).toEqual([
-      "Beta Badge",
-      "Button",
-      "Card",
-    ]);
+    // The hand-written verb expanded `apps` to [global, apps] and listed the
+    // union; the declared list never reads the tier at all, so `apps` and the
+    // unset default are indistinguishable.
+    expect(await blockListNames(fixture.cwd)).toEqual(ALL_FOUR);
   });
 
-  it("an ontology-only pack with no tiered blocks lists empty — a calm exit 0", async () => {
+  it("an ontology-only pack with no blocks lists empty — a calm exit 0", async () => {
+    // D10-A, MEASURED at the dispatch seam the binary uses: the declared list
+    // body (`makeListRun`) returns `[]` and never throws on emptiness, so the
+    // process still exits 0 — no exit-code delta against the hand-written verb.
+    // Only the empty MESSAGE moved (the story's `emptyRecovery` replaces the
+    // tier/channel wording and the `--all-tiers` hint).
     const fixture = await boot(NO_BLOCKS_TTL);
-    const envelope = await readVerb(
+    const outcome = await executeVerb(
       blockListVerb,
-      { allTiers: true },
-      fixture.cwd,
+      {},
+      NO_MUTATION,
+      bootRuntime(JSON_FLAGS, fixture.cwd),
     );
+    expect(outcome.exitCode).toBe(0);
+    const envelope = JSON.parse(outcome.stdout as string) as Envelope;
     expect(envelope.ok).toBe(true);
     expect(envelope.data).toEqual([]);
   });
@@ -347,15 +350,15 @@ describe("default-pack journey — error paths (E1)", () => {
 
   it("a torn (emptied) schema.json boots to STORE_UNAVAILABLE with the update recovery", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
-    const lock = readLock(fixture.cwd);
+    const active = readActivePack(fixture.cwd) ?? "";
     // Simulate a torn/evicted extraction: truncate schema.json in the pack cache.
-    truncateSync(join(packDir(lock?.contentHash ?? ""), SCHEMA_FILE), 0);
+    truncateSync(join(packDir(active), SCHEMA_FILE), 0);
     // A brand-new runtime (fresh store memo) boots against the now-incomplete pack.
     let caught: unknown;
     try {
       await executeVerb(
         blockListVerb,
-        { allTiers: true },
+        {},
         NO_MUTATION,
         bootRuntime(JSON_FLAGS, fixture.cwd),
       );
@@ -366,69 +369,12 @@ describe("default-pack journey — error paths (E1)", () => {
     expect((caught as PragmaError).code).toBe("STORE_UNAVAILABLE");
     expect((caught as PragmaError).recovery?.cli).toBe("pragma sources update");
   });
-
-  it("a --frozen update whose pinned commit is gone fails with a named CONFIG_ERROR", async () => {
-    const runGit = (repo: string, args: string[]): string =>
-      execFileSync("git", args, {
-        cwd: repo,
-        stdio: "pipe",
-        env: {
-          ...process.env,
-          GIT_AUTHOR_NAME: "t",
-          GIT_AUTHOR_EMAIL: "t@t",
-          GIT_COMMITTER_NAME: "t",
-          GIT_COMMITTER_EMAIL: "t@t",
-        },
-      }).toString();
-
-    const repo = mkdtempSync(join(tmpdir(), "e1-repo-"));
-    const cwd = mkdtempSync(join(tmpdir(), "e1-frozen-"));
-    try {
-      runGit(repo, ["init", "-b", "main"]);
-      mkdirSync(join(repo, "definitions"), { recursive: true });
-      writeFileSync(join(repo, "definitions", "pack.ttl"), NO_BLOCKS_TTL);
-      runGit(repo, ["add", "-A"]);
-      runGit(repo, ["commit", "-m", "one"]);
-
-      const runtime = gitRuntimeFor(cwd, [
-        { name: "pkg-git", source: `git+file://${repo}#main` },
-      ]);
-      // First update locks the current commit SHA.
-      await runTask(await buildUpdateTask(runtime, false));
-      expect(readLock(cwd)?.packs.at(0)?.resolved).toMatch(/^[0-9a-f]{40}$/);
-
-      // Orphan the pinned commit: amend main, then expire the reflog + prune so
-      // the previously-locked SHA is unreachable.
-      writeFileSync(
-        join(repo, "definitions", "pack.ttl"),
-        `${NO_BLOCKS_TTL}\nds:extra a owl:Class .\n`,
-      );
-      runGit(repo, ["add", "-A"]);
-      runGit(repo, ["commit", "--amend", "-m", "amended"]);
-      runGit(repo, ["reflog", "expire", "--expire=now", "--all"]);
-      runGit(repo, ["gc", "--prune=now"]);
-
-      // A --frozen update must re-resolve the pinned (now-missing) SHA and refuse.
-      let caught: unknown;
-      try {
-        await runTask(await buildUpdateTask(runtime, true));
-      } catch (error) {
-        caught = error;
-      }
-      expect(caught).toBeInstanceOf(PragmaError);
-      expect((caught as PragmaError).code).toBe("CONFIG_ERROR");
-      expect((caught as PragmaError).message).toContain("pkg-git");
-    } finally {
-      rmSync(repo, { recursive: true, force: true });
-      rmSync(cwd, { recursive: true, force: true });
-    }
-  });
 });
 
 describe("default-pack journey — real-data shapes the clean fixture masked (E1, hand-off to lanes A)", () => {
   it("every block is co-typed owl:NamedIndividual and indexed as an individual (abox)", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
-    const index = readPackIndex(fixture.cwd);
+    const index = await activeIndex(fixture);
     // The vendored pack indexes 17 distinct entities (5 classes + 4 properties +
     // 2 tiers + 2 channels + 4 blocks).
     expect(index?.entities).toHaveLength(17);
@@ -460,7 +406,7 @@ describe("default-pack journey — real-data shapes the clean fixture masked (E1
     // whichever the store yields first (no `@en` preference). E3 (live oxigraph)
     // is where that ordering is confirmed against the real pack; here we only
     // assert the tag is stripped and the value is one of the two declared forms.
-    const label = readPackIndex(fixture.cwd)?.entities.find(
+    const label = (await activeIndex(fixture))?.entities.find(
       (entity) => entity.name === "ds:button",
     )?.label;
     expect(label).not.toMatch(/@(en|fr)/);
@@ -472,7 +418,7 @@ describe("default-pack journey — real-data shapes the clean fixture masked (E1
 
   it("A1: info's entity total must not exceed the distinct entity count (owl:NamedIndividual double-count)", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
-    const index = readPackIndex(fixture.cwd);
+    const index = await activeIndex(fixture);
     // `entityTotal` (the figure `info`/`doctor` report) once SUMMED per-type
     // instance counts, double-counting each entity per asserted rdf:type (each
     // block under owl:NamedIndividual AND its domain class; ds:tier/ds:release
@@ -484,18 +430,17 @@ describe("default-pack journey — real-data shapes the clean fixture masked (E1
     );
   });
 
-  it("A2: an untiered block must still appear in `block list --all-tiers`", async () => {
+  it("A2: an untiered block must still appear in `block list`", async () => {
     const fixture = await boot(
       DEFAULT_PACK_TTL,
       DEFAULT_PACK_ALL_VISIBLE_CONFIG,
     );
     // `block list`'s SELECT once inner-joined `?c ds:tier ?t`, dropping a
     // ds:Component with no ds:tier even under --all-tiers (though `graph query`
-    // found it, proven above). Lane A made the tier join OPTIONAL, so an
-    // untiered block now appears under --all-tiers — guard it stays visible.
-    expect(await blockListNames(fixture.cwd, true)).toContain(
-      UNTIERED_BLOCK_NAME,
-    );
+    // found it, proven above). Lane A made the tier join OPTIONAL; L-OPEN-9 then
+    // removed the filtering entirely, so the untiered block is visible in the
+    // ONE view that now exists — guard it stays that way.
+    expect(await blockListNames(fixture.cwd)).toContain(UNTIERED_BLOCK_NAME);
   });
 
   // KNOWN GAP / product follow-up (NOT a lane hand-off): a corrupt, NON-EMPTY
@@ -511,16 +456,13 @@ describe("default-pack journey — real-data shapes the clean fixture masked (E1
   // to expect a STORE_UNAVAILABLE PragmaError then.
   it("corrupt (non-empty, invalid) schema.json currently surfaces an UNCLASSIFIED error (known gap)", async () => {
     const fixture = await boot(DEFAULT_PACK_TTL, DEFAULT_PACK_CONFIG);
-    const lock = readLock(fixture.cwd);
-    writeFileSync(
-      join(packDir(lock?.contentHash ?? ""), SCHEMA_FILE),
-      "{ not valid json ]",
-    );
+    const active = readActivePack(fixture.cwd) ?? "";
+    writeFileSync(join(packDir(active), SCHEMA_FILE), "{ not valid json ]");
     let caught: unknown;
     try {
       await executeVerb(
         blockListVerb,
-        { allTiers: true },
+        {},
         NO_MUTATION,
         bootRuntime(JSON_FLAGS, fixture.cwd),
       );
@@ -533,39 +475,3 @@ describe("default-pack journey — real-data shapes the clean fixture masked (E1
     expect(caught).not.toBeInstanceOf(PragmaError);
   });
 });
-
-/**
- * A synthetic runtime whose config is a fixed package list — drives the
- * git-source build Task without a config file (mirrors sources.test.ts).
- *
- * @param cwd - The project directory the lock is written to.
- * @param packages - The configured package entries.
- * @returns A runtime wired to a lazy store over `cwd`.
- * @note Impure — constructs a store handle over the working directory.
- */
-function gitRuntimeFor(cwd: string, packages: PackageEntry[]): PragmaRuntime {
-  const layers: ConfigLayers = {
-    config: { channel: "normal", packages },
-    origins: {
-      tier: "default",
-      channel: "default",
-      detail: "default",
-      packages: "project",
-      stories: "default",
-      prefixes: "default",
-      prompts: "default",
-    },
-    global: { path: "/nonexistent", exists: false },
-    project: { exists: false },
-  };
-  const loadConfig = async (): Promise<ConfigLayers> => layers;
-  const store = createLazyStore({ cwd, loadConfig });
-  return {
-    cwd,
-    version: VERSION,
-    globalFlags: JSON_FLAGS,
-    loadConfig,
-    store,
-    query: createQueryFacade(store),
-  };
-}

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

@@ -0,0 +1,167 @@
+/**
+ * The first-install journey — this PR's whole point, pinned.
+ *
+ * A machine with no cache, no pointer, no network and an empty cwd must answer
+ * real store-backed reads from the embedded pack, and must say honestly where
+ * those answers come from. Equally: a project that declared its OWN packs and
+ * never built them must NOT be handed the distribution's graph — it is a
+ * different graph, and quietly serving it is the failure the boot decision
+ * exists to prevent.
+ *
+ * Assertions pin MEMBERSHIP, never counts: the row counts move whenever the
+ * upstream design system does, but a design system with no `Button`, or a tier
+ * hierarchy with no `Global`, is a change a human should be made to look at.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { storyModules } from "../../capabilities/distribution.js";
+import { checkPackageRefs } from "../../capabilities/doctor/checks/checkPackageRefs.js";
+import { promptListVerb } from "../../capabilities/prompt/verbs.js";
+import { collectStatus } from "../../capabilities/sources/collectStatus.js";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+
+const JSON_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+const NO_MUTATION = { dryRun: false, undo: false, yes: false };
+
+const blockModule = storyModules.get("block");
+if (!blockModule) {
+  throw new Error('pragma.conf.ts declares no story for "block"');
+}
+const standardModule = storyModules.get("standard");
+if (!standardModule) {
+  throw new Error('pragma.conf.ts declares no story for "standard"');
+}
+const tierModule = storyModules.get("tier");
+if (!tierModule) {
+  throw new Error('pragma.conf.ts declares no story for "tier"');
+}
+const tokenModule = storyModules.get("token");
+if (!tokenModule) {
+  throw new Error('pragma.conf.ts declares no story for "token"');
+}
+
+const verbOf = (module: CapabilityModule, path: string): VerbSpec =>
+  module.verbs.find((verb) => verb.path.join(" ") === path) as VerbSpec;
+
+/** A cwd with nothing in it — the cold-install shape (the XDG dirs are isolated). */
+const emptyCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-first-"));
+
+/**
+ * A cwd whose `pragma.config.ts` declares its own packs and has never been
+ * built — `origins.packs` is "project", so the embedded pack must not answer.
+ */
+function unbuiltProjectCwd(): string {
+  const cwd = mkdtempSync(join(tmpdir(), "pragma-unbuilt-"));
+  writeFileSync(
+    join(cwd, "pragma.config.ts"),
+    'export default { packs: [{ name: "mine", source: "file:///pragma-never-built" }] };\n',
+  );
+  return cwd;
+}
+
+/** Run a read verb at a cwd and return the parsed `data` payload. */
+async function readData(verb: VerbSpec, cwd: string): Promise<unknown> {
+  const outcome = await executeVerb(
+    verb,
+    {},
+    NO_MUTATION,
+    bootRuntime(JSON_FLAGS, cwd),
+  );
+  return (JSON.parse(outcome.stdout as string) as { data: unknown }).data;
+}
+
+describe("first install — an empty cwd answers real reads offline", () => {
+  it("block list resolves the design system's blocks", async () => {
+    const rows = (await readData(
+      verbOf(blockModule, "block list"),
+      emptyCwd(),
+    )) as { name: string }[];
+    expect(rows.map((row) => row.name)).toContain("Button");
+  });
+
+  it("standard list resolves the code standards", async () => {
+    const rows = (await readData(
+      verbOf(standardModule, "standard list"),
+      emptyCwd(),
+    )) as { uri: string; name: string }[];
+    expect(rows.length).toBeGreaterThan(0);
+    // Every row is a code standard from the standards pack's own namespace.
+    for (const row of rows) {
+      expect(row.uri).toContain("codestandards#");
+    }
+  });
+
+  it("tier list resolves the tier hierarchy", async () => {
+    const rows = (await readData(
+      verbOf(tierModule, "tier list"),
+      emptyCwd(),
+    )) as { name: string }[];
+    expect(rows.map((row) => row.name)).toContain("Global");
+  });
+});
+
+describe("first install — empty results are honest, not papered over", () => {
+  it("token list exits calmly with no rows (the graph carries no ds:Token)", async () => {
+    expect(
+      await readData(verbOf(tokenModule, "token list"), emptyCwd()),
+    ).toEqual([]);
+  });
+
+  it("prompt list exits calmly with no prompts (the graph carries no ds:Prompt)", async () => {
+    expect(await readData(promptListVerb as VerbSpec, emptyCwd())).toEqual({
+      prompts: [],
+    });
+  });
+});
+
+describe("first install — a project with its own unbuilt packs is refused", () => {
+  it("a read throws STORE_UNAVAILABLE naming `pragma sources update`", async () => {
+    let caught: unknown;
+    try {
+      await readData(verbOf(blockModule, "block list"), unbuiltProjectCwd());
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(PragmaError);
+    expect((caught as PragmaError).code).toBe("STORE_UNAVAILABLE");
+    expect((caught as PragmaError).recovery?.cli).toBe("pragma sources update");
+  });
+
+  it("doctor reports it as a failure, not a healthy install", async () => {
+    const result = await checkPackageRefs(
+      bootRuntime(JSON_FLAGS, unbuiltProjectCwd()),
+    );
+    expect(result.status).toBe("fail");
+    expect(result.detail).toContain("the store has not been built");
+    expect(result.remedy).toBe("pragma sources update");
+  });
+});
+
+describe("first install — the surfaces say where the answers come from", () => {
+  it("sources status reports the embedded snapshot with its provenance", async () => {
+    const status = await collectStatus(bootRuntime(JSON_FLAGS, emptyCwd()));
+    expect(status.store).toBe("embedded");
+    // The upstream revisions the snapshot was compiled from — never "up to date".
+    expect(status.sourceRef).toContain("@canonical/design-system@");
+    expect(status.entityCount).toBeGreaterThan(0);
+  });
+
+  it("doctor passes, naming the embedded snapshot rather than the config", async () => {
+    const result = await checkPackageRefs(bootRuntime(JSON_FLAGS, emptyCwd()));
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("embedded snapshot @ ");
+    expect(result.detail).toContain("pragma sources update");
+  });
+});

package/src/testing/behavioral/journeys.mcpLifecycle.mcp.test.ts

@@ -30,7 +30,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { capabilities } from "../../capabilities/index.js";
-import { readLock } from "../../kernel/runtime/lock.js";
+import { readActivePack } from "../../kernel/runtime/paths.js";
 import { DEFAULT_PACK_TTL } from "../fixtures/graph/defaultPack.js";
 import { type McpHarness, projectMcp } from "../helpers/projectMcp.js";
 
@@ -44,7 +44,7 @@ const tempDir = (prefix: string): string => {
 
 /**
  * A COLD project directory: a `pragma.config.ts` pointing at a real file
- * package, but NO lock yet — so the store boots cold until `sources_update`.
+ * package, but nothing built yet — so the store boots cold until `sources_update`.
  */
 function coldProject(ttl: string): string {
   const pkg = tempDir("e2-pkg-");
@@ -53,7 +53,7 @@ function coldProject(ttl: string): string {
   const cwd = tempDir("e2-proj-");
   writeFileSync(
     join(cwd, "pragma.config.ts"),
-    `export default { packages: [{ name: "default", source: "file://${pkg}" }] };\n`,
+    `export default { packs: [{ name: "default", source: "file://${pkg}" }] };\n`,
   );
   return cwd;
 }
@@ -83,7 +83,7 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     };
     expect(error.code).toBe("STORE_UNAVAILABLE");
     expect(error.recovery?.mcp?.tool).toBe("sources_update");
-    expect(readLock(cwd)).toBeUndefined();
+    expect(readActivePack(cwd)).toBeUndefined();
 
     // 2) The agent runs the recovery tool for real (confirm) — it builds the pack.
     const update = await mcp.callTool("sources_update", { confirm: true });
@@ -93,7 +93,7 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     expect((update.data as { contentHash: string }).contentHash).toMatch(
       /^[0-9a-f]{64}$/,
     );
-    expect(readLock(cwd)?.contentHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(readActivePack(cwd)).toMatch(/^[0-9a-f]{64}$/);
 
     // 3) RETRY on the SAME server: the shared store was invalidated by the
     //    mutation, so the memoized cold rejection is gone and the read re-boots
@@ -104,7 +104,10 @@ describe("MCP lifecycle — cold store recovers after sources_update (E2, C1)",
     const names = (warm.data as { name: string }[])
       .map((row) => row.name)
       .sort();
-    expect(names).toEqual(["Button", "Card"]);
+    // The whole pack — `block_list` is the declared, unfiltered list since
+    // L-OPEN-9, so no channel hides Beta Badge and no tier join hides the
+    // untiered Orphan Widget.
+    expect(names).toEqual(["Beta Badge", "Button", "Card", "Orphan Widget"]);
   });
 });