@ultimat3/cli 22.14.0 → 23.0.0

package/src/app-load.ts

@@ -151,7 +151,31 @@ export async function appModulePaths(root: string): Promise<readonly string[]> {
   return found.includes(index) ? [index, ...found.filter((path) => path !== index)] : found;
 }
 
-export async function loadApp(root: string): Promise<LoadedApp> {
+/** What one scan of the app's modules imported, and what would not. */
+export interface AppScan {
+  /** App-root-relative POSIX paths of every module that imported, sorted. */
+  readonly files: readonly string[];
+  /** Modules that would not import, and primitives that would not register. */
+  readonly findings: readonly Finding[];
+}
+
+export interface ScanOptions {
+  /**
+   * Records each module's bytes and pins so a LATER scan can evict what changed: a tool's and
+   * `x dev`'s. A container scans once per process, so its boot passes `false` and neither reads a
+   * module before importing it nor hashes one (`role-load.ts`).
+   */
+  readonly track: boolean;
+  /** `false` leaves a module out: neither read nor imported. Absent: every module is imported. */
+  readonly include?: (absolute: string) => boolean | Promise<boolean>;
+}
+
+/**
+ * The scan itself: every app module `options.include` admits, imported in `appModulePaths` order
+ * and registered. `loadApp` is this plus the facts a tool reads; a container role calls it through
+ * `loadAppForRole`, which decides what the role imports.
+ */
+export async function scanAppModules(root: string, options: ScanOptions): Promise<AppScan> {
   // Before any import: a stylesheet's surface is read below the app root, never off its absolute
   // path — under the container's `WORKDIR /app` that path's first segment is `app/`, and every
   // sheet, the site's included, classified as app CSS.
@@ -164,7 +188,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   const findings: Finding[] = [];
   // A rescan: whatever changed on disk since the last one, and everything importing it, leaves
   // Bun's module registry before the loop below imports it again.
-  if (registered.size > 0) await evictChanged(root);
+  if (options.track && registered.size > 0) await evictChanged(root);
 
   for (const absolute of await appModulePaths(root)) {
     // A SEGMENT, never a substring: an app checked out under
@@ -177,15 +201,19 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
       continue;
     }
+    if (options.include !== undefined && !(await options.include(absolute))) continue;
     // The source is read BEFORE the import, on the file's first pass and for every route module —
     // a rescan of any other registered module reads nothing here. What is recorded is bound to the
     // bytes the module was evaluated from, and a read AFTER the import cannot know which bytes
     // those were: a save landing between the two bound V1's component to V2's hash, so the next
     // scan saw nothing to do and served V1 until the save after. Read first, the worst case is one
-    // re-import the next tick, of a file that did change.
+    // re-import the next tick, of a file that did change. An untracked scan reads nothing here:
+    // no save lands in an image, so a route module's text is read after its import, once.
     const first = !registered.has(absolute) && !failures.has(absolute);
     const snapshot =
-      first || routeModules.has(absolute) ? await Bun.file(absolute).text() : undefined;
+      options.track && (first || routeModules.has(absolute))
+        ? await Bun.file(absolute).text()
+        : undefined;
     if (first && snapshot !== undefined) await trackModule(absolute, snapshot, root);
     let module: Record<string, unknown>;
     try {
@@ -195,16 +223,26 @@ export async function loadApp(root: string): Promise<LoadedApp> {
       continue;
     }
     files.push(file);
-    const finding = await register(absolute, file, module, snapshot);
+    const finding = await register(absolute, file, module, snapshot, options.track);
     if (finding !== undefined) findings.push(finding);
   }
 
   files.sort();
+  return { files, findings };
+}
+
+export async function loadApp(root: string): Promise<LoadedApp> {
+  const scan = await scanAppModules(root, { track: true });
+  // After the scan, because the scan is what mounts an admin: a declaration the globs above cannot
+  // reach is a finding here, owned by `manifest` like every other load finding. Imported here, not
+  // at the top: a container boots through `scanAppModules` and never asks (`serve-graph.test.ts`).
+  const { unscannedAdminFindings } = await import('./unscanned-admin');
+  const findings = [...scan.findings, ...(await unscannedAdminFindings(root))];
   await trackStylesheets(root);
   // An app that imported NOTHING and reported nothing is a registry every later step reads as
   // empty-and-fine. With an `app.config.ts` beside it, that is never what the author meant.
   if (
-    files.length === 0 &&
+    scan.files.length === 0 &&
     findings.length === 0 &&
     registersNothing() &&
     (await Bun.file(join(root, APP_CONFIG_FILE)).exists())
@@ -214,7 +252,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   // Read after the loop, never before it: `configureLocales` runs on the app's own import.
   return {
     root,
-    files,
+    files: scan.files,
     errorCodes: await appErrorCodes(root),
     defaultLocale: localeConfig().fallback,
     findings,
@@ -240,13 +278,15 @@ const emptyAppFinding = (root: string): Finding => ({
 /**
  * Registers a module once; every later call replays whatever the first one reported — except for
  * a route module, which a later call re-registers when the import handed back a new instance.
- * `snapshot` is the source read before this import: always for a first pass and a route module.
+ * `snapshot` is the source read before this import: always for a first pass and a route module of
+ * a TRACKED scan. An untracked one hands none, and a route module's text is read here instead.
  */
 async function register(
   absolute: string,
   file: string,
   module: Record<string, unknown>,
   snapshot: string | undefined,
+  track: boolean,
 ): Promise<Finding | undefined> {
   const previous = failures.get(absolute);
   if (previous !== undefined) return previous;
@@ -255,11 +295,15 @@ async function register(
   try {
     const config = module['config'];
     const route = isRouteConfig(config) ? config : undefined;
-    if (route !== undefined && snapshot !== undefined) {
-      registerRouteModule(file, module, route, snapshot);
+    if (route !== undefined) {
+      registerRouteModule(file, module, route, snapshot ?? (await Bun.file(absolute).text()));
       routeModules.set(absolute, module);
     }
-    if (definesPrimitive(module, route !== undefined) || file === API_INDEX) pinModule(absolute);
+    // A pin is the reload graph's: it stops an eviction a process that never rescans never runs,
+    // and deciding it walks every export of every module against the entity registry.
+    if (track && (definesPrimitive(module, route !== undefined) || file === API_INDEX)) {
+      pinModule(absolute);
+    }
     registerActions(module);
     registerQueries(module);
     return undefined;

package/src/app-manifest.ts

@@ -6,8 +6,10 @@
 // Bun ships no `Bun.*` path API: `join` builds the host-separator path to `x.manifest.json`.
 import { join } from 'node:path';
 import { describeActions } from '@ultimat3/action';
+import { primitiveRegistrar } from '@ultimat3/core';
 import { registeredLocales } from '@ultimat3/i18n';
 import { registeredTasks } from '@ultimat3/jobs';
+import { sendMailJob } from '@ultimat3/mail';
 import type { Manifest, PolicyFact, RouteFact, TaskFact } from '@ultimat3/manifest';
 import {
   buildManifest,
@@ -30,9 +32,21 @@ export interface AppManifest {
   readonly findings: readonly Finding[];
 }
 
+/**
+ * The jobs every role process registers whatever the app imports: `runtime-services.ts` imports
+ * `@ultimat3/mail` in every role, and that import declares `mail.send` — so every app's worker
+ * runs it, and the manifest records it. Seated here rather than left to an import's side effect:
+ * `x manifest`'s module graph never reached the mail barrel and `x verify`'s did, so the same app
+ * got two job lists and the `fix:` of `X_MANIFEST_DRIFT` could never clear it.
+ */
+const RUNTIME_JOBS: Readonly<Record<string, unknown>> = { sendMailJob };
+
 /** Load the app, then describe it. Every command that needs facts goes through here. */
 export async function appManifest(root: string): Promise<AppManifest> {
   const loaded = await loadApp(root);
+  // Through the registrar `defineApi` uses (`define-api.ts`): the declared name wins, and the
+  // same handle seated twice is one registration, so a second build of one tree is unchanged.
+  primitiveRegistrar('job')(RUNTIME_JOBS);
   const manifest = buildManifest(
     frameworkSources({
       app: await appIdentity(root),

package/src/app-reload-graph.ts

@@ -20,9 +20,10 @@
 // the old instance of what changed (a slice's service under its query, an admin page's view under
 // `defineAdmin`), so only a new process serves the save. `x dev` restarts on it (`dev-supervisor.ts`).
 
-// why: Bun ships no path API; import specifiers resolve against the importing file's directory.
-import { dirname, resolve } from 'node:path';
+// why: Bun ships no path API; the app root is compared as an absolute path.
+import { resolve } from 'node:path';
 import { registeredStylesheets } from '@ultimat3/render/server';
+import { resolvedImports } from './module-imports';
 import { hasPathSegment } from './path-segments';
 
 type Kind = 'script' | 'style' | 'data';
@@ -91,11 +92,6 @@ const STYLE = /\.(?:s[ac]ss|css)$/;
 const kindOf = (path: string): Kind =>
   SCRIPT.test(path) ? 'script' : STYLE.test(path) ? 'style' : 'data';
 
-const transpilers = {
-  ts: new Bun.Transpiler({ loader: 'ts' }),
-  tsx: new Bun.Transpiler({ loader: 'tsx' }),
-};
-
 const readText = async (path: string): Promise<string | null> => {
   try {
     return await Bun.file(path).text();
@@ -108,29 +104,10 @@ const hashOf = (text: string | null): bigint | null =>
   text === null ? null : BigInt(Bun.hash.wyhash(text));
 
 /** The in-app files `source` imports — a package under `node_modules` is not the app's to reload. */
-function importsOf(path: string, source: string, root: string): string[] {
-  let specifiers: readonly { readonly path: string }[];
-  try {
-    const transpiler = path.endsWith('x') ? transpilers.tsx : transpilers.ts;
-    specifiers = transpiler.scanImports(source);
-  } catch {
-    // A file that will not parse imports nothing yet; its own hash still changes on the fix.
-    return [];
-  }
-  const found: string[] = [];
-  for (const { path: specifier } of specifiers) {
-    let target: string;
-    try {
-      target = Bun.resolveSync(specifier, dirname(path));
-    } catch {
-      continue;
-    }
-    if (target.startsWith(`${root}/`) && !hasPathSegment(target, 'node_modules')) {
-      found.push(target);
-    }
-  }
-  return found;
-}
+const importsOf = (path: string, source: string, root: string): string[] =>
+  resolvedImports(path, source, 'referenced').filter(
+    (target) => target.startsWith(`${root}/`) && !hasPathSegment(target, 'node_modules'),
+  );
 
 function link(from: string, to: string): void {
   let set = importers.get(to);

package/src/app-transport.ts

@@ -0,0 +1,219 @@
+// The browser-transport rule (`browser-transport.ts`) over ONE APP: what `x verify`'s `boundaries`
+// step reports for a raw `fetch(` in an island. Built in rather than a file in `guards/` — a rule
+// an app can delete is a rule the next agent deletes.
+//
+// It reads nothing `readAppSources` already read. The islands and the surface files arrive in
+// memory; the only new I/O is the app's `tsconfig.json`, its workspace manifests, the installed
+// `@ultimat3/*` manifests (which name the browser entries), and — lazily — the files of the app's
+// own `packages/*` an island actually imports. An app with no island pays for none of it.
+//
+// The walk STOPS at an installed package: `@ultimat3/core`'s `clientTransport`, realtime's socket
+// and storage's upload client are the three seams, they live in `node_modules`, and they are
+// trusted rather than re-read — in an app, no file may open its own connection.
+
+// why: `ClosureHost.read` is synchronous (the walk is a plain loop) and `Bun.file().text()` is not.
+import { readFileSync } from 'node:fs';
+// why: Bun ships no path API; this reaches a file on disk with the host's separator.
+import { join } from 'node:path';
+import { isJsonObject } from '@ultimat3/core';
+import type { SourceFile } from './app-boundaries';
+import type { FindingContext } from './browser-transport';
+import {
+  barrelFinding,
+  browserEntries,
+  bypassFinding,
+  checkBrowserTransport,
+} from './browser-transport';
+import type { ClosureHost } from './import-closure';
+import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
+import { serverBarrels } from './server-barrels';
+import type { TransportShape } from './transport-calls';
+
+/** What an app is told may hold each shape: the framework's function, never a file of its own. */
+const HOLDER: ReadonlyMap<TransportShape, string> = new Map([
+  ['fetch', "@ultimat3/core's clientTransport"],
+  ['websocket', "@ultimat3/realtime's page socket"],
+  ['xhr', "@ultimat3/storage's uploadFile"],
+]);
+
+const CONTEXT: FindingContext = {
+  holder: (shape) => HOLDER.get(shape),
+  rerun: 'x verify --only boundaries --json',
+};
+
+/** One `paths` row or one `exports` row, as a specifier pattern: at most one `*` on each side. */
+interface Pattern {
+  readonly head: string;
+  readonly tail: string;
+  readonly wild: boolean;
+  /** Root-relative, `*` still in place. */
+  readonly target: string;
+}
+
+const patternOf = (key: string, target: string): Pattern => {
+  const star = key.indexOf('*');
+  return star < 0
+    ? { head: key, tail: '', wild: false, target }
+    : { head: key.slice(0, star), tail: key.slice(star + 1), wild: true, target };
+};
+
+/** The path `spec` names under `pattern`, or `undefined` when the pattern is not about it. */
+function applied(pattern: Pattern, spec: string): string | undefined {
+  if (!pattern.wild) return spec === pattern.head ? pattern.target : undefined;
+  if (!spec.startsWith(pattern.head) || !spec.endsWith(pattern.tail)) return undefined;
+  if (spec.length < pattern.head.length + pattern.tail.length) return undefined;
+  const middle = spec.slice(pattern.head.length, spec.length - pattern.tail.length);
+  return pattern.target.replace('*', middle);
+}
+
+const posix = (path: string): string => path.split('\\').join('/').replace(/^\.\//, '');
+
+/** A manifest or a tsconfig, or `undefined`: absent and unreadable both mean "says nothing". */
+async function readObject(path: string): Promise<Readonly<Record<string, unknown>> | undefined> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  try {
+    // JSONC: a tsconfig may carry comments and trailing commas, and a strict parse would turn one
+    // into "this app has no aliases" — every island's imports unresolved, the rule silently blind.
+    const parsed: unknown = Bun.JSONC.parse(await file.text());
+    return isJsonObject(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `compilerOptions.paths` of the app's root tsconfig — how its own packages are spelled. */
+async function tsconfigPatterns(root: string): Promise<readonly Pattern[]> {
+  const options = (await readObject(join(root, 'tsconfig.json')))?.['compilerOptions'];
+  const paths = isJsonObject(options) ? options['paths'] : undefined;
+  if (!isJsonObject(paths)) return [];
+  return Object.entries(paths).flatMap(([key, targets]) => {
+    const first: unknown = Array.isArray(targets) ? targets[0] : undefined;
+    return typeof first === 'string' ? [patternOf(key, posix(first))] : [];
+  });
+}
+
+interface Workspaces {
+  /** Every specifier a workspace package publishes, as a pattern onto its file. */
+  readonly patterns: readonly Pattern[];
+  /** Package name → its directory, for "is this file inside the package that barrel names". */
+  readonly dirs: ReadonlyMap<string, string>;
+}
+
+/** The app's own `apps/*` and `packages/*`, by the `name` and `exports` each manifest declares. */
+async function workspaces(root: string): Promise<Workspaces> {
+  const patterns: Pattern[] = [];
+  const dirs = new Map<string, string>();
+  for await (const manifest of new Bun.Glob('{apps,packages}/*/package.json').scan({ cwd: root })) {
+    const dir = posix(manifest).split('/').slice(0, 2).join('/');
+    const parsed = await readObject(join(root, manifest));
+    const name = parsed?.['name'];
+    if (typeof name !== 'string') continue;
+    dirs.set(name, dir);
+    const exports = isJsonObject(parsed?.['exports']) ? parsed['exports'] : {};
+    for (const [sub, target] of Object.entries(exports)) {
+      if (typeof target !== 'string') continue;
+      const spec = sub === '.' ? name : `${name}${sub.slice(1)}`;
+      patterns.push(patternOf(spec, `${dir}/${posix(target)}`));
+    }
+  }
+  return { patterns, dirs };
+}
+
+const INSTALLED = [
+  'node_modules/@ultimat3/*/package.json',
+  // A workspace install may leave a package beside the workspace that asked for it.
+  '{apps,packages}/*/node_modules/@ultimat3/*/package.json',
+];
+
+/** Every specifier the installed framework publishes — what `serverBarrels` derives its map from. */
+async function installedSpecifiers(root: string): Promise<ReadonlySet<string>> {
+  const specifiers = new Set<string>();
+  for (const pattern of INSTALLED) {
+    const found = new Bun.Glob(pattern).scan({ cwd: root, followSymlinks: true });
+    for await (const manifest of found) {
+      const parsed = await readObject(join(root, manifest));
+      const name = parsed?.['name'];
+      if (typeof name !== 'string') continue;
+      const exports = isJsonObject(parsed?.['exports']) ? parsed['exports'] : {};
+      for (const sub of Object.keys(exports)) {
+        if (!sub.includes('*')) specifiers.add(sub === '.' ? name : `${name}${sub.slice(1)}`);
+      }
+    }
+  }
+  return specifiers;
+}
+
+const SUFFIXES = ['', '.ts', '.tsx', '/index.ts', '/index.tsx'];
+
+/**
+ * The closure's view of the app: the surface files from memory, a file of the app's own
+ * `packages/*` from disk the first time an island reaches it, and nothing under `node_modules` —
+ * a relative import that climbs into an installed package is still past the boundary.
+ */
+function hostOf(
+  root: string,
+  sources: ReadonlyMap<string, string>,
+  patterns: readonly Pattern[],
+): ClosureHost {
+  const disk = new Map<string, string | undefined>();
+  const read = (path: string): string | undefined => {
+    const held = sources.get(path);
+    if (held !== undefined) return held;
+    if (!/\.tsx?$/.test(path) || hasPathSegment(path, 'node_modules')) return undefined;
+    if (!disk.has(path)) {
+      try {
+        disk.set(path, readFileSync(join(root, path), 'utf8'));
+      } catch {
+        disk.set(path, undefined);
+      }
+    }
+    return disk.get(path);
+  };
+  const alias = (spec: string): string | undefined => {
+    for (const pattern of patterns) {
+      const base = applied(pattern, spec);
+      if (base === undefined) continue;
+      for (const suffix of SUFFIXES) {
+        if (read(`${base}${suffix}`) !== undefined) return `${base}${suffix}`;
+      }
+    }
+    return undefined;
+  };
+  return { read, alias };
+}
+
+/**
+ * `X_BROWSER_TRANSPORT_BYPASS` and `X_BROWSER_SERVER_BARREL` for the app at `root`, over the
+ * sources `readAppSources` already holds.
+ */
+export async function appTransportFindings(
+  root: string,
+  files: readonly SourceFile[],
+): Promise<readonly Finding[]> {
+  const sources = new Map(files.map((file) => [file.path, file.source]));
+  const entries = browserEntries(sources);
+  if (entries.length === 0) return [];
+  const [paths, own, installed] = await Promise.all([
+    tsconfigPatterns(root),
+    workspaces(root),
+    installedSpecifiers(root),
+  ]);
+  const published = [...installed, ...own.patterns.filter((p) => !p.wild).map((p) => p.head)];
+  const { bypasses, barrels } = checkBrowserTransport({
+    entries,
+    // The tsconfig first: it is what the app's own typecheck resolves through.
+    host: hostOf(root, sources, [...paths, ...own.patterns]),
+    seams: new Map(),
+    barrels: serverBarrels(published),
+    ownsBarrel: (file, barrel) => {
+      const dir = own.dirs.get(barrel);
+      return dir !== undefined && file.startsWith(`${dir}/`);
+    },
+  });
+  return [
+    ...bypasses.map((bypass) => bypassFinding(bypass, CONTEXT)),
+    ...barrels.map((barrel) => barrelFinding(barrel, CONTEXT)),
+  ];
+}

package/src/boundary-findings.ts

@@ -3,7 +3,9 @@
 // was another command to run for the real one (plan 101 slice 11 j). The planner is the same one
 // `x fix boundary` prints from, so the gate and the command cannot disagree about the cut.
 
+import type { SourceFile } from './app-boundaries';
 import { appImportGraph, checkImportRules, readAppSources } from './app-boundaries';
+import { appTransportFindings } from './app-transport';
 import { planBoundaryCuts } from './boundary-cuts';
 import type { Finding } from './output';
 
@@ -29,8 +31,18 @@ export function withCutEdits(
   });
 }
 
-/** Read the app's sources once, check them, and hand back findings whose fix is the edit. */
-export async function appBoundaryFindings(root: string): Promise<readonly Finding[]> {
-  const files = await readAppSources(root);
-  return withCutEdits(checkImportRules(files), appImportGraph(files));
+/**
+ * Read the app's sources once, check them, and hand back findings whose fix is the edit. The
+ * browser-transport findings come from the same read and already carry their own edit.
+ */
+export async function appBoundaryFindings(
+  root: string,
+  /** The app's sources when the caller has already read them — the gate step reads them once. */
+  read?: readonly SourceFile[],
+): Promise<readonly Finding[]> {
+  const files = read ?? (await readAppSources(root));
+  return [
+    ...withCutEdits(checkImportRules(files), appImportGraph(files)),
+    ...(await appTransportFindings(root, files)),
+  ];
 }

package/src/browser-transport.ts

@@ -0,0 +1,160 @@
+// The browser has ONE HTTP function and ONE socket, as a rule over a file tree: a raw `fetch(`,
+// `new WebSocket(`, `new XMLHttpRequest(` or `new EventSource(` in browser-reachable code skips
+// `@ultimat3/core`'s `clientTransport` — credentials, the idempotency header, the record envelope,
+// the principal fence — so its rows never reach the page's store and it keeps running for the
+// previous principal after a sign-out. A package's SERVER BARREL in that closure is refused too.
+//
+// BROWSER-REACHABLE is derived, never listed: every `*.island.tsx`, every module that names the
+// client seam itself, and the import closure of each, followed name by name through barrels
+// (`import-closure.ts`). Pure over the tree its caller read — `app-transport.ts` reads an app's,
+// `scripts/browser-transport.ts` this repository's.
+//
+// WHAT IT CANNOT SEE: a browser module that neither is an island, nor names the seam, nor is
+// imported by either; a request made inside an installed package (the walk ends at the package
+// boundary); a fetch reached through a computed member (`globalThis['fetch']`); and a bare
+// `fetch(` in a file that also binds a local `fetch` (`bindsFetch`). A floor, not a proof.
+
+import { ERROR_DOCS_URL, maskLiterals } from '@ultimat3/core';
+import { commentSafe } from './comment-safe';
+import type { ClosureHost } from './import-closure';
+import { importClosure } from './import-closure';
+import type { Finding } from './output';
+import type { BarrelImport } from './server-barrels';
+import { barrelImports } from './server-barrels';
+import { isTest } from './source-files';
+import type { TransportCall, TransportShape } from './transport-calls';
+import { transportCalls } from './transport-calls';
+
+export interface Bypass extends TransportCall {
+  readonly file: string;
+}
+
+export interface ServerBarrel extends BarrelImport {
+  readonly file: string;
+}
+
+export const isIsland = (path: string): boolean => path.endsWith('.island.tsx');
+
+/** A module naming the page's client seam is browser code by its own statement. */
+const NAMES_SEAM = /\b(?:clientTransport|pageClient)\s*[(<]/;
+
+/**
+ * Where the closure starts: every island, plus every module `namesSeam` admits that calls the seam
+ * itself. Masked before the test: a template that EMITS `clientTransport(` is not browser code.
+ */
+export function browserEntries(
+  files: ReadonlyMap<string, string>,
+  namesSeam: (path: string) => boolean = () => true,
+): readonly string[] {
+  return [...files.entries()]
+    .filter(([path, source]) => {
+      if (isTest(path)) return false;
+      if (isIsland(path)) return true;
+      // The raw text first: masking is a pass over every character, and almost no file names it.
+      return namesSeam(path) && NAMES_SEAM.test(source) && NAMES_SEAM.test(maskLiterals(source));
+    })
+    .map(([path]) => path)
+    .sort();
+}
+
+export interface TransportInput {
+  readonly entries: readonly string[];
+  /** Reads a file and resolves a bare specifier; `undefined` from either ends the walk there. */
+  readonly host: ClosureHost;
+  /**
+   * Shape → the ONE file in this tree allowed to hold it. Empty for an app: the seams are the
+   * framework's and live in `node_modules`, past the boundary the walk stops at.
+   */
+  readonly seams: ReadonlyMap<TransportShape, string>;
+  /** Files whose realm is not a page — a service worker has no store and no principal fence. */
+  readonly exempt?: ReadonlySet<string>;
+  /** Server barrel → the browser entry that replaces it (`serverBarrels`). */
+  readonly barrels: ReadonlyMap<string, string>;
+  /** A package's own modules may import its own barrel; only a FOREIGN import pays for it. */
+  readonly ownsBarrel?: (file: string, barrel: string) => boolean;
+}
+
+/** The whole rule over a tree, pure. */
+export function checkBrowserTransport(input: TransportInput): {
+  readonly reachable: readonly string[];
+  readonly bypasses: readonly Bypass[];
+  readonly barrels: readonly ServerBarrel[];
+} {
+  const reachable = importClosure(input.host, input.entries);
+  const bypasses: Bypass[] = [];
+  const barrels: ServerBarrel[] = [];
+  for (const file of reachable) {
+    if (input.exempt?.has(file) === true) continue;
+    const source = input.host.read(file) ?? '';
+    for (const call of transportCalls(source)) {
+      if (input.seams.get(call.shape) === file) continue;
+      bypasses.push({ ...call, file });
+    }
+    for (const found of barrelImports(source, input.barrels)) {
+      if (input.ownsBarrel?.(file, found.barrel) === true) continue;
+      barrels.push({ ...found, file });
+    }
+  }
+  return { reachable, bypasses, barrels };
+}
+
+/**
+ * What to write instead, per shape — each a line that runs once its placeholder is named. A raw
+ * request does not say which of these it is, so `fetch` lists the four it can be.
+ */
+const REPLACEMENT: ReadonlyMap<TransportShape, string> = new Map([
+  [
+    'fetch',
+    "an action: `await browserClient.<action>(input)` (rpc<Api['actions']> in apps/web/shared/browser-client.ts); a read: `useQuery(<QUERY_REF>, input)` from '@ultimat3/realtime'; a file: `await uploadFile({ file, grant })` from '@ultimat3/storage'; anything else: `await clientTransport({ method: 'GET', url })` from '@ultimat3/core/page'",
+  ],
+  [
+    'websocket',
+    "`useQuery(<QUERY_REF>, input)` for rows or `useChannel(<CHANNEL_REF>, params, { onEvent })` for events, both from '@ultimat3/realtime' — the page has one socket and it is the framework's",
+  ],
+  [
+    'xhr',
+    "an upload with progress: `await uploadFile({ file, grant, onProgress })` from '@ultimat3/storage'; anything else: `await clientTransport({ method: 'GET', url })` from '@ultimat3/core/page'",
+  ],
+  [
+    'eventsource',
+    "`useQuery(<QUERY_REF>, input)` or `useChannel(<CHANNEL_REF>, params, { onEvent })` from '@ultimat3/realtime' — pushed frames arrive on the page's one socket",
+  ],
+]);
+
+export interface FindingContext {
+  /** Who may hold `shape` instead — a file in a repo, the framework's function in an app. */
+  readonly holder: (shape: TransportShape) => string | undefined;
+  /** The command that re-reads the tree: the gate's step in an app, the script in this repo. */
+  readonly rerun: string;
+}
+
+/** `file:line` for a message: the path is the scanned tree's, so it is escaped before it is quoted. */
+const siteOf = (site: { readonly file: string; readonly line: number }): string =>
+  `${commentSafe(site.file)}:${site.line}`;
+
+/**
+ * One runnable line, the edit behind a `#` — the shape `app-boundaries.ts` gives every fix. The
+ * command re-reads the tree; the comment is the edit, because only the finding knows the line.
+ */
+export function bypassFinding(bypass: Bypass, context: FindingContext): Finding {
+  const holder = context.holder(bypass.shape);
+  const site = siteOf(bypass);
+  return {
+    code: 'X_BROWSER_TRANSPORT_BYPASS',
+    at: `${bypass.file}:${bypass.line}`,
+    cause: `${site} calls ${bypass.spelled} in browser-reachable code; ${holder === undefined ? 'no module may' : `only ${holder} may`}, so this request skips the page's record store, idempotency header and principal fence`,
+    fix: `${context.rerun}   # after replacing ${bypass.spelled} at ${site} with ${REPLACEMENT.get(bypass.shape) ?? ''}`,
+    docs: ERROR_DOCS_URL,
+  };
+}
+
+export function barrelFinding(site: ServerBarrel, context: FindingContext): Finding {
+  const at = siteOf(site);
+  return {
+    code: 'X_BROWSER_SERVER_BARREL',
+    at: `${site.file}:${site.line}`,
+    cause: `${at} imports ${site.barrel} in browser-reachable code; that barrel is the package's server half, and ${site.entry} is the entry it publishes for a browser`,
+    fix: `${context.rerun}   # after changing the import at ${at} from '${site.barrel}' to '${site.entry}'`,
+    docs: ERROR_DOCS_URL,
+  };
+}