dsh-subagent-profile 0.3.4 → 0.5.0

package/lib/core/evolution-lag.mjs

@@ -0,0 +1,78 @@
+// lib/core/evolution-lag.mjs — 防振荡域（滞后计数 + 回滚冷却 + 观察期联动判据）。
+// 滞后 N：同 (profile_key, axis, direction) 连续 N 次同方向建议才放行候选生成
+// （N=2 初值，待实测后校准）；与建议链 10min cooldown 并存——cooldown 优先抑制，
+// 被抑制的建议不计入连续次数。回滚后冷却：rolled_back 资产进同键冷却，冷却期内
+// 不再产生同方向候选（闭环有界：同键 apply→rollback 往返最多 1 次进入冷却）。
+// 观察期联动：观察期内（proposed + 金丝雀未终）同键禁止换代与重生成候选；无
+// canary 字段的旧资产不阻断（保持既有「重新生成候选」通道）。
+// 本域纯函数 + 注入保存：streak 缓存驻内存，落盘由装配层注入 save（fail-soft）。
+
+// 滞后 N：连续同方向建议次数门槛（初值，待实测后校准）。
+export const LAG_N = 2;
+// 回滚后同键冷却时长（与建议链 cooldown 同值）。
+export const ROLLBACK_COOLDOWN_MS = 10 * 60 * 1000;
+
+// 建议方向 → 资产方向（down/up 与候选资产同口径）。
+export function directionOf(item) {
+  return item !== null && typeof item === 'object' && item.suggestion === '升' ? 'up' : 'down';
+}
+
+// 建议方向 → 资产轴（capability/budget）。
+export function axisOf(item) {
+  return item !== null && typeof item === 'object' && item.suggestion === '升' ? 'budget' : 'capability';
+}
+
+// 观察期是否进行中：proposed + 金丝雀未终且未因人工编辑失效。verdict 为 applied /
+// aborted-human-edit 或资产 invalid 时视为已终；regress 等待人工回滚期间仍阻断
+// （换代会销毁回滚建议依据，须先回滚或人工编辑）。
+export function observationPeriodActive(asset) {
+  if (asset === null || typeof asset !== 'object' || asset.state !== 'proposed' || asset.invalid === true) return false;
+  const canary = asset.canary;
+  if (canary === null || typeof canary !== 'object') return false;
+  return canary.verdict !== 'applied' && canary.verdict !== 'aborted-human-edit';
+}
+
+// 资产列表（完整资产）中是否存在同键观察期资产。
+export function observationPeriodBlocked(assetList, profileKey) {
+  return assetList.some((a) => a !== null && typeof a === 'object' && a.profile_key === profileKey && observationPeriodActive(a));
+}
+
+// 决议后冷却是否生效：同键同方向 rolled_back 资产（回滚决议）或带 cooldown_until
+// 的 applied 资产（显式保留决议）在冷却期内抑制候选生成——两种决议都是闭环终点，
+// 冷却口径一致（有界性：同键 apply→rollback 往返最多 1 次进入冷却）。
+export function rollbackCooldownBlocks(assetList, profileKey, direction, now, cooldownMs = ROLLBACK_COOLDOWN_MS) {
+  return assetList.some((a) => a !== null && typeof a === 'object' && a.profile_key === profileKey && a.direction === direction
+    && ((a.state === 'rolled_back' && Number.isFinite(a.rollback_at) && now - a.rollback_at < cooldownMs)
+      || (a.state === 'applied' && Number.isFinite(a.cooldown_until) && now < a.cooldown_until)));
+}
+
+// streak 键：身份键 + 轴 + 方向（连续同方向计数按此聚合）。
+function streakKeyOf(profileKey, axis, direction) {
+  return `${profileKey}\u0000${axis}\u0000${direction}`;
+}
+
+// 连续同方向建议计数：缓存未命中时读 summaries 里上次落盘的 streak（重启续数），
+// 方向翻转重置为 1；计数封顶 LAG_N（防无限增长）。save 注入为批量落盘（fail-soft）。
+export function bumpStreak(streaks, item, summaries, now) {
+  const profileKey = item.profileKey;
+  const axis = axisOf(item);
+  const direction = directionOf(item);
+  const key = streakKeyOf(profileKey, axis, direction);
+  let prev = streaks.cache.get(key);
+  if (prev === undefined) {
+    const l1 = summaries !== null && typeof summaries === 'object' && summaries.l1 !== null && typeof summaries.l1 === 'object' ? summaries.l1 : {};
+    const seeded = l1[profileKey]?.streak;
+    prev = seeded !== null && typeof seeded === 'object' && seeded.axis === axis && seeded.direction === direction ? seeded : null;
+  }
+  const count = prev !== null && typeof prev === 'object' && Number.isFinite(prev.count) ? Math.min(LAG_N, prev.count + 1) : 1;
+  const next = { profileKey, axis, direction, count, last_ts: now };
+  streaks.cache.set(key, next);
+  try { streaks.save([next]); } catch { /* 落盘失败不阻断生成（fail-soft） */ }
+  return count;
+}
+
+// streak 缓存工厂：save 注入落盘（装配层写回 summaries.json）；缓存驻内存供
+// 同进程连续轮次复用。
+export function createLagStreaks({ save = () => {} } = {}) {
+  return { cache: new Map(), save };
+}

package/lib/core/evolution-ledger.mjs

@@ -2,6 +2,9 @@
 // 只 appendFileSync 追加一行，绝不改写既有行。import-free（仅 node 内置
 // fs/crypto/path + lib/core/pure.mjs），可被 bare-CI 单测直接 import。采集异常只
 // warn + 丢失计数，绝不阻断派发（fail-soft）。
+// 轮转：追加成功后在写路径惰性检查阈值（记录数/字节数），命中即封存当前台账为
+// dispatch-<seq>-<ts>.jsonl 并新建空台账续写；封存件超保留上限时淘汰最早者并
+// 提示回放窗口缩短。轮转失败只 warn（本条已落盘），下次写入重试。
 //
 // 审计分级：每类写失败分别计数，计数与 health 落盘到同目录的 ledger.meta.json
 // （{v:1, lostTelemetry, lostGovernance, health}）。派发台账写失败计 lostTelemetry
@@ -17,10 +20,11 @@
 // 不入库（写入那个时刻它们尚不存在，事后回填会破坏 append-only 不可变性，只由聚合层
 // 惰性 join）。
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { textFrom } from './pure.mjs';
+import { createRotation } from './evolution-persistence.mjs';
 
 const LEDGER_VERSION = 1;
 const GOVERNANCE_AUDIT_VERSION = 1;
@@ -78,7 +82,7 @@ function cfgOf(merged, opts = {}) {
 
 // 记录静态元数据（写入即知的共享字段，不含 ts/v——由 record 落盘时补）。三分支各自
 // 在此基础上补 child_id 与 outcome 后调用 record。pluginVersion 由工厂闭包注入。
-function buildBase({ parent, args, merged, mode, pluginVersion }) {
+function buildBase({ parent, args, merged, mode, pluginVersion, effectiveModelSource }) {
   const prompt = typeof args?.prompt === 'string' ? args.prompt : '';
   const effectivePreset = mode === 'continuable' ? 'inherit' : (merged?.preset ?? 'inherit');
   // continuable 下宿主忽略 reasoningEffort（决策轨迹侧将其列入 ignored），生效栏
@@ -90,6 +94,9 @@ function buildBase({ parent, args, merged, mode, pluginVersion }) {
     session_id: parent?.session?.header?.id ?? null,
     parent_model: parent?.options?.model ?? null,
     parent_provider: parent?.options?.provider ?? null,
+    // 生效来源（call/profile/parent/default）：每次派发记录「生效路由是谁决定的」；
+    // 调用方未传时归一 null，保持 JSONL 行形状稳定。
+    effectiveModelSource: typeof effectiveModelSource === 'string' && effectiveModelSource !== '' ? effectiveModelSource : null,
     mode,
     origin: ORIGIN,
     requested: cfgOf(merged),
@@ -169,11 +176,26 @@ export function finishContinuableLedger(ledger, base, childId) {
 // --- 审计 meta（ledger.meta.json）----------------------------------------------
 
 // meta 默认态（缺失/损坏/形状不符均回退此值 → fail-soft 从零）。last_write_ts 为
-// 最近一次成功落盘时间（旧文件无该字段时经合并回退 0）。
-const META_DEFAULTS = { v: 1, lostTelemetry: 0, lostGovernance: 0, health: 'ok', last_write_ts: 0 };
+// 最近一次成功落盘时间（旧文件无该字段时经合并回退 0）。lost_count 计版本迁移
+// 类丢失；rotation_seq 为轮转序号（0 = 尚未轮转）。
+const META_DEFAULTS = {
+  v: 1,
+  lostTelemetry: 0,
+  lostGovernance: 0,
+  health: 'ok',
+  last_write_ts: 0,
+  lost_count: 0,
+  rotation_seq: 0,
+};
+
+// 可选字段（last_write_ts/lost_count/rotation_seq）缺省或非数字时回退默认，
+// 保证旧版本写出的 meta 文件可读。
+function optionalNumber(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
 
 // 读取并校验 meta.json；缺失/损坏/形状不符回退默认并 warn（fail-soft 从零）。
-// 只接受 v:1 与必填三字段的数字/字符串形态，防止被手改的坏元数据冒充。
+// 只接受 v:1 与必填字段的数字/字符串形态，防止被手改的坏元数据冒充。
 function loadAuditMeta(metaFile, warn) {
   if (!existsSync(metaFile)) return { ...META_DEFAULTS };
   try {
@@ -184,7 +206,13 @@ function loadAuditMeta(metaFile, warn) {
       && typeof parsed.lostGovernance === 'number' && Number.isFinite(parsed.lostGovernance)
       && (parsed.health === 'ok' || parsed.health === 'degraded')
     ) {
-      return { ...META_DEFAULTS, ...parsed };
+      return {
+        ...META_DEFAULTS,
+        ...parsed,
+        last_write_ts: optionalNumber(parsed.last_write_ts, 0),
+        lost_count: optionalNumber(parsed.lost_count, 0),
+        rotation_seq: optionalNumber(parsed.rotation_seq, 0),
+      };
     }
     warn(`ledger meta: 审计元数据形状不符，已从零重建（${metaFile}）`);
     return { ...META_DEFAULTS };
@@ -201,7 +229,15 @@ function loadAuditMeta(metaFile, warn) {
 // fail-soft：清理 tmp + warn、返回 false。warnOnFailure 供派发遥测失败路径关闭——
 // 该路径已就台账写失败 warn 一次，避免重复告警。
 function persistAuditMeta(metaState, healthValue, warn, { warnOnFailure = true } = {}) {
-  const payload = { v: 1, lostTelemetry: metaState.lost, lostGovernance: metaState.governanceLost, health: healthValue, last_write_ts: Date.now() };
+  const payload = {
+    v: 1,
+    lostTelemetry: metaState.lost,
+    lostGovernance: metaState.governanceLost,
+    health: healthValue,
+    last_write_ts: Date.now(),
+    lost_count: metaState.migrationLost,
+    rotation_seq: metaState.rotationSeq,
+  };
   let reported = false;
   try {
     mkdirSync(metaState.dir, { recursive: true });
@@ -247,42 +283,105 @@ function appendGovernanceAudit(meta, dir, auditFile, persistMeta, warn, onAlert,
   }
 }
 
-export function createEvolutionLedger({ dshHome, pluginVersion, warn = () => {}, onAlert } = {}) {
+// 台账现有行数（按换行符计数，文件缺失/读失败回退 0）：轮转的记录数判据在
+// 内存累计，避免每次追加都读整文件。
+function countLines(file) {
+  try {
+    if (!existsSync(file)) return 0;
+    const text = readFileSync(file, 'utf8');
+    let count = 0;
+    for (let i = 0; i < text.length; i += 1) if (text[i] === '\n') count += 1;
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+// 台账字节数（文件缺失/读失败回退 0）。
+function fileBytes(file) {
+  try {
+    return statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+
+// 轮转执行器装配：追加成功后惰性检查；首次轮转前若 meta 文件缺失，先按现值落盘
+// （rotation_seq 从 0 起步），seq 递增后再落盘。文件操作异常向上抛，由调用方
+// fail-soft 处理。
+function makeRotationCheck({ dir, file, metaFile, meta, persistMeta, warn, rotation }) {
+  return createRotation({
+    dir,
+    dispatchFile: file,
+    getRotationSeq: () => meta.rotationSeq,
+    setRotationSeq: (seq) => { meta.rotationSeq = seq; },
+    initMetaIfMissing: () => {
+      if (!existsSync(metaFile)) persistMeta(meta.health, { warnOnFailure: false });
+    },
+    persistMeta: () => persistMeta(meta.health),
+    warn,
+    maxRecords: rotation.maxRecords,
+    maxBytes: rotation.maxBytes,
+    keep: rotation.keep,
+    now: rotation.now,
+  });
+}
+
+// 追加不可变：mkdir recursive + appendFileSync。写失败只 warn + 丢失计数 ++，
+// 绝不抛错、绝不阻断派发。写失败计 lostTelemetry 并落盘 meta；写成功恢复 ok。
+// 轮转检查独立于追加成败：轮转失败只 warn，本条已落盘、下次写入重试。
+function makeRecord({ dir, file, meta, persistMeta, warn, checkRotation }) {
+  return (entry) => {
+    try {
+      // 序列化也在 try 内（循环引用/BigInt 等理论异常会绕过 fail-soft 外泄；
+      // 实际 entry 为自产标量，防御性收口）。
+      const line = JSON.stringify({ v: LEDGER_VERSION, ts: Date.now(), ...entry });
+      mkdirSync(dir, { recursive: true });
+      appendFileSync(file, `${line}\n`, 'utf8');
+      meta.lineCount += 1;
+      if (meta.health === 'degraded') persistMeta('ok');
+    } catch (error) {
+      meta.lost += 1;
+      warn(`dispatch ledger: 派发台账写入失败，已丢失 ${meta.lost} 条（${error instanceof Error ? error.message : String(error)}）`);
+      persistMeta(meta.health, { warnOnFailure: false });
+      return;
+    }
+    try {
+      const result = checkRotation(meta.lineCount, fileBytes(file));
+      if (result.rotated) meta.lineCount = 0;
+    } catch (error) {
+      warn(`dispatch ledger: 台账轮转失败，将在下次写入重试（${error instanceof Error ? error.message : String(error)}）`);
+    }
+  };
+}
+
+export function createEvolutionLedger({ dshHome, pluginVersion, warn = () => {}, onAlert, rotation = {} } = {}) {
   if (typeof dshHome !== 'string' || dshHome.length === 0) {
     throw new Error('dispatch ledger: 派发台账需要 dshHome 目录');
   }
   const dir = join(dshHome, 'subagent-evolution');
   const file = join(dir, 'dispatch.jsonl');
   const auditFile = join(dir, 'governance-audit.jsonl');
-  const persisted = loadAuditMeta(join(dir, 'ledger.meta.json'), warn);
-  // 可写审计状态：lost（遥测）/governanceLost/health，初始为持久化值。
+  const metaFile = join(dir, 'ledger.meta.json');
+  const persisted = loadAuditMeta(metaFile, warn);
+  // 可写审计状态：lost（遥测）/governanceLost/migrationLost/rotationSeq/health，
+  // 初始为持久化值；lineCount 为内存行数累计（构造时读文件初始化）。
   const meta = {
     dir,
-    metaFile: join(dir, 'ledger.meta.json'),
+    metaFile,
     lost: persisted.lostTelemetry,
     governanceLost: persisted.lostGovernance,
+    migrationLost: persisted.lost_count,
+    rotationSeq: persisted.rotation_seq,
     health: persisted.health,
+    lineCount: countLines(file),
   };
   const persistMeta = (healthValue, opts) => persistAuditMeta(meta, healthValue, warn, opts);
+  const checkRotation = makeRotationCheck({ dir, file, metaFile, meta, persistMeta, warn, rotation });
 
   return {
     baseEntry: (input) => buildBase({ ...input, pluginVersion }),
-    // 追加不可变：mkdir recursive + appendFileSync。写失败只 warn + 丢失计数 ++，
-    // 绝不抛错、绝不阻断派发。写失败计 lostTelemetry 并落盘 meta；写成功恢复 ok。
-    record(entry) {
-      try {
-        // 序列化也在 try 内（循环引用/BigInt 等理论异常会绕过 fail-soft 外泄；
-        // 实际 entry 为自产标量，防御性收口）。
-        const line = JSON.stringify({ v: LEDGER_VERSION, ts: Date.now(), ...entry });
-        mkdirSync(dir, { recursive: true });
-        appendFileSync(file, `${line}\n`, 'utf8');
-        if (meta.health === 'degraded') persistMeta('ok');
-      } catch (error) {
-        meta.lost += 1;
-        warn(`dispatch ledger: 派发台账写入失败，已丢失 ${meta.lost} 条（${error instanceof Error ? error.message : String(error)}）`);
-        persistMeta(meta.health, { warnOnFailure: false });
-      }
-    },
+    record: makeRecord({ dir, file, meta, persistMeta, warn, checkRotation }),
     recordGovernanceAudit(entry) {
       appendGovernanceAudit(meta, dir, auditFile, persistMeta, warn, onAlert, entry);
     },
@@ -291,10 +390,19 @@ export function createEvolutionLedger({ dshHome, pluginVersion, warn = () => {},
     markGovernanceFailure() {
       markGovernanceFailureMeta(meta, persistMeta, onAlert);
     },
+    // 版本迁移类丢失计数：资产加载方在跳过不可迁移资产时调用（fail-soft 留痕，
+    // 不降级 health）。计数随 meta 落盘，重启保持。
+    markMigrationLoss() {
+      meta.migrationLost += 1;
+      persistMeta(meta.health, { warnOnFailure: false });
+    },
     // 进程内 health（'ok' | 'degraded'）。
     metaHealth: () => meta.health,
     // 设置页 summary 的 audit 字段来源：{lostTelemetry, lostGovernance, health}。
     auditState: () => ({ lostTelemetry: meta.lost, lostGovernance: meta.governanceLost, health: meta.health }),
     lostCount: () => meta.lost,
+    // 迁移类丢失计数与当前轮转序号（诊断/测试读取）。
+    migrationLostCount: () => meta.migrationLost,
+    rotationSeq: () => meta.rotationSeq,
   };
 }

package/lib/core/evolution-persistence.mjs

@@ -0,0 +1,213 @@
+// lib/core/evolution-persistence.mjs — 进化资产持久化机制：版本前向迁移与派发台账轮转。
+// 迁移：可重写资产顶层 v 版本号，load 时仅在内存链式前向迁移（v→v+1），迁移完成后
+// 原子写回（tmp+rename）；未知/超前版本或缺少迁移步骤一律 fail-soft 跳过并计丢失，
+// 绝不阻断其余功能、绝不改写台账号行。
+// 轮转：dispatch.jsonl 达阈值（记录数或字节数）时封存为 dispatch-<seq>-<ts>.jsonl，
+// 新建空台账续写；封存只 rename + 新建（内容字节不变、封存件不可变）；封存件超过
+// 保留份数时按最早封存淘汰，并一次性提示回放窗口缩短。
+// import-free（仅 node 内置），可被 bare-CI 单测直接导入。
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// --- 版本迁移 ---------------------------------------------------------------
+
+// 各可重写资产的当前版本号。新增资产类型在此登记。
+export const CURRENT_VERSIONS = Object.freeze({ summaries: 1 });
+
+// 前向迁移表：<kind, fromV> → 迁移函数（入参 v=n 的数据，须返回 v=n+1 的数据）。
+// 当前各资产无跨版本 schema 变化，表为空；机制（链式前向迁移 / 未知版本
+// fail-soft / 迁移后写回）由测试注入样例迁移覆盖。出现真实 schema 变化时在此
+// 登记步骤并同步提升 CURRENT_VERSIONS 对应项。
+export const MIGRATIONS = Object.freeze({});
+
+// 单次加载允许的最多迁移步数（防迁移表被误配成死循环）。
+const MAX_MIGRATION_STEPS = 100;
+
+// 迁移错误：版本非法/超前/缺步骤等，由调用方按 fail-soft 处理。
+export class MigrationError extends Error {}
+
+// 内存链式前向迁移：v 小于当前版本时逐级执行迁移表步骤，返回 {data, migrated,
+// fromV, toV}；v 等于当前版本原样返回；v 非法/超前或缺步骤抛 MigrationError。
+export function migrateUp(data, kind, { migrations = MIGRATIONS, currentVersions = CURRENT_VERSIONS } = {}) {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    throw new MigrationError('数据不是普通对象');
+  }
+  const current = currentVersions[kind];
+  if (typeof current !== 'number' || !Number.isInteger(current)) {
+    throw new MigrationError(`未知资产类型：${String(kind)}`);
+  }
+  const fromV = data.v;
+  if (!Number.isInteger(fromV) || fromV < 1) {
+    throw new MigrationError(`版本号非法：${String(fromV)}`);
+  }
+  if (fromV > current) throw new MigrationError(`版本 ${fromV} 超前于当前版本 ${current}`);
+  if (fromV === current) return { data, migrated: false, fromV, toV: fromV };
+  const steps = (migrations ?? {})[kind] ?? {};
+  let cursor = data;
+  let v = fromV;
+  while (v < current) {
+    const step = steps[v];
+    if (typeof step !== 'function') {
+      throw new MigrationError(`缺少 ${String(kind)} v${v} 到 v${v + 1} 的迁移步骤`);
+    }
+    cursor = step(cursor);
+    if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor)) {
+      throw new MigrationError(`迁移步骤 v${v} 产出非法数据`);
+    }
+    v += 1;
+    if (v - fromV > MAX_MIGRATION_STEPS) throw new MigrationError('迁移步数超过上限');
+  }
+  // 归一顶层版本号：迁移步骤可省略写 v，此处强制对齐当前版本。
+  cursor.v = current;
+  return { data: cursor, migrated: true, fromV, toV: current };
+}
+
+// 迁移写回（tmp+rename）：崩溃不产生截断文件；失败仅告警（内存迁移结果仍可用），
+// 不抛、不重复计丢失。
+function writeBack(file, data, warnLog) {
+  const tmp = `${file}.tmp`;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+    renameSync(tmp, file);
+  } catch (error) {
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    warnLog(`[dsh-subagent-profile] 资产迁移写回失败（${file}）：${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// 读取并迁移单个资产文件。缺失返回 null（不告警不计丢失）；损坏/形状不符/版本
+// 无法迁移 → 告警 + onLoss + null（fail-soft 跳过）；迁移发生则原子写回后再返回。
+// logger 取带 warn 方法的对象（缺省静默）。
+export function loadWithMigration(
+  file,
+  kind,
+  { logger, migrations = MIGRATIONS, currentVersions = CURRENT_VERSIONS, onLoss } = {}
+) {
+  const warnLog = (message) => {
+    if (logger !== undefined && logger !== null && typeof logger.warn === 'function') logger.warn(message);
+  };
+  const lose = () => { if (typeof onLoss === 'function') onLoss(); };
+  if (!existsSync(file)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    warnLog(`[dsh-subagent-profile] ${String(kind)} 资产损坏，跳过该资产（fail-soft）：${error instanceof Error ? error.message : String(error)}`);
+    lose();
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    warnLog(`[dsh-subagent-profile] ${String(kind)} 资产形状不符，跳过该资产（fail-soft）`);
+    lose();
+    return null;
+  }
+  let result;
+  try {
+    result = migrateUp(parsed, kind, { migrations, currentVersions });
+  } catch (error) {
+    const version = parsed.v !== undefined ? String(parsed.v) : '未知';
+    warnLog(`[dsh-subagent-profile] ${String(kind)} 资产版本 ${version} 无法迁移，跳过该资产（fail-soft）：${error instanceof Error ? error.message : String(error)}`);
+    lose();
+    return null;
+  }
+  if (result.migrated) writeBack(file, result.data, warnLog);
+  return result.data;
+}
+
+// --- 台账轮转 ----------------------------------------------------------------
+
+// 轮转阈值：记录数（>50k）或字节数（>5MB），任一命中即轮转。阈值为建议初值，
+// 待实测后校准。
+export const ROTATION_DEFAULT_MAX_RECORDS = 50000;
+export const ROTATION_DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+// 封存件保留上限（回放窗口）：超过按最早封存淘汰。
+export const ROTATION_DEFAULT_KEEP = 8;
+
+// 封存件文件名：dispatch-<seq>-<ts>.jsonl（同 seq 同毫秒碰撞时追加 -<n>）。
+const ARCHIVE_PATTERN = /^dispatch-(\d+)-(\d+)(?:-\d+)?\.jsonl$/;
+
+// 是否达轮转阈值：记录数超限或字节数超限（任一命中）。
+export function rotationNeeded(records, bytes, { maxRecords = ROTATION_DEFAULT_MAX_RECORDS, maxBytes = ROTATION_DEFAULT_MAX_BYTES } = {}) {
+  return records > maxRecords || bytes > maxBytes;
+}
+
+// 目录内封存件清单（按 seq、ts 升序 = 最早封存在前）。目录缺失/读失败返回空表。
+function listArchives(dir) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .map((name) => ARCHIVE_PATTERN.exec(name))
+    .filter((match) => match !== null)
+    .map((match) => ({ name: match[0], seq: Number(match[1]), ts: Number(match[2]) }))
+    .sort((a, b) => a.seq - b.seq || a.ts - b.ts);
+}
+
+// 淘汰最早封存件至保留上限；发生淘汰时一次性提示回放窗口缩短（每次轮转最多一次，
+// 因本函数每次轮转只执行一次）。单个文件删除失败不阻断其余淘汰。
+function pruneArchives(dir, keep, warn) {
+  const list = listArchives(dir);
+  if (list.length <= keep) return 0;
+  const excess = list.slice(0, list.length - keep);
+  let removed = 0;
+  for (const entry of excess) {
+    try {
+      rmSync(join(dir, entry.name), { force: true });
+      removed += 1;
+    } catch { /* 单个封存件删除失败不影响主流程 */ }
+  }
+  warn(`dispatch ledger: 回放窗口缩短——封存件已超过 ${keep} 份，淘汰最旧 ${removed} 份`);
+  return removed;
+}
+
+// 创建轮转执行器：check(records, bytes) 在阈值命中时执行一次轮转，返回
+// {rotated, archived, seq, pruned}；未命中返回 {rotated:false}。seq 账本与 meta
+// 落盘由调用方注入：getRotationSeq/setRotationSeq 管内存 seq，initMetaIfMissing
+// 保证首次轮转先建 meta（seq 现值落盘），persistMeta 以更新后的 seq 落盘。
+// 文件操作异常向上抛，由调用方按 fail-soft 处理（本条已落盘的追加不受影响）。
+export function createRotation({
+  dir,
+  dispatchFile,
+  getRotationSeq = () => 0,
+  setRotationSeq = () => {},
+  initMetaIfMissing = () => {},
+  persistMeta = () => true,
+  warn = () => {},
+  maxRecords = ROTATION_DEFAULT_MAX_RECORDS,
+  maxBytes = ROTATION_DEFAULT_MAX_BYTES,
+  keep = ROTATION_DEFAULT_KEEP,
+  now = Date.now,
+} = {}) {
+  return (records, bytes) => {
+    if (!rotationNeeded(records, bytes, { maxRecords, maxBytes })) return { rotated: false };
+    initMetaIfMissing();
+    const seq = getRotationSeq() + 1;
+    const stamp = now();
+    let archive = join(dir, `dispatch-${seq}-${stamp}.jsonl`);
+    let attempt = 0;
+    while (existsSync(archive)) {
+      attempt += 1;
+      archive = join(dir, `dispatch-${seq}-${stamp}-${attempt}.jsonl`);
+    }
+    // 只 rename + 新建：封存内容字节不变，绝不重写任何已写行。
+    renameSync(dispatchFile, archive);
+    setRotationSeq(seq);
+    persistMeta();
+    writeFileSync(dispatchFile, '', 'utf8');
+    const pruned = pruneArchives(dir, keep, warn);
+    return { rotated: true, archived: archive, seq, pruned };
+  };
+}

package/lib/core/evolution-renewal.mjs

@@ -0,0 +1,64 @@
+// lib/core/evolution-renewal.mjs — 候选换代判定与换代审计（从 evolution-engine 拆出
+// 守行门）：到期判定、有效期初值、数据指纹、显著变化判定（阈值初值，待实测后校准）、
+// suggestion-expire / suggestion-refresh 审计条目。纯函数、零 IO、零依赖，可裸 import 单测。
+
+// 候选到期判定：expiry 为 null（不自动过期）恒不到期，否则 now >= expiry。
+export function candidateExpired(entry, now) {
+  return typeof entry.expiry === 'number' && now >= entry.expiry;
+}
+
+// 候选有效期初值：手动维护恒不自动过期；自动换新按设置小时数计算，0 = 不自动过期。
+export function candidateExpiryOf(mode, ttlH, now) {
+  if (mode === 'manual') return null;
+  return ttlH === 0 ? null : now + ttlH * 3600 * 1000;
+}
+
+// 数据指纹：该身份键当前聚合的样本数/加权成功分/置信度（换代判定输入）。
+export function dataFingerprintOf(item, summaries) {
+  const l1 = summaries !== null && typeof summaries === 'object' && summaries.l1 !== null && typeof summaries.l1 === 'object'
+    ? summaries.l1
+    : {};
+  const group = typeof item.profileKey === 'string' ? l1[item.profileKey] : undefined;
+  const entry = group !== null && typeof group === 'object' ? group : {};
+  return {
+    n: Number.isFinite(entry.confidence?.n) ? entry.confidence.n : (Number.isFinite(entry.deployments_total) ? entry.deployments_total : 0),
+    score: Number.isFinite(entry.score?.weighted_success) ? entry.score.weighted_success : 0,
+    confidence: typeof entry.confidence?.level === 'string' ? entry.confidence.level : '',
+  };
+}
+
+// 显著变化判定（初值，待实测后校准）：样本数增加 ≥2，或加权成功分变化 ≥0.1，
+// 或置信度升级。
+const FINGERPRINT_CONFIDENCE_RANK = { low: 0, medium: 1, high: 2 };
+export function dataSignificantlyChanged(prev, next) {
+  if (next.n - prev.n >= 2) return true;
+  if (Math.abs(next.score - prev.score) >= 0.1) return true;
+  return (FINGERPRINT_CONFIDENCE_RANK[next.confidence] ?? -1) > (FINGERPRINT_CONFIDENCE_RANK[prev.confidence] ?? -1);
+}
+
+// suggestion-expire 事件：候选到期且数据显著变化、换代时转 expired 的留痕（仅记录）。
+export function expireAuditEntry(asset, reason) {
+  return {
+    event: 'suggestion-expire',
+    profile_id: typeof asset.id === 'string' ? asset.id : '',
+    from: asset.from,
+    to: asset.to,
+    axis: asset.axis,
+    direction: asset.direction,
+    human_confirmed: false,
+    reason,
+  };
+}
+
+// suggestion-refresh 事件：人工触发「重新生成候选」的留痕（人工触发即确认）。
+export function refreshAuditEntry({ profileKey, from, to, axis, direction }) {
+  return {
+    event: 'suggestion-refresh',
+    profile_id: profileKey,
+    from,
+    to,
+    axis,
+    direction,
+    human_confirmed: true,
+  };
+}