@ultimat3/core 1.2.0 → 3.0.0

package/src/lifecycle.ts

@@ -3,7 +3,10 @@
 // and reports the same /healthz + /readyz state.
 
 import { type Clock, systemClock } from './clock';
-import { type Logger, logger as rootLogger } from './logger';
+import { UltimateError } from './errors';
+import { settleWithin } from './lifecycle-deadline';
+import { lifecycleDrained } from './lifecycle-errors';
+import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
 
@@ -17,7 +20,13 @@ export type ProcessSignal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT';
 
 export interface ShutdownReason {
   readonly signal: string;
-  /** Monotonic ms after which hooks are abandoned. */
+  /**
+   * 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;
 }
 
@@ -28,17 +37,51 @@ export interface OnShutdownOptions {
 }
 
 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.
+   */
   readonly deadlineMs?: number | undefined;
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
 }
 
+export type ReadinessStatus = 'ok' | 'failing';
+
+/**
+ * Synchronous, and that is the design, not a limitation. **Do not widen this to
+ * `() => Promise<boolean>`** — the signature is the mechanism.
+ *
+ * A readiness endpoint that does I/O is a liveness bomb. A probe that awaits a network call takes
+ * as long as the dependency does, so a slow database makes the endpoint miss its `timeoutSeconds`,
+ * the kubelet reads that as unready, and capacity is pulled from an already-struggling system —
+ * the outage the probe existed to prevent, caused by the probe. Worse under a liveness probe
+ * sharing the handler: the pod is killed and restarts into the same slow database, cold.
+ *
+ * So the owner of the dependency keeps a boolean fresh — a pool exposes `isOpen`, a background
+ * poller flips a flag on its own schedule with its own timeout — and this reads it. That puts the
+ * waiting where a timeout can be tuned, and leaves this path unable to block. A check that throws
+ * is `failing`.
+ */
+export type ReadinessCheck = () => boolean;
+
 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>>;
 }
 
 export interface HealthPayload {
@@ -65,6 +108,7 @@ let inflight = 0;
 let registrations: Registration[] = [];
 let drainPromise: Promise<void> | undefined;
 let idleWaiters: (() => void)[] = [];
+const readiness = new Map<string, ReadinessCheck>();
 
 export function configureLifecycle(options: LifecycleOptions): void {
   if (options.deadlineMs !== undefined) deadlineMs = options.deadlineMs;
@@ -79,14 +123,106 @@ export function lifecycleState(): HealthState {
   return state;
 }
 
+/**
+ * "This process bound its socket." NOT "this process can serve a request" — that is what the
+ * readiness checks answer. Before them, `markReady()` was the whole of `/readyz`, so a pod went
+ * green the instant it bound and the load balancer sent traffic into a Postgres pool that had not
+ * opened a connection yet; `maxUnavailable: 0` does not help when readiness lies.
+ *
+ * **A drained lifecycle refuses this, and that is the whole of "one process, one lifecycle."**
+ * `state` never leaves `stopped` and `drain()` memoizes, so a role that marked ready after a drain
+ * used to be told nothing and go on to bind a socket answering 503 to everything, with no drain
+ * left to close it. `X_LIFECYCLE_DRAINED` is that mistake named at the moment it is made, rather
+ * than a lifecycle that can be restarted: two live lifecycles racing one shutdown is a worse
+ * mechanism than a boot that fails.
+ */
 export function markReady(): void {
+  if (isDraining()) throw lifecycleDrained(state === 'draining' ? 'draining' : 'stopped');
   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 —
+ * and a throw here does not lose a line, it replaces the event. Inside `drain()` it rejected
+ * `drainPromise`: `state` never reached 'stopped', the memo re-rejected for every later caller,
+ * and on Bun the unhandled rejection ended the process the drain was trying to end cleanly.
+ * Inside `readinessChecks()` it replaced the probe's answer with a throw.
+ *
+ * A lifecycle that cannot report is still a lifecycle: the line falls back to core's own
+ * `rootLogger`, which is total by construction (`logger.ts`), and failing that is dropped.
+ */
+function report(level: 'info' | 'warn' | 'error', message: string, fields: LogFields): void {
+  try {
+    log[level](message, fields);
+    return;
+  } catch {
+    // Fall through — the injected sink is gone, and the fallback below is the last one there is.
+  }
+  if (log === rootLogger) return;
+  try {
+    rootLogger[level](message, fields);
+  } catch {
+    // Both sinks are gone. Dropping the line is the only remaining option that still ends the
+    // process, which is the outcome every caller of this file depends on.
+  }
+}
+
+/** Every check, run now, by name. A check that throws is `failing` — never an unhandled error. */
+export function readinessChecks(): Readonly<Record<string, ReadinessStatus>> {
+  const results: Record<string, ReadinessStatus> = {};
+  for (const [name, check] of readiness) {
+    try {
+      results[name] = check() ? 'ok' : 'failing';
+    } catch (thrown) {
+      results[name] = 'failing';
+      report('warn', 'readiness check threw', { check: name, error: thrown });
+    }
+  }
+  return results;
+}
+
 export function inflightCount(): number {
   return inflight;
 }
 
+/** Test-only: drains still waiting on in-flight work. A count stuck above zero is a leak. */
+export function idleWaiterCount(): number {
+  return idleWaiters.length;
+}
+
+/**
+ * Test-only: hooks still registered. A count that climbs across a start/stop cycle is a leak —
+ * the registration retains its closure, and the next drain runs it against a torn-down resource.
+ */
+export function shutdownHookCount(): number {
+  return registrations.length;
+}
+
 /** Register a drain hook. Returns an unregister function. */
 export function onShutdown(
   name: string,
@@ -127,23 +263,66 @@ export function isDraining(): boolean {
 function waitForIdle(timeoutMs: number): Promise<boolean> {
   if (inflight === 0) return Promise.resolve(true);
   return new Promise<boolean>((resolve) => {
-    const timer = setTimeout(() => resolve(false), timeoutMs);
-    idleWaiters.push(() => {
+    const waiter = (): void => {
       clearTimeout(timer);
       resolve(true);
-    });
+    };
+    // A drain that times out must not leave its waiter in the queue forever — the next
+    // `beginWork()` to reach zero would still hold and invoke it, a dangling closure over a
+    // promise nothing is awaiting anymore.
+    const timer = setTimeout(() => {
+      idleWaiters = idleWaiters.filter((candidate) => candidate !== waiter);
+      resolve(false);
+    }, timeoutMs);
+    idleWaiters.push(waiter);
   });
 }
 
+/**
+ * The budget every drain is bounded by — `DEFAULT_DEADLINE_MS` until an app raises it. There is no
+ * unbounded state: `ShutdownReason.deadlineAt` was always computed and handed to every hook, so the
+ * deadline was declared by the design all along and only the enforcement was missing.
+ *
+ * The ONE place the budget is decided, and exported so a test can pin it: 25s is far above any
+ * drain a test can wait out, so the default needs a probe and not only a stopwatch.
+ */
+export function drainDeadlineMs(): number {
+  return deadlineMs;
+}
+
+/**
+ * What is left of that budget. Read per hook, not per phase: the deadline bounds the WHOLE drain,
+ * so a hook that spent it leaves nothing for the ones behind it — which is what
+ * `terminationGracePeriodSeconds` means, and what makes the SUM of the phases bounded rather than
+ * each one of them separately. Returns `number`, never `number | undefined`: "no budget" is not a
+ * state this file has, and the type is what keeps it from becoming one again.
+ */
+function remainingBudget(reason: ShutdownReason): number {
+  return Math.max(0, reason.deadlineAt - systemClock.monotonic());
+}
+
 async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<void> {
   for (const registration of registrations.filter((entry) => entry.phase === phase)) {
-    try {
-      await registration.hook(reason);
-    } catch (thrown) {
-      log.error('shutdown hook failed', {
+    const outcome = await settleWithin(() => registration.hook(reason), remainingBudget(reason));
+    if (outcome.kind === 'failed') {
+      report('error', 'shutdown hook failed', {
+        hook: registration.name,
+        phase,
+        error: outcome.error,
+      });
+      continue;
+    }
+    if (outcome.kind === 'abandoned') {
+      // Abandoned, not merely logged. A deadline that waited anyway would leave the kubelet to
+      // SIGKILL this process — the every-deploy duplicate that draining exists to prevent — so
+      // the drain moves on and the hook is left running with nobody reading it. The cost of that
+      // choice is real and named in the cause: a write it had in flight may be half done.
+      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`,
         hook: registration.name,
         phase,
-        error: thrown,
       });
     }
   }
@@ -153,26 +332,37 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
 export function drain(signal = 'manual'): Promise<void> {
   if (drainPromise !== undefined) return drainPromise;
   state = 'draining';
-  const reason: ShutdownReason = { signal, deadlineAt: clock.monotonic() + deadlineMs };
+  const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
 
   drainPromise = (async () => {
-    log.info('draining', { signal, deadlineMs, inflight });
-    await runPhase('accept', reason);
-
-    const remaining = Math.max(0, reason.deadlineAt - clock.monotonic());
-    const idle = await waitForIdle(remaining);
-    if (!idle) {
-      log.warn('X_SHUTDOWN_TIMEOUT', {
-        code: 'X_SHUTDOWN_TIMEOUT',
-        cause: `${inflight} in-flight operations still running after ${deadlineMs}ms`,
-        fix: 'raise configureLifecycle({ deadlineMs }) or shorten the slow handler',
-      });
+    try {
+      report('info', 'draining', { signal, deadlineMs, inflight });
+      await runPhase('accept', reason);
+
+      // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
+      // a budget read off an injected clock is a number that timer will never honour.
+      const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic());
+      const idle = await waitForIdle(remaining);
+      if (!idle) {
+        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',
+        });
+      }
+
+      await runPhase('inflight', reason);
+      await runPhase('close', reason);
+    } catch (thrown) {
+      // Nothing above should reach here — every hook is caught by `settleWithin` and every line
+      // goes through `report`. If something does, the drain still ENDS: a rejected `drainPromise`
+      // is a memo that re-rejects for every later caller and an unhandled rejection that kills the
+      // process mid-drain, which is strictly worse than a drain that finished badly and said so.
+      report('error', 'drain failed', { signal, error: thrown });
+    } finally {
+      state = 'stopped';
     }
-
-    await runPhase('inflight', reason);
-    await runPhase('close', reason);
-    state = 'stopped';
-    log.info('stopped', { signal });
+    report('info', 'stopped', { signal });
   })();
 
   return drainPromise;
@@ -191,9 +381,14 @@ export function installSignalHandlers(options?: SignalHandlerOptions): () => voi
 
   for (const signal of signals) {
     const handler = (): void => {
-      void drain(signal).then(() => {
+      // Attached on BOTH settle paths, for the reason `settleWithin` gives: an unhandled rejection
+      // ends the process before the drain does, and the exit is what the kubelet is waiting for.
+      // `drain()` cannot reject today — that is the `try/finally` above, not luck — and this is
+      // the one line that keeps it true when someone changes the body.
+      const done = (): void => {
         if (options?.exit === true) process.exit(0);
-      });
+      };
+      void drain(signal).then(done, done);
     };
     handlers.set(signal, handler);
     process.on(signal, handler);
@@ -205,27 +400,34 @@ export function installSignalHandlers(options?: SignalHandlerOptions): () => voi
 }
 
 export function healthReport(): HealthReport {
+  const checks = readinessChecks();
   return {
     state,
-    ready: state === 'ready',
+    // `ready` is the same predicate `/readyz` answers on, so a body and its status can never
+    // disagree — a 200 whose body says `ready: false` is the bug this shares one source to avoid.
+    ready: state === 'ready' && Object.values(checks).every((status) => status === 'ok'),
     uptimeMs: Math.round(clock.monotonic() - startedAtMono),
     inflight,
     buildId: process.env['BUILD_ID'] ?? 'dev',
+    checks,
   };
 }
 
-/** Liveness: the process exists and is not wedged. Stays 200 while draining. */
+/**
+ * Liveness: the process exists and is not wedged. Stays 200 while draining, and deliberately
+ * ignores the checks — a database outage that failed liveness everywhere would restart the whole
+ * fleet into the same outage, with cold caches and no connections.
+ */
 export function healthzPayload(): HealthPayload {
   const body = healthReport();
   const ok = state !== 'stopped';
   return { ok, status: ok ? 200 : 503, body };
 }
 
-/** Readiness: may this instance receive traffic? 503 while starting or draining. */
+/** Readiness: may this instance receive traffic? 503 while starting, draining or any check fails. */
 export function readyzPayload(): HealthPayload {
   const body = healthReport();
-  const ok = state === 'ready';
-  return { ok, status: ok ? 200 : 503, body };
+  return { ok: body.ready, status: body.ready ? 200 : 503, body };
 }
 
 /** Test-only: forget all hooks and return to `starting`. */
@@ -239,4 +441,5 @@ export function resetLifecycle(): void {
   registrations = [];
   drainPromise = undefined;
   idleWaiters = [];
+  readiness.clear();
 }

package/src/logger.ts

@@ -2,6 +2,7 @@
 // default because the primary reader is an agent tailing `x logs --json`.
 
 import { type Clock, systemClock } from './clock';
+import { renderCauseValue } from './error-render';
 import { isUltimateError } from './errors';
 import { isSecret, REDACTED } from './secret';
 
@@ -48,15 +49,34 @@ export interface LoggerOptions {
   readonly writer?: ((line: string, level: LogLevel) => void) | undefined;
 }
 
+/**
+ * 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.
+ */
 const redactedKeys = new Set<string>([
   'password',
   'token',
   'secret',
   'authorization',
   'cookie',
-  'apiKey',
-  'accessToken',
-  'refreshToken',
+  'set-cookie',
+  'apikey',
+  'api_key',
+  'accesstoken',
+  'access_token',
+  'refreshtoken',
+  'refresh_token',
+  'idtoken',
+  'id_token',
+  'sessiontoken',
+  'session_token',
+  'clientsecret',
+  'client_secret',
+  'privatekey',
+  'private_key',
 ]);
 
 /** Mark keys as secret everywhere. `defineEnv()` calls this for every `secret: true` var. */
@@ -83,31 +103,101 @@ function defaultWriter(line: string, level: LogLevel): void {
   stream.write(`${line}\n`);
 }
 
+/**
+ * TOTAL, on purpose. `lifecycle.ts` logs the value a shutdown hook threw and the value a
+ * readiness check threw — both caught, both arbitrary — so a renderer that throws here escapes
+ * `runPhase`'s catch, rejects the drain promise, and `installSignalHandlers` never reaches
+ * `process.exit(0)`: SIGTERM hangs, and `/readyz` dies with the check it was reporting on. A log
+ * line must never replace the event it describes.
+ *
+ * Degradation is per KEY, the same shape `renderMetaRecord` uses: one hostile getter must not
+ * cost a reader the fields beside it.
+ */
 function serialiseValue(value: unknown, depth: number): unknown {
+  try {
+    return serialise(value, depth);
+  } catch {
+    // `instanceof`, `Object.keys` and `toJSON` are all property reads on a value the framework
+    // did not build; `renderCauseValue` is the one renderer that cannot itself throw.
+    return renderCauseValue(value);
+  }
+}
+
+function serialise(value: unknown, depth: number): unknown {
+  // `JSON.stringify` raises a `TypeError` on a bigint, so the whole line died for one field.
+  if (typeof value === 'bigint') return renderCauseValue(value);
   if (value === null || typeof value !== 'object') return value;
   // Before every other branch: a `Secret` is redacted by VALUE, so it stays redacted under a key
   // nobody listed — `{ dsn: secret(url) }` is the leak key-name redaction cannot see.
   if (isSecret(value)) return REDACTED;
-  if (value instanceof Date) return value.toISOString();
+  // `toISOString()` THROWS on an invalid Date, and an invalid Date is exactly the value worth
+  // logging when a schedule went wrong.
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? 'an invalid Date' : value.toISOString();
+  }
   if (isUltimateError(value)) return value.toJSON();
   if (value instanceof Error) return { name: value.name, message: value.message };
   if (depth >= 6) return '[depth-limit]';
   if (Array.isArray(value)) return value.map((item) => serialiseValue(item, depth + 1));
+  const source = value as Record<string, unknown>;
   const out: Record<string, unknown> = {};
-  for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
-    out[key] = isRedactedKey(key) ? REDACTED : serialiseValue(nested, depth + 1);
+  for (const key of Object.keys(source)) {
+    out[key] = isRedactedKey(key) ? REDACTED : entryValue(source, key, depth);
   }
   return out;
 }
 
+/** One field. The `try` covers the property READ — `serialiseValue` above is already total. */
+function entryValue(source: Record<string, unknown>, key: string, depth: number): unknown {
+  try {
+    return serialiseValue(source[key], depth + 1);
+  } catch {
+    return 'a value that cannot be read';
+  }
+}
+
 function redactFields(fields: LogFields): Record<string, unknown> {
   const out: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(fields)) {
-    out[key] = isRedactedKey(key) ? REDACTED : serialiseValue(value, 0);
+  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
+  // record is the caller's object, and enumerating it eagerly threw on the first hostile getter.
+  for (const key of ownKeys(source)) {
+    out[key] = isRedactedKey(key) ? REDACTED : entryValue(source, key, 0);
   }
   return out;
 }
 
+function ownKeys(source: Record<string, unknown>): readonly string[] {
+  try {
+    return Object.keys(source);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The last guard. The walk above already degraded every hostile field, so reaching the fallback
+ * means the assembled line itself refused to serialise — and the answer to that is still a line,
+ * not a throw propagating out of `log.error` into whatever `catch` block called it.
+ */
+function renderLine(
+  line: Readonly<Record<string, unknown>>,
+  level: LogLevel,
+  message: string,
+  ts: unknown,
+): string {
+  try {
+    return JSON.stringify(line);
+  } catch {
+    return JSON.stringify({
+      ts: typeof ts === 'string' ? ts : '',
+      level,
+      msg: message,
+      logFields: 'a log line that cannot be serialised',
+    });
+  }
+}
+
 function envLevel(): LogLevel {
   const raw = process.env['LOG_LEVEL'];
   return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
@@ -132,7 +222,7 @@ export function createLogger(options?: LoggerOptions): Logger {
       ...redactFields(contextFields() ?? {}),
       ...redactFields(fields ?? {}),
     };
-    writer(JSON.stringify(line), lineLevel);
+    writer(renderLine(line, lineLevel, message, line.ts), lineLevel);
   }
 
   return {

package/src/mcp-exposure.ts

@@ -0,0 +1,32 @@
+// 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 `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.
+ */
+export interface McpExposureDeclaration {
+  readonly expose?: boolean | undefined;
+}
+
+/**
+ * Opt-in, never opt-out: silence exposes nothing. An absent block, an omitted `expose` and a
+ * literal `false` are one answer, because a tool the author never asked for is a capability
+ * handed to every agent that can reach the surface — and writing an action is not a request to
+ * hand one out.
+ *
+ * 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
+ * called one.
+ *
+ * The one deliberate exception is `@ultimat3/admin`'s OWN catalog, whose every tool is already
+ * gated on an admin permission and whose CRUD tools carry no `mcp` block at all; there
+ * `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 {
+  return declared?.expose === true;
+}