@canonical/pragma-cli 0.33.0 → 0.34.0

package/src/kernel/runtime/graphpack/embedded/pack.stories.generated.ts

@@ -0,0 +1,3 @@
+// AUTO-GENERATED by scripts/bundle.ts — do not edit by hand.
+// Regenerate from the packs pragma.conf.ts declares: `bun run bundle`.
+export const storiesJson = "[]";

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

@@ -1,13 +1,27 @@
 /**
- * The embedded fallback pack: a small, self-contained pack compiled into the
- * binary as inlined strings (`pack.generated.ts`, produced by
- * `scripts/genEmbedded.ts`). It is the store the CLI boots when no packages are
- * configured beyond the defaults and no lock has been written yet — so a fresh
- * install answers store-backed reads without a network round-trip.
+ * The embedded pack: the distribution's own graph, compiled from the packs
+ * `pragma.conf.ts` declares and inlined into the binary as escaped strings
+ * (`pack.generated.ts`, produced by `scripts/bundle.ts`). It is the store the
+ * CLI boots when the user has not pinned their own packs and has not built
+ * anything yet — so a fresh install answers real store-backed reads with no
+ * network, no cache, and no git credentials.
+ *
+ * It is a SNAPSHOT, not a substitute for `sources update`: the manifest records
+ * which upstream revisions it was compiled from, and both `sources status` and
+ * `doctor` report that rather than claiming the store is up to date. A project
+ * that declares its own packs and has not built them is never served this graph:
+ * every read, `info`, `sources status`, `doctor` and the MCP prompt/resource
+ * surfaces take {@link resolveSources}' answer and refuse. The one exception is
+ * the shell-completion fast path, which cannot read config at all (see
+ * `kernel/completion/entitySource.ts`) and so still offers this graph's names as
+ * completion candidates — candidates, never content.
  *
  * The inlined strings are materialized into the ordinary content-addressed pack
  * cache on first use and then read back through {@link readPack}, so the
- * embedded pack and a built pack share one boot path. Inlining as JS strings
+ * embedded pack and a built pack share one boot path. The story records live in
+ * their OWN generated module (like the index): dispatch reads them on every
+ * command, and pulling them out of `pack.generated.ts` would load its ~1.9 MB
+ * of n-quads with them — a measured +28 ms on every invocation. Inlining as JS strings
  * (rather than file assets) guarantees the content survives `bun build
  * --compile` with no asset-embedding step.
  */
@@ -24,18 +38,29 @@ import { join } from "node:path";
 import { packDir, packsCacheDir } from "../paths.js";
 import { dataNq, manifestJson, schemaJson } from "./embedded/pack.generated.js";
 import { indexJson } from "./embedded/pack.index.generated.js";
+import { storiesJson } from "./embedded/pack.stories.generated.js";
 import { packIsComplete } from "./manifest.js";
+import { manifestSchema } from "./schemas.js";
 import {
   DATA_FILE,
   INDEX_FILE,
   MANIFEST_FILE,
-  manifestSchema,
+  type Manifest,
   SCHEMA_FILE,
+  STORIES_FILE,
 } from "./types.js";
 
-/** The embedded pack's content hash (its cache-directory name). */
-export function embeddedContentHash(): string {
-  return manifestSchema.parse(JSON.parse(manifestJson)).contentHash;
+/**
+ * The embedded pack's manifest, parsed from the inlined string.
+ *
+ * Carries the provenance `sources status` and `doctor` report — `sourceRef`
+ * (which upstream revisions the snapshot was compiled from), `createdAt`, the
+ * counts — plus the `contentHash` that names its cache directory. Reading it
+ * costs one `JSON.parse` of a ~1 KB string, so neither surface has to
+ * materialize the 1.9 MB pack just to describe it.
+ */
+export function embeddedManifest(): Manifest {
+  return manifestSchema.parse(JSON.parse(manifestJson));
 }
 
 /**
@@ -48,7 +73,7 @@ export function embeddedContentHash(): string {
  * @note Impure — writes the inlined pack files into the cache.
  */
 export function materializeEmbeddedPack(): string {
-  const dir = packDir(embeddedContentHash());
+  const dir = packDir(embeddedManifest().contentHash);
   if (packIsComplete(dir)) return dir;
 
   mkdirSync(packsCacheDir(), { recursive: true });
@@ -57,6 +82,7 @@ export function materializeEmbeddedPack(): string {
     writeFileSync(join(temp, DATA_FILE), dataNq);
     writeFileSync(join(temp, SCHEMA_FILE), schemaJson);
     writeFileSync(join(temp, INDEX_FILE), indexJson);
+    writeFileSync(join(temp, STORIES_FILE), storiesJson);
     // Written last — the completeness marker.
     writeFileSync(join(temp, MANIFEST_FILE), manifestJson);
     if (!packIsComplete(dir)) {

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

@@ -1,18 +1,30 @@
 import {
   existsSync,
   mkdtempSync,
+  readdirSync,
   readFileSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { executeLocal } from "@canonical/ke-graphql";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { buildPack } from "./build.js";
+import { embeddedManifest, materializeEmbeddedPack } from "./embedded.js";
 import { contentHash } from "./hash.js";
+import { packIsComplete, validateManifest } from "./manifest.js";
 import { readPack } from "./read.js";
-import { DATA_FILE, INDEX_FILE, MANIFEST_FILE, SCHEMA_FILE } from "./types.js";
+import { manifestSchema } from "./schemas.js";
+import { activeStories } from "./stories.js";
+import type { PackIndex } from "./types.js";
+import {
+  DATA_FILE,
+  INDEX_FILE,
+  MANIFEST_FILE,
+  SCHEMA_FILE,
+  STORIES_FILE,
+} from "./types.js";
 
 const PREFIXES = {
   ex: "https://pragma.canonical.com/sample#",
@@ -32,12 +44,16 @@ ex:Button a ex:Component ; rdfs:label "Button" ; ex:componentName "Button" .
 ex:Card a ex:Component ; rdfs:label "Card" ; ex:componentName "Card" .
 `;
 
-const build = (inputs: { path: string; content: string }[]) =>
+const build = (
+  inputs: { path: string; content: string }[],
+  stories?: { path: string; content: string }[],
+) =>
   buildPack(inputs, {
     name: "test-pack",
     version: "0.0.0",
     sourceRef: "test:inline",
     prefixes: PREFIXES,
+    ...(stories === undefined ? {} : { stories }),
   });
 
 let savedCacheHome: string | undefined;
@@ -55,12 +71,22 @@ afterAll(() => {
 });
 
 describe("graphpack round-trip (PROTECTED)", () => {
-  it("builds the four artifact files and reuses a cached pack", async () => {
+  it("builds the five artifact files and reuses a cached pack", async () => {
     const result = await build([{ path: "a.ttl", content: TTL }]);
     expect(result.reused).toBe(false);
-    for (const file of [DATA_FILE, SCHEMA_FILE, INDEX_FILE, MANIFEST_FILE]) {
+    for (const file of [
+      DATA_FILE,
+      SCHEMA_FILE,
+      INDEX_FILE,
+      STORIES_FILE,
+      MANIFEST_FILE,
+    ]) {
       expect(existsSync(join(result.dir, file))).toBe(true);
     }
+    // Written even when the packages ship none — an OPTIONAL artifact would put
+    // the same condition in all three modules that name the set, which is how a
+    // pack ends up claiming stories its directory does not hold.
+    expect(readFileSync(join(result.dir, STORIES_FILE), "utf-8")).toBe("[]");
 
     // A second build over identical inputs is a pure cache hit — no rebuild.
     const again = await build([{ path: "a.ttl", content: TTL }]);
@@ -109,6 +135,131 @@ describe("graphpack round-trip (PROTECTED)", () => {
   });
 });
 
+describe("the committed embedded pack (PROTECTED)", () => {
+  it("materializes exactly the files buildPack produces", async () => {
+    // The artifact set is named once, in types.ts, but THREE modules must obey
+    // it: buildPack writes them, packIsComplete gates on them, and
+    // materializeEmbeddedPack writes them back out. A SIXTH artifact added to
+    // only some of those yields a pack whose content hash claims more than its
+    // directory holds — which the next build then reuses, silently dropping the
+    // difference. Comparing the two directories catches that on the day it lands.
+    const built = await build([{ path: "a.ttl", content: TTL }]);
+    expect(readdirSync(materializeEmbeddedPack()).sort()).toEqual(
+      readdirSync(built.dir).sort(),
+    );
+  });
+
+  it("is self-consistent: complete, content-addressed, and non-empty", () => {
+    // No network, so CI runs it: the committed strings really do materialize a
+    // bootable pack whose parts agree with each other.
+    const dir = materializeEmbeddedPack();
+    const manifest = embeddedManifest();
+    expect(packIsComplete(dir)).toBe(true);
+    expect(basename(dir)).toBe(manifest.contentHash);
+    const index = JSON.parse(
+      readFileSync(join(dir, INDEX_FILE), "utf-8"),
+    ) as PackIndex;
+    expect(index.contentHash).toBe(manifest.contentHash);
+    expect(manifest.tripleCount ?? 0).toBeGreaterThan(0);
+    expect(manifest.entityCount ?? 0).toBeGreaterThan(0);
+  });
+});
+
+describe("graphpack carried stories (PROTECTED)", () => {
+  const STORY = {
+    path: "pkg/stories/recipe.json",
+    content: '{"noun":"recipe"}',
+  };
+
+  it("hashes stories as sources and round-trips them byte-for-byte", async () => {
+    const inputs = [{ path: "a.ttl", content: TTL }];
+    const without = await build(inputs);
+    const withStory = await build(inputs, [STORY]);
+
+    // A story-only edit is a NEW pack: the same RDF with a story attached must
+    // not reuse the pack built without it.
+    expect(withStory.contentHash).not.toBe(without.contentHash);
+    expect(
+      JSON.parse(readFileSync(join(withStory.dir, STORIES_FILE), "utf-8")),
+    ).toEqual([{ source: STORY.path, content: STORY.content }]);
+
+    // …and rebuilding with the same story is a pure cache hit.
+    expect((await build(inputs, [STORY])).reused).toBe(true);
+  });
+
+  it("a pack directory missing stories.json is incomplete", async () => {
+    // The migration path: a pack built by the previous kernel has four files,
+    // so it is refused (→ `pragma sources update`) rather than reused as if it
+    // carried the stories its hash covers.
+    const { dir } = await build([{ path: "a.ttl", content: TTL }]);
+    expect(packIsComplete(dir)).toBe(true);
+    rmSync(join(dir, STORIES_FILE));
+    expect(packIsComplete(dir)).toBe(false);
+  });
+
+  it("a non-array stories.json is incomplete, and rebuilds instead of silently losing nouns", async () => {
+    // Size alone let a non-empty but non-ARRAY `stories.json` pass, so
+    // `buildPack` reused the directory and every package-declared noun vanished
+    // while `sources update` reported success. The shape gate turns that into an
+    // ordinary torn pack: refused, then rebuilt.
+    const inputs = [{ path: "a.ttl", content: TTL }];
+    const { dir } = await build(inputs, [STORY]);
+    expect(packIsComplete(dir)).toBe(true);
+
+    for (const corrupt of [
+      '{"noun":"recipe"}',
+      '"a string"',
+      "null",
+      "7",
+      "{",
+    ]) {
+      writeFileSync(join(dir, STORIES_FILE), corrupt);
+      expect(packIsComplete(dir), corrupt).toBe(false);
+    }
+
+    // …and the rebuild is a REBUILD, not a reuse of the corrupt directory: the
+    // stories come back, so the nouns come back.
+    const rebuilt = await build(inputs, [STORY]);
+    expect(rebuilt.reused).toBe(false);
+    expect(packIsComplete(rebuilt.dir)).toBe(true);
+    expect(
+      JSON.parse(readFileSync(join(rebuilt.dir, STORIES_FILE), "utf-8")),
+    ).toEqual([{ source: STORY.path, content: STORY.content }]);
+  });
+
+  it("an EMPTY stories array stays complete — it is the ordinary no-stories pack", async () => {
+    // The gate is shape, not emptiness: `[]` is what a pack with no package
+    // stories legitimately carries, and refusing it would refuse most packs.
+    const { dir } = await build([{ path: "a.ttl", content: TTL }]);
+    expect(readFileSync(join(dir, STORIES_FILE), "utf-8")).toBe("[]");
+    expect(packIsComplete(dir)).toBe(true);
+  });
+
+  it("reads only records shaped { source, content } from a pack directory", async () => {
+    // `stories.json` lives in a user-writable cache. An element that is not a
+    // record used to be cast straight through and reported as
+    // `Ignored story undefined: …` — a diagnostic naming no file, repeated on
+    // every command. Records are checked, so a corrupt entry simply is not one.
+    const { dir } = await build([{ path: "a.ttl", content: TTL }], [STORY]);
+    writeFileSync(
+      join(dir, STORIES_FILE),
+      JSON.stringify([
+        1,
+        null,
+        { source: "x" },
+        { source: 1, content: 2 },
+        {
+          source: STORY.path,
+          content: STORY.content,
+        },
+      ]),
+    );
+    expect(activeStories({ kind: "pack", dir, contentHash: "z" })).toEqual([
+      { source: STORY.path, content: STORY.content },
+    ]);
+  });
+});
+
 describe("graphpack hash stability (PROTECTED)", () => {
   it("is order-independent and content-sensitive", async () => {
     const a = { path: "a.ttl", content: "ex:one a ex:X ." };
@@ -147,6 +298,55 @@ describe("graphpack manifest — persisted counts (A9/A10)", () => {
   });
 });
 
+describe("the manifest hand validator agrees with the schema (PROTECTED)", () => {
+  // `readManifest` is on the storeless fast path, so it validates structurally
+  // instead of importing zod. `manifestSchema` stays the executable spec: this
+  // pins the two to accept EXACTLY the same payloads, in both directions, so a
+  // rule changed in one and not the other fails here rather than at a read.
+  const VALID = {
+    name: "pack",
+    version: "1.0.0",
+    sourceRef: "git+https://example.invalid#main",
+    contentHash: "abc123",
+    prefixes: { ex: "https://example.invalid#" },
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+
+  const cases: Array<[string, unknown]> = [
+    ["the minimal valid manifest", VALID],
+    ["with both optional counts", { ...VALID, tripleCount: 3, entityCount: 2 }],
+    ["with only tripleCount", { ...VALID, tripleCount: 0 }],
+    ["with only entityCount", { ...VALID, entityCount: 0 }],
+    ["with empty prefixes", { ...VALID, prefixes: {} }],
+    ["with an unknown key", { ...VALID, extra: "ignored" }],
+    ["a missing required field", { ...VALID, name: undefined }],
+    ["a required field of the wrong type", { ...VALID, version: 2 }],
+    ["a non-string sourceRef", { ...VALID, sourceRef: null }],
+    ["a non-string contentHash", { ...VALID, contentHash: 7 }],
+    ["a non-string createdAt", { ...VALID, createdAt: 0 }],
+    ["prefixes as an array", { ...VALID, prefixes: [] }],
+    ["prefixes holding a non-string", { ...VALID, prefixes: { ex: 1 } }],
+    ["prefixes as null", { ...VALID, prefixes: null }],
+    ["a non-number tripleCount", { ...VALID, tripleCount: "3" }],
+    ["a non-number entityCount", { ...VALID, entityCount: "2" }],
+    ["a JSON array", [VALID]],
+    ["a JSON string", "manifest"],
+    ["null", null],
+    ["a number", 4],
+  ];
+
+  for (const [label, payload] of cases) {
+    it(`accepts/rejects ${label} exactly as manifestSchema does`, () => {
+      const bySchema = manifestSchema.safeParse(payload);
+      const byHand = validateManifest(payload);
+      expect(byHand !== undefined, label).toBe(bySchema.success);
+      // Agreement on the VALUE too, which is where strip semantics live: an
+      // unknown key must be dropped by both, not carried by one.
+      if (bySchema.success) expect(byHand).toEqual(bySchema.data);
+    });
+  }
+});
+
 describe("graphpack read — truncated data cache (A9)", () => {
   it("a truncated-but-non-empty data.nq surfaces STORE_UNAVAILABLE", async () => {
     // A UNIQUE graph so corrupting its cache never poisons the shared TTL pack.

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

@@ -4,8 +4,9 @@
  *
  * 1. {@link contentHash} — a SHA-256 (ke-graphql's `sha256Hex`) over the
  *    canonicalized *source inputs* (sorted by path, path + content joined with
- *    fixed delimiters). It names the pack's cache directory and is pinned in the
- *    lock, so the same sources always resolve to the same directory and a
+ *    fixed delimiters). It names the pack's cache directory and is what a
+ *    project's active-pack pointer holds, so the same sources always resolve to
+ *    the same directory and a
  *    changed source is a new directory (free invalidation). Hashing the sorted
  *    TTL *inputs* — never the `data.nq` dump, whose n-quads line order is not
  *    canonical — keeps it deterministic.

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

@@ -10,7 +10,7 @@ export type {
 } from "./build.js";
 export { buildPack } from "./build.js";
 export { buildIndex } from "./buildIndex.js";
-export { embeddedContentHash, materializeEmbeddedPack } from "./embedded.js";
+export { embeddedManifest, materializeEmbeddedPack } from "./embedded.js";
 export { contentHash, type HashInput, hashSources } from "./hash.js";
 export { packIsComplete, readManifest } from "./manifest.js";
 export { readPack } from "./read.js";

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

@@ -3,6 +3,13 @@
  * directory without a valid manifest is a torn build (writes land in a temp
  * directory and the manifest is renamed in last), so an absent or invalid
  * manifest means "treat the pack as not there".
+ *
+ * This module is on the storeless FAST PATH (`resolveSources` → `packIsComplete`
+ * → here, while `__complete` builds the command tree), so it validates the ~1 KB
+ * manifest structurally instead of importing zod to do it — that import was
+ * ~3–4 ms of a ~30 ms budget. {@link validateManifest} is held to the schema's
+ * behaviour by `graphpack.test.ts`, which pins the two to accept the same inputs
+ * in both directions; `schemas.ts` remains the executable specification.
  */
 
 import { existsSync, readFileSync, statSync } from "node:fs";
@@ -12,10 +19,61 @@ import {
   INDEX_FILE,
   MANIFEST_FILE,
   type Manifest,
-  manifestSchema,
   SCHEMA_FILE,
+  STORIES_FILE,
 } from "./types.js";
 
+/** Whether `value` is a plain object of strings — the `prefixes` map's shape. */
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+/**
+ * Validate a parsed `manifest.json` payload structurally.
+ *
+ * Mirrors `manifestSchema` exactly, including its STRIP semantics: a valid
+ * manifest is reconstructed field by field, so an unknown key in the file is
+ * dropped rather than carried into the returned object (zod's `z.object`
+ * default, which several callers rely on when they re-serialize a manifest).
+ *
+ * @param value - The `JSON.parse` result to validate.
+ * @returns The manifest, or `undefined` when the payload does not conform.
+ */
+export function validateManifest(value: unknown): Manifest | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const raw = value as Record<string, unknown>;
+  const { tripleCount, entityCount } = raw;
+  if (
+    typeof raw.name !== "string" ||
+    typeof raw.version !== "string" ||
+    typeof raw.sourceRef !== "string" ||
+    typeof raw.contentHash !== "string" ||
+    typeof raw.createdAt !== "string" ||
+    !isStringRecord(raw.prefixes) ||
+    (tripleCount !== undefined && typeof tripleCount !== "number") ||
+    (entityCount !== undefined && typeof entityCount !== "number")
+  ) {
+    return undefined;
+  }
+  return {
+    name: raw.name,
+    version: raw.version,
+    sourceRef: raw.sourceRef,
+    contentHash: raw.contentHash,
+    prefixes: raw.prefixes,
+    createdAt: raw.createdAt,
+    ...(tripleCount === undefined ? {} : { tripleCount }),
+    ...(entityCount === undefined ? {} : { entityCount }),
+  };
+}
+
 /**
  * Read and validate a pack directory's manifest.
  *
@@ -27,29 +85,73 @@ export function readManifest(dir: string): Manifest | undefined {
   const path = join(dir, MANIFEST_FILE);
   if (!existsSync(path)) return undefined;
   try {
-    return manifestSchema.parse(JSON.parse(readFileSync(path, "utf-8")));
+    return validateManifest(JSON.parse(readFileSync(path, "utf-8")));
   } catch {
     return undefined;
   }
 }
 
 /** Whether a pack directory holds a complete pack: a valid manifest AND every
- * non-empty query artifact — the `data.nq` dump, the extracted `schema.json`,
- * and the entity `index.json`. The manifest alone is not enough: an intact
- * manifest beside a missing/truncated `data.nq` boots EMPTY (a silent, then
- * permanent, loss), and a torn or evicted `schema.json`/`index.json` (manifest +
- * dump intact) would be REUSED by `buildPack` and then fail at BOOT as an
- * internal error. Requiring all three present + non-empty makes `buildPack`
- * rebuild a torn pack and makes the boot decision surface STORE_UNAVAILABLE
- * (the ordinary "not built" recovery) instead of a "please report this" crash. */
+ * non-empty content artifact — the `data.nq` dump, the extracted `schema.json`,
+ * the entity `index.json`, and the carried `stories.json`. The manifest alone is
+ * not enough: an intact manifest beside a missing/truncated `data.nq` boots
+ * EMPTY (a silent, then permanent, loss), and a torn or evicted
+ * `schema.json`/`index.json` (manifest + dump intact) would be REUSED by
+ * `buildPack` and then fail at BOOT as an internal error. `stories.json` is
+ * gated for the same reason and unconditionally: it is written even when empty
+ * (as `[]`, which is non-empty text), so a pack directory lacking it is one
+ * whose content hash covers stories the directory does not hold — reusing it
+ * would silently drop every package-declared noun. Requiring all four present +
+ * non-empty makes `buildPack` rebuild a torn pack and makes the boot decision
+ * surface STORE_UNAVAILABLE (the ordinary "not built" recovery) instead of a
+ * "please report this" crash. `stories.json` is additionally gated on its SHAPE
+ * — see {@link storiesAreReadable} for why it, and only it, is parsed here. */
 export function packIsComplete(dir: string): boolean {
   if (readManifest(dir) === undefined) return false;
-  for (const file of [DATA_FILE, SCHEMA_FILE, INDEX_FILE]) {
+  for (const file of [DATA_FILE, SCHEMA_FILE, INDEX_FILE, STORIES_FILE]) {
     try {
       if (statSync(join(dir, file)).size <= 0) return false;
     } catch {
       return false;
     }
   }
-  return true;
+  return storiesAreReadable(dir);
+}
+
+/**
+ * Whether `stories.json` holds what its reader expects: a JSON ARRAY.
+ *
+ * Size alone was not enough, and stories are the one artifact where that gap is
+ * SILENT. A non-empty but non-array `stories.json` passed the size gate, so
+ * `buildPack` REUSED the directory and every package-declared noun vanished
+ * while `sources update` reported success — with `parseRecords`' fix, without
+ * even an error line to attribute. Parsing it turns that into an incomplete
+ * pack: the boot decision reports the ordinary STORE_UNAVAILABLE and the next
+ * `buildPack` rebuilds, which is the recovery the other three artifacts already
+ * get.
+ *
+ * SHAPE ONLY, deliberately: `Array.isArray`, not a check of the records inside.
+ * A malformed or schema-invalid RECORD is the one guard in
+ * `packs/collect.validateStories`, which names it on stderr and under `doctor`
+ * — a story a third party got wrong must not make the whole pack unreadable.
+ *
+ * `data.nq` and `schema.json` stay SIZE-gated on purpose. A truncated `data.nq`
+ * is caught downstream by `readPack`'s A9 triple-count cross-check, which is
+ * stronger than any parse here; a corrupt `schema.json` still surfaces
+ * unclassified, and that gap is pinned separately rather than absorbed into this
+ * one — this is the fast path, and it parses only the artifact whose failure is
+ * otherwise invisible.
+ *
+ * @param dir - The pack directory.
+ * @returns Whether the stories artifact parses as an array.
+ * @note Impure — reads from disk.
+ */
+function storiesAreReadable(dir: string): boolean {
+  try {
+    return Array.isArray(
+      JSON.parse(readFileSync(join(dir, STORIES_FILE), "utf-8")),
+    );
+  } catch {
+    return false;
+  }
 }

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" },

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(),
+});