@ultimat3/cli 24.0.0 → 25.1.0

package/src/app-mcp.ts

@@ -1,11 +1,11 @@
 // The app's own MCP endpoint, mounted by the web role. `defineAppMcp` built `mcp.route` — a
 // `POST` handler with token auth and per-class rate limits — and `app.config.ts` declared
-// `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
+// `ai: { mcp: { expose: true } }` by DEFAULT, and nothing between the two served it:
 // neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
 // every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
 // exports `mcp` — one `AppMcp`, or an array of them, one per population (customers, staff,
-// affiliates) — this module finds it, and both boots mount what it carries: endpoint #0 at
-// `ai.mcp.path`, every other at its own `defineAppMcp({ path })`.
+// affiliates) — this module finds it, and both boots mount what it carries: EVERY endpoint at its
+// own `defineAppMcp({ path })`, the one path its RFC 9728 metadata and its 401 also name.
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
@@ -13,7 +13,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
-import { json, selfOrigin } from '@ultimat3/http';
+import { jsonResponse, selfOrigin } from '@ultimat3/http';
 import {
   type AppMcp,
   McpAppUnmountedError,
@@ -36,7 +36,7 @@ export const APP_MCP_ROUTE_NAME = 'mcp';
 export interface AppMcpMount {
   /** `[]` when `expose` is false, when nothing exports `mcp`, or when no endpoint has a route. */
   readonly routes: readonly Route[];
-  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default, at `ai.mcp.path`. */
+  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default endpoint. */
   readonly path: string | null;
   /** Every mounted endpoint's `POST <path>`, in export order — the boot line prints one each. */
   readonly paths: readonly string[];
@@ -48,17 +48,19 @@ export interface AppMcpMount {
   readonly warning: McpAppUnmountedError | undefined;
 }
 
-interface ExposeDeclaration {
-  readonly expose: boolean;
-  readonly path: string;
-}
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
-/** `config.ai.mcp` off the one loader (`app-config-load.ts`); nothing exposed with no config file. */
-async function exposeDeclaration(root: string): Promise<ExposeDeclaration | undefined> {
-  return (await loadAppConfig(root))?.ai.mcp;
+/**
+ * `defineAppMcp`'s own default — `mcp/src/transport-http.ts`, `input.path ?? '/mcp'` — named here
+ * ONLY in a warning about an endpoint that has no route and so no resolved path. It never decides
+ * where anything mounts: a mounted endpoint's path is `route.path`.
+ */
+const UNROUTED_MCP_PATH = '/mcp';
+
+/** `config.ai.mcp.expose` off the one loader (`app-config-load.ts`); false with no config file. */
+async function exposed(root: string): Promise<boolean> {
+  return (await loadAppConfig(root))?.ai.mcp.expose ?? false;
 }
 
 const isAppMcp = (value: unknown): value is AppMcp =>
@@ -94,21 +96,20 @@ const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undef
  * does not have and answer 401 before the token was ever read.
  */
 export async function appMcpMount(root: string): Promise<AppMcpMount> {
-  const declared = await exposeDeclaration(root);
-  if (declared === undefined || !declared.expose) return NOTHING;
+  if (!(await exposed(root))) return NOTHING;
   const files = await candidates(root);
   const fallbackFile = 'apps/web/mcp.ts';
   for (const file of files) {
     const module = (await import(join(root, file))) as Record<string, unknown>;
     const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
     if (endpoints === undefined) continue;
-    return mountEndpoints(endpoints, declared.path, file);
+    return mountEndpoints(endpoints, file);
   }
   return {
     ...NOTHING,
     warning: new McpAppUnmountedError({
       reason: 'missing',
-      path: declared.path,
+      path: UNROUTED_MCP_PATH,
       file: files[0] ?? fallbackFile,
     }),
   };
@@ -119,11 +120,7 @@ export async function appMcpMount(root: string): Promise<AppMcpMount> {
  * route: it is skipped and the FIRST such is the warning, so one unfinished population never takes
  * the others down with it. Two endpoints on one route is thrown — see `McpPathDuplicateError`.
  */
-function mountEndpoints(
-  endpoints: readonly AppMcp[],
-  defaultPath: string,
-  file: string,
-): AppMcpMount {
+function mountEndpoints(endpoints: readonly AppMcp[], file: string): AppMcpMount {
   const routes: Route[] = [];
   const paths: string[] = [];
   const claimed = new Map<string, number>();
@@ -133,13 +130,15 @@ function mountEndpoints(
     if (route === undefined) {
       warning ??= new McpAppUnmountedError({
         reason: 'no-route',
-        path: defaultPath,
+        path: UNROUTED_MCP_PATH,
         file,
         ...(index === 0 ? {} : { endpoint: index }),
       });
       return;
     }
-    const path = index === 0 ? defaultPath : route.path;
+    // The descriptor's own path — the one its metadata, its `resourceUrl` and its 401 were built
+    // over. A mount path from anywhere else is a resource advertised where nothing answers.
+    const path = route.path;
     for (const mounted of endpointRoutes(route, path, index)) {
       const key = `${mounted.method} ${mounted.path}`;
       const first = claimed.get(key);
@@ -156,8 +155,7 @@ function mountEndpoints(
     }
     paths.push(path);
   });
-  const path = endpoints[0]?.route === undefined ? null : defaultPath;
-  return { routes, path, paths, warning };
+  return { routes, path: endpoints[0]?.route?.path ?? null, paths, warning };
 }
 
 type Descriptor = NonNullable<AppMcp['route']>;
@@ -179,7 +177,7 @@ function endpointRoutes(route: Descriptor, path: string, index: number): readonl
               method: 'GET',
               path: metadataPath,
               handler: (_request, ctx) => {
-                const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
+                const response = jsonResponse(resource.document(selfOrigin(ctx.url, ctx.https)));
                 // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
                 response.headers.set('access-control-allow-origin', '*');
                 response.headers.set('cache-control', 'public, max-age=3600');

package/src/app-name.ts

@@ -0,0 +1,52 @@
+// `x new <name>`'s last refusal before a byte lands: the slug must be a name core's `defineConfig`
+// accepts, because it is written verbatim as `app.config.ts`'s `name:` and spelled into every
+// identifier the scaffold derives (`<app>Seed`). The rule is asked of core, never restated here.
+
+import { defineConfig, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
+
+/**
+ * Why core's own config validator refuses `name`, in core's words, or `undefined` when it accepts
+ * it — asked by building the one config that name would scaffold, every other field defaulted. A
+ * copy of core's pattern here would be a second answer to "what is an app name", and the day one
+ * of them moved `x new` would again write an app whose `app.config.ts` throws at its own import.
+ */
+export function appNameIssue(name: string): string | undefined {
+  try {
+    defineConfig({ name });
+    return undefined;
+  } catch (error) {
+    return isUltimateError(error) ? error.cause : renderThrowable(error);
+  }
+}
+
+/** The bound the suggestion trims an over-long slug to — re-proved by `appNameIssue`, not trusted. */
+const MAX_LENGTH = 64;
+
+/**
+ * A slug core accepts, as close to `slug` as one edit gets: a leading digit gains an `app-` prefix
+ * (an identifier cannot start with one either), a one-letter name an `-app` suffix, and an
+ * over-long one is cut at the bound. `undefined` when none of those land on a valid name.
+ */
+export function suggestAppName(slug: string): string | undefined {
+  let candidate = /^[0-9]/.test(slug) ? `app-${slug}` : slug;
+  if (candidate.length < 2) candidate = `${candidate}-app`;
+  candidate = candidate.slice(0, MAX_LENGTH).replace(/-+$/, '');
+  return appNameIssue(candidate) === undefined ? candidate : undefined;
+}
+
+/** `x new 9lives`, `x new a`: a slug core's `defineConfig` would refuse at the app's first boot. */
+export class AppNameInvalidError extends UltimateError {
+  constructor(input: {
+    name: string;
+    slug: string;
+    issue: string;
+    invocation: string;
+    flags: readonly string[];
+  }) {
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"${input.name}" scaffolds the app name "${input.slug}", which app.config.ts's defineConfig refuses: ${input.issue}`,
+      fix: [input.invocation, suggestAppName(input.slug) ?? '<name>', ...input.flags].join(' '),
+    });
+  }
+}

package/src/app-permissions-borrowed.ts

@@ -3,13 +3,11 @@
 // delete` for every mounted entity, so an app rule naming one passed in the web process and threw
 // X_PERMISSION_UNKNOWN in any process that never mounted the admin — with nothing saying so.
 
-// why: Bun ships no path API, and `relative` renders a frame's absolute path against the app root.
-import { relative } from 'node:path';
 import { listActions } from '@ultimat3/action';
 import { type Policy, permissionDeclarationSites, policyPermissions } from '@ultimat3/policy';
 import { listQueries } from '@ultimat3/query';
 import { routeEntries } from '@ultimat3/render';
-import { frameFile, siteFile } from './app-permissions-site';
+import { frameFile, rootRelative, siteFile } from './app-permissions-site';
 import type { Finding } from './output';
 
 /** One permission one app declaration requires. */
@@ -72,11 +70,7 @@ export function borrowedPermissions(
     if (files.length === 0 || files.some((file) => file === undefined)) continue;
     if ((sites ?? []).some((site) => appFile(root, site) !== undefined)) continue;
     const from = [
-      ...new Set(
-        files.flatMap((file) =>
-          file === undefined ? [] : [relative(root, file).replaceAll('\\', '/')],
-        ),
-      ),
+      ...new Set(files.flatMap((file) => (file === undefined ? [] : [rootRelative(root, file)]))),
     ].sort();
     found.set(`${rule.permission}\u0000${rule.by}`, { ...rule, from });
   }

package/src/app-permissions-site.ts

@@ -2,15 +2,39 @@
 // `defineRoles()` or `definePermissions()` call — reduced to the file it names, absolute or
 // app-root-relative. Both `policy` step questions key their findings by it.
 
-// why: Bun ships no path API, and `relative` is what turns a stack frame's absolute path into
-// the app-root-relative one every finding is keyed by.
-import { relative } from 'node:path';
+// why: Bun ships no path API, and `posix.relative` is what turns a frame's absolute path into the
+// app-root-relative one every finding is keyed by — on POSIX-normalised input, so a Windows frame
+// and root compare the same way on every host.
+import { posix } from 'node:path';
 
-/** The absolute source path a frame (`at foo (/abs/path.ts:3:1)`) names, or `undefined`. */
+/**
+ * The location at the END of a frame — `at fn (<path>:<line>:<col>)` or `at <path>:<line>:<col>` —
+ * read lazily from the first place a path can start, so a `(` INSIDE the path (`/srv/shop (copy)/`)
+ * is part of it, and a drive letter (`C:\…`) is a path start too. Anchored at the end because a
+ * frame's location is always its last token, and the function name before it is not a path.
+ */
+const FRAME_LOCATION = /(?:^|[\s(])((?:[A-Za-z]:)?[\\/].*?\.[cm]?tsx?)(?::\d+){0,2}\)?\s*$/;
+
+/** The absolute source path a frame names, exactly as written, or `undefined`. */
 export function frameFile(site: string): string | undefined {
-  return /\(?(\/[^():]+\.[cm]?tsx?)(?::\d+)?(?::\d+)?\)?/.exec(site)?.[1];
+  return FRAME_LOCATION.exec(site)?.[1];
 }
 
+/**
+ * `\` → `/`, and a drive letter rooted like a POSIX path with its case folded (`C:\a` → `/c:/a`):
+ * `@ultimat3/policy`'s `declaration-site.ts` compares frames `/`-normalised for the same reason —
+ * on Windows neither a frame nor a root holds a `/`, and a shell spells the drive either way.
+ */
+const comparable = (path: string): string => {
+  const slashed = path.replaceAll('\\', '/');
+  const drive = /^([A-Za-z]):\//.exec(slashed);
+  return drive === null ? slashed : `/${(drive[1] ?? '').toLowerCase()}:${slashed.slice(2)}`;
+};
+
+/** `file` relative to `root`, `/`-separated, whichever OS printed either of them. */
+export const rootRelative = (root: string, file: string): string =>
+  posix.relative(comparable(root), comparable(file));
+
 /**
  * The frame's file relative to the app root, or `undefined` outside it: a locator nobody can act on
  * is worse than none. The frame is the only place the declaring module's name exists by the time
@@ -19,6 +43,6 @@ export function frameFile(site: string): string | undefined {
 export function siteFile(root: string, site: string): string | undefined {
   const absolute = frameFile(site);
   if (absolute === undefined) return undefined;
-  const rel = relative(root, absolute).replaceAll('\\', '/');
-  return rel.startsWith('..') || rel.length === 0 ? undefined : rel;
+  const rel = rootRelative(root, absolute);
+  return rel.startsWith('..') || rel.length === 0 || rel.startsWith('/') ? undefined : rel;
 }

package/src/app-root.ts

@@ -20,10 +20,14 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * the gate's dominant step, with `x doctor` reporting the runtime as fine. `--parallel` arrived in
  * the same release and is emitted now, so the floor may never fall below that patch.
  *
- * `1.4.0` rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI pins
- * `1.4.x`, both images build on `oven/bun:1.4-*`, and the per-worker database rests on
- * `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4.0 and on nothing older. `scripts/bun-pin.test.ts`
- * holds this to the same series as every other pin.
+ * A 1.4 patch rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI
+ * pins one exact patch, both images build on that patch's `oven/bun:1.4-*` digest, and the
+ * per-worker database rests on `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4 and on nothing older.
+ * It moved 1.4.0 → 1.4.2 with CI's pin (plan 2026/10/04/101, sweep 3): from then on 1.4.0 was a
+ * runtime nothing here ran, and the bundler defects fixed in 1.4.1 (oven-sh/bun#40578, #40650,
+ * #40657) change what `x build` emits. `scaffold-repo.ts` and the scaffold's CI read this constant,
+ * so a new app's `engines.bun` and its CI runtime move with it. `scripts/bun-pin.test.ts` holds it
+ * to the exact patch CI runs.
  *
  * **Lowering it to 1.3.14 was tried on 2026-08-27 and refused**, and the argument for trying was
  * sound — `--isolate` and `--parallel` are 1.3.13 features, no package here calls a 1.4-only API
@@ -34,7 +38,7 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * declared supported would hang on graceful shutdown the moment its database went away. The full
  * measurement is in `.github/actions/setup/action.yml`; read it before lowering this.
  */
-export const REQUIRED_BUN = '1.4.0';
+export const REQUIRED_BUN = '1.4.2';
 
 export interface AppRoot {
   readonly dir: string;

package/src/bin.ts

@@ -4,6 +4,7 @@
 
 import { dispatch } from './dispatch';
 import { resolveLocalCli } from './local-cli';
+import { handOff } from './local-cli-handoff';
 import { cwdFromArgv } from './root-env';
 // The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
 // one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
@@ -24,13 +25,8 @@ const local = resolveLocalCli({
 });
 if (local !== undefined) {
   writeErrorLine(`x: using the app's own @ultimat3/cli at ${local}`);
-  const child = Bun.spawn([process.execPath, local, ...Bun.argv.slice(2)], {
-    stdin: 'inherit',
-    stdout: 'inherit',
-    stderr: 'inherit',
-    env: Bun.env,
-  });
-  process.exit(await child.exited);
+  // Stop signals are forwarded and the child's code is ours: see local-cli-handoff.ts.
+  process.exit(await handOff([process.execPath, local, ...Bun.argv.slice(2)], Bun.env));
 }
 
 // `x dev` supervises a child that serves (`dev-supervisor.ts`): a save that reaches a module which

package/src/browser-launcher.ts

@@ -39,7 +39,8 @@ export class ShotChromeMissingError extends UltimateError {
       // One literal, so `fix-scan.ts` can read it. A path is the one repair that works whatever the
       // browser is and wherever the distribution put it; `--cdp-url` is the answer for a box that
       // will never have one, and it is a flag `x shot` already ships.
-      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome or Chromium binary; a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
+      // The `#` names the macOS and Windows spellings: one literal for every platform.
+      fix: 'export CHROME_PATH=/usr/bin/google-chrome   # any Chrome, Chromium or Edge binary — macOS: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows PowerShell: $env:CHROME_PATH = "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" (Edge: "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"); a box that will never have one attaches instead: x shot / --cdp-url wss://cdp.example.com/session/abc',
       meta: { tried: [...CHROME_CANDIDATES], vars: [...BROWSER_PATH_VARS] },
     });
   }
@@ -67,7 +68,8 @@ export const browserBinaryExists = (path: string): boolean => existsSync(path);
 /**
  * The path a run will launch, or `undefined` when this machine has no browser to launch.
  *
- * The last step is a PROBE — the four paths `cdp-launch.ts` tries for the e2e driver, imported
+ * The last step is a PROBE — the paths `cdp-launch.ts` tries for the e2e driver on THIS platform
+ * (`/usr/bin` on Linux, the app bundles on macOS, Chrome and Edge on Windows), imported
  * rather than restated, because two lists of Chrome locations that must agree is the drift axiom 2
  * refuses — so a box with no browser is refused before a dev-server boot, not one launch later.
  *

package/src/budgets-charged.ts

@@ -0,0 +1,60 @@
+// What a route's measured JavaScript was made of, file by file: the clause and the `--json` facts
+// `X_BUDGET_EXCEEDED` carries, so a reader can tell a heavier chunk from a byte counted twice
+// without re-running the build. Split from `budgets.ts`, which measures and compares.
+
+import type { JsonValue } from './output';
+
+/** One app file a document made the browser fetch, and its bytes on disk. */
+export interface ChargedFile {
+  readonly url: string;
+  readonly bytes: number;
+}
+
+/**
+ * Named in the cause; the rest are summed. A page carries one or two files in practice, and a
+ * sentence listing forty is one nobody reads — `meta.charged` still holds every one of them.
+ */
+const NAMED_FILES = 5;
+
+/** Heaviest first, then by URL, so the clause and the stats file are reproducible. */
+export function heaviestFirst(files: readonly ChargedFile[]): readonly ChargedFile[] {
+  return [...files].sort((a, b) =>
+    b.bytes !== a.bytes ? b.bytes - a.bytes : a.url < b.url ? -1 : a.url > b.url ? 1 : 0,
+  );
+}
+
+/**
+ * `; charged: /islands/post-form-04f75f18.js 81306 B, inline scripts 855 B` — exact bytes, never
+ * `formatBytes`: a 22 kB disagreement between two platforms is the question this answers, and a
+ * rounded figure hides the byte a duplicate shows up as. Empty for a row an older build wrote.
+ */
+export function chargedClause(
+  charged: readonly ChargedFile[] | undefined,
+  inlineBytes: number | undefined,
+): string {
+  const files = heaviestFirst(charged ?? []);
+  const parts = files.slice(0, NAMED_FILES).map((one) => `${one.url} ${String(one.bytes)} B`);
+  const rest = files.slice(NAMED_FILES);
+  if (rest.length > 0) {
+    const bytes = rest.reduce((sum, one) => sum + one.bytes, 0);
+    parts.push(`${String(rest.length)} more files ${String(bytes)} B`);
+  }
+  if (inlineBytes !== undefined && inlineBytes > 0) {
+    parts.push(`inline scripts ${String(inlineBytes)} B`);
+  }
+  return parts.length === 0 ? '' : `; charged: ${parts.join(', ')}`;
+}
+
+/** The same facts as data, or `undefined` when the row predates them — absent is not empty. */
+export function chargedMeta(
+  jsBytes: number,
+  charged: readonly ChargedFile[] | undefined,
+  inlineBytes: number | undefined,
+): { readonly [key: string]: JsonValue } | undefined {
+  if (charged === undefined && inlineBytes === undefined) return undefined;
+  return {
+    jsBytes,
+    charged: heaviestFirst(charged ?? []).map((one) => ({ url: one.url, bytes: one.bytes })),
+    inlineJsBytes: inlineBytes ?? 0,
+  };
+}

package/src/budgets-scan.ts

@@ -0,0 +1,76 @@
+// How the budget measurer READS an emitted document: which tags are code, which attribute names an
+// island entry, which path a URL is fetched at, and which files a module makes the browser load.
+// Split from `budgets.ts`, which decides what of that is charged and compares it to the budget.
+
+import { SPECULATION_RULES_TYPE } from '@ultimat3/render';
+
+export const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
+export const SRC_ATTR = /\ssrc="(?<src>[^"]*)"/;
+const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
+
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code — the rule
+ * `@ultimat3/render`'s `head.ts` already states, restated because its `carriesJson` reads a
+ * `HeadTag` and is not exported, and this side has an attribute string off the emitted document.
+ * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
+ * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
+ */
+export const carriesJson = (attrs: string): boolean => {
+  // Everything from the first `;` is a MIME PARAMETER and not the type: a real document writes
+  // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
+  // test alone charged an SEO structured-data block as executable JavaScript all over again.
+  const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
+  const declared = type.trim().toLowerCase();
+  // Speculation rules are JSON under a type that does not say so: read by the browser's
+  // prefetcher, never executed — the one script a 0kb page may carry for free.
+  return declared.endsWith('json') || declared === SPECULATION_RULES_TYPE;
+};
+
+/**
+ * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
+ * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
+ * never for the code that runtime boots. The entry attribute is that module URL, so it is read as
+ * exactly what it is: a file the browser will execute.
+ */
+export const ENTRY_ATTR = /\sdata-x-entry="(?<url>[^"]*)"/g;
+
+/**
+ * Static imports and `import()` both. A chunk reached by `import()` was INLINED into its island
+ * before islands were split, so charging it keeps a route's number what it was; and it is fetched
+ * the moment the island needs it, which is before the page does what it was loaded for.
+ */
+const LOADS: ReadonlySet<string> = new Set(['import-statement', 'dynamic-import']);
+
+/** The origin every artifact path is resolved against — a name that can never be a real host. */
+const ARTIFACT_ORIGIN = 'https://artifact.invalid';
+
+/**
+ * The path a browser fetches for a root-relative `url`, or `undefined` for one that is not this
+ * artifact's. Resolved with the WHATWG parser, the browser's own: it reads `\` as `/`, folds `.`
+ * and `..`, drops a query, and makes `//host/a.js` another origin. The dedupe below is keyed by
+ * this, because it is the FETCH that is counted once, and a raw string kept two spellings of one
+ * file apart — which `join` on Windows then turned back into one real path, charged twice.
+ */
+export function artifactPath(url: string): string | undefined {
+  if (!url.startsWith('/')) return undefined;
+  const resolved = URL.parse(url, ARTIFACT_ORIGIN);
+  return resolved?.origin === ARTIFACT_ORIGIN ? resolved.pathname : undefined;
+}
+
+/** Same-origin paths `code`, served at `url`, makes the browser load. Cross-origin and bare are not this build's. */
+export function loadedBy(url: string, code: string): readonly string[] {
+  let imports: readonly { readonly path: string; readonly kind: string }[];
+  try {
+    imports = new Bun.Transpiler({ loader: 'js' }).scanImports(code);
+  } catch {
+    // A file that does not parse as JavaScript imports nothing this gate can name; its own bytes
+    // are already charged.
+    return [];
+  }
+  const base = new URL(url, ARTIFACT_ORIGIN);
+  return imports
+    .filter((one) => LOADS.has(one.kind) && /^\.{0,2}\//.test(one.path))
+    .map((one) => new URL(one.path, base))
+    .filter((target) => target.origin === base.origin)
+    .map((target) => target.pathname);
+}

package/src/budgets-unmeasured.ts

@@ -0,0 +1,91 @@
+// Single responsibility: the finding for a budgeted route a build RAN and could not weigh, read off
+// the static report's `unmeasured` entry — under the failure's own code when that code is the
+// instruction, as an actor edit when the measurement actor was refused, the report otherwise.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Finding } from './output';
+import type { UnmeasuredRoute } from './static-report';
+
+/**
+ * The ONE code a failed measurement is reported under by its own name rather than as
+ * `X_BUDGET_UNMEASURED`. Its cause is complete — the island, the prop, its bytes, the cap — and
+ * its fix is an edit to the page, so the step's own "run x build and read the list" would put a
+ * second command between the author and a sentence the build had already composed. Every other
+ * render failure keeps the generic finding: a `TypeError` from a `load` that wanted a request is
+ * a reason to read the report, not an instruction.
+ *
+ * ONE code and not "any coded error", deliberately. `X_NO_CONTEXT` and `X_DB_UNAVAILABLE` from a
+ * measurement render are facts about the BUILD's environment, and reporting them under their own
+ * codes would tell the author to fix a database the gate never had. The list grows by a decision,
+ * per code, here.
+ */
+const REPORTED_BY_OWN_CODE: ReadonlySet<string> = new Set([
+  'X_ISLAND_PROPS_INVALID',
+  // A dynamic route that lists no `prerender()` path: the edit is in the route, not the build.
+  'X_BUDGET_PARAMS_UNDECLARED',
+]);
+
+/**
+ * Refusals of WHO the render ran as. The actor is the app's own declaration (core's
+ * `defineMeasurementActor`, in `app.config.ts`), so these ARE an instruction — but the refusal's
+ * own `fix:` was written for a request ("sign in", "mint the actor with its tenant at the request
+ * boundary") and names no build-time edit. The default actor is a service actor holding `*` with
+ * no org and no roles: a page whose policy names a role, or whose `load` reads a tenant-scoped
+ * entity, is refused under it (#675).
+ */
+const ACTOR_REFUSALS: ReadonlySet<string> = new Set([
+  'X_FORBIDDEN',
+  'X_UNAUTHENTICATED',
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+]);
+
+function ownCodeFinding(url: string, entry: UnmeasuredRoute): Finding {
+  return {
+    code: entry.code ?? 'X_BUDGET_UNMEASURED',
+    cause: entry.cause ?? entry.reason,
+    fix: entry.fix ?? `x build --target static --json   # its "unmeasured" list has ${url}`,
+    docs: ERROR_DOCS_URL,
+    at: url,
+  };
+}
+
+/** `CODE: cause` when the failure had a code, its rendered reason otherwise. */
+const refusalOf = (entry: UnmeasuredRoute): string =>
+  entry.code === undefined ? entry.reason : `${entry.code}: ${entry.cause ?? entry.reason}`;
+
+/**
+ * A build ran and has no row for `url`. `entry` is the report's account of why, when it has one:
+ * an instruction under its own code, an actor edit, or — for a failure that is a fact about the
+ * build's environment — the report, with the refusal already in the cause.
+ */
+export function builtUnmeasuredFinding(
+  url: string,
+  declared: string,
+  statsFile: string,
+  entry: UnmeasuredRoute | undefined,
+): Finding {
+  if (entry?.code !== undefined && REPORTED_BY_OWN_CODE.has(entry.code)) {
+    return ownCodeFinding(url, entry);
+  }
+  const base = `${url} declares a ${declared} budget and ${statsFile} has no row for it, so the build ran and could not weigh it`;
+  if (entry?.code !== undefined && ACTOR_REFUSALS.has(entry.code)) {
+    const actor = entry.actor ?? 'the measurement actor';
+    return {
+      code: 'X_BUDGET_UNMEASURED',
+      cause: `${base}: rendered as ${actor}, it was refused ${refusalOf(entry)}`,
+      // The paste: one declaration in the one file every build imports.
+      fix: "defineMeasurementActor(() => userActor({ id: 'measure', orgId: '<an org your dev seed creates>', roles: ['<the role this page requires>'] }))   # in app.config.ts",
+      docs: ERROR_DOCS_URL,
+      at: url,
+    };
+  }
+  return {
+    code: 'X_BUDGET_UNMEASURED',
+    cause: entry === undefined ? base : `${base}: ${refusalOf(entry)}`,
+    // When a build already ran, the report is where the rest of the answer is — it names every
+    // route it could not weigh, and why.
+    fix: `x build --target static --json   # its "unmeasured" list says why ${url} could not be weighed`,
+    docs: ERROR_DOCS_URL,
+    at: url,
+  };
+}