dsh-subagent-profile 0.3.3 → 0.4.0

package/lib/core/evolution-generate.mjs

@@ -0,0 +1,196 @@
+// lib/core/evolution-generate.mjs — 候选生成路径（从 evolution-engine 拆出守行门）：
+// 一条建议 → ≤3 条互斥候选，逐候选过三道闸（闸由装配层注入）后落资产域。更新策略
+// 与有效期用户可配：自动换新在「候选到期且数据显著变化」时把旧候选转 expired（留
+// 审计）再产新一代；手动维护不自动换代、不自动过期，只经「重新生成候选」刷新
+// （留审计）。纯函数 + 注入 deps，零 IO、零 LLM。
+
+import { sanitizeProfile } from './pure.mjs';
+import { profileKeyOf } from './evolution-summary.mjs';
+import { buildEvolutionCandidates, profileFingerprint, sourceConfigFromKey } from './evolution-draft.mjs';
+import { candidateExpired, candidateExpiryOf, dataFingerprintOf, dataSignificantlyChanged, expireAuditEntry, refreshAuditEntry } from './evolution-renewal.mjs';
+
+// 候选总量护栏：evolution 资产数达到 20 条即跳过生成并 warn（阈值待实测后校准）。
+const ASSET_CAP = 20;
+
+// 存量 profile 的 L1 身份键（与聚合层同口径：persona/toolFilter 只认存在性）。
+function keyCfg(profile) {
+  const cfg = {};
+  if (typeof profile.preset === 'string' && profile.preset !== '' && profile.preset !== 'inherit') cfg.preset = profile.preset;
+  if (typeof profile.provider === 'string' && profile.provider !== '') cfg.provider = profile.provider;
+  if (typeof profile.model === 'string' && profile.model !== '') cfg.model = profile.model;
+  if (typeof profile.persona === 'string' && profile.persona.length > 0) cfg.persona_present = true;
+  if (profile.toolFilter !== undefined && profile.toolFilter !== null) cfg.toolFilter_present = true;
+  return cfg;
+}
+
+// 注册表中与该 L1 身份键匹配的方案（净化后快照）——指纹输入，编辑任一方案
+// 都会使候选过期。
+export function matchingRegistryProfiles(store, profileKey) {
+  const profiles = store.profiles instanceof Map ? [...store.profiles.values()] : [];
+  return profiles
+    .filter((p) => p !== null && typeof p === 'object' && profileKeyOf(keyCfg(p)) === profileKey)
+    .map((p) => sanitizeProfile(p, { strict: false }).clean);
+}
+
+// 单条候选 → 资产对象。baseline_snapshot 留档金丝雀基线（from + 生成时刻的加权分/
+// 样本数）；data_fingerprint 留档换代判定输入；expiry 按用户设置（手动维护或不自动
+// 过期档为 null，否则 = 生成时刻 + 有效期小时数）。
+export function buildAsset(deps, item, draft, now, summaries) {
+  const l1Entry = summaries !== null && typeof summaries === 'object' && summaries.l1 !== null && typeof summaries.l1 === 'object'
+    ? summaries.l1[item.profileKey]
+    : undefined;
+  const l2 = summaries !== null && typeof summaries === 'object' ? summaries.l2 : undefined;
+  if (draft === null || typeof draft !== 'object') return null;
+  const from = sourceConfigFromKey(item.profileKey, l2);
+  const registry = matchingRegistryProfiles(deps.store, item.profileKey);
+  const fingerprint = profileFingerprint({ profileKey: item.profileKey, from, registryEntries: registry });
+  const axis = item.suggestion === '降' ? 'capability' : 'budget';
+  const direction = item.suggestion === '降' ? 'down' : 'up';
+  return {
+    v: 1,
+    id: draft.config.id,
+    source: 'evolution',
+    provenance: { pluginVersion: deps.pluginVersion, generatedAt: now, basis: draft.basis },
+    state: 'draft',
+    version: 1,
+    expiry: candidateExpiryOf(deps.getCandidateMode(), deps.getCandidateTtlH(), now),
+    from,
+    to: draft.config,
+    axis,
+    direction,
+    baseline_snapshot: {
+      from,
+      score: l1Entry?.score ?? null,
+      n: l1Entry?.confidence?.n ?? 0,
+      confidence: item.confidence ?? '',
+      generatedAt: now,
+    },
+    data_fingerprint: dataFingerprintOf(item, summaries),
+    profile_key: item.profileKey,
+    profile_fingerprint: fingerprint,
+    config: draft.config,
+    name: draft.name,
+    description: draft.description,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+// 单条建议 → ≤3 条候选，逐候选过三道闸（复用装配层注入的闸评估）后落盘；单条
+// 候选闸不过或落盘失败只跳过该候选（fail-soft），不影响其余候选与建议展示。
+async function generateCandidatesFor(deps, { item, snapshot, taken, now, summaries }) {
+  const l1Entry = summaries !== null && typeof summaries === 'object' && summaries.l1 !== null && typeof summaries.l1 === 'object'
+    ? summaries.l1[item.profileKey]
+    : undefined;
+  const l2 = summaries !== null && typeof summaries === 'object' ? summaries.l2 : undefined;
+  const drafts = buildEvolutionCandidates({
+    advice: item,
+    l1Entry,
+    l2,
+    snapshot,
+    whitelist: deps.whitelist,
+    takenIds: taken,
+    now,
+  });
+  const generated = [];
+  const skipped = [];
+  for (const draft of drafts) {
+    const gates = await deps.assessGates(draft.config);
+    if (!gates.ok) {
+      skipped.push({ profileKey: item.profileKey, candidateId: draft.config.id, reason: gates.reason });
+      continue;
+    }
+    const asset = buildAsset(deps, item, draft, now, summaries);
+    if (asset === null) continue;
+    const persisted = deps.assets.add(asset);
+    if (persisted.persisted) {
+      taken.add(asset.id);
+      generated.push(asset.id);
+    } else {
+      skipped.push({ profileKey: item.profileKey, candidateId: draft.config.id, reason: 'persist-failed' });
+    }
+  }
+  return { generated, skipped };
+}
+
+// auto 模式的待处置门槛：null = 可生成；{skip} = 幂等跳过；{expire} = 需先转
+// expired 再换代。观察期（proposed）恒阻断；手动维护不自动换代。
+function pendingGate(deps, item, now, summaries, mode) {
+  const unresolved = deps.assets.findUnresolved(item.profileKey);
+  if (unresolved.length === 0) return null;
+  if (mode === 'manual' || unresolved.some((entry) => entry.state === 'proposed')) return { skip: 'pending' };
+  const expired = unresolved.filter((entry) => candidateExpired(entry, now));
+  if (expired.length < unresolved.length) return { skip: 'pending' };
+  const next = dataFingerprintOf(item, summaries);
+  const changed = expired.some((entry) => {
+    const asset = deps.assets.get(entry.id);
+    return dataSignificantlyChanged(asset !== undefined ? (asset.data_fingerprint ?? {}) : {}, next);
+  });
+  return changed ? { expire: expired } : { skip: 'no-significant-change' };
+}
+
+// 生成候选（建议 → 资产域）：建议链开关门（evolutionAdvice）→ 总量护栏 → 逐条建议：
+//   auto：无未处置候选才生成；未到期幂等跳过；全部到期且数据显著变化 → 旧候选转
+//   expired（留审计）再产新一代；到期但数据没显著变化 → 保留旧候选跳过。
+//   manual：有任何未处置候选即幂等跳过（不自动换代、不自动过期）。
+//   forceProfileKey：只对该键绕过上述待处置门槛（「重新生成候选」内部复用）。
+export async function generateCandidates(deps, { advice, summaries, forceProfileKey = null } = {}) {
+  if (!deps.getAdviceEnabled()) return { generated: [], skipped: [], reason: 'advice-disabled' };
+  const snapshot = await deps.catalog.getSnapshot();
+  const now = Date.now();
+  const mode = deps.getCandidateMode();
+  const evolutionCount = deps.assets.countBySource('evolution');
+  if (evolutionCount >= ASSET_CAP) {
+    deps.logger.warn('[dsh-subagent-profile] 候选总量护栏：evolution 资产已达 20 条上限，跳过生成（阈值待实测后校准）');
+    return { generated: [], skipped: [] };
+  }
+  const taken = new Set([...deps.store.profiles.keys(), ...deps.assets.ids()]);
+  const generated = [];
+  const skipped = [];
+  for (const item of Array.isArray(advice) ? advice : []) {
+    if (evolutionCount + generated.length >= ASSET_CAP) break;
+    const forced = forceProfileKey !== null && item.profileKey === forceProfileKey;
+    if (!forced) {
+      const gate = pendingGate(deps, item, now, summaries, mode);
+      if (gate === null) { /* 无未处置候选，正常生成 */ }
+      else if (gate.skip !== undefined) { skipped.push({ profileKey: item.profileKey, reason: gate.skip }); continue; }
+      else {
+        for (const entry of gate.expire) {
+          const transitioned = deps.assets.transition(entry.id, 'expired', { expire_reason: 'expiry-and-data-change' });
+          if (transitioned.persisted) {
+            const asset = deps.assets.get(entry.id);
+            if (asset !== undefined) deps.evoLedger.recordGovernanceAudit(expireAuditEntry(asset, '候选到期且数据显著变化，已换新'));
+          }
+        }
+      }
+    }
+    const perItem = await generateCandidatesFor(deps, { item, snapshot, taken, now, summaries });
+    generated.push(...perItem.generated);
+    skipped.push(...perItem.skipped);
+  }
+  return { generated, skipped };
+}
+
+// 重新生成候选（人工触发）：该身份键所有未处置候选先转 expired，再产新一代；
+// 审计 suggestion-refresh 一条（人工触发即确认）。无当前建议时只清理不产新候选。
+export async function regenerateCandidates(deps, { profileKey, advice, summaries }) {
+  const unresolved = deps.assets.findUnresolved(profileKey);
+  const expired = [];
+  for (const entry of unresolved) {
+    const transitioned = deps.assets.transition(entry.id, 'expired', { expire_reason: 'manual-regenerate' });
+    if (transitioned.persisted) expired.push(entry.id);
+  }
+  const result = await generateCandidates(deps, { advice, summaries, forceProfileKey: profileKey });
+  const generatedIds = Array.isArray(result.generated) ? result.generated : [];
+  const item = (Array.isArray(advice) ? advice : []).find((a) => a !== null && typeof a === 'object' && a.profileKey === profileKey);
+  const l2 = summaries !== null && typeof summaries === 'object' ? summaries.l2 : undefined;
+  const first = generatedIds.length > 0 ? deps.assets.get(generatedIds[0]) : undefined;
+  deps.evoLedger.recordGovernanceAudit(refreshAuditEntry({
+    profileKey,
+    from: sourceConfigFromKey(profileKey, l2),
+    to: first !== undefined ? first.to : null,
+    axis: item?.suggestion === '升' ? 'budget' : 'capability',
+    direction: item?.suggestion === '升' ? 'up' : 'down',
+  }));
+  return { expired, generated: generatedIds, skipped: Array.isArray(result.skipped) ? result.skipped : [] };
+}

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;
@@ -88,6 +92,8 @@ function buildBase({ parent, args, merged, mode, pluginVersion }) {
     // session_id 空值归一 null：它是未来聚合层惰性 join 的键，静默缺失会破坏
     // join 且难察觉，显式 null 至少保持 JSONL 行形状稳定。
     session_id: parent?.session?.header?.id ?? null,
+    parent_model: parent?.options?.model ?? null,
+    parent_provider: parent?.options?.provider ?? null,
     mode,
     origin: ORIGIN,
     requested: cfgOf(merged),
@@ -107,7 +113,7 @@ function buildBase({ parent, args, merged, mode, pluginVersion }) {
 // tool_count 为「携带 usage 的 assistant/message 事件数」（collectChildCalls 的
 // totalCalls），是工具调用次数的可测代理而非字面计数值——宿主会话面无更直接的
 // 工具调用计数字段；拿不到记 null。
-function foregroundOutcome({ result, elapsedMs, prunedOutputLen, toolCount }) {
+function foregroundOutcome({ result, elapsedMs, prunedOutputLen, toolCount, childTotalTokens, childUsage }) {
   const stopReason = result?.stopReason ?? 'completed';
   const completed = stopReason === 'completed';
   return {
@@ -116,6 +122,8 @@ function foregroundOutcome({ result, elapsedMs, prunedOutputLen, toolCount }) {
     elapsed_ms: elapsedMs,
     output_len: prunedOutputLen,
     tool_count: completed ? toolCount : null,
+    ...(typeof childTotalTokens === 'number' && Number.isFinite(childTotalTokens) ? { tokens: childTotalTokens } : {}),
+    ...(childUsage !== null && typeof childUsage === 'object' ? { usage: childUsage } : {}),
   };
 }
 
@@ -130,12 +138,14 @@ function backgroundOutcome(settled) {
     elapsed_ms: s.elapsedMs,
     output_len: typeof s.output === 'string' ? s.output.length : 0,
     tool_count: totalCalls,
+    ...(typeof s.childTotalTokens === 'number' && Number.isFinite(s.childTotalTokens) ? { tokens: s.childTotalTokens } : {}),
+    ...(s.childUsage !== null && typeof s.childUsage === 'object' ? { usage: s.childUsage } : {}),
   };
 }
 
 // --- 三分支 finish 助手：每条派发只加一行调用（守 dispatch-tool 行门）------------
 
-export function finishForegroundLedger(ledger, base, childId, result, prunedBlocks, elapsedMs, childCalls) {
+export function finishForegroundLedger(ledger, base, childId, result, prunedBlocks, elapsedMs, childCalls, childTotalTokens, childUsage) {
   const calls = childCalls ?? {};
   ledger.record({
     ...base,
@@ -146,6 +156,8 @@ export function finishForegroundLedger(ledger, base, childId, result, prunedBloc
       elapsedMs,
       prunedOutputLen: textFrom(prunedBlocks).length,
       toolCount: typeof calls.totalCalls === 'number' ? calls.totalCalls : null,
+      childTotalTokens,
+      childUsage,
     }),
   });
 }
@@ -161,11 +173,26 @@ export function finishContinuableLedger(ledger, base, childId) {
 // --- 审计 meta（ledger.meta.json）----------------------------------------------
 
 // meta 默认态（缺失/损坏/形状不符均回退此值 → fail-soft 从零）。last_write_ts 为
-// 最近一次成功落盘时间（§12.4 字段；旧文件无该字段时经合并回退 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 {
@@ -176,7 +203,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 };
@@ -193,7 +226,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 });
@@ -215,16 +256,19 @@ function persistAuditMeta(metaState, healthValue, warn, { warnOnFailure = true }
 
 // 治理失败统一接线：计 lostGovernance + health 置 degraded，meta 尽力落盘保证
 // 重启仍 degraded；内存 health 无论落盘成败一律降级（写失败只 warn，不降回 ok）。
-function markGovernanceFailureMeta(meta, persistMeta) {
+// ok → degraded 转变时经 onAlert 通知提醒系统（全局审计异常源）。
+function markGovernanceFailureMeta(meta, persistMeta, onAlert) {
+  const wasOk = meta.health === 'ok';
   meta.governanceLost += 1;
   meta.health = 'degraded';
   persistMeta('degraded');
+  if (wasOk && typeof onAlert === 'function') onAlert(meta.governanceLost);
 }
 
 // 治理审计事件（放行审计等）追加一行到 governance-audit.jsonl（append-only 不可变）。
 // 写失败绝不静默：warn + markGovernanceFailureMeta（计 lostGovernance + degraded）；
 // 写成功若正处 degraded，即为一次成功文件写 → 恢复 ok（与派发台账同口径）。
-function appendGovernanceAudit(meta, dir, auditFile, persistMeta, warn, entry) {
+function appendGovernanceAudit(meta, dir, auditFile, persistMeta, warn, onAlert, entry) {
   const line = JSON.stringify({ v: GOVERNANCE_AUDIT_VERSION, ts: Date.now(), ...entry });
   try {
     mkdirSync(dir, { recursive: true });
@@ -232,58 +276,130 @@ function appendGovernanceAudit(meta, dir, auditFile, persistMeta, warn, entry) {
     if (meta.health === 'degraded') persistMeta('ok');
   } catch (error) {
     warn(`dispatch ledger: 治理审计事件写入失败（${error instanceof Error ? error.message : String(error)}）`);
-    markGovernanceFailureMeta(meta, persistMeta);
+    markGovernanceFailureMeta(meta, persistMeta, 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;
   }
 }
 
-export function createEvolutionLedger({ dshHome, pluginVersion, warn = () => {} } = {}) {
+// 轮转执行器装配：追加成功后惰性检查；首次轮转前若 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, entry);
+      appendGovernanceAudit(meta, dir, auditFile, persistMeta, warn, onAlert, entry);
     },
     // 治理审计失败（profile 变更写失败等）：计 lostGovernance + health 置 degraded，
     // 不抛、不阻断调用方；meta 尽力落盘保证重启仍 degraded。
     markGovernanceFailure() {
-      markGovernanceFailureMeta(meta, persistMeta);
+      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,
   };
 }