@crewhaus/recovery-engine 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/recovery-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pure recovery taxonomy: classify Anthropic API errors into a RecoveryAction (compact/retry/continue/tombstone/fail)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/recovery-engine"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/recovery-engine#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/__fixtures__/errors.json

@@ -0,0 +1,98 @@
+[
+  {
+    "label": "real Anthropic 529 overloaded",
+    "shape": {
+      "name": "APIError",
+      "status": 529,
+      "error": { "type": "overloaded_error", "message": "Overloaded" },
+      "message": "529 Overloaded"
+    },
+    "expectedKind": "retry"
+  },
+  {
+    "label": "real Anthropic 503 service unavailable",
+    "shape": {
+      "name": "APIError",
+      "status": 503,
+      "error": { "type": "api_error", "message": "Service unavailable" },
+      "message": "503 Service Unavailable"
+    },
+    "expectedKind": "retry"
+  },
+  {
+    "label": "real Anthropic 500 internal error",
+    "shape": {
+      "name": "APIError",
+      "status": 500,
+      "error": { "type": "api_error", "message": "Internal server error" },
+      "message": "500 Internal Server Error"
+    },
+    "expectedKind": "retry"
+  },
+  {
+    "label": "real Anthropic prompt too long (400 + invalid_request_error w/ message hint)",
+    "shape": {
+      "name": "BadRequestError",
+      "status": 400,
+      "error": {
+        "type": "invalid_request_error",
+        "message": "Prompt is too long: 220000 tokens > 200000 maximum"
+      },
+      "message": "400 Prompt is too long: 220000 tokens > 200000 maximum"
+    },
+    "expectedKind": "compact"
+  },
+  {
+    "label": "real Anthropic generic 400 invalid_request",
+    "shape": {
+      "name": "BadRequestError",
+      "status": 400,
+      "error": { "type": "invalid_request_error", "message": "messages.0: invalid block" },
+      "message": "400 Bad Request"
+    },
+    "expectedKind": "tombstone"
+  },
+  {
+    "label": "synthetic max_output_tokens (caller fabricates after stop_reason)",
+    "shape": {
+      "name": "Error",
+      "error": { "type": "max_output_tokens", "message": "stop_reason was max_tokens" },
+      "message": "max output tokens reached"
+    },
+    "expectedKind": "continue"
+  },
+  {
+    "label": "user-aborted via APIUserAbortError",
+    "shape": {
+      "name": "APIUserAbortError",
+      "message": "Request was aborted"
+    },
+    "expectedKind": "fail"
+  },
+  {
+    "label": "user-aborted via AbortError",
+    "shape": {
+      "name": "AbortError",
+      "message": "The operation was aborted"
+    },
+    "expectedKind": "fail"
+  },
+  {
+    "label": "unknown TypeError",
+    "shape": {
+      "name": "TypeError",
+      "message": "Cannot read properties of undefined"
+    },
+    "expectedKind": "fail"
+  },
+  {
+    "label": "real Anthropic 401 unauthorized (treated as unknown → fail)",
+    "shape": {
+      "name": "AuthenticationError",
+      "status": 401,
+      "error": { "type": "authentication_error", "message": "invalid x-api-key" },
+      "message": "401 Unauthorized"
+    },
+    "expectedKind": "fail"
+  }
+]

package/src/index.test.ts

@@ -0,0 +1,289 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  BUDGETS,
+  type NamedFailureClass,
+  type RecoveryAction,
+  advanceState,
+  backoffMs,
+  classify,
+  initialRecoveryState,
+  matchNamedFailure,
+  recover,
+} from "./index";
+
+describe("classify", () => {
+  test("531/529/500 → overloaded_or_5xx", () => {
+    expect(classify({ status: 503, message: "x" })).toBe("overloaded_or_5xx");
+    expect(classify({ status: 529, message: "x" })).toBe("overloaded_or_5xx");
+    expect(classify({ status: 500, message: "x" })).toBe("overloaded_or_5xx");
+  });
+
+  test("type: overloaded_error wins regardless of status", () => {
+    expect(classify({ status: 200, error: { type: "overloaded_error" }, message: "x" })).toBe(
+      "overloaded_or_5xx",
+    );
+  });
+
+  test("400 invalid_request → invalid_request", () => {
+    expect(
+      classify({
+        status: 400,
+        error: { type: "invalid_request_error", message: "bad" },
+        message: "bad",
+      }),
+    ).toBe("invalid_request");
+  });
+
+  test('"Prompt is too long" inside a 400 → prompt_too_long, not invalid_request', () => {
+    expect(
+      classify({
+        status: 400,
+        error: { type: "invalid_request_error", message: "Prompt is too long: 220k > 200k" },
+        message: "Prompt is too long",
+      }),
+    ).toBe("prompt_too_long");
+  });
+
+  test("synthetic max_output_tokens → max_output_tokens", () => {
+    expect(classify({ error: { type: "max_output_tokens" }, message: "stopped" })).toBe(
+      "max_output_tokens",
+    );
+  });
+
+  test("APIUserAbortError / AbortError → user_aborted", () => {
+    expect(classify({ name: "APIUserAbortError", message: "aborted" })).toBe("user_aborted");
+    expect(classify({ name: "AbortError", message: "aborted" })).toBe("user_aborted");
+  });
+
+  test("unknown shapes → unknown", () => {
+    expect(classify(null)).toBe("unknown");
+    expect(classify(undefined)).toBe("unknown");
+    expect(classify({})).toBe("unknown");
+    expect(classify({ status: 401, message: "auth" })).toBe("unknown");
+  });
+});
+
+describe("recover — happy paths", () => {
+  test("prompt_too_long → compact", () => {
+    const action = recover(
+      {
+        status: 400,
+        error: { type: "invalid_request_error", message: "Prompt is too long" },
+        message: "Prompt is too long",
+      },
+      initialRecoveryState,
+    );
+    expect(action).toEqual({ kind: "compact" });
+  });
+
+  test("max_output_tokens → continue", () => {
+    const action = recover(
+      { error: { type: "max_output_tokens" }, message: "stopped" },
+      initialRecoveryState,
+    );
+    expect(action).toEqual({ kind: "continue" });
+  });
+
+  test("5xx → retry with first-attempt backoff in [1000, 1250]", () => {
+    const action = recover({ status: 503, message: "boom" }, initialRecoveryState);
+    expect(action.kind).toBe("retry");
+    if (action.kind !== "retry") return;
+    expect(action.attempt).toBe(1);
+    expect(action.delayMs).toBeGreaterThanOrEqual(1000);
+    expect(action.delayMs).toBeLessThanOrEqual(1250);
+  });
+
+  test("invalid_request → tombstone", () => {
+    const action = recover(
+      {
+        status: 400,
+        error: { type: "invalid_request_error", message: "bad block" },
+        message: "bad block",
+      },
+      initialRecoveryState,
+    );
+    expect(action).toEqual({ kind: "tombstone" });
+  });
+
+  test("user_aborted → fail with reason 'user_aborted'", () => {
+    const action = recover({ name: "APIUserAbortError", message: "aborted" }, initialRecoveryState);
+    expect(action).toEqual({ kind: "fail", reason: "user_aborted" });
+  });
+
+  test("unknown → fail with the original message", () => {
+    const action = recover({ name: "TypeError", message: "boom" }, initialRecoveryState);
+    expect(action).toEqual({ kind: "fail", reason: "boom" });
+  });
+});
+
+describe("recover — budget exhaustion", () => {
+  test("retry exhausts after MAX_RETRIES", () => {
+    const state = { ...initialRecoveryState, retryCount: BUDGETS.MAX_RETRIES };
+    const action = recover({ status: 503, message: "boom" }, state);
+    expect(action.kind).toBe("fail");
+  });
+
+  test("compact exhausts after MAX_COMPACTS", () => {
+    const state = { ...initialRecoveryState, compactCount: BUDGETS.MAX_COMPACTS };
+    const action = recover(
+      {
+        status: 400,
+        error: { type: "invalid_request_error", message: "Prompt is too long" },
+        message: "Prompt is too long",
+      },
+      state,
+    );
+    expect(action.kind).toBe("fail");
+  });
+
+  test("continue exhausts after MAX_CONTINUES", () => {
+    const state = { ...initialRecoveryState, continueCount: BUDGETS.MAX_CONTINUES };
+    const action = recover({ error: { type: "max_output_tokens" }, message: "x" }, state);
+    expect(action.kind).toBe("fail");
+  });
+
+  test("tombstone exhausts after MAX_TOMBSTONES", () => {
+    const state = { ...initialRecoveryState, tombstoneCount: BUDGETS.MAX_TOMBSTONES };
+    const action = recover(
+      {
+        status: 400,
+        error: { type: "invalid_request_error", message: "bad" },
+        message: "bad",
+      },
+      state,
+    );
+    expect(action.kind).toBe("fail");
+  });
+});
+
+describe("backoffMs", () => {
+  test("monotonic non-decreasing across attempts (with jitter=0)", () => {
+    const zero = () => 0;
+    const a0 = backoffMs(0, zero);
+    const a1 = backoffMs(1, zero);
+    const a2 = backoffMs(2, zero);
+    const a3 = backoffMs(3, zero);
+    expect(a0).toBeLessThanOrEqual(a1);
+    expect(a1).toBeLessThanOrEqual(a2);
+    expect(a2).toBeLessThanOrEqual(a3);
+  });
+
+  test("jitter stays within [0, 250]", () => {
+    for (let i = 0; i < 100; i++) {
+      const ms = backoffMs(0); // attempt 0 → exp = 1000
+      expect(ms).toBeGreaterThanOrEqual(1000);
+      expect(ms).toBeLessThanOrEqual(1250);
+    }
+  });
+
+  test("caps at MAX_BACKOFF_MS + jitter", () => {
+    const ms = backoffMs(20, () => 1); // 1000 * 2^20 → capped to 30_000, plus jitter 250
+    expect(ms).toBeLessThanOrEqual(BUDGETS.MAX_BACKOFF_MS + BUDGETS.MAX_JITTER_MS);
+  });
+});
+
+describe("advanceState", () => {
+  test("retry increments retryCount", () => {
+    const after = advanceState(initialRecoveryState, {
+      kind: "retry",
+      delayMs: 1000,
+      attempt: 1,
+    });
+    expect(after.retryCount).toBe(1);
+  });
+
+  test("compact/continue/tombstone increment their respective counters", () => {
+    const a = advanceState(initialRecoveryState, { kind: "compact" });
+    expect(a.compactCount).toBe(1);
+    const b = advanceState(initialRecoveryState, { kind: "continue" });
+    expect(b.continueCount).toBe(1);
+    const c = advanceState(initialRecoveryState, { kind: "tombstone" });
+    expect(c.tombstoneCount).toBe(1);
+  });
+
+  test("fail leaves state unchanged", () => {
+    const after = advanceState(initialRecoveryState, { kind: "fail", reason: "boom" });
+    expect(after).toEqual(initialRecoveryState);
+  });
+});
+
+// T4: replay over fixture file. Each entry has an expected action kind; we
+// confirm classify() + recover() agree against an initial state.
+describe("T4 — fixture replay", () => {
+  type Fixture = {
+    label: string;
+    shape: unknown;
+    expectedKind: RecoveryAction["kind"];
+  };
+  // `tsc -b` also compiles this file into `dist/`; resolve fixtures from the
+  // source tree so both the src and dist test copies find errors.json.
+  const SRC_DIR = import.meta.dir.replace(/([/\\])dist$/, "$1src");
+  const fixturesPath = join(SRC_DIR, "__fixtures__", "errors.json");
+  const fixtures = JSON.parse(readFileSync(fixturesPath, "utf-8")) as Fixture[];
+
+  for (const f of fixtures) {
+    test(`${f.label} → action.kind === "${f.expectedKind}"`, () => {
+      const action = recover(f.shape, initialRecoveryState);
+      expect(action.kind).toBe(f.expectedKind);
+    });
+  }
+});
+
+// Section 55 (Track A) — named failure taxonomy. The recovery engine
+// consults user-declared classes before falling back to the built-in
+// taxonomy. Source: NLAH (arxiv 2603.25723).
+describe("Track A — named failure taxonomy", () => {
+  const taxonomy: NamedFailureClass[] = [
+    { class: "missing_artifact", pattern: "ENOENT", recovery: "tombstone" },
+    { class: "verifier_failure", pattern: "verification failed", recovery: "continue" },
+    { class: "rate_limit_429", pattern: "/^429\\b/", recovery: "retry" },
+  ];
+
+  test("substring pattern matches a named class", () => {
+    const matched = matchNamedFailure({ message: "ENOENT: no such file or directory" }, taxonomy);
+    expect(matched?.class).toBe("missing_artifact");
+  });
+
+  test("regex pattern matches a named class", () => {
+    const matched = matchNamedFailure({ message: "429 too many requests" }, taxonomy);
+    expect(matched?.class).toBe("rate_limit_429");
+  });
+
+  test("case-insensitive substring match", () => {
+    const matched = matchNamedFailure({ message: "Verification Failed: bad output" }, taxonomy);
+    expect(matched?.class).toBe("verifier_failure");
+  });
+
+  test("returns undefined when no entry matches", () => {
+    expect(matchNamedFailure({ message: "completely unrelated" }, taxonomy)).toBeUndefined();
+  });
+
+  test("recover() uses named-class recovery when matched", () => {
+    const action = recover({ message: "ENOENT bad path" }, initialRecoveryState, taxonomy);
+    expect(action.kind).toBe("tombstone");
+  });
+
+  test("recover() falls through to built-in classify when no named match", () => {
+    const action = recover({ status: 503, message: "overloaded" }, initialRecoveryState, taxonomy);
+    expect(action.kind).toBe("retry");
+  });
+
+  test("named-class recovery respects per-turn budgets", () => {
+    const exhausted = { ...initialRecoveryState, tombstoneCount: BUDGETS.MAX_TOMBSTONES };
+    const action = recover({ message: "ENOENT bad path" }, exhausted, taxonomy);
+    expect(action.kind).toBe("fail");
+    if (action.kind === "fail") {
+      expect(action.reason).toContain("missing_artifact");
+    }
+  });
+
+  test("malformed regex pattern is skipped without throwing", () => {
+    const badTaxonomy: NamedFailureClass[] = [
+      { class: "bad", pattern: "/[unclosed/", recovery: "fail" },
+    ];
+    expect(() => matchNamedFailure({ message: "anything" }, badTaxonomy)).not.toThrow();
+    expect(matchNamedFailure({ message: "anything" }, badTaxonomy)).toBeUndefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,302 @@
+/**
+ * Catalog R1 `recovery-engine` — pure decision function that maps an
+ * Anthropic API error + per-turn recovery state to a `RecoveryAction`.
+ * No I/O. The orchestrator (runtime-core) is responsible for *executing*
+ * the chosen action (sleeping, recompacting, injecting messages).
+ *
+ * Taxonomy:
+ *   prompt_too_long      → compact   (max once per turn → fail)
+ *   max_output_tokens    → continue  (max 3 per turn   → fail)
+ *   overloaded / 5xx     → retry     (exponential backoff, max 5 → fail)
+ *   invalid_request 400  → tombstone (max once per turn → fail)
+ *   user-aborted         → fail("user_aborted")  — orchestrator handles abort separately
+ *   anything else        → fail(message)
+ *
+ * References: claude-code/query.ts recovery branches; agent-framework
+ * _runner.py retry; AI-Harness-Systems §recovery.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+
+export type RecoveryAction =
+  | { readonly kind: "compact" }
+  | { readonly kind: "retry"; readonly delayMs: number; readonly attempt: number }
+  | { readonly kind: "continue" }
+  | { readonly kind: "tombstone"; readonly messageId?: string }
+  | { readonly kind: "fail"; readonly reason: string };
+
+export type RecoveryErrorClass =
+  | "prompt_too_long"
+  | "max_output_tokens"
+  | "overloaded_or_5xx"
+  | "invalid_request"
+  | "user_aborted"
+  | "unknown";
+
+export type RecoveryState = {
+  /** Number of `retry` actions already chosen in this turn. */
+  readonly retryCount: number;
+  /** Number of `compact` actions already chosen in this turn. */
+  readonly compactCount: number;
+  /** Number of `continue` actions already chosen in this turn. */
+  readonly continueCount: number;
+  /** Number of `tombstone` actions already chosen in this turn. */
+  readonly tombstoneCount: number;
+};
+
+export const initialRecoveryState: RecoveryState = {
+  retryCount: 0,
+  compactCount: 0,
+  continueCount: 0,
+  tombstoneCount: 0,
+};
+
+export class RecoveryEngineError extends CrewhausError {
+  override readonly name = "RecoveryEngineError";
+  constructor(message: string, cause?: unknown) {
+    super("runtime", message, cause);
+  }
+}
+
+const MAX_RETRIES = 5;
+const MAX_COMPACTS = 1;
+const MAX_CONTINUES = 3;
+const MAX_TOMBSTONES = 1;
+
+const BASE_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+const MAX_JITTER_MS = 250;
+
+/**
+ * Compute exponential-backoff delay for the Nth retry (0-indexed): 1 s, 2 s,
+ * 4 s, ..., capped at 30 s, plus 0–250 ms of jitter.
+ */
+export function backoffMs(attempt: number, jitterFn: () => number = Math.random): number {
+  const exp = Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+  // Clamp into [0, MAX_JITTER_MS] so the contract holds even if a test injects
+  // a jitterFn that returns exactly 1.0 (Math.random itself returns [0, 1)).
+  const jitter = Math.min(Math.floor(jitterFn() * (MAX_JITTER_MS + 1)), MAX_JITTER_MS);
+  return exp + jitter;
+}
+
+/**
+ * Classify an unknown error value into a recovery taxonomy bucket. Duck-typed
+ * against the Anthropic SDK error shape: `.status`, `.error.type`, `.message`,
+ * plus the SDK's `name === "APIUserAbortError"` or `"AbortError"` for aborts.
+ *
+ * Synthetic max-output-tokens errors should carry `error.type === "max_output_tokens"`
+ * (the SDK doesn't throw on stop_reason — the caller fabricates an Error with
+ * that shape after seeing `stop_reason: "max_tokens"`).
+ */
+export function classify(error: unknown): RecoveryErrorClass {
+  if (error === null || error === undefined) return "unknown";
+
+  const errObj = error as {
+    name?: unknown;
+    status?: unknown;
+    message?: unknown;
+    error?: { type?: unknown; message?: unknown };
+  };
+
+  // Aborts come through with name === "APIUserAbortError" or "AbortError".
+  if (typeof errObj.name === "string") {
+    if (errObj.name === "APIUserAbortError" || errObj.name === "AbortError") {
+      return "user_aborted";
+    }
+  }
+
+  const innerType = typeof errObj.error?.type === "string" ? errObj.error.type : undefined;
+  const message = typeof errObj.message === "string" ? errObj.message : "";
+  const status = typeof errObj.status === "number" ? errObj.status : undefined;
+
+  if (innerType === "max_output_tokens") return "max_output_tokens";
+
+  // Anthropic returns "Prompt is too long" inside invalid_request_error responses;
+  // distinguish from generic invalid_request by sniffing the message.
+  if (innerType === "invalid_request_error" && /prompt is too long|input length/i.test(message)) {
+    return "prompt_too_long";
+  }
+
+  if (innerType === "overloaded_error") return "overloaded_or_5xx";
+  if (status !== undefined && status >= 500 && status < 600) return "overloaded_or_5xx";
+  if (status === 529) return "overloaded_or_5xx";
+
+  if (innerType === "invalid_request_error" || status === 400) return "invalid_request";
+
+  return "unknown";
+}
+
+/**
+ * Section 55 (Track A) — a single entry from a spec's `failure_taxonomy`,
+ * carried verbatim from the IR. The recovery engine consults the taxonomy
+ * BEFORE falling back to its built-in classify+recover logic so user-
+ * named classes take precedence. Cited paper: NLAH (arxiv 2603.25723).
+ */
+export type NamedFailureClass = {
+  readonly class: string;
+  readonly pattern: string;
+  readonly recovery: "retry" | "compact" | "continue" | "tombstone" | "fail";
+  readonly hint?: string;
+};
+
+/**
+ * Match an unknown error against a taxonomy entry's `pattern`. The pattern
+ * is either a `/regex/flags` literal or a case-insensitive substring of
+ * the error.message. Returns the first matching entry, or undefined.
+ */
+export function matchNamedFailure(
+  error: unknown,
+  taxonomy: ReadonlyArray<NamedFailureClass>,
+): NamedFailureClass | undefined {
+  const message =
+    typeof (error as { message?: unknown })?.message === "string"
+      ? (error as { message: string }).message
+      : "";
+  if (message.length === 0) return undefined;
+  for (const entry of taxonomy) {
+    const p = entry.pattern;
+    if (p.length > 2 && p.startsWith("/") && p.lastIndexOf("/") > 0) {
+      const lastSlash = p.lastIndexOf("/");
+      const body = p.slice(1, lastSlash);
+      const flags = p.slice(lastSlash + 1);
+      let re: RegExp;
+      try {
+        re = new RegExp(body, flags);
+      } catch {
+        continue;
+      }
+      if (re.test(message)) return entry;
+    } else {
+      if (message.toLowerCase().includes(p.toLowerCase())) return entry;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Decide what to do about `error` given the per-turn recovery state. Pure.
+ * Each call returns a single action; the caller advances state.
+ *
+ * When `taxonomy` is provided, named classes take precedence over the
+ * built-in classify+recover taxonomy. A named match returns its declared
+ * `recovery` action directly (subject to the same per-turn budgets as
+ * built-in classes). Unmatched errors fall through to the built-in flow.
+ */
+export function recover(
+  error: unknown,
+  state: RecoveryState,
+  taxonomy?: ReadonlyArray<NamedFailureClass>,
+): RecoveryAction {
+  if (taxonomy !== undefined && taxonomy.length > 0) {
+    const named = matchNamedFailure(error, taxonomy);
+    if (named !== undefined) {
+      return recoverNamed(named, state);
+    }
+  }
+  const klass = classify(error);
+  const message = (error as { message?: unknown })?.message;
+  const reasonStr = typeof message === "string" && message.length > 0 ? message : klass;
+
+  switch (klass) {
+    case "prompt_too_long":
+      if (state.compactCount >= MAX_COMPACTS) {
+        return { kind: "fail", reason: `compact budget exhausted: ${reasonStr}` };
+      }
+      return { kind: "compact" };
+
+    case "max_output_tokens":
+      if (state.continueCount >= MAX_CONTINUES) {
+        return { kind: "fail", reason: `continue budget exhausted: ${reasonStr}` };
+      }
+      return { kind: "continue" };
+
+    case "overloaded_or_5xx":
+      if (state.retryCount >= MAX_RETRIES) {
+        return { kind: "fail", reason: `retry budget exhausted: ${reasonStr}` };
+      }
+      return {
+        kind: "retry",
+        delayMs: backoffMs(state.retryCount),
+        attempt: state.retryCount + 1,
+      };
+
+    case "invalid_request":
+      if (state.tombstoneCount >= MAX_TOMBSTONES) {
+        return { kind: "fail", reason: `tombstone budget exhausted: ${reasonStr}` };
+      }
+      return { kind: "tombstone" };
+
+    case "user_aborted":
+      return { kind: "fail", reason: "user_aborted" };
+
+    case "unknown":
+      return { kind: "fail", reason: reasonStr };
+  }
+}
+
+/**
+ * Convert a matched named-failure entry into the corresponding
+ * RecoveryAction, respecting the same per-turn budgets as built-in
+ * classes. Budget exhaustion always returns `fail` so the user can't
+ * declare an infinite retry loop via taxonomy.
+ */
+function recoverNamed(named: NamedFailureClass, state: RecoveryState): RecoveryAction {
+  const reason = `failure_taxonomy: ${named.class}`;
+  switch (named.recovery) {
+    case "retry":
+      if (state.retryCount >= MAX_RETRIES) {
+        return { kind: "fail", reason: `retry budget exhausted: ${reason}` };
+      }
+      return {
+        kind: "retry",
+        delayMs: backoffMs(state.retryCount),
+        attempt: state.retryCount + 1,
+      };
+    case "compact":
+      if (state.compactCount >= MAX_COMPACTS) {
+        return { kind: "fail", reason: `compact budget exhausted: ${reason}` };
+      }
+      return { kind: "compact" };
+    case "continue":
+      if (state.continueCount >= MAX_CONTINUES) {
+        return { kind: "fail", reason: `continue budget exhausted: ${reason}` };
+      }
+      return { kind: "continue" };
+    case "tombstone":
+      if (state.tombstoneCount >= MAX_TOMBSTONES) {
+        return { kind: "fail", reason: `tombstone budget exhausted: ${reason}` };
+      }
+      return { kind: "tombstone" };
+    case "fail":
+      return { kind: "fail", reason };
+  }
+}
+
+/**
+ * Helper for the orchestrator: advance recovery state by one chosen action.
+ * Pure; returns a new state.
+ */
+export function advanceState(state: RecoveryState, action: RecoveryAction): RecoveryState {
+  switch (action.kind) {
+    case "retry":
+      return { ...state, retryCount: state.retryCount + 1 };
+    case "compact":
+      return { ...state, compactCount: state.compactCount + 1 };
+    case "continue":
+      return { ...state, continueCount: state.continueCount + 1 };
+    case "tombstone":
+      return { ...state, tombstoneCount: state.tombstoneCount + 1 };
+    case "fail":
+      return state;
+  }
+}
+
+/** Budget constants exported so the orchestrator and tests stay in sync. */
+export const BUDGETS = {
+  MAX_RETRIES,
+  MAX_COMPACTS,
+  MAX_CONTINUES,
+  MAX_TOMBSTONES,
+  BASE_BACKOFF_MS,
+  MAX_BACKOFF_MS,
+  MAX_JITTER_MS,
+} as const;