@ultimat3/core 23.0.0 → 25.0.0

package/src/lifecycle-types.ts

@@ -0,0 +1,96 @@
+// Single responsibility: the lifecycle's data model — its states, phases, hook and option shapes,
+// and the health report it answers with. The mechanism that moves between them is `lifecycle.ts`,
+// which re-exports every name here so a caller keeps one import path.
+
+import type { Clock } from './clock';
+import type { ReadinessMode } from './config-health';
+import type { ReadinessStatus } from './lifecycle-readiness';
+import type { Logger } from './logger';
+
+export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
+
+/** Ordered. `accept` runs first, `close` last. */
+export type ShutdownPhase = 'accept' | 'inflight' | 'close';
+
+export const SHUTDOWN_PHASES: readonly ShutdownPhase[] = ['accept', 'inflight', 'close'];
+
+/**
+ * Signals Ultimate reacts to. Narrower than `NodeJS.Signals` on purpose. `SIGBREAK` is Windows'
+ * Ctrl-Break — the one console signal there that is neither Ctrl-C nor a window closing.
+ */
+export type ProcessSignal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGBREAK';
+
+export interface ShutdownReason {
+  readonly signal: string;
+  /**
+   * Real monotonic ms (`systemClock`) after which hooks are abandoned — deliberately NOT the
+   * injected clock. The budget this bounds is `terminationGracePeriodSeconds`, counted by the
+   * kubelet in real seconds, so a frozen clock must be unable to extend it: read off `clock` a
+   * test that advanced an hour of fake time handed the drain a 16-minute grace period, while
+   * `waitForIdle` went on sleeping on a real `setTimeout`. `clock` still owns `uptimeMs`.
+   */
+  readonly deadlineAt: number;
+}
+
+export type ShutdownHook = (reason: ShutdownReason) => void | Promise<void>;
+
+export interface OnShutdownOptions {
+  readonly phase?: ShutdownPhase | undefined;
+}
+
+export interface LifecycleOptions {
+  /**
+   * The whole drain's budget — the in-flight wait AND every hook, in every phase. 25s by default,
+   * and **enforced whether or not an app sets it**: `ShutdownReason.deadlineAt` was always computed
+   * and handed to every hook, so the deadline was declared by the design and only the enforcement
+   * was missing. No hook reads `deadlineAt`, which is why it has to be imposed here.
+   *
+   * The lever is a LARGER value, not the absence of one: a `worker` holding a 10-minute job wants
+   * `configureLifecycle({ deadlineMs: 600_000 })` and a `terminationGracePeriodSeconds` at least as
+   * large. Left at 25s it is abandoned and the process exits clean — the row's visibility lease
+   * lapses and another worker re-claims it, which is what at-least-once already promises. The
+   * alternative is not "the job finishes": it is the same duplicate, delivered by SIGKILL at the
+   * kubelet's grace period, with no log line naming what overran.
+   *
+   * Screened where it is assigned: a whole number of milliseconds, 0 or more. `0` is "drain now".
+   */
+  readonly deadlineMs?: number | undefined;
+  /**
+   * How long `/readyz` answers 503 BEFORE the `accept` phase closes the listener — the time the
+   * endpoints controller and the ingress need to stop routing here. Closing on the flip itself left
+   * endpoints pointing at a closed socket, and a POST in that window got a 502. Added to
+   * `deadlineMs`, never taken from it. Unset: `defaultReadinessGraceMs()` of the process env at
+   * drain time — 0 in development/test, 5000 everywhere else, including a process naming no env.
+   * A whole number from 0 to 60000; 0 is no grace.
+   */
+  readonly readinessGraceMs?: number | undefined;
+  /** What a failing check does to `/readyz` — see `ReadinessMode`. Default `'dependencies'`. */
+  readonly readiness?: ReadinessMode | undefined;
+  readonly clock?: Clock | undefined;
+  readonly logger?: Logger | undefined;
+}
+
+export interface HealthReport {
+  readonly state: HealthState;
+  readonly ready: boolean;
+  readonly uptimeMs: number;
+  readonly inflight: number;
+  readonly buildId: string;
+  /** Named, because "alert on check failures BY CHECK NAME" is not writable against a boolean. */
+  readonly checks: Readonly<Record<string, ReadinessStatus>>;
+  /**
+   * How many checks are registered. `checks: {}` reads identically for "every check passed" and
+   * "nobody registered one", and only the second is a `/readyz` that means no more than "the
+   * socket is bound" — which is what the chart's and compose's healthchecks route traffic on.
+   * Reported rather than enforced: an empty registry is still ready, so a role that genuinely has
+   * no dependency does not have to invent a check to boot.
+   */
+  readonly registered: number;
+}
+
+export interface HealthPayload {
+  readonly ok: boolean;
+  /** The status code the HTTP layer should return. Core stays HTTP-free; this is just data. */
+  readonly status: number;
+  readonly body: HealthReport;
+}

package/src/lifecycle.ts

@@ -5,98 +5,45 @@
 import { type Clock, systemClock } from './clock';
 import type { ReadinessMode } from './config-health';
 import { assertReadinessMode } from './config-health';
+import { DRAIN_DEADLINE_DEFAULT_MS } from './drain-deadline';
 import { UltimateError } from './errors';
 import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
 import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
-import type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
+import type { ReadinessStatus } from './lifecycle-readiness';
+import {
+  clearReadinessChecks,
+  readinessCheckCount,
+  runReadinessChecks,
+} from './lifecycle-readiness';
+import type {
+  HealthPayload,
+  HealthReport,
+  HealthState,
+  LifecycleOptions,
+  OnShutdownOptions,
+  ShutdownHook,
+  ShutdownPhase,
+  ShutdownReason,
+} from './lifecycle-types';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
-export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
-
-/** Ordered. `accept` runs first, `close` last. */
-export type ShutdownPhase = 'accept' | 'inflight' | 'close';
-
-export const SHUTDOWN_PHASES: readonly ShutdownPhase[] = ['accept', 'inflight', 'close'];
-
-/** Signals Ultimate reacts to. Narrower than `NodeJS.Signals` on purpose. */
-export type ProcessSignal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT';
-
-export interface ShutdownReason {
-  readonly signal: string;
-  /**
-   * Real monotonic ms (`systemClock`) after which hooks are abandoned — deliberately NOT the
-   * injected clock. The budget this bounds is `terminationGracePeriodSeconds`, counted by the
-   * kubelet in real seconds, so a frozen clock must be unable to extend it: read off `clock` a
-   * test that advanced an hour of fake time handed the drain a 16-minute grace period, while
-   * `waitForIdle` went on sleeping on a real `setTimeout`. `clock` still owns `uptimeMs`.
-   */
-  readonly deadlineAt: number;
-}
-
-export type ShutdownHook = (reason: ShutdownReason) => void | Promise<void>;
-
-export interface OnShutdownOptions {
-  readonly phase?: ShutdownPhase | undefined;
-}
-
-export interface LifecycleOptions {
-  /**
-   * The whole drain's budget — the in-flight wait AND every hook, in every phase. 25s by default,
-   * and **enforced whether or not an app sets it**: `ShutdownReason.deadlineAt` was always computed
-   * and handed to every hook, so the deadline was declared by the design and only the enforcement
-   * was missing. No hook reads `deadlineAt`, which is why it has to be imposed here.
-   *
-   * The lever is a LARGER value, not the absence of one: a `worker` holding a 10-minute job wants
-   * `configureLifecycle({ deadlineMs: 600_000 })` and a `terminationGracePeriodSeconds` at least as
-   * large. Left at 25s it is abandoned and the process exits clean — the row's visibility lease
-   * lapses and another worker re-claims it, which is what at-least-once already promises. The
-   * alternative is not "the job finishes": it is the same duplicate, delivered by SIGKILL at the
-   * kubelet's grace period, with no log line naming what overran.
-   *
-   * Screened where it is assigned: a whole number of milliseconds, 0 or more. `0` is "drain now".
-   */
-  readonly deadlineMs?: number | undefined;
-  /**
-   * How long `/readyz` answers 503 BEFORE the `accept` phase closes the listener — the time the
-   * endpoints controller and the ingress need to stop routing here. Closing on the flip itself left
-   * endpoints pointing at a closed socket, and a POST in that window got a 502. Added to
-   * `deadlineMs`, never taken from it. Unset: `defaultReadinessGraceMs()` of the process env at
-   * drain time — 0 in development/test, 5000 everywhere else, including a process naming no env.
-   * A whole number from 0 to 60000; 0 is no grace.
-   */
-  readonly readinessGraceMs?: number | undefined;
-  /** What a failing check does to `/readyz` — see `ReadinessMode`. Default `'dependencies'`. */
-  readonly readiness?: ReadinessMode | undefined;
-  readonly clock?: Clock | undefined;
-  readonly logger?: Logger | undefined;
-}
-
-export interface HealthReport {
-  readonly state: HealthState;
-  readonly ready: boolean;
-  readonly uptimeMs: number;
-  readonly inflight: number;
-  readonly buildId: string;
-  /** Named, because "alert on check failures BY CHECK NAME" is not writable against a boolean. */
-  readonly checks: Readonly<Record<string, ReadinessStatus>>;
-  /**
-   * How many checks are registered. `checks: {}` reads identically for "every check passed" and
-   * "nobody registered one", and only the second is a `/readyz` that means no more than "the
-   * socket is bound" — which is what the chart's and compose's healthchecks route traffic on.
-   * Reported rather than enforced: an empty registry is still ready, so a role that genuinely has
-   * no dependency does not have to invent a check to boot.
-   */
-  readonly registered: number;
-}
-
-export interface HealthPayload {
-  readonly ok: boolean;
-  /** The status code the HTTP layer should return. Core stays HTTP-free; this is just data. */
-  readonly status: number;
-  readonly body: HealthReport;
-}
+// The data model and the readiness registry are modules of their own; every name stays exported
+// from here, so nothing that imports a lifecycle type or the check registry learns a second path.
+export { readinessCheckCount, registerReadinessCheck } from './lifecycle-readiness';
+export type {
+  HealthPayload,
+  HealthReport,
+  HealthState,
+  LifecycleOptions,
+  OnShutdownOptions,
+  ProcessSignal,
+  ShutdownHook,
+  ShutdownPhase,
+  ShutdownReason,
+} from './lifecycle-types';
+export { SHUTDOWN_PHASES } from './lifecycle-types';
 
 interface Registration {
   readonly name: string;
@@ -104,7 +51,8 @@ interface Registration {
   readonly hook: ShutdownHook;
 }
 
-const DEFAULT_DEADLINE_MS = 25_000;
+/** `drain.deadlineMs`'s default, owned by `drain-deadline.ts` so the config and this agree. */
+const DEFAULT_DEADLINE_MS = DRAIN_DEADLINE_DEFAULT_MS;
 
 let deadlineMs = DEFAULT_DEADLINE_MS;
 /** `undefined` means "the environment's default", read when a drain starts, not at import. */
@@ -120,15 +68,13 @@ let lifetime = 0;
 let registrations: Registration[] = [];
 let drainPromise: Promise<void> | undefined;
 let idleWaiters: (() => void)[] = [];
-const readiness = new Map<string, ReadinessCheck>();
 
 export function configureLifecycle(options: LifecycleOptions): void {
   // Screened above the write, never beside the arithmetic: `Math.max(0, deadlineAt - monotonic())`
   // PROPAGATES a NaN into `setTimeout(fn, NaN)`, i.e. 0 — measured, one in-flight operation dropped
   // and a 300ms close hook ABANDONED 111ms into a 25s budget, while `X_SHUTDOWN_TIMEOUT` rendered
   // `NaNms` and told the operator to RAISE a budget that was never a number. `min: 0` because 0 is
-  // a real budget — drain now, no grace — and `@ultimat3/http`'s `drainTimeoutMs` accepts 0 and
-  // hands it straight here, so a floor of 1 would refuse at boot what that package declares.
+  // a real budget — drain now, no grace — and `drain.deadlineMs` reaches here unchanged.
   if (options.deadlineMs !== undefined) {
     deadlineMs = finiteCount('configureLifecycle', 'deadlineMs', options.deadlineMs, 0);
   }
@@ -174,30 +120,6 @@ export function markReady(): void {
   if (state === 'starting') state = 'ready';
 }
 
-/**
- * Register a named readiness check. Returns its unregister — the same shape as `onShutdown`, and
- * owned by whoever can be started twice, for the same reason.
- */
-export function registerReadinessCheck(name: string, check: ReadinessCheck): () => void {
-  if (readiness.has(name)) {
-    throw new UltimateError({
-      code: 'X_READINESS_CHECK_DUPLICATE',
-      cause: `a readiness check named "${name}" is already registered (have: ${[...readiness.keys()].join(', ')})`,
-      fix: `name the second check for what it actually probes, e.g. registerReadinessCheck('${name}-replica', check) — or hold the unregister the first registration returned and call it first`,
-      meta: { name },
-    });
-  }
-  readiness.set(name, check);
-  return () => {
-    if (readiness.get(name) === check) readiness.delete(name);
-  };
-}
-
-/** Test-only: registered checks. A count that climbs across a start/stop cycle is a leak. */
-export function readinessCheckCount(): number {
-  return readiness.size;
-}
-
 /**
  * Every line this file emits, and the only way it emits one. `log` is an injection seam
  * (`configureLifecycle({ logger })`), so an app's `Logger` decides whether a log call can throw —
@@ -226,24 +148,13 @@ function report(level: 'info' | 'warn' | 'error', message: string, fields: LogFi
 }
 
 /**
- * Every check, run now, by name. A check that throws is `failing` — never an unhandled error.
- *
- * Built through `Object.fromEntries`, never by assigning `results[name]`: assignment to the one
- * name `__proto__` sets the PROTOTYPE instead of adding a key, so that check vanished from the
- * report, `ready` was computed over an empty object — vacuously true — and a failing check
- * answered 200. `fromEntries` defines own properties and has no such name.
+ * Every check, run now, by name. A check that throws is `failing` — never an unhandled error —
+ * and is reported through `report`, so an injected logger that throws cannot replace the answer.
  */
 export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
-  const results: [string, ReadinessStatus][] = [];
-  for (const [name, check] of readiness) {
-    try {
-      results.push([name, check() ? 'ok' : 'failing']);
-    } catch (thrown) {
-      results.push([name, 'failing']);
-      report('warn', 'readiness check threw', { check: name, error: thrown });
-    }
-  }
-  return Object.fromEntries(results);
+  return runReadinessChecks((name, thrown) => {
+    report('warn', 'readiness check threw', { check: name, error: thrown });
+  });
 }
 
 export function inflightCount(): number {
@@ -369,7 +280,7 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
       report('warn', 'X_SHUTDOWN_TIMEOUT', {
         code: 'X_SHUTDOWN_TIMEOUT',
         cause: `the "${registration.name}" shutdown hook (phase: ${phase}) was still running at the ${deadlineMs}ms drain deadline and has been ABANDONED — the process exits without it, so anything it had in flight may be incomplete`,
-        fix: `raise the budget past the work this hook does — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute job — and set terminationGracePeriodSeconds to at least as many seconds, or make the "${registration.name}" hook return once it has stopped accepting work rather than once it has finished`,
+        fix: `raise the budget past the work this hook does — set drain: { deadlineMs: 600_000 } in app.config.ts for a 10-minute job (configureLifecycle({ deadlineMs: 600_000 }) outside a framework boot) — and give the platform's kill timer at least as many seconds (x deploy --method helm sizes the chart's from it), or make the "${registration.name}" hook return once it has stopped accepting work rather than once it has finished`,
         hook: registration.name,
         phase,
       });
@@ -401,7 +312,7 @@ async function runDrain(signal: string): Promise<void> {
       report('warn', 'X_SHUTDOWN_TIMEOUT', {
         code: 'X_SHUTDOWN_TIMEOUT',
         cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
-        fix: 'raise the budget past the slowest handler — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds, or shorten the handler',
+        fix: 'raise the budget past the slowest handler — set drain: { deadlineMs: 600_000 } in app.config.ts for a 10-minute one (configureLifecycle({ deadlineMs: 600_000 }) outside a framework boot) — and give the platform kill timer at least as many seconds, or shorten the handler',
       });
     }
 
@@ -458,7 +369,7 @@ export function healthReport(mode: ReadinessMode = readinessMode): HealthReport
     inflight,
     buildId: process.env['BUILD_ID'] ?? 'dev',
     checks,
-    registered: readiness.size,
+    registered: readinessCheckCount(),
   };
 }
 
@@ -496,5 +407,5 @@ export function resetLifecycle(): void {
   registrations = [];
   drainPromise = undefined;
   idleWaiters = [];
-  readiness.clear();
+  clearReadinessChecks();
 }

package/src/locale-direction.ts

@@ -2,7 +2,7 @@
 // requests, which is why it is tier 0 rather than `@ultimat3/i18n`'s: `@ultimat3/ui`'s provider
 // reflects `dir` onto `<html>` from the locale it was handed, and reaching the i18n barrel for
 // that one function put the whole framework catalog into every browser chunk with a `UiProvider`
-// in it (issue #490). i18n re-exports these under the same names, so no caller moved.
+// in it (issue #490). Import them from `@ultimat3/core`: i18n's re-export was deleted in 25.0.0.
 
 export type Direction = 'ltr' | 'rtl';
 

package/src/logger.ts

@@ -54,11 +54,10 @@ export interface LoggerOptions {
 }
 
 /**
- * LOWERCASE, always: `isRedactedKey` lowercases its lookup, so `apiKey`/`accessToken`/
- * `refreshToken` sat here for three releases matching nothing — and those are the exact field
- * names on `@ultimat3/auth`'s `OAuthTokens`. Matching is exact-key and never substring, so a
- * spelling that is not in this set is not redacted: both the camel and the snake wire spelling of
- * each credential is listed. Add through `redactKeys()` (which lowercases) rather than here.
+ * The exact-key FAST PATH. LOWERCASE, always: `isRedactedKey` lowercases its lookup, so
+ * `apiKey`/`accessToken`/`refreshToken` sat here for three releases matching nothing — and those
+ * are the exact field names on `@ultimat3/auth`'s `OAuthTokens`. Add through `redactKeys()` (which
+ * lowercases) rather than here. A name this set misses still meets `CREDENTIAL_NAME` below.
  */
 const redactedKeys = new Set<string>([
   'password',
@@ -81,15 +80,78 @@ const redactedKeys = new Set<string>([
   'client_secret',
   'privatekey',
   'private_key',
+  // The framework's own columns (`@ultimat3/auth`): a hash is what an offline guess runs against.
+  'passwordhash',
+  'tokenhash',
+  'keyhash',
 ]);
 
+/**
+ * The second half, for the names no list can enumerate. Exact-key matching alone let every
+ * COMPOUND credential through — `currentPassword`, `mfaSecret`, `resetToken`, `recoveryCode` — and
+ * `@ultimat3/action`'s audit walk asks this same predicate, so each was persisted in clear.
+ *
+ * Tested against the key lowercased with `_` and `-` removed, so one pattern covers the camel, the
+ * snake and the header spelling. It names what BEARS a credential and nothing wider, because a
+ * redacted field is one an operator cannot correlate on:
+ *
+ * - `password` / `passphrase` anywhere — no ordinary field carries the word.
+ * - `secret` as the LAST word (`mfaSecret`, `webhookSecret`, `appSecrets`, `secretAccessKey`), so
+ *   `clientSecretEnv` and `secretsPath` — a variable name and a path — stay readable.
+ * - a `token` is a bearer UNLESS its qualifier says it is not: fail closed, with the exceptions
+ *   named. `idempotencyToken`, `pageToken`, `continuationToken`, `cursorToken`, `syncToken` are
+ *   dedupe and paging keys an operator greps for; everything else ending in `token` — `resetToken`,
+ *   `githubToken`, `NPM_TOKEN` — is redacted without a provider list to keep current. The PLURAL
+ *   is the reverse: `maxTokens` / `inputTokens` are counts on every `@ultimat3/ai` usage line, so
+ *   `tokens` is redacted only behind a bearer qualifier (`accessTokens`).
+ * - key MATERIAL by its qualifier (`apiKey`, `privateKey`, `signingKey`, `encryptionKey`,
+ *   `masterKey`, `hmacKey`, `secretsKey`, `accessKey`, `retiredKeys`) and the id half of a key
+ *   pair (`accessKeyId`). A LOOKUP key — `cacheKey`, `primaryKey`, `idempotencyKey` — and a key's
+ *   own id (`signingKeyId`) carry no qualifier on this list and stay readable.
+ * - a value that EMBEDS a credential: `connectionString`, `dsn`, a registry `authConfig`, and the
+ *   service URLs that carry `user:password@` (`databaseUrl`, `REDIS_URL`). A bare `url` does not.
+ * - the one-time codes by name. Never a `code` suffix: that is the error contract's own field.
+ * - a stored hash of any of them: it is what an offline guess runs against.
+ * - a bearer by its kind as the LAST word: `credentials`, `jwt`, `bearer`, `cookies`, a session's
+ *   id or key (`sessionId` IS the session), and key material by encoding (`privateKeyPem`).
+ *   `credentialId`, `jwtIssuer`, `cookieName`, `privateKeyId` name a credential, not hold one.
+ * - card verification codes (`cvv`, `cvc2`) as a suffix, and a `pin` only as the WHOLE word
+ *   behind an owner qualifier — three letters inside `spinner`, `shipping` or `pinned` are not one.
+ *
+ * Built from constant alternatives with no nested quantifier, so there is no input it backtracks on.
+ */
+const CREDENTIAL_NAME = new RegExp(
+  [
+    'passw(?:or)?d|passphrase',
+    'secrets?$',
+    '(?:api|private|signing|encryption|master|hmac|secrets?|access|retired)keys?$|accesskeyid$',
+    '(?:token|key)hash(?:es)?$',
+    '(?<!idempotency|page|continuation|cursor|sync)token$',
+    '(?:access|refresh|id|session|reset|bearer|auth|api|csrf|xsrf|captcha|card|verification|invite|magic|magiclink|device|push|workload|oauth)tokens$',
+    'authconfig$|connectionstring$|dsn$',
+    '(?:database|db|redis|replication|nats|smtp|amqp|mongo)ur[li]s?$',
+    '^totp$|totpcode$|otp$|otpcode$',
+    '(?:recovery|backup|mfa)codes?(?:hash(?:es)?)?$',
+    'credentials?$|jwts?$|bearer$|cookies?$|session(?:id|key)s?$',
+    'privatekey(?:pem|der|jwk)$',
+    'cv[vc]2?$',
+    '^(?:card|atm|security|account|user|wallet)?pin(?:code|number)?(?:hash(?:es)?)?$',
+  ].join('|'),
+);
+
 /** Mark keys as secret everywhere. `defineEnv()` calls this for every `secret: true` var. */
 export function redactKeys(keys: Iterable<string>): void {
   for (const key of keys) redactedKeys.add(key.toLowerCase());
 }
 
+/**
+ * The framework's ONE answer to "is this field a credential?" — the log line, the error monitor's
+ * envelope and `@ultimat3/action`'s audit row all ask it, so a value that is `[redacted]` in one
+ * cannot be plaintext in another.
+ */
 export function isRedactedKey(key: string): boolean {
-  return redactedKeys.has(key.toLowerCase());
+  const lower = key.toLowerCase();
+  return redactedKeys.has(lower) || CREDENTIAL_NAME.test(lower.replace(/[_-]/g, ''));
 }
 
 /**
@@ -224,7 +286,12 @@ function entryValue(source: Record<string, unknown>, key: string, depth: number)
   }
 }
 
-function redactFields(fields: LogFields): Record<string, unknown> {
+/**
+ * A caller's record made safe to SERIALISE and safe to SHIP: credentials replaced by key and by
+ * value, a bigint / cycle / hostile getter degraded per field. Exported for the one other sink
+ * that sends a caller's record off the box — `error-reporter-sentry.ts`.
+ */
+export function redactFields(fields: LogFields): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   const source = fields as Record<string, unknown>;
   // `Object.keys` before the values, so the read of each value is its own guarded step: a field
@@ -286,7 +353,7 @@ function timestamp(clock: Clock): string {
  * `LOG_LEVEL`, and the default where there is no environment to read it from.
  *
  * A BROWSER has no `process` binding at all, and this read runs at MODULE INIT — `logger` at the
- * foot of this file is `createLogger()` evaluated when the module is. Measured on ai-maxxing's
+ * foot of this file is `structuredLogger()` evaluated when the module is. Measured on ai-maxxing's
  * session console island: `@ultimat3/realtime`'s `channel.ts` calls `logger.warn`, so the shaker
  * keeps `logger`, and the island's chunk died on `ReferenceError: process is not defined` before a
  * line of the app's own code ran — the wrapper rendered `data-x-failed="process is not defined"`
@@ -304,9 +371,18 @@ function timestamp(clock: Clock): string {
  */
 function envLevel(): LogLevel {
   const raw = typeof process === 'undefined' ? undefined : process.env['LOG_LEVEL'];
-  return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
-    ? (raw as LogLevel)
-    : 'info';
+  // Unset and EMPTY are the same answer — `LOG_LEVEL=` is how a compose file spells "not set".
+  if (raw === undefined || raw === '') return 'info';
+  // REFUSED, as `resolveLevel` refuses the same value from `structuredLogger({ level })`. It fell back
+  // to `info` in silence, so `LOG_LEVEL=verbose` — or `DEBUG`, the spelling half the ecosystem
+  // uses — gave an operator who asked for MORE lines fewer, and nothing said the variable was the
+  // reason. This runs at module init, so the refusal is the first thing the process prints.
+  assert(
+    (LOG_LEVELS as readonly string[]).includes(raw),
+    `LOG_LEVEL=${renderCauseValue(raw)} is not a log level`,
+    `set LOG_LEVEL=info (one of ${LOG_LEVELS.join(', ')}, lowercase), or unset LOG_LEVEL`,
+  );
+  return raw as LogLevel;
 }
 
 /**
@@ -325,7 +401,7 @@ function resolveLevel(declared: LogLevel): LogLevel {
     // level that arrived from a config file can be either — the refusal must not be replaced by
     // a `TypeError` from building its own message.
     `${renderCauseValue(declared)} is not a log level`,
-    `pass one of ${LOG_LEVELS.join(', ')} to createLogger({ level })`,
+    `pass one of ${LOG_LEVELS.join(', ')} to structuredLogger({ level })`,
   );
   return declared;
 }
@@ -346,7 +422,7 @@ function unreserved(fields: Record<string, unknown>): Record<string, unknown> {
   return out;
 }
 
-export function createLogger(options?: LoggerOptions): Logger {
+export function structuredLogger(options?: LoggerOptions): Logger {
   const level = options?.level === undefined ? envLevel() : resolveLevel(options.level);
   const bound = options?.fields ?? {};
   const clock = options?.clock ?? systemClock;
@@ -377,10 +453,10 @@ export function createLogger(options?: LoggerOptions): Logger {
     warn: (message, fields) => emit('warn', message, fields),
     error: (message, fields) => emit('error', message, fields),
     fatal: (message, fields) => emit('fatal', message, fields),
-    child: (fields) => createLogger({ level, clock, writer, fields: { ...bound, ...fields } }),
-    withLevel: (next) => createLogger({ level: next, clock, writer, fields: bound }),
+    child: (fields) => structuredLogger({ level, clock, writer, fields: { ...bound, ...fields } }),
+    withLevel: (next) => structuredLogger({ level: next, clock, writer, fields: bound }),
   };
 }
 
 /** The process-wide logger. Prefer `ctx.logger` inside a request — it carries the ids. */
-export const logger: Logger = createLogger();
+export const logger: Logger = structuredLogger();

package/src/mcp-exposure.ts

@@ -1,14 +1,71 @@
-// The one answer to "did this primitive opt into being an MCP tool?" — a literal `expose: true`.
-// Core owns it because its readers span tiers 3-5 — `action`, `query`, `mcp`, `ai`, `manifest` —
-// and this is the only tier all of them reach, the same reason `timing-safe-equal.ts` lives here.
+// The ONE declaration of a primitive's `mcp` block, and the one answer to "did this primitive opt
+// into being an MCP tool?" — a literal `expose: true`. Core owns both because the block's readers
+// span tiers 3-5 — `action`, `query`, `mcp`, `ai`, `manifest` — and this is the only tier all of
+// them reach. `ActionMcp`, `QueryMcp` and `McpExposure` each restated the block until 25.0.0.
 
 /**
- * The `mcp` block, read structurally. Each package keeps its own richer declaration —
- * `ActionMcp` carries `visibleTo`, `@ultimat3/mcp`'s `McpExposure` carries `name` — and hands it
- * here; restating the one field they share binds this to none of them.
+ * MCP's four tool hints, as the spec (2025-06-18) spells them. Hints for a client's confirmation
+ * UI — the primitive's `policy` decides every call whatever they say.
+ */
+export interface McpAnnotationHints {
+  readonly readOnlyHint?: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+  readonly openWorldHint?: boolean;
+}
+
+/** One comparison a list filter accepts. A filter key is `<field><op>`: `status_eq`. */
+export type McpListFilterOp = '_eq' | '_in' | '_gt' | '_lt' | '_cont';
+
+/**
+ * The list whitelist an MCP meta surface composes over: `filters` field → operators, sortable
+ * `sort` fields, pickable `fields`, `maxLimit`. Flat keys: the query's own `input` declares
+ * `status_eq`, `sort`, `fields`, `cursor`, `limit` and implements them; `manage_resource` refuses
+ * anything outside the whitelist before it runs.
+ */
+export interface McpListParams {
+  readonly filters?: Readonly<Record<string, readonly McpListFilterOp[]>>;
+  readonly sort?: readonly string[];
+  readonly fields?: readonly string[];
+  /** Ceiling for `limit`. `@ultimat3/mcp`'s `DEFAULT_LIST_MAX_LIMIT` when absent. */
+  readonly maxLimit?: number;
+}
+
+/**
+ * `mcp: { … }` on an `action`, a `mutator`, a `query` or an `llm()`/`agent()` factory — the block
+ * an author writes and `@ultimat3/mcp`'s `toolFrom` reads. An action's view omits `listParams`
+ * (it has no list to compose); every other field means the same on every primitive.
  */
 export interface McpExposureDeclaration {
-  readonly expose?: boolean | undefined;
+  /** Opt-in: only a literal `true` makes the primitive a tool. Silence exposes nothing. */
+  readonly expose: boolean;
+  /**
+   * Contract text, NOT UI text — deliberately outside `t()`. It becomes the OpenAPI operation
+   * `summary`, and `buildOpenApi`'s bytes are what `x verify` diffs for contract drift. Resolving
+   * it through the ambient, request-scoped translator would make `openapi.json` depend on
+   * whichever locale was active when it was generated. Two ways to describe one tool is the
+   * drift axiom 1 rejects, so there is no localised twin here.
+   */
+  readonly description?: string;
+  /**
+   * Roles that may SEE the projected tool. A CATALOG audience, never an authz rule — the `policy`
+   * still decides every call. Fail-closed where it lands: a caller whose role is not named,
+   * including one with no role at all, gets the answer an ABSENT tool gets, never `Forbidden`,
+   * which would confirm the tool exists. A plain role list, never a predicate: a declared fact
+   * stays static and serialisable. Omitted means every caller may enumerate it.
+   */
+  readonly visibleTo?: readonly string[];
+  /** The tool's display name in an MCP client's UI. Contract text, like `description`. */
+  readonly title?: string;
+  /**
+   * Overrides of the hints `@ultimat3/mcp` derives, key by key: an action derives
+   * `readOnlyHint: false`, `destructiveHint: true` and `idempotentHint` from `idempotent`; a query
+   * `readOnlyHint: true`. `annotations: { destructiveHint: false }` for a write that destroys
+   * nothing, `openWorldHint: true` for one that reaches outside the app.
+   */
+  readonly annotations?: McpAnnotationHints;
+  /** A list query's whitelist, carried to the tool for the meta surface. Never an action's. */
+  readonly listParams?: McpListParams;
 }
 
 /**
@@ -17,6 +74,9 @@ export interface McpExposureDeclaration {
  * handed to every agent that can reach the surface — and writing an action is not a request to
  * hand one out.
  *
+ * Read through `Partial<Pick<…>>` because a reader holding only a descriptor (`manifest`'s
+ * diff, a hand-built test primitive) may carry no `expose` at all, and that is the same "no".
+ *
  * Six readers decided it three ways until 2026-08: `=== true` where a tool is actually built,
  * `!== false` in the OpenAPI hint and `?? true` in the manifest fact. So an action with no `mcp`
  * block was published as a tool by the contract and refused by every surface that could have
@@ -27,6 +87,8 @@ export interface McpExposureDeclaration {
  * `expose: false` withdraws a tool. That surface says so in `mcp-tools.ts` and in
  * `wiki/Admin-Dashboard.md`. Nothing else may grow a second default.
  */
-export function isMcpExposed(declared: McpExposureDeclaration | undefined): boolean {
+export function isMcpExposed(
+  declared: Partial<Pick<McpExposureDeclaration, 'expose'>> | undefined,
+): boolean {
   return declared?.expose === true;
 }