@ultimat3/core 29.4.0 → 30.1.0

package/src/single-flight.ts

@@ -26,6 +26,19 @@ export interface SingleFlightOptions {
   readonly deadlineMs?: number | undefined;
   /** Injected so a deadline is provable without waiting for one. */
   readonly schedule?: Scheduler | undefined;
+  /**
+   * The lifetime of whoever is calling, read at each `run`. Set, a joiner whose leader was aborted
+   * and whose own signal is live re-leads with its own `work`: the leader's closed tab is not a
+   * failure of the read it joined. Any other rejection is shared, ordinary failures included.
+   * Absent means every joiner shares every rejection. Injected, so this file reads no context.
+   */
+  readonly signal?: (() => AbortSignal | undefined) | undefined;
+  /**
+   * Told each time `key` stops being held: settle, deadline or `evict`, and not when a load already
+   * evicted settles. So a caller keeping state per held key mirrors the map exactly, with no gap
+   * before the settle and no entry left behind by a load that never does.
+   */
+  readonly released?: ((key: string) => void) | undefined;
 }
 
 export interface SingleFlight {
@@ -51,9 +64,10 @@ export interface SingleFlight {
   evict(key: string): boolean;
 }
 
-/** The leader's promise, the box its merged context lives in, and its deadline's canceller. */
+/** The leader's promise, its signal, the box its merged context lives in, its deadline's canceller. */
 interface Flight {
   readonly running: Promise<unknown>;
+  readonly signal: AbortSignal | undefined;
   readonly shared: { context: unknown };
   cancelDeadline: () => void;
 }
@@ -69,12 +83,68 @@ export function singleFlight(options?: SingleFlightOptions): SingleFlight {
   const inflight = new Map<string, Flight>();
   const schedule = options?.schedule ?? defaultScheduler;
   const deadlineMs = options?.deadlineMs;
+  const readSignal = options?.signal;
+  const released = options?.released;
 
   // Identity, never key presence. `inflight.delete(key)` from a settling load drops whatever holds
   // the key NOW — which, once a deadline can evict, is a different load that has not settled: its
   // joiners would then be sharing a promise nothing in the map answers for.
   const evict = (key: string, entry: Flight): void => {
-    if (inflight.get(key) === entry) inflight.delete(key);
+    if (inflight.get(key) !== entry) return;
+    inflight.delete(key);
+    released?.(key);
+  };
+
+  const run = <T, C = undefined>(
+    key: string,
+    work: (shared: () => C | undefined) => Promise<T>,
+    join?: FlightJoin<C>,
+  ): Promise<T> => {
+    const joined = inflight.get(key);
+    // Two readers of one key asking for two different `T` is a caller bug this cannot see; the
+    // value they share is the same object either way, so the cast is the honest one.
+    if (joined !== undefined) {
+      if (join !== undefined) {
+        joined.shared.context = join.merge(joined.shared.context as C, join.context);
+      }
+      if (readSignal === undefined) return joined.running as Promise<T>;
+      const mine = readSignal();
+      // Asked at the rejection, not now: either side may yet abort. `settled` was attached at lead,
+      // ahead of this, so the key is already free; the first re-lead leads and the rest join it. No
+      // cap is needed, as each further round spends one more aborted leader. `catch` runs under the
+      // context it was attached in, so the re-lead's `work` is this joiner's, as this joiner.
+      return (joined.running as Promise<T>).catch((error: unknown) => {
+        if (joined.signal?.aborted !== true || mine?.aborted === true) throw error;
+        return run(key, work, join);
+      });
+    }
+
+    const shared: { context: unknown } = { context: join?.context };
+    // Wrapped so a `work()` that throws SYNCHRONOUSLY still rejects the joiners rather than
+    // escaping past the map and leaving no entry to clear.
+    const running: Promise<T> = (async () => await work(() => shared.context as C | undefined))();
+    const entry: Flight = {
+      running,
+      signal: readSignal?.(),
+      shared,
+      cancelDeadline: (): void => undefined,
+    };
+    inflight.set(key, entry);
+
+    if (deadlineMs !== undefined) {
+      entry.cancelDeadline = schedule(() => {
+        evict(key, entry);
+      }, deadlineMs);
+    }
+
+    const settled = (): void => {
+      entry.cancelDeadline();
+      evict(key, entry);
+    };
+    // A rejected load MUST clear too, or one failure is cached as a permanent rejection.
+    void running.then(settled, settled);
+
+    return running;
   };
 
   return {
@@ -88,45 +158,10 @@ export function singleFlight(options?: SingleFlightOptions): SingleFlight {
       const held = inflight.get(key);
       if (held === undefined) return false;
       held.cancelDeadline();
-      return inflight.delete(key);
+      evict(key, held);
+      return true;
     },
 
-    run<T, C = undefined>(
-      key: string,
-      work: (shared: () => C | undefined) => Promise<T>,
-      join?: FlightJoin<C>,
-    ): Promise<T> {
-      const joined = inflight.get(key);
-      // Two readers of one key asking for two different `T` is a caller bug this cannot see; the
-      // value they share is the same object either way, so the cast is the honest one.
-      if (joined !== undefined) {
-        if (join !== undefined) {
-          joined.shared.context = join.merge(joined.shared.context as C, join.context);
-        }
-        return joined.running as Promise<T>;
-      }
-
-      const shared: { context: unknown } = { context: join?.context };
-      // Wrapped so a `work()` that throws SYNCHRONOUSLY still rejects the joiners rather than
-      // escaping past the map and leaving no entry to clear.
-      const running: Promise<T> = (async () => await work(() => shared.context as C | undefined))();
-      const entry: Flight = { running, shared, cancelDeadline: (): void => undefined };
-      inflight.set(key, entry);
-
-      if (deadlineMs !== undefined) {
-        entry.cancelDeadline = schedule(() => {
-          evict(key, entry);
-        }, deadlineMs);
-      }
-
-      const settled = (): void => {
-        entry.cancelDeadline();
-        evict(key, entry);
-      };
-      // A rejected load MUST clear too, or one failure is cached as a permanent rejection.
-      void running.then(settled, settled);
-
-      return running;
-    },
+    run,
   };
 }

package/src/source-mask.ts

@@ -147,8 +147,42 @@ function blankRegions(text: string, strings: boolean): string {
   return out.join('');
 }
 
+/**
+ * Held units per memo — key plus answer, twice the input — past which it is dropped whole: about
+ * 190 MB of RSS. Measured 2026-11-03 on the `errors` step, user CPU / RSS: no memo 32.2 s /
+ * 0.7 GB; 32M 21.9 s, too small for the step's working set; 64M 16.5-16.9 s / 0.89-1.15 GB;
+ * 128M 15.8 s / 1.14 GB.
+ */
+export const MASK_MEMO_CAP = 64 * 1024 * 1024;
+
+/**
+ * `mask` memoised on its input text. Every guard of the `errors` step re-masked every file: 74,031
+ * masks for 11,298 distinct inputs, 42% of its CPU. Cleared whole and not LRU, because a guard
+ * walks every file in order and an LRU smaller than the corpus misses on every call.
+ */
+export function memoText(
+  mask: (text: string) => string,
+  cap = MASK_MEMO_CAP,
+): (text: string) => string {
+  const memo = new Map<string, string>();
+  let held = 0;
+  return (text) => {
+    const known = memo.get(text);
+    if (known !== undefined) return known;
+    const out = mask(text);
+    // Key and answer are both held: twice the input, about 2.9 B of RSS per unit measured.
+    if (held + 2 * text.length > cap) {
+      memo.clear();
+      held = 0;
+    }
+    memo.set(text, out);
+    held += 2 * text.length;
+    return out;
+  };
+}
+
 /** Comments gone, string literals intact — what a scan for declared codes or `t()` keys reads. */
-export const stripComments = (text: string): string => blankRegions(text, false);
+export const stripComments = memoText((text) => blankRegions(text, false));
 
 /** Comments and string contents gone, delimiters kept — what a scan for code structure reads. */
-export const maskLiterals = (text: string): string => blankRegions(text, true);
+export const maskLiterals = memoText((text) => blankRegions(text, true));

package/src/tool-description.ts

@@ -0,0 +1,29 @@
+// The ONE description a projected tool carries: `@ultimat3/mcp`'s, `@ultimat3/ai`'s and
+// `@ultimat3/admin`'s, which the tier table keeps apart, so the rule lives here, never copied.
+
+import { describeDeclaredErrors } from './declared-errors';
+
+/** What a tool's description is read from — an action's, a query's, or a hand-built primitive's. */
+export interface ToolDescriptionSource {
+  readonly name: string;
+  readonly description?: string;
+  readonly mcp?: { readonly description?: string };
+  /** `false` for a read (a query). Absent counts as a write, as `toolFrom` meters it. */
+  readonly mutates?: boolean;
+}
+
+/**
+ * `mcp.description`, else the primitive's own `description`, else a default naming it — a read
+ * says it reads, so an agent never plans a write around one — then the declared `errors:`
+ * appended (`describeDeclaredErrors`), so an agent plans around a refusal.
+ */
+export function toolDescription(source: ToolDescriptionSource, errors?: readonly string[]): string {
+  const lead = source.mcp?.description ?? source.description ?? defaultLead(source);
+  return describeDeclaredErrors(lead, errors);
+}
+
+function defaultLead(source: ToolDescriptionSource): string {
+  return source.mutates === false
+    ? `Read with the "${source.name}" query.`
+    : `Run the "${source.name}" action.`;
+}

package/src/visible-interval.ts

@@ -0,0 +1,153 @@
+/**
+ * A poll that a hidden tab and a lost session both stop: the ONE timer for what has no changefeed,
+ * and for the safety re-read behind an at-most-once channel. Here, not in `@ultimat3/realtime`,
+ * because reaching realtime ships the whole page runtime to an island that only wanted a timer.
+ */
+
+import { backoffDelay, type Random } from './backoff';
+import { finiteOption, MAX_TIMER_MS } from './finite-option';
+import { whileSessionHeld } from './session-lost';
+
+export interface VisibleIntervalOptions {
+  /**
+   * Back off on failure: each failed run (a throw or a rejection) doubles the wait from `ms` up to
+   * `maxMs`, with equal jitter so a fleet of tabs does not ask in lockstep; a success resets it to
+   * `ms`. Without it every wait is `ms`, failed or not.
+   */
+  readonly maxMs?: number | undefined;
+}
+
+/** The tab, injected: timers and visibility. Internal; `visibleInterval` reads the real one. */
+export interface IntervalHost {
+  setTimer(fn: () => void, ms: number): unknown;
+  clearTimer(id: unknown): void;
+  isHidden(): boolean;
+  /** Subscribe to visibility changes; returns the unsubscribe. */
+  onVisibility(fn: () => void): () => void;
+  readonly random: Random;
+}
+
+const SUBJECT = 'visibleInterval';
+
+/**
+ * Call `run` every `ms` while the tab is shown. Hidden: no call; one make-up call when shown. An
+ * async `run` is never overlapped — the next wait starts when it settles; a throw or rejection is
+ * re-raised for the page's error hook. With `maxMs`, failures back off and a success resets.
+ * Stops on a session loss; starts afresh when a principal next signs in. Returns an idempotent
+ * disposer.
+ */
+export function visibleInterval(
+  run: () => unknown,
+  ms: number,
+  options: VisibleIntervalOptions = {},
+): () => void {
+  return visibleIntervalOn(browserHost(), run, ms, options);
+}
+
+/** `visibleInterval` over an injected tab. Internal: tests and `visibleInterval` call it. */
+export function visibleIntervalOn(
+  host: IntervalHost,
+  run: () => unknown,
+  ms: number,
+  options: VisibleIntervalOptions = {},
+): () => void {
+  const base = clampTimer(finiteOption(SUBJECT, 'ms', ms));
+  const max =
+    options.maxMs === undefined ? base : clampTimer(finiteOption(SUBJECT, 'maxMs', options.maxMs));
+  // Stopped by a session loss, started afresh — attempt 1 — by the next signed-in principal.
+  return whileSessionHeld(() => runLoop(host, run, base, max));
+}
+
+/** One session's loop: armed now, stopped by the returned function. */
+function runLoop(host: IntervalHost, run: () => unknown, base: number, max: number): () => void {
+  /** 1 + the failures since the last success: what `backoffDelay` grows the wait by. */
+  let attempt = 1;
+  let timer: unknown;
+  let owed = false;
+  let running = false;
+  let stopped = false;
+
+  const arm = (): void => {
+    if (stopped || running) return;
+    // Jitter spreads a fleet's RETRIES; a healthy poll's period is exactly what was asked for.
+    const wait =
+      attempt > 1 && max > base
+        ? backoffDelay({ attempt, base, max, jitter: 'equal', random: host.random })
+        : base;
+    timer = host.setTimer(tick, wait);
+  };
+  const call = (): void => {
+    running = true;
+    const settled = (failed: boolean): void => {
+      running = false;
+      attempt = failed ? attempt + 1 : 1;
+      arm();
+    };
+    // A failure is timed (it backs off) and then re-raised ONCE, off the loop's stack, so the loop
+    // survives and the page's error hook still sees what `run` did not catch. Never swallowed.
+    const failed = (error: unknown): void => {
+      settled(true);
+      queueMicrotask(() => {
+        throw error;
+      });
+    };
+    let result: unknown;
+    try {
+      result = run();
+    } catch (error) {
+      failed(error);
+      return;
+    }
+    if (result instanceof Promise) result.then(() => settled(false), failed);
+    else settled(false);
+  };
+  const tick = (): void => {
+    timer = undefined;
+    if (host.isHidden()) {
+      owed = true;
+      return;
+    }
+    call();
+  };
+  const visible = (): void => {
+    if (host.isHidden() || !owed) return;
+    owed = false;
+    call();
+  };
+
+  const offVisibility = host.onVisibility(visible);
+  const stop = (): void => {
+    if (stopped) return;
+    stopped = true;
+    if (timer !== undefined) host.clearTimer(timer);
+    timer = undefined;
+    offVisibility();
+  };
+  arm();
+  return stop;
+}
+
+/** A timer past 2^31-1 ms fires at once, and one under 1 ms is a spin. */
+function clampTimer(ms: number): number {
+  return Math.min(Math.max(1, ms), MAX_TIMER_MS);
+}
+
+type VisibilityDoc = {
+  readonly visibilityState?: string;
+  addEventListener?(type: string, fn: () => void): void;
+  removeEventListener?(type: string, fn: () => void): void;
+};
+
+function browserHost(): IntervalHost {
+  const doc: VisibilityDoc | undefined = Reflect.get(globalThis, 'document');
+  return {
+    setTimer: (fn, ms) => setTimeout(fn, ms),
+    clearTimer: (id) => clearTimeout(id as ReturnType<typeof setTimeout>),
+    isHidden: () => doc?.visibilityState === 'hidden',
+    onVisibility(fn) {
+      doc?.addEventListener?.('visibilitychange', fn);
+      return (): void => doc?.removeEventListener?.('visibilitychange', fn);
+    },
+    random: Math.random,
+  };
+}

package/src/webhook-signature.ts

@@ -2,15 +2,17 @@
 // three headers a delivery carries, and the parse of the one header a receiver reads back.
 //
 // It lives HERE for the reason `timing-safe-equal.ts` does, in that file's own words: two packages
-// need the identical guarantee and cannot share it any other way. `@ultimat3/jobs` (tier 3) signs
-// a delivery and its boundary forbids `@ultimat3/http`; `@ultimat3/http` (tier 2) verifies one and
-// may not reach tier 3. Neither is the other's dependency, so the one copy lives at the tier both
-// can reach. Before this module the spelling was stated twice and held together by a hex literal
-// asserted in two test files — which works and is not a single source of truth.
+// need the identical guarantee. `@ultimat3/jobs` (tier 3) signs a delivery; `@ultimat3/http`
+// (tier 2) verifies one and may not reach tier 3. `jobs` may import `http` (it does, for
+// `webhookReceiver()`'s route), but a sender's format is not the receiver's policy, so the format
+// sits below both and neither re-declares it. Before this module the spelling was stated twice and
+// held together by a hex literal asserted in two test files — not a single source of truth.
 //
 // FORMAT and never POLICY. What counts as fresh, how large a body may be, and which status a
 // refusal answers with are the receiver's questions and stay in `@ultimat3/http`.
 
+import { hmac } from './hmac';
+
 /** The format's version: the first field of the canonical string, and the signature's key. */
 export const WEBHOOK_SIGNATURE_VERSION = 'v1';
 
@@ -86,12 +88,8 @@ export interface WebhookMacInput {
 
 /** The hex hmac-sha256 over the canonical string. The one place either side computes one. */
 export function webhookMac(input: WebhookMacInput): string {
-  const hasher = new Bun.CryptoHasher('sha256', input.secret);
-  hasher.update(
-    `${WEBHOOK_SIGNATURE_VERSION}:${input.timestampText}:${input.eventId}:${input.topic}:`,
-  );
-  hasher.update(input.body);
-  return hasher.digest('hex');
+  const prefix = `${WEBHOOK_SIGNATURE_VERSION}:${input.timestampText}:${input.eventId}:${input.topic}:`;
+  return hmac('sha256', input.secret, [prefix, input.body], 'hex');
 }
 
 /**