dsh-expert-group 0.1.1

package/host/persistence-health.js

@@ -0,0 +1,389 @@
+/**
+ * 持久化旁路健康状态。
+ *
+ * 该模块只维护内存中的可观察状态，不写 storage、不触发回调，也不持有 manager 句柄。
+ * 失败记录因此不会重新进入持久化链；Host 可以在外层使用 retryDecision 做有界重试。
+ */
+
+export const PERSISTENCE_FAILURE_CATEGORIES = Object.freeze([
+  "transient",
+  "generation-stale",
+  "capacity",
+  "permanent",
+]);
+
+const CATEGORY_SET = new Set(PERSISTENCE_FAILURE_CATEGORIES);
+const CATEGORY_CODES = Object.freeze({
+  transient: "PERSISTENCE_TRANSIENT",
+  "generation-stale": "PERSISTENCE_GENERATION_STALE",
+  capacity: "PERSISTENCE_CAPACITY",
+  permanent: "PERSISTENCE_PERMANENT",
+});
+
+function isRecord(value) {
+  return value !== null && typeof value === "object";
+}
+
+function textOf(value) {
+  return typeof value === "string" ? value : "";
+}
+
+function nonNegativeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function attemptNumber(value) {
+  return Number.isSafeInteger(value) && value > 0 ? value : 1;
+}
+
+function clone(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function categoryOf(value) {
+  if (CATEGORY_SET.has(value)) return value;
+  if (value === "generation_stale" || value === "generation-stale") return "generation-stale";
+  return undefined;
+}
+
+function errorSource(input) {
+  if (isRecord(input) && isRecord(input.error)) return input.error;
+  return input;
+}
+
+/**
+ * 把 storage adapter 的错误归一为稳定类别和 code。
+ * 未知错误默认按 permanent 处理，只有明确声明 retryable/transient 的错误才会重试。
+ */
+export function classifyFailure(input) {
+  const source = errorSource(input);
+  const explicit = categoryOf(input?.category) ?? categoryOf(source?.category);
+  if (explicit !== undefined) {
+    return {
+      category: explicit,
+      code: CATEGORY_CODES[explicit],
+      retryable: explicit === "transient" || explicit === "generation-stale",
+    };
+  }
+
+  const code = textOf(source?.code).toLowerCase();
+  const name = textOf(source?.name).toLowerCase();
+  const message = textOf(source?.message).toLowerCase();
+  const reason = textOf(source?.reason).toLowerCase();
+  const detached = input?.detached === true || source?.detached === true;
+  if (detached
+    || code.includes("generation")
+    || code.includes("detached")
+    || code.includes("binding_replaced")
+    || code.includes("binding-replaced")
+    || code.includes("stale")
+    || reason.includes("generation")
+    || reason.includes("detached")
+    || message.includes("binding was replaced")
+    || message.includes("generation stale")
+    || message.includes("generation changed")) {
+    return { category: "generation-stale", code: CATEGORY_CODES["generation-stale"], retryable: true };
+  }
+
+  if (name === "quotaexceedederror"
+    || code.includes("quota")
+    || code.includes("capacity")
+    || code.includes("enospc")
+    || code.includes("efbig")
+    || code.includes("payload_too_large")
+    || code.includes("payload-too-large")
+    || message.includes("quota")
+    || message.includes("capacity")
+    || message.includes("out of space")
+    || message.includes("storage full")
+    || message.includes("too large")) {
+    return { category: "capacity", code: CATEGORY_CODES.capacity, retryable: false };
+  }
+
+  if (source?.retryable === true
+    || source?.transient === true
+    || code === "etimedout"
+    || code === "econnreset"
+    || code === "eagain"
+    || code === "ebusy"
+    || code.includes("transient")
+    || code.includes("temporary")
+    || message.includes("timed out")
+    || message.includes("temporarily unavailable")
+    || message.includes("try again")) {
+    return { category: "transient", code: CATEGORY_CODES.transient, retryable: true };
+  }
+
+  return { category: "permanent", code: CATEGORY_CODES.permanent, retryable: false };
+}
+
+/** 保留上一轮失败轮次使用的命名，供现有 Host adapter 兼容调用。 */
+export function classifyPersistenceFailure(input) {
+  return classifyFailure(input);
+}
+
+function positionOf({ sequence, generation } = {}) {
+  const position = {
+    sequence: nonNegativeInteger(sequence),
+    generation: nonNegativeInteger(generation),
+  };
+  return position.sequence === null && position.generation === null ? null : position;
+}
+
+/**
+ * generation 优先，随后比较同一 generation 内的 event sequence。
+ *
+ * 前置不变式：唯一调用方 staleAgainstLatest 已把「任一侧档位缺失」的输入提前返回
+ * （接受，不判 stale），因此这里只会收到「双侧都有 generation 与 sequence」或
+ * 「双侧都是 null」两种输入。函数内部仍保留单侧缺失分支，作为独立可读的比较器契约，
+ * 不依赖调用方的不变式才能正确。
+ */
+function comparePosition(left, right) {
+  if (left === null && right === null) return 0;
+  if (left === null) return -1;
+  if (right === null) return 1;
+  if (left.generation !== null || right.generation !== null) {
+    if (left.generation === null) return -1;
+    if (right.generation === null) return 1;
+    if (left.generation !== right.generation) return left.generation - right.generation;
+  }
+  if (left.sequence === null && right.sequence === null) return 0;
+  if (left.sequence === null) return -1;
+  if (right.sequence === null) return 1;
+  return left.sequence - right.sequence;
+}
+
+function atOf(value, now) {
+  return value === undefined || value === null ? now() : value;
+}
+
+function normalizeDrainState(value) {
+  if (typeof value === "string") {
+    return { status: value, pending: value === "draining" ? 1 : 0 };
+  }
+  if (!isRecord(value)) return undefined;
+  const status = typeof value.status === "string" ? value.status : "idle";
+  const pending = Number.isSafeInteger(value.pending) && value.pending >= 0
+    ? value.pending
+    : status === "draining" ? 1 : 0;
+  return { status, pending };
+}
+
+/**
+ * 创建健康状态。maxRetries 表示同一次提交最多允许追加的 retry 次数；它不限制之后
+ * 由新的 manager sequence 发起的独立提交。
+ */
+export function createPersistenceHealth({ now = () => Date.now(), maxRetries = 2 } = {}) {
+  const retryLimit = Number.isSafeInteger(maxRetries) && maxRetries >= 0 ? maxRetries : 2;
+  let tokenSequence = 0;
+  const pendingTokens = new Set();
+  let explicitDrain = { status: "idle", pending: 0 };
+  let lastSuccess = null;
+  let lastFailure = null;
+  let consecutiveFailures = 0;
+  let latestPosition = null;
+  let latestKind;
+  /**
+   * session/child domain 写入的独立观察通道。
+   *
+   * 这两类写入没有 fanout 快照的 manager sequence，若复用 recordFailure 会覆盖
+   * latestPosition/latestKind，从而把 fanout 的有界重试判定（retryDecision）与
+   * "已成功"的陈旧判定一起污染。因此这里单独计数与记录：它是纯内存状态，不触发
+   * 任何持久化回调，失败记录不可能形成 persistence feedback loop。
+   * 成功也不清除 fanout 的 lastFailure——两个通道各自表达自己的最近结果。
+   */
+  let storageObserved = 0;
+  let storageFailures = 0;
+  let lastStorageFailure = null;
+  let lastStorageSuccess = null;
+
+  function drainState() {
+    if (pendingTokens.size > 0) return { status: "draining", pending: pendingTokens.size };
+    return { ...explicitDrain };
+  }
+
+  function applyDrainState(value) {
+    const normalized = normalizeDrainState(value);
+    if (normalized !== undefined) explicitDrain = normalized;
+  }
+
+  function stateSnapshot() {
+    return clone({
+      drain: drainState(),
+      lastSuccess,
+      consecutiveFailures,
+      failureCategory: lastFailure?.category ?? null,
+      failureCode: lastFailure?.code ?? null,
+      lastFailure,
+      maxRetries: retryLimit,
+      // session/child 写入通道：只读投影，不参与 fanout 的 latestPosition 比较。
+      storage: {
+        observed: storageObserved,
+        failures: storageFailures,
+        lastFailure: lastStorageFailure,
+        lastSuccess: lastStorageSuccess,
+      },
+    });
+  }
+
+  /**
+   * 判定一次记录是否相对最近一次被采纳的记录过时（stale）。
+   *
+   * 无 position（null 档位）的显式语义：**任一侧为 null 时不判 stale，一律接受**。
+   * 理由：null 档位只表示「缺少游标信息」，不携带「更旧」这一事实证明。
+   *   - null-position 成功必须能清零 lastFailure/consecutiveFailures，否则该次失败会
+   *     在健康视图里永不清零（审核发现 03 的主症状）；
+   *   - null-position 失败必须照常计数，否则真实故障被静默丢弃。
+   * 该规则同时覆盖「单侧 null」：例如 generation 可用但 sequence 非安全整数时，
+   * position 为 {generation: n, sequence: null}，与前沿比较时 sequence 一侧缺失，
+   * 同样不得凭空判旧。
+   * 两侧都有 position 时保持既有规则：generation 优先、同 generation 比 sequence，
+   * 并且同 position 上「成功之后紧跟失败」仍被抑制（order === 0 分支）。
+   */
+  function staleAgainstLatest(position, kind) {
+    if (position === null || latestPosition === null) return false;
+    if (position.generation === null || latestPosition.generation === null) return false;
+    if (position.sequence === null || latestPosition.sequence === null) return false;
+    const order = comparePosition(position, latestPosition);
+    if (order < 0) return true;
+    return order === 0 && kind === "failure" && latestKind === "success";
+  }
+
+  /**
+   * 采纳一次记录后推进档位前沿：kind 始终更新，position 原样写入（null 也写入）。
+   *
+   * 保持修复前「前沿 = 最近一次被采纳记录」的语义：一次缺信息的记录会把前沿降级为
+   * 缺信息，之后的记录不再与更早的档位比较。取舍是宁可不做推断，也不能把「缺少游标」
+   * 当成「已知更旧」——后者会把迟到的正常记录永久丢进 stale，正是本次修复要消除的失效模式。
+   */
+  function advancePosition(position, kind) {
+    latestPosition = position;
+    latestKind = kind;
+  }
+
+  const api = {
+    beginDrain({ generation, sequence, drainState: suppliedDrainState } = {}) {
+      const token = Object.freeze({
+        id: ++tokenSequence,
+        generation: nonNegativeInteger(generation),
+        sequence: nonNegativeInteger(sequence),
+      });
+      pendingTokens.add(token.id);
+      explicitDrain = { status: "draining", pending: pendingTokens.size };
+      applyDrainState(suppliedDrainState);
+      return token;
+    },
+
+    endDrain(token) {
+      if (!isRecord(token) || !pendingTokens.has(token.id)) return false;
+      pendingTokens.delete(token.id);
+      explicitDrain = {
+        status: pendingTokens.size > 0 ? "draining" : "idle",
+        pending: pendingTokens.size,
+      };
+      return true;
+    },
+
+    recordSuccess({ sequence, generation, at, drainState: suppliedDrainState } = {}) {
+      // 无 position 的成功同样被采纳：它必须能清零失败计数（见 staleAgainstLatest 注释）。
+      const position = positionOf({ sequence, generation });
+      if (staleAgainstLatest(position, "success")) return stateSnapshot();
+      advancePosition(position, "success");
+      lastSuccess = {
+        sequence: nonNegativeInteger(sequence),
+        generation: nonNegativeInteger(generation),
+        at: atOf(at, now),
+      };
+      lastFailure = null;
+      consecutiveFailures = 0;
+      applyDrainState(suppliedDrainState);
+      return stateSnapshot();
+    },
+
+    recordFailure({ error, category, sequence, generation, at, drainState: suppliedDrainState, attempt = 1 } = {}) {
+      const normalized = classifyFailure({ error, category });
+      // 无 position 的失败照常计数（accepted: true），只有明确更旧的档位才返回 stale 丢弃。
+      const position = positionOf({ sequence, generation });
+      if (staleAgainstLatest(position, "failure")) {
+        return { ...normalized, accepted: false, stale: true, health: stateSnapshot() };
+      }
+      advancePosition(position, "failure");
+      const failure = {
+        category: normalized.category,
+        code: normalized.code,
+        sequence: nonNegativeInteger(sequence),
+        generation: nonNegativeInteger(generation),
+        at: atOf(at, now),
+        attempt: attemptNumber(attempt),
+        message: textOf(error?.message ?? error),
+      };
+      lastFailure = failure;
+      consecutiveFailures += 1;
+      applyDrainState(suppliedDrainState);
+      return { ...normalized, accepted: true, failure, health: stateSnapshot() };
+    },
+
+    retryDecision(categoryOrOptions = {}, suppliedAttempt = 1) {
+      const input = typeof categoryOrOptions === "string"
+        ? { category: categoryOrOptions, attempt: suppliedAttempt }
+        : categoryOrOptions;
+      const normalized = classifyFailure(input);
+      const attempt = attemptNumber(input?.attempt);
+      if (normalized.category !== "transient" && normalized.category !== "generation-stale") {
+        return { retry: false, merge: false, nextAttempt: null, reason: normalized.category };
+      }
+      if (attempt > retryLimit) {
+        return { retry: false, merge: false, nextAttempt: null, reason: "retry-exhausted" };
+      }
+      return {
+        retry: true,
+        merge: normalized.category === "generation-stale",
+        nextAttempt: attempt + 1,
+        reason: normalized.category,
+      };
+    },
+
+    shouldRetry(category, attempt = 1) {
+      return api.retryDecision(category, attempt);
+    },
+
+    /**
+     * 记录一次 session/child domain 写入的结果（同步 throw 或异步 reject 都归一到这里）。
+     *
+     * - 失败：分类为 transient/generation-stale/capacity/permanent 并只更新本通道；
+     *   不触碰 fanout 的 lastFailure/latestPosition，因此不会改变其重试判定；
+     * - 成功：只更新本通道的 lastSuccess，不掩盖 fanout 自己的失败状态。
+     *
+     * @param {object} input - { ok, error, generation, at, source }
+     * @returns {{ok:boolean, category:string|null, code:string|null, health:object}}
+     */
+    observeStorageWrite({ ok = false, error, generation, at, source } = {}) {
+      const position = nonNegativeInteger(generation);
+      const observedAt = atOf(at, now);
+      if (ok === true) {
+        storageObserved += 1;
+        lastStorageSuccess = { generation: position, at: observedAt, source: textOf(source) };
+        return { ok: true, category: null, code: null, health: stateSnapshot() };
+      }
+      const normalized = classifyFailure({ error });
+      storageObserved += 1;
+      storageFailures += 1;
+      lastStorageFailure = {
+        category: normalized.category,
+        code: normalized.code,
+        generation: position,
+        at: observedAt,
+        source: textOf(source),
+        message: textOf(error?.message ?? error),
+      };
+      return { ok: false, category: normalized.category, code: normalized.code, health: stateSnapshot() };
+    },
+
+    classifyFailure,
+    snapshot: stateSnapshot,
+    describe: stateSnapshot,
+  };
+
+  return Object.freeze(api);
+}

package/host/recovery.js

@@ -0,0 +1,242 @@
+/**
+ * Host 关注点模块：普通专家自动恢复的 runtime 状态与判定。
+ *
+ * 接管此前散落在 index.js 的 recovery 上下文存储（原 record.taskRecoveryContexts）、
+ * 待消费的重建意图队列（原 pendingRecoveryRebuilds）、失败文案分类、终止性投递
+ * 错误分类与恢复预算判定。recovery record 本身仍由组合根持有（被多个事件路径
+ * 直接读写），本模块只持有"纯状态 + 纯判定"。
+ *
+ * 语义保持：自动恢复最多 5 次、成功重置、明确取消不恢复、非空输出不恢复；
+ * 不涉及 fan-out 手工 retry。
+ *
+ * 生命周期（任务 06）：模块暴露 describe()/dispose() 标准形态，可作为生命周期参与者
+ * 装配进 host/composition，也可由入口在 ctx.effect 清理里直接调用。dispose 同步关闭
+ * 并清空重建意图与上下文存储，随后按注册逆序执行释放回调（timer、AbortController、
+ * pending operation、相关绑定），异步回调会被等待；重复 dispose 返回同一个 promise，
+ * 回调只执行一次。关闭之后到达的迟到 promise 一律读到空状态：takeRebuild/contextFor/
+ * promptFor 为空、canAutoRecover 为 false、queueRebuild 静默丢弃，因此不可能复活任务
+ * 或启动新的 child（也不能把错误变成未处理的 rejection）。
+ *
+ * @module dsh-expert-group/host/recovery
+ */
+import { appendRecoveryRetryCount, lastTurnErrorMessage, shouldAutoRecover } from "../shared.js";
+
+function isRecord(value) {
+  return value !== null && typeof value === "object";
+}
+
+function evictOldest(store, limit) {
+  while (store.size > limit) {
+    const oldest = store.keys().next();
+    if (oldest.done === true) return;
+    store.delete(oldest.value);
+  }
+}
+
+/**
+ * @param {object} [options]
+ * @param {number} [options.limit] - 自动恢复上限。
+ * @param {number} [options.taskBindingLimit] - 每个 record 保留的任务上下文上限。
+ * @param {string} [options.effortMarker] - child.options 上的推理深度 marker 名。
+ * @param {Function[]} [options.disposeHooks] - 释放回调（timer 清理、AbortController
+ *   取消、pending operation 与绑定释放）；按注册逆序执行，异步回调会被等待。
+ */
+export function createRecoveryModule({ limit = 5, taskBindingLimit = 64, effortMarker = "__degExpertEffort", disposeHooks = [] } = {}) {
+  if (!Number.isSafeInteger(limit) || limit < 0) throw new TypeError("recovery limit 必须是非负整数");
+  if (!Number.isSafeInteger(taskBindingLimit) || taskBindingLimit <= 0) throw new TypeError("taskBindingLimit 必须是正整数");
+  if (!Array.isArray(disposeHooks) || disposeHooks.some((hook) => typeof hook !== "function")) {
+    throw new TypeError("disposeHooks 必须全部是函数");
+  }
+  let contexts = new WeakMap();
+  let contextCount = 0;
+  const rebuilds = [];
+  // 释放回调按注册顺序保存、按注册逆序执行；dispose 时整体摘除，保证每个回调只跑一次。
+  const hooks = disposeHooks.slice();
+  let disposed = false;
+  let disposePromise;
+
+  const api = {
+    /**
+     * 保存恢复重建所需的原任务上下文：route、prompt、provider/model/effort、
+     * persona、toolFilter 与 maxDepth。非文本 prompt 不建立上下文。
+     */
+    rememberContext(record, { routeKey, request, label, taskKey } = {}) {
+      if (disposed || !isRecord(record) || request === void 0 || request === null) return undefined;
+      const promptText = request.prompt?.[0]?.text;
+      if (typeof promptText !== "string" || promptText.length === 0) return undefined;
+      const context = {
+        routeKey,
+        label,
+        promptText,
+        provider: request.agentOptions?.provider,
+        model: request.agentOptions?.model,
+        reasoningEffort: request.agentOptions?.[effortMarker],
+        persona: request.persona,
+        toolFilter: request.toolFilter,
+        maxDepth: request.maxDepth,
+      };
+      let store = contexts.get(record);
+      if (store === undefined) {
+        store = new Map();
+        contexts.set(record, store);
+        contextCount += 1;
+      }
+      // routeKey 与 recoveryRequest 是既有 record 字段（重建路径会读 route 变化），
+      // 继续写回以保持兼容；按任务键的查找由本模块持有。
+      record.routeKey = routeKey;
+      record.recoveryRequest = context;
+      store.set(taskKey, context);
+      evictOldest(store, taskBindingLimit);
+      return context;
+    },
+    /** 优先按 op.taskKeys 取本次任务的上下文，缺失时回落最近一次上下文。 */
+    contextFor(record, op) {
+      // 关闭之后连宿主持有的兼容字段（record.recoveryRequest）也不再读取：迟到的恢复
+      // 流程不能借它复活 prompt。
+      if (disposed) return undefined;
+      const store = isRecord(record) ? contexts.get(record) : undefined;
+      if (store !== undefined) {
+        for (const taskKey of op?.taskKeys ?? []) {
+          const context = store.get(taskKey);
+          if (context !== undefined) return context;
+        }
+      }
+      return record?.recoveryRequest;
+    },
+    promptFor(record, op) {
+      const context = api.contextFor(record, op);
+      return typeof context?.promptText === "string" ? context.promptText : void 0;
+    },
+
+    /** 登记一个待消费的重建意图（agent/created 时按 parent+parentId+role 取用）。 */
+    queueRebuild(entry) {
+      // 关闭后重新排队是"迟到 promise"最常见的复活入口：静默丢弃。这里不能抛错，
+      // 否则迟到回调会把异常变成未处理的 rejection。
+      if (disposed) return undefined;
+      if (!isRecord(entry) || typeof entry.parentId !== "string" || typeof entry.role !== "string") {
+        throw new TypeError("queueRebuild 需要 parentId/role");
+      }
+      rebuilds.push(entry);
+      return entry;
+    },
+    /** 取用并移除最早匹配的重建意图；父 Agent 必须是同一 exact 对象。 */
+    takeRebuild(parent, parentId, role) {
+      const index = rebuilds.findIndex((item) => item.parent === parent && item.parentId === parentId && item.role === role);
+      return index === -1 ? void 0 : rebuilds.splice(index, 1)[0];
+    },
+    /** 移除一个具体的重建意图（startContinuable 失败/成功后清理）。 */
+    removeRebuild(entry) {
+      const index = rebuilds.indexOf(entry);
+      if (index === -1) return false;
+      rebuilds.splice(index, 1);
+      return true;
+    },
+    dropRebuildsFor(parent) {
+      let removed = 0;
+      for (let index = rebuilds.length - 1; index >= 0; index -= 1) {
+        if (rebuilds[index].parent === parent) {
+          rebuilds.splice(index, 1);
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+    rebuildsFor: (parent) => rebuilds.filter((item) => item.parent === parent),
+    rebuildCount: () => rebuilds.length,
+
+    /** 失败原因文案：底层原因 + 恢复次数后缀（供任务终态与后续 feedback）。 */
+    failureMessage(record, reason, session) {
+      const kind = reason?.kind;
+      let message;
+      if (kind === "error") {
+        const detail = reason?.error?.message;
+        if (typeof detail === "string" && detail.length > 0) {
+          message = "subagent run failed: " + detail;
+        } else {
+          const latest = lastTurnErrorMessage(session?.events);
+          message = latest === null ? "subagent run failed" : "subagent run failed: " + latest;
+        }
+      } else if (kind === "aborted") {
+        message = "subagent run was cancelled";
+      // B9：blocked（pre-step 拒绝，消息被认领但未落盘）与 refusal 统一为 declined 文案。
+      } else if (kind === "refusal" || kind === "blocked") {
+        message = "subagent declined the task";
+      } else if (kind === "max-tokens") {
+        message = "subagent run hit its token limit before finishing";
+      } else if (kind === "completed") {
+        message = "subagent returned no text output";
+      } else {
+        message = "subagent run ended abnormally (" + String(kind ?? "unknown") + ")";
+      }
+      return appendRecoveryRetryCount(message, record?.recoveryCount);
+    },
+
+    /** 终止性投递错误：取消、权限、父/根生命周期变化不再消耗恢复预算。 */
+    isTerminalDispatchError(error) {
+      const code = typeof error?.code === "string" ? error.code.toUpperCase() : "";
+      const detail = error instanceof Error ? error.message : String(error ?? "");
+      if (error?.name === "AbortError"
+        || ["ABORT_ERR", "UNAUTHORIZED", "FORBIDDEN", "PERMISSION_DENIED", "DRAINING", "PARENT_DISPOSED", "ROOT_DISPOSED"].includes(code)) {
+        return true;
+      }
+      return /root generation is no longer live|parent.*(?:destroyed|disposed|not live|不可用)|cannot rebuild recovery child because|cancel(?:led|ed)|unauthori[sz]ed|permission denied|forbidden/i.test(detail);
+    },
+
+    /** 归一化后的连续恢复次数（非法值按 0）。 */
+    recoveryCount(record) {
+      return Number.isSafeInteger(record?.recoveryCount) && record.recoveryCount >= 0 ? record.recoveryCount : 0;
+    },
+    /** 是否仍有自动恢复预算：非空输出、明确取消、超限都返回 false。 */
+    canAutoRecover(record, reason, hasOutput) {
+      // 卸载之后不得再派发新的恢复 child：预算一律为 0。
+      if (disposed) return false;
+      return shouldAutoRecover(reason, hasOutput, api.recoveryCount(record)) && api.recoveryCount(record) < limit;
+    },
+    /** 成功完成后重置连续恢复预算。 */
+    resetBudget(record) {
+      if (isRecord(record)) record.recoveryCount = 0;
+      return 0;
+    },
+    describe: () => ({ rebuilds: rebuilds.length, trackedContexts: contextCount, disposed }),
+    /**
+     * 注册一个释放回调：timer 清理、AbortController 取消、pending operation 与绑定
+     * 释放都通过它挂到模块生命周期上。关闭之后注册被拒绝（返回 false），避免回调
+     * 在关闭之后才登记而永远不执行。
+     */
+    addDisposeHook(hook) {
+      if (typeof hook !== "function") throw new TypeError("addDisposeHook 需要函数");
+      if (disposed) return false;
+      hooks.push(hook);
+      return true;
+    },
+    /**
+     * 幂等清理：同步关闭并清空重建意图与上下文存储（迟到 promise 因此读不到任何状态），
+     * 随后按注册逆序执行释放回调。异步回调会被等待，单个回调的异常记录下来后继续
+     * 执行其余回调，绝不向外抛出，也不会成为未处理的 rejection。重复调用返回同一个
+     * promise，回调只执行一次。
+     */
+    dispose() {
+      if (disposePromise !== undefined) return disposePromise;
+      disposed = true;
+      rebuilds.length = 0;
+      contexts = new WeakMap();
+      contextCount = 0;
+      const registered = hooks.splice(0, hooks.length);
+      disposePromise = (async () => {
+        const errors = [];
+        for (let index = registered.length - 1; index >= 0; index -= 1) {
+          try {
+            const result = registered[index]();
+            // 同步回调不额外让出微任务：卸载路径上的 timer/AbortController 立即释放。
+            if (result !== null && typeof result === "object" && typeof result.then === "function") await result;
+          } catch (error) {
+            errors.push(error);
+          }
+        }
+        return Object.freeze({ errors: Object.freeze(errors) });
+      })();
+      return disposePromise;
+    },
+  };
+  return Object.freeze(api);
+}