@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/testing/fixtures/graph/canonical.ts

@@ -26,6 +26,16 @@
  * ours to pin): 4 `ds:Component` (Button, Modal, LXD Panel, Beta Widget),
  * `importance` family with value `primary`, code standard
  * `code/function/purity`.
+ *
+ * Two of those anchors exist to pin an ABSENCE, and are load-bearing for the
+ * "declared, not inferred" halves of the read grammar:
+ * - `ds:token.legacy.borderRadius` — a `ds:Token` with no `ds:tokenId`, which
+ *   `token list` therefore never publishes and `token lookup`/`token sample`
+ *   must never reach (`PackLookup.nameFallback` is declared by `standard`
+ *   alone).
+ * - `cs:archive` — a `cs:Category` with no standards, which `standard
+ *   categories` reports at count 0 and `standard list --category archive` must
+ *   answer with a calm empty list rather than INVALID_INPUT.
  */
 
 import { BLOCK_PREFIXES, BLOCK_TTL } from "../blockGraph.js";
@@ -76,13 +86,46 @@ ds:token.spacing.medium a ds:Token ;
   ds:tokenType ds:type.spacing ;
   ds:valueLight "16px" ;
   ds:valueDark "16px" .
+
+# A ds:Token carrying NO ds:tokenId — the entity "token list" does not publish,
+# because its query REQUIRES the id. It is here to pin what a lookup may NOT
+# reach: "token lookup" addresses by ds:tokenId, and a story whose list requires
+# its "by" property must not become addressable (or sampleable) under a name
+# derived from its IRI. See PackLookup.nameFallback, declared by the "standard"
+# story alone — the one story whose list DOES publish such a name.
+ds:token.legacy.borderRadius a ds:Token ;
+  ds:tokenType ds:type.spacing ;
+  ds:valueLight "4px" ;
+  ds:valueDark "4px" .
 `;
 
-/** The `cs:` (code standards) section — reused verbatim from `standard/parity.test.ts`'s
- * fixture shape so `code/function/purity`/`react/component/*` are stable, shared
- * anchor names rather than a second invented set. */
+/**
+ * The `cs:` (code standards) section — shaped like the SHIPPED code-standards
+ * graph, not like a convenience fixture.
+ *
+ * Two facts about the real data are reproduced here on purpose, because the
+ * eval harness was blind to both while every fixture standard carried a
+ * `cs:name`:
+ *
+ * 1. **Most standards carry NO `cs:name`.** The shipped graph asserts it on 22
+ *    of 156 (~13%); one of the eight standards below carries one (~13%). The
+ *    ontology says so deliberately — `cs:name` is "an optional human-readable
+ *    display title" that "never participates in identity", the canonical
+ *    identifier being the compact IRI. So the name `standard list` publishes for
+ *    the other seven is SYNTHESIZED from the IRI local name
+ *    (`cs:react.component.props` → `react/component/props`), and a lookup that
+ *    cannot resolve a synthesized name cannot resolve the graph.
+ * 2. **Categories are a two-level SKOS tree.** `cs:testing.unit skos:broader
+ *    cs:testing`, exactly as the shipped graph declares for `testing.*` and
+ *    `ui_blocks.nojs`, and one standard sits DIRECTLY on the parent — the case a
+ *    non-reflexive roll-up (`skos:broader+`) silently drops.
+ *
+ * Anchor names (`code/function/purity`, `react/component/*`) are unchanged; they
+ * are simply reached the way the real graph reaches them.
+ */
 const CS_TTL = `
 @prefix cs: <http://pragma.canonical.com/codestandards#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
 
 cs:CodeStandard a owl:Class .
 cs:Category a owl:Class .
@@ -97,27 +140,66 @@ cs:dont a owl:ObjectProperty ; rdfs:domain cs:CodeStandard ; rdfs:range cs:Examp
 cs:language a owl:DatatypeProperty ; rdfs:domain cs:Example ; rdfs:range xsd:string .
 cs:code a owl:DatatypeProperty ; rdfs:domain cs:Example ; rdfs:range xsd:string .
 
-cs:cat.react a cs:Category ; cs:slug "react" .
-cs:cat.code a cs:Category ; cs:slug "code" .
+# ---- Categories: flat roots, plus one two-level branch (testing) ----
+cs:react a cs:Category ; rdfs:label "React" ; cs:slug "react" .
+cs:code a cs:Category ; rdfs:label "Code" ; cs:slug "code" .
+cs:turtle a cs:Category ; rdfs:label "Turtle" ; cs:slug "turtle" .
+cs:testing a cs:Category ; rdfs:label "Testing" ; cs:slug "testing" .
+cs:testing.unit a cs:Category ;
+  rdfs:label "Unit testing" ;
+  cs:slug "testing-unit" ;
+  skos:broader cs:testing .
 
+# A category the graph DECLARES with no standards filed under it. The
+# "standard categories" verb lists it with count 0, so
+# "standard list --category archive" must be the documented calm empty list — a
+# real slug, an empty answer. Validity read off the returned ROWS instead of the
+# graph called it INVALID_INPUT.
+cs:archive a cs:Category ;
+  rdfs:label "Archive" ;
+  cs:slug "archive" .
+
+# ---- Standards. Seven of eight carry NO cs:name (the shipped ~13% split). ----
 cs:react.component.props a cs:CodeStandard ;
-  cs:name "react/component/props" ;
   cs:description "Type component props explicitly." ;
-  cs:hasCategory cs:cat.react ;
+  cs:hasCategory cs:react ;
   cs:do [ a cs:Example ; cs:description "Do type props" ; cs:language "tsx" ; cs:code "interface P {}" ] ;
   cs:dont [ a cs:Example ; cs:description "Avoid any" ; cs:language "tsx" ; cs:code "props: any" ] .
 
 cs:react.component.structure a cs:CodeStandard ;
-  cs:name "react/component/structure" ;
   cs:description "Keep folder structure flat." ;
-  cs:hasCategory cs:cat.react ;
+  cs:hasCategory cs:react ;
   cs:extends cs:react.component.props ;
   cs:do [ a cs:Example ; cs:description "Do flatten" ; cs:language "text" ; cs:code "src/Button.tsx" ] .
 
 cs:code.function.purity a cs:CodeStandard ;
-  cs:name "code/function/purity" ;
   cs:description "Prefer pure functions." ;
-  cs:hasCategory cs:cat.code .
+  cs:hasCategory cs:code .
+
+# The standard sitting DIRECTLY on the parent category: a skos:broader+
+# roll-up loses it, a reflexive skos:broader* keeps it.
+cs:testing.smoke a cs:CodeStandard ;
+  cs:description "Keep one end-to-end smoke path green." ;
+  cs:hasCategory cs:testing .
+
+cs:testing.unit.isolation a cs:CodeStandard ;
+  cs:description "Isolate the unit under test." ;
+  cs:hasCategory cs:testing.unit .
+
+cs:testing.unit.naming a cs:CodeStandard ;
+  cs:description "Name a unit test for the behaviour it pins." ;
+  cs:hasCategory cs:testing.unit ;
+  cs:do [ a cs:Example ; cs:description "Do name the behaviour" ; cs:language "ts" ; cs:code "it(\\"rejects an empty batch\\")" ] .
+
+cs:testing.unit.fixtures a cs:CodeStandard ;
+  cs:description "Share one fixture per behavioural claim." ;
+  cs:hasCategory cs:testing.unit .
+
+# The ~13%: a display title that adds something the IRI does not.
+cs:turtle.naming.local_name_casing a cs:CodeStandard ;
+  cs:name "Turtle local-name casing" ;
+  cs:description "Use snake_case for multi-word local-name segments." ;
+  cs:hasCategory cs:turtle .
 `;
 
 /** The `ds:Prompt` workflow templates — the ONE source both the `prompt_list`/
@@ -160,19 +242,106 @@ ds:prompt.configure a ds:Prompt ;
 ds:prompt.scaffold-component a ds:Prompt ;
   rdfs:label "scaffold-component" ;
   rdfs:comment "Scaffold a new component and align it to the standards." ;
-  ds:promptBody "Scaffold the {{componentName}} component in {{framework}}. Use create_component with the component path and --framework {{framework}}, then review the generated files against the react/component standards via standard_lookup." ;
+  ds:promptBody "Scaffold the {{componentName}} component in {{framework}}. Use create_component with framework {{framework}} and the component path, then review the generated files against the react/component standards via standard_lookup." ;
   ds:promptArgument [ ds:argName "componentName" ; rdfs:comment "Component name/path (e.g. Button)." ; ds:argRequired true ] ;
   ds:promptArgument [ ds:argName "framework" ; rdfs:comment "react | svelte | lit." ; ds:argRequired false ] .
 `;
 
+/** The `ds:Concept` section — long-form documentation entries the `concept`
+ * story reads. Mirrors the real design-system data shape (canonical/design-system#64):
+ * `ds:name`/`ds:summary`/`ds:tier` base, the Markdown body in `ds:content`
+ * (standard disclosure), `ds:knownEdgeCases` (detailed), and `ds:conceptType`
+ * → a named `ds:ConceptType` individual carrying its own `ds:name`. */
+const CONCEPT_TTL = `
+ds:Concept a owl:Class .
+ds:ConceptType a owl:Class .
+ds:content a owl:DatatypeProperty ; rdfs:domain ds:Concept ; rdfs:range xsd:string .
+ds:knownEdgeCases a owl:DatatypeProperty ; rdfs:domain ds:Concept ; rdfs:range xsd:string .
+ds:conceptType a owl:ObjectProperty ; rdfs:domain ds:Concept ; rdfs:range ds:ConceptType .
+
+ds:concepttype.Explanation a ds:ConceptType ;
+  ds:name "Explanation" ;
+  ds:summary "Concept documentation that deepens understanding of a topic." .
+
+ds:concepttype.How-to-guide a ds:ConceptType ;
+  ds:name "How-to guide" ;
+  ds:summary "Concept documentation that walks through solving a problem." .
+
+ds:concept.Foundations-Grid a ds:Concept ;
+  ds:name "Foundations: Grid" ;
+  ds:summary "How the grid system underpins every layout." ;
+  ds:tier ds:global ;
+  ds:conceptType ds:concepttype.Explanation ;
+  ds:content "The grid is the shared spatial contract every block lays out against." ;
+  ds:knownEdgeCases "Nested grids inherit the outer gutter unless re-declared." .
+
+ds:concept.Question-mark-vs-information-icon a ds:Concept ;
+  ds:name "Question mark vs information icon" ;
+  ds:summary "Deciding between the information icon and the question mark icon." ;
+  ds:tier ds:global ;
+  ds:conceptType ds:concepttype.How-to-guide ;
+  ds:content "The information icon offers context proactively; the question mark answers a question the user already has." ;
+  ds:knownEdgeCases "Icon interpretation depends on the user's prior conventions." .
+`;
+
+/**
+ * The implementation graph: two libraries whose `ds:implementsBlock` edges point
+ * at `BLOCK_TTL`'s own Button/Modal IRIs, so a test can prove the cross-pack
+ * join (an implementation collected from source resolving to a block declared by
+ * the design system) rather than just the shape of a row. Button is implemented
+ * TWICE, on two platforms — the case `--platform` has to separate.
+ */
+const IMPLEMENTATION_TTL = `
+ds:ImplementationLibrary a owl:Class .
+ds:ImplementationObject a owl:Class .
+ds:hasImplementation a owl:ObjectProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range ds:ImplementationObject .
+ds:implementsBlock a owl:ObjectProperty ; rdfs:domain ds:ImplementationObject ; rdfs:range ds:UIBlock .
+ds:libraryName a owl:DatatypeProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range xsd:string .
+ds:platform a owl:DatatypeProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range xsd:string .
+ds:libraryTier a owl:ObjectProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range ds:Tier .
+ds:implementationCount a owl:DatatypeProperty ; rdfs:domain ds:ImplementationLibrary ; rdfs:range xsd:integer .
+ds:headLink a owl:DatatypeProperty ; rdfs:domain ds:ImplementationObject ; rdfs:range xsd:string .
+ds:versionedLink a owl:DatatypeProperty ; rdfs:domain ds:ImplementationObject ; rdfs:range xsd:string .
+
+ds:implementation.library.react-ds-global a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/react-ds-global" ;
+  ds:platform "react" ;
+  ds:libraryTier ds:global ;
+  ds:version "0.34.0" ;
+  ds:implementationCount 2 ;
+  ds:hasImplementation ds:implementation.react-ds-global.button,
+                       ds:implementation.react-ds-global.modal .
+
+ds:implementation.react-ds-global.button a ds:ImplementationObject ;
+  ds:implementsBlock ds:button ;
+  ds:headLink "https://example.test/react/Button.tsx" .
+
+ds:implementation.react-ds-global.modal a ds:ImplementationObject ;
+  ds:implementsBlock ds:modal ;
+  ds:headLink "https://example.test/react/Modal.tsx" .
+
+ds:implementation.library.svelte-ds-global a ds:ImplementationLibrary ;
+  ds:libraryName "@canonical/svelte-ds-global" ;
+  ds:platform "svelte" ;
+  ds:libraryTier ds:global ;
+  ds:version "0.34.0" ;
+  ds:implementationCount 1 ;
+  ds:hasImplementation ds:implementation.svelte-ds-global.button .
+
+ds:implementation.svelte-ds-global.button a ds:ImplementationObject ;
+  ds:implementsBlock ds:button ;
+  ds:headLink "https://example.test/svelte/Button.svelte" .
+`;
+
 /** The prefixes the canonical store is built and queried with. */
 export const CANONICAL_PREFIXES: Readonly<Record<string, string>> = {
   ...BLOCK_PREFIXES,
   cs: "http://pragma.canonical.com/codestandards#",
+  skos: "http://www.w3.org/2004/02/skos/core#",
 };
 
 /** The full canonical Turtle: PR3's `BLOCK_TTL` verbatim, plus the sections above. */
-export const CANONICAL_TTL = `${BLOCK_TTL}\n${DS_EXTRA_TTL}\n${CS_TTL}\n${PROMPT_TTL}`;
+export const CANONICAL_TTL = `${BLOCK_TTL}\n${DS_EXTRA_TTL}\n${CS_TTL}\n${PROMPT_TTL}\n${CONCEPT_TTL}\n${IMPLEMENTATION_TTL}`;
 
 /** Default viewing config: no tier set, `normal` channel — drops the beta-only block. */
 export const CANONICAL_CONFIG = { channel: "normal" as const };

package/src/testing/fixtures/graph/defaultPack.ts

@@ -171,7 +171,7 @@ ex:beta ex:name "Beta" .
 /**
  * A malformed Turtle source — a subject/predicate with no object — drives the
  * `sources update` data-error classification path (a NAMED `CONFIG_ERROR`, not
- * an INTERNAL "please report this issue").
+ * an INTERNAL "report this issue").
  */
 export const MALFORMED_TTL = `@prefix ex: <https://ex.test/#> .
 ex:One a ex:Widget .

package/src/testing/helpers/blankCanonicalRanges.ts

@@ -0,0 +1,36 @@
+/**
+ * Blank the @canonical/* dependency ranges inside a scaffolded application's
+ * `my-app/package.json` — identically on every snapshot — before a byte
+ * comparison. The application generator resolves its range through each
+ * producer's OWN `npm view` call (no timeout, no shared cache), so an
+ * asymmetric registry outcome (one producer reaches npm and another does
+ * not, or a @canonical/* release lands between the calls) would turn
+ * `^0.34.0` vs `^0.33.0` across all 11 ranges into a red that says nothing
+ * about the code under test. The networked cases prove the TEMPLATE surface;
+ * range truth belongs to the offline cells, where the outcome is forced
+ * (`capabilities/create/shippedCreate.subprocess.test.ts`).
+ *
+ * The regex preserves the dependency KEY (`$1`), so a key-set or
+ * non-@canonical divergence still fails; only the range value collapses.
+ * Deliberately import-free — a pure string transform no module-graph guard
+ * can ever see.
+ *
+ * @param tree - A tree snapshot (relative path → contents).
+ * @param manifestPath - The scaffolded manifest's path within the tree.
+ * @returns A NEW map with the manifest's @canonical/* ranges blanked; the
+ *   input is untouched. A tree without the manifest comes back copied as-is.
+ */
+export function blankCanonicalRanges(
+  tree: ReadonlyMap<string, string>,
+  manifestPath = "my-app/package.json",
+): Map<string, string> {
+  const out = new Map(tree);
+  const manifest = out.get(manifestPath);
+  if (manifest !== undefined) {
+    out.set(
+      manifestPath,
+      manifest.replaceAll(/("@canonical\/[^"]+": )"[^"]+"/g, '$1"<range>"'),
+    );
+  }
+  return out;
+}

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,12 +35,29 @@ 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. */
@@ -100,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 });
@@ -117,7 +135,15 @@ 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();

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,13 +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.
     // 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(BINARY, ["__store-probe"], {
+    const result = measureCommand(NODE, cli("__store-probe"), {
       runs: 12,
       warmups: 3,
       env: {

package/src/testing/perf/budgets.ts

@@ -1,29 +1,78 @@
 /**
- * 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 — those ceilings are
- * set to roughly 2× the measured median rather than silently weakening the
- * target. {@link BUDGET_WARM_STORE_MS} is derived differently (from a projected
+ * 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.
+ * 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