@ultimat3/cli 1.1.0 → 2.0.0

package/src/db-finding.ts

@@ -0,0 +1,28 @@
+// One rule for turning a thrown value into a `Finding` on the `x db` path, shared by every
+// subcommand: a framework error reaches the caller verbatim, and anything else is named by the
+// step that failed. Its own module because `cmd-db.ts` and `cmd-db-branch.ts` both need it and
+// neither may import the other.
+
+import { renderThrowable } from '@ultimat3/core';
+import type { Finding } from './output';
+import { findingFrom, isUltimateErrorShape } from './output';
+
+/**
+ * The engine names its own failures — `X_MIGRATION_CONFLICT` carries the ledger row that disagrees,
+ * `X_MIGRATION_IRREVERSIBLE` carries the exact `--allow-destructive` line to rerun, and
+ * `X_BRANCH_EXISTS` carries the `x db branch drop` that clears it — so those reach the caller
+ * verbatim. `X_DB_GEN_FAILED` / `X_DB_MIGRATE_FAILED` / `X_DB_BRANCH_FAILED` are what is left: the
+ * step failed for a reason no framework error claimed, and the raw message is all there is.
+ */
+export const stepFinding = (error: unknown, code: string): Finding =>
+  isUltimateErrorShape(error)
+    ? findingFrom(error)
+    : {
+        code,
+        // The engine may throw a non-Error, and an Error whose `message` is a getter: core's
+        // `renderThrowable` reads both without trusting either, so the refusal cannot be lost to
+        // a TypeError raised while reporting it.
+        cause: renderThrowable(error),
+        fix: 'x doctor --json',
+        docs: `https://ultimate.dev/errors/${code}`,
+      };

package/src/db-generate.ts

@@ -0,0 +1,112 @@
+// `x db gen`, on the framework's own engine. The app's registered entities diffed against what the
+// migration files already declare, written as one reversible `.sql` plus the two sidecars the gate
+// reads back — the snapshot the next generation diffs against, and the schema hash `drift` checks.
+
+// `node:path` — Bun ships no path joiner of its own, and these paths are built, not opened.
+import { join } from 'node:path';
+import type { GeneratedMigration } from '@ultimat3/db';
+import {
+  DESTRUCTIVE_MARKER,
+  declaredSchema,
+  generateMigration,
+  migrationSnapshotMissing,
+  snapshotJson,
+} from '@ultimat3/db';
+import { describeEntities } from '@ultimat3/entity';
+import { loadApp } from './app-load';
+import { writeSchemaHash } from './drift';
+import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
+import type { Finding } from './output';
+
+export interface GenerateMigrationOptions {
+  readonly name: string;
+  /** `x db gen "…" --allow-destructive`. A DROP whose `down` cannot restore the rows. */
+  readonly allowDestructive?: boolean | undefined;
+}
+
+export interface GeneratedFiles {
+  /** Absent when the entities and the migrations already agree — nothing was written. */
+  readonly migration?: GeneratedMigration | undefined;
+  /** App-root-relative paths written, in write order. Empty when there was nothing to write. */
+  readonly files: readonly string[];
+  readonly schemaHash?: string | undefined;
+  /** Modules that would not load. Non-empty means nothing was generated. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * The header every generated migration carries. It names the id rather than interpolating the
+ * caller's own message: a `name` is free text from argv, and a newline in it would end the comment
+ * and turn prose into SQL.
+ *
+ * A destructive `up` carries the marker `x verify` demands, written here rather than hand-added
+ * later: the marker is part of the SQL the checksum covers, so a migration that earns it after it
+ * has been applied is an edited migration and `X_MIGRATION_CONFLICT` — correctly — says so.
+ */
+export function migrationSql(migration: GeneratedMigration): string {
+  return [
+    `-- ${migration.id}`,
+    "-- GENERATED by `x db gen` from the app's entities — do not edit.",
+    '-- Editing an applied migration changes its checksum: X_MIGRATION_CONFLICT on the next apply.',
+    ...(migration.destructive ? [DESTRUCTIVE_MARKER] : []),
+    '',
+    migration.up,
+    '',
+    '-- down',
+    migration.down,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Generation reads source and writes files; it never opens a database. The previous migration's
+ * snapshot is what it diffs against (`declaredSchema`), so `x db gen` answers the same in CI, on a
+ * laptop with no Postgres running, and against a database three migrations behind.
+ *
+ * An app that would not load generates nothing. `describeEntities()` is the registry a failed
+ * import leaves short, and a diff against a short registry is a migration that drops the tables
+ * whose module happened to throw — the one destructive edit no `--allow-destructive` was asked for.
+ */
+export async function generateAppMigration(
+  root: string,
+  options: GenerateMigrationOptions,
+): Promise<GeneratedFiles> {
+  const app = await loadApp(root);
+  if (app.findings.length > 0) return { files: [], findings: app.findings };
+
+  const migrations = await readMigrations(root);
+  const current = declaredSchema(migrations);
+  // Refused, never defaulted to the empty schema: with nothing to diff against, every table the
+  // database already holds looks new and the generated `up` is `create table` for all of them.
+  if (current === undefined) {
+    const newest = migrations[migrations.length - 1];
+    const id = newest?.id ?? '';
+    throw migrationSnapshotMissing(id, join(MIGRATIONS_DIR, snapshotFileName(id)));
+  }
+
+  const migration = generateMigration({
+    entities: describeEntities(),
+    current,
+    name: options.name,
+    ...(options.allowDestructive === true ? { allowDestructive: true } : {}),
+  });
+  // An empty diff writes nothing. A migration with no statement still takes a ledger row, a
+  // checksum and a place in the apply order — a permanent record that nothing changed.
+  if (migration.up.trim().length === 0) return { files: [], findings: [] };
+
+  const dir = join(root, MIGRATIONS_DIR);
+  const sql = `${migration.id}.sql`;
+  const snapshot = snapshotFileName(migration.id);
+  await Bun.write(join(dir, sql), migrationSql(migration));
+  // `snapshotJson`, never `JSON.stringify`: the sidecar is the one migration artefact a scaffolded
+  // app's `biome check .` reads, and its bytes carry their own trailing newline.
+  await Bun.write(join(dir, snapshot), snapshotJson(migration.snapshot));
+  const schemaHash = await writeSchemaHash(root, migration.id);
+
+  return {
+    migration,
+    schemaHash,
+    files: [sql, snapshot, hashFileName(migration.id)].map((file) => `${MIGRATIONS_DIR}/${file}`),
+    findings: [],
+  };
+}

package/src/db-snapshot.ts

@@ -0,0 +1,24 @@
+// `x db gen`'s own precondition, asked as a diagnostic rather than met as a throw: a newest
+// migration with no `.snapshot.json` leaves the next generation nothing to diff against, so it
+// refuses before writing anything. `@ultimat3/db` owns both the condition (`declaredSchema`) and
+// the wording, so this check and that refusal cannot disagree about one directory.
+
+import { declaredSchema, migrationSnapshotMissing } from '@ultimat3/db';
+import { MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
+import { type Finding, findingFrom } from './output';
+
+/**
+ * Empty result = the next `x db gen` has something to start from. An app with no migrations at all
+ * reports nothing: `declaredSchema([])` is the empty schema, which is a real answer and the state a
+ * freshly scaffolded app is in before its first generation.
+ *
+ * One finding, never one per file. Only the NEWEST snapshot is what a diff starts from, so an older
+ * migration missing one is a fact about history and not something the author can act on.
+ */
+export async function checkMigrationSnapshots(root: string): Promise<readonly Finding[]> {
+  const migrations = await readMigrations(root);
+  if (declaredSchema(migrations) !== undefined) return [];
+  const id = migrations[migrations.length - 1]?.id ?? '';
+  const file = `${MIGRATIONS_DIR}/${snapshotFileName(id)}`;
+  return [{ ...findingFrom(migrationSnapshotMissing(id, file)), at: file }];
+}

package/src/dev-assets.ts

@@ -1,20 +1,28 @@
 // Projecting the framework's one image pipeline onto the routes `x dev` serves. Three packages
 // declare what an image is — `@ultimat3/seo` a variant URL, `@ultimat3/storage` a variant key,
 // `@ultimat3/pwa` the icons a web manifest promises — and `@ultimat3/core`'s pipeline owns every
-// pixel, so this file picks the two base paths they hang off and decides nothing else.
+// pixel, so this file picks the two base paths they hang off and decides nothing else. The one
+// thing it does NOT decide is who may read a stored object: `/media` borrows that whole answer
+// from `dev-storage.ts`, because the same bytes are reachable through both.
 
 // `join` is `node:`-only by necessity: Bun exposes no path-join primitive, and `ICON_SOURCE` is
 // app-root-relative, so resolving it against the root is string work no `Bun.file` overload does.
 import { join } from 'node:path';
 import { probeImage } from '@ultimat3/core';
-import type { Route, UltimateRequest } from '@ultimat3/http';
+import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import type { IconPlan } from '@ultimat3/pwa';
 import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
-import type { ImageQuery } from '@ultimat3/seo';
+import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, parseImageQuery } from '@ultimat3/seo';
 import type { ImageFormat, ImageTransform, Storage } from '@ultimat3/storage';
-import { IMAGE_FORMATS, variantKey } from '@ultimat3/storage';
+import { IMAGE_FORMATS, isTenantScoped, variantKey } from '@ultimat3/storage';
+import {
+  AUTHORIZED_OBJECT_CACHE,
+  assertReadableKey,
+  authorizeStorageRead,
+  STORAGE_READ_PERMISSION,
+} from './dev-storage';
 
 /**
  * The one source image every generated icon derives from. `x new` scaffolds it, `x doctor` checks
@@ -26,22 +34,41 @@ export const ICON_SOURCE = 'apps/web/site/icon.png';
 /** Where `planIcons` writes, and therefore the paths the generated web manifest names. */
 export const ICON_BASE_PATH = '/icons';
 
-/** Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it. */
+/**
+ * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.
+ * Guarded exactly as `/_storage` is — an object reachable through two URLs must not be reachable
+ * on two different terms — so a `src` under this path needs a signed-in reader holding
+ * `storage:read`. A genuinely public image belongs in `apps/web/site/`, which is served as a
+ * static asset and never touches a disk holding another tenant's uploads.
+ */
 export const MEDIA_BASE_PATH = '/media';
 
 /**
- * Variants are content-addressed by `variantKey`, so a URL that answers once answers forever with
- * the same bytes — the immutable hint is a fact about the key, not an optimism about the source.
+ * A generated icon and a content-addressed variant answer forever with the same bytes, so the
+ * immutable hint is a fact about the key. It is NOT a fact about this route — see `mediaCache`.
  */
-const imageResponse = (bytes: Uint8Array, contentType: string): Response =>
+const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
+
+const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
     // `SharedArrayBuffer`, which `Response` does not accept, and copying is what makes that true
     // by construction rather than by a cast that would only silence it.
     new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
-    { mode: 'immutable' },
+    cache,
   );
 
+/**
+ * Immutable is a claim about the KEY, and a tenant-scoped key names one org's private object: a
+ * CDN or shared proxy that stores it under a public URL for a year hands it to every other tenant,
+ * which is the cross-tenant read one hop removed. `/media` declared `public, max-age=31536000,
+ * immutable` for exactly those keys until this branch. Applied in the handler rather than declared
+ * in `meta.cache` because the posture is decided by the key, which no route declaration can see —
+ * the pipeline's `cache-headers` stage only fills a `cache-control` a handler did not set.
+ */
+const mediaCache = (key: string): CacheHint =>
+  isTenantScoped(key) ? AUTHORIZED_OBJECT_CACHE : IMMUTABLE_IMAGE;
+
 const isImageFormat = (value: string): value is ImageFormat =>
   (IMAGE_FORMATS as readonly string[]).includes(value);
 
@@ -66,6 +93,7 @@ async function transformedVariant(
   storage: Storage,
   key: string,
   query: ImageQuery,
+  images: ImageTransformDriver | undefined,
 ): Promise<Response> {
   const disk = storage.disk();
   // A format storage cannot name has no variant key, so it cannot be cached. The driver refuses
@@ -74,13 +102,23 @@ async function transformedVariant(
     query.format !== undefined && isImageFormat(query.format) ? query.format : undefined;
   const cacheable = query.format === undefined || format !== undefined;
   const cached = cacheable ? variantKey(key, storageTransform(query, format)) : undefined;
+  // The SOURCE key decides the posture, not the variant's: `variantKey` keeps the source's prefix,
+  // so a variant of `org/<id>/…` is one org's object too, and reading the hint off the derived key
+  // would be a second answer to a question the source already settled.
+  const cache = mediaCache(key);
   if (cached !== undefined && (await disk.exists(cached))) {
     const hit = await disk.get(cached);
-    return imageResponse(hit.bytes, hit.object.contentType);
+    return imageResponse(hit.bytes, hit.object.contentType, cache);
   }
 
   const source = await disk.get(key);
-  const variant = await builtinImageDriver({ read: async () => source.bytes }).transform({
+  // The seam is WHICH driver transforms, not who resolves the bytes: `TransformRequest.width` is
+  // required, and a request with no `?w=` gets its width from the source's own header — so the
+  // read happens either way and a supplied driver is handed the same resolved request the builtin
+  // one gets. Constructed inline before this, with no seam at all, so a deployment that routes
+  // transforms through a CDN had to fork the route to do it.
+  const driver = images ?? builtinImageDriver({ read: async () => source.bytes });
+  const variant = await driver.transform({
     src: key,
     // A header read, not a decode: `?f=webp` alone still needs a width, and the source's own is
     // the only one that does not resize an image the caller never asked to resize.
@@ -91,16 +129,29 @@ async function transformedVariant(
   if (cached !== undefined) {
     await disk.put(cached, variant.bytes, { contentType: variant.contentType });
   }
-  return imageResponse(variant.bytes, variant.contentType);
+  return imageResponse(variant.bytes, variant.contentType, cache);
 }
 
-async function mediaResponse(request: UltimateRequest, storage: Storage): Promise<Response> {
-  const key = request.params['key'] ?? '';
+/**
+ * Authorized before a key is parsed and before a disk is touched — the same two calls, in the same
+ * order, that `/_storage` makes. This route made NEITHER: it was `auth: 'public'` with no policy
+ * and handed the raw client-supplied key to `disk().get`, so every object on the app's only disk
+ * was one unauthenticated URL away, and `?w=` made it an unauthenticated `put` besides.
+ */
+async function mediaResponse(
+  request: UltimateRequest,
+  ctx: RequestContext,
+  storage: Storage,
+  images: ImageTransformDriver | undefined,
+): Promise<Response> {
+  const requested = request.params['key'] ?? '';
+  authorizeStorageRead({ disk: storage.defaultDisk, key: requested }, ctx);
+  const key = assertReadableKey(requested, ctx.actor);
   const query = parseImageQuery(request.url.searchParams);
-  if (query !== null) return transformedVariant(storage, key, query);
+  if (query !== null) return transformedVariant(storage, key, query, images);
   // No transform asked for: the object itself, still under the storage key's own safety checks.
   const read = await storage.disk().get(key);
-  return imageResponse(read.bytes, read.object.contentType);
+  return imageResponse(read.bytes, read.object.contentType, mediaCache(key));
 }
 
 /**
@@ -145,6 +196,8 @@ export interface AssetRoutesOptions {
   /** App root. The source icon is resolved against it; storage keys never are. */
   readonly root: string;
   readonly storage: Storage;
+  /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG pipeline. */
+  readonly images?: ImageTransformDriver;
 }
 
 /**
@@ -163,14 +216,27 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
     path: entry.outputPath,
     meta: { name: `assets.icon.${entry.spec.filename}`, auth: 'public', tags: ['assets'] },
     handler: async (request: UltimateRequest): Promise<Response> =>
-      imageResponse(await render(plan, request.pathname), 'image/png'),
+      imageResponse(await render(plan, request.pathname), 'image/png', IMMUTABLE_IMAGE),
   }));
+  // The icons above are genuinely public — they are rendered from a file committed in the app, and
+  // an install prompt fetches them before anyone has signed in. `/media` is the opposite: it serves
+  // whatever is on the app's only disk, which is every tenant's uploads, so it takes `/_storage`'s
+  // declaration verbatim. `enforcedBy: 'handler'` for the reason that route gives — the `authz`
+  // stage resolves a policy from `@ultimat3/render`'s page table, which this route is not in.
+  // `cache` declares the conservative posture; `mediaCache` narrows or widens it per key.
   routes.push({
     method: 'GET',
     path: `${MEDIA_BASE_PATH}/*key`,
-    meta: { name: 'assets.media', auth: 'public', tags: ['assets'] },
-    handler: async (request: UltimateRequest): Promise<Response> =>
-      mediaResponse(request, options.storage),
+    meta: {
+      name: 'assets.media',
+      auth: 'required',
+      policy: STORAGE_READ_PERMISSION,
+      enforcedBy: 'handler',
+      cache: AUTHORIZED_OBJECT_CACHE,
+      tags: ['assets'],
+    },
+    handler: async (request: UltimateRequest, ctx: RequestContext): Promise<Response> =>
+      mediaResponse(request, ctx, options.storage, options.images),
   });
 
   return routes;

package/src/dev-cache.ts

@@ -0,0 +1,122 @@
+// Which cache tiers this process reads through, and the hop that tells the other replicas what it
+// just dropped. `createMemoTier`, `createLruTier` and `createRedisTier` were built, exported and
+// tested with ZERO callers — `dev-runtime.ts` registered the CDN tier and nothing else — so every
+// cached read was recomputed on every replica on every request, and `registerInvalidationBroadcast`
+// had no one to register it.
+
+import type { CacheTier, PurgeDriver } from '@ultimat3/cache';
+import {
+  createCdnTier,
+  createLruTier,
+  createMemoTier,
+  createRedisTier,
+  isNoopPurgeDriver,
+  receiveInvalidationBroadcast,
+  registerInvalidationBroadcast,
+  registerTier,
+  resetTiers,
+} from '@ultimat3/cache';
+import { logger } from '@ultimat3/core';
+import type { Transport, TransportSubscription } from '@ultimat3/realtime';
+import type { Env } from './dev-services';
+
+/**
+ * The subject every replica of every app publishes tag invalidations on. One subject and not one
+ * per app: a transport is already namespaced by the bus an operator pointed the deployment at,
+ * and a second namespace here would be a knob whose only correct value is the default.
+ */
+export const CACHE_INVALIDATE_SUBJECT = 'x.cache.invalidate';
+
+export interface CacheTiersOptions {
+  readonly env: Env;
+  /** Already resolved by the boot — the CDN tier is registered only for a real edge. */
+  readonly purge: PurgeDriver;
+  readonly transport: Transport;
+}
+
+/**
+ * The shared tier, or nothing. `REDIS_URL` is the same "an unset variable means the embedded
+ * default" law the db, events, storage, mail and CDN bindings already follow — and it is the
+ * variable Bun's own `Bun.redis` reads, so a tier selected here and a client built there cannot
+ * point at two servers.
+ */
+function sharedTier(env: Env): CacheTier | undefined {
+  const url = env['REDIS_URL']?.trim();
+  return url === undefined || url === '' ? undefined : createRedisTier();
+}
+
+/**
+ * Register the tiers, wire both halves of cross-instance invalidation, and return the release.
+ *
+ * The outbound half publishes the wire tags this process just dropped; the inbound half applies
+ * another instance's. A message this process published is delivered back to it on every real bus
+ * and is applied again — deliberately, with no node-id filter: dropping an already-dropped key is
+ * idempotent and free, while a dedup table is state that can be wrong. Re-emit is impossible by
+ * construction, not by a flag: `receiveInvalidationBroadcast` is the only entry point that
+ * suppresses it, and `emit` is not a public parameter.
+ */
+export function startCacheTiers(options: CacheTiersOptions): () => Promise<void> {
+  // Request-scoped memo first, then the process-local LRU: both are free of external state, so
+  // they are the "embedded default" that needs no variable to switch on. Registration order does
+  // not decide read order — `sortTiers` does — but it is written in read order anyway.
+  registerTier(createMemoTier());
+  registerTier(createLruTier());
+  const shared = sharedTier(options.env);
+  if (shared !== undefined) registerTier(shared);
+  // Nothing installs a read tier here, and that is the point. `@ultimat3/query` used to own a
+  // private `ReadCache` this boot had to hand-wire over one of the objects above, because
+  // `invalidateTags` fans out to registered tiers and to nothing else — so a read cache holding
+  // entries of its own was a `cache:` query an action's `invalidates` could never bust. The seam
+  // is gone: a `cache:` read fills the ladder registered here, so there is one registry and one
+  // fan-out and no wiring to get wrong.
+  // Registered only when a credential named a real edge. A noop tier would put a `cdn` line in
+  // every invalidation report claiming keys an edge that does not exist had accepted — and the
+  // `/_x` cache panel renders those reports, so the lie would be the thing an agent reads.
+  if (!isNoopPurgeDriver(options.purge)) {
+    registerTier(createCdnTier({ purge: options.purge }));
+  }
+
+  registerInvalidationBroadcast(async (wireTags) => {
+    await options.transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(wireTags));
+  });
+  let subscription: TransportSubscription | undefined;
+  // Not awaited: the boot must not block on a subscribe, and a bus that refuses one is a process
+  // that misses peer invalidations, never a process that fails to start.
+  void options.transport
+    .subscribe(CACHE_INVALIDATE_SUBJECT, (payload: string) => {
+      void applyBroadcast(payload);
+    })
+    .then((handle) => {
+      subscription = handle;
+    })
+    .catch((error: unknown) => {
+      logger.warn('cache.broadcast.subscribe-failed', { error: messageOf(error) });
+    });
+
+  // `resetTiers()` drops the registry AND the broadcast in one call: this boot is the only thing
+  // that registers either, and a tier left behind would purge for a process that has stopped.
+  return async () => {
+    subscription?.unsubscribe();
+    subscription = undefined;
+    resetTiers();
+  };
+}
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : 'unknown error';
+
+/**
+ * A peer's wire tags, applied here. Never throws: a malformed frame or an undeclared tag must not
+ * kill the subscriber loop, because that would silently end cross-instance invalidation for the
+ * whole process — the exact failure this hop exists to prevent, arriving quietly.
+ */
+async function applyBroadcast(payload: string): Promise<void> {
+  try {
+    const parsed: unknown = JSON.parse(payload);
+    if (!Array.isArray(parsed)) return;
+    const wire = parsed.filter((value): value is string => typeof value === 'string');
+    if (wire.length > 0) await receiveInvalidationBroadcast(wire);
+  } catch (error) {
+    logger.warn('cache.broadcast.apply-failed', { error: messageOf(error) });
+  }
+}

package/src/dev-dashboard.ts

@@ -12,6 +12,7 @@ import type {
   PolicyFact,
   RequestTrace,
   SqlResult,
+  StatementLoopFact,
 } from '@ultimat3/admin/dev';
 import { DEV_BASE_PATH, DEV_PANELS, defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
 import { recentInvalidations } from '@ultimat3/cache';
@@ -23,11 +24,13 @@ import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
 import { checkAppBoundaries } from './app-boundaries';
 import { appManifest, readAppManifest } from './app-manifest';
+import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
 import type { RunningServices } from './dev-runtime';
 import type { DevServices } from './dev-services';
 import type { TraceRecorder } from './dev-traces';
 import type { Finding } from './output';
+import { loopFacts } from './statement-loop';
 
 export interface DevStatus {
   readonly url: string;
@@ -46,6 +49,8 @@ export interface DevDashboardInput {
   readonly env?: string | undefined;
   /** The spans this process recorded. Absent when `x dev` did not install the exporter. */
   readonly traces?: TraceRecorder | undefined;
+  /** The statement shapes this process counted. Absent when `x dev` did not install the observer. */
+  readonly statements?: StatementLedger | undefined;
 }
 
 /**
@@ -127,6 +132,7 @@ const invalidationFacts = (): readonly InvalidationFact[] =>
  */
 export function devSources(input: DevDashboardInput): DevSources {
   const traces = input.traces;
+  const statements = input.statements;
   // Only the memory driver retains what it accepted. Once a credential selects a real transport
   // the messages are at the provider, so the hook is omitted rather than answered with `[]` —
   // an empty outbox claims nobody was mailed, which is a different and unearned answer.
@@ -148,6 +154,15 @@ export function devSources(input: DevDashboardInput): DevSources {
       ...(traces === undefined
         ? {}
         : { traces: (): Promise<readonly RequestTrace[]> => Promise.resolve(traces.traces()) }),
+      // Same rule, same reason: the timeline panel answers `null` for a host that counted nothing,
+      // and an empty list here would instead claim every request on screen was clean. The verdicts
+      // are read at request time, so a loop that just happened is on the panel without a remount.
+      ...(statements === undefined
+        ? {}
+        : {
+            statementLoops: (): Promise<readonly StatementLoopFact[]> =>
+              Promise.resolve(statements.repeats().map(loopFacts)),
+          }),
     },
   });
 }
@@ -163,8 +178,8 @@ interface ServicesPanelData extends DevStatus {
  */
 const servicesPanel = (input: DevDashboardInput): DevPanel<ServicesPanelData> => ({
   key: 'services',
-  titleKey: 'dev.panel.services',
-  question: 'which services is this process talking to, and did anything fail to load?',
+  titleKey: 'dev.panel.services.title',
+  questionKey: 'dev.panel.services.question',
   data(): Promise<ServicesPanelData> {
     const status = input.status();
     return Promise.resolve({ ...status, stateDir: status.services.stateDir });
@@ -177,8 +192,8 @@ interface BoundariesPanelData {
 
 const boundariesPanel = (input: DevDashboardInput): DevPanel<BoundariesPanelData> => ({
   key: 'boundaries',
-  titleKey: 'dev.panel.boundaries',
-  question: 'does any file import across a boundary the build will reject?',
+  titleKey: 'dev.panel.boundaries.title',
+  questionKey: 'dev.panel.boundaries.question',
   async data(): Promise<BoundariesPanelData> {
     return { findings: await checkAppBoundaries(input.root) };
   },

package/src/dev-hooks.ts

@@ -4,7 +4,7 @@
 
 import { actorOf } from '@ultimat3/action';
 import type { AuthzDecision, ServerHooks } from '@ultimat3/http';
-import { asCtx } from '@ultimat3/http';
+import { asCtx, configuredAuthenticator } from '@ultimat3/http';
 import type { KnownPermission, Policy } from '@ultimat3/policy';
 import { can, evaluate } from '@ultimat3/policy';
 import { routeFor } from '@ultimat3/render';
@@ -22,8 +22,33 @@ function policyFor(path: string): Policy<unknown, unknown> | undefined {
   return permission !== undefined && isPermission(permission) ? can(permission) : undefined;
 }
 
-export function devHooks(): ServerHooks {
+/**
+ * Both seams, never one. This returned `authorize` alone, so `hooks.authenticate` — the only
+ * place an actor can come from — had no caller anywhere in the framework: every request under
+ * `x dev` AND under `apps/web/server.ts` (both boot through `startRoles`) was anonymous, and
+ * `auth: 'required'` was unsatisfiable. The app declares the resolver with
+ * `configureAuthenticator()` at import time; this reads it back at server start, which is after
+ * `loadApp` has imported the app's modules.
+ *
+ * Read here rather than captured at module load so a test — and a watch-mode restart — sees the
+ * function the app configured, not the one that was absent when this module first evaluated.
+ */
+export interface DevHookOptions {
+  /**
+   * Dev-only findings this process accumulated for the request being answered — `x dev`'s N+1
+   * ledger, and nothing else today. Passed rather than read from a module-global for the reason
+   * `authorize` is passed a route: a hook that reached for the ledger itself would make every host
+   * that starts a web role — `serve.ts` included — carry a diagnostic only one of them installs.
+   */
+  readonly devNotices?: ServerHooks['devNotices'];
+}
+
+export function devHooks(options: DevHookOptions = {}): ServerHooks {
+  const authenticate = configuredAuthenticator();
+  const devNotices = options.devNotices;
   return {
+    ...(authenticate === undefined ? {} : { authenticate }),
+    ...(devNotices === undefined ? {} : { devNotices }),
     authorize: (route, _request, ctx): AuthzDecision => {
       // An action route never arrives here: it carries `enforcedBy: 'handler'`, so the pipeline
       // never asks. `invoke` is its one evaluation, and the only one holding the row a row-level