@ultimat3/core 27.6.1 → 27.8.0

package/README.md

@@ -494,7 +494,10 @@ match with `sealAll()`; uniqueness cannot be held across keys.
   **bound**. `ReadinessCheck` is `() => boolean` and must stay synchronous — a probe that awaits its
   dependency turns a slow dependency into a wedged endpoint and then a restart loop; keep a boolean
   fresh and let the check read it. It returns an unregister. `HealthReport.checks` is a map of name
-  → `'ok' | 'failing'`, so "alert on check failures by check name" is writable.
+  → `'ok' | 'degraded' | 'failing'`, so "alert on check failures by check name" is writable.
+  `registerReadinessCheck(name, check, { onFailure: 'degraded' })` is a dependency the role serves
+  without (the bus of a role that only publishes to it): its `false` is `'degraded'`, never a 503
+  on `/readyz` in either mode, and a 503 on `/readyz?deep=1`.
 - **`HealthReport.registered` is the third state.** `checks: {}` reads identically for "every check
   passed" and "nobody registered one", and an **empty registry is still ready** — reported, never
   enforced, so a role with no dependency does not have to invent a check to boot. Read `registered`
@@ -728,7 +731,7 @@ nothing consulted it before deciding to try again. `As of 2026-08-23`.
 | Export | The one answer | The question it settles |
 |---|---|---|
 | `backoffDelay({ attempt, base, max, factor?, curve?, jitter?, random? })` | one curve — `exponential \| linear \| fixed`, `full \| equal \| none` — 1-based `attempt`, clamped to `max` **before** jitter, rounded, and `0` rather than `NaN` | how long to wait. `random` is injectable, so a schedule is a unit test rather than a range |
-| `singleFlight({ deadlineMs?, schedule? })` → `run(key, work, join?)`, `size` | N callers on one key are ONE run | who pays for a miss. Eviction is identity-checked, so a load that settles late never drops the load that replaced it; `deadlineMs` frees the KEY a wedged load would hold forever — it never cancels the work and never rejects a joiner |
+| `singleFlight({ deadlineMs?, schedule? })` → `run(key, work, join?)`, `size`, `keys()`, `evict(key)` | N callers on one key are ONE run | who pays for a miss. Eviction is identity-checked, so a load that settles late never drops the load that replaced it; `deadlineMs` frees the KEY a wedged load would hold forever — it never cancels the work and never rejects a joiner. `evict(key)` does the same on demand, for a caller that learns the load in flight began before a write its result must reflect |
 | `flightGate({ maxConcurrent, maxQueued }, { subject?, overflow? })` | one bound, one queue, one refusal | how many at once. Past the queue the answer is `X_FLIGHT_GATE_OVERLOADED` (503) and never a longer queue; the slot is HANDED to a waiter, never released and re-acquired. Both limits are screened at construction (`finiteCount`, 0 allowed); a width of 0 refuses every caller rather than queueing for a slot that never frees. `run(work, signal?)`: an abort while QUEUED removes the waiter and rejects with the abort's reason |
 | `generationFence(subject)` → `generation()`, `bump()`, `guard(issued)` | whether an answer still applies | `X_SUPERSEDED` (499) and `isSuperseded(error)` — the piece nothing in the tree had. `guard` compares `!==`, never `<` |
 | `isRetryableStatus(status)`, `RETRYABLE_STATUSES` | `>= 500`, plus 408, 409, 425, 429 | which HTTP answers are worth repeating |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "27.6.1",
+  "version": "27.8.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "27.6.1"
+    "@ultimat3/schema": "27.8.0"
   }
 }

package/src/index.ts

@@ -646,7 +646,11 @@ export {
   READINESS_GRACE_DEFAULT_MS,
   READINESS_GRACE_MAX_MS,
 } from './lifecycle-grace';
-export type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
+export type {
+  ReadinessCheck,
+  ReadinessCheckOptions,
+  ReadinessStatus,
+} from './lifecycle-readiness';
 export type { SignalHandlerOptions } from './lifecycle-signals';
 export { drainSignals, installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';
@@ -675,6 +679,9 @@ export {
   resetMeasurementActor,
 } from './measurement-actor';
 export { nearestName } from './nearest-name';
+// An outage said on failures 1, 2, 4, 8, … and once when it ends.
+export type { OutageLog, OutageLogOptions } from './outage-log';
+export { isOutageMilestone, outageLog } from './outage-log';
 /** The message pwa's `sw.js` posts and realtime's outbox listens for. */
 export { OUTBOX_DRAIN_MESSAGE, type OutboxDrainMessage } from './outbox-drain';
 /** The `<meta name>`s render writes and the page client, realtime and pwa read. */

package/src/lifecycle-readiness.ts

@@ -4,7 +4,22 @@
 
 import { UltimateError } from './errors';
 
-export type ReadinessStatus = 'ok' | 'failing';
+/**
+ * `'degraded'` is a failed check the role serves WITHOUT (`onFailure: 'degraded'`): reported by
+ * name, never a 503 on `/readyz` in either mode, and a 503 on `/readyz?deep=1` — the probe routes
+ * traffic on the first and a monitor alerts on the second.
+ */
+export type ReadinessStatus = 'ok' | 'degraded' | 'failing';
+
+export interface ReadinessCheckOptions {
+  /**
+   * What a `false` (or a throw) from this check is. `'failing'`, the default, is a dependency the
+   * role cannot serve without. `'degraded'` is one it can — the bus of a role that only publishes
+   * to it: pulling every replica from the ingress for a dependency no served request waits on is
+   * the outage the probe exists to prevent.
+   */
+  readonly onFailure?: 'failing' | 'degraded' | undefined;
+}
 
 /**
  * Synchronous, and that is the design, not a limitation. **Do not widen this to
@@ -23,13 +38,22 @@ export type ReadinessStatus = 'ok' | 'failing';
  */
 export type ReadinessCheck = () => boolean;
 
-const checks = new Map<string, ReadinessCheck>();
+interface Registered {
+  readonly check: ReadinessCheck;
+  readonly onFailure: 'failing' | 'degraded';
+}
+
+const checks = new Map<string, Registered>();
 
 /**
  * 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 {
+export function registerReadinessCheck(
+  name: string,
+  check: ReadinessCheck,
+  options: ReadinessCheckOptions = {},
+): () => void {
   if (checks.has(name)) {
     throw new UltimateError({
       code: 'X_READINESS_CHECK_DUPLICATE',
@@ -38,9 +62,10 @@ export function registerReadinessCheck(name: string, check: ReadinessCheck): ()
       meta: { name },
     });
   }
-  checks.set(name, check);
+  const registered: Registered = { check, onFailure: options.onFailure ?? 'failing' };
+  checks.set(name, registered);
   return () => {
-    if (checks.get(name) === check) checks.delete(name);
+    if (checks.get(name) === registered) checks.delete(name);
   };
 }
 
@@ -55,8 +80,8 @@ export function clearReadinessChecks(): void {
 }
 
 /**
- * Every check, run now, by name. A check that throws is `failing` — never an unhandled error —
- * and is handed to `onThrow`, which `lifecycle.ts` routes through its total `report`.
+ * Every check, run now, by name. A check that throws is its `onFailure` (`failing` unless it was
+ * registered degradable) — never an unhandled error — and is handed to `onThrow`, which `lifecycle.ts` routes through its total `report`.
  *
  * 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
@@ -67,11 +92,11 @@ export function runReadinessChecks(
   onThrow: (name: string, thrown: unknown) => void,
 ): Readonly<Record<string, ReadinessStatus>> {
   const results: [string, ReadinessStatus][] = [];
-  for (const [name, check] of checks) {
+  for (const [name, { check, onFailure }] of checks) {
     try {
-      results.push([name, check() ? 'ok' : 'failing']);
+      results.push([name, check() ? 'ok' : onFailure]);
     } catch (thrown) {
-      results.push([name, 'failing']);
+      results.push([name, onFailure]);
       onThrow(name, thrown);
     }
   }

package/src/lifecycle.ts

@@ -374,9 +374,15 @@ export function drain(signal = 'manual'): Promise<void> {
   return drainPromise;
 }
 
-export function healthReport(mode: ReadinessMode = readinessMode): HealthReport {
+export function healthReport(
+  mode: ReadinessMode = readinessMode,
+  /** `/readyz?deep=1`: a `'degraded'` check is not ready either. Never the probe's reading. */
+  strict = false,
+): HealthReport {
   const checks = readinessChecks();
-  const dependencies = Object.values(checks).every((status) => status === 'ok');
+  const dependencies = Object.values(checks).every(
+    (status) => status === 'ok' || (!strict && status === 'degraded'),
+  );
   return {
     state,
     // `ready` is the same predicate `/readyz` answers on, so a body and its status can never
@@ -405,9 +411,11 @@ export function healthzPayload(): HealthPayload {
 /**
  * Readiness: may this instance receive traffic? 503 while starting or draining, and — in the
  * default `'dependencies'` mode, or always with `deep` (`/readyz?deep=1`) — while any check fails.
+ * A `'degraded'` check (`ReadinessCheckOptions.onFailure`) is a 503 under `deep` ALONE.
  */
 export function readyzPayload(options: { readonly deep?: boolean } = {}): HealthPayload {
-  const body = healthReport(options.deep === true ? 'dependencies' : readinessMode);
+  const deep = options.deep === true;
+  const body = healthReport(deep ? 'dependencies' : readinessMode, deep);
   return { ok: body.ready, status: body.ready ? 200 : 503, body };
 }
 

package/src/outage-log.ts

@@ -0,0 +1,53 @@
+// Single responsibility: one condition that KEEPS failing, said rarely — on failures 1, 2, 4, 8, …
+// and once more when it ends. An outage is one fact; a line per retry per pod for as long as it
+// lasts is the fact buried under itself.
+
+import { type LogFields, logger } from './logger';
+
+export interface OutageLogOptions {
+  /** The line's message while the condition fails. Low cardinality: it is what a monitor groups on. */
+  readonly event: string;
+  /**
+   * `'warn'` for a process that is degraded and still serving (a publisher without its bus).
+   * `'error'` for one that cannot do its job (a `sync` node without its bus).
+   */
+  readonly level: 'warn' | 'error';
+}
+
+export interface OutageLog {
+  /**
+   * One more failure. Written — with `failures`, the count since it last worked — on the 1st,
+   * 2nd, 4th, 8th, …; answers whether this one was, so a caller thins a second sink the same way.
+   */
+  failed(fields?: LogFields): boolean;
+  /** It works again: ONE `info` line, `<event> recovered`, with `after`. Silent when nothing had failed. */
+  recovered(fields?: LogFields): void;
+  /** Failures since it last worked. */
+  readonly failures: number;
+}
+
+/** True on 1, 2, 4, 8, …: the attempts an outage is said on. */
+export function isOutageMilestone(failures: number): boolean {
+  return failures > 0 && (failures & (failures - 1)) === 0;
+}
+
+export function outageLog(options: OutageLogOptions): OutageLog {
+  let failures = 0;
+  return {
+    get failures(): number {
+      return failures;
+    },
+    failed(fields?: LogFields): boolean {
+      failures += 1;
+      if (!isOutageMilestone(failures)) return false;
+      logger[options.level](options.event, { ...fields, failures });
+      return true;
+    },
+    recovered(fields?: LogFields): void {
+      if (failures === 0) return;
+      const after = failures;
+      failures = 0;
+      logger.info(`${options.event} recovered`, { ...fields, after });
+    },
+  };
+}

package/src/single-flight.ts

@@ -40,6 +40,15 @@ export interface SingleFlight {
   ): Promise<T>;
   /** In-flight loads right now. A number that does not fall back to `0` is a leak. */
   readonly size: number;
+  /** The keys held by a load right now — what a caller that must `evict` by a rule walks. */
+  keys(): readonly string[];
+  /**
+   * Free `key` NOW, so the next `run` leads a fresh load instead of joining the one in flight.
+   * For a caller that learns the load in flight is already wrong — it began before a write its
+   * result must reflect. The load is not cancelled and its own callers still get its value; only
+   * later ones stop joining it. `false` when nothing held the key.
+   */
+  evict(key: string): boolean;
 }
 
 /** The leader's promise, the box its merged context lives in, and its deadline's canceller. */
@@ -73,6 +82,15 @@ export function singleFlight(options?: SingleFlightOptions): SingleFlight {
       return inflight.size;
     },
 
+    keys: () => [...inflight.keys()],
+
+    evict(key: string): boolean {
+      const held = inflight.get(key);
+      if (held === undefined) return false;
+      held.cancelDeadline();
+      return inflight.delete(key);
+    },
+
     run<T, C = undefined>(
       key: string,
       work: (shared: () => C | undefined) => Promise<T>,