@ultimat3/core 29.3.2 → 30.0.0

package/src/client-paths-pins.ts

@@ -0,0 +1,92 @@
+/**
+ * The pinned URLs (`http: { path, method }`) a server stamps into its document, and the browser's
+ * read of them: `{"a":{"<action>":"<METHOD> <path>"},"q":{"<query>":"<path>"}}` under
+ * `<meta name="ultimate-pins">`. One format, written and read here, so a by-name browser caller
+ * goes where the declaration put the primitive and no browser ref restates the pin.
+ */
+
+import { CLIENT_PINS_META } from './page-meta';
+
+export type PinnedActionMethod = 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+const METHODS: readonly PinnedActionMethod[] = ['POST', 'PUT', 'PATCH', 'DELETE'];
+
+export interface ActionPin {
+  readonly path: string;
+  readonly method: PinnedActionMethod;
+}
+
+/** What a server pins, by registered name: an action's path and verb, a query's path. */
+export interface ClientPins {
+  readonly actions: Readonly<Record<string, ActionPin>>;
+  readonly queries: Readonly<Record<string, string>>;
+}
+
+const sorted = <T>(record: Readonly<Record<string, T>>): [string, T][] =>
+  Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+
+/**
+ * The meta's content, or `undefined` when nothing is pinned — no tag, so an app that pins nothing
+ * renders the bytes it always did. Sorted, so one registry is one byte string whatever its order.
+ */
+export function encodeClientPins(pins: ClientPins): string | undefined {
+  const actions = sorted(pins.actions);
+  const queries = sorted(pins.queries);
+  if (actions.length === 0 && queries.length === 0) return undefined;
+  return JSON.stringify({
+    ...(actions.length === 0
+      ? {}
+      : {
+          a: Object.fromEntries(actions.map(([name, pin]) => [name, `${pin.method} ${pin.path}`])),
+        }),
+    ...(queries.length === 0 ? {} : { q: Object.fromEntries(queries) }),
+  });
+}
+
+/** The last stamp parsed, by its content: a page asks per call, and parses once per document. */
+let parsed: { readonly content: string; readonly table: unknown } | undefined;
+
+/**
+ * `table[kind][name]` of the document's stamp, or `undefined`: no document (a server, a worker),
+ * no stamp (nothing pinned), or content this build cannot read. Only the server writes the tag, so
+ * an unreadable one is a mismatched build — and the derived URL is the one it would have answered.
+ */
+function stamped(kind: 'a' | 'q', name: string): unknown {
+  const doc: { querySelector?: (selector: string) => { content?: unknown } | null } | undefined =
+    Reflect.get(globalThis, 'document');
+  const content = doc?.querySelector?.(`meta[name="${CLIENT_PINS_META}"]`)?.content;
+  if (typeof content !== 'string') return undefined;
+  if (parsed?.content !== content) {
+    let table: unknown;
+    try {
+      table = JSON.parse(content);
+    } catch {
+      table = undefined;
+    }
+    parsed = { content, table };
+  }
+  const section: unknown =
+    typeof parsed.table === 'object' && parsed.table !== null
+      ? Reflect.get(parsed.table, kind)
+      : undefined;
+  if (typeof section !== 'object' || section === null || !Object.hasOwn(section, name)) {
+    return undefined;
+  }
+  return Reflect.get(section, name);
+}
+
+/** The action `name`'s pinned path and verb, as this document's server serves it. */
+export function renderedActionPin(name: string): ActionPin | undefined {
+  const value = stamped('a', name);
+  if (typeof value !== 'string') return undefined;
+  const space = value.indexOf(' ');
+  const method = METHODS.find((known) => known === value.slice(0, space));
+  const path = value.slice(space + 1);
+  return method === undefined || !path.startsWith('/') ? undefined : { path, method };
+}
+
+/** The query `name`'s pinned path, as this document's server serves it. */
+export function renderedQueryPin(name: string): string | undefined {
+  const value = stamped('q', name);
+  return typeof value === 'string' && value.startsWith('/') ? value : undefined;
+}

package/src/client-problem.ts

@@ -76,7 +76,10 @@ export function problemError(
     retry: retryForStatus(code, status, retryAfterSeconds),
     // The server's declared keys FIRST, so the ones this decoder owns win a collision.
     meta: withStatedDelay(
-      { ...serverMeta(body['meta'], body['issues']), origin: 'remote', status, url },
+      withRequestId(
+        { ...serverMeta(body['meta'], body['issues']), origin: 'remote', status, url },
+        body['requestId'],
+      ),
       retryAfterSeconds,
     ),
     ...(docs === undefined ? {} : { docs }),
@@ -100,6 +103,27 @@ export function withStatedDelay(
   return retryAfterSeconds === undefined ? kept : { ...kept, retryAfterSeconds };
 }
 
+/** A longer `requestId` is not an id the server minted, and it would ride into every report. */
+const MAX_REQUEST_ID_LENGTH = 127;
+
+/**
+ * A remote error's `meta` with the document's ROOT `requestId`, and only that: one copied off the
+ * body's `meta` is dropped first, so a key a server declared cannot pose as the id support is
+ * given. Absent unless it is a non-empty string this long at most. The rule for both decoders.
+ */
+export function withRequestId(
+  meta: Readonly<Record<string, unknown>>,
+  requestId: unknown,
+): Record<string, unknown> {
+  // Object rest copies own keys with CreateDataProperty, so a parsed `__proto__` stays a plain key.
+  const { requestId: _fromTheMeta, ...kept } = meta;
+  const carried =
+    typeof requestId === 'string' &&
+    requestId.length > 0 &&
+    requestId.length <= MAX_REQUEST_ID_LENGTH;
+  return carried ? { ...kept, requestId } : kept;
+}
+
 /**
  * WHICH way no usable answer came back, on `meta.failure` — what a caller branches on, since the
  * code is the same for all three: `network` (no response at all — the one an offline outbox

package/src/client-scope.ts

@@ -12,7 +12,7 @@
  */
 
 import type { ScopeCell } from './record-sink';
-import { heldRecords, scopeCell } from './record-sink';
+import { heldRecords, scopeCell, sessionLostCell } from './record-sink';
 
 export interface ClientScope {
   /**
@@ -35,6 +35,8 @@ export function rescope(principal: string | null): void {
   cell.current = next;
   // Held early records belong to the principal that just left; they never reach the next store.
   heldRecords()?.clear();
+  // A new principal has a session of its own: the loss was the previous one's.
+  sessionLostCell().lost = false;
   let failure: { readonly error: unknown } | undefined;
   // A snapshot: a subscriber that unsubscribes (or subscribes) mid-notify changes the NEXT round.
   for (const listener of [...cell.listeners]) {

package/src/client-stream.ts

@@ -0,0 +1,106 @@
+/**
+ * The browser's streamed read of a stream-declaring action: `POST`, `accept: text/event-stream`,
+ * through `client-dispatch.ts`'s `dispatchStream`, never `EventSource` (cannot POST). Each `chunk`
+ * frame yields as it arrives, `done` is the return, `error` throws the problem it carries.
+ */
+
+import type { StreamDispatch } from './client-dispatch';
+import { dispatchStream } from './client-dispatch';
+import { problemError, transportFailed } from './client-problem';
+import { settleAnswer } from './client-transport';
+import { notifyClientWrite } from './client-writes';
+import { RECORDS_HEADER } from './record-envelope';
+import { pageClient } from './record-sink';
+import { DATES_HEADER } from './wire-dates';
+
+/** What `clientStream` reads: a write's request, never a raw body or a flight. */
+export type StreamRequest = StreamDispatch;
+
+interface Frame {
+  readonly event: string;
+  readonly data: string;
+}
+
+/** Splits a growing buffer into complete frames; the incomplete tail is handed back. */
+export function takeFrames(buffer: string): { readonly frames: Frame[]; readonly rest: string } {
+  const frames: Frame[] = [];
+  const blocks = buffer.split(/\r?\n\r?\n/);
+  const rest = blocks.pop() ?? '';
+  for (const block of blocks) {
+    let event = 'message';
+    const data: string[] = [];
+    for (const line of block.split(/\r?\n/)) {
+      // A `:` line is a comment — the server's keep-alive.
+      if (line.startsWith(':')) continue;
+      if (line.startsWith('event:')) event = line.slice(6).trim();
+      else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+    }
+    if (data.length > 0) frames.push({ event, data: data.join('\n') });
+  }
+  return { frames, rest };
+}
+
+export async function* clientStream<TChunk = unknown, TOutput = unknown>(
+  req: StreamRequest,
+): AsyncGenerator<TChunk, TOutput, undefined> {
+  const issued = pageClient().scope.epoch;
+  try {
+    const response = await dispatchStream(req);
+    // A server that answered JSON (no stream declared, or a proxy) gave the whole answer at once —
+    // `call()`'s answer, so it is settled exactly as `call()` settles it.
+    if (!(response.headers.get('content-type') ?? '').startsWith('text/event-stream')) {
+      const answer = {
+        text: await response.text(),
+        enveloped: response.headers.get(RECORDS_HEADER) === '1',
+        dates: response.headers.get(DATES_HEADER),
+      };
+      return settleAnswer(answer, req, false, issued) as TOutput;
+    }
+    const reader = response.body?.getReader();
+    if (reader === undefined)
+      throw transportFailed('body', `${req.url} answered a stream with no body`, undefined, {
+        url: req.url,
+      });
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        buffer += decoder.decode(value, { stream: !done });
+        const taken = takeFrames(done ? `${buffer}\n\n` : buffer);
+        buffer = taken.rest;
+        for (const frame of taken.frames) {
+          if (frame.event === 'chunk') yield JSON.parse(frame.data) as TChunk;
+          else if (frame.event === 'done') return JSON.parse(frame.data) as TOutput;
+          else if (frame.event === 'error') {
+            const status = problemStatus(frame.data);
+            throw (
+              req.decodeError?.(status, frame.data) ?? problemError(status, frame.data, req.url)
+            );
+          }
+        }
+        if (done) break;
+      }
+    } finally {
+      // A consumer that stopped early releases the body: the server sees the disconnect and aborts.
+      await reader.cancel().catch(() => undefined);
+    }
+    throw transportFailed(
+      'body',
+      `${req.url} closed its stream before a done or error frame`,
+      undefined,
+      { url: req.url },
+    );
+  } finally {
+    notifyClientWrite(req.url);
+  }
+}
+
+function problemStatus(text: string): number {
+  try {
+    const status = (JSON.parse(text) as { status?: unknown }).status;
+    return typeof status === 'number' ? status : 500;
+  } catch {
+    return 500;
+  }
+}

package/src/client-transport.ts

@@ -72,14 +72,28 @@ export async function clientTransport<T = unknown>(req: TransportRequest): Promi
   // `rawBody` return, so the overload's `Promise<string>` holds for a raw upload read as text too.
   if (req.responseType === 'text') return answer.text as T;
   if (req.rawBody !== undefined) return undefined as T;
+  return settleAnswer(answer, req, read, issued) as T;
+}
+
+/**
+ * A 2xx JSON answer as its caller's value: the records envelope unwrapped and adopted, the
+ * instants revived. Exported for `clientStream`'s JSON answer, so `stream()` and `call()` of one
+ * action can never hand back two different values.
+ */
+export function settleAnswer(
+  answer: Answer,
+  req: Pick<TransportRequest, 'url' | 'adopt' | 'onEnvelope'>,
+  read: boolean,
+  issued: number,
+): unknown {
   const envelope = unwrap(answer, req.url, read);
   // A write that crossed a rescope HAS landed, so its caller is told — but its rows are the
   // previous principal's, and the new scope's store never sees them.
-  if (current === issued) {
+  if (pageClient().scope.epoch === issued) {
     if (req.adopt !== false) adopt(envelope);
     if (answer.enveloped) req.onEnvelope?.(envelope);
   }
-  return envelope.data as T;
+  return envelope.data;
 }
 
 function unwrap(answer: Answer, url: string, read: boolean): RecordEnvelope {

package/src/config-assets.ts

@@ -0,0 +1,64 @@
+// Single responsibility: the `assets` block of `app.config.ts` — whether a web pod keeps earlier
+// builds' hashed files reachable across a deploy, and on which disk. Its own file for the reason
+// `config-mail.ts` is: shape, merge and screen are one subject, and `config.ts` is at its ceiling.
+
+import { countIssue } from './config-count';
+import { describeValue } from './error-render';
+import { isJsonObject } from './json-object';
+
+/**
+ * A retention window over a disk the web role can read: an S3-compatible bucket, or a volume every
+ * replica mounts. `builds` has NO default — how many deploys an open tab may survive is the app's
+ * decision (axiom 8), and a guessed number is either a bucket that grows or a tab that breaks.
+ */
+export interface AssetsRetainConfig {
+  /** A disk name from the app's `defineStorage({ disks })`, checked against it at boot. */
+  readonly disk: string;
+  /** How many builds' files stay readable, newest first: a whole number of at least 1. */
+  readonly builds: number;
+}
+
+/** `retain` absent is today's behaviour: each process serves only the assets it built. */
+export interface AssetsConfig {
+  readonly retain: AssetsRetainConfig | undefined;
+}
+
+export interface AssetsSection {
+  readonly assets: AssetsConfig;
+}
+
+export interface AssetsSectionInput {
+  readonly assets?: { readonly retain?: AssetsRetainConfig | undefined } | undefined;
+}
+
+/** The last layer that said it wins, as every scalar does; a wrong shape is carried AS WRITTEN. */
+export function mergeAssets(layers: readonly AssetsSectionInput[]): AssetsSection {
+  let retain: AssetsConfig['retain'];
+  for (const layer of layers) {
+    const said = layer.assets?.retain;
+    if (said !== undefined) retain = said;
+  }
+  return { assets: { retain } };
+}
+
+/** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
+export function assetsIssues(
+  config: { readonly assets?: AssetsConfig | undefined },
+  issues: string[],
+): void {
+  // `unknown`: an untyped config file reaches this validator with whatever it wrote.
+  const retain: unknown = config.assets?.retain;
+  if (retain === undefined) return;
+  if (!isJsonObject(retain)) {
+    issues.push(`assets.retain must be { disk, builds }, not ${describeValue(retain)}`);
+    return;
+  }
+  const disk: unknown = retain['disk'];
+  if (typeof disk !== 'string' || disk.trim() === '') {
+    issues.push(
+      `assets.retain.disk must name a disk declared with defineStorage, not ${describeValue(disk)}`,
+    );
+  }
+  const builds = countIssue('assets.retain.builds', retain['builds'], 1);
+  if (builds !== undefined) issues.push(builds);
+}

package/src/config-client-errors.ts

@@ -0,0 +1,132 @@
+// Single responsibility: the `clientErrors` block of `app.config.ts` — whether `app/` documents
+// carry the browser reporter (`@ultimat3/cli`'s `/x-client-errors.js`), who may file through it,
+// and whether documents beacon real-user timings (`vitals`) through the same door. Shape, merge and
+// screen are one subject, and `config.ts` is at its 500-line ceiling.
+
+import { countIssue } from './config-count';
+import { booleanIssue, oneOfIssue } from './config-shape';
+import { describeValue } from './error-render';
+
+/** The surfaces a document is rendered for. `site/` is listed by choice: a beacon costs it bytes. */
+export const CLIENT_VITALS_SURFACES = ['app', 'site'] as const;
+
+export type ClientVitalsSurface = (typeof CLIENT_VITALS_SURFACES)[number];
+
+/**
+ * OFF BY DEFAULT, and anonymous: a timing carries no actor, so it needs no sign-in and lands as a
+ * histogram sample (`web_vital_seconds`, `web_vital_cls`), never a row. `sampleRate` is the share
+ * of page views that beacon — decided once per view, in the browser. `surfaces` defaults to
+ * `app/` alone: `site/` is the static path, and it pays for the script only when it is listed.
+ */
+export interface ClientVitalsConfig {
+  readonly enabled: boolean;
+  readonly sampleRate: number;
+  readonly surfaces: readonly ClientVitalsSurface[];
+}
+
+/**
+ * OFF BY DEFAULT: a new public write route is the app's decision, as `pwa.push` is. `anonymous`
+ * is refused by default too — crash text is input to whoever reads the monitor, and an open door
+ * lets anyone write there. `perMinute` is the route's own bucket, per actor or, for an anonymous
+ * caller, per address, spent through the app's rate-limit store.
+ */
+export interface ClientErrorsConfig {
+  readonly enabled: boolean;
+  readonly anonymous: boolean;
+  readonly perMinute: number;
+  readonly vitals: ClientVitalsConfig;
+}
+
+export const CLIENT_VITALS_DEFAULTS: ClientVitalsConfig = Object.freeze({
+  enabled: false,
+  sampleRate: 0.1,
+  surfaces: Object.freeze(['app'] as const),
+});
+
+export const CLIENT_ERRORS_DEFAULTS: ClientErrorsConfig = Object.freeze({
+  enabled: false,
+  anonymous: false,
+  perMinute: 30,
+  vitals: CLIENT_VITALS_DEFAULTS,
+});
+
+export interface ClientErrorsSection {
+  readonly clientErrors: ClientErrorsConfig;
+}
+
+export interface ClientErrorsSectionInput {
+  readonly clientErrors?:
+    | {
+        readonly enabled?: boolean | undefined;
+        readonly anonymous?: boolean | undefined;
+        readonly perMinute?: number | undefined;
+        readonly vitals?:
+          | {
+              readonly enabled?: boolean | undefined;
+              readonly sampleRate?: number | undefined;
+              readonly surfaces?: readonly ClientVitalsSurface[] | undefined;
+            }
+          | undefined;
+      }
+    | undefined;
+}
+
+/** Key by key, the last layer that said one wins it — every section's rule. */
+export function mergeClientErrors(
+  layers: readonly ClientErrorsSectionInput[],
+): ClientErrorsSection {
+  let { enabled, anonymous, perMinute } = CLIENT_ERRORS_DEFAULTS;
+  let vitals: ClientVitalsConfig = CLIENT_VITALS_DEFAULTS;
+  for (const layer of layers) {
+    const said = layer.clientErrors;
+    if (said?.enabled !== undefined) enabled = said.enabled;
+    if (said?.anonymous !== undefined) anonymous = said.anonymous;
+    if (said?.perMinute !== undefined) perMinute = said.perMinute;
+    // One level further, by the same rule: an overlay naming `surfaces` keeps the base's rate.
+    const timings = said?.vitals;
+    if (timings?.enabled !== undefined) vitals = { ...vitals, enabled: timings.enabled };
+    if (timings?.sampleRate !== undefined) vitals = { ...vitals, sampleRate: timings.sampleRate };
+    if (timings?.surfaces !== undefined) vitals = { ...vitals, surfaces: timings.surfaces };
+  }
+  return { clientErrors: { enabled, anonymous, perMinute, vitals } };
+}
+
+/** A share of page views: a finite number in 0–1. `0` is legal — sampled out, still declared. */
+function rateIssue(key: string, value: unknown): string | undefined {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1) {
+    return undefined;
+  }
+  const shown = typeof value === 'number' ? `${value}` : describeValue(value);
+  return `${key} must be a number from 0 to 1 (the share of page views that report), not ${shown}`;
+}
+
+/** At least one listed surface: an empty list is `enabled: false` spelled a second way. */
+function surfacesIssues(key: string, value: unknown, issues: string[]): void {
+  if (!Array.isArray(value) || value.length === 0) {
+    issues.push(`${key} must list at least one of ${CLIENT_VITALS_SURFACES.join(', ')}`);
+    return;
+  }
+  for (const surface of value) {
+    const issue = oneOfIssue(key, surface, CLIENT_VITALS_SURFACES);
+    if (issue !== undefined) issues.push(issue);
+  }
+}
+
+/** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
+export function clientErrorsIssues(config: ClientErrorsSection, issues: string[]): void {
+  // `unknown`: an untyped config file reaches this validator with whatever it wrote.
+  const block: Readonly<Record<keyof ClientErrorsConfig, unknown>> = config.clientErrors;
+  const vitals: Readonly<Record<keyof ClientVitalsConfig, unknown>> = config.clientErrors.vitals;
+  for (const issue of [
+    booleanIssue('clientErrors.enabled', block.enabled),
+    booleanIssue('clientErrors.anonymous', block.anonymous),
+    // Zero is refused, not read as "off": a bucket of nothing refuses every report, and `enabled`
+    // is the switch that says off.
+    countIssue('clientErrors.perMinute', block.perMinute, 1),
+    booleanIssue('clientErrors.vitals.enabled', vitals.enabled),
+    rateIssue('clientErrors.vitals.sampleRate', vitals.sampleRate),
+  ]) {
+    if (issue !== undefined) issues.push(issue);
+  }
+  surfacesIssues('clientErrors.vitals.surfaces', vitals.surfaces, issues);
+}

package/src/config-defaults.ts

@@ -8,12 +8,25 @@ import {
   JOBS_DONE_RETENTION_MS_DEFAULT,
   JOBS_OUTBOX_RETENTION_MS_DEFAULT,
 } from './config-jobs';
-import { DRAIN_DEADLINE_DEFAULT_MS } from './drain-deadline';
+import { DRAIN_DEADLINE_DEFAULT_MS, WORKER_RETIRE_DEFAULT_MS } from './drain-deadline';
 import { defaultReadinessGraceMs } from './lifecycle-grace';
 import { ROLES } from './roles';
 
-/** The keys their own files default: `config-site.ts`, `-navigation`, `-islands`, `-mail`. */
-type Sectioned = 'name' | 'site' | 'seo' | 'navigation' | 'islands' | 'mail';
+/**
+ * The keys their own files default: `config-site.ts`, `-navigation`, `-islands`, `-mail`,
+ * `-client-errors`, `-assets`, `-failure-capture`, `-time`.
+ */
+type Sectioned =
+  | 'name'
+  | 'site'
+  | 'seo'
+  | 'navigation'
+  | 'islands'
+  | 'mail'
+  | 'clientErrors'
+  | 'failureCapture'
+  | 'time'
+  | 'assets';
 
 export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
   return {
@@ -28,7 +41,7 @@ export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
       colors: undefined,
     },
     roles: [...ROLES],
-    database: { driver: 'postgres', ssl: false },
+    database: { driver: 'postgres', ssl: false, rowSecurity: false },
     cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
     jobs: {
       queues: [`${name}-default`],
@@ -60,6 +73,7 @@ export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
       deadlineMs: DRAIN_DEADLINE_DEFAULT_MS,
       // Unset: the worker drains on `deadlineMs`, like every role.
       workerDeadlineMs: undefined,
+      workerRetireMs: WORKER_RETIRE_DEFAULT_MS,
     },
     health: { readiness: 'dependencies' },
   };

package/src/config-failure-capture.ts

@@ -0,0 +1,70 @@
+// Single responsibility: the `failureCapture` block of `app.config.ts` — whether a 5xx at `invoke`
+// keeps a replayable bundle (input, actor, flags, the rows the code read) for `x repro`, and how
+// much of one. Shape, merge and screen are one subject, and `config.ts` is at its line ceiling.
+
+import { countIssue } from './config-count';
+import { booleanIssue } from './config-shape';
+
+/**
+ * OFF BY DEFAULT: storing what a user sent is the app's decision, as `clientErrors` is. `x dev`
+ * turns it on for its own process. `perHour` bounds bundles per fingerprint per hour, per process;
+ * `maxRows` and `maxBytes` bound one bundle — past either it is stored truncated, and says so.
+ */
+export interface FailureCaptureConfig {
+  readonly enabled: boolean;
+  readonly perHour: number;
+  readonly maxRows: number;
+  readonly maxBytes: number;
+}
+
+export const FAILURE_CAPTURE_DEFAULTS: FailureCaptureConfig = Object.freeze({
+  enabled: false,
+  perHour: 5,
+  maxRows: 50,
+  maxBytes: 64 * 1024,
+});
+
+export interface FailureCaptureSection {
+  readonly failureCapture: FailureCaptureConfig;
+}
+
+export interface FailureCaptureSectionInput {
+  readonly failureCapture?:
+    | {
+        readonly enabled?: boolean | undefined;
+        readonly perHour?: number | undefined;
+        readonly maxRows?: number | undefined;
+        readonly maxBytes?: number | undefined;
+      }
+    | undefined;
+}
+
+/** Key by key, the last layer that said one wins it — every section's rule. */
+export function mergeFailureCapture(
+  layers: readonly FailureCaptureSectionInput[],
+): FailureCaptureSection {
+  let { enabled, perHour, maxRows, maxBytes } = FAILURE_CAPTURE_DEFAULTS;
+  for (const layer of layers) {
+    const said = layer.failureCapture;
+    if (said?.enabled !== undefined) enabled = said.enabled;
+    if (said?.perHour !== undefined) perHour = said.perHour;
+    if (said?.maxRows !== undefined) maxRows = said.maxRows;
+    if (said?.maxBytes !== undefined) maxBytes = said.maxBytes;
+  }
+  return { failureCapture: { enabled, perHour, maxRows, maxBytes } };
+}
+
+/** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
+export function failureCaptureIssues(config: FailureCaptureSection, issues: string[]): void {
+  // `unknown`: an untyped config file reaches this validator with whatever it wrote.
+  const block: Readonly<Record<keyof FailureCaptureConfig, unknown>> = config.failureCapture;
+  // Zero is refused, not read as "off": `enabled` is the switch that says off.
+  for (const issue of [
+    booleanIssue('failureCapture.enabled', block.enabled),
+    countIssue('failureCapture.perHour', block.perHour, 1),
+    countIssue('failureCapture.maxRows', block.maxRows, 1),
+    countIssue('failureCapture.maxBytes', block.maxBytes, 1),
+  ]) {
+    if (issue !== undefined) issues.push(issue);
+  }
+}

package/src/config-health.ts

@@ -51,6 +51,14 @@ export interface DrainConfig {
    * `deadlineMs`. A whole number, 1–86400000. The chart's worker grace period is derived from it.
    */
   readonly workerDeadlineMs: number | undefined;
+  /**
+   * How long a retiring worker may finish what it holds on a Kubernetes rollout or scale-down:
+   * claim nothing, abort nothing, exit when the last job settles. Not `workerDeadlineMs`, which
+   * bounds a SIGTERM drain and then aborts. An idle worker exits at once, so it costs only while a
+   * job holds the pod. Default 3600000; 0 turns it off. A whole number, 0–86400000. `x deploy
+   * --method helm` hands it to the chart, whose worker `preStop` and grace period are sized from it.
+   */
+  readonly workerRetireMs: number;
 }
 
 /** Why a value is not a readiness mode, or `undefined` when it is one. */

package/src/config-islands.ts

@@ -11,7 +11,7 @@ import { describeValue } from './error-render';
  * reason is measured rather than cautious: tree shaking across one split build keeps whatever ANY
  * importer uses, so an island that imports one helper from a module other islands use heavily
  * pays for all of it. `examples/dummy`'s plain-DOM update banner went 712 → 16,288 B with it on;
- * notificado.co's `/afiliados` with two upload islands went 55,585 → 42,331 B. Turn it on where a
+ * one adopter's `/afiliados` with two upload islands went 55,585 → 42,331 B. Turn it on where a
  * surface's pages render many islands over one graph, and weigh the routes with `x verify`.
  */
 export interface IslandsConfig {

package/src/config-keys.ts

@@ -3,6 +3,7 @@
 // is merged and read by nothing is the switch with no wire, and a typo (`drian`) is the same defect.
 
 import type { JobsConfig } from './config';
+import type { AssetsRetainConfig } from './config-assets';
 import { BASE_FIX } from './config-fixes';
 import type { MailRetainMimeConfig } from './config-mail';
 import type { NavigationConfig, SpeculationConfig } from './config-navigation';
@@ -62,6 +63,7 @@ export const SECTION_KEYS: Readonly<Record<string, readonly string[]>> = Object.
   'pwa.shortcuts[].icons[]': keysOf<PwaImage>()(['src', 'sizes', 'type', 'purpose']),
   'pwa.screenshots[]': keysOf<PwaScreenshot>()(['src', 'sizes', 'type', 'formFactor', 'label']),
   'mail.retainMime': keysOf<MailRetainMimeConfig>()(['maxBytes']),
+  'assets.retain': keysOf<AssetsRetainConfig>()(['disk', 'builds']),
   jobs: keysOf<JobsConfig>()([
     'queues',
     'concurrency',