Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

35.3 KB
Raw Blame
/**
 * 本地变更原语:把「用户/学习器做了什么」翻译成对 CRDT 状态的一次操作。
 *
 * 全部是纯函数,返回新状态与新时钟,由调用方在写盘成功后再提交 —— 时钟一旦
 * 前进就不能回退(回退会让此后产出的时间戳与已广播出去的产生冲突)。
 *
 * ## 计数只在这里增长
 *
 * 词典频次的唯一增长入口是本模块:每个真实事件让**本节点自己那一桶** +1。合并
 * 永远不产生新计数(逐节点取 max),物化永远不产生新计数(只读求和)。所以频次
 * 恒等于真实事件数,与同步了多少次、以什么拓扑同步无关。
 */

import { compareHlc, formatHlc, hlcWallMs, tickHlc, type HlcClock, type HlcTimestamp } from './hlc';
import { DICTIONARY_CANDIDATE_PROMOTION_COUNT } from '../dictionaryLearningPolicy';
import { MATERIALIZED_ID_PREFIX, materializeDictionary, pickDisplayText } from './materialize';
import { deriveMoveTag } from './move-tag';
import { createMovedAliasResolver } from './moved-aliases';
import { dictionaryTermKey, normalizeDictionaryTermText } from './text';
import {
  createAliasRemovalMarker,
  gcExpiredRemovedAliases,
  indexAliasRemovalMarkers,
  isAliasRemovalMarkerKey,
  readAliasStateVisibleCount,
  readAliasVisibleCount,
} from './alias-removal';
import {
  copyDictionaryMap,
  createDictionaryMap,
  hasDictionaryKey,
  listLiveIncarnations,
  readCounterTotal,
  withDictionaryKey,
  type DictionaryIncarnation,
  type DictionaryRecord,
  type DictionaryStage,
  type DictionaryTermSource,
  type SyncAliasState,
  type VoiceDictionarySyncState,
} from './types';

export interface MutationResult {
  state: VoiceDictionarySyncState;
  clock: HlcClock;
  /** 本次操作是否真的改变了状态;false 时调用方可以跳过写盘与广播。 */
  changed: boolean;
}

export interface LearningEventInput {
  /** 词条原文(未归一化亦可)。 */
  text: string;
  /** 本次观察到的误识别写法。 */
  aliases?: string[];
  /** 目标阶段:攒证据用 'candidate',晋升或已是正式词条用 'entry'。 */
  stage: DictionaryStage;
  nowMs: number;
}

/**
 * 记录一次自动学习事件。
 *
 * 对齐 desktop `applyVoiceInputDictionaryLearningActions` 的语义:
 *  - 已存在(有存活化身)→ 在其中一个化身上 +1,顺带按 stage 提级;
 *  - 不存在 → 新建化身,计数从 1 起;
 *  - 被抑制的词不会被自动学习重新建出来(但已存在的化身照常 +1 —— 抑制只在
 *    物化阶段压制显示,这样「A 删除」与「B 并发学习」并发时删除意图不被绕过)。
 *
 * 晋升不需要特判:候选阶段攒下的计数就挂在同一个化身上,晋升事件 +1 之后总数
 * 自然等于 desktop 单机路径的 `evidenceCount + 1`。
 */
export function recordLearningEvent(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: LearningEventInput,
): MutationResult {
  const text = normalizeDictionaryTermText(input.text);
  const key = dictionaryTermKey(text);
  if (!key) return { state, clock, changed: false };

  const record = state.records[key];
  const live = record ? listLiveIncarnations(record) : [];
  // 用户删除过这条自动词条:既不重新建出来,也不给残留的自动化身继续记证据。
  // 后者看起来无害(物化阶段本来就会被抑制压住),但每次学习都会改状态 → 触发
  // 写盘与同步广播,而且计数一直涨,是纯粹的浪费。用户手动把词加回来之后
  // (存在 manual 存活化身)才恢复正常学习。
  if (hasDictionaryKey(state.suppressed, key) && !live.some((item) => item.source === 'manual')) {
    return { state, clock, changed: false };
  }

  const aliasTexts = normalizeAliasTexts(input.aliases, key);
  const ticked = tickHlc(clock, input.nowMs);

  if (live.length === 0) {
    return {
      state: putRecord(state, key, {
        incarnations: {
          [ticked.stamp]: createIncarnation({
            tag: ticked.stamp,
            text,
            source: 'automatic',
            stage: input.stage,
            nodeId: clock.nodeId,
            aliasTexts,
            nowMs: input.nowMs,
          }),
        },
        tombstones: record?.tombstones ?? {},
      }),
      clock: ticked.clock,
      changed: true,
    };
  }

  // 确定性地落在同一个化身上(存活化身按 tag 升序,取第一个),避免每次学习都
  // 新建化身让状态无限膨胀。落在哪个化身上不影响总数:计数按节点分桶,不同设备
  // 各记各的桶,合并后求和仍是真实事件总数。
  const target = live[0];
  const targetAliases = createMovedAliasResolver(state)(key, target);
  const nextCount = live.reduce((sum, item) => sum + readCounterTotal(item.counters), 0) + 1;
  return {
    state: putRecord(state, key, {
      ...record!,
      incarnations: {
        ...copyDictionaryMap(record!.incarnations),
        [target.tag]: bumpIncarnation({ ...target, aliases: targetAliases }, {
          nodeId: clock.nodeId,
          stage: nextCount >= DICTIONARY_CANDIDATE_PROMOTION_COUNT ? 'entry' : input.stage,
          aliasTexts,
          stamp: ticked.stamp,
          nowMs: input.nowMs,
        }),
      },
    }, ticked.clock),
    clock: ticked.clock,
    changed: true,
  };
}

export interface SeedTermInput {
  /**
   * 允许在「只剩墓碑」的键上重建化身。默认 true(降级回收语义)。
   * sidecar 恢复认领必须显式传 false —— 见 seedTerm 内的说明。
   */
  allowTombstonedRevival?: boolean;
  text: string;
  source: DictionaryTermSource;
  stage: DictionaryStage;
  /** 已积累的证据次数(来自被认领的词典文件),至少按 1 计。 */
  count: number;
  /**
   * 已积累的别名(误识别写法)及其次数。
   *
   * 别名是词典纠错能力的主体 —— 「web coding → Vibe Coding」这类映射全靠它。
   * 认领时不带上,存量用户升级后纠错能力就凭空退化了,而且下一次物化写回文件
   * 就永久丢失。
   */
  aliases?: ReadonlyArray<{ text: string; count?: number }>;
  nowMs: number;
}

/**
 * 以既有频次「种下」一个词条 —— 只用于把一份状态之外的词典认领进来。
 *
 * 与 {@link recordLearningEvent} 的区别是它一次写入 N 次证据,而不是 +1。这个能力
 * 很危险,所以有一道硬约束:**只在该词条完全不存在于状态里时才生效**(连墓碑都
 * 没有)。已经存在的词条一律不碰 —— 否则合并进来的远端计数会被文件里的数字覆盖
 * 或重复记账,那正是词典频次膨胀的经典成因。
 */
/**
 * 把某个词的存活化身提升为正式词条,不动计数。
 *
 * stage 是 entry-wins 单调寄存器,提升只会前进不会回退。降级期间老客户端把候选词
 * 转正时会用到:那个键从没进过 `lastMaterializedKeys`,而状态里已有存活的候选化身,
 * `seedTerm` 会因此判定「已存在」而放过 —— 不补这一步,转正就在下次物化时被写回候选。
 */
export function promoteTermToEntry(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: { termKey: string; nowMs: number },
): MutationResult {
  const record = state.records[input.termKey];
  if (!record) return { state, clock, changed: false };
  const live = listLiveIncarnations(record);
  if (live.length === 0 || live.every((item) => item.stage === 'entry')) {
    return { state, clock, changed: false };
  }

  const ticked = tickHlc(clock, input.nowMs);
  const incarnations = copyDictionaryMap(record.incarnations);
  for (const incarnation of live) {
    if (incarnation.stage === 'entry') continue;
    incarnations[incarnation.tag] = { ...incarnation, stage: 'entry', updatedAt: input.nowMs };
  }
  return {
    state: putRecord(state, input.termKey, { ...record, incarnations }, ticked.clock),
    clock: ticked.clock,
    changed: true,
  };
}

/** Apply admission policy after merging, without changing CRDT merge algebra or counts. */
export function promoteEligibleDictionaryCandidates(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  nowMs: number,
): MutationResult {
  let next = state;
  let nextClock = clock;
  for (const [key, record] of Object.entries(state.records)) {
    const live = listLiveIncarnations(record);
    if (hasDictionaryKey(state.suppressed, key) || live.some((item) => item.stage === 'entry')) continue;
    const count = live.reduce((sum, item) => sum + readCounterTotal(item.counters), 0);
    if (count < DICTIONARY_CANDIDATE_PROMOTION_COUNT) continue;
    const promoted = promoteTermToEntry(next, nextClock, {
      termKey: key,
      nowMs: Math.max(nowMs, ...live.map((item) => item.updatedAt)),
    });
    next = promoted.state;
    nextClock = promoted.clock;
  }
  return { state: next, clock: nextClock, changed: next !== state };
}

export function seedTerm(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: SeedTermInput,
): MutationResult {
  const text = normalizeDictionaryTermText(input.text);
  const key = dictionaryTermKey(text);
  if (!key) return { state, clock, changed: false };
  // 判据是「有没有存活化身」,不是「记录键在不在」。一个被删过又被旧版本重新加
  // 回来的词,记录里只剩墓碑 —— 按键存在就跳过的话,回收永远认领不了它,那条词
  // 在升级后就凭空消失了。新化身自带新 tag,旧墓碑覆盖不到它。
  const existing = state.records[key];
  if (existing && listLiveIncarnations(existing).length > 0) {
    return { state, clock, changed: false };
  }
  // sidecar 丢失后的恢复认领必须尊重对端墓碑:本机没有身份历史,新化身自带新 tag,
  // 对端那条删除盖不住它 —— 用户在另一台电脑删掉的词会在合并后复活。降级回收则相反,
  // 那时投影是老客户端刚写下的新证据,越过墓碑重建才是对的。
  if (existing && input.allowTombstonedRevival === false) {
    return { state, clock, changed: false };
  }
  if (input.source === 'automatic' && hasDictionaryKey(state.suppressed, key)) {
    return { state, clock, changed: false };
  }

  const ticked = tickHlc(clock, input.nowMs);
  const count = Math.max(1, Math.floor(input.count));
  const incarnation = createIncarnation({
    tag: ticked.stamp,
    text,
    source: input.source,
    stage: input.stage,
    nodeId: clock.nodeId,
    aliasTexts: [],
    nowMs: input.nowMs,
  });

  // 别名按各自既有次数种下(同样只在首次认领时发生,不会重复记账)。
  const aliases = createDictionaryMap<SyncAliasState>();
  for (const alias of input.aliases ?? []) {
    const aliasText = normalizeDictionaryTermText(alias?.text);
    const aliasKey = dictionaryTermKey(aliasText);
    if (!aliasKey || aliasKey === key || hasDictionaryKey(aliases, aliasKey)) continue;
    aliases[aliasKey] = {
      text: aliasText,
      textStamp: ticked.stamp,
      counters: withDictionaryKey(null, clock.nodeId, Math.max(1, Math.floor(alias?.count ?? 1))),
      lastSeenAt: input.nowMs,
    };
  }

  const incarnations = createDictionaryMap<DictionaryIncarnation>();
  incarnations[ticked.stamp] = {
    ...incarnation,
    counters: withDictionaryKey(null, clock.nodeId, count),
    aliases,
  };
  return {
    state: putRecord(state, key, {
      incarnations: { ...copyDictionaryMap(existing?.incarnations), ...incarnations },
      // 墓碑必须留着:它们对应的是旧化身,丢掉会让那些化身在别的设备上复活。
      tombstones: copyDictionaryMap(existing?.tombstones),
    }),
    clock: ticked.clock,
    changed: true,
  };
}

export interface ManualEntryInput {
  text: string;
  nowMs: number;
}

/**
 * 手动添加词条(设置页输入或 CSV 导入的单条)。
 *
 * 手动添加不受抑制集合限制 —— 用户显式要它回来。
 *
 * ## 为什么总是新建化身,而不是原地改已有化身
 *
 * 「A 上删除」与「B 上手动添加同一个词」并发时,用户在两台设备上表达了相反的
 * 意图,没有先后可言。这里选 **add-wins**:显式添加胜出。词典多留一个词的代价,
 * 远小于用户明确添加的词莫名消失。
 *
 * 原地改已有化身做不到这一点 —— A 的墓碑按 tag 覆盖,会把 B 改过的那个化身一起
 * 带走,添加就白做了。新建化身带来全新的 tag,任何并发删除都覆盖不到它。
 *
 * 只有「这条词已经是 manual 正式词条」时才是真正的空操作(用户在 UI 上其实什么
 * 都没改变),此时不新建化身,并发删除照常生效。判定只看合并主键,不比较原文
 * 大小写 —— 设置页有独立的「编辑词条」入口负责改写法,重复添加不承担这个职责。
 */
export function addManualEntry(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: ManualEntryInput,
): MutationResult {
  const text = normalizeDictionaryTermText(input.text);
  const key = dictionaryTermKey(text);
  if (!key) return { state, clock, changed: false };

  const record = state.records[key];
  const live = record ? listLiveIncarnations(record) : [];
  const noop = live.some((item) => item.source === 'manual' && item.stage === 'entry');
  if (noop) return { state, clock, changed: false };

  const ticked = tickHlc(clock, input.nowMs);
  return {
    state: putRecord(state, key, {
      incarnations: {
        ...copyDictionaryMap(record?.incarnations),
        [ticked.stamp]: createIncarnation({
          tag: ticked.stamp,
          text,
          source: 'manual',
          stage: 'entry',
          nodeId: clock.nodeId,
          aliasTexts: [],
          nowMs: input.nowMs,
        }),
      },
      tombstones: record?.tombstones ?? {},
    }),
    clock: ticked.clock,
    changed: true,
  };
}

export interface DeleteTermsInput {
  /** 归一化主键;调用方拿到的若是词条 id,先翻译成主键再传进来。 */
  termKeys: ReadonlyArray<string>;
  nowMs: number;
  /**
   * 删除自动词条时是否写入抑制集合。默认 true(用户主动删除的语义)。
   * 改名内部调用传 false —— 用户是改写法而不是拒绝这个词,抑制会误伤新写法。
   */
  suppressAutomatic?: boolean;
}

/**
 * 删除词条(observed-remove)。
 *
 * 对「本机当前看得见的那些化身」记墓碑,而不是对主键记墓碑:这样之后重新添加
 * 同名词会产生新化身,不会被这次删除的墓碑压住;同时被删化身上的计数一并失效,
 * 离线设备带着旧计数回来也复活不了。
 *
 * 删的若是自动词条,同时写入抑制集合,阻止后台学习把它一路加回来 —— 与 desktop
 * `deleteVoiceInputDictionaryEntriesFromSettings` 的单机语义一致。手动词条不写
 * 抑制:之后自动学习可以合法地重新学出来。
 */
export function deleteTerms(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: DeleteTermsInput,
): MutationResult {
  let nextState = state;
  let nextClock = clock;
  let changed = false;

  for (const rawKey of input.termKeys) {
    const key = dictionaryTermKey(rawKey);
    const record = key ? nextState.records[key] : undefined;
    if (!record) continue;
    const live = listLiveIncarnations(record);
    if (live.length === 0) continue;

    const ticked = tickHlc(nextClock, input.nowMs);
    nextClock = ticked.clock;

    const tombstones: Record<HlcTimestamp, HlcTimestamp> = copyDictionaryMap(record.tombstones);
    for (const incarnation of live) tombstones[incarnation.tag] = ticked.stamp;

    const isAutomatic = !live.some((item) => item.source === 'manual');
    nextState = putRecord(nextState, key, { ...record, tombstones });
    if (input.suppressAutomatic !== false && isAutomatic && !hasDictionaryKey(nextState.suppressed, key)) {
      nextState = {
        ...nextState,
        suppressed: withDictionaryKey(nextState.suppressed, key, {
          // 抑制列表展示的文本与词条列表用同一套 LWW 规则,避免两处显示不一致。
          text: pickDisplayText(live),
          stamp: ticked.stamp,
        }),
      };
    }
    changed = true;
  }

  return { state: nextState, clock: nextClock, changed };
}

export interface RenameTermInput {
  /** 被改写的词条主键。 */
  termKey: string;
  /** 新写法。 */
  nextText: string;
  nowMs: number;
}

/**
 * 改写词条(设置页的「编辑词条」入口)。
 *
 * 分两种情况:
 *  - 只改写法(归一化主键不变,例如 litellm → LiteLLM):在存活化身上更新展示文本,
 *    并把来源提升为 manual,频次与别名原样保留;
 *  - 改成了另一个词(主键变了):等价于「删掉旧词 + 添加新词」。此时**不写抑制**——
 *    用户是在改名,不是拒绝这个词,否则新写法若日后被自动学习到会被自己的抑制挡住。
 */
export function renameTerm(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: RenameTermInput,
): MutationResult {
  const fromKey = dictionaryTermKey(input.termKey);
  const nextText = normalizeDictionaryTermText(input.nextText);
  const toKey = dictionaryTermKey(nextText);
  if (!fromKey || !toKey) return { state, clock, changed: false };

  const record = state.records[fromKey];
  const resolveMovedAliases = createMovedAliasResolver(state);
  const live = record
    ? listLiveIncarnations(record).map((incarnation) => ({
        ...incarnation,
        aliases: resolveMovedAliases(fromKey, incarnation),
      }))
    : [];
  if (live.length === 0) return { state, clock, changed: false };

  if (fromKey !== toKey) {
    // 改名 = 把积累的证据整体**搬**到新键下,而不是「删旧 + 按聚合值新建」。
    //
    // 频次是排序权重、别名是纠错能力的主体,不搬过去等于用户纠正一个学错的写法就
    // 把这个词学到的东西全丢了。但搬的方式很关键:早先是把跨化身求和出来的总频次
    // 塞进一个全新化身。两台已收敛的电脑各自把同一个词改成同一个新名时,双方都会
    // 算出同样的总数、各自造一个新化身;合并后两个化身都存活,物化把它们相加 ——
    // 频次 5 的词变成 10,而其间没有发生任何一次学习。
    //
    // 现在把原化身连同它按节点分桶的计数一起搬过去,新 tag 由「原 tag + 目标键」
    // 确定性派生:两台电脑搬出来的是**同一个**化身(tag 相同、计数相同),合并时
    // 天然去重,搬多少次都不会涨。
    //
    // 不直接复用原 tag,是因为原键上刚给这个 tag 打了墓碑 —— 改回原名时(A→B→A)
    // 搬回去的化身会被自己那条旧墓碑当场盖住,词条凭空消失。派生保证每次落地的
    // tag 都是新的,同时仍然可去重。
    const ticked = tickHlc(clock, input.nowMs);
    const moved = createDictionaryMap<DictionaryIncarnation>();
    for (const incarnation of live) {
      const movedTag = deriveMoveTag(incarnation.tag, toKey);
      moved[movedTag] = {
        ...incarnation,
        tag: movedTag,
        text: nextText,
        textStamp: ticked.stamp,
        source: 'manual',
        stage: 'entry',
        updatedAt: input.nowMs,
      };
    }

    // 原键打墓碑。墓碑是记录内部的,不会波及新键下同 tag 的化身。
    const removed = deleteTerms(state, ticked.clock, {
      termKeys: [fromKey],
      nowMs: input.nowMs,
      suppressAutomatic: false,
    });

    // 目标键已有词条时,搬过去的化身与它并存 —— 那是两批各自独立的证据,相加才对。
    const target = removed.state.records[toKey];
    return {
      state: putRecord(removed.state, toKey, {
        incarnations: { ...copyDictionaryMap(target?.incarnations), ...moved },
        tombstones: copyDictionaryMap(target?.tombstones),
      }),
      clock: removed.clock,
      changed: true,
    };
  }

  if (live.every((item) => item.text === nextText && item.source === 'manual')) {
    return { state, clock, changed: false };
  }

  const ticked = tickHlc(clock, input.nowMs);
  const incarnations: Record<HlcTimestamp, DictionaryIncarnation> = copyDictionaryMap(record!.incarnations);
  for (const incarnation of live) {
    incarnations[incarnation.tag] = {
      ...incarnation,
      text: nextText,
      textStamp: ticked.stamp,
      source: 'manual',
      updatedAt: Math.max(incarnation.updatedAt, input.nowMs),
    };
  }
  return {
    state: putRecord(state, fromKey, { ...record!, incarnations }),
    clock: ticked.clock,
    changed: true,
  };
}

export interface ReplaceTermAliasesInput {
  /** 要编辑的词条主键。 */
  termKey: string;
  /** 保存后的主词;改名时用它排除“别名与主词相同”,默认仍取 termKey。 */
  primaryText?: string;
  /** 保存后的完整别名集合;缺少的旧别名视为删除。 */
  aliases: ReadonlyArray<string>;
  nowMs: number;
}

/**
 * 替换一条词的完整别名集合。
 *
 * 保留别名原有的观察计数,只给真正新增或重新添加的别名记一次用户确认。删除记录
 * “当时已观察到的各节点计数下界”,物化只展示下界之后的新证据:旧副本回流不会复活,
 * 与删除并发发生的新学习也不会被吞掉。词条化身本身不替换,所以频次与并发改名都不会
 * 因这次别名编辑重复计数。
 */
export function replaceTermAliases(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  input: ReplaceTermAliasesInput,
): MutationResult {
  const key = dictionaryTermKey(input.termKey);
  const record = key ? state.records[key] : undefined;
  const resolveMovedAliases = createMovedAliasResolver(state);
  const live = record
    ? listLiveIncarnations(record).map((incarnation) => ({
        ...incarnation,
        aliases: resolveMovedAliases(key, incarnation),
      }))
    : [];
  if (!key || !record || live.length === 0) return { state, clock, changed: false };

  const primaryKey = dictionaryTermKey(input.primaryText ?? input.termKey);
  const aliasTexts = normalizeAliasTexts(input.aliases, primaryKey);
  const desired = new Map(aliasTexts.map((text) => [dictionaryTermKey(text), text]));
  const current = new Map<string, { text: string; stamp: HlcTimestamp }>();
  for (const incarnation of live) {
    const removalIndex = indexAliasRemovalMarkers(incarnation.aliases);
    for (const [aliasKey, alias] of Object.entries(incarnation.aliases)) {
      if (isAliasRemovalMarkerKey(aliasKey)) continue;
      const removal = removalIndex.get(aliasKey);
      if (readAliasStateVisibleCount(alias, removal) === 0) continue;
      const existing = current.get(aliasKey);
      if (!existing || compareHlc(alias.textStamp, existing.stamp) > 0) {
        current.set(aliasKey, { text: alias.text, stamp: alias.textStamp });
      }
    }
  }
  const unchanged =
    current.size === desired.size &&
    [...desired].every(([aliasKey, text]) => current.get(aliasKey)?.text === text) &&
    live.every((incarnation) => incarnation.source === 'manual' && incarnation.stage === 'entry');
  if (unchanged) return { state, clock, changed: false };

  const ticked = tickHlc(clock, input.nowMs);
  const primaryTag = [...live].sort((a, b) => a.tag.localeCompare(b.tag))[0].tag;
  const incarnations = copyDictionaryMap(record.incarnations);

  for (const incarnation of live) {
    const aliases = copyDictionaryMap(incarnation.aliases);
    const floors = indexAliasRemovalMarkers(incarnation.aliases);

    for (const [aliasKey, existing] of Object.entries(incarnation.aliases)) {
      if (isAliasRemovalMarkerKey(aliasKey)) continue;
      const desiredText = desired.get(aliasKey);
      if (desiredText !== undefined) {
        if (existing.text !== desiredText) {
          aliases[aliasKey] = {
            ...existing,
            text: desiredText,
            textStamp: ticked.stamp,
          };
        }
        continue;
      }

      const removal = floors?.get(aliasKey);
      const visibleCount = readAliasStateVisibleCount(existing, removal);
      if (visibleCount === 0) continue;
      const counterVisibleCount = readAliasVisibleCount(existing.counters, removal?.floor);
      for (const [counterNodeId, rawCount] of Object.entries(existing.counters)) {
        const removedCount = Math.floor(rawCount);
        if (removedCount <= (removal?.floor[counterNodeId] ?? 0)) continue;
        const marker = createAliasRemovalMarker(ticked.stamp, {
          aliasKey,
          counterNodeId,
          removedCount,
        });
        aliases[marker.key] = marker.state;
      }
      // TTL 回收后重新添加、再合并旧副本时,原 GCounter 与旧下界可能再次持平;
      // 可见性此时来自较新的 alias.textStamp。删除要刷新一个既有下界的时间戳,
      // 否则旧 marker 仍早于别名,这次删除会被误判成一次重新添加。
      if (counterVisibleCount === 0) {
        const fallbackCounter = Object.entries(existing.counters)
          .filter(([, rawCount]) => Math.floor(rawCount) > 0)
          .sort(([nodeA], [nodeB]) => nodeA.localeCompare(nodeB))[0];
        if (fallbackCounter) {
          const [counterNodeId, rawCount] = fallbackCounter;
          const marker = createAliasRemovalMarker(ticked.stamp, {
            aliasKey,
            counterNodeId,
            removedCount: Math.floor(rawCount),
          });
          aliases[marker.key] = marker.state;
        }
      }
    }

    if (incarnation.tag === primaryTag) {
      for (const [aliasKey, text] of desired) {
        if (current.has(aliasKey)) continue;
        const existing = aliases[aliasKey];
        const removal = floors?.get(aliasKey);
        const counters = copyDictionaryMap(existing?.counters);
        counters[clock.nodeId] =
          Math.max(counters[clock.nodeId] ?? 0, removal?.floor[clock.nodeId] ?? 0) + 1;
        aliases[aliasKey] = {
          ...(existing ?? {
            counters,
            lastSeenAt: input.nowMs,
          }),
          text,
          textStamp: ticked.stamp,
          counters,
          lastSeenAt: Math.max(existing?.lastSeenAt ?? 0, input.nowMs),
        };
      }
    }

    incarnations[incarnation.tag] = {
      ...incarnation,
      source: 'manual',
      stage: 'entry',
      aliases,
      updatedAt: Math.max(incarnation.updatedAt, input.nowMs),
    };
  }

  return {
    state: putRecord(state, key, { ...record, incarnations }, ticked.clock),
    clock: ticked.clock,
    changed: true,
  };
}

/**
 * 把词条 id 翻译回合并主键。UI 只持有 id,删除入口需要这一步。
 *
 * 本模块物化出的 id 由主键确定性派生,直接反解即可;查不到前缀时回退到物化列表
 * 查找,兼容接线迁移窗口里仍带着旧本地 id 的词条。
 */
export function termKeyFromMaterializedId(
  state: VoiceDictionarySyncState,
  entryId: string,
  limits?: Parameters<typeof materializeDictionary>[1],
): string | null {
  const trimmed = entryId.trim();
  if (!trimmed) return null;
  if (trimmed.startsWith(MATERIALIZED_ID_PREFIX)) {
    const key = trimmed.slice(MATERIALIZED_ID_PREFIX.length);
    return hasDictionaryKey(state.records, key) ? key : null;
  }
  const match = materializeDictionary(state, limits).entries.find((entry) => entry.id === trimmed);
  return match ? dictionaryTermKey(match.text) : null;
}

export interface GcOptions {
  nowMs: number;
  /** 墓碑保留时长。 */
  ttlMs: number;
}

/** 词条化身墓碑默认保留 180 天。 */
export const DEFAULT_TOMBSTONE_TTL_MS = 180 * 24 * 60 * 60 * 1000;

/**
 * 自动候选的**权威状态**硬上限。
 *
 * 物化只暴露前 200 条候选,但状态里存的是全部 —— 被挤出展示的那些既看不见也删不掉,
 * 自动学习跑得久一点就单调增长下去,直到整份状态超过 relay 单帧上限,此后每一次
 * 同步广播都被丢弃(而且不会有任何报错)。
 *
 * 上限定得远高于展示上限:正常用户碰不到,只有异常增长才会触发,尽量少动用户数据。
 */
export const MAX_AUTOMATIC_CANDIDATE_RECORDS = 2_000;

/**
 * 裁掉超出硬上限的最弱自动候选(打墓碑,不写抑制)。
 *
 * 只动**自动学习的候选**:手动词条是用户的显式意图,正式词条已经被用户看见并接受,
 * 两者都不在裁剪范围内。不写抑制集合是关键 —— 抑制是永久的,而这些词只是暂时没
 * 挤进来,日后再被学到应该能正常回来。
 *
 * 裁剪会生成墓碑并同步出去,所以判据必须确定性:证据数升序、并列时按主键。两台
 * 设备各自裁剪出的集合可能不同,合并后是删除的并集 —— 候选是学习的中间态,重新
 * 学到就会回来,这个代价可以接受;放任状态无界增长则会让同步彻底停摆。
 */
export function pruneWeakAutomaticCandidates(
  state: VoiceDictionarySyncState,
  clock: HlcClock,
  options: { maxRecords?: number; nowMs: number },
): MutationResult {
  const limit = Math.max(0, options.maxRecords ?? MAX_AUTOMATIC_CANDIDATE_RECORDS);
  const candidates: Array<{ key: string; weight: number }> = [];
  for (const [key, record] of Object.entries(state.records)) {
    const live = listLiveIncarnations(record);
    if (live.length === 0) continue;
    // 只要还有任何一个化身是正式词条或手动来源,这个词就不参与裁剪。
    if (live.some((item) => item.stage === 'entry' || item.source === 'manual')) continue;
    candidates.push({
      key,
      weight: live.reduce((sum, item) => sum + readCounterTotal(item.counters), 0),
    });
  }
  if (candidates.length <= limit) return { state, clock, changed: false };

  const doomed = candidates
    .sort((a, b) => a.weight - b.weight || (a.key < b.key ? -1 : 1))
    .slice(0, candidates.length - limit)
    .map((item) => item.key);

  // suppressAutomatic: false —— 这是容量裁剪,不是「用户不想要这个词」。
  return deleteTerms(state, clock, {
    termKeys: doomed,
    nowMs: options.nowMs,
    suppressAutomatic: false,
  });
}

/**
 * 回收过期墓碑。
 *
 * **必须连同被它覆盖的化身一起删掉** —— 只删墓碑会让化身立刻复活,是这类实现最
 * 常见的自伤。
 *
 * 已知边界:回收之后,一台离线时长超过 TTL 的设备重新上线,理论上能把它手里的
 * 旧化身或已删除别名带回来。自动词条有抑制集合兜底(抑制不过期),所以词条层面
 * 真正能复活的只剩「手动词条 + 设备离线超过 TTL」这一种组合;别名与它采用
 * 相同的离线兼容窗口。
 */
export function gcTombstones(
  state: VoiceDictionarySyncState,
  options: GcOptions,
): VoiceDictionarySyncState {
  const threshold = options.nowMs - options.ttlMs;
  const hasExpiredState = Object.values(state.records).some(
    (record) =>
      Object.values(record.tombstones).some((stamp) => hlcWallMs(stamp) < threshold) ||
      Object.values(record.incarnations).some((incarnation) =>
        Object.entries(incarnation.aliases).some(
          ([aliasKey, alias]) =>
            isAliasRemovalMarkerKey(aliasKey) && hlcWallMs(alias.textStamp) < threshold,
        ),
      ),
  );
  if (!hasExpiredState) return state;

  // 并发别名编辑可能仍挂在即将回收的改名前化身上。先沿搬移链把别名状态压实到
  // 所有保留下来的后继化身,再删过期状态;否则 180 天后被删别名会在新词上复活。
  const resolveMovedAliases = createMovedAliasResolver(state);
  // 用户文本作键 —— 必须无原型,否则 GC 后给 `__proto__` 赋值会走原型 setter,
  // 那条合法词条会被静默丢掉,而且这个丢失还会被持久化并同步出去。
  const records: Record<string, DictionaryRecord> = createDictionaryMap<DictionaryRecord>();
  let changed = false;

  for (const [key, record] of Object.entries(state.records)) {
    const tombstones: Record<HlcTimestamp, HlcTimestamp> = createDictionaryMap<HlcTimestamp>();
    const expired = new Set<HlcTimestamp>();
    for (const [tag, stamp] of Object.entries(record.tombstones)) {
      if (hlcWallMs(stamp) < threshold) {
        expired.add(tag);
        changed = true;
      }
      else tombstones[tag] = stamp;
    }
    const incarnations: Record<HlcTimestamp, DictionaryIncarnation> = createDictionaryMap<DictionaryIncarnation>();
    for (const [tag, incarnation] of Object.entries(record.incarnations)) {
      if (!expired.has(tag)) {
        const resolvedAliases = resolveMovedAliases(key, incarnation);
        const aliases = gcExpiredRemovedAliases(resolvedAliases, threshold);
        changed = changed || aliases !== resolvedAliases;
        incarnations[tag] = {
          ...incarnation,
          aliases,
        };
      }
    }
    if (Object.keys(incarnations).length > 0 || Object.keys(tombstones).length > 0) {
      records[key] = { incarnations, tombstones };
    }
  }

  return changed ? { ...state, records } : state;
}

function putRecord(
  state: VoiceDictionarySyncState,
  key: string,
  record: DictionaryRecord,
  mutationClock?: HlcClock,
): VoiceDictionarySyncState {
  const next = { ...state, records: withDictionaryKey(state.records, key, record) };
  if (mutationClock) {
    next.mutationVector = withDictionaryKey(state.mutationVector, mutationClock.nodeId, formatHlc(mutationClock));
  }
  return next;
}

function createIncarnation(input: {
  tag: HlcTimestamp;
  text: string;
  source: DictionaryTermSource;
  stage: DictionaryStage;
  nodeId: string;
  aliasTexts: ReadonlyArray<string>;
  nowMs: number;
}): DictionaryIncarnation {
  return {
    tag: input.tag,
    text: input.text,
    textStamp: input.tag,
    source: input.source,
    stage: input.stage,
    counters: { [input.nodeId]: 1 },
    aliases: buildAliases({}, input.aliasTexts, input.nodeId, input.tag, input.nowMs),
    createdAt: input.nowMs,
    updatedAt: input.nowMs,
  };
}

function bumpIncarnation(
  incarnation: DictionaryIncarnation,
  input: {
    nodeId: string;
    stage: DictionaryStage;
    aliasTexts: ReadonlyArray<string>;
    stamp: HlcTimestamp;
    nowMs: number;
  },
): DictionaryIncarnation {
  return {
    ...incarnation,
    stage: incarnation.stage === 'entry' || input.stage === 'entry' ? 'entry' : 'candidate',
    counters: {
      ...copyDictionaryMap(incarnation.counters),
      [input.nodeId]: (incarnation.counters[input.nodeId] ?? 0) + 1,
    },
    aliases: buildAliases(incarnation.aliases, input.aliasTexts, input.nodeId, input.stamp, input.nowMs),
    updatedAt: Math.max(incarnation.updatedAt, input.nowMs),
  };
}

function buildAliases(
  current: Record<string, SyncAliasState>,
  aliasTexts: ReadonlyArray<string>,
  nodeId: string,
  stamp: HlcTimestamp,
  nowMs: number,
): Record<string, SyncAliasState> {
  if (aliasTexts.length === 0) return current;
  const next: Record<string, SyncAliasState> = copyDictionaryMap(current);
  for (const aliasText of aliasTexts) {
    const aliasKey = dictionaryTermKey(aliasText);
    if (!aliasKey) continue;
    const existing = next[aliasKey];
    next[aliasKey] = existing
      ? {
          text: aliasText,
          textStamp: stamp,
          counters: { ...existing.counters, [nodeId]: (existing.counters[nodeId] ?? 0) + 1 },
          lastSeenAt: Math.max(existing.lastSeenAt, nowMs),
        }
      : {
          text: aliasText,
          textStamp: stamp,
          counters: { [nodeId]: 1 },
          lastSeenAt: nowMs,
        };
  }
  return next;
}

function normalizeAliasTexts(aliases: ReadonlyArray<string> | undefined, termKey: string): string[] {
  if (!aliases || aliases.length === 0) return [];
  const seen = new Set<string>();
  const result: string[] = [];
  for (const raw of aliases) {
    const text = normalizeDictionaryTermText(raw);
    const key = dictionaryTermKey(text);
    // 别名等于词条本身没有意义(desktop 学习路径同样会把它过滤掉)。
    if (!key || key === termKey || isAliasRemovalMarkerKey(key) || seen.has(key)) continue;
    seen.add(key);
    result.push(text);
  }
  return result;
}