@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -16,24 +16,19 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createStore } from "@canonical/ke";
 import { compileFromExtraction } from "@canonical/ke-graphql";
-import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
 import { PragmaError } from "../../error/PragmaError.js";
 import { cliRecovery } from "../../error/recovery.js";
 import type { StoreSession } from "../types.js";
 import { readManifest } from "./manifest.js";
-import {
-  DATA_FILE,
-  INDEX_FILE,
-  packIndexSchema,
-  SCHEMA_FILE,
-} from "./types.js";
+import { packIndexSchema } from "./schemas.js";
+import { DATA_FILE, INDEX_FILE, SCHEMA_FILE } from "./types.js";
 
 /** STORE_UNAVAILABLE with the canonical `pragma sources update` recovery (CLI + MCP). */
 function packUnavailable(reason: string): PragmaError {
   return PragmaError.storeUnavailable(reason, {
     recovery: cliRecovery(
-      `${RECOVERY_CLI_PREFIX}sources update`,
-      "Rebuild the local store from the configured packages.",
+      "sources update",
+      "Rebuild the local store from the configured packs.",
       // An agent recovers by calling the tool, then retrying (PR9 C1 cold-store
       // retry makes the post-update retry succeed).
       { tool: "sources_update" },
@@ -73,13 +68,28 @@ export async function readPack(dir: string): Promise<StoreSession> {
     JSON.parse(readFileSync(join(dir, INDEX_FILE), "utf-8")),
   );
 
-  // Guard against a corrupt/unparseable `data.nq` beside an intact manifest:
-  // ke silently falls back to an EMPTY store (and rewrites an empty dump).
-  // If the index says the pack is populated but the store booted with no
-  // triples, the cache is ruined — surface STORE_UNAVAILABLE (and, via the
-  // now-empty dump, `packIsComplete` turns false so recovery rebuilds) rather
-  // than serve an empty graph as if it were the pack.
-  if (index.entities.length > 0 && !(await storeHasTriples(store))) {
+  // Guard against a corrupt or TRUNCATED `data.nq` beside an intact manifest:
+  // ke silently serves whatever loaded (falling back to an EMPTY store on a
+  // parse failure, and rewriting an empty dump). When the manifest records the
+  // build-time triple count (A9), require the booted store to hold AT LEAST it:
+  // a SHORTFALL means the dump was truncated (fewer triples than were built) —
+  // it passes the mere size>0 completeness gate yet would serve a partial graph
+  // silently, so it must surface STORE_UNAVAILABLE here. A benign SUPERSET (more
+  // triples than recorded — e.g. a future ke counting change) is TOLERATED
+  // rather than treated as corruption, so such a change can't trip a fleet-wide
+  // false STORE_UNAVAILABLE. Older packs without the count fall back to the
+  // "populated index but empty store" check (via the now-empty dump,
+  // `packIsComplete` turns false so recovery rebuilds) rather than serving an
+  // empty graph as the pack.
+  const actualTriples = await countTriples(store);
+  if (manifest.tripleCount !== undefined) {
+    if (actualTriples < manifest.tripleCount) {
+      store.dispose();
+      throw packUnavailable(
+        `The pack at ${dir} has a corrupt data cache (expected at least ${manifest.tripleCount} triples, loaded ${actualTriples}).`,
+      );
+    }
+  } else if (index.entities.length > 0 && actualTriples === 0) {
     store.dispose();
     throw packUnavailable(`The pack at ${dir} has a corrupt data cache.`);
   }
@@ -93,10 +103,10 @@ export async function readPack(dir: string): Promise<StoreSession> {
   };
 }
 
-/** Whether the booted store holds at least one triple (a cheap ASK probe). */
-async function storeHasTriples(store: StoreSession["store"]): Promise<boolean> {
-  const result = (await store.query("ASK { ?s ?p ?o }" as never)) as {
-    result: boolean;
-  };
-  return result.result === true;
+/** Count the booted store's triples (a cheap aggregate over the union graph). */
+async function countTriples(store: StoreSession["store"]): Promise<number> {
+  const result = (await store.query(
+    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+  )) as import("@canonical/ke").SelectResult;
+  return Number(result.bindings.at(0)?.n ?? 0);
 }

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

@@ -0,0 +1,74 @@
+/**
+ * The zod schemas validating a pack's persisted artifacts.
+ *
+ * They live HERE, apart from the contracts in `types.ts`, for one reason: zod is
+ * a value dependency, and `types.ts` is reachable from the storeless fast path.
+ * `capabilities/index.ts` → `resolveSources` → `packIsComplete` → `readManifest`
+ * put `manifest.json`'s schema on the graph `bin.ts` evaluates for `__complete`,
+ * costing ~3–4 ms of a ~30 ms budget to build a validator for a ~1 KB file the
+ * boot decision only needs to look at. `readManifest` now validates that file
+ * structurally, by hand, and this module is imported only by the two readers
+ * that are already off the fast path (`read.ts` boots the store; `embedded.ts`
+ * materializes the 1.9 MB embedded pack).
+ *
+ * The schemas remain the EXECUTABLE SPECIFICATION of what a valid artifact is:
+ * `graphpack.test.ts` pins `readManifest`'s hand validator to accept exactly
+ * what {@link manifestSchema} accepts, in both directions, so the two cannot
+ * drift. Change a rule here and that test fails until the hand validator
+ * follows. `capabilities/lazy.test.ts` pins the other half — that NO module on
+ * the storeless graph imports zod at all — so this split cannot silently close.
+ *
+ * Each schema is annotated `z.ZodType<T>` against the hand-written contract it
+ * validates, so a field added to one and not the other is a type error here
+ * rather than a runtime surprise at a read.
+ */
+
+import { z } from "zod";
+import type { Manifest, PackIndex, PackIndexEntity } from "./types.js";
+
+/** zod schema validating a persisted {@link PackIndexEntity}. */
+export const packIndexEntitySchema: z.ZodType<PackIndexEntity> = z.object({
+  name: z.string(),
+  type: z.string(),
+  uri: z.string().optional(),
+  prefixed: z.string().optional(),
+  types: z.array(z.string()).optional(),
+  label: z.string().nullable().optional(),
+  altNames: z.array(z.string()).optional(),
+  box: z.enum(["tbox", "abox"]).optional(),
+  description: z.string().nullable().optional(),
+});
+
+/** zod schema validating a persisted {@link PackIndex}. */
+export const packIndexSchema: z.ZodType<PackIndex> = z.object({
+  version: z.union([z.literal(1), z.literal(2)]),
+  contentHash: z.string(),
+  prefixes: z.record(z.string(), z.string()),
+  entities: z.array(packIndexEntitySchema),
+  instanceCountByType: z.record(z.string(), z.number()),
+});
+
+/** zod schema validating a persisted `manifest.json`. */
+export const manifestSchema: z.ZodType<Manifest> = z.object({
+  name: z.string(),
+  version: z.string(),
+  /** The config `packs` ref this pack was built from (verbatim), or a label. */
+  sourceRef: z.string(),
+  contentHash: z.string(),
+  prefixes: z.record(z.string(), z.string()),
+  createdAt: z.string(),
+  /**
+   * The store's triple count at build time. Cross-checked against the booted
+   * store so a truncated-but-non-empty `data.nq` (a partial graph that passes
+   * the mere size>0 completeness gate) surfaces as STORE_UNAVAILABLE rather
+   * than being served silently (A9). Optional — packs built before this field
+   * skip the check.
+   */
+  tripleCount: z.number().optional(),
+  /**
+   * The distinct abox entity count (matches `entityTotal`). Lets
+   * `sources status` report the figure without parsing the whole `index.json`
+   * (A10). Optional — packs built before this field fall back to the index read.
+   */
+  entityCount: z.number().optional(),
+});

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

@@ -0,0 +1,84 @@
+/**
+ * Read the read stories the ANSWERING pack carries.
+ *
+ * It CONSUMES the one boot decision ({@link resolveSources}) rather than
+ * re-deriving it, so the nouns a project's reads answer with can never differ
+ * from the nouns its pack carries: a project pointed at its own pack gets that
+ * pack's stories, a fresh install gets the embedded snapshot's, and a
+ * configured-but-unbuilt project gets none (its reads refuse too).
+ *
+ * Total: any unreadable or unparseable `stories.json` yields `[]`. The records
+ * are RAW TEXT — validating them is `kernel/packs/collect.validateStories`'s
+ * job, behind one guard, because a third-party story must never break a command.
+ *
+ * The embedded snapshot's records come from their OWN generated module, so
+ * reading them costs a small string and never loads `pack.generated.ts`'s
+ * ~1.9 MB of n-quads (a measured +28 ms on every invocation).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SourcesDecision } from "../resolveSources.js";
+import { storiesJson } from "./embedded/pack.stories.generated.js";
+import { STORIES_FILE } from "./types.js";
+
+/** One package-declared story as the pack carries it: the file it came from, verbatim. */
+export interface PackStoryRecord {
+  /** Where the story was declared, e.g. `@canonical/design-system/stories/block.json`. */
+  readonly source: string;
+  /** The file's raw text — unparsed, uninterpreted. */
+  readonly content: string;
+}
+
+/** A record shaped as this module promises — the file is a user-writable cache. */
+function isRecord(value: unknown): value is PackStoryRecord {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as PackStoryRecord).source === "string" &&
+    typeof (value as PackStoryRecord).content === "string"
+  );
+}
+
+/**
+ * Parse a `stories.json` body; anything malformed degrades to no stories.
+ *
+ * The elements are checked, not just the container: a record that is not
+ * `{ source, content }` would otherwise reach `validateStories` and be reported
+ * as `Ignored story undefined: …` — a diagnostic that names no file.
+ */
+function parseRecords(json: string): readonly PackStoryRecord[] {
+  try {
+    const parsed: unknown = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The read stories the answering pack carries.
+ *
+ * @param decision - The boot decision from `resolveSources`.
+ * @returns The carried story records — `[]` when the pack carries none, no pack
+ *   answers, or the file is unreadable.
+ * @note Impure — reads `stories.json` from the answering pack directory.
+ */
+export function activeStories(
+  decision: SourcesDecision,
+): readonly PackStoryRecord[] {
+  switch (decision.kind) {
+    case "pack":
+      try {
+        return parseRecords(
+          readFileSync(join(decision.dir, STORIES_FILE), "utf-8"),
+        );
+      } catch {
+        return [];
+      }
+    case "embedded":
+      return parseRecords(storiesJson);
+    case "unavailable":
+      return [];
+  }
+}

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

@@ -1,28 +1,56 @@
 /**
- * Graphpack artifact contracts — the four files a built pack directory holds
- * and the zod schemas that keep them honest on read.
+ * Graphpack artifact contracts — the five files a built pack directory holds,
+ * as hand-written types with NO runtime dependency.
  *
  * A pack is the content-addressed, boot-ready form of a set of RDF sources:
  * `data.nq` (the store's n-quads dump — boots via ke's cache path, no TTL
  * parse), `schema.json` (the serialized ke-graphql extraction — boots via
  * `compileFromExtraction`, no live 7-pass compile), `index.json` (the storeless
- * entity index the completion tier and reads consume), and `manifest.json`
+ * entity index the completion tier and reads consume), `stories.json` (the read
+ * stories the packages ship, carried verbatim as raw text), and `manifest.json`
  * (provenance + the prefixes the store was built with). A directory missing
  * `manifest.json` is treated as absent (a torn build), so writes are always
  * temp-dir + atomic rename.
  *
- * This module is reached only behind a dynamic import (pack build / read /
- * store boot), so its zod dependency never lands on the storeless fast path.
+ * FIVE AND ONLY FIVE: the constants below are the single place the artifact set
+ * is named, and three modules must agree with them — `buildPack` writes them,
+ * `packIsComplete` gates on them, and `materializeEmbeddedPack` writes them back
+ * out. A sixth artifact added to only some of those makes a pack whose content
+ * hash claims more than its directory holds, which the next build then reuses,
+ * silently dropping the difference. The agreement is pinned by `graphpack.test.ts`'s
+ * "the committed embedded pack (PROTECTED) > materializes exactly the files
+ * buildPack produces" — extend the set here and that test fails until every
+ * side follows.
+ *
+ * This module is on the STORELESS FAST PATH — `capabilities/index.ts` →
+ * `resolveSources` → `packIsComplete` → `readManifest` reaches it while
+ * `__complete` builds the command tree — so it carries NO runtime import at
+ * all. It used to hold the zod schemas too, which put zod on that graph through
+ * a genuine value import and cost ~3–4 ms of a ~30 ms budget; they now live in
+ * `schemas.ts`, imported only by the two readers that are already off the fast
+ * path. `capabilities/lazy.test.ts` pins the result — no module on that graph
+ * imports zod — so the split cannot silently close.
  */
 
-import { z } from "zod";
-
 /** The n-quads store dump — ke boots it via `createStore({ cache })`. */
 export const DATA_FILE = "data.nq";
 /** The serialized ke-graphql extraction — boots via `compileFromExtraction`. */
 export const SCHEMA_FILE = "schema.json";
 /** The storeless entity index (PR-C's dynamic-completion contract). */
 export const INDEX_FILE = "index.json";
+/**
+ * The read stories the packages shipped, as raw text: one
+ * `{ source, content }` record per `stories/*.json` file, in a JSON array.
+ *
+ * Written ALWAYS, even as `[]`, and gated by `packIsComplete` alongside the
+ * other three — an optional artifact would put the same condition in all three
+ * modules below, which is exactly how a pack ends up claiming stories its
+ * directory does not hold. Raw text rather than parsed definitions so the pack stays a
+ * faithful carrier of the package's bytes and EVERY interpretation failure
+ * (malformed JSON and schema-invalid JSON alike) is caught behind the one guard
+ * in `kernel/packs/collect.validateStories`.
+ */
+export const STORIES_FILE = "stories.json";
 /** Provenance + prefixes; its presence marks a pack directory as complete. */
 export const MANIFEST_FILE = "manifest.json";
 
@@ -45,9 +73,10 @@ export interface PackIndexEntity {
   /** Human label (rdfs:label / skos:prefLabel / dcterms:title / schema:name). */
   readonly label?: string | null;
   /**
-   * Alternative completable names — the `ds:name` values a family (e.g.
-   * `ds:Tier`, matched by `tier lookup`) is addressed by, when they differ from
-   * `name`/`label`. Enrichment for the storeless name-completion sources.
+   * Alternative completable names — the values of the distribution's declared
+   * alternative-name property (`kernel/vocabulary.ts`), which is what a
+   * bespoke lookup matches on, when they differ from `name`/`label`.
+   * Enrichment for the storeless name-completion sources.
    */
   readonly altNames?: readonly string[];
   /** Schema (`tbox`) vs individual (`abox`). */
@@ -74,38 +103,36 @@ export interface PackIndex {
   readonly instanceCountByType: Readonly<Record<string, number>>;
 }
 
-/** zod schema validating a persisted {@link PackIndexEntity}. */
-export const packIndexEntitySchema: z.ZodType<PackIndexEntity> = z.object({
-  name: z.string(),
-  type: z.string(),
-  uri: z.string().optional(),
-  prefixed: z.string().optional(),
-  types: z.array(z.string()).optional(),
-  label: z.string().nullable().optional(),
-  altNames: z.array(z.string()).optional(),
-  box: z.enum(["tbox", "abox"]).optional(),
-  description: z.string().nullable().optional(),
-});
-
-/** zod schema validating a persisted {@link PackIndex}. */
-export const packIndexSchema: z.ZodType<PackIndex> = z.object({
-  version: z.union([z.literal(1), z.literal(2)]),
-  contentHash: z.string(),
-  prefixes: z.record(z.string(), z.string()),
-  entities: z.array(packIndexEntitySchema),
-  instanceCountByType: z.record(z.string(), z.number()),
-});
-
-/** zod schema validating a persisted `manifest.json`. */
-export const manifestSchema = z.object({
-  name: z.string(),
-  version: z.string(),
-  /** The config `packages` ref this pack was built from (verbatim), or a label. */
-  sourceRef: z.string(),
-  contentHash: z.string(),
-  prefixes: z.record(z.string(), z.string()),
-  createdAt: z.string(),
-});
-
-/** Pack provenance and the prefixes the store was built with. */
-export type Manifest = z.infer<typeof manifestSchema>;
+/**
+ * Pack provenance and the prefixes the store was built with — the parsed shape
+ * of `manifest.json`.
+ *
+ * Hand-written rather than inferred from a zod schema, so reading a manifest
+ * needs no validator library (see the module docblock). `schemas.ts`'s
+ * {@link manifestSchema} is annotated against this type, so the two cannot
+ * drift in their FIELDS; `graphpack.test.ts` pins that they do not drift in
+ * what they ACCEPT either.
+ */
+export interface Manifest {
+  readonly name: string;
+  readonly version: string;
+  /** The config `packs` ref this pack was built from (verbatim), or a label. */
+  readonly sourceRef: string;
+  readonly contentHash: string;
+  readonly prefixes: Readonly<Record<string, string>>;
+  readonly createdAt: string;
+  /**
+   * The store's triple count at build time. Cross-checked against the booted
+   * store so a truncated-but-non-empty `data.nq` (a partial graph that passes
+   * the mere size>0 completeness gate) surfaces as STORE_UNAVAILABLE rather
+   * than being served silently (A9). Optional — packs built before this field
+   * skip the check.
+   */
+  readonly tripleCount?: number;
+  /**
+   * The distinct abox entity count (matches `entityTotal`). Lets
+   * `sources status` report the figure without parsing the whole `index.json`
+   * (A10). Optional — packs built before this field fall back to the index read.
+   */
+  readonly entityCount?: number;
+}

package/src/kernel/runtime/loadSession.ts

@@ -9,13 +9,11 @@
  * than silently reaching out.
  */
 
-import { RECOVERY_CLI_PREFIX } from "../../constants.js";
 import type { ConfigLayers } from "../config/types.js";
-import { PragmaError } from "../error/PragmaError.js";
-import { cliRecovery } from "../error/recovery.js";
 import { materializeEmbeddedPack } from "./graphpack/embedded.js";
 import { readPack } from "./graphpack/read.js";
 import { resolveSources } from "./resolveSources.js";
+import { storeUnavailable } from "./storeReadiness.js";
 import type { StoreSession } from "./types.js";
 
 /** What {@link loadStoreSession} needs from the runtime. */
@@ -39,15 +37,9 @@ export async function loadStoreSession(
   const decision = resolveSources(layers, ctx.cwd);
 
   if (decision.kind === "unavailable") {
-    throw PragmaError.storeUnavailable(`${decision.reason}.`, {
-      recovery: cliRecovery(
-        `${RECOVERY_CLI_PREFIX}sources update`,
-        "Build the local store from the configured packages.",
-        // An agent recovers by calling the tool (then retrying — PR9's C1 cold-
-        // store retry makes a post-update retry succeed).
-        { tool: "sources_update" },
-      ),
-    });
+    // The SAME cold-store diagnostic the native MCP surfaces raise (shared via
+    // storeReadiness), so a cold store reads identically on every surface.
+    throw storeUnavailable(decision.reason);
   }
 
   const dir =

package/src/kernel/runtime/paths.ts

@@ -1,27 +1,44 @@
 /**
  * Filesystem locations for the store layer: the content-addressed pack cache,
- * the git-ref checkout cache, and the project lock file.
+ * the git-ref checkout cache, and the per-project active-pack pointer.
  *
- * The pack cache lives under `$XDG_CACHE_HOME/pragma/packs/<contentHash>/`
+ * The pack cache lives under `$XDG_CACHE_HOME/<bin>/packs/<contentHash>/`
  * (content-addressed, so a new source set is a new directory and invalidation
- * is free); ref checkouts under `.../pragma/refs/`. The lock is a committed
- * project artifact at `<cwd>/pragma.lock.json`. All cache paths derive from the
- * config kernel's {@link cacheDir}, so the XDG isolation the tests install
- * contains them.
+ * is free); ref checkouts under `.../<bin>/refs/`. Which pack answers a
+ * project's reads is recorded by a one-line POINTER under
+ * `.../<bin>/projects/` — the content hash `sources update` last built there,
+ * and nothing else. It lives in the cache rather than the repo because the pack
+ * it names is machine-local: a committed pointer would promise a store the next
+ * machine does not have.
+ *
+ * A LEAF module on purpose: it imports node builtins and the distribution's
+ * {@link BIN_NAME}, and owns the cache root's XDG resolution outright
+ * (`kernel/config/paths.ts` keeps config and state). The storeless `__complete`
+ * fast path (`kernel/completion/entitySource.ts`) has to read the pointer, and
+ * `completion/safety.test.ts` forbids the config LAYER anywhere on that import
+ * graph — so the cache root is resolved here rather than imported. `constants.ts`
+ * is not the config layer: it reads inert data, and that same guard positive-lists
+ * it.
  */
 
-import { join } from "node:path";
-import { cacheDir } from "../config/paths.js";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
-/** The lock file basename, committed at the project root. */
-export const LOCK_BASENAME = "pragma.lock.json";
+/** `$XDG_CACHE_HOME/<bin>` (default `~/.cache/<bin>`) — the cache root. */
+function cacheDir(): string {
+  const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  return join(base, BIN_NAME);
+}
 
-/** `$XDG_CACHE_HOME/pragma/packs` — the content-addressed pack cache root. */
+/** `$XDG_CACHE_HOME/<bin>/packs` — the content-addressed pack cache root. */
 export function packsCacheDir(): string {
   return join(cacheDir(), "packs");
 }
 
-/** `$XDG_CACHE_HOME/pragma/refs` — cached git-ref checkouts. */
+/** `$XDG_CACHE_HOME/<bin>/refs` — cached git-ref checkouts. */
 export function refsCacheDir(): string {
   return join(cacheDir(), "refs");
 }
@@ -31,7 +48,39 @@ export function packDir(contentHash: string): string {
   return join(packsCacheDir(), contentHash);
 }
 
-/** The project lock file for a working directory. */
-export function lockPath(cwd: string): string {
-  return join(cwd, LOCK_BASENAME);
+/**
+ * The active-pack pointer for a project: `$XDG_CACHE_HOME/<bin>/projects/<key>`.
+ *
+ * The key is the SHA-256 of the resolved `cwd` — a hash rather than the path
+ * itself so a deep project directory can never exceed the 255-byte filename
+ * limit, and a cryptographic one so two projects can never collide onto each
+ * other's graph.
+ */
+export function activePackPath(cwd: string): string {
+  return join(
+    cacheDir(),
+    "projects",
+    createHash("sha256").update(resolve(cwd)).digest("hex"),
+  );
+}
+
+/**
+ * The content hash of the pack `sources update` built for a project.
+ *
+ * @param cwd - The project directory.
+ * @returns The 64-hex content hash, or `undefined` when the project was never
+ *   built. A pointer that is unreadable, or that does not hold exactly one
+ *   hash, is treated as absent — a corrupt pointer must never name an arbitrary
+ *   cache directory.
+ * @note Impure — reads the pointer from the cache.
+ */
+export function readActivePack(cwd: string): string | undefined {
+  const path = activePackPath(cwd);
+  if (!existsSync(path)) return undefined;
+  try {
+    const hash = readFileSync(path, "utf-8").trim();
+    return /^[0-9a-f]{64}$/.test(hash) ? hash : undefined;
+  } catch {
+    return undefined;
+  }
 }

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

@@ -1,16 +1,20 @@
 import { describe, expect, it } from "vitest";
+import { embeddedManifest } from "./graphpack/embedded.js";
 import { runStoreProbe } from "./probe.js";
 
 describe("store probe (in-process)", () => {
-  it("boots the embedded pack and reports entity + triple counts", async () => {
+  it("boots the embedded pack and finds the triples its manifest claims", async () => {
     const out = JSON.parse(await runStoreProbe()) as {
       ok: boolean;
       entities: number;
       triples: string;
     };
     expect(out.ok).toBe(true);
-    // The embedded sample pack ships six indexed entities (3 abox + 3 tbox).
-    expect(out.entities).toBe(6);
-    expect(Number(out.triples)).toBeGreaterThan(0);
+    // Against the COMMITTED manifest, not a recomputation: a store booted from
+    // `data.nq` must really hold what `manifest.json` says was built into it.
+    // That catches a regenerated dump that disagrees with its own provenance,
+    // and needs no literal that churns whenever upstream moves.
+    expect(Number(out.triples)).toBe(embeddedManifest().tripleCount);
+    expect(out.entities).toBeGreaterThan(0);
   });
 });

package/src/kernel/runtime/readEntity.ts

@@ -16,6 +16,7 @@
  */
 
 import { PragmaError } from "../error/PragmaError.js";
+import { cliRecovery } from "../error/recovery.js";
 import { resolveUri } from "../packs/iri.js";
 import type { PragmaRuntime } from "./types.js";
 
@@ -57,11 +58,11 @@ export async function readEntity(
 
   if (result.type !== "select" || result.bindings.length === 0) {
     throw PragmaError.notFound("entity", uri, {
-      recovery: {
-        message: "Check the URI, or list known entities.",
-        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
-        mcp: { tool: "graph_query" },
-      },
+      recovery: cliRecovery(
+        `graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'`,
+        "Check the URI, or list known entities.",
+        { tool: "graph_query" },
+      ),
     });
   }
 

package/src/kernel/runtime/refs/gitOps.ts

@@ -9,7 +9,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 /** Whether a ref looks like a commit SHA (7-40 hex chars). */
@@ -64,24 +64,6 @@ export function fetchRef(url: string, ref: string, dest: string): string {
   return gitOutput(dest, ["rev-parse", "HEAD"]);
 }
 
-/** Check out an exact commit in an existing clone (fetching it if needed). */
-export function checkoutCommit(
-  url: string,
-  commit: string,
-  dest: string,
-): void {
-  if (!existsSync(dest)) {
-    cloneRef(url, commit, dest);
-    return;
-  }
-  try {
-    git(dest, ["checkout", commit]);
-  } catch {
-    git(dest, ["fetch", "--depth", "1", url, commit]);
-    git(dest, ["checkout", commit]);
-  }
-}
-
 /** The resolved HEAD commit of a checkout. */
 export function headCommit(dest: string): string {
   return gitOutput(dest, ["rev-parse", "HEAD"]);