@ultimat3/core 22.15.0 → 24.0.0

package/src/config.ts

@@ -8,6 +8,7 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 // drift into two vocabularies with no map between them (issue #293).
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 import { countIssue } from './config-count';
+import { configDefaults } from './config-defaults';
 import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
 import type { DrainConfig, HealthConfig } from './config-health';
 import { readinessModeIssue } from './config-health';
@@ -18,15 +19,24 @@ import type { NavigationConfig, NavigationSectionInput } from './config-navigati
 import { mergeNavigation, navigationIssues } from './config-navigation';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
+import {
+  booleanIssue,
+  localeIssues,
+  nameListIssues,
+  oneOfIssue,
+  routePathIssue,
+  shapeIssues,
+} from './config-shape';
 import type { SeoConfig, SiteConfig, SiteSectionsInput } from './config-site';
 import { mergeSite, siteIssues } from './config-site';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
-import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
+import { readinessGraceIssue } from './lifecycle-grace';
 import { ROLES, type Role } from './roles';
 import { isIanaZoneName } from './time-zone-name';
 
-export type ThemeMode = 'light' | 'dark' | 'system';
+export const THEME_MODES = ['light', 'dark', 'system'] as const;
+export type ThemeMode = (typeof THEME_MODES)[number];
 /**
  * The buses `@ultimat3/realtime`'s `selectTransport` builds, and nothing else. `'redis'` was in
  * this union until 22.0.0 with no Redis transport anywhere: it booted whatever `NATS_URL` chose.
@@ -99,8 +109,10 @@ export const INBOX_RETENTION_KEYS = ['inboxReadRetentionMs', 'inboxUnreadRetenti
  * 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.
  */
+const DATABASE_DRIVERS = ['postgres'] as const;
+
 export interface DatabaseConfig {
-  readonly driver: 'postgres';
+  readonly driver: (typeof DATABASE_DRIVERS)[number];
   readonly ssl: boolean;
 }
 
@@ -125,6 +137,8 @@ export interface CacheConfig {
   readonly tiers: readonly CacheTierName[];
 }
 
+const JOB_BACKOFFS = ['exponential', 'fixed'] as const;
+
 export interface JobsConfig {
   /**
    * No `driver`. It accepted `'postgres' | 'redis' | 'nats'`, was read by NOTHING, and boot always
@@ -140,7 +154,7 @@ export interface JobsConfig {
   readonly queues: readonly string[];
   readonly concurrency: number;
   readonly maxAttempts: number;
-  readonly backoff: 'exponential' | 'fixed';
+  readonly backoff: (typeof JOB_BACKOFFS)[number];
   readonly visibilityTimeoutMs: number;
 }
 
@@ -255,52 +269,6 @@ const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
  */
 const CURRENCY_RE = new RegExp(CURRENCY_CODE_PATTERN);
 
-function isLocale(value: string): boolean {
-  try {
-    return Intl.getCanonicalLocales(value).length === 1;
-  } catch {
-    return false;
-  }
-}
-
-type Sectioned = 'name' | 'site' | 'seo' | 'navigation' | 'islands';
-function defaults(name: string): Omit<AppConfig, Sectioned> {
-  return {
-    locales: ['en'],
-    defaultLocale: 'en',
-    defaultTimeZone: 'UTC',
-    defaultCurrency: 'USD',
-    theme: { defaultMode: 'system', tokens: {} },
-    auth: { signInPath: null },
-    pwa: {
-      enabled: false,
-      offline: { fallback: null, image: null, font: null, neverCache: [], personalPages: 'never' },
-      backgroundSync: false,
-      push: false,
-      name: '',
-      colors: undefined,
-    },
-    roles: [...ROLES],
-    database: { driver: 'postgres', ssl: false },
-    cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
-    jobs: {
-      queues: [`${name}-default`],
-      concurrency: 8,
-      maxAttempts: 5,
-      backoff: 'exponential',
-      visibilityTimeoutMs: 30_000,
-    },
-    // ON by default since 22.0.0, when the boot began obeying the key: an app with no section
-    // keeps the `sync` node it always got, and `enabled: false` is the explicit opt-out.
-    realtime: { enabled: true, transport: 'memory', urlEnv: undefined },
-    notify: { inboxReadRetentionMs: undefined, inboxUnreadRetentionMs: undefined },
-    ai: { mcp: { expose: true, path: '/mcp' } },
-    // Read from the process env when the config is DEFINED — the same env the drain will run in.
-    drain: { readinessGraceMs: defaultReadinessGraceMs() },
-    health: { readiness: 'dependencies' },
-  };
-}
-
 function validate(config: AppConfig): void {
   const issues: string[] = [];
   // Zero or one entry: the zone's own remedy, carried only when the zone is what failed.
@@ -311,16 +279,13 @@ function validate(config: AppConfig): void {
   // Same shape again: carried only when an installable app is missing what an install needs.
   const pwaFix: string[] = [];
 
-  if (!NAME_RE.test(config.name)) {
+  // `typeof` first: `NAME_RE.test(undefined)` tests the string "undefined", which matches.
+  if (typeof config.name !== 'string') {
+    issues.push(`name must be a string like "my-app", not ${describeValue(config.name)}`);
+  } else if (!NAME_RE.test(config.name)) {
     issues.push(`name "${config.name}" must match ${String(NAME_RE)}`);
   }
-  if (config.locales.length === 0) issues.push('locales must list at least one locale');
-  for (const locale of config.locales) {
-    if (!isLocale(locale)) issues.push(`locales contains "${locale}", not a BCP-47 tag`);
-  }
-  if (!config.locales.includes(config.defaultLocale)) {
-    issues.push(`defaultLocale "${config.defaultLocale}" is not in locales`);
-  }
+  localeIssues(config.locales, config.defaultLocale, issues);
   // `@ultimat3/time`'s rule, restated because tier 0 cannot import tier 1 — see
   // `time-zone-name.ts`. One validator means a zone `app.config.ts` accepts is a zone every
   // `format` call, `task()` and `toZoned` below it can then do arithmetic in.
@@ -334,25 +299,33 @@ function validate(config: AppConfig): void {
     issues.push(`defaultCurrency "${config.defaultCurrency}" is not a 3-letter ISO 4217 code`);
   }
   if (config.roles.length === 0) issues.push('roles must list at least one runtime role');
-  // A domain per numeric key, never a bare `< 1`: every comparison with `NaN` is false, so the old
-  // `concurrency < 1` passed `NaN`, `2.5` and `Infinity`, and nothing screened the other three.
-  const counts: readonly (string | undefined)[] = [
+  // ONE check per key, each against the key's own domain. A number is never a bare `< 1` — every
+  // comparison with `NaN` is false, so `concurrency < 1` passed `NaN`, `2.5` and `Infinity` — and
+  // a switch is never read for truthiness: `ssl: 'false'` and `enabled: 'false'` were both ON.
+  const perKey: readonly (string | undefined)[] = [
+    ...config.roles.map((role) => oneOfIssue('roles', role, ROLES)),
     countIssue('jobs.concurrency', config.jobs.concurrency, 1),
     countIssue('jobs.maxAttempts', config.jobs.maxAttempts, 1),
     countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
+    oneOfIssue('jobs.backoff', config.jobs.backoff, JOB_BACKOFFS),
     countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
+    oneOfIssue('database.driver', config.database.driver, DATABASE_DRIVERS),
+    booleanIssue('database.ssl', config.database.ssl),
+    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
+      ? undefined
+      : routePathIssue('auth.signInPath', config.auth.signInPath),
+    booleanIssue('ai.mcp.expose', config.ai.mcp.expose),
+    routePathIssue('ai.mcp.path', config.ai.mcp.path),
+    booleanIssue('realtime.enabled', config.realtime.enabled),
+    oneOfIssue('realtime.transport', config.realtime.transport, REALTIME_TRANSPORTS),
     readinessGraceIssue(config.drain.readinessGraceMs),
     readinessModeIssue(config.health.readiness),
   ];
-  for (const issue of counts) if (issue !== undefined) issues.push(issue);
-  if (config.jobs.queues.length === 0) issues.push('jobs.queues must list at least one queue');
-  // An untyped config reaches here with whatever it wrote: a string is a name worth echoing, and
-  // anything else goes through `describeValue` rather than `${…}`.
-  const transport: unknown = config.realtime.transport;
-  if (!REALTIME_TRANSPORTS.some((known) => known === transport)) {
-    const said = typeof transport === 'string' ? `"${transport}"` : describeValue(transport);
-    issues.push(`realtime.transport ${said} is not one of ${REALTIME_TRANSPORTS.join(', ')}`);
-  } else if (transport === 'nats' && config.realtime.urlEnv === undefined) {
+  for (const issue of perKey) if (issue !== undefined) issues.push(issue);
+  nameListIssues('jobs.queues', config.jobs.queues, 'queue', issues);
+  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
@@ -381,6 +354,9 @@ function validate(config: AppConfig): void {
   // 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.
   // So an unknown tier is refused at boot rather than silently ignored or silently placed first.
+  // An EMPTY ladder is refused with the unknown rung: it builds no tier at all, so every read
+  // misses and nothing says the cache was configured away.
+  if (config.cache.tiers.length === 0) issues.push('cache.tiers must list at least one tier');
   for (const tier of config.cache.tiers) {
     if (CACHE_TIERS.includes(tier)) continue;
     issues.push(`cache.tiers contains "${tier}", which is not one of ${CACHE_TIERS.join(', ')}`);
@@ -399,20 +375,14 @@ function validate(config: AppConfig): void {
 }
 
 /**
- * The single config entry point. Later overlays win, so `config/jobs.ts` can own jobs without
- * touching `app.config.ts`.
+ * Every layer, in order, merged per section and KEY BY KEY — see `layered`. `name` comes from the
+ * input alone because it identifies the app: an overlay may not rename it. No layer at all is the
+ * defaults, which is the reference `shapeIssues` compares each layer against.
  */
-export function defineConfig(
-  input: AppConfigInput,
-  ...overlays: readonly AppConfigOverlay[]
-): AppConfig {
-  const base = defaults(input.name);
-  // Every layer, in order, merged per section and KEY BY KEY — see `layered`. `name` comes from
-  // the input alone because it identifies the app: an overlay may not rename it.
-  const layers: readonly AppConfigOverlay[] = [input, ...overlays];
-
-  const config: AppConfig = {
-    name: input.name,
+function merge(name: string, layers: readonly AppConfigOverlay[]): AppConfig {
+  const base = configDefaults(name);
+  return {
+    name,
     locales: lastSaid(
       base.locales,
       layers.map((layer) => layer.locales),
@@ -492,7 +462,28 @@ export function defineConfig(
     ...mergeNavigation(layers),
     ...mergeIslands(layers),
   };
+}
 
+/**
+ * The single config entry point. Later overlays win, so `config/jobs.ts` can own jobs without
+ * touching `app.config.ts`.
+ */
+export function defineConfig(
+  input: AppConfigInput,
+  ...overlays: readonly AppConfigOverlay[]
+): AppConfig {
+  const layers: readonly AppConfigOverlay[] = [input, ...overlays];
+  // Structure FIRST, per layer and before the merge: a section written as `null` or a list
+  // written as a string is what `Object.entries` and `.length` raised a native `TypeError` on.
+  const issues: string[] = [];
+  // `navigation` is left out: `config-navigation.ts` carries a wrong shape through AS WRITTEN and
+  // refuses it in its own words, with the surfaces it accepts.
+  const reference = { ...merge(input.name, []), navigation: undefined };
+  for (const layer of layers) shapeIssues(reference, layer, issues);
+  if (issues.length > 0) {
+    throw new ConfigInvalidError({ cause: issues.join('; '), fix: BASE_FIX, meta: { issues } });
+  }
+  const config = merge(input.name, layers);
   validate(config);
   return Object.freeze(config);
 }

package/src/context.ts

@@ -272,6 +272,18 @@ function screenDeadline(value: number | null | undefined): number | null {
   return finiteOption('the request context', 'deadlineAt', value);
 }
 
+/**
+ * A patched signal is ADDED to the parent's, never swapped for it — the deadline's own rule, one
+ * field over. `patch ?? parent` made a step that brought its own signal blind to the request it
+ * runs inside: the client disconnected, the request timed out, and `ctx.signal.aborted` stayed
+ * false in the child. The shared never-aborting default is skipped rather than composed, so a
+ * context with no request behind it does not grow a listener per child.
+ */
+function composeSignal(parent: AbortSignal, patch: AbortSignal | undefined): AbortSignal {
+  if (patch === undefined || patch === parent) return parent;
+  return parent === neverAborted ? patch : AbortSignal.any([parent, patch]);
+}
+
 /**
  * Derive a narrowed context — impersonation, a locale switch, a per-step abort signal.
  * `requestId` is deliberately not patchable: one request, one id.
@@ -301,7 +313,7 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     // 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: patch.signal ?? parent.signal,
+    signal: composeSignal(parent.signal, patch.signal),
     services: { ...carried, ...(patch.services ?? {}) },
   });
   return requestContext.run(child, fn);

package/src/cookie.ts

@@ -0,0 +1,35 @@
+// The one `Cookie:` request-header reader. At tier 0 because three packages need it — auth and http
+// at tier 2 cannot import each other, i18n sits below both — and each copy had to rediscover the
+// same thrown `URIError` on its own (`bun run flight-copies` refuses a fourth).
+
+/**
+ * A `Cookie:` header is attacker-controlled, and `decodeURIComponent('%')` throws a bare
+ * `URIError` — which escapes every coded path that reads through here: an OAuth callback would
+ * answer 500 instead of `X_OAUTH_STATE_INVALID`, and `curl -H 'Cookie: x-locale=%'` paged the
+ * on-call from the `locale` stage. The raw value is returned instead, so the caller's own
+ * rejection stays the readable failure; a raw value is still checked against a signature, a stored
+ * hash or a `supported` list, and none of them match a mangled one.
+ */
+const decodeCookieValue = (raw: string): string => {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+};
+
+/**
+ * The value of cookie `name` in a `Cookie:` header, or `null` when the header or the cookie is
+ * absent. Never throws: the header is client-authored, so an unreadable value is the raw value and
+ * a header that is not a string at all is no cookie.
+ */
+export function readCookie(header: string | null | undefined, name: string): string | null {
+  if (typeof header !== 'string') return null;
+  for (const part of header.split(';')) {
+    const equals = part.indexOf('=');
+    if (equals === -1) continue;
+    if (part.slice(0, equals).trim() !== name) continue;
+    return decodeCookieValue(part.slice(equals + 1).trim());
+  }
+  return null;
+}

package/src/core-error-codes.ts

@@ -54,6 +54,11 @@ const CORE_CODE_TITLES = {
   X_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',
   X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
   X_ROLE_INVALID: 'ROLE is not a known runtime role',
+  // `seal.ts`'s three. Titled here, not registered beside their classes the way the X_SECRETS_*
+  // set is, so `seal-errors.ts` runs nothing at import and is no `sideEffects` anchor.
+  X_SEAL_INVALID: 'a sealed value did not authenticate, or is not a sealed value',
+  X_SEAL_KEY_MISSING: 'no master key to seal or open a value with',
+  X_SEAL_KEY_UNKNOWN: 'a sealed value names a master key this process does not declare',
   X_SERVICE_DUPLICATE: 'a service name is registered twice',
   X_SERVICE_MISSING: 'service is not registered on the request context',
   X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',

package/src/cursor.ts

@@ -49,7 +49,10 @@ let configured: string | undefined;
  * warned and nothing failed.
  */
 function currentSecret(): string {
-  return configured ?? Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
+  // `||`, never `??`: `ULTIMATE_CURSOR_SECRET=` (a blank compose or chart value) is the EMPTY
+  // string, which `??` keeps — an HMAC keyed by '' that anyone can forge, while
+  // `usesDevCursorSecret()` answered `false` and the boot check passed. Empty is unset.
+  return configured || Bun.env['ULTIMATE_CURSOR_SECRET'] || DEV_SECRET;
 }
 
 /**

package/src/decimal-order.ts

@@ -10,10 +10,11 @@
  * and a keyset page boundary was cut where the database never cuts one.
  *
  * It answers `undefined` rather than guessing, and that is the whole of its contract: a caller
- * that knows the column's declared kind (`@ultimat3/entity`'s `compareByKind`) asks; a caller that
- * does NOT know it — `@ultimat3/query`, whose `OrderKey` is a name and a direction — must not,
- * because Postgres orders a `text` column holding `"10"` and `"9"` lexically and a comparator
- * guessing "both sides look like decimals" would disagree with the SQL it printed.
+ * that knows the column's declared kind asks — `@ultimat3/entity`'s `numericOrder`, behind
+ * `compareByKind`, which `@ultimat3/query` calls with the kind it resolves from the entity — and a
+ * caller with NO kind in hand must not, because Postgres orders a `text` column holding `"10"` and
+ * `"9"` lexically and a comparator guessing "both sides look like decimals" would disagree with
+ * the SQL it printed.
  */
 
 /** A decimal, split so two of them can be compared exactly however long the digits run. */

package/src/dev-secrets.ts

@@ -19,7 +19,7 @@ export class CursorSecretDevError extends UltimateError {
     super({
       code: CursorSecretDevError.code,
       cause:
-        'ULTIMATE_CURSOR_SECRET is unset, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
+        'ULTIMATE_CURSOR_SECRET is unset or empty, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
       fix: "x secrets set ULTIMATE_CURSOR_SECRET — or export ULTIMATE_CURSOR_SECRET from the platform's secret store",
       meta: { variable: 'ULTIMATE_CURSOR_SECRET' },
     });

package/src/error-render.ts

@@ -188,9 +188,11 @@ export function renderFixLiteral(value: unknown, placeholder: string): string {
  * denylist has to be right about every character every shell will ever read, and this only has to
  * be right about the ones a fix line needs. No space, so a value is always one word; no leading
  * `-` or `~`, because an argument starting with either is an OPTION or a home directory rather
- * than the value it reads as.
+ * than the value it reads as. A leading `@` IS carried: a scoped package name starts with one, and
+ * `@` opens nothing in a POSIX shell — `$@` needs the `$`, an extglob `@(…)` the parenthesis, and
+ * neither is in the set.
  */
-const SHELL_ARG_SAFE = /^[A-Za-z0-9/][A-Za-z0-9._:/@=+,%~-]*$/;
+const SHELL_ARG_SAFE = /^[A-Za-z0-9/@][A-Za-z0-9._:/@=+,%~-]*$/;
 
 /**
  * The same value where the text is read by a SHELL. A `fix:` is a command meant to be pasted, so a

package/src/error-reporter-sentry.ts

@@ -7,7 +7,7 @@ import { renderThrowable } from './error-render';
 import type { ErrorReport, ErrorReporter, ErrorSeverity } from './error-reporter';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { traceId } from './ids';
-import { logger } from './logger';
+import { logger, redactFields } from './logger';
 
 export class ErrorReporterDsnInvalidError extends UltimateError {
   static readonly code = 'X_ERROR_REPORTER_DSN_INVALID';
@@ -108,6 +108,10 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
           },
         }),
     extra: {
+      // The caller's two records go through `redactFields`, and FIRST. Spread raw and last, a
+      // `bigint` or a cycle in `meta` made `JSON.stringify` throw — that error was never reported
+      // — `meta: { fix, stack }` replaced the framework's own, and `meta.password` left the box.
+      ...redactFields(report.scope.extra ?? {}),
       // The whole point of reporting the framework's contract instead of a message: whoever is
       // paged reads the runnable fix next to the failure.
       fix: report.fix,
@@ -115,8 +119,8 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
       ...(report.scope.requestId === undefined ? {} : { requestId: report.scope.requestId }),
       ...(report.scope.actorId === undefined ? {} : { actorId: report.scope.actorId }),
       ...(report.stack === undefined ? {} : { stack: report.stack }),
-      ...(report.meta ?? {}),
-      ...(report.scope.extra ?? {}),
+      // Under its own key, so no name an error author picks can collide with one above.
+      ...(report.meta === undefined ? {} : { meta: redactFields(report.meta) }),
     },
     exception: { values: [{ type: report.code, value: `${report.title} — ${report.cause}` }] },
   };

package/src/error-retry.ts

@@ -61,6 +61,14 @@ const CORE_ERROR_RETRY: ReadonlyMap<string, ErrorRetry> = new Map(
     // The principal fence's twin of `X_SUPERSEDED`, listed for the same reason: re-sending a read
     // from the previous principal's scope is refused identically every time.
     X_CLIENT_SCOPE_CHANGED: 'terminal',
+    // `seal.ts`'s three, listed for `X_NOT_IMPLEMENTED`'s reason: a missing key, an undeclared
+    // key and a value that failed its tag are each the same answer on attempt five, and left
+    // unclassified a job opening a sealed column would spend its whole retry policy re-proving it.
+    // Here rather than through `registerErrorRetry` because they are core's own codes, which that
+    // function refuses, and a module-scope call would make `seal-errors.ts` a side-effect anchor.
+    X_SEAL_INVALID: 'terminal',
+    X_SEAL_KEY_MISSING: 'terminal',
+    X_SEAL_KEY_UNKNOWN: 'terminal',
   } as const),
 );
 

package/src/flight-gate.ts

@@ -8,6 +8,7 @@
 // memory fault and answers it minutes late.
 
 import { UltimateError } from './errors';
+import { finiteCount } from './finite-option';
 
 export interface FlightGateLimits {
   /** Work running at once. */
@@ -53,23 +54,34 @@ export function createFlightGate(
   options?: FlightGateOptions,
 ): FlightGate {
   const subject = options?.subject ?? 'in-flight work';
+  // Refused at CONSTRUCTION, because this pair wedges rather than fails: `active < NaN` and
+  // `waiters.length >= NaN` are both false, so every caller parks in a queue with no bound. Zero
+  // is a real value at both — "never wait" and, at the width, "refuse everything".
+  const maxConcurrent = finiteCount(
+    `createFlightGate (${subject})`,
+    'maxConcurrent',
+    limits.maxConcurrent,
+  );
+  const maxQueued = finiteCount(`createFlightGate (${subject})`, 'maxQueued', limits.maxQueued);
   const waiters: Array<() => void> = [];
   let active = 0;
 
   const state = (): FlightGateState => ({
-    maxConcurrent: limits.maxConcurrent,
-    maxQueued: limits.maxQueued,
+    maxConcurrent,
+    maxQueued,
     active,
     queued: waiters.length,
     subject,
   });
 
   const acquire = async (): Promise<void> => {
-    if (active < limits.maxConcurrent) {
+    if (active < maxConcurrent) {
       active += 1;
       return;
     }
-    if (waiters.length >= limits.maxQueued) {
+    // A width of zero has no slot to hand over, so a waiter would never be resumed: the queue is
+    // for work that WILL run, and here none will.
+    if (maxConcurrent === 0 || waiters.length >= maxQueued) {
       const current = state();
       throw options?.overflow?.(current) ?? gateOverloaded(current);
     }

package/src/fnv1a.ts

@@ -0,0 +1,19 @@
+// 32-bit FNV-1a: a BUCKET, never a key. Rollout buckets and factory seeds need a hash every process
+// computes identically and synchronously; anything that decides who shares what is `fingerprint`
+// (`canonical-json.ts`), because 2^32 values collide offline in seconds.
+
+const FNV_OFFSET_BASIS = 0x811c_9dc5;
+const FNV_PRIME = 0x0100_0193;
+
+/**
+ * The published 32-bit FNV-1a over UTF-16 code units, unsigned. Pure and dependency-free, which is
+ * the property its two callers need: two nodes place one subject in one bucket without talking.
+ */
+export function fnv1a(text: string): number {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}

package/src/health-disclosure.ts

@@ -0,0 +1,43 @@
+// What `/healthz` and `/readyz` say, and to whom — ONE rule for every role's listener. Both answer
+// outside every pipeline, so the body is a stranger's to read: everyone gets the verdict, and the
+// build id, the in-flight count and the readiness check names go only to a listed peer.
+
+import { classifyAddress } from './address-class';
+import type { HealthReport } from './lifecycle';
+import type { Role } from './roles';
+
+/** The box itself: `kubectl exec`, a port-forward, a compose healthcheck, a sidecar scraper. */
+export const DEFAULT_HEALTH_DETAIL_PEERS: readonly string[] = ['loopback'];
+
+/** The verdict a stranger gets. An allow-list, so a field `HealthReport` gains is withheld by default. */
+export interface PublicHealthBody {
+  readonly state: HealthReport['state'];
+  readonly ready: boolean;
+  readonly role: Role;
+}
+
+/** The body for one caller: the whole report for a listed peer, the verdict for anyone else. */
+export function healthBody(
+  report: HealthReport,
+  role: Role,
+  detailed: boolean,
+): PublicHealthBody | (HealthReport & { readonly role: Role }) {
+  return detailed ? { ...report, role } : { state: report.state, ready: report.ready, role };
+}
+
+/**
+ * Whether `address` is one the list names: an entry is an address CLASS (`loopback`, `private`, …)
+ * or one exact IP literal. Pure, and total — it runs on an unauthenticated probe path, so a list
+ * that is not a list, an entry that is not a string and an address that is not a literal all
+ * answer `false` rather than throw: nothing can vouch for them, whatever the list says.
+ */
+export function healthPeerListed(peers: readonly string[], address: string | null): boolean {
+  if (address === null || !Array.isArray(peers)) return false;
+  const kind = classifyAddress(address);
+  if (kind === undefined) return false;
+  const literal = address.trim().toLowerCase();
+  return peers.some(
+    (entry: unknown) =>
+      typeof entry === 'string' && (entry === kind || entry.trim().toLowerCase() === literal),
+  );
+}

package/src/host-rules.ts

@@ -4,6 +4,8 @@
 // read. In core because two tier-5 packages drive a browser (`scraping`, and `cli`'s `x shot`) and
 // neither may import the other; two copies of this rule would be two answers to "may it leave".
 
+import { classifyAddress } from './address-class';
+
 export type HostRule = string;
 
 /** The one spelling that means "every host", written out so it is visible in review. */
@@ -51,6 +53,31 @@ export function hostMatches(host: string, rule: HostRule): boolean {
   return normalised === cleaned;
 }
 
+/** A rule that names a CLASS of hosts rather than one — the two spellings `hostMatches` widens. */
+const isWildcard = (rule: HostRule): boolean => {
+  const cleaned = rule.trim();
+  return cleaned === ANY_HOST || cleaned.startsWith('*.');
+};
+
+/**
+ * The address-class FLOOR. A wildcard means "any site", and an address literal inside the network
+ * — loopback, RFC 1918, link-local, the metadata endpoint — is not a site: it is the request this
+ * module's header names. So a wildcard never admits one, and the opt-out is NAMING it: an exact
+ * rule (`'127.0.0.1'`, `'[::1]'`) is a line a reviewer can see, which `'*'` is not.
+ *
+ * What this cannot do is see through a NAME. `allowHosts: ['*']` still admits a hostname that
+ * resolves inward, because this function is synchronous and has no resolver — pinning the
+ * resolved address belongs to the driver that opens the connection, as `@ultimat3/jobs`'
+ * `webhook-target.ts` does for a webhook. The URL parser has already folded the numeric
+ * spellings (`2130706433`, `0x7f.1`) to dotted form, so they are classified as what they are.
+ */
+function admits(host: string, rule: HostRule): boolean {
+  if (!hostMatches(host, rule)) return false;
+  if (!isWildcard(rule)) return true;
+  const kind = classifyAddress(host);
+  return kind === undefined || kind === 'public';
+}
+
 /**
  * Fails CLOSED: a URL that cannot be parsed is refused. A driver handed a malformed request has
  * no way to know where it would have gone, and "we could not tell, so we let it through" is the
@@ -67,5 +94,5 @@ export function hostDecision(url: string, allowHosts: readonly HostRule[]): Host
     return { allowed: false, host: '' };
   }
   if (host === '') return { allowed: false, host };
-  return { allowed: allowHosts.some((rule) => hostMatches(host, rule)), host };
+  return { allowed: allowHosts.some((rule) => admits(host, rule)), host };
 }

package/src/html-escape.ts

@@ -0,0 +1,24 @@
+// The one HTML character table: how an untrusted value becomes inert text or attribute content.
+// At tier 0 because every package that writes markup — http, mail, render, seo, the dashboards —
+// can reach it, and a second table is one character away from a hole (`bun run flight-copies`).
+
+/** A `Map`, so a lookup never reaches `Object.prototype` (`bun run proto-index`). */
+const HTML_ESCAPES: ReadonlyMap<string, string> = new Map([
+  ['&', '&amp;'],
+  ['<', '&lt;'],
+  ['>', '&gt;'],
+  ['"', '&quot;'],
+  ["'", '&#39;'],
+]);
+
+const HTML_SPECIAL = /[&<>"']/g;
+
+/**
+ * Text content AND attribute values, in any quoting — one set for both, deliberately. A text-only
+ * subset is correct exactly until someone uses it for an attribute, and a no-`'` set until someone
+ * writes a single-quoted one. `&#39;` rather than `&apos;`: it is a numeric reference, so it means
+ * the same thing in HTML 4, HTML 5 and XML. One pass, so `&` is never escaped twice.
+ */
+export function escapeHtml(value: string): string {
+  return value.replace(HTML_SPECIAL, (char) => HTML_ESCAPES.get(char) ?? char);
+}

package/src/image/errors.ts

@@ -55,7 +55,9 @@ export const imageTooLarge = (
 ): ImageTooLargeError =>
   new ImageTooLargeError(
     cause,
-    'downscale the source before it reaches the pipeline, or raise MAX_IMAGE_PIXELS deliberately',
+    // No "or lift the ceiling": `MAX_IMAGE_PIXELS` is a constant, so a fix naming it as a knob
+    // sent a reader looking for a setting that does not exist.
+    'downscale the source below the 64-megapixel ceiling before it reaches the pipeline, or route it through an ImageTransformDriver (a CDN or an external encoder) — MAX_IMAGE_PIXELS is fixed, not a setting',
     meta,
   );