@ultimat3/core 27.7.0 → 27.8.1

package/README.md

@@ -731,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.7.0",
+  "version": "27.8.1",
   "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.7.0"
+    "@ultimat3/schema": "27.8.1"
   }
 }

package/src/index.ts

@@ -679,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/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>,