@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/testing/helpers/fixtureGraph.ts

@@ -1,6 +1,6 @@
 /**
  * Test helper: boot a store-backed {@link PragmaRuntime} at a REAL `cwd` whose
- * `pragma.lock.json` points at a built fixture pack.
+ * active-pack pointer names a built fixture pack.
  *
  * This is distinct from (and complements) `packRuntime.ts#buildFixtureRuntime`:
  * that helper hands back an in-process runtime wired to a custom `LazyStore`,
@@ -8,14 +8,18 @@
  * generalizes the `runtimeFor` + `buildUpdateTask` pattern proven in
  * `capabilities/sources/sources.test.ts`: it writes an actual
  * `pragma.config.ts` + package directory, runs the REAL `sources update` Task
- * (resolve → build → lock), and returns a `cwd`. Because the lock is a real
- * file, EVERY independent runtime construction that resolves config from that
+ * (resolve → build → point), and returns a `cwd`. Because the pointer is a
+ * real file, EVERY independent runtime construction that resolves config from that
  * `cwd` — `bootRuntime(flags, cwd)` (CLI dispatch), `projectMcp(modules, cwd)`
  * (MCP), and `runCli(args, { cwd })` (spawn) — boots the SAME cached pack. That
  * is the property PR4's cross-surface parity tests need and PR3's single-surface
  * parity tests did not: proof that CLI-json and MCP-json agree over a graph
  * built the same way `sources update` builds one for a real project.
  *
+ * A fixture package may also ship `stories/*.json` (the `stories` option), which
+ * `sources update` carries into the built pack — that is the package tier a
+ * third-party noun arrives through.
+ *
  * Hermetic: the pack cache lives under the isolated `$XDG_CACHE_HOME`
  * `setupXdgIsolation` installs; `dispose()` removes the temp directories (the
  * shared content-addressed pack cache itself is left for reuse/cleanup by the
@@ -30,7 +34,7 @@ import { buildUpdateTask } from "../../capabilities/sources/runUpdate.js";
 import { VERSION } from "../../constants.js";
 import type {
   ConfigLayers,
-  PackageEntry,
+  PackDeclaration,
   PragmaConfig,
 } from "../../kernel/config/types.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
@@ -52,34 +56,39 @@ export interface FixtureGraphOptions {
   readonly ttl: string;
   /**
    * Config fields to bake into the written `pragma.config.ts`, e.g.
-   * `{ tier: "apps/lxd", channel: "prerelease" }`. `packages` is always set by
+   * `{ tier: "apps/lxd", channel: "prerelease" }`. `packs` is always set by
    * this helper (to the fixture package) — do not override it here.
    */
-  readonly config?: Omit<Partial<PragmaConfig>, "packages">;
+  readonly config?: Omit<Partial<PragmaConfig>, "packs">;
+  /**
+   * `stories/*.json` the fixture PACKAGE ships, as raw text keyed by file name
+   * — deliberately raw, so a test can ship malformed or schema-invalid content
+   * and assert that it is dropped rather than fatal.
+   */
+  readonly stories?: Readonly<Record<string, string>>;
 }
 
 /** A booted fixture runtime plus its `cwd` (usable by any surface) and disposal. */
 export interface FixtureGraph {
   /** A REAL `bootRuntime` at {@link cwd} — the same one CLI dispatch uses. */
   readonly runtime: PragmaRuntime;
-  /** The project directory whose `pragma.lock.json`/`pragma.config.ts` were written. */
+  /** The project directory whose `pragma.config.ts` + active-pack pointer were written. */
   readonly cwd: string;
   /** Remove the temp directories and dispose the store session, if booted. */
   dispose(): Promise<void>;
 }
 
 /** A synthetic runtime with an IN-MEMORY config — used only to drive the build Task. */
-function builderRuntime(cwd: string, packages: PackageEntry[]): PragmaRuntime {
+function builderRuntime(cwd: string, packs: PackDeclaration[]): PragmaRuntime {
   const layers: ConfigLayers = {
-    config: { channel: "normal", packages },
+    config: { channel: "normal", packs },
     origins: {
       tier: "default",
       channel: "default",
       detail: "default",
-      packages: "project",
+      packs: "project",
       stories: "default",
       prefixes: "default",
-      prompts: "default",
     },
     global: { path: "/nonexistent", exists: false },
     project: { exists: false },
@@ -102,8 +111,9 @@ function configField(key: string, value: unknown): string {
 }
 
 /**
- * Build a store-backed runtime whose `cwd` carries a real lock file — the ONE
- * shared store-backed fixture path for cross-surface (CLI/MCP/spawn) tests.
+ * Build a store-backed runtime whose `cwd` is pointed at a real built pack —
+ * the ONE shared store-backed fixture path for cross-surface (CLI/MCP/spawn)
+ * tests.
  *
  * @param options - The fixture graph TTL and any config overrides.
  * @returns The runtime, its cwd, and a disposer.
@@ -116,11 +126,18 @@ export async function bootFixtureRuntime(
   const pkgDir = mkdtempSync(join(tmpdir(), "pragma-fixture-pkg-"));
   mkdirSync(join(pkgDir, "definitions"), { recursive: true });
   writeFileSync(join(pkgDir, "definitions", "fixture.ttl"), options.ttl);
+  const stories = Object.entries(options.stories ?? {});
+  if (stories.length > 0) {
+    mkdirSync(join(pkgDir, "stories"), { recursive: true });
+    for (const [file, content] of stories) {
+      writeFileSync(join(pkgDir, "stories", file), content);
+    }
+  }
 
-  const packages: PackageEntry[] = [
+  const packs: PackDeclaration[] = [
     { name: "fixture", source: `file://${pkgDir}` },
   ];
-  const fields = [configField("packages", packages)];
+  const fields = [configField("packs", packs)];
   for (const [key, value] of Object.entries(options.config ?? {})) {
     fields.push(configField(key, value));
   }
@@ -129,7 +146,7 @@ export async function bootFixtureRuntime(
     `export default {\n${fields.join("\n")}\n};\n`,
   );
 
-  await runTask(await buildUpdateTask(builderRuntime(cwd, packages), false));
+  await runTask(await buildUpdateTask(builderRuntime(cwd, packs)));
 
   const runtime = bootRuntime(FIXTURE_FLAGS, cwd);
 

package/src/testing/helpers/packRuntime.ts

@@ -36,7 +36,7 @@ export interface FixtureRuntimeOptions {
   /** Explicit `--detail` level for this invocation. */
   readonly detail?: DetailLevel;
   /** Config `detail` value and its origin (drives {@link resolvePackDetail}). */
-  readonly configDetail?: string;
+  readonly configDetail?: DetailLevel;
   /** Origin of the config `detail` (default `"default"`). */
   readonly detailOrigin?: ConfigOrigin;
 }
@@ -93,10 +93,9 @@ export async function buildFixtureRuntime(
       tier: "default",
       channel: "default",
       detail: options.detailOrigin ?? "default",
-      packages: "default",
+      packs: "default",
       stories: "default",
       prefixes: "default",
-      prompts: "default",
     },
     global: { path: "", exists: false },
     project: { exists: false },

package/src/testing/helpers/projectCli.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Command } from "commander";
+import { BIN_NAME } from "../../constants.js";
 import { buildProgram } from "../../kernel/project/cli/buildProgram.js";
 import type { GlobalFlags } from "../../kernel/runtime/types.js";
 import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
@@ -31,5 +32,5 @@ export function projectCli(
   globalFlags: GlobalFlags = TEST_FLAGS,
 ): Command {
   const verbs: VerbSpec[] = modules.flatMap((module) => [...module.verbs]);
-  return buildProgram(verbs, { globalFlags, programName: "pragma" });
+  return buildProgram(verbs, { globalFlags, programName: BIN_NAME });
 }

package/src/testing/helpers/projectMcp.ts

@@ -10,6 +10,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import type {
   CallToolResult,
+  Resource,
   ServerCapabilities,
 } from "@modelcontextprotocol/sdk/types.js";
 import { buildServer } from "../../kernel/project/mcp/buildServer.js";
@@ -34,14 +35,33 @@ export interface McpHarness {
   ): Promise<Record<string, unknown>>;
   /** List the registered tools. */
   listTools(): Promise<ToolInfo[]>;
-  /** List the resources exposed by the `{+uri}` template's list callback. */
-  listResources(): Promise<{ uri: string; name: string }[]>;
+  /**
+   * List the resources exposed by the `{+uri}` template's list callback.
+   *
+   * The WHOLE wire entry (title, annotations, `_meta`, …), not a projection of
+   * it: the listing's cost and its navigability are both properties of what
+   * actually crosses the wire, and a helper that trimmed the entry would hide
+   * exactly the fields under test.
+   */
+  listResources(): Promise<Resource[]>;
   /** Read one resource by URI; returns the first content's parsed/raw text. */
   readResource(uri: string): Promise<{ mimeType?: string; text: string }>;
-  /** Complete a resource-template variable against a partial value. */
-  completeResource(partial: string): Promise<string[]>;
+  /**
+   * Complete a resource-template variable against a partial value.
+   *
+   * Returns the full completion result — `total` and `hasMore` are derived by
+   * the SDK from the callback's array, so they are the only witness that a
+   * truncated result admits to being truncated.
+   */
+  completeResource(partial: string): Promise<{
+    values: string[];
+    total?: number;
+    hasMore?: boolean;
+  }>;
   /** The server capabilities negotiated at initialize (tools/resources/prompts). */
   serverCapabilities(): ServerCapabilities | undefined;
+  /** The `serverInfo` the server introduced itself with at initialize. */
+  serverInfo(): { name: string; version: string } | undefined;
   /** The server `instructions` string sent at initialize. */
   instructions(): string | undefined;
   /** List the native MCP prompts (`prompts/list`). */
@@ -98,7 +118,7 @@ export async function projectMcp(
     },
     async listResources() {
       const { resources } = await client.listResources();
-      return resources.map((r) => ({ uri: r.uri, name: r.name }));
+      return resources;
     },
     async readResource(uri) {
       const result = await client.readResource({ uri });
@@ -115,11 +135,23 @@ export async function projectMcp(
         ref: { type: "ref/resource", uri: "pragma:{+uri}" },
         argument: { name: "uri", value: partial },
       });
-      return result.completion.values;
+      return {
+        values: result.completion.values,
+        ...(result.completion.total === undefined
+          ? {}
+          : { total: result.completion.total }),
+        ...(result.completion.hasMore === undefined
+          ? {}
+          : { hasMore: result.completion.hasMore }),
+      };
     },
     serverCapabilities() {
       return client.getServerCapabilities();
     },
+    serverInfo() {
+      const info = client.getServerVersion();
+      return info ? { name: info.name, version: info.version } : undefined;
+    },
     instructions() {
       return client.getInstructions();
     },

package/src/testing/helpers/runCli.ts

@@ -1,10 +1,10 @@
 /**
- * Test helper: spawn-and-CAPTURE the real `pragma` binary.
+ * Test helper: spawn-and-CAPTURE the real `pragma` entry point.
  *
  * {@link measureCommand} (the perf helper) discards stdout/stderr — it only
  * times spawns. This is the complementary helper for tests that need to READ
  * what the process printed: the true end-to-end boundary (argv parsing,
- * first-run, the compiled/`bun` entry point, real process exit codes).
+ * first-run, the shipped entry point, real process exit codes).
  *
  * Kept THIN — most behavioral coverage should run in-process via
  * `executeVerb`/`projectCli`/`projectMcp`; reserve `runCli` for tests where the
@@ -18,9 +18,12 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** The compiled binary the perf `globalSetup` guarantees exists before tests run. */
-const COMPILED_BINARY = fileURLToPath(
-  new URL("../../../dist/pragma", import.meta.url),
+/**
+ * The shipped entry the perf `globalSetup` guarantees exists before tests run —
+ * the `bin` the published package points at, run the way a consumer runs it.
+ */
+const SHIPPED_ENTRY = fileURLToPath(
+  new URL("../../../dist/src/bin.js", import.meta.url),
 );
 
 /** The `bin.ts` entry point, for fast source-mode spawns (no rebuild). */
@@ -37,11 +40,12 @@ export interface RunCliOptions {
    */
   readonly env?: Record<string, string | undefined>;
   /**
-   * `"compiled"` (default) spawns `dist/pragma` — the true release boundary.
-   * `"source"` spawns `bun src/bin.ts` — faster, no rebuild required, for
-   * journeys that do not test the compiled-binary boundary itself.
+   * `"shipped"` (default) spawns `node dist/src/bin.js` — the true release
+   * boundary, exactly what a consumer's `pragma` runs. `"source"` spawns
+   * `bun src/bin.ts` — faster, no rebuild required, for journeys that do not
+   * test the shipped-entry boundary itself.
    */
-  readonly mode?: "compiled" | "source";
+  readonly mode?: "shipped" | "source";
   /** Spawn timeout in milliseconds (default 20000). */
   readonly timeoutMs?: number;
 }
@@ -76,7 +80,7 @@ function seededXdgConfigHome(): string {
 /**
  * Spawn the real `pragma` CLI and capture its output.
  *
- * @param args - Argv passed to the binary (no `pragma`/`bun` prefix).
+ * @param args - Argv passed to the CLI (no `pragma`/runtime prefix).
  * @param options - cwd, env overrides, mode, and timeout.
  * @returns The captured stdout/stderr/exitCode/signal.
  * @note Impure — spawns a child process.
@@ -85,17 +89,30 @@ export function runCli(
   args: readonly string[],
   options: RunCliOptions = {},
 ): RunCliResult {
-  const mode = options.mode ?? "compiled";
-  const command = mode === "compiled" ? COMPILED_BINARY : "bun";
-  const spawnArgs = mode === "compiled" ? [...args] : [SOURCE_ENTRY, ...args];
+  const mode = options.mode ?? "shipped";
+  // Both modes spawn a RUNTIME with an entry argument now — the built entry is
+  // emitted JavaScript, not a self-executing binary, so `node` names it.
+  const command = mode === "shipped" ? process.execPath : "bun";
+  const entry = mode === "shipped" ? SHIPPED_ENTRY : SOURCE_ENTRY;
+  const spawnArgs = [entry, ...args];
+
+  // Colour OFF by default: these tests assert on bytes, and nx exports
+  // FORCE_COLOR to its test tasks, so a spawned CLI colours its help even
+  // through a pipe — green locally, red in CI, for a difference no assertion
+  // meant to make. NO_COLOR is the one convention the style seam obeys
+  // unconditionally. FORCE_COLOR is DELETED rather than overridden: Bun warns
+  // on stderr when it sees both, and stderr is part of what is asserted.
+  // `options.env` still wins, so a test that wants colour asks for it.
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    NO_COLOR: "1",
+    XDG_CONFIG_HOME: seededXdgConfigHome(),
+  };
+  delete env.FORCE_COLOR;
 
   const result = spawnSync(command, spawnArgs, {
     cwd: options.cwd,
-    env: {
-      ...process.env,
-      XDG_CONFIG_HOME: seededXdgConfigHome(),
-      ...options.env,
-    },
+    env: { ...env, ...options.env },
     encoding: "utf-8",
     timeout: options.timeoutMs ?? 20_000,
   });

package/src/testing/perf/budgets.test.ts

@@ -15,8 +15,19 @@ import {
 } from "./budgets.js";
 import { measureCommand, percentile, trimmedMean } from "./measure.js";
 
-/** The compiled binary the perf globalSetup guarantees exists. */
-const BINARY = fileURLToPath(new URL("../../../dist/pragma", import.meta.url));
+/**
+ * The shipped entry the perf globalSetup guarantees exists, spawned through
+ * `node` — which is what a consumer's `pragma` does, so node's own startup is
+ * inside every sample rather than excluded from it. The budgets below are
+ * ceilings on what a user waits, not on what a bundler produced.
+ */
+const NODE = process.execPath;
+const ENTRY = fileURLToPath(
+  new URL("../../../dist/src/bin.js", import.meta.url),
+);
+
+/** Argv for one CLI invocation through the shipped entry. */
+const cli = (...args: string[]): string[] => [ENTRY, ...args];
 
 /** Fresh XDG dirs so spawned runs never touch real state (and first-run is isolated). */
 const perfEnv = {
@@ -25,7 +36,7 @@ const perfEnv = {
 };
 
 /**
- * Protected budget suite. Spawns the standalone `dist/pragma`, discards
+ * Protected budget suite. Spawns the shipped entry through `node`, discards
  * warmups, and asserts median + p95 against the ceilings in budgets.ts. Given
  * spawn-time variance, each spawn case retries.
  */
@@ -45,7 +56,7 @@ describe("perf budgets (PROTECTED)", () => {
   });
 
   it("pragma --help stays under budget", { retry: 2 }, () => {
-    const result = measureCommand(BINARY, ["--help"], {
+    const result = measureCommand(NODE, cli("--help"), {
       runs: 15,
       warmups: 3,
       env: perfEnv,
@@ -55,7 +66,7 @@ describe("perf budgets (PROTECTED)", () => {
   });
 
   it("pragma __complete stays under budget", { retry: 3 }, () => {
-    const result = measureCommand(BINARY, ["__complete", "config"], {
+    const result = measureCommand(NODE, cli("__complete", "config"), {
       runs: 30,
       warmups: 5,
       env: perfEnv,
@@ -77,8 +88,8 @@ describe("perf budgets (PROTECTED)", () => {
     // dir → an empty walk, but it exercises the discoverSkills path per spawn;
     // enforce the same robust statistic as the noun case.
     const result = measureCommand(
-      BINARY,
-      ["__complete", "skill", "lookup", "do"],
+      NODE,
+      cli("__complete", "skill", "lookup", "do"),
       {
         runs: 30,
         warmups: 5,
@@ -94,9 +105,13 @@ describe("perf budgets (PROTECTED)", () => {
 
   it("warm store-backed verb stays under budget", { retry: 2 }, () => {
     // __store-probe boots the embedded pack from its n-quads cache and queries
-    // it — the full store-backed verb cost in the compiled binary. The first
+    // it — the full store-backed verb cost through the shipped entry. The first
     // spawn materializes the pack; warmups absorb it, then it is a cache hit.
-    const result = measureCommand(BINARY, ["__store-probe"], {
+    // Note that with 9 kept samples a nearest-rank p95 IS the maximum (see
+    // BUDGETS.md's p95-stabilization section) — deliberately kept, because the
+    // honest statistic here is the one that catches real cost, and the ceiling
+    // is sized with a 1.25× margin over a projected p95 to absorb it.
+    const result = measureCommand(NODE, cli("__store-probe"), {
       runs: 12,
       warmups: 3,
       env: {

package/src/testing/perf/budgets.ts

@@ -1,30 +1,94 @@
 /**
- * Performance budgets for the compiled `pragma` binary.
+ * Performance budgets for the shipped `pragma` entry.
  *
  * The ceilings the protected budget tests assert against. The surface
  * covenant's designed target for `--help`/`__complete` is 50 ms; the day-1 perf
- * spike (commit 6) found that unrealistic on the build hardware (cold Bun
- * process start alone is ~45 ms here), so — per the plan — each ceiling is set
- * to roughly 2× the measured median rather than silently weakening the target.
- * Measured numbers and environment are recorded in BUDGETS.md.
+ * spike (commit 6) found that unrealistic on the build hardware (cold process
+ * start alone is ~45 ms here), so — per the plan — those ceilings are set to
+ * roughly 2× the measured median rather than silently weakening the target.
+ *
+ * A CEILING IS RELATIVE TO THE ARTIFACT IT WAS MEASURED ON. These were derived
+ * against a `bun build --compile` executable. The distribution now ships
+ * JavaScript that `node` executes, which costs roughly 2× on the fast paths, so
+ * a ceiling set at 2× the binary's median lands at the emit's median — where it
+ * cannot separate a regression from a slow runner. `__complete` proved that
+ * exactly: three CI attempts at 100.15, 100.20 and 100.37 ms against a 100 ms
+ * ceiling. Re-derived below on the same rule, against the artifact that now
+ * ships; the designed 50 ms target is recorded as unmet rather than quietly
+ * moved. {@link BUDGET_WARM_STORE_MS} is derived differently (from a projected
+ * p95, and it lands TIGHTER than 2× its median); its arithmetic is written out
+ * in full in BUDGETS.md, as are the measurements and environment for all of
+ * them.
  */
 
-/** `pragma --help` ceiling (ms). Designed 50; measured median ~61 → 2×. */
+/**
+ * `pragma --help` ceiling (ms). Designed 50; the rule is 2× the measured median.
+ *
+ * Down from the provisional 220, which covered the create surface's eager
+ * registration imports on the capabilities barrel. Those are gone — the
+ * registered flag spellings are baked into `createSurface.generated.ts` at
+ * build time, the mount's adapter loads behind `CliProjection.prepare()`, and
+ * the bare-help path no longer loads Commander at all — and the lazy-graph
+ * guard in `lazy.test.ts` pins all three so the cost cannot creep back
+ * silently.
+ *
+ * MEASURED, paired: the pre-refactor tree and this one were each built and
+ * spawned alternately, 40 kept samples per cell, so drift on a shared box hits
+ * both arms. Median 74.6 → 64.7 ms; net of each arm's own `--version` control,
+ * the work this path does went 49.3 → 35.3 ms (−28%). 2 × 64.7 = 129.5, so
+ * 130 is the rule's own number rather than a number the rule tolerates. It is
+ * also where this path sat before the regression. BUDGETS.md carries the full
+ * table, the reference-box projection, and why this is the floor.
+ */
 export const BUDGET_HELP_MS = 130;
 
-/** `pragma __complete …` ceiling (ms). Designed 50; measured median ~46 → 2×. */
-export const BUDGET_COMPLETE_MS = 100;
+/**
+ * `pragma __complete …` ceiling (ms). Designed 50 — **not met, and recorded as
+ * such**: the shipped entry cannot reach it, because node's own start is most
+ * of that number before pragma runs a line.
+ *
+ * Down from the provisional 220 for the same reason as {@link BUDGET_HELP_MS}:
+ * the eager create-surface imports both fast paths paid for are deferred, and
+ * completion additionally sheds Commander — nothing on the `__complete`
+ * closure imports it any more.
+ *
+ * MEASURED in the same paired run: median 79.1 → 69.2 ms for the noun case and
+ * 74.2 → 69.3 ms for the name-source case; net of the control, 53.7 → 39.7 ms
+ * and 48.9 → 39.8 ms.
+ *
+ * 2× the slower median is 138.5, BELOW this 150 — and it stays 150 anyway,
+ * because a ceiling is relative to the box as well as the artifact. This box's
+ * cold start is 25–30 ms against the reference box's 45.5; projecting the
+ * measured work onto the reference box gives a ~85 ms median, whose 2× is
+ * ~170. CI has already run this path at a ~100 ms trimmed mean. Cutting to 140
+ * on a local median would be deriving a ceiling on hardware the suite does not
+ * run on. Completion is typed interactively, so this stays the budget most
+ * worth defending — see BUDGETS.md for the arithmetic.
+ */
+export const BUDGET_COMPLETE_MS = 150;
 
 /** Warm project-config (`pragma.config.ts`) load ceiling (ms). Cache hit is sub-ms. */
 export const BUDGET_PROJECT_CONFIG_MS = 10;
 
 /**
  * Warm store-backed verb ceiling (ms) — a store boot from the cached n-quads
- * dump plus a query, in the compiled binary. The designed 300 ms holds: the
- * measured median (`__store-probe`) is ~150 ms here, so 300 is already ~2× the
- * measured median and needs no relaxation (see BUDGETS.md).
+ * dump plus a query, through the shipped entry.
+ *
+ * Re-derived when the embed became the distribution's real 8 479-triple graph
+ * instead of a 23-triple sample. Netted against a `--version` control from the
+ * SAME binary in the SAME run (this box's process start swings 60–287 ms with
+ * page-cache state alone), the real pack's store work is 2.83× the sample's —
+ * the median of five repetitions across two protocols. Projected onto the
+ * reference box, whose own toy store work is 147 − 45.5 = 101.5 ms: 45.5 +
+ * 101.5 × 2.83 ≈ 333 ms median, and 333 × (176/147) ≈ 398 ms p95 using the
+ * reference box's own dispersion for this command. `ceil(398 × 1.25 / 50) × 50`
+ * = 500 — which is 1.6× the projected median, i.e. tighter than the
+ * 2×-of-median rule the ceilings above use. Every input, every step, and the
+ * raw measurements are in BUDGETS.md; the designed `<300ms` target stays in the
+ * surface covenant, exactly as the 50 ms `help` target survived its 130 ms
+ * ceiling.
  */
-export const BUDGET_WARM_STORE_MS = 300;
+export const BUDGET_WARM_STORE_MS = 500;
 
 /**
  * Warm in-process MCP tool-call ceiling (ms) — PR7 graduates this from seeded to

package/src/testing/perf/codegen.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Unit pins for the committed-codegen CHECK seam (`scripts/codegen.ts`) —
+ * the mechanism behind two loop MAJORs: a gate's build must COMPARE the
+ * committed generated module and fail on staleness instead of silently
+ * repairing it before the PROTECTED drift guard (create.test.ts's
+ * projection-fidelity cell) reads it. The generator cell drives the EXPORTED
+ * generator with an injected `out` in a tmpdir — no spawn, no build, no repo
+ * write. The wiring cells pin the two halves the
+ * seam is made of and the fact that they MEET: the flag's VALUE (the
+ * exported GATE_BUILD_ENV) and its READER (the exported
+ * checkModeFromEnv). They do NOT pin the two CALL SITES — the gate
+ * spawn's `...GATE_BUILD_ENV` spread (perf/globalSetup.ts) and
+ * build.ts's `checkModeFromEnv(process.env)` read — which stay pinned by
+ * CONSTRUCTION: scripts/build.ts is executed by no test at all, and
+ * dropping the spread leaves every cell here green. A refactor that
+ * severs either call site still reverts gate builds to write mode
+ * silently; only a VALUE or READER change reddens.
+ */
+
+import {
+  copyFileSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  checkModeFromEnv,
+  generateCreateSurface,
+} from "../../../scripts/codegen.js";
+import { GATE_BUILD_ENV } from "./globalSetup.js";
+
+const SURFACE_COMMITTED = fileURLToPath(
+  new URL(
+    "../../capabilities/create/createSurface.generated.ts",
+    import.meta.url,
+  ),
+);
+describe("the committed-codegen CHECK seam (scripts/codegen.ts)", () => {
+  let surfaceOut: string;
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "codegen-check-"));
+    surfaceOut = join(dir, "createSurface.generated.ts");
+    copyFileSync(SURFACE_COMMITTED, surfaceOut);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("check mode over the committed bytes: green, nothing written, ZERO notices — the healthy-tree gate", () => {
+    // Seeded with the bytes git holds, check mode must compute NO change (this
+    // is also the healthy gate build's determinism: a fresh render equals the
+    // committed bytes), must never write — and must log NOTHING. The
+    // zero-notices half is what separates "byte-identical" from "tolerated".
+    const before = readFileSync(surfaceOut, "utf-8");
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const surface = generateCreateSurface({ check: true, out: surfaceOut });
+    expect(surface.changed).toBe(false);
+    expect(surface.surfaced).toBeGreaterThan(0);
+    expect(log).not.toHaveBeenCalled();
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(before);
+  });
+
+  it("check mode over STALE bytes: throws naming the module — and never repairs it", () => {
+    // The other arm of the seam — the one the gate exists for. Seed bytes
+    // that differ from a fresh render; check mode must FAIL loudly (naming
+    // the committed module and the repair) and must leave the seeded bytes
+    // untouched: a check that silently rewrote them would green the stale
+    // tree before the PROTECTED drift guard reads it.
+    const stale = "// stale committed projection\n";
+    writeFileSync(surfaceOut, stale);
+    expect(() =>
+      generateCreateSurface({ check: true, out: surfaceOut }),
+    ).toThrowError(/createSurface\.generated\.ts is STALE[\s\S]*bun run build/);
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(stale);
+  });
+
+  it("write mode over STALE bytes repairs them to the committed render", () => {
+    // The developer path `bun run build` takes: the same seeded staleness,
+    // check off — the module is rewritten to exactly the bytes a fresh
+    // render produces (the committed generation this suite copied in).
+    const committed = readFileSync(SURFACE_COMMITTED, "utf-8");
+    writeFileSync(surfaceOut, "// stale committed projection\n");
+    const result = generateCreateSurface({ check: false, out: surfaceOut });
+    expect(result.changed).toBe(true);
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(committed);
+  });
+});
+
+describe("the CHECK seam's wiring (GATE_BUILD_ENV → checkModeFromEnv)", () => {
+  it("checkModeFromEnv: exactly the documented flag value flips a build into the gate's check", () => {
+    // The READ side of the seam, pinned: build.ts consumes this one-liner
+    // over its process.env, so a build enters check mode exactly when the
+    // flag is the string "1" — an ordinary developer env (no flag) and a
+    // flag EXPLICITLY set to any other value both stay in write mode,
+    // where `bun run build` repairs the committed artifacts. The
+    // third case is what makes "exactly" true: a predicate that merely
+    // tested for the key's presence, or accepted "0" as well, would pass
+    // the first two.
+    expect(checkModeFromEnv({ PRAGMA_BUILD_SKIP_DOCS: "1" })).toBe(true);
+    expect(checkModeFromEnv({})).toBe(false);
+    expect(checkModeFromEnv({ PRAGMA_BUILD_SKIP_DOCS: "0" })).toBe(false);
+  });
+
+  it("GATE_BUILD_ENV carries the check-mode flag — the gate spawn's env enters check mode", () => {
+    // The SET side of the seam, pinned against the read side: the exported
+    // constant IS the object the gate spawn spreads into its child env
+    // (perf/globalSetup.ts), and feeding it to checkModeFromEnv proves the
+    // VALUE and the READER meet — changing the flag's value, or renaming
+    // the key on either side, reddens here. What this cell does NOT see is
+    // the spawn's `...GATE_BUILD_ENV` spread itself: dropping that leaves
+    // every cell in this file green while gate builds silently revert to
+    // write mode (repairing the stale committed tree every drift guard
+    // exists to catch), so the call site stays pinned by construction.
+    expect(GATE_BUILD_ENV.PRAGMA_BUILD_SKIP_DOCS).toBe("1");
+    expect(checkModeFromEnv(GATE_BUILD_ENV)).toBe(true);
+  });
+});