@ultimat3/cli 19.1.3 → 19.2.0

package/src/duplicate-packages.ts

@@ -0,0 +1,278 @@
+// Two installed copies of one registry-holding framework package, found before either registry is
+// asked anything. `@ultimat3/i18n`, `@ultimat3/policy` and `@ultimat3/entity` each keep their
+// registry at MODULE scope, so a second module instance is a second, EMPTY registry: an app whose
+// `packages/i18n` workspace pinned `@ultimat3/i18n@19.0.0` while its root had 19.1.0 registered
+// every catalog into the workspace's copy, the CLI read the root's, and `x i18n check` answered
+// `X_CATALOG_UNREGISTERED` with a fix that said to move a `defineCatalogs()` call that was already
+// exactly where the fix said to put it (ai-maxxing, 2026-09-05). The same split is the one
+// `local-cli.ts` hands over for — a global `x` is a second copy of `@ultimat3/entity` — except this
+// one lives inside the app's own `node_modules`, where no hand-over can reach it.
+
+// why: Bun ships no symlink-resolving stat and no path API of its own. `realpathSync` is the whole
+// decision — two symlinks to one directory are one module instance, and two store entries at one
+// version are still two — and `dirname`/`join` walk a resolved entry up to the package that owns it.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+// why: Bun exposes no path API — `dirname` walks a resolved entry up to the package that owns it,
+// `join` reaches its manifest, and `relative` is what turns an absolute hit into the repo-relative
+// path a finding names.
+import { dirname, join, relative } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Finding } from './output';
+import { readWorkspaceGraph } from './workspace-graph';
+
+/**
+ * The packages whose registry is a module-scope table, and what that table is called in a finding.
+ * A second copy of any other `@ultimat3/*` package is a mixed-version install the CHANGELOG already
+ * warns against; a second copy of one of these is an app that registers into a registry nothing
+ * reads.
+ */
+export const REGISTRY_PACKAGES: Readonly<Record<string, string>> = {
+  '@ultimat3/i18n': 'catalog registry',
+  '@ultimat3/policy': 'permission registry',
+  '@ultimat3/entity': 'entity registry',
+};
+
+/** One resolution of one package from one directory. `dir` is the package's REAL directory. */
+export interface InstalledCopy {
+  readonly pkg: string;
+  /** Where the resolution started, app-root-relative: `.`, a workspace dir, or `CLI_ORIGIN`. */
+  readonly from: string;
+  readonly dir: string;
+  readonly version: string;
+}
+
+/** The `from` label of the copy the running CLI itself imports. */
+export const CLI_ORIGIN = 'the x CLI';
+
+/** One distinct copy of a duplicated package, and every origin that resolves to it. */
+export interface DuplicateCopy {
+  readonly dir: string;
+  readonly version: string;
+  readonly from: readonly string[];
+}
+
+export interface DuplicateInstall {
+  readonly pkg: string;
+  /** Newest version first; ties in `dir` order, so a report is stable across runs. */
+  readonly copies: readonly DuplicateCopy[];
+}
+
+/**
+ * Semver order, through Bun's own comparator so `19.1.0-beta.1` sorts BELOW `19.1.0` and
+ * `19.10.0` above `19.9.0`; a string that is not a version falls back to its text, because the
+ * report still has to be stable over whatever a hand-edited manifest carries.
+ */
+function compareVersions(left: string, right: string): number {
+  try {
+    return Bun.semver.order(left, right);
+  } catch {
+    return left.localeCompare(right);
+  }
+}
+
+/**
+ * The pure half: every package that resolves to more than one real directory. Keyed by REALPATH,
+ * never by version — two workspace symlinks to one checkout are one instance whatever the labels
+ * say, and two store entries both stamped `19.1.0` are two instances all the same, because a
+ * module registry is per module instance and not per version string.
+ */
+export function duplicateInstalls(copies: readonly InstalledCopy[]): readonly DuplicateInstall[] {
+  const byPackage = new Map<string, Map<string, { version: string; from: string[] }>>();
+  for (const copy of copies) {
+    const dirs = byPackage.get(copy.pkg) ?? new Map<string, { version: string; from: string[] }>();
+    const entry = dirs.get(copy.dir) ?? { version: copy.version, from: [] };
+    if (!entry.from.includes(copy.from)) entry.from.push(copy.from);
+    dirs.set(copy.dir, entry);
+    byPackage.set(copy.pkg, dirs);
+  }
+  const duplicates: DuplicateInstall[] = [];
+  for (const [pkg, dirs] of byPackage) {
+    if (dirs.size < 2) continue;
+    const sorted = [...dirs.entries()]
+      .map(([dir, entry]) => ({ dir, version: entry.version, from: [...entry.from].sort() }))
+      .sort(
+        (left, right) =>
+          compareVersions(right.version, left.version) || left.dir.localeCompare(right.dir),
+      );
+    duplicates.push({ pkg, copies: sorted });
+  }
+  return duplicates.sort((left, right) => left.pkg.localeCompare(right.pkg));
+}
+
+/** The filesystem this reader touches, injectable so a fixture needs no install. */
+export interface DuplicateIo {
+  /** The resolved entry file, or throws — `Bun.resolveSync`'s contract. */
+  resolve(specifier: string, from: string): string;
+  realpath(path: string): string;
+  exists(path: string): boolean;
+  readText(path: string): string;
+}
+
+const nodeIo: DuplicateIo = {
+  resolve: (specifier, from) => Bun.resolveSync(specifier, from),
+  realpath: (path) => realpathSync(path),
+  exists: (path) => existsSync(path),
+  readText: (path) => readFileSync(path, 'utf8'),
+};
+
+/**
+ * Deep enough for `src/index.ts` and for any entry an `exports` map could point at, shallow enough
+ * that a resolver answering something unexpected stops rather than walking to `/` — the same bound
+ * `framework-scope.ts` walks under.
+ */
+const MAX_DEPTH = 6;
+
+/**
+ * The real directory owning `entry`, judged by the `package.json` that NAMES `pkg`. The entry alone
+ * is not enough: a workspace checkout resolves to `packages/i18n/src/index.ts` and a published
+ * install to `…/dist/index.js`, and the first `package.json` upward from either is the one that
+ * says which package it is — a stray manifest in a `src/` would otherwise be reported as a copy.
+ */
+function packageDirOf(
+  pkg: string,
+  entry: string,
+  io: DuplicateIo,
+): { dir: string; version: string } | undefined {
+  let dir = dirname(entry);
+  for (let depth = 0; depth < MAX_DEPTH; depth += 1) {
+    const manifest = join(dir, 'package.json');
+    if (io.exists(manifest)) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(io.readText(manifest));
+      } catch {
+        return undefined;
+      }
+      if (typeof parsed !== 'object' || parsed === null) return undefined;
+      const fields = parsed as Record<string, unknown>;
+      if (fields['name'] !== pkg) return undefined;
+      const version = fields['version'];
+      return { dir: io.realpath(dir), version: typeof version === 'string' ? version : '0.0.0' };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/**
+ * One resolution per (package, origin), for every origin that IMPORTS the package in a real boot:
+ * the app root, every workspace the root manifest claims, and this CLI's own directory — which is
+ * what `x i18n check` reads its registry through. A directory that cannot resolve the package
+ * contributes nothing: a workspace with no dependency on `@ultimat3/policy` is not a copy of it.
+ *
+ * `cliDir` is injectable so a test can stand the CLI somewhere with no framework under it;
+ * production passes nothing, and the only defensible base is this module's own directory.
+ */
+export async function installedCopies(
+  root: string,
+  packages: readonly string[],
+  io: DuplicateIo = nodeIo,
+  cliDir: string = import.meta.dir,
+): Promise<readonly InstalledCopy[]> {
+  const origins: { from: string; dir: string }[] = [{ from: '.', dir: root }];
+  for (const node of await readWorkspaceGraph(root)) {
+    origins.push({ from: node.dir, dir: join(root, node.dir) });
+  }
+  origins.push({ from: CLI_ORIGIN, dir: cliDir });
+
+  const copies: InstalledCopy[] = [];
+  for (const pkg of packages) {
+    for (const origin of origins) {
+      let entry: string;
+      try {
+        entry = io.resolve(pkg, origin.dir);
+      } catch {
+        continue;
+      }
+      const owner = packageDirOf(pkg, entry, io);
+      if (owner === undefined) continue;
+      copies.push({ pkg, from: origin.from, dir: owner.dir, version: owner.version });
+    }
+  }
+  return copies;
+}
+
+/** The two steps composed — what `x i18n check` and the gate's `policy` step call. */
+export async function findDuplicateInstalls(
+  root: string,
+  packages: readonly string[],
+): Promise<readonly DuplicateInstall[]> {
+  return duplicateInstalls(await installedCopies(root, packages));
+}
+
+/** What a caller injects in place of `findDuplicateInstalls`, so a fixture needs no install. */
+export type DuplicateProbe = (
+  root: string,
+  packages: readonly string[],
+) => Promise<readonly DuplicateInstall[]>;
+
+/** `<dir>@<version> (resolved from ., packages/i18n)` — one clause per copy. */
+const renderCopy = (root: string, copy: DuplicateCopy): string => {
+  const shown = relative(root, copy.dir).replaceAll('\\', '/');
+  const dir = shown === '' || shown.startsWith('..') ? copy.dir : shown;
+  return `${dir}@${copy.version} (resolved from ${copy.from.join(', ')})`;
+};
+
+/** The manifest an origin pins its dependencies in — the file the fix names an edit to. */
+const manifestOf = (from: string): string | undefined =>
+  from === CLI_ORIGIN ? undefined : from === '.' ? 'package.json' : `${from}/package.json`;
+
+/**
+ * The one sentence both findings share: which copies, where each is read from, and why that is
+ * an empty registry rather than a version skew. `root` is what turns a store path into the
+ * app-relative one an agent can open.
+ */
+export function duplicateCause(root: string, duplicate: DuplicateInstall): string {
+  const registry = REGISTRY_PACKAGES[duplicate.pkg] ?? 'registry';
+  const copies = duplicate.copies.map((copy) => renderCopy(root, copy)).join(' and ');
+  return (
+    `${duplicate.copies.length} copies of ${duplicate.pkg} are installed: ${copies} — each is ` +
+    `its own module instance with its own ${registry}, so what the app registers into one, the ` +
+    'other never sees'
+  );
+}
+
+/**
+ * The command that leaves ONE copy, then the command that re-checks. Two shapes, because the two
+ * causes repair differently: copies at different versions are a workspace pinning an older
+ * range, and the fix names that manifest and the version to pin; copies at ONE version are two
+ * resolutions of one range — a stale nested `node_modules`, or two peer sets in the store — and
+ * the only edit that can collapse them is the install itself.
+ */
+export function duplicateFix(duplicate: DuplicateInstall, recheck: string): string {
+  const newest = duplicate.copies[0];
+  const older = duplicate.copies.filter((copy) => copy.version !== newest?.version);
+  if (newest !== undefined && older.length > 0) {
+    const manifests = [
+      ...new Set(older.flatMap((copy) => copy.from.map(manifestOf)).filter(Boolean)),
+    ];
+    const where = manifests.length === 0 ? 'every package.json that pins it' : manifests.join(', ');
+    return `set "${duplicate.pkg}": "${newest.version}" in ${where}, then: bun install && ${recheck}`;
+  }
+  return `bun install --force   # one resolution of ${duplicate.pkg} for every workspace; then: ${recheck}`;
+}
+
+/**
+ * The finding both steps report. Its own code rather than the registry's own (`X_CATALOG_UNREGISTERED`,
+ * `X_PERMISSION_UNKNOWN`): those name a symptom that has a source-level repair, and this names an
+ * install with no source-level repair at all — an agent handed the registry's fix edits a file that
+ * is already right, re-runs, and is red again.
+ */
+export function duplicateFinding(
+  root: string,
+  duplicate: DuplicateInstall,
+  recheck: string,
+): Finding {
+  const at = duplicate.copies
+    .flatMap((copy) => copy.from.map(manifestOf))
+    .find((manifest): manifest is string => manifest !== undefined);
+  return {
+    code: 'X_PACKAGE_DUPLICATED',
+    cause: duplicateCause(root, duplicate),
+    fix: duplicateFix(duplicate, recheck),
+    docs: ERROR_DOCS_URL,
+    ...(at === undefined ? {} : { at }),
+  };
+}

package/src/error-codes.ts

@@ -148,6 +148,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SECRETS_EDITOR_MISSING',
   'X_SECRETS_EDIT_FAILED',
   'X_WORKSPACE_DEP_UNDECLARED',
+  // Two module instances of a registry-holding package inside ONE app's `node_modules`. Its own
+  // code and not the registry's (`X_CATALOG_UNREGISTERED`, `X_PERMISSION_UNKNOWN`): those carry a
+  // source-level fix, and an agent following it here edits a file that is already right — the
+  // repair is an install, and only `duplicate-packages.ts` can see that.
+  'X_PACKAGE_DUPLICATED',
   'X_SHOT_BROWSER_MISSING',
   // `x shot --island` — one code per way a component's named state fails to become a picture.
   // The last of the four is the one that gates: it is checked against the expansion computed
@@ -290,6 +295,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
   X_WORKSPACE_DEP_UNDECLARED: 'a workspace imports another workspace it does not declare',
+  X_PACKAGE_DUPLICATED: 'two copies of one registry-holding framework package are installed',
   X_SHOT_BROWSER_MISSING: 'x shot found no browser library in the app',
   X_SHOT_ISLAND_STATES_EMPTY: 'an island states file declares no manifest',
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',

package/src/i18n-registration.ts

@@ -19,12 +19,17 @@ import {
   registeredLocales,
 } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
+import type { DuplicateProbe } from './duplicate-packages';
+import { duplicateCause, duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import { auditApp } from './i18n-audit';
 import { I18N_INDEX_PATH } from './i18n-index';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
 
+/** The one package this check probes for a duplicate: its registry is the one it reads. */
+const I18N_PKG = '@ultimat3/i18n';
+
 /**
  * What this check needs of a boot. The seam is injected so a fixture can be exactly "the app
  * loaded and registered nothing" — the shipped shape of the bug — without a temp directory that
@@ -43,6 +48,8 @@ export interface RegistrationInput {
   readonly extraction: Extraction;
   readonly ignoreUnused: readonly string[];
   readonly load?: AppLoader;
+  /** The duplicate-install probe; `findDuplicateInstalls` is the production value. */
+  readonly duplicates?: DuplicateProbe;
 }
 
 export interface RegistrationReport {
@@ -74,17 +81,39 @@ function unresolvedUsedKeys(input: RegistrationInput, locale: Locale): readonly
   return report.locales[0]?.missing ?? [];
 }
 
+/** What `X_PACKAGE_DUPLICATED`'s fix runs once the install is one copy again. */
+const RECHECK = 'x i18n check --json';
+
 export async function checkRegistration(input: RegistrationInput): Promise<RegistrationReport> {
   // Importing the app's modules IS the registration, in this process exactly as in the server's.
   const app = await (input.load ?? loadApp)(input.root);
 
+  // Asked BEFORE the registry is: two copies of `@ultimat3/i18n` in one app are two registries,
+  // and every gap below is then a symptom of the install, not of where `defineCatalogs()` sits.
+  // Reported even with no gap — the CLI may share the app's index module's copy while a page in
+  // another workspace reads the other, which renders `⟦key⟧` under a green gate.
+  const duplicate = (await (input.duplicates ?? findDuplicateInstalls)(input.root, [I18N_PKG]))[0];
   const gaps = catalogRegistrationGaps(input.catalogs);
   const index = await indexSource(input.root);
-  const findings: Finding[] = gaps.map((gap) => ({
-    ...findingFrom(catalogUnregistered(gap)),
-    ...unregisteredFix(gap.locale, index),
-    at: catalogPath(gap.locale),
-  }));
+  const findings: Finding[] =
+    duplicate === undefined ? [] : [duplicateFinding(input.root, duplicate, RECHECK)];
+  for (const gap of gaps) {
+    const finding = findingFrom(catalogUnregistered(gap));
+    findings.push(
+      duplicate === undefined
+        ? { ...finding, ...unregisteredFix(gap.locale, index), at: catalogPath(gap.locale) }
+        : // The registry's own fix names a source edit — move the `defineCatalogs()` call — that an
+          // agent following it performs on a file that is already right (ai-maxxing, 2026-09-05).
+          // With a duplicate on disk the cause IS the install, so the finding says so and the fix
+          // is the one the duplicate carries.
+          {
+            ...finding,
+            cause: `${duplicateCause(input.root, duplicate)}; ${gap.missing.length} of ${catalogPath(gap.locale)}'s ${gap.shipped} key(s) registered into the copy the CLI does not read`,
+            fix: findings[0]?.fix ?? finding.fix,
+            at: catalogPath(gap.locale),
+          },
+    );
+  }
   let unregistered = gaps.reduce((sum, gap) => sum + gap.missing.length, 0);
   let locales = gaps.length;
 

package/src/index.ts

@@ -361,6 +361,8 @@ export {
   skipReasonFor,
   writeStaticReport,
 } from './static-report';
+export type { StyleBundle, StyleChunk } from './style-bundle';
+export { STYLE_BASE_PATH, styleBundle } from './style-bundle';
 export type { TestCounts } from './test-counts';
 export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';

package/src/island-bundle.ts

@@ -1,12 +1,13 @@
 // The island chunk table: every `*.island.tsx` in the app compiled as its OWN bundle entry point,
-// content-hashed, plus the resolver that turns a page's `src` specifier into the URL its
+// addressed by a hash of its SOURCE GRAPH (`graphHash` — `Bun.build`'s minified output is not
+// byte-deterministic), plus the resolver that turns a page's `src` specifier into the URL its
 // `data-x-entry` carries. One entry point per island is axiom 6 made mechanical — the page's graph
 // never reaches an island, so a `site/` document stays at 0kb whatever the island imports.
 
 // Bun ships no path API. `posix` does the specifier arithmetic (an app-relative route file is
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { frameworkVersion, renderThrowable } from '@ultimat3/core';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
@@ -32,7 +33,10 @@ export interface IslandChunk {
   readonly file: string;
   /** `islandModuleId` of the filename — the id the document, the budget and a finding all name. */
   readonly moduleId: string;
-  /** Immutable, content-addressed URL. What `data-x-entry` carries and what a route serves. */
+  /**
+   * Immutable, source-addressed URL. What `data-x-entry` carries and what a route serves — stable
+   * for as long as the sources, the framework version and the Bun version are. See `graphHash`.
+   */
   readonly url: string;
   /** The built JavaScript. Held in memory so `x dev` and the container serve without a disk hop. */
   readonly code: string;
@@ -101,30 +105,138 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
       // `x dev` serves the same chunk the container does, and bytes that depend on the ambient
       // NODE_ENV are a content hash and a byte budget measured on a build nobody ships.
       define: { 'process.env.NODE_ENV': '"production"' },
+      // The fourth, and it is asked for its INPUT list rather than its output: `sourcesContent` is
+      // the whole module graph this chunk was built from, which is the only stable identity a
+      // chunk has. See `graphHash`. Measured on 1.4.0 against a 131 kB island: 277ms with it and
+      // 276ms without, so the map costs nothing worth naming.
+      sourcemap: 'external',
     });
   } catch (error) {
     throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
   }
   const output = built.outputs.find((artifact) => artifact.kind === 'entry-point');
-  if (!built.success || output === undefined) {
+  const map = built.outputs.find((artifact) => artifact.kind === 'sourcemap');
+  if (!built.success || output === undefined || map === undefined) {
     throw new IslandBuildFailedError({
       file,
       logs: built.logs.map((log) => String(log)).join('; '),
     });
   }
-  const code = await output.text();
+  const code = stripDebugId(await output.text());
+  const hash = graphHash(file, await map.text());
   const moduleId = islandModuleId(basename(file));
   return {
     file,
     moduleId,
-    // Hashed with the framework's own `contentHash`, the function that already stamps an ETag and
-    // a precache revision — one identity for a byte string, not a third.
-    url: `${ISLAND_BASE_PATH}/${moduleId}-${contentHash(code)}.js`,
-    code,
+    url: `${ISLAND_BASE_PATH}/${moduleId}-${hash}.js`,
+    // The FIRST bytes this process emitted for these inputs, so a URL served `immutable` answers
+    // one byte string for as long as the process lives. Without it `x dev` re-mints the chunk on
+    // every watcher tick and a browser holding the previous one under `max-age=31536000` has two
+    // different files at one address.
+    code: stableCode(file, hash, code),
     bytes: new TextEncoder().encode(code).byteLength,
   };
 }
 
+/**
+ * `sourcemap: 'external'` appends `//# debugId=<hex>` to the chunk. It is a pointer to a map this
+ * framework does not serve, so it is removed rather than shipped — and removing it makes the
+ * emitted bytes identical to what the same build produced before the map was asked for, which is
+ * what keeps `bytes` a budget number and not a build-flag artefact. `slice`, never a `replace` with
+ * an empty replacement — `bun run sql-literal-copies` refuses that shape anywhere but `db/sql.ts`.
+ */
+const DEBUG_ID_COMMENT = '\n//# debugId=';
+
+function stripDebugId(code: string): string {
+  const at = code.lastIndexOf(DEBUG_ID_COMMENT);
+  return at === -1 ? code : code.slice(0, at);
+}
+
+/**
+ * The chunk's identity, computed from what went IN rather than from what came out.
+ *
+ * `Bun.build` is not byte-deterministic under `minify`. Measured on 1.4.0, one entry point, no
+ * source file touched: a 131,589-byte island alternated between two outputs of IDENTICAL length
+ * differing only in minified identifier names (`var ca=Object.defineProperty` against
+ * `var la=…`) — roughly one build in ten, which is a race in the renamer and not anything a caller
+ * can order. Hashing that output made the URL flap: ten distinct `session-console-*.js` names in
+ * ten minutes, so a service worker's precache manifest named a chunk that already 404ed and a
+ * browser's `immutable` cache never hit on a 131 kB download. Twelve consecutive builds hash
+ * identically here.
+ *
+ * `sourcesContent`, hashed per file and SORTED, so the identity is independent of the order the
+ * bundler happened to visit the graph in. The PATHS are deliberately not in it: they are absolute
+ * on the build machine and would make a chunk built in a container disagree with the same chunk
+ * built on a laptop for no difference a browser could observe. `file` is, so two islands with
+ * byte-identical sources under different names stay two chunks; the framework version and the Bun
+ * version are, because both decide the emitted bytes while no source file moves — an upgrade must
+ * mint a new URL rather than leave a stale chunk pinned in a browser for a year.
+ *
+ * What this gives up, stated plainly: the URL is source-addressed, not byte-addressed, so two
+ * processes building the same sources can serve two byte-strings at one URL. They are the same
+ * program under different local identifier names. That is the trade a nondeterministic bundler
+ * forces, and the alternative — `minify: { identifiers: false }`, which IS deterministic — was
+ * measured at 193,590 bytes against 131,649, +47% raw and +20% gzipped, on every island of every
+ * app. Delete this the day `Bun.build` is deterministic.
+ */
+function graphHash(file: string, map: string): string {
+  const parsed: unknown = JSON.parse(map);
+  const contents = sourcesContentOf(parsed);
+  if (contents === undefined) {
+    throw new IslandBuildFailedError({
+      file,
+      logs: 'the bundler emitted a source map with no sourcesContent, so the chunk has no stable identity',
+    });
+  }
+  const graph = contents.map((source) => contentHash(source)).sort();
+  return contentHash([file, frameworkVersion(), Bun.version, ...graph].join('\u0000'));
+}
+
+/**
+ * `sourcesContent`, read the way `aggregatedErrors` below reads `errors`: narrowed first,
+ * dereferenced inside a `try`, `undefined` for anything that is not a full list of strings. A
+ * partial list is refused rather than padded — a graph with holes in it hashes two different
+ * islands the same.
+ */
+function sourcesContentOf(value: unknown): readonly string[] | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  try {
+    const held: unknown = (value as Record<string, unknown>)['sourcesContent'];
+    if (!Array.isArray(held) || held.length === 0) return undefined;
+    return held.every((one: unknown) => typeof one === 'string')
+      ? (held as readonly string[])
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The code this process already emitted for these inputs, or the code it just built.
+ *
+ * Keyed by PATH and validated by the input hash, `transformIslandTsx`'s cache's shape and for its
+ * reason: one entry per island bounds the map by the island count, which is the only quantity that
+ * should bound it, and an entry whose hash no longer matches is replaced rather than served.
+ */
+const emitted = new Map<string, { readonly graph: string; readonly code: string }>();
+
+/** Test seam: the table is process-global because the dev server it serves is too. */
+export function clearIslandChunkCache(): void {
+  emitted.clear();
+}
+
+/**
+ * `graph`, never `hash`: `bun run secret-compare` reads the NAME of a comparison's operands, and a
+ * value called `hash` is a digest an attacker may be probing. This one is a build input's
+ * identity — the same reason `pr-threads.ts` calls a review state `wanted`.
+ */
+function stableCode(file: string, graph: string, code: string): string {
+  const hit = emitted.get(file);
+  if (hit !== undefined && hit.graph === graph) return hit.code;
+  emitted.set(file, { graph, code });
+  return code;
+}
+
 /**
  * The bundler's own diagnostics, kept verbatim. An `AggregateError` holds one entry per unresolved
  * import or syntax error, and flattening them is what puts the line number in the cause instead of

package/src/island-harness.ts

@@ -13,9 +13,9 @@ import {
   islandModuleId,
   SURFACES,
 } from '@ultimat3/render';
-import { stylesFor } from '@ultimat3/render/server';
 import type { IslandShotTarget, IslandState } from '@ultimat3/testing';
 import { harnessScript } from './island-harness-script';
+import { styleBundle } from './style-bundle';
 
 /** Where the harness lives in `x dev`'s own namespace, so no app route can shadow it. */
 export const ISLAND_HARNESS_PATH = '/_x/island';
@@ -43,8 +43,13 @@ export function surfaceOf(island: string): Surface | null {
  * off because a picture taken mid-transition is a picture of a moment no user experiences; the
  * caret is invisible because a focused input blinks and two otherwise identical runs then differ.
  * Colours are semantic tokens, never literals — the app's own global layer defines them.
+ *
+ * Exported so `x dev` can hash it into `style-src`: it is emitted INLINE, so a policy that does
+ * not name it blocks the frame under an enforced CSP. It was never hashed at all until
+ * 2026-09-06 — invisible because `x dev` sends the policy report-only, which is exactly how the
+ * hydration runtime shipped blocked once already.
  */
-const FRAME_STYLE = `
+export const FRAME_STYLE = `
 *,*::before,*::after{animation:none !important;transition:none !important;
 scroll-behavior:auto !important;caret-color:transparent !important}
 html{background:rgb(var(--color-bg) / 1)}
@@ -74,13 +79,15 @@ export function harnessPage(input: HarnessPageInput): string {
     entry: input.entry,
     props: input.state.props,
   };
-  const css = stylesFor(surfaceOf(input.target.island));
+  // The same content-hashed file every real document links, so the picture is taken against the
+  // bytes a visitor gets — and the harness stops carrying 157 kB of inline CSS of its own.
+  const href = styleBundle().hrefFor(surfaceOf(input.target.island));
   return [
     '<!doctype html>',
     `<html lang="en" data-theme="${input.target.theme}">`,
     '<head><meta charset="utf-8">',
     `<title>${input.target.name} · ${input.target.state} · ${input.target.theme}</title>`,
-    css.length === 0 ? '' : `<style>${css}</style>`,
+    href === undefined ? '' : `<link rel="stylesheet" href="${href}">`,
     `<style>${FRAME_STYLE}</style>`,
     // Before the body and before every module script, which is the only ordering in which the
     // seal can catch a component's first request.

package/src/mcp-errors.ts

@@ -52,6 +52,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --json   # the finding names the fix line and the path it cites',
   X_WORKSPACE_DEP_UNDECLARED:
     'x verify --json   # the package-shape finding carries the dependency line to add',
+  X_PACKAGE_DUPLICATED:
+    'x i18n check --json   # the finding names both copies and the package.json to pin',
   X_SHOT_BROWSER_MISSING: 'bun add -d puppeteer-core',
   // The four island-capture codes. Each one's real repair is an edit to the app's own states file
   // or component, which no command can perform — so each names the command that REPRODUCES it with

package/src/mcp-host.ts

@@ -3,6 +3,9 @@
 // the gate. The description half is the framework's own `frameworkIntrospection`, so nothing here
 // is a second catalog of routes, entities, actions, queries or jobs.
 
+// why: Bun exposes no path API. Every use here builds a path this host then hands to `Bun.file`
+// or prints inside a `fix:` an operator runs — the dev log, a per-role log, the committed
+// manifest — and string concatenation would answer a different path on a Windows checkout.
 import { join } from 'node:path';
 import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';