@canonical/pragma-cli 0.38.0 → 0.42.0

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

@@ -51,6 +51,7 @@ export const packIndexSchema: z.ZodType<PackIndex> = z.object({
 /** zod schema validating a persisted `manifest.json`. */
 export const manifestSchema: z.ZodType<Manifest> = z.object({
   name: z.string(),
+  /** The CLI version that built the pack — the boot decision compares it. */
   version: z.string(),
   /** The config `packs` ref this pack was built from (verbatim), or a label. */
   sourceRef: z.string(),

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

@@ -115,6 +115,19 @@ export interface PackIndex {
  */
 export interface Manifest {
   readonly name: string;
+  /**
+   * The version of the CLI that built this pack — `VERSION`, written by
+   * `sources update` and by the bundler for the embedded snapshot.
+   *
+   * Load-bearing, not just provenance: the boot decision compares it with the
+   * running CLI's version, so a pack an older CLI built in a project that
+   * declares no packs of its own yields to the newer CLI's embedded snapshot
+   * (see `resolveSources`). Every pack any released CLI has ever built already
+   * carries it, which is why that rule needed no new field and heals packs built
+   * before it existed. A REUSED pack has it refreshed (see
+   * `build.stampBuilderVersion`) — otherwise `sources update` could not get a
+   * project out of that state.
+   */
   readonly version: string;
   /** The config `packs` ref this pack was built from (verbatim), or a label. */
   readonly sourceRef: string;

package/src/kernel/runtime/loadSession.ts

@@ -46,5 +46,12 @@ export async function loadStoreSession(
     decision.kind === "embedded"
       ? await materializeEmbeddedPack()
       : decision.dir;
-  return readPack(dir);
+  const session = await readPack(dir);
+  // Carry the passed-over pack (the upgrade row of the decision table) onto the
+  // session, so a read can report which pack it did NOT answer from without
+  // re-deriving the decision — the same reason the session already carries the
+  // loaded pack's own manifest.
+  return decision.kind === "embedded" && decision.ignoredPack !== undefined
+    ? { ...session, ignoredPack: decision.ignoredPack }
+    : session;
 }

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

@@ -0,0 +1,61 @@
+/**
+ * The builder-version comparison behind the boot decision's upgrade row.
+ *
+ * It decides whether a pack a user built on purpose is passed over, so the
+ * cases that matter most here are the ones where it must answer NO.
+ */
+
+import { describe, expect, it } from "vitest";
+import { packIsOlderThanCli, parseSemver } from "./packVersion.js";
+
+describe("parseSemver", () => {
+  it("parses a release triple", () => {
+    expect(parseSemver("0.38.0")).toEqual([0, 38, 0]);
+    expect(parseSemver("10.2.137")).toEqual([10, 2, 137]);
+  });
+
+  it("parses a pre-release/build version to its release triple", () => {
+    // The suffix orders two builds of the same release; this comparison only
+    // ever asks which RELEASE is older.
+    expect(parseSemver("1.2.3-rc.1")).toEqual([1, 2, 3]);
+    expect(parseSemver("1.2.3+sha.abc")).toEqual([1, 2, 3]);
+  });
+
+  it("refuses anything that is not a version", () => {
+    for (const value of ["0", "1.2", "v1.2.3", "", "next", "1.2.3.4"]) {
+      expect(parseSemver(value)).toBeUndefined();
+    }
+  });
+});
+
+describe("packIsOlderThanCli", () => {
+  it("is true only for a pack built by a strictly older CLI", () => {
+    expect(packIsOlderThanCli("0.37.0", "0.38.0")).toBe(true);
+    expect(packIsOlderThanCli("0.38.0", "1.0.0")).toBe(true);
+    expect(packIsOlderThanCli("1.2.3", "1.2.4")).toBe(true);
+  });
+
+  it("keeps the pack when the versions are equal", () => {
+    expect(packIsOlderThanCli("0.38.0", "0.38.0")).toBe(false);
+  });
+
+  it("keeps the pack when a NEWER CLI built it", () => {
+    // A downgrade, or two CLIs sharing one cache. The user's own build wins.
+    expect(packIsOlderThanCli("0.39.0", "0.38.0")).toBe(false);
+    expect(packIsOlderThanCli("1.0.0", "0.38.0")).toBe(false);
+  });
+
+  it("keeps the pack under a dev build (0.0.0) or an unreadable CLI version", () => {
+    // A local checkout must not start reporting every pack on the machine as
+    // stale — its version says nothing about how its snapshot compares.
+    expect(packIsOlderThanCli("0.37.0", "0.0.0")).toBe(false);
+    expect(packIsOlderThanCli("0.37.0", "workspace")).toBe(false);
+  });
+
+  it("keeps a pack whose recorded version cannot be read", () => {
+    // The notice names the version that built the pack, so a pack we cannot
+    // name is one we cannot honestly call old.
+    expect(packIsOlderThanCli("0", "0.38.0")).toBe(false);
+    expect(packIsOlderThanCli("", "0.38.0")).toBe(false);
+  });
+});

package/src/kernel/runtime/packVersion.ts

@@ -0,0 +1,84 @@
+/**
+ * Is a built pack older than the CLI that is now reading it?
+ *
+ * A pack's `manifest.json` records the version of the CLI that built it (the
+ * `version` field — see `graphpack/types.Manifest`). When a user upgrades, the
+ * new CLI ships a new embedded snapshot, and a pack built by the OLD CLI weeks
+ * ago is no longer the better of the two: it answered every read from a graph
+ * the upgrade was meant to replace, silently, with nothing in `sources status`
+ * to say so. This module is the comparison that ends that — `resolveSources`
+ * uses it to let the embedded snapshot answer instead (see its decision table).
+ *
+ * A LEAF on the storeless fast path: string arithmetic, no imports at all. It
+ * deliberately does NOT depend on a semver library — the comparison is
+ * major/minor/patch on two strings that both come from a `package.json`
+ * `version`, and the fast path pays for every value import it makes.
+ */
+
+/** A parsed `major.minor.patch` triple. */
+type Semver = readonly [major: number, minor: number, patch: number];
+
+/**
+ * Parse the `major.minor.patch` prefix of a version string.
+ *
+ * A pre-release or build suffix (`1.2.3-rc.1`, `1.2.3+sha`) parses to its
+ * release triple: the suffix orders two builds of the SAME release, and this
+ * comparison only ever asks which release is older.
+ *
+ * @param value - The recorded version string.
+ * @returns The triple, or `undefined` when the string is not a version.
+ */
+export function parseSemver(value: string): Semver | undefined {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(value.trim());
+  if (match === null) return undefined;
+  const [, major, minor, patch] = match as unknown as [
+    string,
+    string,
+    string,
+    string,
+  ];
+  return [Number(major), Number(minor), Number(patch)];
+}
+
+/**
+ * Whether a pack built by `packVersion` predates the CLI at `cliVersion`.
+ *
+ * Deliberately conservative — it answers `true` only when the pack is PROVABLY
+ * older, because answering `true` means overriding a store the user built on
+ * purpose:
+ *
+ * - Equal, or a pack built by a NEWER CLI (a downgrade, or two CLIs sharing one
+ *   cache): keep the built pack. The user's own build wins, exactly as today.
+ * - `cliVersion` unparseable, or `0.0.0` (a dev build, whose version says
+ *   nothing about how its snapshot compares): keep the built pack, and say
+ *   nothing about it — a local checkout must not start reporting every pack on
+ *   the machine as stale.
+ * - `packVersion` unparseable: keep the built pack. The notice a user reads
+ *   names the version that built the pack, so a pack we cannot name is one we
+ *   cannot honestly call old. (No released CLI writes such a manifest —
+ *   `version` comes from `package.json` — and a manifest MISSING the field is
+ *   already not a readable pack at all: `validateManifest` requires it, so the
+ *   directory fails the completeness gate and boot reports the ordinary
+ *   "not built" recovery.)
+ *
+ * @param packVersion - The manifest's `version` (the CLI that built the pack).
+ * @param cliVersion - The running CLI's version.
+ * @returns Whether the pack should yield to the running CLI's snapshot.
+ */
+export function packIsOlderThanCli(
+  packVersion: string,
+  cliVersion: string,
+): boolean {
+  const cli = parseSemver(cliVersion);
+  if (cli === undefined || (cli[0] === 0 && cli[1] === 0 && cli[2] === 0)) {
+    return false;
+  }
+  const pack = parseSemver(packVersion);
+  if (pack === undefined) return false;
+  for (let index = 0; index < 3; index++) {
+    const packPart = pack[index] as number;
+    const cliPart = cli[index] as number;
+    if (packPart !== cliPart) return packPart < cliPart;
+  }
+  return false;
+}

package/src/kernel/runtime/readEntity.ts

@@ -54,7 +54,7 @@
  */
 
 import type { DetailLevel } from "../../constants.js";
-import { cliRecovery, PragmaError } from "../error/index.js";
+import { callRecovery, PragmaError } from "../error/index.js";
 import { resolveUri } from "../packs/iri.js";
 import { compactUri, resolveDetail } from "../render/index.js";
 import type { PackIndex } from "./graphpack/types.js";
@@ -110,6 +110,18 @@ const SAMPLE_CAP: Readonly<Record<DetailLevel, number>> = {
   detailed: 5,
 };
 
+/**
+ * How many OBJECTS of one outbound predicate each level lists; the true total
+ * rides {@link PredicateGroup.count}. `summary` keeps a few rather than none —
+ * a predicate's first objects are the entity's type, name and tier. Derivation
+ * in BUDGETS.md.
+ */
+const OUTBOUND_CAP: Readonly<Record<DetailLevel, number>> = {
+  summary: 3,
+  standard: 10,
+  detailed: Number.POSITIVE_INFINITY,
+};
+
 /**
  * How many characters of a LITERAL each level carries.
  *
@@ -182,7 +194,12 @@ export type NestedRecord = Record<string, ReadTerm>;
 /** All objects asserted for one predicate on the subject. */
 export interface PredicateGroup {
   readonly predicate: ReadTerm;
+  /** The objects — all of them, or the head when {@link truncated}. */
   readonly objects: ReadTerm[];
+  /** Set when `objects` is shorter than the predicate's true fan-out. */
+  readonly truncated?: true;
+  /** The TRUE number of objects, present only when truncated. */
+  readonly count?: number;
 }
 
 /** Everything asserting one predicate ABOUT the subject. */
@@ -348,10 +365,12 @@ export async function readEntity(
 
   if (outbound.type !== "select" || outbound.termBindings.length === 0) {
     throw PragmaError.notFound("entity", uri, {
-      recovery: cliRecovery(
-        `graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'`,
+      recovery: callRecovery(
+        {
+          verb: "graph query",
+          params: { sparql: "SELECT ?s WHERE { ?s ?p ?o } LIMIT 10" },
+        },
         "Check the URI, or list known entities.",
-        { tool: "graph_query" },
       ),
     });
   }
@@ -381,11 +400,17 @@ export async function readEntity(
     objects.push(term(object));
     groupMap.set(predicate.value, objects);
   }
+  // Cut from the rows already in hand: the count is the group's own length, so
+  // bounding the answer costs no second query.
+  const cap = OUTBOUND_CAP[detail];
   const groups: PredicateGroup[] = [...groupMap.entries()].map(
     ([predicate, objects]) => ({
       // Every key was written from a binding above, so the lookup cannot miss.
       predicate: predicates.get(predicate) as ReadTerm,
-      objects,
+      objects: objects.slice(0, cap),
+      ...(objects.length > cap
+        ? { truncated: true as const, count: objects.length }
+        : {}),
     }),
   );
 
@@ -393,7 +418,10 @@ export async function readEntity(
   const nested =
     detail === "summary" || !hasBlankObject
       ? {}
-      : await readNested(rt, resolved, session.prefixes, term);
+      : capNested(
+          await readNested(rt, resolved, session.prefixes, term),
+          groups,
+        );
 
   const prefixed = compactUri(resolved, session.prefixes);
   const label = session.index.entities.find((e) => e.uri === resolved)?.label;
@@ -409,6 +437,33 @@ export async function readEntity(
   };
 }
 
+/**
+ * Hold the inlined records to the objects their predicate kept.
+ *
+ * A record IS one of its predicate's objects, written out. Listing ten of a
+ * predicate's 24 blank objects beside all 24 of their records would make the
+ * cap a claim about the group and not about the answer.
+ */
+function capNested(
+  nested: Record<string, NestedRecord[]>,
+  groups: readonly PredicateGroup[],
+): Record<string, NestedRecord[]> {
+  const kept = new Map(
+    groups
+      .filter((group) => group.truncated)
+      .map((group) => [
+        group.predicate.prefixed ?? group.predicate.value,
+        group.objects.filter((object) => object.termType === "BlankNode")
+          .length,
+      ]),
+  );
+  return Object.fromEntries(
+    Object.entries(nested)
+      .map(([via, rows]) => [via, rows.slice(0, kept.get(via))] as const)
+      .filter(([, rows]) => rows.length > 0),
+  );
+}
+
 /**
  * Everything asserting a predicate about the subject, grouped and capped.
  *

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

@@ -2,10 +2,12 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { VERSION } from "../../constants.js";
 import type { ConfigLayers } from "../config/types.js";
 import { loadStoreSession } from "./loadSession.js";
+import { parseSemver } from "./packVersion.js";
 import { activePackPath, packDir } from "./paths.js";
-import { resolveSources } from "./resolveSources.js";
+import { describeIgnoredPack, resolveSources } from "./resolveSources.js";
 
 /**
  * Pin the store-boot decision table (`resolveSources`) — especially the two
@@ -41,33 +43,52 @@ function layersWith(packsOrigin: "default" | "project"): ConfigLayers {
   };
 }
 
-/** Write a pack's manifest.json at the given hash (the completeness marker). */
-function writeManifest(dir: string, hash: string): void {
+/**
+ * Write a pack's manifest.json at the given hash (the completeness marker).
+ *
+ * `version` is the CLI version that built the pack — the field the upgrade row
+ * of the decision table compares. The default is deliberately NOT a version:
+ * every case that predates the upgrade row keeps the built pack whatever CLI is
+ * running, so those cases stay about what they were about.
+ */
+function writeManifest(dir: string, hash: string, version = "0"): void {
   writeFileSync(
     join(dir, "manifest.json"),
     JSON.stringify({
       name: "t",
-      version: "0",
+      version,
       sourceRef: "t",
       contentHash: hash,
       prefixes: {},
-      createdAt: new Date().toISOString(),
+      createdAt: BUILT_AT,
     }),
   );
 }
 
+/** The `createdAt` every fixture pack records — a fixed day, for the sentence. */
+const BUILT_AT = "2026-09-10T21:49:00.411Z";
+
 /** Materialize a COMPLETE pack — manifest + non-empty dump, schema, and index. */
-function writeCompletePack(hash: string): string {
+function writeCompletePack(hash: string, version?: string): string {
   const dir = packDir(hash);
   mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, "data.nq"), "<urn:s> <urn:p> <urn:o> .\n");
   writeFileSync(join(dir, "schema.json"), "{}");
   writeFileSync(join(dir, "index.json"), "{}");
   writeFileSync(join(dir, "stories.json"), "[]");
-  writeManifest(dir, hash);
+  writeManifest(dir, hash, version);
   return dir;
 }
 
+/** A version one minor release below the running CLI, and one above it. */
+function neighbouringVersions(): { older: string; newer: string } {
+  const [major, minor] = parseSemver(VERSION) as [number, number, number];
+  return {
+    older: minor > 0 ? `${major}.${minor - 1}.0` : `${major - 1}.0.0`,
+    newer: `${major}.${minor + 1}.0`,
+  };
+}
+
 /** Plant the active-pack pointer a `sources update` would have written. */
 function writePointer(cwd: string, content: string): void {
   const path = activePackPath(cwd);
@@ -175,6 +196,68 @@ describe("resolveSources decision table", () => {
   });
 });
 
+describe("resolveSources — a pack an older CLI built (the upgrade row)", () => {
+  it("yields to the embedded snapshot, and names the pack it passed over", () => {
+    // The reported bug: a pack built weeks ago by an older CLI answered every
+    // read from the graph the upgrade replaced, and nothing said so.
+    const cwd = tmp();
+    const hash = "e".repeat(64);
+    const { older } = neighbouringVersions();
+    writeCompletePack(hash, older);
+    writePointer(cwd, hash);
+
+    expect(resolveSources(layersWith("default"), cwd)).toEqual({
+      kind: "embedded",
+      ignoredPack: { contentHash: hash, builtBy: older, builtAt: BUILT_AT },
+    });
+  });
+
+  it("keeps the built pack when the project declares its OWN packs", () => {
+    // A project with its own packs has its own graph, and a snapshot of the
+    // distribution's is not a substitute for it, stale or not. Byte-identical
+    // to the pre-existing pack row.
+    const cwd = tmp();
+    const hash = "f".repeat(64);
+    const { older } = neighbouringVersions();
+    const dir = writeCompletePack(hash, older);
+    writePointer(cwd, hash);
+
+    expect(resolveSources(layersWith("project"), cwd)).toEqual({
+      kind: "pack",
+      dir,
+      contentHash: hash,
+    });
+  });
+
+  it("keeps a pack this CLI, or a newer one, built", () => {
+    const { newer } = neighbouringVersions();
+    for (const version of [VERSION, newer]) {
+      const cwd = tmp();
+      const hash = version === VERSION ? "1".repeat(64) : "2".repeat(64);
+      const dir = writeCompletePack(hash, version);
+      writePointer(cwd, hash);
+
+      expect(resolveSources(layersWith("default"), cwd)).toEqual({
+        kind: "pack",
+        dir,
+        contentHash: hash,
+      });
+    }
+  });
+
+  it("names the version, the day, and both ways out", () => {
+    expect(
+      describeIgnoredPack({
+        contentHash: "0e82d35c6668",
+        builtBy: "0.37.0",
+        builtAt: BUILT_AT,
+      }),
+    ).toBe(
+      "a pack built by pragma 0.37.0 on 2026-09-10 is ignored — run `pragma sources update` to rebuild it or `pragma sources reset` to remove it",
+    );
+  });
+});
+
 describe("loadStoreSession recovery", () => {
   it("surfaces the `pragma sources update` recovery (CLI + MCP tool) when cold", async () => {
     const cwd = tmp();

package/src/kernel/runtime/resolveSources.ts

@@ -8,27 +8,59 @@
  * says so, and it answers with completion candidates, never content.
  *
  * Boot never touches the network. From the project's active-pack pointer (the
- * content hash `sources update` last built here) and the resolved config:
+ * content hash `sources update` last built here), the pack's recorded builder
+ * version, and the resolved config:
  *
- * | pointer | pack complete | packs origin | → decision            |
- * |---------|---------------|--------------|-----------------------|
- * | yes     | yes           | —            | load the built pack   |
- * | yes     | no            | —            | STORE_UNAVAILABLE     |
- * | no      | —             | default      | embedded fallback     |
- * | no      | —             | configured   | STORE_UNAVAILABLE     |
+ * | pointer | pack complete | built by       | packs origin | → decision          |
+ * |---------|---------------|----------------|--------------|---------------------|
+ * | yes     | yes           | this CLI/newer | —            | load the built pack |
+ * | yes     | yes           | an older CLI   | configured   | load the built pack |
+ * | yes     | yes           | an older CLI   | default      | embedded, pack named|
+ * | yes     | no            | —              | —            | STORE_UNAVAILABLE   |
+ * | no      | —             | —              | default      | embedded fallback   |
+ * | no      | —             | —              | configured   | STORE_UNAVAILABLE   |
  *
  * A configured-but-unbuilt store (or a pointer whose pack the cache lost)
  * surfaces STORE_UNAVAILABLE with a single recovery: `pragma sources update`.
  * "packs origin default" means the user has not pinned their own packs —
  * a fresh install — so the embedded pack answers reads offline. A project that
  * DID configure its own packs is never quietly served the distribution's graph.
+ *
+ * The third row is the UPGRADE row, and it is why the pack's builder version is
+ * part of the decision. A CLI upgrade ships a NEW embedded snapshot; a pack some
+ * older CLI built in this directory weeks ago then answered every read from the
+ * graph the upgrade replaced — silently, with `sources status` reporting a
+ * healthy `built` store. So a pack built by an older CLI, in a project that
+ * declares no packs of its own, YIELDS: the snapshot answers and the pack is
+ * named as ignored ({@link IgnoredPack}) on every surface that reports on the
+ * store, until `sources update` rebuilds it or `sources reset` removes it. The
+ * second row is the other half of the same rule: a project with its own packs
+ * has its own graph, and a snapshot of the distribution's is not a substitute
+ * for it, stale or not — that project keeps today's behaviour exactly.
  */
 
 import { existsSync } from "node:fs";
+import { BIN_NAME, VERSION } from "../../constants.js";
 import type { ConfigLayers } from "../config/types.js";
-import { packIsComplete } from "./graphpack/manifest.js";
+import { packArtifactsPresent, readManifest } from "./graphpack/manifest.js";
+import { packIsOlderThanCli } from "./packVersion.js";
 import { packDir, readActivePack } from "./paths.js";
 
+/**
+ * A built pack the boot decided to pass over: it was built by an older CLI, and
+ * the project declares no packs of its own, so the CLI's own snapshot answers
+ * instead. Carried on the decision (and onward on the booted session) so every
+ * surface that reports on the store can name the pack it is NOT reading.
+ */
+export interface IgnoredPack {
+  /** The passed-over pack's content hash (its cache directory name). */
+  readonly contentHash: string;
+  /** The CLI version that built it (its manifest `version`). */
+  readonly builtBy: string;
+  /** When it was built (its manifest `createdAt`). */
+  readonly builtAt: string;
+}
+
 /** The resolved boot strategy. */
 export type SourcesDecision =
   | {
@@ -36,9 +68,37 @@ export type SourcesDecision =
       readonly dir: string;
       readonly contentHash: string;
     }
-  | { readonly kind: "embedded" }
+  | {
+      readonly kind: "embedded";
+      /**
+       * Present only on the upgrade row: the built pack this project has, which
+       * an older CLI built and which the snapshot is answering in place of.
+       * Absent for an ordinary fresh install, which has no pack at all.
+       */
+      readonly ignoredPack?: IgnoredPack;
+    }
   | { readonly kind: "unavailable"; readonly reason: string };
 
+/**
+ * The one sentence every surface uses for a passed-over pack.
+ *
+ * ONE wording, in one place, because the three surfaces that say it
+ * (`sources status`, `doctor`'s pack refs row, and the recovery text a reader
+ * lands on) must not each invent their own account of the same state. It names
+ * the version and the day — the two facts that make the situation legible — and
+ * both ways out, because they are genuinely different choices: rebuild if you
+ * want your own packs back, reset if you want the shipped snapshot.
+ *
+ * @param ignored - The passed-over pack.
+ * @returns The sentence, without a trailing full stop.
+ */
+export function describeIgnoredPack(ignored: IgnoredPack): string {
+  return (
+    `a pack built by ${BIN_NAME} ${ignored.builtBy} on ${ignored.builtAt.slice(0, 10)} is ignored — ` +
+    `run \`${BIN_NAME} sources update\` to rebuild it or \`${BIN_NAME} sources reset\` to remove it`
+  );
+}
+
 /**
  * Decide how (or whether) to boot the store — without any network or store I/O.
  *
@@ -54,7 +114,28 @@ export function resolveSources(
   const contentHash = readActivePack(cwd);
   if (contentHash !== undefined) {
     const dir = packDir(contentHash);
-    if (packIsComplete(dir)) return { kind: "pack", dir, contentHash };
+    // The manifest is read ONCE and used twice — for completeness (the half of
+    // `packIsComplete` that is not the manifest itself) and for the builder
+    // version. The boot decision is evaluated on the storeless fast path, so
+    // asking the same ~1 KB file for the version separately would be a second
+    // read for a field the first read already had in hand.
+    const manifest = readManifest(dir);
+    if (manifest !== undefined && packArtifactsPresent(dir)) {
+      if (
+        layers.origins.packs === "default" &&
+        packIsOlderThanCli(manifest.version, VERSION)
+      ) {
+        return {
+          kind: "embedded",
+          ignoredPack: {
+            contentHash,
+            builtBy: manifest.version,
+            builtAt: manifest.createdAt,
+          },
+        };
+      }
+      return { kind: "pack", dir, contentHash };
+    }
     // Two different things, and the recovery text is the only thing a user has
     // to go on: the cache evicted the pack, or the directory is there but does
     // not hold a whole pack — the state EVERY install upgraded past the

package/src/kernel/runtime/storeReadiness.ts

@@ -18,7 +18,8 @@
  */
 
 import type { ConfigLayers } from "../config/types.js";
-import { cliRecovery, PragmaError } from "../error/index.js";
+import { callRecovery, PragmaError } from "../error/index.js";
+import { BUILD_STORE_CALL } from "../spec/call.js";
 import { resolveSources } from "./resolveSources.js";
 
 /**
@@ -32,10 +33,9 @@ import { resolveSources } from "./resolveSources.js";
  */
 export function storeUnavailable(reason: string): PragmaError {
   return PragmaError.storeUnavailable(`${reason}.`, {
-    recovery: cliRecovery(
-      "sources update",
+    recovery: callRecovery(
+      BUILD_STORE_CALL,
       "Build the local store from the configured packs.",
-      { tool: "sources_update" },
     ),
   });
 }

package/src/kernel/runtime/types.ts

@@ -67,6 +67,18 @@ export interface StoreSession {
    * have changed since.
    */
   readonly manifest: import("./graphpack/types.js").Manifest;
+  /**
+   * The project's OWN built pack, when the boot passed over it because an older
+   * CLI built it (see `resolveSources`' upgrade row). Present only on a session
+   * booted from the embedded snapshot in a project that has a pack; absent on
+   * every ordinary boot.
+   *
+   * Carried for the same reason `manifest` is: a read that was answered from
+   * the snapshot instead of the pack this directory built has to be able to say
+   * so, from the session it was answered from, without re-resolving a decision
+   * the caller could have changed since.
+   */
+  readonly ignoredPack?: import("./resolveSources.js").IgnoredPack;
 }
 
 /**