@ultimat3/core 29.4.0 → 30.1.0

package/src/config-site.ts

@@ -90,12 +90,19 @@ export interface SeoSitemapConfig {
 export interface SeoConfig {
   readonly robots: SeoRobotsConfig;
   readonly sitemap: SeoSitemapConfig;
+  /**
+   * `/llms.txt`: the `site/` pages' titles and descriptions for a language model. On by default,
+   * like the sitemap, over the same indexable pages; `false` serves an empty document and lifts the
+   * `seo` step's description rule (`X_SEO_LLMS_DESCRIPTION_MISSING`). Optional in the TYPE only.
+   */
+  readonly llms?: boolean | undefined;
 }
 
 /** `robots` is NESTED for `AiConfigInput`'s reason: `section` applies a patch one level deep. */
 export interface SeoConfigInput {
   readonly robots?: Input<SeoRobotsConfig> | undefined;
   readonly sitemap?: Input<SeoSitemapConfig> | undefined;
+  readonly llms?: boolean | undefined;
 }
 
 export interface SiteSections {
@@ -124,6 +131,11 @@ export function mergeSite(layers: readonly SiteSectionsInput[]): SiteSections {
         { extra: [], lastmod: 'none', sections: [], pageSize: SITEMAP_PAGE_SIZE_MAX },
         layers.map((layer) => layer.seo?.sitemap),
       ),
+      // The last layer that says, else on.
+      llms: layers.reduce<boolean>(
+        (on, layer) => (layer.seo?.llms === undefined ? on : layer.seo.llms),
+        true,
+      ),
     },
   };
 }
@@ -196,4 +208,8 @@ export function siteIssues(config: SiteSections, issues: string[]): void {
     );
   }
   issues.push(...sitemapSectionIssues(config.seo.sitemap.sections, config.seo.sitemap.pageSize));
+  const llms: unknown = config.seo.llms;
+  if (llms !== undefined && typeof llms !== 'boolean') {
+    issues.push(`seo.llms must be true or false, not ${describeValue(llms)}`);
+  }
 }

package/src/config-time.ts

@@ -0,0 +1,40 @@
+// Single responsibility: the `time` block of `app.config.ts` — whether `app/` documents carry the
+// zone script that tells the next request the visitor's zone. No default zone lives here, ever:
+// every format call names its zone. Shape, merge and screen are one subject; `config.ts` is full.
+
+import { booleanIssue } from './config-shape';
+
+/**
+ * OFF BY DEFAULT: `detect` writes a cookie (`x_timezone_detected`) on every `app/` document, and a
+ * cookie is the app's decision. On, a visitor's second page renders in their zone with no picker.
+ */
+export interface AppTimeConfig {
+  readonly detect: boolean;
+}
+
+export const TIME_DEFAULTS: AppTimeConfig = Object.freeze({ detect: false });
+
+export interface TimeSection {
+  readonly time: AppTimeConfig;
+}
+
+export interface TimeSectionInput {
+  readonly time?: { readonly detect?: boolean | undefined } | undefined;
+}
+
+/** The last layer that said `detect` wins it — every section's rule. */
+export function mergeTime(layers: readonly TimeSectionInput[]): TimeSection {
+  let { detect } = TIME_DEFAULTS;
+  for (const layer of layers) {
+    if (layer.time?.detect !== undefined) detect = layer.time.detect;
+  }
+  return { time: { detect } };
+}
+
+/** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
+export function timeIssues(config: TimeSection, issues: string[]): void {
+  // `unknown`: an untyped config file reaches this validator with whatever it wrote.
+  const detect: unknown = config.time.detect;
+  const issue = booleanIssue('time.detect', detect);
+  if (issue !== undefined) issues.push(issue);
+}

package/src/config.ts

@@ -7,8 +7,11 @@
 // drift into two vocabularies with no map between them (issue #293).
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 import type { AiConfig, AiConfigInput } from './config-ai';
+import * as assetsSection from './config-assets';
+import * as clientErrors from './config-client-errors';
 import { countIssue } from './config-count';
 import { configDefaults } from './config-defaults';
+import * as failureCapture from './config-failure-capture';
 import { BASE_FIX, CACHE_TIER_FIX } from './config-fixes';
 import { type DrainConfig, type HealthConfig, readinessModeIssue } from './config-health';
 import type { IslandsConfig, IslandsSectionInput } from './config-islands';
@@ -31,6 +34,7 @@ import {
 } from './config-shape';
 import type { SeoConfig, SiteConfig, SiteSectionsInput } from './config-site';
 import { mergeSite, siteIssues } from './config-site';
+import * as timeSection from './config-time';
 import { drainIssues } from './drain-deadline';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
@@ -102,21 +106,20 @@ export interface NotifyConfig {
 export const INBOX_RETENTION_KEYS = ['inboxReadRetentionMs', 'inboxUnreadRetentionMs'] as const;
 /**
  * Deliberately thin. `urlEnv`, `poolSize` and `schema` were removed 2026-08 because **nothing
- * read them** — the only reader of any `config.database.*` field in the repo was this file's own
- * validator, and each of the three was unfixable where it sat:
- *
- * `poolSize` was a dead second spelling of `DATABASE_POOL_MAX`; `client.ts` reads `DATABASE_URL`
- * as a literal, so no `urlEnv` could be honoured; nothing emits `SET search_path` for `schema`.
- *
- * Wiring them instead would need a tier-0 → tier-1 read the tier table forbids. Deleting is axiom
- * 3 applied to configuration: a value that produces neither a build error nor a runtime effect is
- * worse than no field, because an SRE sets `poolSize: 3`, redeploys, and nothing changes.
+ * read them**: `poolSize` was a dead second spelling of `DATABASE_POOL_MAX`, `client.ts` reads
+ * `DATABASE_URL` as a literal, and nothing emits `SET search_path`. A value that produces neither
+ * a build error nor a runtime effect is worse than no field (axiom 3).
  */
 const DATABASE_DRIVERS = ['postgres'] as const;
 
 export interface DatabaseConfig {
   readonly driver: (typeof DATABASE_DRIVERS)[number];
   readonly ssl: boolean;
+  /**
+   * Every `tenant:` table carries a forced policy (`x db gen`) the serving role must be subject to
+   * (`X_DB_ROW_SECURITY_BYPASSED`). Off by default: a transaction per bare statement is not free.
+   */
+  readonly rowSecurity: boolean;
 }
 
 /**
@@ -182,16 +185,10 @@ export interface JobsConfig {
 }
 
 /**
- * No `heartbeatMs`. It was declared here, defaulted to 15_000, and read by NOTHING — deleted
- * 2026-08-19. The socket beat is `new LiveClient({ heartbeatMs })`, browser code that cannot read
- * server config, and the presence beat is DERIVED (`PresenceRegistry.heartbeatMs` is
- * `max(1000, floor(ttlMs / 3))`). A second knob is a second number that can disagree with the one
- * it is a fraction of, and a knob nothing reads is a knob nothing enforces — axioms 1 and 3.
- *
- * No `tier` either (deleted 2026-08-23): no file read it, so `tier: 'local-first'` bought nothing.
- * An app's realtime tier is what it DECLARES — a `channel()` topic, a `live: true` query, a local
- * store — never a config key. `transport`, `urlEnv` and the two per-actor caps (read by the `sync`
- * role into its registry and node) are the fields code reads.
+ * No `heartbeatMs` (deleted 2026-08-19) and no `tier` (deleted 2026-08-23): read by nothing. The
+ * socket beat is `new LiveClient({ heartbeatMs })`, the presence beat is derived, and an app's
+ * realtime tier is what it DECLARES (a `channel()`, a `live: true` query) — never a config key.
+ * `transport`, `urlEnv` and the two per-actor caps are the fields code reads.
  */
 export interface RealtimeConfig {
   readonly enabled: boolean;
@@ -229,6 +226,10 @@ export interface AppConfig {
   readonly navigation: NavigationConfig;
   readonly islands: IslandsConfig;
   readonly mail: MailConfig;
+  readonly assets: assetsSection.AssetsConfig;
+  readonly clientErrors: clientErrors.ClientErrorsConfig;
+  readonly failureCapture: failureCapture.FailureCaptureConfig;
+  readonly time: timeSection.AppTimeConfig;
 }
 
 /**
@@ -246,7 +247,11 @@ export interface AppConfigInput
   extends SiteSectionsInput,
     NavigationSectionInput,
     IslandsSectionInput,
-    MailSectionInput {
+    MailSectionInput,
+    assetsSection.AssetsSectionInput,
+    clientErrors.ClientErrorsSectionInput,
+    failureCapture.FailureCaptureSectionInput,
+    timeSection.TimeSectionInput {
   readonly name: string;
   readonly theme?: Input<ThemeConfig> | undefined;
   readonly auth?: Input<AuthConfig> | undefined;
@@ -300,6 +305,7 @@ function validate(config: AppConfig): void {
     countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
     oneOfIssue('database.driver', config.database.driver, DATABASE_DRIVERS),
     booleanIssue('database.ssl', config.database.ssl),
+    booleanIssue('database.rowSecurity', config.database.rowSecurity),
     oneOfIssue('theme.defaultMode', config.theme.defaultMode, THEME_MODES),
     // `null` is the documented "no redirect"; a path that is said must be one a browser can follow.
     config.auth.signInPath === null
@@ -321,12 +327,9 @@ function validate(config: AppConfig): void {
   if (config.realtime.transport === 'nats' && config.realtime.urlEnv === undefined) {
     issues.push(`realtime.transport "nats" requires realtime.urlEnv`);
   }
-  // BOTH RETENTION WINDOWS OR NEITHER — `undefined` is a real value here (never swept) and the
-  // only other legal one is a positive, finite count of milliseconds. Zero is refused rather than
-  // read as "immediately": a sweep at age 0 deletes every row the instant it is written, which is
-  // an inbox that silently receives nothing, and nobody types it on purpose. `describeValue`
-  // rather than `${…}`: this validator is the boundary a JS app's untyped config crosses, so the
-  // value here is `unknown` in practice however the interface types it.
+  // `undefined` (never swept) or a positive, finite count of ms. Zero is refused, never read as
+  // "immediately": a sweep at age 0 is an inbox that silently receives nothing. `describeValue`:
+  // this is the boundary a JS app's untyped config crosses, so the value is `unknown` in practice.
   for (const key of INBOX_RETENTION_KEYS) {
     const ms: unknown = config.notify[key];
     if (ms === undefined) continue;
@@ -345,6 +348,10 @@ function validate(config: AppConfig): void {
   navigationIssues(config, issues);
   islandsIssues(config, issues);
   mailIssues(config, issues);
+  assetsSection.assetsIssues(config, issues);
+  clientErrors.clientErrorsIssues(config, issues);
+  failureCapture.failureCaptureIssues(config, issues);
+  timeSection.timeIssues(config, issues);
 
   // A rung the ladder cannot build is the defect this key had: `sortTiers` places a name by its
   // index in `CACHE_TIERS`, and a name missing from it sorts to `-1` — AHEAD of the request memo.
@@ -441,6 +448,10 @@ function merge(name: string, layers: readonly AppConfigOverlay[]): AppConfig {
     ...mergeNavigation(layers),
     ...mergeIslands(layers),
     ...mergeMail(layers),
+    ...assetsSection.mergeAssets(layers),
+    ...clientErrors.mergeClientErrors(layers),
+    ...failureCapture.mergeFailureCapture(layers),
+    ...timeSection.mergeTime(layers),
   };
 }
 

package/src/context.ts

@@ -34,7 +34,7 @@ import { type Actor, anonymousActor } from './actor';
 import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
 import { DEFAULT_LOCALE, DEFAULT_TIME_ZONE } from './default-locale';
-import { UltimateError } from './errors';
+import { isUltimateError, UltimateError } from './errors';
 import { finiteOption } from './finite-option';
 import { traceId as newTraceId, uuidV7 } from './ids';
 import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
@@ -214,6 +214,13 @@ export function ctxOf(init: CtxInit = {}): Ctx {
   return Object.freeze(ctx);
 }
 
+/** What bounds a `runToCompletion` scope, when its caller owns a ceiling. */
+export interface CompletionBound {
+  readonly signal?: AbortSignal | undefined;
+  /** Epoch ms: what an outbound hop forwards as the budget left. */
+  readonly deadlineAt?: number | undefined;
+}
+
 export function runWithContext<T>(ctx: Ctx, fn: () => T): T {
   // A request scope is what gives an outbound typed call a budget to forward; see the module.
   installTraceHeaders();
@@ -288,6 +295,27 @@ function composeSignal(parent: AbortSignal, patch: AbortSignal | undefined): Abo
  */
 export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
   const parent = useContext();
+  const child = derivedContext(parent, patch, {
+    // One request, one budget: a child scope inherits the deadline for the same reason it
+    // inherits `requestId`. A patch may SHORTEN it (a step with its own budget); nothing here
+    // lengthens it, because the socket the parent is answering does not move. `??` alone said
+    // that and did not do it — a patched hour replaced a parent's second outright, and
+    // `remainingBudgetMs` then put the hour on `x-request-timeout-ms` for the next hop.
+    deadlineAt: earliest(screenDeadline(patch.deadlineAt) ?? undefined, parent.deadlineAt),
+    signal: composeSignal(parent.signal, patch.signal),
+  });
+  return requestContext.run(child, fn);
+}
+
+/**
+ * The one build of a child context, narrowing (`withChildContext`) or not (`runToCompletion`): the
+ * caller decides the two members that say how long this work may run, everything else is the rule.
+ */
+function derivedContext(
+  parent: Ctx,
+  patch: CtxPatch,
+  lifetime: { readonly deadlineAt: number | undefined; readonly signal: AbortSignal },
+): Ctx {
   // A factory-managed service was built for the PARENT's actor; forwarding it verbatim into an
   // impersonated child would answer every call with the parent's tenant. `ctxOf` below
   // rebuilds every registered factory fresh against the child's own actor, so only services no
@@ -295,7 +323,7 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
   const carried = Object.fromEntries(
     Object.entries(parent.services).filter(([name]) => !isManagedService(name)),
   );
-  const child = ctxOf({
+  return ctxOf({
     requestId: parent.requestId,
     traceId: patch.traceId ?? parent.traceId,
     actor: patch.actor ?? parent.actor,
@@ -305,18 +333,72 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     role: patch.role ?? parent.role,
     clock: patch.clock ?? parent.clock,
     logger: patch.logger ?? parent.logger,
-    // One request, one budget: a child scope inherits the deadline for the same reason it
-    // inherits `requestId`. A patch may SHORTEN it (a step with its own budget); nothing here
-    // lengthens it, because the socket the parent is answering does not move. `??` alone said
-    // that and did not do it — a patched hour replaced a parent's second outright, and
-    // `remainingBudgetMs` then put the hour on `x-request-timeout-ms` for the next hop.
-    deadlineAt: earliest(screenDeadline(patch.deadlineAt) ?? undefined, parent.deadlineAt),
-    signal: composeSignal(parent.signal, patch.signal),
+    deadlineAt: lifetime.deadlineAt,
+    signal: lifetime.signal,
     services: { ...carried, ...(patch.services ?? {}) },
   });
+}
+
+/**
+ * Why this scope's work no longer belongs to anyone: the ambient signal's reason, when it was
+ * aborted with a CODED one, the same object. Coded means somebody was answered (`X_TIMEOUT`) or
+ * another attempt owns the run (a job's `X_ABORTED`, `X_DRAINING`, `X_JOB_TIMEOUT`,
+ * `X_JOB_SLOT_LOST`, `X_JOB_LEASE_LOST`), so a write landing now lands behind their back. A client
+ * hang-up is Bun's uncoded `AbortError`: nobody was told anything, and a click followed by a
+ * navigation must keep landing, so it answers `undefined`.
+ */
+export function abandonment(): UltimateError | undefined {
+  const signal = tryUseContext()?.signal;
+  if (signal?.aborted !== true) return undefined;
+  return isUltimateError(signal.reason) ? signal.reason : undefined;
+}
+
+/**
+ * Run `fn` to its end whatever happens to the scope around it: a FRESH signal nothing aborts and no
+ * deadline, same request id and actor, managed services rebuilt over it. The one escape from
+ * `abandonment()`, which then has no special case; `retry()` and `outbound()` inside keep working,
+ * and both honour a `bound`'s signal and deadline as they do the request's.
+ * Unbounded by default, and work left hanging holds its slot for good: a caller owning work it cannot
+ * trust passes `bound` (`withIdempotency`'s `ceilingMs`, `onSettled`'s timeout), whose coded abort is
+ * abandonment again. Inside an open transaction wrap the whole `withTransaction`: its COMMIT is
+ * outside an inner scope, and refused. Outside a context it just runs `fn`.
+ */
+export function runToCompletion<T>(fn: () => T, bound: CompletionBound = {}): T {
+  const parent = tryUseContext();
+  if (parent === undefined) return fn();
+  const child = completionScope(parent, {
+    deadlineAt: screenDeadline(bound.deadlineAt) ?? undefined,
+    signal: bound.signal ?? new AbortController().signal,
+  });
   return requestContext.run(child, fn);
 }
 
+/**
+ * The lifetime a frozen `ctxOf` child can hold. A context that is not frozen is wider than core can
+ * name (`@ultimat3/http`'s request, a tier above): a rebuilt one drops its fields, and a copy would
+ * lose a slot written inside (`setRedirect`'s, read back on the original). So it is forwarded, and
+ * only the lifetime and what closed over it read differently: the same object, a fresh signal.
+ */
+function completionScope(
+  parent: Ctx,
+  lifetime: { readonly deadlineAt: number | undefined; readonly signal: AbortSignal },
+): Ctx {
+  const child = derivedContext(parent, {}, lifetime);
+  if (Object.isFrozen(parent)) return child;
+  const fresh = new Map<string | symbol, unknown>([
+    ['signal', child.signal],
+    ['deadlineAt', child.deadlineAt],
+    ['services', child.services],
+  ]);
+  for (const name of Object.keys(child.services)) {
+    // Only what IS the service today: a service named `url` never shadows the request's own.
+    if (parent[name] === parent.services[name]) fresh.set(name, child.services[name]);
+  }
+  return new Proxy(parent, {
+    get: (target, key) => (fresh.has(key) ? fresh.get(key) : Reflect.get(target, key)),
+  });
+}
+
 /** Resolve a late-bound service. Throws `X_SERVICE_MISSING` rather than returning undefined. */
 export function useService<T>(name: string): T {
   const ctx = useContext();
@@ -341,7 +423,7 @@ export function throwIfAborted(ctx: Ctx = useContext()): void {
   throw new UltimateError({
     code: 'X_ABORTED',
     cause: `request ${ctx.requestId} was aborted by the caller`,
-    fix: 'add throwIfAborted(ctx) before expensive work, or pass fetch(url, { signal: ctx.signal }) — the caller is gone, so unwind instead of finishing',
+    fix: 'add throwIfAborted(ctx) before expensive work, and make each vendor call with outbound({ url, vendor, dial, deadlineMs }) from @ultimat3/core/outbound, which hears ctx.signal — the caller is gone, so unwind instead of finishing',
     meta: { requestId: ctx.requestId },
   });
 }

package/src/core-error-codes.ts

@@ -72,6 +72,25 @@ const CORE_CODE_TITLES = {
   X_UNREACHABLE: 'unreachable branch was reached',
   X_SECRETS_KEY_ACL_FAILED: 'key file ACL not owner-only',
   X_COOKIE_INVALID: 'a Set-Cookie value would be dropped, misread or injectable',
+  X_OUTBOUND_TIMEOUT: 'an outbound HTTP call passed its deadline or went idle',
+  X_OUTBOUND_UNREACHABLE: 'an outbound HTTP call got no response',
+  X_OUTBOUND_THROTTLED: 'an outbound HTTP call was told to wait',
+  X_OUTBOUND_UNAVAILABLE: 'an outbound HTTP call answered a retryable status',
+  X_OUTBOUND_REFUSED: 'an outbound HTTP call answered a non-retryable status',
+  X_OUTBOUND_TOO_LARGE: 'an outbound HTTP response body passed its byte cap',
+  X_OUTBOUND_HOST_BLOCKED: 'an outbound HTTP call refused the address it would reach',
+  X_OUTBOUND_REDIRECTED: 'an outbound HTTP call answered a redirect',
+  X_OUTBOUND_RETRY_UNSAFE: 'a retry was asked for on a write that is not idempotent',
+  X_OUTBOUND_BODY_INVALID: 'an outbound HTTP response did not match its schema',
+  X_BREAKER_OPEN: 'a circuit breaker is open and refused the call',
+  X_ERROR_DECLARATION_INVALID: 'a defineError declaration is malformed',
+  X_CLIENT_ERROR: 'a browser reported an uncaught failure',
+  X_HTTP_PATH_INPUT_CONFLICT:
+    'a path parameter and the request body or query name one key with two values',
+  X_ERROR_UNDECLARED: 'a handler threw a 4xx code its errors: list does not declare',
+  X_ACTION_ERRORS_INVALID: 'an errors: list names a code that cannot be declared there',
+  X_CONTRACT_EXERCISE_ENVIRONMENT: 'a contract exercise was asked to run in a deployed environment',
+  X_CONTRACT_EXERCISE_UNSCOPED: 'a contract exercise could not roll back its writes',
 } as const;
 
 export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;

package/src/cursor.ts

@@ -8,6 +8,7 @@
 // a silently wrong page. It is tamper-evidence, not authorization: policy still runs per page.
 
 import { UltimateError } from './errors';
+import { hmac } from './hmac';
 
 export interface CursorPayload {
   /** What this cursor belongs to: one read plus its arguments. A cursor is not portable. */
@@ -45,8 +46,11 @@ export const DEV_CURSOR_SECRET = 'ultimate-dev-cursor-secret';
  */
 export const CURSOR_SECRET_KEY = 'ULTIMATE_CURSOR_SECRET';
 
-/** The one fix for `X_CURSOR_SECRET_DEV`, wherever it is reported — the boot and the CLI. */
-export const CURSOR_SECRET_FIX = `export ${CURSOR_SECRET_KEY}="$(openssl rand -hex 32)"`;
+/**
+ * The one fix for `X_CURSOR_SECRET_DEV`, wherever it is reported — the boot and the CLI. No
+ * `export`: it is gone on an agent's next shell call, and it never reaches a deployed process.
+ */
+export const CURSOR_SECRET_FIX = `openssl rand -hex 32   # put the output in this deploy's secret store as ${CURSOR_SECRET_KEY}; this machine: ULTIMATE_ENV=development x env check`;
 
 /** `configureCursorSigning`'s value, when an app has called it. `undefined` means "read the env". */
 let configured: string | undefined;
@@ -132,7 +136,7 @@ export function decodeCursor(cursor: string, scope: string): CursorPayload {
 
 /** Truncated HMAC-SHA256. 128 bits is far past forging a page position. */
 function sign(body: string): string {
-  return new Bun.CryptoHasher('sha256', currentSecret()).update(body).digest('hex').slice(0, 32);
+  return hmac('sha256', currentSecret(), body, 'hex').slice(0, 32);
 }
 
 /** Constant time: the comparison must not leak how much of a forged signature was right. */

package/src/deadline-signal.ts

@@ -0,0 +1,57 @@
+// One request's signal: a deadline plus the caller's own signal, undone when the request settles.
+// `AbortSignal.any([AbortSignal.timeout(ms), outer])` could not be undone: every read hung one
+// listener on a session-long `outer` and armed a timer that outlived the answer. In core since
+// `outbound()` arms one per attempt; `@ultimat3/scraping` imports it from `@ultimat3/core/outbound`.
+
+/**
+ * The timer a request DEADLINE is armed on — not a wait, but a timer all the same, so a test hands
+ * its own and fires it rather than waiting. Cleared when the request settles, where
+ * `AbortSignal.timeout` stayed armed for its whole span after the answer had landed.
+ */
+export interface DeadlineTimer {
+  set(fire: () => void, ms: number): unknown;
+  clear(handle: unknown): void;
+}
+
+export const platformDeadlineTimer: DeadlineTimer = Object.freeze({
+  set: (fire: () => void, ms: number): unknown => setTimeout(fire, ms),
+  clear: (handle: unknown): void => clearTimeout(handle as ReturnType<typeof setTimeout>),
+});
+
+export interface DeadlineSignal extends Disposable {
+  /** Aborts at the deadline (a `TimeoutError`, as `AbortSignal.timeout`'s) or with `outer`. */
+  readonly signal: AbortSignal;
+  /** Whether the DEADLINE fired — not the caller cancelling. What the timeout code is chosen by. */
+  timedOut(): boolean;
+}
+
+/**
+ * `ms` is the caller's already-screened deadline (a positive finite count). `[Symbol.dispose]`
+ * clears the timer and detaches from `outer`; idempotent, and it never aborts.
+ */
+export function deadlineSignal(
+  ms: number,
+  outer?: AbortSignal,
+  timer: DeadlineTimer = platformDeadlineTimer,
+): DeadlineSignal {
+  const controller = new AbortController();
+  let fired = false;
+  const handle = timer.set(() => {
+    fired = true;
+    controller.abort(new DOMException('The operation timed out.', 'TimeoutError'));
+  }, ms);
+  const forward = (): void => controller.abort(outer?.reason);
+  if (outer?.aborted === true) forward();
+  else outer?.addEventListener('abort', forward, { once: true });
+  let open = true;
+  return {
+    signal: controller.signal,
+    timedOut: () => fired,
+    [Symbol.dispose]: () => {
+      if (!open) return;
+      open = false;
+      timer.clear(handle);
+      outer?.removeEventListener('abort', forward);
+    },
+  };
+}

package/src/declared-errors-openapi.ts

@@ -0,0 +1,70 @@
+// Single responsibility: an operation's `responses` with its declared `errors:` in them — one entry
+// per status, the Problem narrowed to the declared `type`s. Shared by `@ultimat3/action`'s and
+// `@ultimat3/query`'s documents (one tier, no sideways import); `@ultimat3/http`'s status reader
+// and `problemTypeFor` are passed in, being a tier above this package.
+
+import type { ErrorStatusOf } from './declared-errors';
+
+export interface DeclaredResponsesWire {
+  readonly statusOf: ErrorStatusOf;
+  /** `problemTypeFor`: the `type` a Problem document carries for a code. */
+  readonly typeFor: (code: string) => string;
+  /** The `$ref` of the document's `Problem` schema. */
+  readonly problemRef: string;
+}
+
+/** The extension naming the declared codes a response may carry, in every case machine-readable. */
+export const DECLARED_ERRORS_EXTENSION = 'x-ultimate-errors';
+
+const descriptionOf = (held: unknown): string | undefined => {
+  if (typeof held !== 'object' || held === null) return undefined;
+  const description = (held as { readonly description?: unknown }).description;
+  return typeof description === 'string' ? description : undefined;
+};
+
+/**
+ * `responses`, member for member, when nothing is declared — an undeclared operation's bytes
+ * are today's. Each declared code joins the entry for its status, codes sorted. A status the
+ * framework already answers keeps its open `Problem` (it may carry codes no list names — a
+ * policy's denial, `X_INPUT_INVALID`) and gains the codes in its description and extension; a
+ * status only the list answers narrows `type` to an enum of exactly those codes.
+ */
+export function withDeclaredResponses(
+  responses: Readonly<Record<string, unknown>>,
+  declared: readonly string[] | undefined,
+  wire: DeclaredResponsesWire,
+): Record<string, unknown> {
+  if (declared === undefined || declared.length === 0) return { ...responses };
+  const byStatus = new Map<string, string[]>();
+  for (const code of [...declared].sort()) {
+    const status = String(wire.statusOf(code));
+    byStatus.set(status, [...(byStatus.get(status) ?? []), code]);
+  }
+  const merged: Record<string, unknown> = { ...responses };
+  for (const [status, codes] of byStatus) {
+    const held = responses[status];
+    const listed = codes.join(' | ');
+    merged[status] =
+      held === undefined
+        ? {
+            description: listed,
+            content: {
+              'application/problem+json': {
+                schema: {
+                  allOf: [
+                    { $ref: wire.problemRef },
+                    { properties: { type: { enum: codes.map(wire.typeFor) } } },
+                  ],
+                },
+              },
+            },
+            [DECLARED_ERRORS_EXTENSION]: codes,
+          }
+        : {
+            ...(held as Record<string, unknown>),
+            description: `${descriptionOf(held) ?? status} | ${listed}`,
+            [DECLARED_ERRORS_EXTENSION]: codes,
+          };
+  }
+  return merged;
+}

package/src/declared-errors-scan.ts

@@ -0,0 +1,79 @@
+// Single responsibility: the static half of `errors:` — the codes a handler's FIRST HOP names in
+// its own source, as `X_…` literals and as `new <Class>` of a `defineError` class. Test-time only:
+// it reads `Function.prototype.toString()` and the file a class was declared in, which an
+// unminified server build keeps and nothing in production asks for.
+
+import { definedErrorSites } from './define-error';
+
+const CODE_LITERAL = /["'`](X(?:_[A-Z0-9]+)+)["'`]/g;
+// Bun prints `new PostNotFound` with no parentheses when the call passes nothing, and keeps a
+// namespace import's `E.PostNotFound`: the last segment is the binding a declaration exported.
+const CONSTRUCTION = /\bnew\s+(?:[A-Za-z_$][\w$]*\.)*([A-Za-z_$][\w$]*)/g;
+
+/**
+ * Every code `source` names, sorted: its literals, and each `new <Class>` whose name is a key of
+ * `classCodes`. First hop only — a helper the handler calls is its own source, reached by the
+ * dynamic half when a test runs the path.
+ */
+export function scanHandlerSource(
+  source: string,
+  classCodes: ReadonlyMap<string, string>,
+): readonly string[] {
+  const codes = new Set<string>();
+  for (const match of source.matchAll(CODE_LITERAL)) codes.add(match[1] as string);
+  for (const match of source.matchAll(CONSTRUCTION)) {
+    const code = classCodes.get(match[1] as string);
+    if (code !== undefined) codes.add(code);
+  }
+  return [...codes].sort();
+}
+
+/** `file:line` out of one stack frame — `at /a/b.ts:8:29` or `at fn (file:///a/b.ts:8:29)`. */
+export function frameSite(frame: string): { readonly file: string; readonly line: number } | null {
+  const match = /(?:\(|at\s+)(?:file:\/\/)?([^()\s][^()]*?):(\d+):\d+\)?\s*$/.exec(frame.trim());
+  if (match === null) return null;
+  return { file: match[1] as string, line: Number(match[2]) };
+}
+
+const BINDING = /([A-Za-z_$][\w$]*)\s*(?::[^=]*)?=\s*defineError\b/;
+
+/**
+ * The name `defineError`'s result was bound to, read off the declaring line (or the one above it,
+ * for `const X =` broken before the call). `null` for an inline or re-bound class: the dynamic
+ * half still judges its throw.
+ */
+export function bindingAt(text: string, line: number): string | null {
+  const lines = text.split('\n');
+  const declaring = lines[line - 1] ?? '';
+  const found = BINDING.exec(declaring) ?? BINDING.exec(`${lines[line - 2] ?? ''} ${declaring}`);
+  return found === null ? null : (found[1] as string);
+}
+
+/** Reads a declaring file. Injected so a test answers without a disk; `Bun.file` otherwise. */
+export type SourceReader = (file: string) => Promise<string>;
+
+const readWithBun: SourceReader = (file) => Bun.file(file).text();
+
+/**
+ * Binding name → code, for every `defineError` class whose declaring line can still be read. A
+ * file that cannot be read contributes nothing: the scan is a first hop, never the verdict.
+ */
+export async function definedErrorClassCodes(
+  read: SourceReader = readWithBun,
+): Promise<ReadonlyMap<string, string>> {
+  const byName = new Map<string, string>();
+  const texts = new Map<string, Promise<string | null>>();
+  for (const [code, frame] of definedErrorSites()) {
+    const site = frameSite(frame);
+    if (site === null) continue;
+    let text = texts.get(site.file);
+    if (text === undefined) {
+      text = read(site.file).catch(() => null);
+      texts.set(site.file, text);
+    }
+    const source = await text;
+    const name = source === null ? null : bindingAt(source, site.line);
+    if (name !== null) byName.set(name, code);
+  }
+  return byName;
+}