@humwick/server 0.130.1 → 0.130.2

package/node_modules/@humwick/offload/src/types.ts

@@ -1,235 +0,0 @@
-import { errMessage } from "@humwick/sdk";
-
-export type OffloadErrorKind = "timeout" | "aborted" | "worker-error" | "worker-exit" | "rejected";
-
-/** A stable, backend-independent failure surface for callers and escalation sinks. */
-export class OffloadError extends Error {
-  readonly kind: OffloadErrorKind;
-  readonly code?: string;
-  readonly taskName: string;
-
-  constructor(options: {
-    kind: OffloadErrorKind;
-    taskName: string;
-    code?: string;
-    message?: string;
-    cause?: unknown;
-  }) {
-    super(options.message ?? `${options.taskName} ${options.kind}`, { cause: options.cause });
-    this.name = "OffloadError";
-    this.kind = options.kind;
-    this.code = options.code;
-    this.taskName = options.taskName;
-  }
-}
-
-export type OffloadLogFields = Record<string, unknown>;
-
-/** Deliberately structural: server, runner and orchestrator can pass their existing logger adapters. */
-export interface OffloadLogger {
-  debug?(message: string, fields?: OffloadLogFields): void;
-  info?(message: string, fields?: OffloadLogFields): void;
-  warn?(message: string, fields?: OffloadLogFields): void;
-  error?(message: string, fields?: OffloadLogFields): void;
-}
-
-export interface EscalationEvent {
-  taskName: string;
-  backend: "worker" | "async" | "subprocess";
-  error: OffloadError;
-  strikes: number;
-  labels: Record<string, string>;
-}
-
-export type EscalationSink = (event: EscalationEvent) => void | Promise<void>;
-
-/** The common per-run contract. No backend-specific options leak into this envelope. */
-export interface OffloadEnvelope {
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  logger?: OffloadLogger;
-  labels?: Record<string, string>;
-  onEscalate?: EscalationSink;
-  /**
-   * Opt in to automatic re-dispatch after an ambiguous worker death (WorkerPool only; the async
-   * and subprocess runners never re-run). Default is AT-MOST-ONCE: if the worker dies with this
-   * job in flight, the job is rejected (`worker-exit`) and never re-run — because a re-run would
-   * repeat any side effect the job already performed (an HTTP POST, a mutation). Set this ONLY
-   * when the job is idempotent/retry-safe (pure compute), in which case a worker death is
-   * absorbed by re-dispatching to a fresh worker up to a bounded number of times (#1822 HIGH-1).
-   * Command/handler offload (side-effecting) must leave this unset.
-   */
-  retrySafe?: boolean;
-}
-
-export interface OffloadDefaults {
-  defaultTimeoutMs?: number;
-  logger?: OffloadLogger;
-  onEscalate?: EscalationSink;
-  /** Consecutive failed runs for a task before its injected sink fires. Defaults to 3. */
-  escalationThreshold?: number;
-  /**
-   * Size, in failure-attempts, of the sliding window the strike counter escalates over: a task
-   * escalates when it accumulates `escalationThreshold` failures within this many consecutive
-   * failure-attempts (counted across ALL tasks). A task with no failure inside the window is
-   * forgotten, which is ALSO what bounds memory — the counter holds at most this many failure
-   * events, so at most this many distinct names, at once (#1822 items 1 and 4). Adoption keys
-   * runs by dynamic names (workspace/agent ids); the window is what keeps that from growing
-   * without bound. Defaults to 4096.
-   */
-  escalationWindowAttempts?: number;
-}
-
-/**
- * Sliding-window failure counter driving edge-triggered escalation (#1822 F1/F4, round-3
- * redesign). A task escalates when it accumulates `threshold` failures within the last
- * `window` failure-attempts (counted across all tasks); a failure older than the window no
- * longer counts. This is attempt-based — no wall-clock, no timers — so it is deterministic and
- * needs no time injection to test.
- *
- * WHY windowed rather than a size-capped consecutive counter: any hard *count* cap on a
- * consecutive-strike map either scans the map per failure (O(cap); an earlier attempt blocked
- * the event loop ~11s at 40k / ~31s at 100k distinct failures) or silently drops a task that is
- * genuinely accumulating (a missed page — strictly worse than the leak it replaced). The window
- * gives all four invariants at once: no lost escalation, no page storm, amortized O(1) per
- * failure, and a hard memory bound.
- *
- * IMPLEMENTATION — the standard sliding-window multiset over a ring of failure events:
- *  - `#ring[(clock-1) % window]` holds the failure event `window` attempts ago. Each new failure
- *    overwrites exactly that slot, and the event it evicts is exactly the one aging out — so a
- *    failure is pushed once and expired once: amortized O(1), never a scan.
- *  - `#live[name]` is the name's failure count still inside the window = its escalation score.
- *  - Memory is hard-bounded: the ring holds ≤ `window` events, hence ≤ `window` distinct names.
- *  - `succeed()` bumps a per-name `#epoch`; events carry the epoch they were recorded under, so a
- *    success invalidates the name's in-window failures (score resets) in O(1) without scanning
- *    the ring — the stale events simply don't count as they age out.
- *  - Latch (`trip`): a per-name flag so an escalation fires ONCE and does not re-fire while the
- *    task stays continuously failing; it clears when the task succeeds or every failure ages out.
- *
- * SEMANTIC NOTE (deliberate change from the first #1822 attempt): escalation is now "threshold
- * failures WITHIN the window", not "threshold consecutive failures ever". Failures spread wider
- * apart than the window decay and never trip — which is the actual flap-detection semantic.
- */
-export class StrikeCounter {
-  #ring: Array<{ name: string; epoch: number } | undefined>;
-  /** Failures still inside the window under the name's CURRENT epoch = its escalation score. */
-  #live = new Map<string, number>();
-  /** Total ring occurrences per name across all epochs — for O(1) cleanup and the memory bound. */
-  #present = new Map<string, number>();
-  /** Per-name epoch, bumped by succeed() so pre-success failures stop counting. */
-  #epoch = new Map<string, number>();
-  /** Names that have escalated and not yet re-armed (edge-trigger latch). */
-  #latched = new Set<string>();
-  #clock = 0;
-  readonly threshold: number;
-  readonly window: number;
-
-  constructor(threshold = 3, escalationWindowAttempts = 4096) {
-    if (!Number.isSafeInteger(threshold) || threshold < 1) throw new RangeError("escalationThreshold must be a positive integer");
-    if (!Number.isSafeInteger(escalationWindowAttempts) || escalationWindowAttempts < 1) throw new RangeError("escalationWindowAttempts must be a positive integer");
-    // A window smaller than the threshold can never hold `threshold` of one name's failures at
-    // once (the ring evicts the oldest before the count gets there), so it would score 1,2,…,
-    // threshold-1 forever and SILENTLY never escalate. Reject it rather than mislead (#1822 LOW-4).
-    if (escalationWindowAttempts < threshold) throw new RangeError("escalationWindowAttempts must be >= escalationThreshold");
-    this.threshold = threshold;
-    this.window = escalationWindowAttempts;
-    this.#ring = new Array(escalationWindowAttempts).fill(undefined);
-  }
-
-  /** Distinct task names with a failure still inside the window. Bounded by `window`. */
-  get size(): number {
-    return this.#present.size;
-  }
-
-  // Removes the event in `slot` (the one aging out of the window) and updates the name's counts.
-  #expire(slot: number): void {
-    const event = this.#ring[slot];
-    if (event === undefined) return;
-    this.#ring[slot] = undefined;
-    const { name, epoch } = event;
-    // Only decrement the score if the event is still under the name's live epoch; an event from
-    // before a succeed() carries a stale epoch and was never counted toward the current score.
-    if (epoch === (this.#epoch.get(name) ?? 0)) {
-      const live = (this.#live.get(name) ?? 0) - 1;
-      if (live <= 0) { this.#live.delete(name); this.#latched.delete(name); }
-      else this.#live.set(name, live);
-    }
-    const present = (this.#present.get(name) ?? 0) - 1;
-    if (present <= 0) {
-      // Every trace of the name has aged out of the window: forget it entirely (this is the
-      // natural memory bound, and it re-arms a latch that went quiet).
-      this.#present.delete(name);
-      this.#epoch.delete(name);
-      this.#live.delete(name);
-      this.#latched.delete(name);
-    } else {
-      this.#present.set(name, present);
-    }
-  }
-
-  fail(taskName: string): number {
-    this.#clock += 1;
-    const slot = (this.#clock - 1) % this.window;
-    // The event this slot holds is exactly `window` attempts old — evict it before reusing it.
-    this.#expire(slot);
-    const epoch = this.#epoch.get(taskName) ?? 0;
-    this.#ring[slot] = { name: taskName, epoch };
-    this.#present.set(taskName, (this.#present.get(taskName) ?? 0) + 1);
-    const score = (this.#live.get(taskName) ?? 0) + 1;
-    this.#live.set(taskName, score);
-    // A latched name must not re-page while it stays continuously live.
-    if (this.#latched.has(taskName)) return 0;
-    return score;
-  }
-
-  /** Latch an escalation so it fires once until the task re-arms (succeeds or ages out). */
-  trip(taskName: string): void {
-    // Latch ONLY a name that has a failure in the window. Otherwise a caller (or a bug) tripping
-    // arbitrary names would grow #latched without any ring presence to age it out — breaking the
-    // "memory bounded BY the window" invariant, since `size` counts only #present (#1822 MED-3).
-    // In practice trip() is always called right after fail() returned >= threshold, so the name
-    // is present; this guard just makes the bound hold unconditionally.
-    if (this.#present.has(taskName)) this.#latched.add(taskName);
-  }
-
-  succeed(taskName: string): void {
-    // Nothing tracked → nothing to reset (and never create an epoch entry for a name that only
-    // ever succeeds, which would leak one map entry per distinct successful task name).
-    if (!this.#present.has(taskName)) return;
-    // Bump the epoch: every in-window failure recorded under the old epoch stops counting, so
-    // the score resets to 0 in O(1). The stale ring events are reclaimed as they age out.
-    this.#epoch.set(taskName, (this.#epoch.get(taskName) ?? 0) + 1);
-    this.#live.delete(taskName);
-    this.#latched.delete(taskName);
-  }
-}
-
-export function normalizeError(taskName: string, error: unknown, fallback: OffloadErrorKind = "rejected"): OffloadError {
-  if (error instanceof OffloadError) return error;
-  const detail = error as { code?: unknown; message?: unknown } | undefined;
-  return new OffloadError({
-    kind: fallback,
-    taskName,
-    code: typeof detail?.code === "string" ? detail.code : undefined,
-    message: errMessage(error),
-    cause: error,
-  });
-}
-
-export function log(logger: OffloadLogger | undefined, level: keyof OffloadLogger, message: string, fields: OffloadLogFields): void {
-  const method = logger?.[level];
-  if (typeof method !== "function") return;
-  try {
-    method.call(logger, message, fields);
-  } catch {
-    // A caller-supplied transport that throws must never break the run it is describing:
-    // logging happens on the settle path, so an escaping throw wedges the backend (#1809 P0-1).
-    // There is no second transport to report this to, so it is deliberately swallowed.
-  }
-}
-
-export function validateTimeout(timeoutMs: number | undefined): number | undefined {
-  if (timeoutMs === undefined) return undefined;
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new RangeError("timeoutMs must be a positive finite number");
-  return timeoutMs;
-}