@ultimat3/cli 29.4.0 → 30.1.0

package/src/serve-boot.ts

@@ -6,11 +6,15 @@
 // module graph holds neither.
 
 import type { DrainConfig, LifecycleOptions, Role } from '@ultimat3/core';
-import { configureLifecycle, logger } from '@ultimat3/core';
+import { configureLifecycle, logger, UltimateError } from '@ultimat3/core';
+import { loadAppConfig } from './app-config-load';
+import { armFailureCapture } from './failure-capture-boot';
 import type { MetricsEndpoint } from './metrics-endpoint';
 import { startOtlpExport } from './otlp-export';
+import type { Finding } from './output';
 import { loadAppForRole, roleLoadFor } from './role-load';
 import { startRoles } from './role-start';
+import { armRowSecurity, rowSecurityDeclared } from './row-security-boot';
 import { resolveServices } from './runtime-bindings';
 import { busLabel } from './runtime-bus';
 import { warnIfIdempotencyProcessScoped } from './runtime-idempotency-scope';
@@ -96,6 +100,29 @@ export async function bootServing(boot: {
   return bootRoles({ ...boot, runtime });
 }
 
+/**
+ * A container role whose app did not load whole: `X_APP_MODULE_LOAD_FAILED`. Beside its one thrower
+ * (`errors.ts` is at its ceiling). Every environment, not only production: this boot has no watcher
+ * to load the module again after a save — that is `x dev`'s, which keeps its own log-and-reload —
+ * so a half-loaded app here stays half-loaded, answering `/readyz` without a route or a policy.
+ */
+export class AppModuleLoadFailedError extends UltimateError {
+  constructor(input: { role: Role; findings: readonly Finding[] }) {
+    const modules = input.findings.map((finding) => finding.at ?? '(unknown module)');
+    super({
+      code: 'X_APP_MODULE_LOAD_FAILED',
+      cause: `the ${input.role} role refused to start: ${String(modules.length)} app module(s) failed to load, and serving without them drops their routes, actions, policies and jobs — ${input.findings.map((finding, index) => `${modules[index] ?? ''} (${finding.code})`).join(', ')}`,
+      fix: 'x manifest --json   # names each module that does not load and why; fix it, then restart the role',
+      meta: { role: input.role, modules },
+    });
+  }
+}
+
+/** Throws when any app module failed to load; each was already logged with its own cause. */
+export function refuseHalfLoadedApp(role: Role, findings: readonly Finding[]): void {
+  if (findings.length > 0) throw new AppModuleLoadFailedError({ role, findings });
+}
+
 /** The half of `serveApp` whose every acquisition is registered for rollback. */
 async function bootRoles(boot: {
   readonly options: ServeOptions;
@@ -106,6 +133,15 @@ async function bootRoles(boot: {
   readonly metrics: MetricsEndpoint;
 }): Promise<ServedApp> {
   const { options, role, runtime, acquired, metrics } = boot;
+  // Before the app's modules, because importing one may register a `close` hook, and that phase
+  // runs last-registered first: the flush has to be the hook registered earliest, or a teardown's
+  // spans are recorded into an exporter already shut down. `OTEL_EXPORTER_OTLP_ENDPOINT` is in the
+  // shipped chart and nothing read it, so every deployment that configured a collector got an empty
+  // dashboard. `x dev` keeps its own recorder — the `/_x` timeline is a different sink with a
+  // different lifetime — so this is the production boot's alone (axiom 6).
+  // At the FRONT of the unwind list, so the stop and a failed boot's rollback alike release it
+  // last: the drain's own spans and the final counter snapshot still have somewhere to go.
+  acquired.unshift(startOtlpExport(options.env));
   // The image's compiled stylesheets, before the first page is imported — importing one IS
   // compiling its sheet — and the count of what this boot compiles anyway.
   adoptPrebuiltStyles(options.root);
@@ -113,23 +149,26 @@ async function bootRoles(boot: {
   // Importing the app's modules IS the registration: every route, action and job below is
   // whatever this call put in the registries — for THIS role (`role-load.ts`).
   const loaded = await loadAppForRole(options.root, role);
-  // A module that would not import registered nothing, and a process that only logs the roles it
-  // started gives no sign of it: each one is a line an operator can act on.
+  // A module that would not import registered nothing — its routes, actions, policies and jobs
+  // are simply absent — so each is logged with its own cause, and then the role refuses to serve.
   for (const finding of loaded.findings) {
     logger.error('ultimate app module failed to load', { role, ...finding });
   }
+  refuseHalfLoadedApp(role, loaded.findings);
+  // After the app's modules and before any role serves: a role Postgres exempts from row security is
+  // refused here (`X_DB_ROW_SECURITY_BYPASSED`), never discovered on another tenant's first read.
+  // PGlite's one session is a superuser: there the boot serves as `x_app` instead of refusing.
+  const embedded = runtime.services.db.mode === 'embedded';
+  const appConfig = await loadAppConfig(options.root);
+  acquired.push(await armRowSecurity(rowSecurityDeclared(appConfig), { embedded }));
+  // `failureCapture.enabled`: a 5xx keeps a replayable bundle for `x repro` (off by default).
+  acquired.push(armFailureCapture(appConfig));
   // After the app's modules: an app swaps the store at import time, after `startServices`.
   warnIfIdempotencyProcessScoped();
   const buildId = await buildIdFor(options, role);
   // Before the first socket opens: everything above this line fails loudly into the container's
   // own logs, everything below it is a served request, a claimed job or a routed frame.
   configureReporting(options.env, buildId);
-  // Beside error reporting, and for the same reason it is here: `OTEL_EXPORTER_OTLP_ENDPOINT` is
-  // in the shipped chart and nothing read it, so every deployment that configured a collector got
-  // an empty dashboard. `x dev` keeps its own recorder — the `/_x` timeline is a different sink
-  // with a different lifetime — so this is the production boot's alone (axiom 6).
-  const stopOtlp = startOtlpExport(options.env);
-  acquired.push(stopOtlp);
   // Only the web role serves pages, so only it builds islands and assembles a route table: a
   // worker, scheduler, sync or replicator pod compiled every island of the app on every boot for
   // nothing it would ever serve (plan 101, slice 12 e). The MODULE is the web role's as well —
@@ -196,18 +235,12 @@ async function bootRoles(boot: {
     running,
     runtime,
     async stop() {
-      // Every step runs and the first failure is rethrown (`releaseOrThrow`): a refused role stop
-      // used to leave the services, the PGlite lock and the exporter behind it. Listed in boot
-      // order, released newest first — the roles; then the web surface, after the server drained
-      // (a bust landing mid-drain still marks the pages it is serving); then the services; LAST
-      // the exporter, so the drain's own spans and the final counter snapshot still have
-      // somewhere to go.
-      await releaseOrThrow([
-        stopOtlp,
-        () => runtime.stop(),
-        () => web?.release(),
-        () => running.stop(),
-      ]);
+      // The boot's own unwind list, whole (as `x dev`'s is): every step runs and the first failure
+      // is rethrown (`releaseOrThrow`), newest first — the roles; the web surface, after the server
+      // drained; the failure-capture store, settled while the pool is still open; the row-security
+      // client; the services; the exporter last. A hand-listed copy dropped the two in the middle,
+      // so a bundle in flight at drain was lost and the next boot in the process inherited them.
+      await releaseOrThrow([...acquired]);
     },
   };
 }

package/src/serve-drain.ts

@@ -13,6 +13,7 @@ export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig
         readinessGraceMs: drain.readinessGraceMs,
         deadlineMs: drain.deadlineMs,
         workerDeadlineMs: drain.workerDeadlineMs,
+        workerRetireMs: drain.workerRetireMs,
       };
 }
 

package/src/serve-env.ts

@@ -1,8 +1,16 @@
 // What a container's environment decides about a boot: which role, which port, which interface,
 // and where errors are reported. Split from `serve.ts`, which re-exports every name here.
 
-import type { Role } from '@ultimat3/core';
-import { configureErrorReporting, isRole, ROLES, sentryErrorReporter } from '@ultimat3/core';
+import type { ErrorReporter, Role } from '@ultimat3/core';
+import {
+  chainErrorReporters,
+  configureErrorReporting,
+  errorReportersOf,
+  installedErrorReporter,
+  isRole,
+  ROLES,
+  sentryErrorReporter,
+} from '@ultimat3/core';
 import { PortInvalidError, RoleUnknownError } from './errors';
 import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import type { WebBinding } from './role-start';
@@ -103,17 +111,27 @@ export const metricsPortFor = (env: Env, port: number, override?: number): numbe
  */
 export const ERROR_DSN_KEY = 'SENTRY_DSN';
 
+/** The transport the LAST `configureReporting` installed, so a second boot swaps it, never adds. */
+let vendor: ErrorReporter | undefined;
+
 /**
- * Switch reporting on for this process. Unset DSN leaves core's no-op reporter in place, so a
- * laptop and a CI run pay nothing and page nobody — and the release every event carries is the
- * build id this boot already computed, never a second identity for the same deploy.
+ * Switch reporting on for this process. Unset DSN leaves whatever the app installed (or core's
+ * no-op) in place, so a laptop and a CI run pay nothing and page nobody — and the release every
+ * event carries is the build id this boot already computed, never a second identity for the deploy.
+ *
+ * The transport is CHAINED beside the app's reporter, never over it: the app's modules import —
+ * and install an `errorGroupsSink`, say — before this line runs, and replacing it here would
+ * leave `/admin/errors` empty in exactly the deploys that set `SENTRY_DSN`.
  */
 export function configureReporting(env: Env, buildId: string): void {
   const dsn = env[ERROR_DSN_KEY]?.trim();
+  // A malformed DSN throws here, at boot, rather than at the first outage: a monitor that was
+  // never connected looks exactly like an app that never failed.
+  const next = dsn === undefined || dsn.length === 0 ? undefined : sentryErrorReporter({ dsn });
+  const app = errorReportersOf(installedErrorReporter()).filter((member) => member !== vendor);
+  vendor = next;
   configureErrorReporting({
     release: buildId,
-    // A malformed DSN throws here, at boot, rather than at the first outage: a monitor that was
-    // never connected looks exactly like an app that never failed.
-    ...(dsn === undefined || dsn.length === 0 ? {} : { reporter: sentryErrorReporter({ dsn }) }),
+    reporter: chainErrorReporters(...app, ...(next === undefined ? [] : [next])),
   });
 }

package/src/serve-retire.ts

@@ -62,12 +62,18 @@ export function armWorkerRetire(options: WorkerRetireOptions = {}): WorkerRetire
     const worker = await adopted;
     try {
       if (worker !== null) {
-        const before = await worker.stats();
-        logger.info('jobs.worker.retiring', {
-          signal: RETIRE_SIGNAL,
-          workerId: before.workerId,
-          inFlight: before.inFlight,
-        });
+        // The log line alone reads stats: a db blip here must not skip the stop, or the drain
+        // below is a plain SIGTERM drain and cuts at the budget a job meant to outlast.
+        try {
+          const before = await worker.stats();
+          logger.info('jobs.worker.retiring', {
+            signal: RETIRE_SIGNAL,
+            workerId: before.workerId,
+            inFlight: before.inFlight,
+          });
+        } catch (error) {
+          logger.warn('jobs.worker.retire-stats-failed', { error: renderThrowable(error) });
+        }
         await worker.stop(RETIRE_SIGNAL);
         const after = await worker.stats();
         logger.info('jobs.worker.retired', {

package/src/serve-web.ts

@@ -3,14 +3,17 @@
 // `await import()` for `ROLE=web` alone, and `serve-graph.test.ts` pins what every other role is
 // spared: render's server half, the PWA, SEO, MCP and island subsystems.
 
+import { resolveEnvironment } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
-
 import { installedVapid } from '@ultimat3/pwa';
 import { describePages } from '@ultimat3/render';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
+import { loadAppConfig } from './app-config-load';
 import { mountAppMcp } from './app-mcp';
+import { clientErrorsSurface } from './client-errors-routes';
+import { clientScriptHeads, clientVitalsSurface } from './client-vitals-route';
 import { errorPageStyleBodies } from './error-page-csp';
 import { islandRoutes } from './island-routes';
 import type { LoadedIslands } from './island-store';
@@ -18,7 +21,10 @@ import { loadOrBuildIslands } from './island-store';
 import { loadNavigation, pageNavigation } from './page-navigation';
 import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
+import { plainRoutes } from './plain-routes';
 import { loadPwaArtifacts } from './pwa-artifacts';
+import { retainBuildAssets } from './retained-assets-boot';
+import { withRetainedAssets } from './retained-assets-read';
 import { adminMountRoutes } from './runtime-admin';
 import { assetRoutes } from './runtime-assets';
 import { attachedIsr } from './runtime-isr';
@@ -34,6 +40,7 @@ import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 import { loadThemeMode, themeBoot } from './theme-boot';
 import { loadThemeBrand } from './theme-brand';
+import { zoneBoot } from './zone-boot';
 
 /** Everything `startRoles` is handed that only a process serving documents has. */
 export interface WebSurface {
@@ -108,6 +115,29 @@ export async function webSurface(
   const mcpMount = await mountAppMcp(options.root);
   // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
   const served = servedStorage(runtime.storage);
+  // `assets.retain`: this build's hashed files onto the shared disk, BEFORE the role binds — a pod
+  // takes no traffic until `/readyz`, so no document of this build reaches an old pod first.
+  const config = await loadAppConfig(options.root);
+  // `time.detect`: the zone script on `app/` documents, admitted below by its own hash.
+  const zone = zoneBoot(config?.time);
+  const scripts = [
+    ...sync.scripts,
+    ...(navigation.script === undefined ? [] : [navigation.script]),
+  ];
+  const retained = await retainBuildAssets({
+    root: options.root,
+    config,
+    storage: served,
+    buildId,
+    environment: resolveEnvironment({ env: options.env, fallback: 'production' }),
+    islands,
+    styles: styleBundle(),
+    scripts,
+  });
+  // The same call `x dev` makes: `clientErrors.enabled` or nothing mounted and nothing named.
+  const clientErrors = clientErrorsSurface(config?.clientErrors, buildId);
+  // And real-user timings, on their own switch: the call `x dev` makes, so both name one script.
+  const vitals = clientVitalsSurface(config?.clientErrors?.vitals);
   // Attached, so a tag bust marks this process's ISR pages stale. The store is the deployment's
   // when it supplied one: the default is per process, so twelve replicas hold twelve of them and a
   // purge regenerates one twelfth of the fleet while the other eleven keep the invalidated page.
@@ -122,7 +152,7 @@ export async function webSurface(
     ...apiMountRoutes(options.runtime?.rateLimitStore ?? runtime.rateLimitStore),
     ...mcpMount.routes,
     // The app's own plain routes (`apps/<app>/runtime.ts` `routes`), before any page can shadow one.
-    ...(options.runtime?.routes ?? []),
+    ...plainRoutes(options.runtime?.routes),
     ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...assetRoutes({
       root: options.root,
@@ -131,6 +161,8 @@ export async function webSurface(
       ...(pwa === undefined ? {} : { pwa }),
     }),
     ...storageRoutes({ storage: served }),
+    ...(clientErrors?.routes ?? []),
+    ...(vitals?.routes ?? []),
     ...islandRoutes(() => islands),
     // The surface stylesheets the documents link. Built from the registry the `loadApp` above
     // filled, so this process serves exactly the CSS it renders against.
@@ -169,12 +201,18 @@ export async function webSurface(
       ...(pwa === undefined
         ? {}
         : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
+      ...clientScriptHeads(clientErrors, vitals, zone),
       isr: isr.isr,
     }),
   ];
   return {
-    routes,
-    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    // A miss on any asset route asks the retained builds (`assets.retain`); none declared, unchanged.
+    routes: withRetainedAssets(routes, retained?.reader),
+    inlineScripts: [
+      theme.cspSource,
+      ...(speculation === undefined ? [] : [speculation.cspSource]),
+      ...(zone === undefined ? [] : [zone.cspSource]),
+    ],
     // The enforced policy this process sends must admit the app's own error pages' `<style>` and
     // the brand's; `x dev` is report-only, so only here was a missing hash an unstyled page.
     inlineStyles: [

package/src/serve.ts

@@ -50,20 +50,22 @@ export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-t
 export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
   // `'apply'`, never the stamp-first default: this IS the step that applies, and an operator
   // re-running it is how a dropped framework table comes back.
-  const queue = await startQueue(
-    resolveServices(options.root, options.env),
-    options.runtime,
-    options.env,
-    'apply',
-  );
+  const services = resolveServices(options.root, options.env);
+  const queue = await startQueue(services, options.runtime, options.env, 'apply');
   try {
     const migrations = await readMigrations(options.root);
+    // PGlite with `database.rowSecurity`: the app's migrations run as `x_migrator` for their scope.
+    // Behind `await import()` and only embedded: a container's migrate graph never loads it.
+    const release =
+      services.db.mode === 'embedded'
+        ? await (await import('./row-security-boot')).migrateAsMigrator(options.root)
+        : undefined;
     const report = await migrate({
       migrations,
       ...(options.env['APP_VERSION'] === undefined
         ? {}
         : { appVersion: options.env['APP_VERSION'] }),
-    });
+    }).finally(() => release?.());
     logger.info('ultimate migrate applied', {
       applied: report.applied.length,
       available: migrations.length,

package/src/site-asset-routes.ts

@@ -35,7 +35,13 @@ function assetResponse(asset: SiteAsset, range: string | null): Response {
     });
   }
   if (wanted === undefined) {
-    return applyCacheHeaders(new Response(file, { headers }), SITE_ASSET_CACHE);
+    return applyCacheHeaders(
+      new Response(file, {
+        // Declared, or `compress` may not read it: a `Bun.file` body states no length of its own.
+        headers: { ...headers, 'content-length': String(asset.bytes) },
+      }),
+      SITE_ASSET_CACHE,
+    );
   }
   return applyCacheHeaders(
     new Response(file.slice(wanted.start, wanted.end + 1), {

package/src/site-config.ts

@@ -26,6 +26,8 @@ export interface SiteSettings {
    * `SiteSettings` literal written before it existed still compiles.
    */
   readonly favicon?: SiteFavicon | undefined;
+  /** `seo.llms` — `/llms.txt` on (the default) or off. Optional for `robotsGroups`' reason. */
+  readonly llms?: boolean | undefined;
 }
 
 export const NO_SITE_SETTINGS: SiteSettings = {
@@ -34,6 +36,7 @@ export const NO_SITE_SETTINGS: SiteSettings = {
   robotsGroups: [],
   sitemap: { extra: [], lastmod: 'none', sections: [], pageSize: 50_000 },
   favicon: undefined,
+  llms: true,
 };
 
 const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
@@ -48,6 +51,7 @@ export async function loadSiteSettings(root: string): Promise<SiteSettings> {
     robotsGroups: [...(config.seo.robots.groups ?? [])],
     sitemap: config.seo.sitemap,
     favicon,
+    llms: config.seo.llms !== false,
   };
 }
 

package/src/site-llms-pages.ts

@@ -0,0 +1,106 @@
+// `/llms.txt`'s per-page reads: every page of a public `site/` route whose `meta` needs its `load`
+// (or its params), titled by that `meta`. Collected by the static export INSIDE its API scope, so
+// `siteLlms` never runs a page's `load` after the build stopped answering the app's own queries.
+
+import type { Environment } from '@ultimat3/core';
+import { ctxOf, DEFAULT_ENVIRONMENT, runWithContext, tryResolveEnvironment } from '@ultimat3/core';
+import type { PrerenderEntry, RouteEntry } from '@ultimat3/render';
+import { metaContextFor, routeDataFor, routeEntries } from '@ultimat3/render';
+import { enumeratePrerenderEntries, fillPath } from '@ultimat3/render/server';
+import type { RouteRecord } from '@ultimat3/seo';
+import { isIndexable } from '@ultimat3/seo';
+import type { RouteEntries } from './prerender-entries';
+import { readSiteMeta } from './seo-meta';
+
+/** Each route's page records, by DECLARED path (`/posts/:slug`) — what `siteLlms` reads first. */
+export type LlmsPages = ReadonlyMap<string, readonly RouteRecord[]>;
+
+export type Enumerate = (entry: RouteEntry) => Promise<readonly PrerenderEntry[]>;
+
+export interface LlmsPageOptions {
+  readonly baseUrl: string;
+  /** The app's default locale: every `meta` runs in it. */
+  readonly defaultLocale: string;
+  /** The build's own enumeration (`PrerenderReport.entries`), so `prerender()` is asked once. */
+  readonly enumerate?: Enumerate | undefined;
+}
+
+/** A `site/` page anyone may fetch — `site-seo.ts`' own rule. */
+const isPublicSite = (entry: RouteEntry): boolean =>
+  entry.surface === 'site' && entry.config.policy === undefined;
+
+/** `llms.txt`'s routes: those whose `meta` resolves without a request, and those that need `load`. */
+export interface LlmsRoutes {
+  readonly resolved: readonly RouteRecord[];
+  readonly loaded: readonly RouteEntry[];
+}
+
+/**
+ * The public `site/` routes, split once: `resolved` answered by `readSiteMeta` (no `load`, no
+ * params), `loaded` the rest, which `pageRecords` reads page by page.
+ */
+export async function llmsRoutes(defaultLocale: string): Promise<LlmsRoutes> {
+  const entries = routeEntries().filter(isPublicSite);
+  const publicPaths = new Set(entries.map((entry) => entry.path));
+  const resolved = (await readSiteMeta(defaultLocale)).records.filter((record) =>
+    publicPaths.has(record.path),
+  );
+  const resolvedPaths = new Set(resolved.map((record) => record.path));
+  return { resolved, loaded: entries.filter((entry) => !resolvedPaths.has(entry.path)) };
+}
+
+/**
+ * One record per page `prerender()` enumerates, with the `meta` its own `load` feeds, run in the
+ * default locale with no actor: the prerender's context.
+ */
+export async function pageRecords(
+  entry: RouteEntry,
+  options: LlmsPageOptions,
+): Promise<readonly RouteRecord[]> {
+  const records: RouteRecord[] = [];
+  for (const page of await (options.enumerate ?? enumeratePrerenderEntries)(entry)) {
+    const path = fillPath(entry.pattern.source, page.params);
+    const ctx = { url: `${options.baseUrl.replace(/\/+$/, '')}${path}`, params: page.params };
+    const meta = await runWithContext(
+      ctxOf({ role: 'web', locale: options.defaultLocale }),
+      async () => entry.config.meta(metaContextFor(ctx, await routeDataFor(entry.config, ctx))),
+    );
+    records.push({ path, file: entry.file, surface: 'site', render: entry.config.render, meta });
+  }
+  return records;
+}
+
+export interface CollectLlmsPagesOptions extends Omit<LlmsPageOptions, 'enumerate'> {
+  /** The build's own `prerender()` answers (`enumerateRoutes`): a route listed is never asked again. */
+  readonly entries?: RouteEntries | undefined;
+  readonly environment?: Environment | undefined;
+  /** `seo.llms`; `false` collects nothing. */
+  readonly enabled?: boolean | undefined;
+  /** The build's API scope: every `load` runs inside it, where the app's own queries answer. */
+  readonly scope: <T>(fn: () => Promise<T>) => Promise<T>;
+  /** Before the first `load`: the build starts its database here, and only when one is needed. */
+  readonly before?: (() => Promise<void>) | undefined;
+}
+
+/**
+ * Every page record `siteLlms` would read through a `load`, read now, inside `scope`. Nothing
+ * outside production or under `seo.llms: false` — `siteLlms` answers empty there, so a staging
+ * build reads no row for a document it throws away. A throw is the build's failure: a `load` that
+ * cannot answer is the app's bug, never a page silently left out.
+ */
+export async function collectLlmsPages(options: CollectLlmsPagesOptions): Promise<LlmsPages> {
+  const environment = options.environment ?? tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
+  const pages = new Map<string, readonly RouteRecord[]>();
+  if (options.enabled === false || !isIndexable(environment)) return pages;
+  const routes = (await llmsRoutes(options.defaultLocale)).loaded;
+  if (routes.length === 0) return pages;
+  await options.before?.();
+  const enumerate: Enumerate = (route) => {
+    const listed = options.entries?.get(route.path);
+    return listed === undefined ? enumeratePrerenderEntries(route) : Promise.resolve(listed);
+  };
+  for (const entry of routes) {
+    pages.set(entry.path, await options.scope(() => pageRecords(entry, { ...options, enumerate })));
+  }
+  return pages;
+}

package/src/site-llms.ts

@@ -0,0 +1,64 @@
+// `/llms.txt`'s pages, off the route table: every public `site/` page in the default locale by the
+// title and description its own `meta` gives it. A dynamic route (or one with a `load`) is expanded
+// through `prerender()` and its `load`, page by page, exactly as the static export renders it — or
+// read off what the export already collected inside its API scope (`site-llms-pages.ts`).
+
+import type { Environment } from '@ultimat3/core';
+import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import { unlocalizedPath } from '@ultimat3/i18n';
+import type { RouteRecord } from '@ultimat3/seo';
+import { buildLlmsTxt, disallowMatcher, isDynamic, isIndexable } from '@ultimat3/seo';
+import type { Enumerate, LlmsPages } from './site-llms-pages';
+import { llmsRoutes, pageRecords } from './site-llms-pages';
+
+export interface SiteLlmsOptions {
+  readonly baseUrl: string;
+  readonly environment?: Environment | undefined;
+  /** `seo.llms`; `false` answers an empty document. */
+  readonly enabled?: boolean | undefined;
+  readonly disallow?: readonly string[] | undefined;
+  /** The static export's emitted pages per route, as the sitemap reads them (`SiteSeoOptions`). */
+  readonly pagesFor?: ((routePath: string) => readonly string[]) | undefined;
+  /** The app's default locale: every `meta` runs in it, and its paths are unprefixed. */
+  readonly defaultLocale: string;
+  /** `siteSeo`'s one enumeration per route, so the sitemap and this file never call `prerender()` twice. */
+  readonly enumerate?: Enumerate | undefined;
+  /**
+   * What the static export read inside its API scope (`collectLlmsPages`), by declared route path.
+   * A route listed here never runs its `load` again: by the time `llms.txt` is written the build's
+   * scope is gone, and a `load` reading the app's own query failed the export
+   * (`X_CLIENT_TRANSPORT_FAILED`).
+   */
+  readonly pages?: LlmsPages | undefined;
+}
+
+/**
+ * Empty outside production and under `seo.llms: false` BEFORE any `prerender()` or `load` runs: a
+ * staging web role must not read every post to answer a document it then throws away.
+ */
+export async function siteLlms(options: SiteLlmsOptions): Promise<string> {
+  const environment = options.environment ?? tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
+  if (options.enabled === false || !isIndexable(environment)) return '';
+  const disallowed = disallowMatcher(options.disallow ?? []);
+  const { resolved, loaded } = await llmsRoutes(options.defaultLocale);
+  const expanded: RouteRecord[] = [];
+  for (const entry of loaded) {
+    const records = options.pages?.get(entry.path) ?? (await pageRecords(entry, options));
+    expanded.push(...emittedOnly(entry.path, records, options));
+  }
+  return buildLlmsTxt(
+    [...resolved, ...expanded].filter((record) => !disallowed(record.path)),
+    { baseUrl: options.baseUrl, environment },
+  );
+}
+
+/** A dynamic route's pages, less those the export did not emit — the sitemap's own rule. */
+function emittedOnly(
+  routePath: string,
+  records: readonly RouteRecord[],
+  options: SiteLlmsOptions,
+): readonly RouteRecord[] {
+  if (options.pagesFor === undefined || !isDynamic(routePath)) return records;
+  const emitted = new Set(options.pagesFor(routePath).map((path) => unlocalizedPath(path)));
+  return records.filter((record) => emitted.has(record.path));
+}

package/src/site-seo-write.ts

@@ -1,8 +1,9 @@
 // Single responsibility: `siteSeo()`'s answer as files in a static export — `/sitemap.xml`, every
-// part an index names, and `robots.txt` — so a CDN serves the bytes a running web role answers.
+// part an index names, `robots.txt` and `llms.txt` — so a CDN serves the bytes a running web role answers.
 
 // why: Bun exposes no path-join primitive, and every file path is relative to the output root.
 import { join } from 'node:path';
+import { LLMS_PATH } from '@ultimat3/seo';
 import { ROBOTS_PATH, type SiteSeo } from './site-seo';
 
 /**
@@ -12,5 +13,6 @@ import { ROBOTS_PATH, type SiteSeo } from './site-seo';
 export async function writeSiteSeo(out: string, seo: SiteSeo): Promise<readonly string[]> {
   for (const file of seo.sitemaps) await Bun.write(join(out, file.path), file.xml);
   await Bun.write(join(out, ROBOTS_PATH), seo.robots);
-  return [...seo.sitemaps.map((file) => file.path), ROBOTS_PATH];
+  await Bun.write(join(out, LLMS_PATH), seo.llms);
+  return [...seo.sitemaps.map((file) => file.path), ROBOTS_PATH, LLMS_PATH];
 }