@ultimat3/cli 1.2.0 → 3.0.0

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 { builtinImageDriver, parseImageQuery } from '@ultimat3/seo';
+import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
+import { builtinImageDriver, DEFAULT_WIDTHS, 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,59 @@ 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' };
+
+/**
+ * Whether a variant is one the framework itself can MINT, and therefore one worth storing.
+ *
+ * The cache key is built entirely from caller-supplied query values, and a signed-in reader
+ * holding `storage:read` may ask for any of them on their own objects — so `?w=1`, `?w=2`, … each
+ * wrote a new object to the app's only disk. `@ultimat3/seo`'s `MAX_IMAGE_WIDTH` (8192) bounds the
+ * blast radius and does not close it: 8192 stored objects per source, per format, is amplification
+ * a tenant drives with a `for` loop.
+ *
+ * The set is `DEFAULT_WIDTHS` **plus the source's intrinsic width**, which is exactly what
+ * `usableWidths` puts in a `srcset` — clamping to the constant alone would refuse the widest entry
+ * of every image whose intrinsic width is not one of the eight, a URL the framework mints itself.
+ * Anything outside it is still SERVED: this decides what is written, not what is answered, so no
+ * caller gains a new 4xx and the disk stops growing on a stranger's key.
+ */
+const isMintableWidth = (width: number | undefined, intrinsic: number): boolean =>
+  width === undefined || width === intrinsic || DEFAULT_WIDTHS.includes(width);
+
+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 +111,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,33 +120,57 @@ 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({
+  const intrinsic = probeImage(source.bytes).width;
+  // 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.
-    width: query.width ?? probeImage(source.bytes).width,
+    width: query.width ?? intrinsic,
     ...(query.format === undefined ? {} : { format: query.format }),
     ...(query.quality === undefined ? {} : { quality: query.quality }),
   });
-  if (cached !== undefined) {
+  if (cached !== undefined && isMintableWidth(query.width, intrinsic)) {
     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 +215,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 +235,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

package/src/dev-n-plus-one.ts

@@ -0,0 +1,191 @@
+// The N+1 ledger: one count per statement shape per request, and a verdict once a shape crosses
+// the threshold. Counting state hangs off the request's own `Ctx` in a `WeakMap`, so it is
+// collected with the request and never swept. Installed by `x dev` and by nothing else — a
+// production process pays the one `undefined` branch `@ultimat3/db`'s seam already costs (axiom 6).
+// It counts and it warns once; what a verdict *means* — which code, which `fix:` — is
+// `statement-loop.ts`'s, so all four surfaces read one answer.
+
+import type { Ctx } from '@ultimat3/core';
+import { assert, tryUseContext } from '@ultimat3/core';
+import type { StatementAttribution, StatementEvent, StatementObserver } from '@ultimat3/db';
+import { statementFingerprint, statementKind } from '@ultimat3/db';
+import { N_PLUS_ONE_THRESHOLD } from '@ultimat3/entity';
+import { loopFacts, warnLoop } from './statement-loop';
+
+/** Verdicts retained. A dev diagnostic shows the recent loops; it does not page through history. */
+const DEFAULT_LIMIT = 50;
+
+/** One statement shape, repeated inside one request past the threshold. */
+export interface RepeatedStatement {
+  /** What was repeated: `members.findById` when attributed, else the statement's own text. */
+  readonly fingerprint: string;
+  /** Which loop this is, and therefore which fix a report can name. */
+  readonly kind: 'read' | 'write';
+  /** The entity and operation that compiled it, absent for hand-written SQL and queue traffic. */
+  readonly attribution?: StatementAttribution | undefined;
+  /** One of the statements, verbatim — the SQL a report shows under the fingerprint. */
+  readonly sample: string;
+  /** Statements of this shape the request has issued so far. Never below the threshold. */
+  readonly count: number;
+  /** The request the loop happened in; a report and its log line name the same one. */
+  readonly requestId: string;
+  readonly traceId: string;
+}
+
+export interface StatementLedger {
+  /** Hand this to `setStatementObserver()`. */
+  readonly observer: StatementObserver;
+  /** Shapes that crossed the threshold, newest first. */
+  repeats(): readonly RepeatedStatement[];
+  /**
+   * The same verdicts, for one request. What the browser overlay shows next to an error: a page
+   * that looped names its loop on the page, not only in a terminal the author is not looking at.
+   */
+  repeatsFor(ctx: Ctx): readonly RepeatedStatement[];
+  reset(): void;
+}
+
+export interface StatementLedgerOptions {
+  /**
+   * Statements of one shape in one request that trip a verdict. Defaults to
+   * `N_PLUS_ONE_THRESHOLD` — `@ultimat3/entity`'s, so this ledger and the strict test fixture
+   * cannot disagree about how many of one shape is a loop.
+   */
+  readonly threshold?: number;
+  /** Verdicts retained before the oldest is dropped. Default `50`. */
+  readonly limit?: number;
+}
+
+/** The live count behind a `RepeatedStatement`: reported once, then still counting. */
+interface RepeatGroup {
+  readonly fingerprint: string;
+  readonly kind: 'read' | 'write';
+  readonly attribution: StatementAttribution | undefined;
+  readonly sample: string;
+  readonly requestId: string;
+  readonly traceId: string;
+  count: number;
+  /** Whether this shape is already a verdict. The flag, not the count, so a `threshold` of 1 works. */
+  promoted: boolean;
+}
+
+/** The verdict a surface reads, without the bookkeeping the group keeps for the ledger itself. */
+const snapshot = (group: RepeatGroup): RepeatedStatement => ({
+  fingerprint: group.fingerprint,
+  kind: group.kind,
+  attribution: group.attribution,
+  sample: group.sample,
+  count: group.count,
+  requestId: group.requestId,
+  traceId: group.traceId,
+});
+
+/**
+ * Count statement shapes per request and report the ones that repeat past `threshold`.
+ *
+ * Three rules, each load-bearing. **Per request, keyed by the context object** — the map dies with
+ * the `Ctx` that owns it, so a dev server up for a week accumulates nothing and no sweep has to
+ * decide when a request ended. A statement issued outside a request (a migration, a boot probe, a
+ * script) is not counted at all: "five of one shape" only means something inside one unit of work.
+ * A `withChildContext` scope is its own key and therefore its own tally, which is the price of
+ * keying on identity rather than on `requestId` and holding the counts forever.
+ *
+ * **An expected statement is not counted** — `expectedQueryLoop` suppresses a verdict, and this
+ * ledger *is* the verdict. The statement is still sent, still observed and still a span, so the
+ * timeline keeps showing the loop while the thing that warns is told the author already answered.
+ *
+ * **A shape is promoted exactly once**, on the statement that crosses the threshold, and the group
+ * behind it keeps counting — so a loop of fifty is one verdict reading `count: 50`, not
+ * forty-six verdicts. The report list is bounded and drops its oldest entry.
+ *
+ * Promotion is also the moment the log line goes out, and it is **one line per request per code**:
+ * a request that loops three different shapes of read has three verdicts and one `X_N_PLUS_ONE_QUERY`
+ * warning, because a log is read to learn that this request looped and the three shapes are what
+ * `x dev`'s findings, `/_x` and the overlay are for. The line names the count as it stood when the
+ * threshold was crossed; every other surface reads the count as it stands when asked.
+ */
+export function createStatementLedger(options: StatementLedgerOptions = {}): StatementLedger {
+  const threshold = options.threshold ?? N_PLUS_ONE_THRESHOLD;
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  assert(
+    Number.isInteger(threshold) && threshold >= 1,
+    `createStatementLedger() was given a threshold of ${threshold}, which no statement count can reach`,
+    'pass a whole number of statements: createStatementLedger({ threshold: 5 })',
+  );
+  assert(
+    Number.isInteger(limit) && limit >= 1,
+    `createStatementLedger() was given a limit of ${limit}, so no verdict could be kept`,
+    'pass how many verdicts to retain: createStatementLedger({ limit: 50 })',
+  );
+  const byRequest = new WeakMap<Ctx, Map<string, RepeatGroup>>();
+  // Which codes this request has already warned about. Its own map rather than a field on the
+  // groups: the rule is one line per *code*, and the groups are per shape — three shapes of read
+  // in one request share one warning and each keeps its own verdict.
+  const warned = new WeakMap<Ctx, Set<string>>();
+  const reported: RepeatGroup[] = [];
+
+  const warnOnce = (ctx: Ctx, group: RepeatGroup): void => {
+    const facts = loopFacts(snapshot(group));
+    let codes = warned.get(ctx);
+    if (codes === undefined) {
+      codes = new Set();
+      warned.set(ctx, codes);
+    }
+    if (codes.has(facts.code)) return;
+    codes.add(facts.code);
+    warnLoop(facts);
+  };
+
+  const onStatement = (event: StatementEvent): void => {
+    if (event.expected !== undefined) return;
+    const ctx = tryUseContext();
+    if (ctx === undefined) return;
+    let groups = byRequest.get(ctx);
+    if (groups === undefined) {
+      groups = new Map();
+      byRequest.set(ctx, groups);
+    }
+    const fingerprint = statementFingerprint(event);
+    let group = groups.get(fingerprint);
+    if (group === undefined) {
+      group = {
+        fingerprint,
+        kind: statementKind(event.text),
+        attribution: event.attribution,
+        sample: event.text,
+        requestId: ctx.requestId,
+        traceId: ctx.traceId,
+        count: 0,
+        promoted: false,
+      };
+      groups.set(fingerprint, group);
+    }
+    // A statement that threw is still a statement: fifty identical timeouts are still a loop, and
+    // one that reports them as four is a loop nobody is told about.
+    group.count += 1;
+    if (group.promoted || group.count < threshold) return;
+    group.promoted = true;
+    reported.push(group);
+    if (reported.length > limit) reported.shift();
+    warnOnce(ctx, group);
+  };
+
+  return {
+    observer: { onStatement },
+    repeats(): readonly RepeatedStatement[] {
+      // Snapshotted, because the groups behind these are still counting — and newest first,
+      // matching the trace recorder: the loop that just happened is the one being looked at.
+      return reported.map(snapshot).reverse();
+    },
+    repeatsFor(ctx: Ctx): readonly RepeatedStatement[] {
+      // Read off this request's own tally rather than filtered out of `reported`, so a verdict the
+      // bound already dropped is still shown on the page it happened on.
+      const groups = byRequest.get(ctx);
+      if (groups === undefined) return [];
+      return [...groups.values()].filter((group) => group.promoted).map(snapshot);
+    },
+    reset(): void {
+      reported.length = 0;
+    },
+  };
+}