@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -1,14 +1,14 @@
 /**
- * Parse a config `packages` entry into a typed {@link PackageRef}.
+ * Parse a config `packs` declaration into a typed {@link PackageRef}.
  *
  * Ported from the v1 refs domain. Three resolution strategies, discriminated by
  * `kind`: `npm` (a bare package name, resolved via `require.resolve`), `file`
  * (a `file://` local path override), and `git` (a `git+<proto>://…#ref` shallow
- * clone). The `source` string is kept verbatim so the lock records exactly what
- * the config declared.
+ * clone). The `source` string is kept verbatim so `sources status` reports
+ * exactly what the config declared.
  */
 
-import type { PackageEntry } from "../../config/types.js";
+import type { PackDeclaration } from "../../config/types.js";
 import { PragmaError } from "../../error/PragmaError.js";
 
 /** A parsed, validated package reference — discriminated by `kind`. */
@@ -29,13 +29,13 @@ export type PackageRef =
     };
 
 /**
- * Parse a config `packages` entry into a {@link PackageRef}.
+ * Parse a config `packs` declaration into a {@link PackageRef}.
  *
  * @param entry - A bare npm name, or a `{ name, source }` declaration.
  * @returns The parsed reference (with the verbatim `source`).
  * @throws PragmaError CONFIG_ERROR on an invalid `source`.
  */
-export function parsePackageEntry(entry: PackageEntry): PackageRef {
+export function parsePackDeclaration(entry: PackDeclaration): PackageRef {
   if (typeof entry === "string") {
     return { kind: "npm", pkg: entry, source: entry };
   }
@@ -43,7 +43,7 @@ export function parsePackageEntry(entry: PackageEntry): PackageRef {
   const { name, source } = entry;
   if (typeof name !== "string" || name.length === 0) {
     throw PragmaError.configError(
-      'Package entry must have a non-empty "name".',
+      'Pack declaration must have a non-empty "name".',
     );
   }
   if (source === undefined) {

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

@@ -2,27 +2,26 @@
  * Resolve a {@link PackageRef} to its pinned revision and RDF source contents.
  *
  * `file` reads the local path in place; `npm` resolves the installed package
- * from the project's `node_modules`; `git` clones/fetches into the ref cache
- * (or, under `--frozen`, checks out exactly the lock's pinned commit and never
- * advances). Each package contributes its `definitions/**` and `data/**` TTL
- * files, labelled by a stable `pkg/relative-path` so the pack's content hash is
- * machine-independent. Reached only from the `sources update` Task body.
+ * from the project's `node_modules`; `git` clones/fetches into the ref cache.
+ * A ref that is already a commit SHA resolves to exactly that commit, which is
+ * how a project pins a revision. Each package contributes its `definitions/**`
+ * and `data/**` TTL files plus any `stories/*.json` it ships, labelled by a
+ * stable `pkg/relative-path` so the pack's content hash is machine-independent.
+ * Reached only from the `sources update` Task body.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, relative } from "node:path";
-import { RECOVERY_CLI_PREFIX } from "../../../constants.js";
 import { PragmaError } from "../../error/PragmaError.js";
-import { cliRecovery } from "../../error/recovery.js";
 import { refsCacheDir } from "../paths.js";
-import { checkoutCommit, cloneRef, fetchRef, headCommit } from "./gitOps.js";
+import { cloneRef, fetchRef, headCommit } from "./gitOps.js";
 import { type PackageRef, redactUrl } from "./parseRef.js";
 
 /** A resolved package: its pinned revision and labelled RDF sources. */
 export interface ResolvedPackage {
   readonly name: string;
-  /** The config `packages` source ref, verbatim. */
+  /** The config `packs` source ref, verbatim. */
   readonly source: string;
   /** The resolved commit / version / absolute path. */
   readonly resolved: string;
@@ -34,19 +33,26 @@ export interface ResolvedPackage {
   readonly root: string;
   /** The labelled RDF sources (path label + content). */
   readonly sources: { readonly path: string; readonly content: string }[];
+  /**
+   * The package's `stories/*.json` files, as RAW TEXT — never parsed here. The
+   * pack carries the package's bytes verbatim so every interpretation failure
+   * (malformed JSON and schema-invalid JSON alike) is caught behind one guard
+   * at dispatch instead of two half-guards at two layers.
+   */
+  readonly stories: { readonly path: string; readonly content: string }[];
 }
 
-/** Options for a resolution: whether to honour a pinned commit (`--frozen`). */
+/** Options for a resolution — the project directory an `npm` ref resolves from. */
 export interface ResolveOptions {
   readonly cwd: string;
-  readonly frozen: boolean;
-  /** The lock's pinned revision for this package (used under `--frozen`). */
-  readonly pinned?: string;
 }
 
 /** The package subdirectories scanned for `.ttl` sources. */
 const TTL_DIRS = ["definitions", "data"];
 
+/** The package subdirectory whose immediate `*.json` children are read stories. */
+const STORIES_DIR = "stories";
+
 /** Sanitize a ref for use as a cache path segment. */
 const sanitize = (value: string): string => value.replace(/[/\\:*?"<>|]/g, "_");
 
@@ -84,9 +90,28 @@ function walkTtl(
     // build (a `.`-prefixed Turtle local name isn't even valid).
     if (entry.name.startsWith(".")) continue;
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
+    // Resolve symlinks: pnpm / workspace trees link their sources, but
+    // `Dirent.isFile`/`isDirectory` are BOTH false for a symlink — so a
+    // symlinked `.ttl` was silently skipped (L6). Follow the link to recover a
+    // symlinked FILE, but NEVER recurse into a symlinked DIRECTORY: a symlink
+    // cycle (a link to an ancestor dir) would recurse without bound — a
+    // stack-overflow RangeError surfacing as an INTERNAL "please report" — and a
+    // linked directory could pull `.ttl` from OUTSIDE the package root. Linking
+    // individual source files (all L6 needs) stays supported; a dangling link is
+    // skipped, not fatal.
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        isFile = statSync(full).isFile();
+        isDir = false;
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
       walkTtl(full, base, label, out);
-    } else if (entry.isFile() && entry.name.endsWith(".ttl")) {
+    } else if (isFile && entry.name.endsWith(".ttl")) {
       out.push({
         path: `${label}/${relative(base, full)}`,
         content: readFileSync(full, "utf-8"),
@@ -108,6 +133,47 @@ function readTtlSources(
   return sources;
 }
 
+/**
+ * Read a package's `stories/*.json` as raw text, with stable labels.
+ *
+ * IMMEDIATE children only — the same discipline `skills/` uses, and recursion
+ * buys nothing. Hidden entries are skipped and a symlinked FILE is followed but
+ * a symlinked DIRECTORY is never recursed into, exactly as {@link walkTtl}
+ * argues. Sorted so the pack's content hash does not depend on readdir order.
+ *
+ * @param rootDir - The package root.
+ * @param label - The package name, used as the label prefix.
+ * @returns The labelled story files (`pkg/stories/name.json` + raw content).
+ * @note Impure — reads from disk.
+ */
+function readStorySources(
+  rootDir: string,
+  label: string,
+): { path: string; content: string }[] {
+  const dir = join(rootDir, STORIES_DIR);
+  if (!existsSync(dir)) return [];
+  const stories: { path: string; content: string }[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || !entry.name.endsWith(".json")) continue;
+    const full = join(dir, entry.name);
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        isFile = statSync(full).isFile();
+      } catch {
+        continue;
+      }
+    }
+    if (!isFile) continue;
+    stories.push({
+      path: `${label}/${STORIES_DIR}/${entry.name}`,
+      content: readFileSync(full, "utf-8"),
+    });
+  }
+  stories.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return stories;
+}
+
 /**
  * A Turtle/SPARQL prefix prologue declaration: `@prefix ex: <iri> .` or the
  * keyword-form `PREFIX ex: <iri>`. Both are legal in Turtle 1.1; the keyword is
@@ -143,6 +209,47 @@ export function harvestPrefixes(
   return prefixes;
 }
 
+/** One `@prefix` clash: a label declared with two or more distinct IRIs. */
+export interface PrefixClash {
+  readonly label: string;
+  /** The distinct IRIs bound to the label, in first-seen order. */
+  readonly iris: readonly string[];
+}
+
+/**
+ * Detect `@prefix` label clashes across a set of sources.
+ *
+ * {@link harvestPrefixes} resolves clashes last-wins (Turtle's own rule),
+ * silently compacting the losing package's URIs to the wrong prefix (or to full
+ * IRIs). This surfaces the clashes so `sources update` can warn (A5): a label
+ * bound to two or more distinct IRIs. Harmless same-label/same-IRI
+ * redeclarations (the common case) are NOT clashes. Result is sorted by label
+ * so the warnings are deterministic.
+ *
+ * @param sources - The packages' labelled RDF sources.
+ * @returns One entry per clashing label, each with its distinct IRIs.
+ */
+export function detectPrefixClashes(
+  sources: readonly { readonly content: string }[],
+): PrefixClash[] {
+  const byLabel = new Map<string, string[]>();
+  for (const { content } of sources) {
+    for (const match of content.matchAll(PREFIX_DECL)) {
+      const [, label, iri] = match;
+      if (label === undefined || iri === undefined) continue;
+      const iris = byLabel.get(label) ?? [];
+      if (!iris.includes(iri)) iris.push(iri);
+      byLabel.set(label, iris);
+    }
+  }
+  const clashes: PrefixClash[] = [];
+  for (const [label, iris] of byLabel) {
+    if (iris.length > 1) clashes.push({ label, iris });
+  }
+  clashes.sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+  return clashes;
+}
+
 /**
  * Locate a package's `package.json` from the project.
  *
@@ -194,31 +301,15 @@ export function resolvePackageJson(
  * Resolve a package reference to its revision and RDF sources.
  *
  * @param ref - The parsed package reference.
- * @param options - The cwd, frozen flag, and any pinned revision.
+ * @param options - The project directory an `npm` ref resolves from.
  * @returns The resolved package.
  * @throws PragmaError on a missing file path or unresolvable npm package.
- * @throws PragmaError under `--frozen` when the package has no lock entry.
  * @note Impure — may clone/fetch git, reads TTL from disk.
  */
 export async function resolvePackage(
   ref: PackageRef,
   options: ResolveOptions,
 ): Promise<ResolvedPackage> {
-  // `--frozen` means "reproduce the locked state exactly". A configured package
-  // with no lock entry has nothing to reproduce, so refuse rather than silently
-  // resolving it fresh (which would advance the very state the lock pins).
-  if (options.frozen && options.pinned === undefined) {
-    throw PragmaError.configError(
-      `Cannot resolve "${ref.pkg}" under --frozen: it has no entry in the lock.`,
-      {
-        recovery: cliRecovery(
-          `${RECOVERY_CLI_PREFIX}sources update`,
-          "Update the lock without --frozen, then commit it.",
-        ),
-      },
-    );
-  }
-
   switch (ref.kind) {
     case "file": {
       if (!existsSync(ref.path)) {
@@ -232,6 +323,7 @@ export async function resolvePackage(
         resolved: ref.path,
         root: ref.path,
         sources: readTtlSources(ref.path, ref.pkg),
+        stories: readStorySources(ref.path, ref.pkg),
       };
     }
 
@@ -262,22 +354,15 @@ export async function resolvePackage(
         resolved: version,
         root: dir,
         sources: readTtlSources(dir, ref.pkg),
+        stories: readStorySources(dir, ref.pkg),
       };
     }
 
     case "git": {
-      const useCommit = options.frozen && options.pinned;
-      const dir = join(
-        refsCacheDir(),
-        sanitize(ref.pkg),
-        sanitize(useCommit ? (options.pinned as string) : ref.ref),
-      );
+      const dir = join(refsCacheDir(), sanitize(ref.pkg), sanitize(ref.ref));
       let resolved: string;
       try {
-        if (useCommit) {
-          checkoutCommit(ref.url, options.pinned as string, dir);
-          resolved = options.pinned as string;
-        } else if (existsSync(dir)) {
+        if (existsSync(dir)) {
           resolved = fetchRef(ref.url, ref.ref, dir);
         } else {
           cloneRef(ref.url, ref.ref, dir);
@@ -285,28 +370,18 @@ export async function resolvePackage(
         }
       } catch (error) {
         // A git clone/fetch/checkout failed — an unreachable remote, a moved or
-        // deleted ref, an auth/credential problem, or (under --frozen) a pinned
-        // commit that is gone. Name the package + ref with git's own reason so
-        // it reads as a fixable data/reproducibility error, not INTERNAL_ERROR.
-        throw useCommit
-          ? PragmaError.configError(
-              `Cannot reproduce "${ref.pkg}" under --frozen: commit ${options.pinned} could not be checked out from ${redactUrl(ref.url)}. ${errorDetail(error)}`,
-              {
-                recovery: {
-                  message:
-                    "The pinned commit may have been force-pushed away or the remote is unreachable. Restore access to it, or re-run `pragma sources update` without --frozen to re-pin.",
-                },
-              },
-            )
-          : PragmaError.configError(
-              `Cannot resolve "${ref.pkg}" from ${redactUrl(ref.url)}#${ref.ref}: ${errorDetail(error)}`,
-              {
-                recovery: {
-                  message:
-                    "Check the git URL and ref, your network, and your git credentials, then re-run the update.",
-                },
-              },
-            );
+        // deleted ref, an auth/credential problem, or a pinned SHA that has been
+        // force-pushed away. Name the package + ref with git's own reason so it
+        // reads as a fixable data error, not INTERNAL_ERROR.
+        throw PragmaError.configError(
+          `Cannot resolve "${ref.pkg}" from ${redactUrl(ref.url)}#${ref.ref}: ${errorDetail(error)}`,
+          {
+            recovery: {
+              message:
+                "Check the git URL and ref, your network, and your git credentials, then re-run the update.",
+            },
+          },
+        );
       }
       return {
         name: ref.pkg,
@@ -314,6 +389,7 @@ export async function resolvePackage(
         resolved,
         root: dir,
         sources: readTtlSources(dir, ref.pkg),
+        stories: readStorySources(dir, ref.pkg),
       };
     }
   }

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

@@ -1,11 +1,10 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { ConfigLayers } from "../config/types.js";
 import { loadStoreSession } from "./loadSession.js";
-import { writeLock } from "./lock.js";
-import { packDir } from "./paths.js";
+import { activePackPath, packDir } from "./paths.js";
 import { resolveSources } from "./resolveSources.js";
 
 /**
@@ -21,24 +20,21 @@ const tmp = (): string => {
   return dir;
 };
 
-/** Config layers whose only relevant knob is the `packages` origin. */
-function layersWith(packagesOrigin: "default" | "project"): ConfigLayers {
+/** Config layers whose only relevant knob is the `packs` origin. */
+function layersWith(packsOrigin: "default" | "project"): ConfigLayers {
   return {
     config: {
       channel: "normal",
-      packages:
-        packagesOrigin === "project"
-          ? [{ name: "x", source: "file:///x" }]
-          : [],
+      packs:
+        packsOrigin === "project" ? [{ name: "x", source: "file:///x" }] : [],
     },
     origins: {
       tier: "default",
       channel: "default",
       detail: "default",
-      packages: packagesOrigin,
+      packs: packsOrigin,
       stories: "default",
       prefixes: "default",
-      prompts: "default",
     },
     global: { path: "/nonexistent", exists: false },
     project: { exists: false },
@@ -67,10 +63,18 @@ function writeCompletePack(hash: string): string {
   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);
   return dir;
 }
 
+/** Plant the active-pack pointer a `sources update` would have written. */
+function writePointer(cwd: string, content: string): void {
+  const path = activePackPath(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
 beforeEach(() => {
   roots = [];
 });
@@ -79,11 +83,11 @@ afterEach(() => {
 });
 
 describe("resolveSources decision table", () => {
-  it("lock present + pack cached → load the locked pack", () => {
+  it("pointer present + pack cached → load the built pack", () => {
     const cwd = tmp();
     const hash = "a".repeat(64);
     const dir = writeCompletePack(hash);
-    writeLock(cwd, { version: 1, contentHash: hash, packs: [] });
+    writePointer(cwd, hash);
 
     expect(resolveSources(layersWith("default"), cwd)).toEqual({
       kind: "pack",
@@ -92,46 +96,81 @@ describe("resolveSources decision table", () => {
     });
   });
 
-  it("lock present + pack evicted → STORE_UNAVAILABLE", () => {
+  it("pointer present + pack evicted → STORE_UNAVAILABLE", () => {
     const cwd = tmp();
-    // A lock whose content-addressed pack is absent from the cache.
-    writeLock(cwd, { version: 1, contentHash: "b".repeat(64), packs: [] });
+    // A pointer whose content-addressed pack is absent from the cache.
+    writePointer(cwd, "b".repeat(64));
 
     expect(resolveSources(layersWith("default"), cwd)).toEqual({
       kind: "unavailable",
-      reason: "the locked pack is missing from the cache",
+      reason: "the built pack is missing from the cache",
     });
   });
 
-  it("lock present + pack with a torn schema/index → STORE_UNAVAILABLE", () => {
+  it("pointer present + pack with a torn schema/index → STORE_UNAVAILABLE", () => {
     const cwd = tmp();
     const hash = "c".repeat(64);
     // manifest + non-empty dump present, but the extracted schema/index are
     // missing (a torn or partially-evicted pack). This used to slip through
     // `packIsComplete` and then crash at read time as an INTERNAL error; it must
-    // now be treated as not-built so the boot surfaces STORE_UNAVAILABLE.
+    // now be treated as not-built so the boot surfaces STORE_UNAVAILABLE — and
+    // say INCOMPLETE, not "missing", because the directory is right there. This
+    // is also the shape every pack built before `stories.json` now takes.
     const dir = packDir(hash);
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, "data.nq"), "<urn:s> <urn:p> <urn:o> .\n");
     writeManifest(dir, hash);
-    writeLock(cwd, { version: 1, contentHash: hash, packs: [] });
+    writePointer(cwd, hash);
+
+    expect(resolveSources(layersWith("default"), cwd)).toEqual({
+      kind: "unavailable",
+      reason: "the built pack is incomplete — an older or torn build",
+    });
+  });
+
+  it("pointer present + a pack whose stories.json is not an array → STORE_UNAVAILABLE", () => {
+    const cwd = tmp();
+    const hash = "d".repeat(64);
+    const dir = writeCompletePack(hash);
+    // Every file present and non-empty, but `stories.json` holds an object.
+    // Gated on size alone this passed, so `buildPack` REUSED the directory and
+    // every package-declared noun disappeared while `sources update` reported
+    // success. It is a torn build like any other, and says so.
+    writeFileSync(join(dir, "stories.json"), '{"noun":"recipe"}');
+    writePointer(cwd, hash);
 
     expect(resolveSources(layersWith("default"), cwd)).toEqual({
       kind: "unavailable",
-      reason: "the locked pack is missing from the cache",
+      reason: "the built pack is incomplete — an older or torn build",
+    });
+  });
+
+  it("a malformed pointer is treated as absent, not as a pack name", () => {
+    // A truncated/garbage pointer must never name a cache directory. With
+    // default packs it falls through to the embedded row, exactly as no
+    // pointer at all would.
+    const cwd = tmp();
+    writePointer(cwd, "not-a-content-hash\n");
+
+    expect(resolveSources(layersWith("default"), cwd)).toEqual({
+      kind: "embedded",
+    });
+    expect(resolveSources(layersWith("project"), cwd)).toEqual({
+      kind: "unavailable",
+      reason: "packs are configured but the store has not been built",
     });
   });
 
-  it("no lock + default packages → embedded fallback", () => {
+  it("no pointer + default packs → embedded fallback", () => {
     expect(resolveSources(layersWith("default"), tmp())).toEqual({
       kind: "embedded",
     });
   });
 
-  it("no lock + packages configured → STORE_UNAVAILABLE", () => {
+  it("no pointer + packs configured → STORE_UNAVAILABLE", () => {
     expect(resolveSources(layersWith("project"), tmp())).toEqual({
       kind: "unavailable",
-      reason: "packages are configured but the store has not been built",
+      reason: "packs are configured but the store has not been built",
     });
   });
 });

package/src/kernel/runtime/resolveSources.ts

@@ -1,26 +1,33 @@
 /**
  * The store-boot decision table — storeless, and the single place the boot
- * strategy is decided.
+ * strategy is decided. No other module re-derives it: `sources status`, `info`,
+ * `doctor`, and the native MCP prompt/resource surfaces all switch on what this
+ * returns (`readPackIndex` takes the decision rather than resolving a pack of
+ * its own). The one module that cannot is the shell-completion fast path, which
+ * is denied the config evaluator and so implements the pointer half only — it
+ * says so, and it answers with completion candidates, never content.
  *
- * Boot never touches the network. From the lock and the resolved config:
+ * Boot never touches the network. From the project's active-pack pointer (the
+ * content hash `sources update` last built here) and the resolved config:
  *
- * | lock present | pack cached | packages origin | → decision            |
- * |--------------|-------------|-----------------|-----------------------|
- * | yes          | yes         | —               | load the locked pack  |
- * | yes          | no          | —               | STORE_UNAVAILABLE     |
- * | no           | —           | default         | embedded fallback     |
- * | no           | —           | configured      | STORE_UNAVAILABLE     |
+ * | pointer | pack complete | packs origin | → decision            |
+ * |---------|---------------|--------------|-----------------------|
+ * | yes     | yes           | —            | load the built pack   |
+ * | yes     | no            | —            | STORE_UNAVAILABLE     |
+ * | no      | —             | default      | embedded fallback     |
+ * | no      | —             | configured   | STORE_UNAVAILABLE     |
  *
- * A configured-but-unbuilt store (or a lock whose pack the cache lost)
+ * A configured-but-unbuilt store (or a pointer whose pack the cache lost)
  * surfaces STORE_UNAVAILABLE with a single recovery: `pragma sources update`.
- * "packages origin default" means the user has not pinned their own packages —
- * a fresh install — so the embedded fallback answers reads offline.
+ * "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.
  */
 
+import { existsSync } from "node:fs";
 import type { ConfigLayers } from "../config/types.js";
 import { packIsComplete } from "./graphpack/manifest.js";
-import { readLock } from "./lock.js";
-import { packDir } from "./paths.js";
+import { packDir, readActivePack } from "./paths.js";
 
 /** The resolved boot strategy. */
 export type SourcesDecision =
@@ -35,32 +42,36 @@ export type SourcesDecision =
 /**
  * Decide how (or whether) to boot the store — without any network or store I/O.
  *
- * @param layers - The resolved config layers (for the `packages` origin).
- * @param cwd - The project directory (for the lock).
+ * @param layers - The resolved config layers (for the `packs` origin).
+ * @param cwd - The project directory (for the active-pack pointer).
  * @returns The boot decision.
- * @note Impure — reads the lock and probes the pack cache.
+ * @note Impure — reads the pointer and probes the pack cache.
  */
 export function resolveSources(
   layers: ConfigLayers,
   cwd: string,
 ): SourcesDecision {
-  const lock = readLock(cwd);
-  if (lock) {
-    const dir = packDir(lock.contentHash);
-    if (packIsComplete(dir)) {
-      return { kind: "pack", dir, contentHash: lock.contentHash };
-    }
+  const contentHash = readActivePack(cwd);
+  if (contentHash !== undefined) {
+    const dir = packDir(contentHash);
+    if (packIsComplete(dir)) 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
+    // four-file pack lands in, where "missing" is plainly contradicted by `ls`.
     return {
       kind: "unavailable",
-      reason: "the locked pack is missing from the cache",
+      reason: existsSync(dir)
+        ? "the built pack is incomplete — an older or torn build"
+        : "the built pack is missing from the cache",
     };
   }
 
-  if (layers.origins.packages === "default") {
+  if (layers.origins.packs === "default") {
     return { kind: "embedded" };
   }
   return {
     kind: "unavailable",
-    reason: "packages are configured but the store has not been built",
+    reason: "packs are configured but the store has not been built",
   };
 }