@canonical/pragma-cli 0.32.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,12 +1,30 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+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#",
@@ -26,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;
@@ -49,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 }]);
@@ -103,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 ." };
@@ -128,6 +285,117 @@ describe("graphpack hash stability (PROTECTED)", () => {
   });
 });
 
+describe("graphpack manifest — persisted counts (A9/A10)", () => {
+  it("records tripleCount and a distinct-abox entityCount", async () => {
+    const { dir } = await build([{ path: "a.ttl", content: TTL }]);
+    const manifest = JSON.parse(
+      readFileSync(join(dir, MANIFEST_FILE), "utf-8"),
+    ) as { tripleCount?: number; entityCount?: number };
+    expect(typeof manifest.tripleCount).toBe("number");
+    expect(manifest.tripleCount ?? 0).toBeGreaterThan(0);
+    // TTL declares two individuals (ex:Button, ex:Card) → two abox subjects.
+    expect(manifest.entityCount).toBe(2);
+  });
+});
+
+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.
+    const uniqueTtl = `${TTL}\nex:Truncated a ex:Component ; rdfs:label "Truncated" .\n`;
+    const { dir } = await build([{ path: "trunc.ttl", content: uniqueTtl }]);
+    const dataPath = join(dir, DATA_FILE);
+    const lines = readFileSync(dataPath, "utf-8")
+      .split("\n")
+      .filter((line) => line.trim() !== "");
+    expect(lines.length).toBeGreaterThan(1);
+    // Drop the last statement: the dump is now a PARTIAL graph — still
+    // non-empty (so it passes the size>0 completeness gate) but fewer triples
+    // than the manifest recorded, which the boot cross-check must catch.
+    writeFileSync(dataPath, `${lines.slice(0, -1).join("\n")}\n`);
+
+    let caught: unknown;
+    try {
+      const session = await readPack(dir);
+      session.store.dispose();
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "STORE_UNAVAILABLE" });
+  });
+
+  it("tolerates a benign superset (actual > recorded), not corruption", async () => {
+    // A future ke counting change could load MORE triples than the manifest
+    // recorded. That is not truncation, so boot must NOT reject it — otherwise
+    // one counting change trips a fleet-wide false STORE_UNAVAILABLE. Simulate by
+    // lowering the manifest's tripleCount below the dump's actual count.
+    const uniqueTtl = `${TTL}\nex:Superset a ex:Component ; rdfs:label "Superset" .\n`;
+    const { dir } = await build([{ path: "superset.ttl", content: uniqueTtl }]);
+    const manifestPath = join(dir, MANIFEST_FILE);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as {
+      tripleCount: number;
+    };
+    writeFileSync(
+      manifestPath,
+      JSON.stringify({ ...manifest, tripleCount: manifest.tripleCount - 1 }),
+    );
+
+    // The booted store holds one MORE triple than the (lowered) manifest — a
+    // superset. On the pre-fix exact-equality guard this threw; now it boots.
+    const session = await readPack(dir);
+    expect(session.index.entities.length).toBeGreaterThan(0);
+    session.store.dispose();
+  });
+});
+
 describe("graphpack read — incomplete pack recovery (CLI + MCP)", () => {
   it("an incomplete pack is STORE_UNAVAILABLE with a `sources_update` tool recovery", async () => {
     // A dir with no manifest is an incomplete pack — readPack rejects before any

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;
+  }
 }