@ultimat3/cli 29.4.0 → 30.1.0

package/src/runtime-storage.ts

@@ -9,15 +9,14 @@
 
 import type { Actor } from '@ultimat3/core';
 import { actorOf } from '@ultimat3/core';
-import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
-import {
-  asCtx,
-  byteWindow,
-  contentRangeOf,
-  parseByteRange,
-  RANGE_UNSATISFIABLE,
-  unauthenticated,
+import type {
+  CacheHint,
+  ObjectSource,
+  RequestContext,
+  Route,
+  UltimateRequest,
 } from '@ultimat3/http';
+import { asCtx, objectResponse, unauthenticated } from '@ultimat3/http';
 import type { KnownPermission } from '@ultimat3/policy';
 import {
   can,
@@ -27,7 +26,7 @@ import {
   policyForbidden,
   reasonOf,
 } from '@ultimat3/policy';
-import type { Storage, StorageObject } from '@ultimat3/storage';
+import type { Storage, StorageDriver } from '@ultimat3/storage';
 import {
   assertSafeKey,
   DEFAULT_SIGNED_URL_BASE,
@@ -37,9 +36,10 @@ import {
   keyUnshared,
   objectNotFound,
   orgMismatch,
+  variantRevision,
+  variantSourceOf,
 } from '@ultimat3/storage';
 import { storageUploadRoute } from './runtime-storage-upload';
-import { storedObjectHeaders } from './stored-object-headers';
 
 /**
  * The one capability that gates reading a stored object, on every disk. A permission and not a
@@ -64,9 +64,9 @@ 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.
+ * one tenant's file under a public key for a year. A key is not content-addressed either: an
+ * overwrite changes the bytes under it, which is what the etag answers. `vary` names the two
+ * headers that carry an identity.
  */
 export const AUTHORIZED_OBJECT_CACHE: CacheHint = {
   mode: 'private',
@@ -154,89 +154,49 @@ export function assertReadableKey(
 }
 
 /**
- * What the route serves: the object's description and a STREAM of its bytes, never a buffer. The
- * route used `get()`, which holds the whole object in memory and refuses past the disk's
- * `maxGetBytes` — so a large upload was either a pod's worth of heap or `X_STORAGE_TOO_LARGE`.
+ * A stored variant read by its OWN key answers for its source, or the URL outlives an erasure: a key
+ * naming a revision is served only while the source still holds that revision. Both routes read
+ * through here. An unrevisioned key is an ordinary object, because `logo@2x.png` is a real name.
  */
-export interface ServedObject {
-  readonly object: StorageObject;
-  /** Opened only once the route knows it will send a body: a 304 and a 416 open nothing. */
-  readonly open: () => Promise<ReadableStream<Uint8Array>>;
+export async function assertVariantCurrent(
+  driver: StorageDriver,
+  disk: string,
+  key: string,
+): Promise<void> {
+  const variant = variantSourceOf(key);
+  if (variant === undefined) return;
+  const source = await driver.stat(variant.source);
+  if (source === undefined || variantRevision(source.etag) !== variant.revision) {
+    throw objectNotFound(disk, key);
+  }
 }
 
 /**
  * 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.
+ *
+ * A STREAM of the bytes, never a buffer: `get()` holds the whole object in memory and refuses past
+ * the disk's `maxGetBytes`, so a large upload was a pod's worth of heap or `X_STORAGE_TOO_LARGE`,
+ * and a video's `bytes=0-` probe is the whole object, which only a stream holds. A `Range:` is
+ * `streamRange`, so a seek late in the file costs its window. The content type is the STORED one and the validator the driver's own content hash: inventing a cache key here
+ * would be a second identity for one object.
  */
 export async function readStorageObject(
   storage: Storage,
   input: StorageReadInput,
   actor: Actor,
-): Promise<ServedObject> {
+): Promise<ObjectSource> {
   const key = assertReadableKey(storage, input.disk, input.key, actor);
   if (!storage.diskNames.includes(input.disk)) throw objectNotFound(input.disk, key);
   const driver = storage.disk(input.disk);
+  await assertVariantCurrent(driver, input.disk, key);
   const object = await driver.stat(key);
   if (object === undefined) throw objectNotFound(input.disk, key);
-  return { object, open: () => driver.stream(key) };
-}
-
-/** `*`, 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 async function storageResponse(
-  request: UltimateRequest,
-  served: ServedObject,
-): Promise<Response> {
-  const { object } = served;
-  const etag = `"${object.etag}"`;
-  const headers = new Headers({
-    'content-type': object.contentType,
-    etag,
-    'accept-ranges': 'bytes',
-    // A type a browser would RUN (html, svg, xml) is a download, never a page on this origin.
-    ...storedObjectHeaders(object.contentType),
-  });
-  // Omitted, never invented: a disk whose provider reported no date has none, and a `Last-Modified`
-  // made up for it is a validator a cache would go on to trust.
-  const modified = object.lastModified;
-  if (modified !== undefined) headers.set('last-modified', modified.toUTCString());
-  // 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 = object.size;
-  const range = parseByteRange(request.header('range'), size);
-  if (range === RANGE_UNSATISFIABLE) {
-    headers.set('content-range', `bytes */${size}`);
-    return new Response(null, { status: 416, headers });
-  }
-  // `size` is the stat's: a key's bytes never change under it (an upload mints a new key), so the
-  // length declared here is the length the stream delivers.
-  if (range === undefined) {
-    headers.set('content-length', String(size));
-    return new Response(await served.open(), { headers });
-  }
-  // A disk could serve the window itself (`get(key, { range })`), but `get` buffers and is bounded
-  // by `maxGetBytes`; a video's `bytes=0-` probe is the whole object, which only a stream holds.
-  headers.set('content-range', contentRangeOf(range, size));
-  headers.set('content-length', String(range.end - range.start + 1));
-  return new Response(byteWindow(await served.open(), range), {
-    status: 206,
-    headers,
-  });
+  return {
+    object,
+    open: async (range) =>
+      range === undefined ? driver.stream(key) : driver.streamRange(key, [range.start, range.end]),
+  };
 }
 
 /**
@@ -299,7 +259,7 @@ export function storageRoutes(options: StorageRoutesOptions): readonly Route[] {
           key: request.params['key'] ?? '',
         };
         authorizeStorageRead(input, ctx);
-        return storageResponse(request, await readStorageObject(options.storage, input, ctx.actor));
+        return objectResponse(request, await readStorageObject(options.storage, input, ctx.actor));
       },
     },
     // The upload half: the `PUT` every `grantUpload` URL names (#523). One call mounts both, so

package/src/schema-diff-views.ts

@@ -0,0 +1,54 @@
+// Single responsibility: the views half of `diffDeclaredSchema` — what the entities declare as
+// `entity({ view })` against the views the newest migration's snapshot recorded. A view is
+// recorded as the statements `x db gen` wrote for it, so equal statements are the whole agreement.
+
+import type { ViewDescription } from '@ultimat3/db';
+import type { SchemaDifference } from './schema-diff';
+
+const DECLARED_ONLY = 'is declared by the entities and no migration recorded it';
+const RECORDED_ONLY = 'was recorded by the newest migration and no entity declares it';
+const STATEMENTS_MOVED = 'is declared with a query or index the newest migration did not record';
+
+const kindOf = (view: ViewDescription): string =>
+  view.materialized === true ? 'materialized' : 'a plain view';
+
+function viewDetail(declared: ViewDescription, recorded: ViewDescription): string | undefined {
+  if ((declared.materialized === true) !== (recorded.materialized === true)) {
+    return `is declared ${kindOf(declared)} and was recorded ${kindOf(recorded)}`;
+  }
+  const same =
+    declared.create.length === recorded.create.length &&
+    declared.create.every((statement, at) => statement === recorded.create[at]);
+  return same ? undefined : STATEMENTS_MOVED;
+}
+
+/**
+ * Both directions, by name. Absent `views` is "none recorded": every snapshot written before views
+ * existed, which is agreement with an app that declares none. A changed view is `unmigrated`, as a
+ * changed column is — the declaration is the intent, and `x db gen` rebuilds every view from it.
+ */
+export function diffViews(
+  declared: readonly ViewDescription[] = [],
+  recorded: readonly ViewDescription[] = [],
+): readonly SchemaDifference[] {
+  const out: SchemaDifference[] = [];
+  const byName = new Map(recorded.map((view) => [view.name, view]));
+  for (const view of declared) {
+    const counterpart = byName.get(view.name);
+    const detail = counterpart === undefined ? DECLARED_ONLY : viewDetail(view, counterpart);
+    if (detail === undefined) continue;
+    out.push({ direction: 'unmigrated', part: 'view', table: view.name, name: view.name, detail });
+  }
+  const names = new Set(declared.map((view) => view.name));
+  for (const view of recorded) {
+    if (names.has(view.name)) continue;
+    out.push({
+      direction: 'undeclared',
+      part: 'view',
+      table: view.name,
+      name: view.name,
+      detail: RECORDED_ONLY,
+    });
+  }
+  return out;
+}

package/src/schema-diff.ts

@@ -17,6 +17,7 @@ import type {
   TableDescription,
 } from '@ultimat3/db';
 import { indexMethodOf } from '@ultimat3/db';
+import { diffViews } from './schema-diff-views';
 
 /**
  * Which side holds a declaration the other does not, and they are two different repairs.
@@ -25,8 +26,11 @@ import { indexMethodOf } from '@ultimat3/db';
  */
 export type SchemaDirection = 'unmigrated' | 'undeclared';
 
-/** The part of a table a difference is about. Rendered into the cause verbatim. */
-export type SchemaPart = 'table' | 'column' | 'index' | 'foreign key' | 'check';
+/**
+ * The part of a table a difference is about, or a whole view (`table` is then the view's name).
+ * Rendered into the cause verbatim.
+ */
+export type SchemaPart = 'table' | 'view' | 'column' | 'index' | 'foreign key' | 'check';
 
 export interface SchemaDifference {
   readonly direction: SchemaDirection;
@@ -73,6 +77,12 @@ function columnDetail(
       recorded.generated ?? 'not generated'
     }`;
   }
+  // `true` or absent. Listed under `retired` with no marker yet is the app's half alone.
+  if ((declared.retired === true) !== (recorded.retired === true)) {
+    return declared.retired === true
+      ? 'is declared retired and no migration recorded it'
+      : 'is declared again and was recorded retired';
+  }
   return undefined;
 }
 
@@ -240,7 +250,14 @@ function compareTable(declared: TableDescription, recorded: TableDescription): S
   return out;
 }
 
-const PART_ORDER: readonly SchemaPart[] = ['table', 'column', 'index', 'foreign key', 'check'];
+const PART_ORDER: readonly SchemaPart[] = [
+  'table',
+  'view',
+  'column',
+  'index',
+  'foreign key',
+  'check',
+];
 
 /**
  * Pure and total: the same two snapshots always produce the same ordered report, so a diff of two
@@ -281,6 +298,7 @@ export function diffDeclaredSchema(
       detail: RECORDED_ONLY,
     });
   }
+  out.push(...diffViews(declared.views, recorded.views));
   out.sort((a, b) => {
     if (a.table !== b.table) return a.table < b.table ? -1 : 1;
     if (a.part !== b.part) return PART_ORDER.indexOf(a.part) - PART_ORDER.indexOf(b.part);

package/src/schema-drift.ts

@@ -15,7 +15,13 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { EntityDescriptionLike, UnrenderedDeclaration } from '@ultimat3/db';
-import { declaredSchema, shellInertIdentifier, snapshotOf, unrenderedOf } from '@ultimat3/db';
+import {
+  declaredSchema,
+  recordRetired,
+  shellInertIdentifier,
+  snapshotOf,
+  unrenderedOf,
+} from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
 import { loadApp } from './app-load';
 import { checkSourceDrift, DB_PACKAGE } from './drift';
@@ -26,6 +32,7 @@ import {
 } from './drift-replica-identity';
 import { MIGRATIONS_DIR, readMigrations } from './migrations';
 import type { Finding } from './output';
+import { appRowSecurity, type RowSecurityWanted, rowSecurityFindings } from './row-security-wanted';
 import { diffDeclaredSchema, type SchemaDifference } from './schema-diff';
 
 /**
@@ -43,7 +50,7 @@ export type DeclaredEntities = (
  * one of these tables was dropped" — a DROP per table, handed out as the fix, for a syntax error in
  * one file. `loadApp`'s findings are reported by the steps that own them.
  */
-const appEntities: DeclaredEntities = async (root) => {
+export const appEntities: DeclaredEntities = async (root) => {
   const app = await loadApp(root);
   if (app.findings.length > 0) return undefined;
   return describeEntities();
@@ -111,10 +118,10 @@ function repairFix(
  * never get what the app declares; `undeclared` means the database holds what nothing declares.
  * One "drift" verdict over both teaches a reader neither.
  */
-/** A table difference names the table once: `table "customers" on table "customers"` did not. */
+/** A table or view difference names it once: `table "customers" on table "customers"` did not. */
 export const schemaDifferenceCause = (difference: SchemaDifference): string =>
-  difference.part === 'table'
-    ? `table "${difference.table}" ${difference.detail}`
+  difference.part === 'table' || difference.part === 'view'
+    ? `${difference.part} "${difference.table}" ${difference.detail}`
     : `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
 
 function findingFor(difference: SchemaDifference, repair: Repair): Finding {
@@ -139,6 +146,7 @@ export async function checkSnapshotDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
   identity: ReplicaIdentityWanted = appReplicaIdentity,
+  rowSecurity: RowSecurityWanted = appRowSecurity,
 ): Promise<readonly Finding[]> {
   if (!existsSync(join(root, DB_PACKAGE))) return [];
   const entities = await declared(root);
@@ -151,12 +159,22 @@ export async function checkSnapshotDrift(
   // states for the same call: a short one makes every subscribed name in the missing module a typo.
   const wanted = wantedReplicaIdentity(identity, new Set(entities.map((entity) => entity.table)));
   if ('finding' in wanted) return [wanted.finding];
-  const differences = diffDeclaredSchema(snapshotOf(entities, wanted.tables), recorded);
-  if (differences.length === 0) return [];
+  // `recordRetired`, the step `x db gen` takes after `snapshotOf`: a retired column stays on the
+  // record though no entity declares it, and that is the design rather than a difference.
+  // Its own code, ahead of the generic diff: a flipped flag moves no entity and no source hash.
+  const policies = rowSecurityFindings(entities, recorded, await rowSecurity(root));
+  const differences = diffDeclaredSchema(
+    recordRetired(snapshotOf(entities, wanted.tables), entities, recorded),
+    recorded,
+  );
+  if (differences.length === 0) return policies;
   // `recorded` and not the entities alone: whether an `assert` is a LOSS depends on whether a
   // migration recorded a CHECK for it, which only the sidecar knows.
   const unrendered = unrenderedOf(entities, recorded);
-  return differences.map((difference) => findingFor(difference, repairFix(unrendered, difference)));
+  return [
+    ...policies,
+    ...differences.map((difference) => findingFor(difference, repairFix(unrendered, difference))),
+  ];
 }
 
 /**
@@ -175,8 +193,9 @@ export async function checkMigrationDrift(
   declared: DeclaredEntities = appEntities,
   hashDrift: (root: string) => Promise<readonly Finding[]> = checkSourceDrift,
   identity: ReplicaIdentityWanted = appReplicaIdentity,
+  rowSecurity: RowSecurityWanted = appRowSecurity,
 ): Promise<readonly Finding[]> {
-  const snapshot = await checkSnapshotDrift(root, declared, identity);
+  const snapshot = await checkSnapshotDrift(root, declared, identity, rowSecurity);
   if (snapshot.length > 0) return snapshot;
   return hashDrift(root);
 }

package/src/schema-dump-drift.ts

@@ -1,7 +1,7 @@
-// The `drift` step's fourth rail: is the committed schema dump what the migrations produce, and
-// does a database loaded from it come back the same? The other three rails read files and open
+// The `drift` step's fourth rail: is the committed schema dump what the migrations produce, does
+// it hold what their snapshots record, and does a database loaded from it come back the same? The other three rails read files and open
 // nothing; this one replays the migrations on a scratch embedded database, because "what the
-// migrations produce" is a fact only a database can state.
+// migrations produce" is a fact only a database can state — and so is what a view outputs.
 
 // why: Bun has no directory probe — `Bun.file().exists()` answers about a file.
 import { existsSync } from 'node:fs';
@@ -9,7 +9,8 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Migration } from '@ultimat3/db';
-import type { SchemaDumpDifference } from '@ultimat3/db/schema-dump';
+import { ungeneratableStatements } from '@ultimat3/db';
+import type { SchemaDumpDifference, SchemaDumpFile } from '@ultimat3/db/schema-dump';
 import { compareSchemaDump, schemaDumpDrift } from '@ultimat3/db/schema-dump';
 import {
   hasSchemaDump,
@@ -20,9 +21,12 @@ import {
 } from './db-schema-dump';
 import { dumpNeverGenerated, replayFailure } from './db-schema-refresh';
 import { DB_PACKAGE } from './drift';
-import { readMigrations } from './migrations';
+import { MIGRATIONS_DIR, readMigrations } from './migrations';
 import type { Finding } from './output';
 import { findingFrom } from './output';
+import { appEntities, type DeclaredEntities } from './schema-drift';
+import { quoteArg } from './shell-quote';
+import { viewColumnFindings } from './view-drift';
 
 /** Injected so this module's rules are testable without booting a database per case. */
 export type SchemaReplay = (migrations: readonly Migration[]) => Promise<ReplayedSchema>;
@@ -33,6 +37,77 @@ const findingFor = (difference: SchemaDumpDifference): Finding => ({
   at: `${SCHEMA_DUMP_DIR}/${difference.path}`,
 });
 
+/** One `  "name" type…,` line of a generated `create table`; a `constraint` line opens with no quote. */
+const DUMP_COLUMN = /^ {2}"((?:[^"]|"")+)" /gm;
+
+const dumpColumns = (sql: string): readonly string[] =>
+  [...sql.matchAll(DUMP_COLUMN)].map((match) => (match[1] ?? '').replaceAll('""', '"'));
+
+/** The tables a statement alters or creates, as written: optionally schema-qualified, quoted or not. */
+const TABLE_STATEMENT =
+  /\b(?:alter|create|drop)\s+(?:unlogged\s+|temp(?:orary)?\s+)?table\s+(?:if\s+(?:not\s+)?exists\s+)?(?:only\s+)?(?:(?:"[^"]+"|[\w$]+)\.)?(?:"([^"]+)"|([\w$]+))/gi;
+
+/** As Postgres names it: an unquoted identifier folds to lower case, a quoted one is kept. */
+const tablesNamedBy = (sql: string): readonly string[] =>
+  [...sql.matchAll(TABLE_STATEMENT)].flatMap((match) => {
+    const name = match[1] ?? match[2]?.toLowerCase();
+    return name === undefined ? [] : [name];
+  });
+
+/**
+ * Tables whose columns a snapshot cannot speak for: `x db gen` writes a snapshot from the entities,
+ * so hand-written SQL is on no snapshot. That is every migration holding statements it could not have
+ * generated, and every one newer than the newest snapshot, which is a file somebody wrote by hand.
+ */
+const handWrittenTables = (migrations: readonly Migration[], newest: number): Set<string> => {
+  const tables = new Set<string>();
+  migrations.forEach((migration, index) => {
+    const sql = index > newest ? migration.up : ungeneratableStatements(migration.up).join(';\n');
+    for (const table of tablesNamedBy(sql)) tables.add(table);
+  });
+  return tables;
+};
+
+/**
+ * The rail the replay below cannot be: the dump IS that replay's output, so an edited migration
+ * regenerates into it and both sides agree. The snapshot was written from the entities and did not
+ * move. No database, and read beside the replay's findings rather than ahead of them: an edited
+ * migration and a stale file are two repairs.
+ */
+function dumpColumnFindings(
+  migrations: readonly Migration[],
+  committed: readonly SchemaDumpFile[],
+): readonly Finding[] {
+  const newest = migrations.findLastIndex((migration) => migration.snapshot !== undefined);
+  const snapshot = migrations[newest]?.snapshot;
+  if (snapshot === undefined) return [];
+  const exempt = handWrittenTables(migrations, newest);
+  const files = new Map(committed.map((file) => [file.path, file.content]));
+  return snapshot.tables.flatMap((table) => {
+    const path = `04_tables/${table.name}.sql`;
+    const held = files.get(path);
+    if (held === undefined || exempt.has(table.name)) return [];
+    const dumped = dumpColumns(held);
+    const recorded = table.columns.map((column) => column.name);
+    const extra = dumped.filter((name) => !recorded.includes(name));
+    const lost = recorded.filter((name) => !dumped.includes(name));
+    if (extra.length === 0 && lost.length === 0) return [];
+    const said = [
+      ...extra.map((name) => `"${name}" is in the dump`),
+      ...lost.map((name) => `"${name}" is only in the snapshot`),
+    ].join(', ');
+    return [
+      {
+        code: 'X_DB_DRIFT',
+        cause: `the dump holds a column no migration's snapshot records, in table "${table.name}": ${said}`,
+        fix: `git checkout -- ${quoteArg(MIGRATIONS_DIR)} ${quoteArg(SCHEMA_DUMP_DIR)}   # an applied migration was edited: restore it. Meant it: declare the column on its entity, then x db gen "<change>"`,
+        docs: ERROR_DOCS_URL,
+        at: `${SCHEMA_DUMP_DIR}/${path}`,
+      },
+    ];
+  });
+}
+
 /**
  * Empty result = the dump is the migrations' own.
  *
@@ -49,16 +124,25 @@ export async function checkSchemaDump(
   root: string,
   env: Readonly<Record<string, string | undefined>> = Bun.env,
   replay: SchemaReplay = replayFor(root, env, true),
+  declared: DeclaredEntities = appEntities,
 ): Promise<readonly Finding[]> {
   if (!existsSync(join(root, DB_PACKAGE))) return [];
   const migrations = await readMigrations(root);
   if (!hasSchemaDump(root)) return migrations.length === 0 ? [] : [dumpNeverGenerated()];
   const committed = await readSchemaDump(root);
+  const columns = dumpColumnFindings(migrations, committed);
   let replayed: ReplayedSchema;
   try {
     replayed = await replay(migrations);
   } catch (error) {
-    return [replayFailure(error)];
+    return [...columns, replayFailure(error)];
   }
-  return [...compareSchemaDump(committed, replayed.files), ...replayed.reload].map(findingFor);
+  // Only a replay that created a view loads the app: what a view outputs is the one column list
+  // no snapshot records, and an app with no view owes this rail nothing.
+  const entities = replayed.catalog.views.length === 0 ? undefined : await declared(root);
+  return [
+    ...columns,
+    ...[...compareSchemaDump(committed, replayed.files), ...replayed.reload].map(findingFor),
+    ...(entities === undefined ? [] : viewColumnFindings(entities, replayed.catalog)),
+  ];
 }

package/src/script-csp.ts

@@ -16,7 +16,7 @@ import { HYDRATE_RUNTIME_BODIES, STREAM_REVEAL_BODIES } from '@ultimat3/render';
  * which `theme-boot.ts` derives from the same string it inlines.
  */
 export function inlineScriptSources(extra: readonly string[] = []): readonly string[] {
-  // The stream reveal too: a `render: 'stream'` page swaps each Suspense boundary in with a
+  // The stream reveal too: a `render: 'stream'` page swaps each `<Hole>` in with a
   // constant inline `$X()` call, and unhashed it is blocked under the enforced policy.
   const bodies = [...HYDRATE_RUNTIME_BODIES, ...STREAM_REVEAL_BODIES];
   return [...new Set([...bodies.map(cspHashSource), ...extra])].sort();

package/src/seo-cards.ts

@@ -0,0 +1,26 @@
+// Single responsibility: the convention `og.capture` rests on, as a gate finding — a declared card
+// path is a `site/` route, or the build has no page to photograph. `x verify`'s `seo` step asks it
+// of every route whose meta the scan resolved; the build asks it again of the filled paths.
+
+import { routeEntries } from '@ultimat3/render';
+import type { RouteRecord } from '@ultimat3/seo';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { CardRouteUnknownError } from './static-capture-errors';
+
+/** True when some `site/` route's pattern answers `path` — a static or a prerendered dynamic one. */
+const isSiteRoute = (path: string): boolean =>
+  routeEntries().some((entry) => entry.surface === 'site' && entry.pattern.regex.test(path));
+
+export function cardRouteFindings(records: readonly RouteRecord[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const record of records) {
+    const capture = record.meta?.og?.capture;
+    if (capture === undefined || isSiteRoute(capture)) continue;
+    findings.push({
+      ...findingFrom(new CardRouteUnknownError([capture], record.file)),
+      at: record.file,
+    });
+  }
+  return findings;
+}

package/src/seo-routes.ts

@@ -1,5 +1,5 @@
-// `GET /robots.txt`, `GET /sitemap.xml` and its parts (`/sitemaps/<n>.xml`) from a running web
-// role — the files the static export writes, for a deploy that serves its pages from a container.
+// `GET /robots.txt`, `GET /llms.txt`, `GET /sitemap.xml` and its parts (`/sitemaps/<n>.xml`) from a
+// running web role — the files the static export writes, for a deploy that serves from a container.
 // Mounted by `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
 
 import {
@@ -11,8 +11,8 @@ import {
   tryResolveEnvironment,
 } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
-import { SITEMAP_PARTS_DIR } from '@ultimat3/seo';
+import { applyCacheHeaders, jsonResponse, NO_STORE, textResponse } from '@ultimat3/http';
+import { LLMS_PATH, SITEMAP_PARTS_DIR } from '@ultimat3/seo';
 import { quoteArg } from './shell-quote';
 import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
 import type { SiteSeo } from './site-seo';
@@ -74,7 +74,7 @@ interface Memo {
 }
 
 /** A placeholder for the one statement between building a first memo and starting its enumeration. */
-const NO_ANSWER: SiteSeo = { robots: '', sitemaps: [] };
+const NO_ANSWER: SiteSeo = { robots: '', sitemaps: [], llms: '' };
 
 export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
   const environment: Environment =
@@ -87,6 +87,7 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
       robotsGroups: options.site?.robotsGroups ?? [],
       ...(options.site === undefined ? {} : { sitemap: options.site.sitemap }),
       ...(options.root === undefined ? {} : { root: options.root }),
+      ...(options.site?.llms === undefined ? {} : { llms: options.site.llms }),
     });
   // One answer per origin. A FIRST enumeration is single-flight and awaited; failed, it is dropped,
   // so the next request asks again rather than serving the failure for an hour.
@@ -189,12 +190,24 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
       meta: { name: 'seo.robots', auth: 'public', tags: ['seo'] },
       handler: async (request: UltimateRequest): Promise<Response> =>
         applyCacheHeaders(
-          new Response((await answer(request)).robots, {
+          textResponse((await answer(request)).robots, {
             headers: { 'content-type': 'text/plain; charset=utf-8' },
           }),
           SEO_CACHE,
         ),
     },
+    {
+      method: 'GET',
+      path: LLMS_PATH,
+      meta: { name: 'seo.llms', auth: 'public', tags: ['seo'] },
+      handler: async (request: UltimateRequest): Promise<Response> =>
+        applyCacheHeaders(
+          textResponse((await answer(request)).llms, {
+            headers: { 'content-type': 'text/markdown; charset=utf-8' },
+          }),
+          SEO_CACHE,
+        ),
+    },
     {
       method: 'GET',
       path: SITEMAP_PATH,
@@ -202,7 +215,8 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
       // The first file is `/sitemap.xml` in both shapes: the whole urlset, or the index of parts.
       handler: async (request: UltimateRequest): Promise<Response> =>
         applyCacheHeaders(
-          new Response((await answer(request)).sitemaps[0]?.xml ?? '', {
+          // `textResponse` for the length it declares: `compress` reads nothing undeclared.
+          textResponse((await answer(request)).sitemaps[0]?.xml ?? '', {
             headers: { 'content-type': 'application/xml; charset=utf-8' },
           }),
           SEO_CACHE,
@@ -219,7 +233,7 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
         const part = seo.sitemaps.find((file) => file.path === request.pathname);
         if (part !== undefined && part.path !== SITEMAP_PATH) {
           return applyCacheHeaders(
-            new Response(part.xml, {
+            textResponse(part.xml, {
               headers: { 'content-type': 'application/xml; charset=utf-8' },
             }),
             SEO_CACHE,