@ultimat3/cli 1.2.0 → 3.0.0

package/src/dev-storage.ts

@@ -0,0 +1,247 @@
+// Single responsibility: the one HTTP surface that SERVES a stored object. `@ultimat3/storage`
+// owns keys, bytes and the tenant boundary and owns no `Response`; `@ultimat3/policy` owns the
+// one authz decision; this file is where those two meet a `Route` — the same shape `dev-assets.ts`
+// uses for `/icons` and `/media`, so `x dev` and `apps/web/server.ts` mount one read path, not two.
+//
+// The base path is `@ultimat3/storage`'s `DEFAULT_SIGNED_URL_BASE`, imported and never restated:
+// `localDriver` SIGNS `/_storage/<disk>/<key>`, so a local `'/_storage'` here is a second statement
+// of one constant — and a signer and a reader that disagree serve 404 for every signed URL.
+
+import { actorOf } from '@ultimat3/action';
+import type { Actor } from '@ultimat3/core';
+import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
+import { asCtx, unauthenticated } from '@ultimat3/http';
+import type { KnownPermission } from '@ultimat3/policy';
+import { can, codeOf, evaluate, forbidden, reasonOf } from '@ultimat3/policy';
+import type { Storage, StorageRead } from '@ultimat3/storage';
+import {
+  assertSafeKey,
+  DEFAULT_SIGNED_URL_BASE,
+  isTenantScoped,
+  isWithinOrg,
+  objectNotFound,
+  orgMismatch,
+} from '@ultimat3/storage';
+
+/**
+ * The one capability that gates reading a stored object, on every disk. A permission and not a
+ * per-disk family: `disk` is in the policy's `input`, so an app that wants a per-disk rule writes
+ * one predicate over it, while a second permission string would be a second thing to grant and to
+ * forget. An app that declared a permission set without it gets `X_PERMISSION_UNKNOWN` from
+ * `can()` — naming the exact `definePermissions` edit — rather than a request that quietly worked.
+ */
+export const STORAGE_READ_PERMISSION = 'storage:read';
+
+/**
+ * `can()` takes a `KnownPermission`, which narrows to the APP's declared set the moment an app
+ * augments `PermissionRegistry` — and this package compiles against no app, so the bare literal is
+ * a type error inside a generated project (`scaffold-typecheck` is what proves it). The check that
+ * decides is the runtime one anyway: `can()` calls `assertPermission`, which throws
+ * `X_PERMISSION_UNKNOWN` naming the `definePermissions` edit. `dev-hooks.ts` narrows a route's
+ * structurally-typed permission for the same reason.
+ */
+const READ_PERMISSION = STORAGE_READ_PERMISSION as unknown as KnownPermission;
+
+/**
+ * The cache posture of a response that was authorized for ONE actor, named once so the two routes
+ * that serve stored bytes cannot declare different ones — which they did: `/media` answered
+ * `public, max-age=31536000, immutable` for the same object this route marks private, so a CDN held
+ * one tenant's file under a public key for a year. Revalidation costs a request and no bytes, which
+ * is the trade an authorized response wants: the bytes never change under a key, but the actor's
+ * permission to read them can be revoked. `vary` names the two headers that carry an identity.
+ */
+export const AUTHORIZED_OBJECT_CACHE: CacheHint = {
+  mode: 'private',
+  maxAgeSeconds: 0,
+  vary: ['authorization', 'cookie'],
+};
+
+/** What the rule decides about. The key IS the object's identity, so this is the whole subject. */
+export interface StorageReadInput {
+  readonly disk: string;
+  readonly key: string;
+}
+
+/**
+ * The single door. `evaluate()` is the framework's one authz entry point and this is a plain call
+ * to it — no inline permission test, no per-surface args type, no "public unless configured".
+ *
+ * Evaluated with NO row, deliberately. An object's owner is encoded in its key (`org/<id>/<entity>/
+ * <id>/<field>/…`), which `input` already carries, so a `StorageObject` would hand a predicate
+ * nothing it cannot already read — and loading one first would decide "does it exist" before
+ * "may you read it", which is how a caller learns another tenant's keys by watching the status.
+ */
+export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContext): void {
+  const context = asCtx(ctx);
+  // Built per request, not at mount: an app whose permission set lacks `storage:read` must get a
+  // problem document on this route, not a boot that takes every other route down with it.
+  const policy = can<StorageReadInput>(READ_PERMISSION);
+  const evaluation = evaluate(policy, { input, actor: actorOf(context) });
+  if (evaluation.allowed) return;
+  // The decision's own code goes on the wire, never a flattened one: `can()` denies "nobody" with
+  // X_UNAUTHENTICATED and a known actor with X_FORBIDDEN, and 401 and 403 are different
+  // instructions — "log in" against "you may not". `reason` is the deciding clause's own words,
+  // which `@ultimat3/policy` guarantees are safe to log.
+  const reason = reasonOf(evaluation.decision) ?? 'denied';
+  throw codeOf(evaluation.decision) === 'X_UNAUTHENTICATED'
+    ? unauthenticated(ctx.url.pathname)
+    : forbidden(policy.label, reason);
+}
+
+/**
+ * The key half of the read decision, in the order that discloses least: a key that could escape its
+ * prefix is refused before any tenant is named, and a key inside another tenant's prefix is 404
+ * (never 403 — `error-map.ts` maps `X_STORAGE_ORG_MISMATCH` there so a refusal cannot confirm that
+ * a key exists).
+ *
+ * Split out of `readStorageObject` because `/media/*key` (`dev-assets.ts`) has to make the same
+ * decision and made none at all: it passed a client-supplied key straight to `disk().get`, so every
+ * object on the app's only disk was one unauthenticated URL away. A second copy of this test is how
+ * one of the two surfaces would drift back — `storage-surfaces.test.ts` is what holds them level.
+ */
+export function assertReadableKey(key: string, actor: Actor): string {
+  const safe = assertSafeKey(key);
+  // An actor with no org is inside no org, so every tenant-scoped key is somebody else's. Checked
+  // before `isWithinOrg`, which reads an empty org as a malformed key and would blame the caller's
+  // URL for the actor's missing claim.
+  const orgId = actor.orgId ?? '';
+  if (isTenantScoped(safe) && (orgId === '' || !isWithinOrg(safe, orgId))) {
+    throw orgMismatch(safe, orgId);
+  }
+  return safe;
+}
+
+/**
+ * Everything between the decision and the bytes. An unknown disk is the same 404 the foreign-tenant
+ * case answers, rather than `X_STORAGE_DISK_UNKNOWN`, whose cause lists every configured disk name.
+ */
+export async function readStorageObject(
+  storage: Storage,
+  input: StorageReadInput,
+  actor: Actor,
+): Promise<StorageRead> {
+  const key = assertReadableKey(input.key, actor);
+  if (!storage.diskNames.includes(input.disk)) throw objectNotFound(input.disk, key);
+  return storage.disk(input.disk).get(key);
+}
+
+/** Inclusive, as `Range` and `Content-Range` both are. */
+export interface ByteRange {
+  readonly start: number;
+  readonly end: number;
+}
+
+const UNSATISFIABLE = 'unsatisfiable';
+
+/**
+ * One range or none. A multi-range or malformed header is ignored rather than refused — RFC 9110
+ * lets a server answer the whole representation, and `multipart/byteranges` is a body format no
+ * caller of this route asks for. Ranges exist here for one reason: Safari will not play a `<video>`
+ * from a source that answers 200 to a `Range` probe, so an uploaded video would be a dead player.
+ */
+export function parseByteRange(
+  header: string | null,
+  size: number,
+): ByteRange | typeof UNSATISFIABLE | undefined {
+  if (header === null) return undefined;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (match === null) return undefined;
+  const from = match[1] ?? '';
+  const to = match[2] ?? '';
+  if (from === '' && to === '') return undefined;
+  if (from === '') {
+    const wanted = Number(to);
+    // A suffix longer than the object is the whole object, not a refusal.
+    return wanted === 0 ? UNSATISFIABLE : { start: Math.max(size - wanted, 0), end: size - 1 };
+  }
+  const start = Number(from);
+  const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);
+  return start >= size || end < start ? UNSATISFIABLE : { start, end };
+}
+
+/** `*`, a weak validator and a comma list all count — the etag is what has to match. */
+export function etagMatches(header: string | null, etag: string): boolean {
+  if (header === null) return false;
+  if (header.trim() === '*') return true;
+  return header.split(',').some((candidate) => candidate.trim().replace(/^W\//, '') === etag);
+}
+
+/**
+ * The content type is the STORED one — the upload gate sniffed those bytes and `put` recorded the
+ * answer, so an extension in the URL is the only party that can lie. The validator is the driver's
+ * own content hash (local: sha256 of the bytes, S3: the provider's etag), which is the identity
+ * storage already keeps for an object; inventing a cache key here would be a second one.
+ */
+export function storageResponse(request: UltimateRequest, read: StorageRead): Response {
+  const etag = `"${read.object.etag}"`;
+  const headers = new Headers({
+    'content-type': read.object.contentType,
+    etag,
+    'last-modified': read.object.lastModified.toUTCString(),
+    'accept-ranges': 'bytes',
+  });
+  // Revalidation costs a request and no bytes, which is the trade an authorized response wants:
+  // the bytes never change under a key, but the actor's permission to read them can be revoked.
+  if (etagMatches(request.header('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+
+  const size = read.bytes.byteLength;
+  const range = parseByteRange(request.header('range'), size);
+  if (range === UNSATISFIABLE) {
+    headers.set('content-range', `bytes */${size}`);
+    return new Response(null, { status: 416, headers });
+  }
+  // Copied at each call, not through a helper, for `dev-assets.ts`'s reason: a
+  // `Uint8Array<ArrayBufferLike>` may be backed by a `SharedArrayBuffer`, which `Response` does
+  // not accept — and a helper's declared return type widens the copy back to the type it refuses.
+  if (range === undefined) {
+    headers.set('content-length', String(size));
+    return new Response(new Uint8Array(read.bytes), { headers });
+  }
+  const slice = read.bytes.subarray(range.start, range.end + 1);
+  headers.set('content-range', `bytes ${range.start}-${range.end}/${size}`);
+  headers.set('content-length', String(slice.byteLength));
+  return new Response(new Uint8Array(slice), { status: 206, headers });
+}
+
+export interface StorageRoutesOptions {
+  /** The configured disks. The driver seam only — this route never assumes a filesystem. */
+  readonly storage: Storage;
+}
+
+/**
+ * `enforcedBy: 'handler'` for the reason an action route says it: the handler is the one
+ * evaluation. The `authz` stage decides through `ServerHooks.authorize`, which resolves a policy
+ * from `@ultimat3/render`'s page-route table — a table this route is not in, so the stage would
+ * deny every request with "no policy is registered" and the real rule would never run.
+ *
+ * `auth: 'required'` so an anonymous caller is 401 before the handler, and `cache` is declared
+ * rather than applied here: the pipeline's `cache-headers` stage is the one place a hint becomes a
+ * header. `private` because the response is authorized per actor, and `vary` on the two headers
+ * that carry an identity so no shared cache can hand one actor's object to another.
+ */
+export function storageRoutes(options: StorageRoutesOptions): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${DEFAULT_SIGNED_URL_BASE}/:disk/*key`,
+      meta: {
+        name: 'storage.read',
+        auth: 'required',
+        policy: STORAGE_READ_PERMISSION,
+        enforcedBy: 'handler',
+        cache: AUTHORIZED_OBJECT_CACHE,
+        tags: ['storage'],
+      },
+      handler: async (request: UltimateRequest, ctx: RequestContext): Promise<Response> => {
+        const input: StorageReadInput = {
+          disk: request.params['disk'] ?? '',
+          key: request.params['key'] ?? '',
+        };
+        authorizeStorageRead(input, ctx);
+        return storageResponse(request, await readStorageObject(options.storage, input, ctx.actor));
+      },
+    },
+  ];
+}

package/src/dev-sync.ts

@@ -0,0 +1,107 @@
+// The `sync` role: which live queries this node serves, who is dialling it, and the socket it owns.
+// Split from `dev-roles.ts` because it is the one role with an authenticator, a presence registry
+// and a listener of its own — and because that file is the boot's index, not its detail.
+
+import { createContext, logger } from '@ultimat3/core';
+import { listQueries } from '@ultimat3/query';
+import {
+  ChannelHub,
+  createSyncNode,
+  LiveQueryRegistry,
+  listenSyncNode,
+  liveQueryDefinition,
+  PresenceRegistry,
+  RingChangeBuffer,
+  SocketRegistry,
+} from '@ultimat3/realtime';
+import type { StartRolesOptions } from './dev-roles';
+import { syncAuthenticator } from './sync-authenticator';
+
+/** What `startRoles` holds on to: where the node listens, and how to take it down. */
+export interface RunningSync {
+  readonly url: string;
+  stop(): Promise<void>;
+}
+
+/**
+ * Every read the app declared `live: true` becomes a subscribable query on this node, through
+ * `@ultimat3/realtime`'s own bridge. A registry with nothing in it answers every live `subscribe`
+ * with "no live query registered", which is a working socket serving no reads — and it is what
+ * kept the row gate that decides per subscriber from ever running outside a unit test.
+ *
+ * The context is the node's, and it carries no actor: it supplies the services and the clock the
+ * shared read needs, never an authority. Who may subscribe, and which rows they see, is decided
+ * per socket at subscribe time and again for every row of every delivery.
+ *
+ * **The per-TENANT subscription cap is deliberately unset, and both halves of it are.**
+ * `assertCapacity` returns early unless `maxPerTenant` AND `tenantOf` are both given, so passing
+ * one arms nothing — a knob that quietly does nothing is the defect this whole seam exists to
+ * close. And no default is defensible: one tenant is a single person and the next is five
+ * thousand seats, so any number here is either unreachable or an outage on a Monday morning. The
+ * per-socket 128 stands because a socket is one browser tab, which is a bound the framework can
+ * actually know. A deployment that wants the tenant cap passes both:
+ *
+ *   new LiveQueryRegistry({ …, maxPerTenant: 5_000, tenantOf: (actor) => actor?.orgId ?? null })
+ */
+export function registerLiveQueries(options: StartRolesOptions): LiveQueryRegistry {
+  const registry = new LiveQueryRegistry({
+    source: new RingChangeBuffer(),
+    // A withheld row is a metric, never a frame and never an error: telling a client "there is a
+    // row you may not see" is the leak the gate exists to prevent.
+    onRowDenied: (event) => logger.debug('live.rows_denied', { ...event }),
+  });
+  const ctx = createContext({ role: 'sync', buildId: options.buildId });
+  for (const target of listQueries()) {
+    if (target.isLive) registry.register(liveQueryDefinition(target, { ctx }));
+  }
+  return registry;
+}
+
+/**
+ * The sync role owns its own socket: websockets and the request pipeline drain differently.
+ *
+ * Port 0 is passed straight through rather than incremented — `+ 1` would ask the kernel for
+ * port 1 instead of an ephemeral one — and the reported url is the listener's own bound address,
+ * never a string built from the port that was requested.
+ */
+export async function startSync(options: StartRolesOptions): Promise<RunningSync> {
+  const sockets = new SocketRegistry();
+  const hub = new ChannelHub({ transport: options.runtime.transport, sockets });
+  // The node evaluated no credential of its own and no host ever handed it one, so every socket
+  // the framework opened was anonymous and every guard, gate, presence entry and tenant cap
+  // decided against `null`. An explicit override first — only that one can carry an `expiresAt`
+  // and a `refresh`, which is the whole of re-authorization — then the app's own HTTP resolver,
+  // then nothing at all, which is what `x dev` with no authenticator should stay.
+  const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
+  const node = createSyncNode({
+    hub,
+    registry: registerLiveQueries(options),
+    transport: options.runtime.transport,
+    buildId: options.buildId,
+    sockets,
+    ...(authenticate === undefined ? {} : { authenticate }),
+    // Tier 1 is presence, and without a registry the node answers a topic subscribe with no member
+    // list at all — the KV bucket the transport just created would hold nothing and every `sync`
+    // container would run a presence-less protocol. It reads and writes `transport.shared`, so it
+    // is exactly as multi-node as the transport behind it: in-process here, the bucket under NATS.
+    presence: new PresenceRegistry({
+      transport: options.runtime.transport,
+      hub,
+      ttlMs: options.runtime.presenceTtlMs,
+    }),
+  });
+  await node.start();
+  try {
+    const listener = listenSyncNode(node, { port: options.port === 0 ? 0 : options.port + 1 });
+    return {
+      url: listener.url,
+      stop: async () => {
+        listener.stop();
+        await node.stop();
+      },
+    };
+  } catch (error) {
+    await node.stop();
+    throw error;
+  }
+}

package/src/dev-traces.ts

@@ -5,6 +5,9 @@
 
 import type { RequestTrace, SpanKind, TimelineSpan } from '@ultimat3/admin/dev';
 import type { ReadableSpan, SpanExporter } from '@ultimat3/core';
+// The attribute name is `@ultimat3/db`'s to declare — this reads it rather than restating it, so
+// renaming it there is a compile error here instead of a panel that silently groups nothing.
+import { STATEMENT_ATTRIBUTE } from '@ultimat3/db';
 
 /** Traces retained. A dev panel shows recent requests; it does not page through history. */
 const DEFAULT_LIMIT = 50;
@@ -23,6 +26,10 @@ export interface TraceRecorder {
  * prefix IS the kind — no registry of names to keep in step with the packages that emit them.
  */
 const KIND_BY_PREFIX: readonly (readonly [string, SpanKind])[] = [
+  // Two producers of `sql`, one axis: `db.` is the statement itself (`db.select`, carrying its
+  // text), `query.` is the read that compiled it. The panel counts repeats of the detail, so a
+  // repository loop shows up as one SQL text fifty times and not as one `query.feed`.
+  ['db.', 'sql'],
   ['query.', 'sql'],
   ['cache.', 'cache'],
   ['action.', 'action'],
@@ -64,9 +71,27 @@ function requestFacts(root: ReadableSpan): { method: string; path: string } {
   };
 }
 
+/** `http.request_id` is stamped by the pipeline's root and by nothing else; the name is a fallback. */
 const isHttpRoot = (span: ReadableSpan): boolean =>
-  span.parentSpanId === undefined &&
-  (span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name));
+  span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name);
+
+/**
+ * The request's own span among a trace's. `parentSpanId === undefined` was a third CONDITION
+ * until `As of 2026-08`, and it dropped every request that arrived with an inbound
+ * `traceparent`: `pipeline.ts` passes `parent: correlation.parent`, so the root has a defined
+ * `parentSpanId`, `spans.find(isHttpRoot)` answered `undefined`, and the whole trace vanished
+ * from `/_x/timeline` for any caller behind an instrumented client, an ingress or a service
+ * mesh. It survives as the TIE-BREAK: the outermost candidate is the one whose parent is not
+ * itself in this recording, so a nested candidate can never outrank the request's own span.
+ */
+function httpRootOf(spans: readonly ReadableSpan[]): ReadableSpan | undefined {
+  const candidates = spans.filter(isHttpRoot);
+  const recorded = new Set(spans.map((span) => span.context.spanId));
+  const outermost = candidates.find(
+    (span) => span.parentSpanId === undefined || !recorded.has(span.parentSpanId),
+  );
+  return outermost ?? candidates[0];
+}
 
 function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTrace {
   const { method, path } = requestFacts(root);
@@ -89,9 +114,10 @@ function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTra
           name: span.name,
           startMs: Math.max(0, span.startedAt - origin),
           durationMs: span.durationMs,
-          // The panel counts repeats of `detail` to find the N+1, and a framework span's name is
-          // exactly the identity that repeats — `query.feed` twice is two reads of one query.
-          detail: attrString(span, 'db.statement') ?? span.name,
+          // The panel counts repeats of `detail` to find the N+1. A statement states its own
+          // identity (`STATEMENT_ATTRIBUTE`, set by `@ultimat3/db`'s funnels); for every other span
+          // the name is that identity — `query.feed` twice is two reads of one query.
+          detail: attrString(span, STATEMENT_ATTRIBUTE) ?? span.name,
         }),
       )
       .sort((a, b) => a.startMs - b.startMs),
@@ -113,7 +139,11 @@ export function createTraceRecorder(options: { limit?: number } = {}): TraceReco
     const spans = byTrace.get(traceId);
     if (spans === undefined) {
       byTrace.set(traceId, [span]);
-      // Bounded by trace, not by span: dropping half a request would leave a flame with holes.
+      // Bounded by TRACE, not by span: dropping half a request would leave a flame with holes.
+      // The cost is stated rather than capped — one trace's span array has no bound of its own, so
+      // a request issuing 50k statements holds 50k `ReadableSpan`s until it is evicted. That is a
+      // dev-only recorder (`serve.ts` installs none), and a per-trace cap would silently produce
+      // the holed flame this bound exists to prevent.
       while (byTrace.size > limit) {
         const oldest = byTrace.keys().next();
         if (oldest.done === true) break;
@@ -129,7 +159,7 @@ export function createTraceRecorder(options: { limit?: number } = {}): TraceReco
     traces(): readonly RequestTrace[] {
       const traces: RequestTrace[] = [];
       for (const spans of byTrace.values()) {
-        const root = spans.find(isHttpRoot);
+        const root = httpRootOf(spans);
         if (root !== undefined) traces.push(toTrace(root, spans));
       }
       return traces.sort((a, b) => b.startedAt.localeCompare(a.startedAt));

package/src/dispatch.ts

@@ -12,7 +12,7 @@ import { exec } from './exec';
 import type { CommandResult } from './output';
 import { exitCodeFor, findingFrom, render } from './output';
 import type { ParsedArgs } from './parse';
-import { parseArgs } from './parse';
+import { parseArgs, wantsJson } from './parse';
 import { commandFor, SPECS } from './registry';
 
 export interface DispatchOptions {
@@ -47,8 +47,10 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     requireBunVersion(options.bunVersion);
     args = parseArgs(options.argv, SPECS);
   } catch (error) {
+    // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
+    // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
     const result = errorResult('x', error);
-    options.write(render(result, options.argv.includes('--json')));
+    options.write(render(result, wantsJson(options.argv)));
     return 1;
   }
 

package/src/document-styles.ts

@@ -0,0 +1,54 @@
+// One question the gate asks of what a render actually emits: does the document carry its global
+// style layer? Every rule `@ultimat3/ui` emits reads a custom property — `background:rgb(var(
+// --color-bg)/1)`, `padding:var(--space-8)` — so CSS with no `:root` definitions is a document the
+// browser drops every one of those declarations from, byte-for-byte identical to a working page
+// apart from the styling nobody sees missing. A silent failure is exactly what axiom 3 exists for.
+
+import type { Surface } from '@ultimat3/render';
+import { routeEntries, stylesFor } from '@ultimat3/render';
+import type { Finding } from './output';
+
+/** The stylesheet an app is expected to own, named in the fix so it is one edit, not a hunt. */
+export const APP_GLOBAL_STYLESHEET = 'shared/global.scss';
+export const APP_GLOBAL_MODULE = 'shared/global.ts';
+
+/**
+ * A custom property DEFINED at the document root. `var(--color-bg)` is a *use* and cannot match —
+ * there is no colon after the name — which is the whole distinction the check turns on: the broken
+ * document was full of uses and had not one definition.
+ */
+const ROOT_CUSTOM_PROPERTY = /:root[^{}]*\{[^{}]*--[\w-]+\s*:/;
+
+export const definesRootCustomProperties = (css: string): boolean => ROOT_CUSTOM_PROPERTY.test(css);
+
+export interface SurfaceDocument {
+  readonly surface: Surface;
+  /** Exactly the CSS `dev-render.ts` would inline into a document on this surface. */
+  readonly css: string;
+}
+
+/**
+ * Every surface that renders a document, with the CSS one would carry. `api/` is excluded because
+ * it emits no document at all — a surface with nothing to style is not a surface missing its
+ * tokens. Read from render's own registry, filled when the CLI loaded the app: a second walk of
+ * the app's stylesheets here would be a second answer to "what does this document contain".
+ */
+export function documentSurfaces(): readonly SurfaceDocument[] {
+  const surfaces = new Set(routeEntries().map((entry) => entry.surface));
+  surfaces.delete('api');
+  return [...surfaces]
+    .sort()
+    .map((surface) => ({ surface, css: stylesFor(surface) }) satisfies SurfaceDocument);
+}
+
+export function checkDocumentStyles(documents: readonly SurfaceDocument[]): readonly Finding[] {
+  return documents
+    .filter((document) => !definesRootCustomProperties(document.css))
+    .map((document) => ({
+      code: 'X_STYLES_GLOBAL_MISSING',
+      cause: `a ${document.surface}/ document carries ${document.css.length} characters of CSS and defines no :root custom properties, so every var(--color-*) and var(--space-*) in it resolves to nothing`,
+      fix: `add apps/web/${APP_GLOBAL_STYLESHEET} containing \`@use '@ultimat3/ui/global.scss';\` and apps/web/${APP_GLOBAL_MODULE} containing \`import './global.scss';\``,
+      docs: 'https://ultimate.dev/errors/X_STYLES_GLOBAL_MISSING',
+      at: `apps/web/${APP_GLOBAL_STYLESHEET}`,
+    }));
+}

package/src/drift.ts

@@ -1,14 +1,23 @@
-// Migration drift detection. `x db gen` records the hash of the app's entity schema next to the
-// migration it produced; drift is "the schema hashes to something no migration recorded". The
-// hash file is committed beside the migration, so a fresh clone can detect drift with no local
-// state and CI needs no database to answer the question.
+// Source drift: the app's schema *source* against what migrations recorded. `x db gen` writes the
+// hash of the entity schema next to the migration it produced, so drift here is "the schema hashes
+// to something no migration recorded". The hash is committed beside the migration, so a fresh clone
+// answers with no local state and CI needs no database. An app with NO migration at all is the one
+// case that also asks how many entities are declared — see `checkSourceDrift`.
+//
+// This is not the post-migrate verification and deliberately cannot be: that one is the live
+// database against the ledger (`checkDrift`, `@ultimat3/db`), asked by `runMigrations` where a
+// connection is open. Same `X_DB_DRIFT`, two conditions — an entity edited with no migration
+// generated, versus a database that does not match the migrations it ran.
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { countDeclaredEntities } from './app-entities';
+// One declaration of where migrations live, and it belongs to the module that reads them —
+// `x db migrate` and this sidecar must never disagree about the directory they share.
+import { hashFileName, MIGRATIONS_DIR } from './migrations';
 import type { Finding } from './output';
 
 export const DB_PACKAGE = join('packages', 'db');
-export const MIGRATIONS_DIR = join(DB_PACKAGE, 'migrations');
 const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
 
 /** Content hash of the whole schema, order-independent per file path. */
@@ -47,22 +56,81 @@ export async function recordedHashes(root: string): Promise<readonly MigrationRe
   return out;
 }
 
-export async function writeSchemaHash(root: string, migrationName: string): Promise<string> {
+export async function writeSchemaHash(root: string, migrationId: string): Promise<string> {
   const hash = await schemaHash(root);
-  await Bun.write(join(root, MIGRATIONS_DIR, `${migrationName}.hash`), `${hash}\n`);
+  await Bun.write(join(root, MIGRATIONS_DIR, hashFileName(migrationId)), `${hash}\n`);
   return hash;
 }
 
+/**
+ * "Some migration recorded this hash" — the one predicate, read by the check below AND by the
+ * reconcile above it. Two spellings would let `x db gen` report the sidecar written while
+ * `x verify` still reports drift over the same two files.
+ */
+const isRecorded = (records: readonly MigrationRecord[], hash: string): boolean =>
+  records.some((record) => record.hash === hash);
+
+export interface HashReconciliation {
+  readonly hash: string;
+  /** False when a sidecar already held this hash — nothing was written, and nothing needed to be. */
+  readonly written: boolean;
+}
+
+/**
+ * Re-record the sidecar for a migration that is already the right one. `SCHEMA_GLOB` covers every
+ * non-test file under `packages/db/src`, not only the ones that imply DDL, so editing a seed or a
+ * helper moves the hash with no diff behind it — and `X_DB_DRIFT`'s `fix:` has to have somewhere to
+ * land or the instruction is unfollowable. The caller owes the proof that the DDL genuinely did not
+ * move (`db-generate.ts` reaches this only on an empty diff off a fully loaded registry); this
+ * function decides only whether a write is needed.
+ *
+ * A hash an OLDER migration recorded is left alone: `checkSourceDrift` already answers clean on it,
+ * and stamping the newest sidecar would claim that migration produced a schema it did not.
+ */
+export async function reconcileSchemaHash(
+  root: string,
+  migrationId: string,
+): Promise<HashReconciliation> {
+  const hash = await schemaHash(root);
+  if (isRecorded(await recordedHashes(root), hash)) return { hash, written: false };
+  await Bun.write(join(root, MIGRATIONS_DIR, hashFileName(migrationId)), `${hash}\n`);
+  return { hash, written: true };
+}
+
+/**
+ * How many entities the app declares. Injected so this module's own tests need no app on disk, and
+ * so a caller that has already loaded the app can answer without loading it twice.
+ */
+export type DeclaredEntityCount = () => Promise<number>;
+
 /**
  * Empty result = no drift. A missing db package is not drift (an app may have no database yet);
- * a schema with no migration at all is.
+ * a schema with no migration at all is — *provided* the app declares an entity for one to record.
+ *
+ * The entity count is read lazily and ONLY in that first branch, so an app past its first migration
+ * pays nothing for it: every other path answers from file hashes alone, with no app load and no
+ * database, which is what lets the gate run this in a CI with neither.
  */
-export async function checkDrift(root: string): Promise<readonly Finding[]> {
+export async function checkSourceDrift(
+  root: string,
+  declaredEntities: DeclaredEntityCount = () => countDeclaredEntities(root),
+): Promise<readonly Finding[]> {
   if (!existsSync(join(root, DB_PACKAGE))) return [];
   const current = await schemaHash(root);
   const records = await recordedHashes(root);
   const latest = records.at(-1);
   if (latest === undefined) {
+    // Zero declared against zero recorded is AGREEMENT, not drift. The weaker condition this used
+    // to test — "a packages/db directory exists" — held `x new --no-example` permanently red behind
+    // `x db gen "initial"`, which has an empty diff there, writes no `.hash`, and exits ok: a fix
+    // that succeeds and changes nothing. Drift resumes the moment the author declares an entity,
+    // and by then the fix genuinely writes one.
+    //
+    // An empty diff still writes no `.hash` HERE, and must: `reconcileSchemaHash` needs a migration
+    // id to record against and there is no migration at all in this branch. With an entity declared
+    // the diff is never empty — a registry against zero migrations is `create table` for all of
+    // it — so this branch's fix stays the real generation it always was.
+    if ((await declaredEntities()) === 0) return [];
     return [
       {
         code: 'X_DB_DRIFT',
@@ -73,7 +141,7 @@ export async function checkDrift(root: string): Promise<readonly Finding[]> {
       },
     ];
   }
-  if (records.some((record) => record.hash === current)) return [];
+  if (isRecorded(records, current)) return [];
   return [
     {
       code: 'X_DB_DRIFT',