@canonical/pragma-cli 0.33.0 → 0.35.0

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, 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 { PragmaError } from "../../error/index.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, "_");
 
@@ -69,7 +75,7 @@ function errorDetail(error: unknown): string {
 }
 
 /** Recursively collect `*.ttl` files under a directory (a manual walk — the
- * compiled binary's node:fs globSync mishandles `**`, so we avoid it). */
+ * node:fs globSync has mishandled `**` under a shipped runtime, so we avoid it). */
 function walkTtl(
   dir: string,
   base: string,
@@ -89,7 +95,7 @@ function walkTtl(
     // 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
+    // stack-overflow RangeError surfacing as an INTERNAL "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.
@@ -127,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
@@ -254,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)) {
@@ -292,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),
       };
     }
 
@@ -311,7 +343,7 @@ export async function resolvePackage(
           "0.0.0";
       } catch (error) {
         // A malformed `package.json` for an otherwise-installed package: name it
-        // as a data error, not an INTERNAL_ERROR "please report this issue".
+        // as a data error, not an INTERNAL_ERROR "report this issue".
         throw PragmaError.configError(
           `Package "${ref.pkg}" has an invalid package.json (${pkgJsonPath}): ${errorDetail(error)}`,
         );
@@ -322,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);
@@ -345,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,
@@ -374,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",
   };
 }

package/src/kernel/runtime/storeReadiness.ts

@@ -12,15 +12,13 @@
  * and one silently-empty list. Centralizing the construction here is what keeps
  * those surfaces from drifting apart.
  *
- * It reaches only {@link resolveSources} (a lock + config probe — no store, no
- * ke), so a caller on the storeless fast path can pre-check availability without
- * ever booting the store.
+ * It reaches only {@link resolveSources} (a pointer + config probe — no store,
+ * no ke), so a caller on the storeless fast path can pre-check availability
+ * without ever booting the store.
  */
 
-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 { cliRecovery, PragmaError } from "../error/index.js";
 import { resolveSources } from "./resolveSources.js";
 
 /**
@@ -28,14 +26,15 @@ import { resolveSources } from "./resolveSources.js";
  * single `pragma sources update` recovery that also names the `sources_update`
  * tool an agent calls (then retries — PR9's C1 cold-store retry succeeds).
  *
- * @param reason - The boot decision's reason (e.g. "the locked pack is missing").
+ * @param reason - The boot decision's reason (e.g. "the built pack is missing
+ *   from the cache").
  * @returns The structured STORE_UNAVAILABLE error.
  */
 export function storeUnavailable(reason: string): PragmaError {
   return PragmaError.storeUnavailable(`${reason}.`, {
     recovery: cliRecovery(
-      `${RECOVERY_CLI_PREFIX}sources update`,
-      "Build the local store from the configured packages.",
+      "sources update",
+      "Build the local store from the configured packs.",
       { tool: "sources_update" },
     ),
   });
@@ -43,7 +42,8 @@ export function storeUnavailable(reason: string): PragmaError {
 
 /**
  * The STORE_UNAVAILABLE error to surface when the store cannot boot from the
- * current config/lock, or `undefined` when a store read may proceed. STORELESS —
+ * current config and active-pack pointer, or `undefined` when a store read may
+ * proceed. STORELESS —
  * probes the decision table only, never constructs the store.
  *
  * @param layers - The resolved config layers.

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

@@ -58,7 +58,7 @@ describe("storeless guarantee — the store never boots for storeless verbs (PRO
     expect(runtime.store.booted).toBe(false);
   });
 
-  it("sources status does not construct the store (reports a cold store)", async () => {
+  it("sources status does not construct the store", async () => {
     const runtime = bootRuntime(FLAGS, freshCwd());
     const outcome = await executeVerb(sourcesStatusVerb, {}, NO_MUT, runtime);
     expect(outcome.exitCode).toBe(0);

package/src/kernel/runtime/types.ts

@@ -21,10 +21,14 @@ export interface GlobalFlags {
   readonly llm: boolean;
   /** True when `llm` was inferred from a non-interactive stdout, not requested. */
   readonly autoLlm?: boolean;
-  /** Selected output format; `--format text` is normalised to `plain`. */
+  /** Selected output format (`plain`, `llm`, or `json` — the full set). */
   readonly format: OutputFormat;
   /** Diagnostic output to stderr. */
   readonly verbose: boolean;
+  /** True when `--no-headers` suppressed the plain-table header row. */
+  readonly noHeaders?: boolean;
+  /** True when `--quiet` suppresses success/progress output (errors keep printing). */
+  readonly quiet?: boolean;
   /** Explicit progressive-disclosure level from `--detail`, if any. */
   readonly detail?: DetailLevel;
 }
@@ -94,6 +98,8 @@ export interface QueryFacade {
 export interface MutationRuntime {
   /** True for a plan-only preview; false for a real execution. */
   readonly preview: boolean;
+  /** True when this invocation reverses a previous run (`--undo`). */
+  readonly undo?: boolean;
 }
 
 /**
@@ -207,4 +213,12 @@ export interface PragmaRuntime {
    * returning the Task, and the projector reads it back on the real-run branch.
    */
   exec?: RunnerOptions;
+  /**
+   * Structured plan data a mutating verb stashes for the `--dry-run` branch to
+   * render through its `output.formatPlan` seam, and to carry verbatim in the
+   * JSON dry-run envelope. NOT readonly, and set the same way `exec` is: the
+   * verb writes it before returning its Task. Unset on every verb that has no
+   * plan of its own, which is what keeps the raw-effect render the default.
+   */
+  planData?: unknown;
 }