@ultimat3/cli 22.14.0 → 23.0.0

package/src/db-schema-refresh.ts

@@ -0,0 +1,122 @@
+// The schema dump, regenerated on behalf of a command: `x db gen` and `x db migrate` both end by
+// making `packages/db/schema/` equal to what the migrations produce. Split from
+// `db-schema-dump.ts`, which replays and writes; this decides what a command REPORTS when the dump
+// was written, was already right, was not owed, or could not be produced — and holds the two
+// findings that are about the dump as a whole rather than about one file in it.
+
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import type { Migration } from '@ultimat3/db';
+import { PGLITE_MISSING } from '@ultimat3/db';
+import type { CatalogDescription } from '@ultimat3/db/schema-dump';
+import {
+  hasSchemaDump,
+  type ReplayedSchema,
+  replayFor,
+  SCHEMA_DUMP_DIR,
+  type SchemaDumpWrite,
+  writeSchemaDump,
+} from './db-schema-dump';
+import { MIGRATIONS_DIR, readMigrations } from './migrations';
+import type { Finding, JsonValue } from './output';
+import { findingFrom, isUltimateErrorShape } from './output';
+
+/**
+ * The migrations would not replay, so there is no dump to write and nothing to compare one with.
+ * A framework error keeps its own cause; the fix is replaced, because the engine's own (`set
+ * DATABASE_URL …`) answers a question nobody asked — this database is a scratch one booted here.
+ *
+ * Two causes are not about the migrations at all, and each keeps the fix that repairs it: a
+ * refusal this pipeline raised itself (`X_SCHEMA_DUMP_DRIFT` — no server for an extension the
+ * embedded database cannot link) arrives whole, and a missing optional peer gets the install,
+ * because `x db migrate` would succeed and teach nothing.
+ */
+export function replayFailure(error: unknown): Finding {
+  if (isUltimateErrorShape(error) && error.code === 'X_SCHEMA_DUMP_DRIFT') {
+    return { ...findingFrom(error), docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR };
+  }
+  const detail = isUltimateErrorShape(error) ? findingFrom(error).cause : renderThrowable(error);
+  const missing = detail.startsWith(PGLITE_MISSING);
+  return {
+    code: 'X_SCHEMA_DUMP_DRIFT',
+    cause: missing
+      ? `the schema dump is replayed on the embedded database and ${detail}`
+      : `the migrations do not replay on the scratch database, so the schema dump cannot be produced: ${detail}`,
+    fix: missing
+      ? // A literal, as `@ultimat3/db`'s own `PGLITE_FIX` is: a `fix:` splices nothing into its
+        // command position, and `db-schema-refresh.test.ts` holds it equal to `PGLITE_PACKAGE`.
+        'bun add -d @electric-sql/pglite   # then: x db gen'
+      : 'x db migrate --json   # applies the same migrations to the dev database; a statement refused there too is the one to repair — then: x db gen',
+    docs: ERROR_DOCS_URL,
+    at: missing ? SCHEMA_DUMP_DIR : MIGRATIONS_DIR,
+  };
+}
+
+/**
+ * The same finding, for a run of `x db gen` that DID write its migration before the dump failed.
+ * The exit code is 1 and the migration is on disk, and a reader who sees only the first fact
+ * generates a second migration for a schema that is already recorded. So the cause leads with
+ * the file that exists, and says what the next `x db gen` will and will not do.
+ */
+export const afterWrittenMigration = (finding: Finding, id: string): Finding => ({
+  ...finding,
+  cause: `migration ${id} WAS written to ${MIGRATIONS_DIR} and is not to be generated again; only the schema dump failed, and once that is repaired a bare x db gen writes the dump and no second migration — ${finding.cause}`,
+});
+
+/** An app with a migration and no dump directory: one finding, and no database booted to say so. */
+export const dumpNeverGenerated = (): Finding => ({
+  code: 'X_SCHEMA_DUMP_DRIFT',
+  cause: `${MIGRATIONS_DIR} holds migrations and ${SCHEMA_DUMP_DIR} does not exist: the schema dump was never generated`,
+  fix: 'x db gen',
+  docs: ERROR_DOCS_URL,
+  at: SCHEMA_DUMP_DIR,
+});
+
+export interface SchemaDumpRefresh extends SchemaDumpWrite {
+  /**
+   * `skipped` — no migration and no dump, so nothing is owed and no database is booted.
+   * `failed` — the migrations did not replay; `finding` says why, and the dump on disk is left
+   * exactly as it was.
+   */
+  readonly status: 'written' | 'unchanged' | 'skipped' | 'failed';
+  readonly finding?: Finding | undefined;
+  /** The replayed catalog, for a caller that compares a live database against it. */
+  readonly catalog?: CatalogDescription | undefined;
+}
+
+const NOTHING: SchemaDumpWrite = { written: [], removed: [], total: 0 };
+
+/**
+ * Regenerate the dump after `x db gen` or `x db migrate`. Never throws: a replay that fails is
+ * reported as the finding it is, after the migration the command was asked for is already written.
+ */
+export async function refreshSchemaDump(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+  // Injected so the reporting rules are testable without booting a database per case.
+  replay: (migrations: readonly Migration[]) => Promise<ReplayedSchema> = replayFor(
+    root,
+    env,
+    false,
+  ),
+): Promise<SchemaDumpRefresh> {
+  const migrations = await readMigrations(root);
+  if (migrations.length === 0 && !hasSchemaDump(root)) return { ...NOTHING, status: 'skipped' };
+  let replayed: ReplayedSchema;
+  try {
+    replayed = await replay(migrations);
+  } catch (error) {
+    return { ...NOTHING, status: 'failed', finding: replayFailure(error) };
+  }
+  const write = await writeSchemaDump(root, replayed.files);
+  const changed = write.written.length + write.removed.length > 0;
+  return { ...write, status: changed ? 'written' : 'unchanged', catalog: replayed.catalog };
+}
+
+/** The `--json` shape both commands report under `data.schemaDump`. */
+export const schemaDumpJson = (refresh: SchemaDumpRefresh): JsonValue => ({
+  directory: SCHEMA_DUMP_DIR,
+  status: refresh.status,
+  files: refresh.total,
+  written: [...refresh.written],
+  removed: [...refresh.removed],
+});

package/src/dev-dashboard.ts

@@ -55,8 +55,8 @@ export interface DevDashboardInput {
 
 /**
  * Read-only is already enforced by `assertReadOnly` inside `dbPanel`, before `runSql` is ever
- * reached. A second gate here would be a second authz: two places to update when `x db psql
- * --write` changes what is allowed, and one of them would eventually disagree.
+ * reached. A second gate here would be a second authz: two places to update when what the panel
+ * allows changes, and one of them would eventually disagree.
  */
 async function runSql(input: DevDashboardInput, sql: string): Promise<SqlResult> {
   const started = performance.now();

package/src/dev-route-table.ts

@@ -17,8 +17,11 @@ import { islandHarnessRoutes } from './island-harness-route';
 import { islandRoutes } from './island-routes';
 import { loadIslandStates } from './island-states-load';
 import { loadNavigation, pageNavigation } from './page-navigation';
+import type { PageSpeculation } from './page-speculation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
+import { adminMountRoutes } from './runtime-admin';
 import { assetRoutes } from './runtime-assets';
 import { appRoutes } from './runtime-render';
 import { servedStorage, storageRoutes } from './runtime-storage';
@@ -56,6 +59,8 @@ export interface DevRouteTable {
   readonly routes: readonly Route[];
   /** The theme boot, whose `cspSource` the web role admits. */
   readonly theme: ThemeBoot;
+  /** The speculation rules, admitted the same way — `undefined` when no document carries any. */
+  readonly speculation: PageSpeculation | undefined;
   /** The app's own error pages' inline styles, admitted the same way. */
   readonly errorStyles: readonly string[];
   /** Where the app's default MCP endpoint was mounted, or `null`. */
@@ -75,11 +80,14 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
   const sync = await pageSync(input.root, input.env, input.buildId, input.realtime);
   // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
-  const navigation = await pageNavigation(
-    input.root,
-    await loadNavigation(input.root),
-    input.buildId,
-  );
+  const declared = await loadNavigation(input.root);
+  const navigation = await pageNavigation(input.root, declared, input.buildId);
+  // The browser's own prefetch, from the table as it stands at boot: a page added by a later save
+  // joins the rules on the next `x dev` — its links are a full load until then, never a wrong one.
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(input.root),
+    client: declared.surfaces,
+  });
   const errorStyles = await errorPageStyleSources(input.root);
   // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
   // changes under a page it controls is the update path, and one per keystroke exercises it per save.
@@ -143,6 +151,14 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     ...sync.routes,
     ...navigation.routes,
     ...pagePostRoutes(),
+    // The app's generated admin, when it declared one (`defineAdmin`): every screen under its base
+    // path, served through the same document builder as the pages below. Nothing for an app with
+    // no admin — the registry is asked, the package is not imported.
+    ...adminMountRoutes({
+      buildId: input.buildId,
+      themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
+    }),
     ...appRoutes({
       buildId: input.buildId,
       ...(input.isr === undefined ? {} : { isr: input.isr }),
@@ -151,6 +167,7 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       ...(origin === undefined ? {} : { origin }),
       ...(pwa === undefined
         ? {}
@@ -158,5 +175,12 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
   ];
 
-  return { routes, theme, errorStyles, mcpPath: mcpMount.path, mcpPaths: mcpMount.paths };
+  return {
+    routes,
+    theme,
+    speculation,
+    errorStyles,
+    mcpPath: mcpMount.path,
+    mcpPaths: mcpMount.paths,
+  };
 }

package/src/doctor-coverage.ts

@@ -0,0 +1,39 @@
+// `x doctor`'s coverage listing: every file the app's coverage floor does not see, and the reason
+// `x.verify.json` gives for each. A LISTING, never a finding: an `exclude` with its `why` is a
+// decision the app made in a committed file — printing it is what keeps the decision in view, and
+// a red `x doctor` over it would be the framework overruling what it asked to be written down.
+
+import type { CoverageExclude } from './coverage-floor';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { readVerifyFloor } from './verify-floor';
+
+/** The I/O half: the excludes this app's `x.verify.json` states. None when it states no floor. */
+export async function coverageExcludesProbe(root: string): Promise<readonly CoverageExclude[]> {
+  return (await readVerifyFloor(root))?.coverage?.exclude ?? [];
+}
+
+/**
+ * The listing, on a result `x doctor` already decided: `data.coverage.exclude` for a machine, one
+ * line per entry for a person. `ok`, the summary and the findings are returned as they came.
+ */
+export function withCoverageExcludes(
+  result: CommandResult,
+  exclude: readonly CoverageExclude[],
+): CommandResult {
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const listed: JsonValue = exclude.map(({ glob, why }) => ({ glob, why }));
+  return {
+    ...result,
+    data: { ...(data as Record<string, JsonValue>), coverage: { exclude: listed } },
+    ...(exclude.length === 0
+      ? {}
+      : {
+          lines: [
+            ...(result.lines ?? []),
+            msg('cli.doctor.coverageExclude', { count: exclude.length }),
+            ...exclude.map(({ glob, why }) => `  ${glob} — ${why}`),
+          ],
+        }),
+  };
+}

package/src/doctor-guards.ts

@@ -0,0 +1,54 @@
+// `x doctor`'s guard listing: the guards the framework ships that this app's `guards/` does not
+// hold, each with the command that adds it. A LISTING, never a finding: every shipped guard says
+// "delete this file to drop the rule", so an app without one may have decided — and a red
+// `x doctor` over a decision would be the framework overruling the convention it handed over.
+
+import { GUARD_DIR, guardPaths } from './guards';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { SHIPPED_GUARD_NAMES } from './templates/scaffold-guards';
+
+export interface MissingGuard {
+  readonly name: string;
+  /** The command that writes it, with its test. Then `x verify` says what it finds. */
+  readonly add: string;
+}
+
+/** The rule, pure: which shipped names have no file among the guards an app holds. */
+export function missingShippedGuards(present: readonly string[]): readonly MissingGuard[] {
+  const held = new Set(present.map((path) => path.replace(/\.tsx?$/, '')));
+  return SHIPPED_GUARD_NAMES.filter((name) => !held.has(`${GUARD_DIR}/${name}`)).map((name) => ({
+    name,
+    add: `x g guard ${name}`,
+  }));
+}
+
+/** The I/O half: the same enumeration the `boundaries` step runs, so the two cannot disagree. */
+export async function shippedGuardsProbe(root: string): Promise<readonly MissingGuard[]> {
+  return missingShippedGuards(await guardPaths(root));
+}
+
+/**
+ * The listing, on a result `x doctor` already decided: `data.guards.missing` for a machine, one
+ * line per command for a person. `ok`, the summary and the findings are returned as they came.
+ */
+export function withGuardListing(
+  result: CommandResult,
+  missing: readonly MissingGuard[],
+): CommandResult {
+  const data = typeof result.data === 'object' && result.data !== null ? result.data : {};
+  const listed: JsonValue = missing.map(({ name, add }) => ({ name, add }));
+  return {
+    ...result,
+    data: { ...(data as Record<string, JsonValue>), guards: { missing: listed } },
+    ...(missing.length === 0
+      ? {}
+      : {
+          lines: [
+            ...(result.lines ?? []),
+            msg('cli.doctor.guards', { count: missing.length }),
+            ...missing.map(({ add }) => `  ${add}`),
+          ],
+        }),
+  };
+}

package/src/doctor-sealed.ts

@@ -0,0 +1,132 @@
+// `x doctor`'s sealed-column checks: the columns the app declared `.sealed()`, against the master
+// keys this environment declares. Its own file for `doctor-offline.ts`'s reason — answering needs
+// the app's entities and the committed secrets, and `cmd-doctor.ts`'s job is the probe. The split
+// is the same too: reaching the disk is `sealedKeysProbe`, deciding is `sealedKeyFindings`.
+
+import {
+  ERROR_DOCS_URL,
+  findMasterKey,
+  readSecretsFile,
+  SECRETS_RETIRED_KEYS_ENV,
+  sealKeyIds,
+  secretsFileExists,
+} from '@ultimat3/core';
+import { registeredEntities, sealedFields } from '@ultimat3/entity';
+import { loadApp } from './app-load';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+export interface SealedColumnFact {
+  readonly entity: string;
+  /** Property key, as the entity declares it. */
+  readonly column: string;
+  readonly lookup: boolean;
+}
+
+export interface SealedKeysFact {
+  /**
+   * Every sealed column the app declares, or `undefined` when the app would not load — a short
+   * registry reads as "no sealed columns", which is the false green `appEntities` exists to refuse.
+   */
+  readonly columns: readonly SealedColumnFact[] | undefined;
+  /** The key ids in force, or `undefined` when no usable master key was found. */
+  readonly keys: { readonly current: string; readonly retired: readonly string[] } | undefined;
+}
+
+const named = (columns: readonly SealedColumnFact[]): string =>
+  columns.map((one) => `${one.entity}.${one.column}`).join(', ');
+
+/**
+ * The rule, pure. Two conditions, and an app with no sealed column is judged by neither.
+ *
+ * No key: every write to a sealed column is `X_SEAL_KEY_MISSING` — core's own code and its own
+ * fix, reported here before the first request finds out.
+ *
+ * A retired key still declared: a rotation whose re-seal has not finished. That is a live-system
+ * state and not a fault, but it has a cost that ends only when someone acts — a `lookup` column
+ * matches through `in (…)` over every key and its `.unique()` holds per key — so it is a finding
+ * until the retired key is dropped.
+ */
+export function sealedKeyFindings(fact: SealedKeysFact): readonly Finding[] {
+  const columns = fact.columns;
+  if (columns === undefined || columns.length === 0) return [];
+  if (fact.keys === undefined) {
+    return [
+      {
+        code: 'X_SEAL_KEY_MISSING',
+        cause: `${named(columns)} ${columns.length === 1 ? 'is' : 'are'} sealed and this environment has no usable master key, so every write to ${columns.length === 1 ? 'it' : 'them'} is refused`,
+        fix: 'x secrets init   # or, where the key already exists: export ULTIMATE_SECRETS_KEY="$(cat .secrets.key)"',
+        docs: ERROR_DOCS_URL,
+      },
+    ];
+  }
+  const [oldest] = fact.keys.retired;
+  if (oldest === undefined) return [];
+  const lookups = columns.filter((one) => one.lookup);
+  const weakened =
+    lookups.length === 0
+      ? ''
+      : ` — ${named(lookups)} ${lookups.length === 1 ? 'is a lookup column' : 'are lookup columns'}, so until then equality reads through in (…) over every key and .unique() holds per key`;
+  return [
+    {
+      code: 'X_SEAL_RESEAL_PENDING',
+      cause: `${named(columns)} may still hold values sealed under retired master key(s) ${fact.keys.retired.join(', ')}: a rotation whose re-seal has not finished${weakened}`,
+      // The id is 16 hex characters computed here from a key, never text read from a file.
+      fix: `x secrets rotate --drop ${quoteArg(oldest)} --json   # AFTER a backfill() has rewritten every row — update(id, { column: row.column }) seals under the current key`,
+      docs: ERROR_DOCS_URL,
+    },
+  ];
+}
+
+/**
+ * The retired ring as a booted process would see it: the real environment first, the committed
+ * file second — `installSecrets()`'s own order, without installing anything into this process.
+ */
+async function retiredRing(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<string | undefined> {
+  const declared = env[SECRETS_RETIRED_KEYS_ENV];
+  if (declared !== undefined && declared !== '') return declared;
+  const key = findMasterKey(root, { ...env });
+  if (key === undefined || !secretsFileExists(root)) return undefined;
+  return (await readSecretsFile(root, key))[SECRETS_RETIRED_KEYS_ENV];
+}
+
+/** The app's sealed columns, or `undefined` when it would not load. */
+export type DeclaredSealedColumns = (
+  root: string,
+) => Promise<readonly SealedColumnFact[] | undefined>;
+
+/** `appEntities`' rule (`schema-drift.ts`): a registry short one module is not "none declared". */
+const appSealedColumns: DeclaredSealedColumns = async (root) => {
+  const app = await loadApp(root);
+  if (app.findings.length > 0) return undefined;
+  return registeredEntities().flatMap((entry) =>
+    // `core` is absent on a hand-registered entry, which declares no columns to seal.
+    (entry.core === undefined ? [] : sealedFields(entry.core)).map((field) => ({
+      entity: entry.name,
+      column: field.property,
+      lookup: field.lookup,
+    })),
+  );
+};
+
+export async function sealedKeysProbe(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  declared: DeclaredSealedColumns = appSealedColumns,
+): Promise<SealedKeysFact> {
+  const columns = await declared(root);
+  // No sealed column means no question about keys, and no reason to open the secrets file.
+  if (columns === undefined || columns.length === 0) return { columns, keys: undefined };
+  try {
+    const ring = await retiredRing(root, env);
+    const source = { ...env, ...(ring === undefined ? {} : { [SECRETS_RETIRED_KEYS_ENV]: ring }) };
+    return { columns, keys: await sealKeyIds({ root, env: source }) };
+  } catch {
+    // Whatever refused — no key, a malformed one, a secrets file this key does not open — the
+    // answer for a sealed column is the same: there is no key ring to seal under.
+    return { columns, keys: undefined };
+  }
+}

package/src/document-graph.ts

@@ -0,0 +1,82 @@
+// Whether importing an app module would bring a DOCUMENT module into this process: a component
+// (`.tsx`) or a stylesheet. A role that renders nothing asks this before each import
+// (`role-load.ts`), so a worker never compiles the app's Sass or evaluates its pages to learn that
+// they register no job.
+
+import { resolvedImports } from './module-imports';
+import { hasPathSegment } from './path-segments';
+
+/** A component or a stylesheet: what only a process that renders documents evaluates. */
+const DOCUMENT = /\.(?:[jt]sx|s[ac]ss|css)$/;
+
+export const isDocumentModule = (path: string): boolean => DOCUMENT.test(path);
+
+/** An installed framework package, under either linker: `…/node_modules/@ultimat3/<pkg>/…`. */
+const FRAMEWORK_SCOPE = '/node_modules/@ultimat3/';
+
+export interface DocumentGraph {
+  /**
+   * True when importing `absolute` would evaluate a document module this process has not already
+   * loaded. Errs toward `false`: a specifier that will not resolve and a file that will not parse
+   * contribute no edge, so the caller imports the module and the import itself reports the fault.
+   */
+  reachesDocument(absolute: string): Promise<boolean>;
+}
+
+/**
+ * `loaded` answers whether a module is already in this process — a module the API index imported
+ * costs nothing more, whatever it reaches, so the walk stops there. Injected, so a test decides it.
+ */
+export function createDocumentGraph(loaded: (absolute: string) => boolean): DocumentGraph {
+  const edges = new Map<string, readonly string[]>();
+  const verdicts = new Map<string, boolean>();
+
+  /**
+   * The files importing `path` evaluates, when the walk follows them: the app's own modules and
+   * the framework's — `@ultimat3/ui` is a barrel of components, and an app module importing it
+   * brings every one of them and their Sass. A third-party package is not walked: it ships no
+   * component this framework's loader compiles. A lazy import's target is no edge at all.
+   */
+  async function importsOf(path: string): Promise<readonly string[]> {
+    const known = edges.get(path);
+    if (known !== undefined) return known;
+    // Unreadable: no edge, and the caller's own import is what reports it.
+    const source = await Bun.file(path)
+      .text()
+      .catch(() => '');
+    const found = resolvedImports(path, source, 'evaluated').filter(
+      (target) => !hasPathSegment(target, 'node_modules') || target.includes(FRAMEWORK_SCOPE),
+    );
+    edges.set(path, found);
+    return found;
+  }
+
+  return {
+    async reachesDocument(absolute: string): Promise<boolean> {
+      const known = verdicts.get(absolute);
+      if (known !== undefined) return known;
+      // The whole reachable set, never a per-node recursion: inside an import cycle a node's own
+      // answer depends on one still being computed, and a `false` memoised there is wrong.
+      const seen = new Set<string>();
+      const stack = [absolute];
+      let reaches = false;
+      while (stack.length > 0 && !reaches) {
+        const path = stack.pop();
+        if (path === undefined || seen.has(path)) continue;
+        seen.add(path);
+        if (verdicts.get(path) === true || (isDocumentModule(path) && !loaded(path))) {
+          reaches = true;
+          break;
+        }
+        // Already here, or already cleared: nothing below it is new to this process.
+        if (isDocumentModule(path) || loaded(path) || verdicts.get(path) === false) continue;
+        stack.push(...(await importsOf(path)));
+      }
+      // A clean walk clears everything it visited — each one's reachable set is inside this one's.
+      // A walk that found a document proves it for the start alone.
+      if (reaches) verdicts.set(absolute, true);
+      else for (const path of seen) verdicts.set(path, false);
+      return reaches;
+    },
+  };
+}

package/src/document-options.ts

@@ -0,0 +1,64 @@
+// What a document renderer is handed by the boot that knows it: the island resolver and every
+// document-level head the route itself cannot decide. Split out of `runtime-render.ts` at its
+// 500-line ceiling; one declaration for `x dev`, the container and the static export.
+
+import type { ClientSyncHead } from '@ultimat3/render';
+import type { NavigationDocumentHead } from './page-navigation';
+
+/**
+ * Specifier → built chunk URL, bound to the route file the specifier is written relative to.
+ * Supplied by whoever built the islands (`x dev`, the container, the static build); absent means
+ * no island was built, and a page that renders one then fails by name rather than emitting a
+ * `data-x-entry` nothing can import.
+ */
+export type IslandResolver = (routeFile: string) => (src: string) => string;
+
+export interface DocumentOptions {
+  readonly resolveIsland?: IslandResolver;
+  /**
+   * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
+   * from `pwa-artifacts.ts`, or absent when the app is not installable.
+   *
+   * A document-level string rather than something a route's `meta()` returns: it is the same three
+   * elements on every page of the app, an installable app is one whose EVERY page carries them
+   * (a browser offers the install on whichever page the visitor landed on), and `headFromMeta`
+   * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
+   * boot knows it, the renderer cannot ask.
+   */
+  readonly pwaHead?: string | ((locale: string) => string);
+  /**
+   * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
+   * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
+   * decided by `app.config.ts`, which the boot read and the renderer cannot.
+   */
+  readonly themeHead?: string;
+  /**
+   * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
+   * document this process serves. Principal-free, so a shareable document carries it too; absent
+   * for a caller that serves no socket at all (the static export).
+   */
+  readonly sync?: ClientSyncHead;
+  /**
+   * The record types the app persists (`entity(…, { persist: true })`), read per render. Rendered
+   * as `ultimate-persist` beside the scope tag only — persistence is per principal, so a document
+   * with no scope carries none.
+   */
+  readonly persisted?: () => readonly string[];
+  /**
+   * The public origin canonical, `og:url` and hreflang are absolute against — `publicOrigin()`
+   * from `site-config.ts`. Absent, the request's own origin: a relative canonical is one a crawler
+   * resolves against whatever host it happened to fetch from, a CDN's or a preview's.
+   */
+  readonly origin?: string;
+  /**
+   * The client router — `pageNavigation(…).head`. A document of a surface listed in
+   * `navigation.client` names it; every other document carries none of it.
+   */
+  readonly navigation?: NavigationDocumentHead;
+  /**
+   * `<script type="speculationrules">` — `pageSpeculation(…).head` — on every document that names
+   * NO client router: the browser prefetches the next page instead. A document with the router
+   * carries none, because the router prefetches by its own rules.
+   */
+  readonly speculationHead?: string;
+}

package/src/error-codes.ts

@@ -141,6 +141,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_GUARD_INVALID',
   'X_GUARD_FAILED',
   'X_GUARD_FINDING_INVALID',
+  // The browser-transport rule, on `boundaries` in every app (`app-transport.ts`). Both codes
+  // shipped as this repository's own script findings; the rule moved into the gate, so the CLI
+  // emits them and therefore owns them — the code strings and their meaning are unchanged.
+  'X_BROWSER_TRANSPORT_BYPASS',
+  'X_BROWSER_SERVER_BARREL',
   // The CLI's own declarations, held to each other. A flag the parser accepts and no code reads
   // is a promise in `x help` with nothing behind it — `x deploy --critical` said "forces clients
   // to reload" and reached no reader outside the plan JSON it was written into.
@@ -205,6 +210,16 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SITEMAP_EXTRA_INVALID',
   'X_DEV_RESTART_REQUIRED',
   'X_DEV_ROOT_GONE',
+  'X_SEAL_RESEAL_PENDING',
+  'X_VERIFY_STEP_TIMEOUT',
+  'X_COVERAGE_BELOW_FLOOR',
+  'X_COVERAGE_FLOOR_UNSTATED',
+  'X_COVERAGE_FLOOR_STALE',
+  'X_DB_HANDLE_UNREGISTERED',
+  'X_ROLE_LOAD_INCOMPLETE',
+  'X_ADMIN_RESOURCE_UNWIRED',
+  'X_IMAGE_NOT_PREBUILT',
+  'X_ADMIN_UNSCANNED',
 ] as const;
 
 /**
@@ -314,6 +329,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_GUARD_INVALID: 'a file in guards/ exports no usable guard',
   X_GUARD_FAILED: 'an app guard threw instead of returning findings',
   X_GUARD_FINDING_INVALID: "an app guard's finding breaks the error contract",
+  X_BROWSER_TRANSPORT_BYPASS:
+    'browser-reachable code opens its own connection instead of using the one seam',
+  X_BROWSER_SERVER_BARREL:
+    "browser-reachable code imports a package's server barrel where the package publishes a browser entry",
   X_CLI_FLAG_UNREAD: 'a command declares a flag no code reads',
   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',
@@ -360,6 +379,19 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_DEV_RESTART_REQUIRED:
     'a save reached a module that defines a primitive; only a new process serves it',
   X_DEV_ROOT_GONE: 'the app root x dev serves was deleted or moved',
+  X_SEAL_RESEAL_PENDING: 'sealed columns still hold values under a retired master key',
+  X_VERIFY_STEP_TIMEOUT: 'a gate step ran past its deadline and was stopped',
+  X_COVERAGE_BELOW_FLOOR: 'the unit suite covers less of the app than x.verify.json states',
+  X_COVERAGE_FLOOR_UNSTATED:
+    'x.verify.json states no coverage floor, or one under 95 with no reason',
+  X_COVERAGE_FLOOR_STALE: 'the app now covers more than the floor in x.verify.json states',
+  X_DB_HANDLE_UNREGISTERED: "an entity x g wrote is not in the app's typed database handle",
+  X_ROLE_LOAD_INCOMPLETE: 'a worker or scheduler did not register a job or task the manifest names',
+  X_ADMIN_RESOURCE_UNWIRED: "an admin override x g wrote is not in the app's defineAdmin() call",
+  X_IMAGE_NOT_PREBUILT:
+    'a container role built at boot what the image build should have: island chunks or stylesheets',
+  X_ADMIN_UNSCANNED:
+    'a defineAdmin() declaration sits outside the app scan, so the admin is never mounted',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws