@ultimat3/cli 1.1.0 → 2.0.0

package/src/runtime-overrides.ts

@@ -0,0 +1,66 @@
+// The one place a host hands the framework a driver. `ServeOptions` had `{ root, env, role, port,
+// metricsPort }` and nothing else, so the ONLY way to install a driver was to call an ambient
+// setter from an app module — which `loadApp` imports *after* `startServices` has already captured
+// its own. This type is the seam that removes the need to, and every field is read exactly once,
+// as the first arm of `overrides?.x ?? <the env-selected default>`.
+
+import type { PurgeDriver } from '@ultimat3/cache';
+import type { Middleware, RateLimitStore } from '@ultimat3/http';
+import type { JobDriver } from '@ultimat3/jobs';
+import type { MailDriver } from '@ultimat3/mail';
+import type { SyncAuthenticator, Transport } from '@ultimat3/realtime';
+import type { IsrStore } from '@ultimat3/render';
+import type { ImageTransformDriver } from '@ultimat3/seo';
+import type { Storage } from '@ultimat3/storage';
+
+/**
+ * What a deployment may substitute for a boot decision the environment would otherwise make.
+ *
+ * Every field is OPTIONAL and every field REPLACES the default rather than sitting beside it: the
+ * env switch each one used to be is now the `??` arm of one expression, so there is exactly one
+ * answer to "which driver is this process running" (axiom 1). A field nothing consumes is not
+ * here — the entity `Driver` in particular, because `@ultimat3/entity` exposes no installer for
+ * one (`database(entities, { driver })` is the app's own call), and a slot the boot cannot honour
+ * is the class of defect this seam exists to end.
+ */
+export interface RuntimeOverrides {
+  /**
+   * The queue every enqueue AND every claim uses. Installed as the ambient driver too, so
+   * `jobDriver()` and the worker cannot disagree — `startRoles` refuses to boot when they do.
+   */
+  readonly jobs?: JobDriver;
+  /** Replaces the `S3_ENDPOINT`/embedded-disk decision whole: disks, default disk and all. */
+  readonly storage?: Storage;
+  /** Replaces the `SMTP_URL` / `RESEND_API_KEY` selection. */
+  readonly mail?: MailDriver;
+  /**
+   * Replaces the `NATS_URL` selection. Already connected when it arrives, and NOT closed by
+   * `stop()`: whoever built it owns its socket, exactly as `createServer` does not close a
+   * `rateLimitStore` it was handed.
+   */
+  readonly transport?: Transport;
+  /** Replaces the `CLOUDFLARE_*` / `FASTLY_*` selection behind the `cdn` cache tier. */
+  readonly purge?: PurgeDriver;
+  /**
+   * Where the HTTP rate limiter keeps its counters. It also DECIDES `rateLimit.scope`: a store
+   * that says `'shared'` is a deployment declaring fleet-wide numbers, and `assertRateLimitScope`
+   * holds the two halves together rather than a literal in the boot contradicting the store.
+   */
+  readonly rateLimitStore?: RateLimitStore;
+  /**
+   * Where regenerated ISR pages live. Omitted, `createIsrController` keeps a per-process memory
+   * store — twelve replicas then hold twelve of them, and a purge tag reaches one twelfth of the
+   * fleet.
+   */
+  readonly isrStore?: IsrStore;
+  /** Prepended to the pipeline by `createServer`, which `startRoles` never passed one. */
+  readonly middleware?: readonly Middleware[];
+  /** The `/media/*` transform. Omitted, `builtinImageDriver` — core's PNG/JPEG pipeline. */
+  readonly images?: ImageTransformDriver;
+  /**
+   * Who is dialling the `sync` node. Omitted, the app's own `configureAuthenticator()` is adapted
+   * — this field exists because that adapter can only ever answer `{ actor }`, and a real
+   * deployment's token has an `expiresAt` and a `refresh`, which is the whole of re-authorization.
+   */
+  readonly syncAuthenticate?: SyncAuthenticator;
+}

package/src/safe-url-label.ts

@@ -0,0 +1,24 @@
+// Single responsibility: a connection URL rendered so it can be printed, logged and scraped —
+// scheme, host, path, and never the userinfo, query or fragment that carry the password.
+// DATABASE_URL, NATS_URL and S3_ENDPOINT all reach `x dev --json` as raw strings, so the redaction
+// has one implementation rather than one per caller that remembers.
+
+/**
+ * `fallback` is the caller's, not this file's: a string that does not parse as a URL is a fact
+ * about that binding, and only the caller knows which binding it was. Never the raw string — an
+ * unparseable value is exactly where a hand-written credential ends up.
+ */
+export function safeUrlLabel(url: string, fallback: string): string {
+  let label: string;
+  try {
+    const parsed = new URL(url);
+    label = `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    return fallback;
+  }
+  // A scheme with no `//` is parsed as ONE opaque path — `app:user:pw@host/db` keeps its whole
+  // credential in `pathname` and `username` is empty, so dropping the userinfo fields is not
+  // enough. Any surviving `@` is treated as userinfo we failed to split, and the fallback wins: a
+  // host printed with a `@` in it is a redaction that did not happen.
+  return label.includes('@') ? fallback : label;
+}

package/src/scaffold-fixture.ts

@@ -28,9 +28,19 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'query', name: 'invoice-search', feature: 'invoice' },
   { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
   { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
+  { kind: 'backfill', name: 'reindex-invoices', feature: 'invoice' },
   { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
   { kind: 'route', name: 'pricing', surface: 'site' },
   { kind: 'route', name: 'billing', surface: 'app' },
+  // `--at`, pointed at the `site/` route above: an island's whole reason to exist is a 0kb page
+  // that needs one interactive control, so the fixture places it where that is true.
+  { kind: 'island', name: 'currency-picker', at: 'apps/web/site/pricing' },
+  // The one screen the admin derives from nothing — and the one generator that must NOT emit a
+  // `defineRoute`, so compiling it is how that stays true.
+  { kind: 'admin:page', name: 'reconcile', permission: 'ledger:reconcile' },
+  // The app's own convention. It is the only generated file that imports `@ultimat3/cli` for its
+  // types, so compiling it is what proves a scaffolded app can actually write one.
+  { kind: 'guard', name: 'migration-safety' },
 ];
 
 /** The whole scaffolded surface: a new app, then every generator run inside it. */

package/src/scaffold-typecheck.ts

@@ -66,50 +66,28 @@ export interface KnownGap {
   readonly owner: string;
 }
 
-// `InvariantColumns` is an index-signature type, so `c.title` is `ColumnExpr | undefined` under
-// `noUncheckedIndexedAccess`. Every hand-written entity in `examples/dummy` reproduces it
-// identically: the fix is a column proxy typed from the entity's own columns, in @ultimat3/entity
-// — a different template cannot avoid it without dropping to `satisfies()`, which would silently
-// stop emitting the Postgres CHECK.
-//
-// Measured, not guessed: no open-keyed form avoids the `| undefined` (index signature, `Record`,
-// and a mapped type over `string` or a template-literal pattern all produce it), and typing the
-// proxy from `columns` only reaches `c` when the element of `invariants:` is itself
-// context-sensitive. `invariant(name, build)` is a *call*, which TypeScript checks before
-// `entity()`'s own `C` is fixed, so `K` falls back to `string` and nothing changes. Making it
-// reach means changing the shape of `invariants:` — a documented primitive, so a major.
-const INVARIANT_PROXY =
-  '@ultimat3/entity — type the invariant column proxy from the declared columns (needs a major: ' +
-  'the `invariants:` element shape has to become context-sensitive)';
-
-/** Every entity the fixture generates. Each one declares the same two invariants. */
-const FIXTURE_ENTITIES = [
-  'apps/web/app/credit-note/entity.ts',
-  'apps/web/app/invoice/entity.ts',
-  'apps/web/app/post/entity.ts',
-] as const;
-
 /**
  * Diagnostics a template cannot fix, pinned one occurrence at a time. Pinned, never ignored:
  * `unexpectedIn` fails on anything not listed here — including a second copy of a listed
  * diagnostic, because each entry is consumed by exactly one match — and `staleGapsIn` fails when
  * a listed entry stops reproducing, so an entry cannot outlive the bug it describes.
+ *
+ * Empty, and that is the point: `invariants:` is one callback over the whole list, so `c` is typed
+ * from the entity's own columns and the six `TS18048 'c.title' is possibly 'undefined'` pins this
+ * list used to carry are gone. A new entry here is a template shipping a diagnostic, which needs
+ * an owner who can remove it — not a permanent exemption.
  */
-export const KNOWN_GAPS: readonly KnownGap[] = FIXTURE_ENTITIES.flatMap((file) =>
-  ["'c.title' is possibly 'undefined'.", "'c.price' is possibly 'undefined'."].map(
-    (message): KnownGap => ({
-      variant: 'x new',
-      code: 'TS18048',
-      file,
-      message,
-      owner: INVARIANT_PROXY,
-    }),
-  ),
-);
-
-/** The pins one invocation may spend. Another variant's pins are not its to spend. */
-export const gapsFor = (variant: string): readonly KnownGap[] =>
-  KNOWN_GAPS.filter((gap) => gap.variant === variant);
+export const KNOWN_GAPS: readonly KnownGap[] = [];
+
+/**
+ * The pins one invocation may spend. Another variant's pins are not its to spend. `gaps` is a
+ * parameter for the same reason it is on `unexpectedIn` and `staleGapsIn`: with `KNOWN_GAPS`
+ * legitimately empty, the bookkeeping is only testable against a list a test supplies.
+ */
+export const gapsFor = (
+  variant: string,
+  gaps: readonly KnownGap[] = KNOWN_GAPS,
+): readonly KnownGap[] => gaps.filter((gap) => gap.variant === variant);
 
 const matches = (diagnostic: TypeDiagnostic, gap: KnownGap): boolean =>
   diagnostic.code === gap.code &&

package/src/serve.ts

@@ -4,11 +4,25 @@
 // `dev: true`. The only production-shaped decisions live here: which role, which port, and the
 // fact that a container must bind every interface.
 
-import { listActions, toRoute } from '@ultimat3/action';
 import type { Role } from '@ultimat3/core';
-import { isRole, logger, ROLES } from '@ultimat3/core';
-import { type MigrationReport, migrate } from '@ultimat3/db';
+import {
+  configureErrorReporting,
+  isRole,
+  logger,
+  ROLES,
+  sentryErrorReporter,
+} from '@ultimat3/core';
+import {
+  assertNoDrift,
+  checkDrift,
+  type DriftReport,
+  type MigrationReport,
+  migrate,
+} from '@ultimat3/db';
 import type { Route } from '@ultimat3/http';
+import { createIsrController } from '@ultimat3/render';
+import { apiRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import { assetRoutes } from './dev-assets';
@@ -20,9 +34,15 @@ import type { RunningServices } from './dev-runtime';
 import { startServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { resolveServices } from './dev-services';
+import { storageRoutes } from './dev-storage';
 import { PortInvalidError, RoleUnknownError } from './errors';
 import { holdUntilShutdown } from './hold';
+import { buildIslands } from './island-bundle';
+import { islandRoutes } from './island-routes';
+import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import { readMigrations } from './migrations';
+import { startOtlpExport } from './otlp-export';
+import type { RuntimeOverrides } from './runtime-overrides';
 
 export const DEFAULT_PORT = 3000;
 
@@ -40,19 +60,57 @@ export function roleFromEnv(env: Env): Role {
 }
 
 /**
- * Every PaaS injects `PORT` and routes traffic to exactly it. `Number.parseInt` would read `80abc`
- * as 80, so the whole string has to be a port — a partially-parsed port is a deploy that binds
- * somewhere nobody asked for.
+ * `Number.parseInt` would read `80abc` as 80, so the whole string has to be a port — a
+ * partially-parsed port is a deploy that binds somewhere nobody asked for.
  */
-export function portFromEnv(env: Env): number {
-  const raw = env['PORT'];
-  if (raw === undefined || raw.trim().length === 0) return DEFAULT_PORT;
+function portValue(env: Env, name: string, fallback: number): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim().length === 0) return fallback;
   const port = Number(raw.trim());
   if (!Number.isInteger(port) || port < 0 || port > 65_535)
-    throw new PortInvalidError({ value: raw });
+    throw new PortInvalidError({ value: raw, name });
   return port;
 }
 
+/** Every PaaS injects `PORT` and routes traffic to exactly it. */
+export function portFromEnv(env: Env): number {
+  return portValue(env, 'PORT', DEFAULT_PORT);
+}
+
+/**
+ * The scrape port, deliberately its own env var and not `PORT + n`: an operator who moves the app
+ * port must not silently move the port their Prometheus is configured against, and the roles that
+ * set no `PORT` at all — `worker`, `scheduler`, `replicator` — still need this one.
+ */
+export function metricsPortFromEnv(env: Env): number {
+  return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
+}
+
+/**
+ * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
+ * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
+ * wire format behind it is documented and self-hostable, and `SENTRY_DSN` is what every monitor
+ * that speaks it already documents — inventing a second spelling would mean an operator's existing
+ * tooling sets a variable this framework ignores. Exactly the precedent
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` already sets in `docker/helm/values.yaml`.
+ */
+export const ERROR_DSN_KEY = 'SENTRY_DSN';
+
+/**
+ * Switch reporting on for this process. Unset DSN leaves core's no-op reporter in place, so a
+ * laptop and a CI run pay nothing and page nobody — and the release every event carries is the
+ * build id this boot already computed, never a second identity for the same deploy.
+ */
+export function configureReporting(env: Env, buildId: string): void {
+  const dsn = env[ERROR_DSN_KEY]?.trim();
+  configureErrorReporting({
+    release: buildId,
+    // A malformed DSN throws here, at boot, rather than at the first outage: a monitor that was
+    // never connected looks exactly like an app that never failed.
+    ...(dsn === undefined || dsn.length === 0 ? {} : { reporter: sentryErrorReporter({ dsn }) }),
+  });
+}
+
 export interface ServeOptions {
   readonly root: string;
   readonly env: Env;
@@ -60,6 +118,18 @@ export interface ServeOptions {
   readonly role?: Role;
   /** Overrides `PORT`. 0 asks the kernel for an ephemeral one, which is what a test wants. */
   readonly port?: number;
+  /** Overrides `METRICS_PORT`, on the same terms. */
+  readonly metricsPort?: number;
+  /**
+   * The drivers this deployment supplies instead of the ones the environment would select.
+   *
+   * This field is why `apps/web/server.ts` can stay three lines and still run a custom queue, a
+   * shared ISR store or an app's own middleware. Before it there was nowhere to hand the framework
+   * a driver, so the only way was an ambient setter from an app module — which `loadApp` imports
+   * AFTER `startServices` has captured its own, giving a process that enqueues to one queue and
+   * claims from another. `startRoles` now refuses that split outright.
+   */
+  readonly runtime?: RuntimeOverrides;
 }
 
 export interface ServedApp {
@@ -77,6 +147,8 @@ export interface MigratedApp {
   readonly kind: 'migrated';
   readonly role: 'migrate';
   readonly report: MigrationReport;
+  /** The post-condition: the live schema against the ledger this run just wrote. */
+  readonly drift: DriftReport;
 }
 
 export type StartedApp = ServedApp | MigratedApp;
@@ -90,9 +162,16 @@ export type StartedApp = ServedApp | MigratedApp;
  *
  * It boots the queue, not the whole runtime: this role touches the database and nothing else, and
  * `startQueue` is what installs `db()` for `migrate()` to find.
+ *
+ * The drift check is the post-condition, and it lives here rather than in `cmd-db.ts` for the same
+ * reason the migrator does: it needs the connection this function opened, and a developer and a
+ * release phase must not verify different things. It is **returned, never thrown** — the role's
+ * contract is "apply every migration, then exit", and a schema difference after a clean apply is a
+ * diagnostic, not a failed migration. `x db migrate` is where it is actionable, so `x db migrate`
+ * is what fails on it.
  */
 export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
-  const queue = await startQueue(resolveServices(options.root, options.env));
+  const queue = await startQueue(resolveServices(options.root, options.env), options.runtime);
   try {
     const migrations = await readMigrations(options.root);
     const report = await migrate({
@@ -106,12 +185,43 @@ export async function runMigrations(options: ServeOptions): Promise<MigratedApp>
       available: migrations.length,
       appVersion: report.appVersion,
     });
-    return { kind: 'migrated', role: 'migrate', report };
+    const drift = await checkDrift({ migrations });
+    // Logged with the first difference, not just a count: a release phase's log is the only place
+    // an operator sees this, and "3 differences" names nothing to act on.
+    if (!drift.ok) {
+      logger.warn('ultimate migrate drift', {
+        differences: drift.differences.length,
+        cause: drift.differences[0]?.cause,
+        fix: drift.differences[0]?.fix,
+      });
+    }
+    return { kind: 'migrated', role: 'migrate', report, drift };
   } finally {
     await queue.stop();
   }
 }
 
+/**
+ * Release what a boot acquired before it failed, newest first.
+ *
+ * Every failure here is swallowed, because the step that refused to start is the one worth
+ * reporting — the same rule `startRoles`' own rollback runs by. Without it a throw between
+ * `startServices` and `startRoles` left the Postgres pool, the queue and the OTLP exporter running
+ * in a process whose caller has already given up: `x dev` and the container both retry the boot,
+ * and the second attempt met a `.x/pgdata` the first one still held.
+ */
+export async function releaseBoot(
+  acquired: readonly (() => void | Promise<void>)[],
+): Promise<void> {
+  for (const release of [...acquired].reverse()) {
+    try {
+      await release();
+    } catch {
+      // Deliberately empty: see above.
+    }
+  }
+}
+
 /**
  * Boot order is `x dev`'s, for the reason `x dev` gives: services, then the app's own modules
  * (importing them IS the registration), then the role that serves what they registered. The route
@@ -120,7 +230,29 @@ export async function runMigrations(options: ServeOptions): Promise<MigratedApp>
  */
 export async function serveApp(options: ServeOptions): Promise<ServedApp> {
   const role = options.role ?? roleFromEnv(options.env);
-  const runtime = await startServices(resolveServices(options.root, options.env), options.env);
+  const runtime = await startServices(
+    resolveServices(options.root, options.env),
+    options.env,
+    options.runtime,
+  );
+  // Everything acquired from here down, in order, so a throw anywhere below gives it all back.
+  const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
+  try {
+    return await bootRoles({ options, role, runtime, acquired });
+  } catch (error) {
+    await releaseBoot(acquired);
+    throw error;
+  }
+}
+
+/** The half of `serveApp` whose every acquisition is registered for rollback. */
+async function bootRoles(boot: {
+  readonly options: ServeOptions;
+  readonly role: Role;
+  readonly runtime: RunningServices;
+  readonly acquired: (() => void | Promise<void>)[];
+}): Promise<ServedApp> {
+  const { options, role, runtime, acquired } = boot;
   // Importing the app's modules IS the registration: every route, action and job below is
   // whatever this call put in the registries.
   await loadApp(options.root);
@@ -133,20 +265,61 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
     stamped !== undefined && stamped.length > 0
       ? stamped
       : (await appManifest(options.root)).manifest.buildId;
+  // Before the first socket opens: everything above this line fails loudly into the container's
+  // own logs, everything below it is a served request, a claimed job or a routed frame.
+  configureReporting(options.env, buildId);
+  // Beside error reporting, and for the same reason it is here: `OTEL_EXPORTER_OTLP_ENDPOINT` is
+  // in the shipped chart and nothing read it, so every deployment that configured a collector got
+  // an empty dashboard. `x dev` keeps its own recorder — the `/_x` timeline is a different sink
+  // with a different lifetime — so this is the production boot's alone (axiom 6).
+  const stopOtlp = startOtlpExport(options.env);
+  acquired.push(stopOtlp);
+  // Built at boot rather than shipped prebuilt, so the container serves the same chunks `x dev`
+  // does from the same source — the alternative is a second bundler invocation in the image build
+  // whose output nothing compares against the one the dev loop proved.
+  const islands = await buildIslands(options.root);
   const routes: readonly Route[] = [
-    ...listActions().map(toRoute),
-    ...assetRoutes({ root: options.root, storage: runtime.storage }),
-    ...appRoutes({ buildId }),
+    ...apiRoutes(),
+    ...assetRoutes({
+      root: options.root,
+      storage: runtime.storage,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+    }),
+    ...storageRoutes({ storage: runtime.storage }),
+    ...islandRoutes(() => islands),
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => islands.resolverFor(file),
+      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
+      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
+      // the fleet while the other eleven keep serving the page it just invalidated.
+      ...(options.runtime?.isrStore === undefined
+        ? {}
+        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+    }),
   ];
+  const port = options.port ?? portFromEnv(options.env);
+  // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+  // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
+  // still wins — that is the deploy talking.
+  const metricsPort =
+    options.metricsPort ??
+    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
   const running = await startRoles({
     roles: [role],
-    port: options.port ?? portFromEnv(options.env),
+    port,
+    metricsPort,
     buildId,
     runtime,
     routes,
     env: options.env,
+    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
+    // guarded page with the problem document, rendered as raw JSON in the viewport.
+    signInPath: await loadSignInPath(options.root),
     http: CONTAINER_BINDING,
+    ...(options.runtime === undefined ? {} : { overrides: options.runtime }),
   });
+  acquired.push(() => running.stop());
   return {
     kind: 'served',
     role,
@@ -157,6 +330,9 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
     async stop() {
       await running.stop();
       await runtime.stop();
+      // Last: the exporters outlive the roles they were recording, so the drain's own spans and
+      // the final counter snapshot still have somewhere to go.
+      stopOtlp();
     },
   };
 }
@@ -168,7 +344,15 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
  */
 export async function runRole(options: ServeOptions): Promise<StartedApp> {
   const role = options.role ?? roleFromEnv(options.env);
-  if (role === 'migrate') return runMigrations({ ...options, role });
+  if (role === 'migrate') {
+    const migrated = await runMigrations({ ...options, role });
+    // The release phase has one channel — the exit code — so drift is thrown here rather than
+    // returned. `x db migrate` calls the same `runMigrations` and renders every difference as a
+    // finding before exiting non-zero; a container that logged one and exited 0 would let the
+    // deploy roll on over a schema nobody can reconstruct, which is the failure drift exists for.
+    assertNoDrift(migrated.drift);
+    return migrated;
+  }
   const app = await serveApp({ ...options, role });
   logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
   await holdUntilShutdown('serve', () => app.stop())();

package/src/source-files.ts

@@ -4,6 +4,10 @@
 
 export const SOURCE_GLOBS = [
   'packages/*/src/**/*.{ts,tsx}',
+  // Three packages carry an `e2e` directory beside `src`. It is shipped source by every rule that
+  // matters here — a 900-line file or an unrunnable `fix:` in one was invisible to `filesize` and
+  // `errors` alike, and `scripts/boundaries.ts` walked past it for the same reason.
+  'packages/*/e2e/**/*.{ts,tsx}',
   'scripts/**/*.{ts,tsx}',
   'site/**/*.{ts,tsx}',
   'app/**/*.{ts,tsx}',

package/src/statement-loop.ts

@@ -0,0 +1,74 @@
+// One repeated statement shape, as every surface renders it. The ledger next door decides that a
+// shape repeated; `@ultimat3/entity` decides which fix it has earned; this file is the one
+// projection all four surfaces read — so `x dev`'s findings, the `/_x` timeline, the browser
+// overlay and the log line can never disagree about a loop's code, its cause or the line that ends it.
+
+import type { StatementLoopFact } from '@ultimat3/admin/dev';
+import { logger } from '@ultimat3/core';
+import { nPlusOne } from '@ultimat3/entity';
+import type { OverlayNotice } from '@ultimat3/http';
+import type { RepeatedStatement } from './dev-n-plus-one';
+import type { Finding } from './output';
+
+/**
+ * The verdict, as an error — built here rather than in the ledger because the count keeps rising
+ * after a shape is promoted: a loop of fifty reads `ran 50 times` when a surface asks, not
+ * `ran 5 times` because that is where the threshold sat. `nPlusOne` is `@ultimat3/entity`'s, and
+ * deliberately: the `fix:` names `preload`, `insertAll` and `updateWhere`, which are that package's
+ * vocabulary and derived from the relations the schema already declared — a line composed here
+ * would be a second answer to "what ends this loop", one the schema never agreed to.
+ */
+export function loopFacts(repeat: RepeatedStatement): StatementLoopFact {
+  const attribution = repeat.attribution;
+  const error = nPlusOne({
+    kind: repeat.kind,
+    subject: repeat.fingerprint,
+    count: repeat.count,
+    entity: attribution?.entity,
+    op: attribution?.op,
+  });
+  return {
+    requestId: repeat.requestId,
+    code: error.code,
+    cause: error.cause,
+    fix: error.fix,
+    docs: error.docs ?? null,
+    subject: repeat.fingerprint,
+    count: repeat.count,
+    sample: repeat.sample,
+  };
+}
+
+/**
+ * The `x dev` half. `at` is the request id and not a file: a loop has no line to open — it is a
+ * page's worth of statements — and the id is what joins this finding to the timeline's own row and
+ * to the log line the same request emitted.
+ */
+export const loopFinding = (facts: StatementLoopFact): Finding => ({
+  code: facts.code,
+  cause: facts.cause,
+  fix: facts.fix,
+  at: facts.requestId,
+  ...(facts.docs === null ? {} : { docs: facts.docs }),
+});
+
+/** The browser half. `exactOptionalPropertyTypes`: an absent doc link is omitted, never `undefined`. */
+export const loopNotice = (facts: StatementLoopFact): OverlayNotice => ({
+  code: facts.code,
+  cause: facts.cause,
+  fix: facts.fix,
+  ...(facts.docs === null ? {} : { docs: facts.docs }),
+});
+
+/**
+ * The log half, emitted once per request per code by the ledger that counts.
+ *
+ * The root logger and not `ctx.logger`, because this runs inside the request's own ALS scope and
+ * core's `setLoggerContextFields` puts `requestId` and `traceId` on every line emitted there — so
+ * the ids ride along without this file reaching for a context it would then have to prove it had.
+ * One line, in the 3-line contract's own order, because a warning an agent has to reassemble from
+ * three log records is a warning it acts on in three passes.
+ */
+export const warnLoop = (facts: StatementLoopFact): void => {
+  logger.warn(`${facts.code}: ${facts.cause} — fix: ${facts.fix}`);
+};

package/src/style-csp.ts

@@ -0,0 +1,18 @@
+// Every inline `<style>` body a served process can put in a document, as the `style-src` sources
+// that admit it. Read from the stylesheet registry at boot rather than checked in as a constant:
+// importing the app's modules IS what fills that registry, so a committed hash would describe a
+// stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
+
+import { cspHashSource } from '@ultimat3/http';
+import { SURFACES, stylesFor } from '@ultimat3/render';
+
+/**
+ * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in
+ * the tag, per surface, so hashing the same call is the only way the two cannot drift. `extra`
+ * carries the documents this package does not render — `/_x`'s shell — because the caller is what
+ * knows which of them it mounted.
+ */
+export function inlineStyleSources(extra: readonly string[] = []): readonly string[] {
+  const bodies = [...SURFACES.map((surface) => stylesFor(surface)), ...extra];
+  return [...new Set(bodies.filter((body) => body.length > 0).map(cspHashSource))].sort();
+}