Skip to content

World's first open-source enterprise world model.

134 KB
Raw Blame
//! 实体消解 v2:同名≠同人(流程图与三次实测修洞见 `docs/pipeline.md` 第二节)。
//!
//! 漏斗:名字候选召回(免费,含泛用后缀词干互推)→ 画像向量相似度分层(毫秒,复用摄入阶段的 chunk embedding)
//! → 灰区新建实体 + 疑似重复审核项(宁分勿合),LLM 攒批裁决在独立后台任务里跑,
//! 人工终审兜底。LLM 永远不在抽取写入的关键路径上。
//!
//! 类型漂移:同名在同类型下无候选时再查其它类型(同一团队被抽成 organization/
//! project/concept 是常态),按类型对的互斥强度分流——concept 兜底型当召回候选走
//! 画像分层,易混具体类型照建实体但入队审核对,硬互斥(person vs organization)完全分开。

use chrono::{DateTime, Utc};
use pgvector::Vector;
use sqlx::PgPool;
use std::collections::{HashMap, HashSet};
use utopia_core::models::{MergeLogView, ReviewBatchOutcome, ReviewItem, ReviewSide};
use utopia_core::{AppError, AppResult};
use uuid::Uuid;

/// 上下文相似度阈值(bge-m3 类模型余弦相似度经验值,后续可调)。
/// ≥ ATTACH 归并到既有实体;< NEW 判为不同实体;中间灰区宁分勿合 + 审核项。
pub const SIM_ATTACH: f32 = 0.55;
pub const SIM_NEW: f32 = 0.35;

/// 同名并列的判定边界:两个**同名**候选的画像分数相差不超过这个值,就算「分不开」。
/// 画像分不出谁是谁时,attach 到分高的那个只是候选顺序掷出的硬币(#270)——
/// 与其掷硬币,不如两个都不并、都入人工审核。取值偏紧:真正拉得开的同名人(不同
/// chunk、不同事实积累)分差远大于此,只有质心几乎重合(如同一 chunk 播种)才触发。
pub const SIM_TIE_MARGIN: f32 = 0.02;

/// 旁证宾语的最短长度。低于它的("IT"、"A 组")在任何一篇文档里都可能出现,
/// 命中不含信息量。**宁可漏掉一条旁证**:漏了就是今天的行为,错了会并错人。
const MIN_CORROBORATION_CHARS: usize = 2;

/// 每个候选取几个消歧宾语参与旁证。取多个是因为文档提到的未必是排序最靠前的
/// 那一个(他的部门写在这句、职位写在下一句),但也不能全取——候选的事实越多,
/// 撞上一个泛泛的宾语的机会越大。
const CORROBORATION_OBJECTS: i64 = 3;

/// 名称规范化:全角 ASCII → 半角、全角空格 → 半角、空白折叠。
/// 返回展示形态(保留大小写);匹配一律再套 SQL lower()。
pub fn normalize_name(raw: &str) -> String {
    let mapped: String = raw
        .chars()
        .map(|c| match c {
            '\u{3000}' => ' ',
            '\u{FF01}'..='\u{FF5E}' => char::from_u32(c as u32 - 0xFEE0).unwrap_or(c),
            _ => c,
        })
        .collect();
    mapped.split_whitespace().collect::<Vec<_>>().join(" ")
}

/// Fold unambiguous Markdown formatting in names; evidence keeps the original text.
/// Input should already have passed through [`normalize_name`]. Only whole-name
/// `**...**` / `__...__` emphasis is removed; empty, nested, mismatched or
/// whitespace-padded markup is kept.
/// `__identifier__` stays literal (Unicode letters/digits and underscores count).
/// Single backticks are removed only around a slash path or a dotted filename
/// containing a letter: only letters, digits, `/`, `.`, `_` and `-` are allowed,
/// with at least one alphanumeric character and no trailing dot. This deliberately
/// leaves code, bare identifiers, numeric versions and paths with spaces alone.
pub fn fold_markdown_markers(name: &str) -> &str {
    for marker in ["**", "__", "`"] {
        let Some(inner) = name
            .strip_prefix(marker)
            .and_then(|s| s.strip_suffix(marker))
        else {
            continue;
        };
        if inner.is_empty()
            || inner.trim() != inner
            || inner.contains(['*', '`'])
            || (marker != "`"
                && (inner.starts_with('_') || inner.ends_with('_') || inner.contains("__")))
        {
            return name;
        }
        let fold = match marker {
            "__" => !inner.chars().all(|c| c.is_alphanumeric() || c == '_'),
            "`" => {
                (inner.contains('/')
                    || (inner.contains('.') && inner.chars().any(char::is_alphabetic)))
                    && inner.chars().any(char::is_alphanumeric)
                    && !inner.ends_with('.')
                    && inner
                        .chars()
                        .all(|c| c.is_alphanumeric() || matches!(c, '/' | '.' | '_' | '-'))
            }
            _ => true,
        };
        return if fold { inner } else { name };
    }
    name
}

/// Shared identity key for recall and document-level name claims.
pub fn name_key(raw: &str) -> String {
    fold_markdown_markers(&normalize_name(raw)).to_lowercase()
}

/// 泛用后缀词表:中文直接拼在词干后;英文按独立词算、首尾两种语序都认
/// ("Phoenix Project" / "Project Phoenix")。只影响召回,判定仍走画像相似度。
const GENERIC_SUFFIXES_CJK: &[&str] = &["项目", "公司", "集团", "部门", "团队"];
const GENERIC_WORDS_EN: &[&str] = &["project", "corp", "inc", "team"];

/// 词干:剥去一个泛用后缀后的 lower 形态。未命中、剥空、或词干本身就是
/// 泛用词("项目团队")时返回 None。输入应已过 normalize_name。
pub fn name_stem(name: &str) -> Option<String> {
    let lower = name.to_lowercase();
    let strip_punct = |w: &str| w.trim_end_matches(['.', ',']).to_string();
    let generic = |s: &str| {
        GENERIC_SUFFIXES_CJK.contains(&s) || GENERIC_WORDS_EN.contains(&strip_punct(s).as_str())
    };
    for suf in GENERIC_SUFFIXES_CJK {
        if let Some(stem) = lower.strip_suffix(suf) {
            let stem = stem.trim_end();
            if !stem.is_empty() && !generic(stem) {
                return Some(stem.to_string());
            }
        }
    }
    let words: Vec<&str> = lower.split(' ').collect();
    if words.len() >= 2 {
        if generic(words[words.len() - 1]) {
            let stem = words[..words.len() - 1].join(" ");
            if !generic(&stem) {
                return Some(stem);
            }
        }
        if generic(words[0]) {
            let stem = words[1..].join(" ");
            if !generic(&stem) {
                return Some(stem);
            }
        }
    }
    None
}

/// 输入应已过 [`normalize_name`]。
/// mention 的召回键集合(全 lower):本名 + 词干 + 词干的泛用后缀增广。
/// 增广覆盖反方向(库内是"星尘项目"、mention 只说"星尘");词干含 CJK 拼中文
/// 尾缀,否则拼英文词(两种语序)。键数 ≤11,走 (kb,type,lower(name)) 索引多点查。
pub fn recall_keys(normalized: &str) -> Vec<String> {
    let name = fold_markdown_markers(normalized);
    let lower = name.to_lowercase();
    let base = name_stem(name).unwrap_or_else(|| lower.clone());
    let mut keys = vec![lower];
    fn add(keys: &mut Vec<String>, k: String) {
        if !keys.contains(&k) {
            keys.push(k);
        }
    }
    // Keep exact recall of names already stored with formatting as well.
    add(&mut keys, normalized.to_lowercase());
    add(&mut keys, base.clone());
    if base.chars().any(|c| ('\u{4E00}'..='\u{9FFF}').contains(&c)) {
        for suf in GENERIC_SUFFIXES_CJK {
            add(&mut keys, format!("{base}{suf}"));
        }
    } else {
        for w in GENERIC_WORDS_EN {
            add(&mut keys, format!("{base} {w}"));
            add(&mut keys, format!("{w} {base}"));
        }
    }
    keys
}

// ---------------------------------------------------------------------------
// 类型漂移:同名实体被抽成了不同类型("Orion platform team" ↔ organization/project)
// ---------------------------------------------------------------------------

/// 易混具体类型:抽取常在这几类间摇摆(一个团队算组织还是项目?平台算项目还是产品?)。
/// 同名跨这组类型 → 照建实体(宁分勿合),但入队审核对交 LLM/人工裁决。
///
/// **本体说了算,这张表只是没声明时的退路。** 判两个类能不能指同一个东西,先看
/// `owl:disjointWith`(`entity_type_disjoint`,含继承:Person ⟂ Organization 就让
/// Corporation ⟂ Person)——声明了互斥的一律分开,哪怕它们在类层级上是一家;
/// 没声明的再看类层级(同一支系当易混,#226),最后才是这三个硬 key。
/// 没装包也没声明的库里这三个 key 不存在,于是所有跨类型同名判 `Disjoint`——
/// 变严不变松,不会错合(0016 B3)
pub const CONFUSABLE_TYPE_KEYS: &[&str] = &["organization", "project", "product"];

/// 单次消解最多入队的漂移审核对(防同名大组刷爆审核队列)。
const MAX_DRIFT_REVIEWS: usize = 4;

/// 跨类型同名的处置分类。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TypeDrift {
    /// 一侧是兜底类型:当召回候选,走画像相似度分层(可 ATTACH)
    Recall,
    /// 两个易混具体类型:新建 + 审核对
    Review,
    /// 硬互斥(person vs organization 等,含未知自定义类型):完全分开
    Disjoint,
}

fn classify_type_drift(a: Option<&str>, b: Option<&str>) -> TypeDrift {
    // **同一个类型当然可能是同一个东西。**
    //
    // 这一档原本不存在,因为这个函数生来只服务"类型漂移"——同名被抽成两种
    // 类型——那里两边相同根本不会发生。后来 containment_reviews 借它当相容性
    // 判据,而那里**两边相同才是最常见的情形**,于是 person 对 person 落进了
    // 最后那行 Disjoint,被读成"永不可能是同一个东西"。
    //
    // 代价是全文最明显的同指关系一对都进不了队列:福尔摩斯前六篇里
    // Sherlock Holmes 与 Holmes 是两个实体,488 个实体只合并掉 14 个。
    // 原有的 12 个单元测试全在测跨类型,一个都没测相同类型。
    if a == b {
        return TypeDrift::Recall;
    }
    // **一侧还没判出来** → 当召回候选,走画像相似度分层。
    // 从前比的是 `== FALLBACK_TYPE_KEY`,那个 key 已经没有了:
    // 「还没判出来」现在由 `None` 表达(0009)。两边都是 None
    // 已经被上面 `a == b` 那行接住
    let (Some(a), Some(b)) = (a, b) else {
        return TypeDrift::Recall;
    };
    if CONFUSABLE_TYPE_KEYS.contains(&a) && CONFUSABLE_TYPE_KEYS.contains(&b) {
        return TypeDrift::Review;
    }
    TypeDrift::Disjoint
}

fn cosine(a: &[f32], b: &[f32]) -> Option<f32> {
    if a.len() != b.len() || a.is_empty() {
        return None;
    }
    let (mut dot, mut na, mut nb) = (0f32, 0f32, 0f32);
    for (x, y) in a.iter().zip(b) {
        dot += x * y;
        na += x * x;
        nb += y * y;
    }
    if na == 0.0 || nb == 0.0 {
        return None;
    }
    Some(dot / (na.sqrt() * nb.sqrt()))
}

#[derive(Debug, sqlx::FromRow)]
struct Candidate {
    id: Uuid,
    canonical_name: String,
    profile_embedding: Option<Vector>,
    profile_n: i32,
}

/// 这些实体各自的度数(不数名字事实),与 `ids` 同序;没有事实的是 0。
async fn degrees(pool: &PgPool, kb_id: Uuid, ids: &[Uuid]) -> AppResult<Vec<i64>> {
    let rows: HashMap<Uuid, i64> = sqlx::query_as(&format!(
        "SELECT n.id, count(*)
           FROM unnest($2::uuid[]) AS n(id)
           JOIN facts f ON f.kb_id = $1 AND (f.subject_id = n.id OR f.object_id = n.id)
                       AND f.invalidated_at IS NULL AND {not_name}
          GROUP BY n.id",
        not_name = crate::names::not_a_name("f"),
    ))
    .bind(kb_id)
    .bind(ids)
    .fetch_all(pool)
    .await?
    .into_iter()
    .collect();
    Ok(ids
        .iter()
        .map(|id| rows.get(id).copied().unwrap_or(0))
        .collect())
}

/// 消解结果:mention 落到了哪个实体;附带需要入队的疑似重复审核对
/// (同名灰区 / 类型漂移),由调用方写入审核队列并触发裁决任务。
#[derive(Debug)]
pub struct Resolution {
    pub entity_id: Uuid,
    pub created: bool,
    pub reviews: Vec<ReviewRequest>,
}

/// 待入队的审核对:`Resolution::entity_id` vs `other_id`。
#[derive(Debug)]
pub struct ReviewRequest {
    pub other_id: Uuid,
    pub score: f32,
    pub reason: String,
    /// 交给谁裁:画像灰区走 [`ReviewStage::Adjudicating`](批量裁决器),
    /// 同名并列只有人分得开,走 [`ReviewStage::Human`]。
    pub stage: ReviewStage,
}

/// 审核项由谁消费。普通画像灰区先交给批量裁决器;抽取器在同一回复里明确拆出的
/// 同名实体只有人能判断,不能让几乎相同的画像触发自动合并。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReviewStage {
    Adjudicating,
    Human,
}

impl ReviewStage {
    fn as_str(self) -> &'static str {
        match self {
            Self::Adjudicating => "adjudicating",
            Self::Human => "human",
        }
    }
}

/// 消解一个 mention。召回走两条通道(0041 决定 3):名字字面相等(通道 1,
/// `resolve_by_name` 里的那条 SQL)和名字向量最近邻(通道 2,给了 `name_vector` 才走)。
///
/// **通道 2 只提议,不决定。** 它召回到的实体这一刀不参与归并——决定该由证据来做,
/// 那是 0041 的第 3 刀,还没建——只给裁决器排一对(`name_vector|<余弦>`),让它拿两份
/// 画像和先例去判是不是一个。于是这一刀加的是「多问一句」,不是「多合一次」:错合
/// 是静默的、要人回头拆,多问只是贵一点。
///
/// 同一个字面名字不走通道 2:那是通道 1 的地盘,它已经按画像判过了,再排一对等于
/// 让裁决器复议一个刚做过的决定。大类对不上的也不提议(海探1 是设备,不会是一个人)。
#[allow(clippy::too_many_arguments)]
pub async fn resolve_mention(
    pool: &PgPool,
    kb_id: Uuid,
    type_id: Option<Uuid>,
    raw_name: &str,
    context: Option<&[f32]>,
    // mention 名字本身的向量(不是块的)。None = 没配嵌入模型,或这次没算
    name_vector: Option<&[f32]>,
    text: Option<&str>,
    exclude: &[Uuid],
) -> AppResult<Resolution> {
    let mut r = resolve_by_name(pool, kb_id, type_id, raw_name, context, text, exclude).await?;
    if let Some(query) = name_vector {
        propose_by_name_vector(pool, kb_id, type_id, raw_name, query, exclude, &mut r).await?;
    }
    // 判过「不是一个」的对不再排。新建的实体没有过去,没东西要排的也不用问
    if !r.created && !r.reviews.is_empty() {
        let kept = kept_apart_from(pool, kb_id, r.entity_id).await?;
        r.reviews.retain(|v| !kept.contains(&v.other_id));
    }
    Ok(r)
}

/// 跟这个实体判过「不是一个」的那些实体。
///
/// **每次提到都会走到召回**:名字向量通道不分新建还是归并,同名易混类型那条路也是
/// 归并之后照常入队。而审核表的唯一索引只管 pending 的行——判完的一对下次被提到,
/// 就又是一条新的 pending。一个有六万实体的库上,`migration 395` 每出现在一篇新文档里,
/// 它跟 `migration 394` 等八个近邻就重新排一遍队,裁决器(或人)分开过多少次都一样
/// (#1104)。分开这个决定要记得住,[`crate::names::pair_shared_name`] 早就是这么做的。
///
/// 人仍然可以在审核页把分开过的一对合并:这里拦的是自动重提,不是合并本身。
async fn kept_apart_from(pool: &PgPool, kb_id: Uuid, entity_id: Uuid) -> AppResult<HashSet<Uuid>> {
    let rows: Vec<(Uuid,)> = sqlx::query_as(
        "SELECT CASE WHEN left_id = $2 THEN right_id ELSE left_id END
           FROM resolution_reviews
          WHERE kb_id = $1 AND status = 'kept' AND (left_id = $2 OR right_id = $2)",
    )
    .bind(kb_id)
    .bind(entity_id)
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().map(|(id,)| id).collect())
}

/// 通道 2:mention 名字向量的近邻,各排一对(规矩见 [`resolve_mention`])
async fn propose_by_name_vector(
    pool: &PgPool,
    kb_id: Uuid,
    type_id: Option<Uuid>,
    raw_name: &str,
    query: &[f32],
    exclude: &[Uuid],
    r: &mut Resolution,
) -> AppResult<()> {
    let mention_name = name_key(raw_name);
    let mention_family = match type_id {
        Some(t) => type_label(pool, t)
            .await?
            .as_deref()
            .and_then(crate::governance::type_family),
        None => None,
    };
    let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
    let mut seen: HashSet<Uuid> = r.reviews.iter().map(|v| v.other_id).collect();
    seen.insert(r.entity_id);
    seen.extend(exclude.iter().copied());
    for near in crate::name_vectors::nearest(pool, kb_id, query, crate::name_vectors::TOP_K).await?
    {
        if near.similarity < crate::name_vectors::SIM_FLOOR {
            break; // 降序:后面的更远
        }
        if near.name.to_lowercase() == mention_name || !seen.insert(near.entity_id) {
            continue;
        }
        // 只差一个数的名字向量上几乎重合,却几乎从不是同一个(见 `numbers_differ`)
        if crate::names::numbers_differ(raw_name, &near.name) {
            continue;
        }
        let near_family = near
            .type_label
            .as_deref()
            .and_then(crate::governance::type_family);
        if let (Some(a), Some(b)) = (mention_family, near_family) {
            if a != b {
                continue;
            }
        }
        // 大类认不出的类(Spec、Test……)靠本体声明分开,与 containment、类型漂移同一张表
        if near.type_id.is_some_and(|t| disjoint.contains(&t)) {
            continue;
        }
        r.reviews.push(ReviewRequest {
            other_id: near.entity_id,
            score: near.similarity,
            reason: format!(
                "{}{:.2}",
                utopia_core::review_reasons::NAME_VECTOR,
                near.similarity
            ),
            stage: ReviewStage::Adjudicating,
        });
    }
    Ok(())
}

async fn type_label(pool: &PgPool, type_id: Uuid) -> AppResult<Option<String>> {
    Ok(
        sqlx::query_scalar("SELECT label FROM entity_types WHERE id = $1")
            .bind(type_id)
            .fetch_optional(pool)
            .await?,
    )
}

/// 通道 1:名字字面相等的候选,按画像分层归并或新建(原 `resolve_mention` 的全部)。
/// `context` 为 mention 所在分块的向量(无 embedding 模型时为 None,退化为 v1 行为:
/// 同名归并到事实最多的候选)。
#[allow(clippy::too_many_arguments)]
async fn resolve_by_name(
    pool: &PgPool,
    kb_id: Uuid,
    // None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
    type_id: Option<Uuid>,
    raw_name: &str,
    context: Option<&[f32]>,
    // 这次提及所在的**块原文**。画像分不出谁是谁时拿它做事实旁证(#331)——
    // 传整篇文档会让每个部门都命中,所以这里要的是句子或块,不是文档。
    text: Option<&str>,
    // Candidates already claimed by a different response-local handle. They remain stored
    // and recallable on later calls, but this mention cannot attach to them.
    exclude: &[Uuid],
) -> AppResult<Resolution> {
    let normalized = normalize_name(raw_name);
    // 召回键 = 本名 + 泛用后缀词干及其增广("星尘"↔"星尘项目"互为候选)。
    // 只扩召回,归并与否仍由下方画像相似度分层定夺。
    let keys = recall_keys(&normalized);
    // Store the same spelling whichever form is mentioned first.
    let name = fold_markdown_markers(&normalized);
    // 名字召回读名字事实(0041 决定 1):本名、简称、曾用名都是 `known_as` 上的一条。
    // 度数不数名字事实——名字不是一条「关于它的事」,数进去每个实体都凭空多一
    // 度数要等真有几个候选得比时才数:每个候选一条计数子查询,大库上很贵(#1296)
    let candidates: Vec<Candidate> = sqlx::query_as(&format!(
        "SELECT e.id, e.canonical_name, e.profile_embedding, e.profile_n
         FROM entities e
         -- IS NOT DISTINCT FROM 而不是 =(0009 的那个陷阱):开放图谱里的实体都没有类
         -- (类由对齐来定),`type_id = NULL` 永远不成立,同名的它就永远撞不上——
         -- 实测一个库里 Securities and Exchange Commission 与它的全大写写法成了两个实体
         WHERE e.kb_id = $1 AND e.type_id IS NOT DISTINCT FROM $2 AND e.merged_into IS NULL
           -- 被描述的东西没有名字(0044):它的 canonical_name 只是显示用的描述,
           -- 不是召回的桥——两篇文档里描述得一样的两个东西不能因此接到一起
           AND e.description IS NULL
           AND (lower(e.canonical_name) = ANY($3) OR {named})",
        named = crate::names::has_name_in("e", 1, 3),
    ))
    .bind(kb_id)
    .bind(type_id)
    .bind(&keys)
    .fetch_all(pool)
    .await?
    .into_iter()
    .filter(|candidate: &Candidate| !exclude.contains(&candidate.id))
    .collect();

    if candidates.is_empty() {
        // 同类型无候选 ≠ 新名字:类型标签会漂(同一团队被抽成 organization/project/
        // concept),先查其它类型下的同名实体,按类型对的互斥强度分流。
        return resolve_type_drift(pool, kb_id, type_id, name, &keys, context, exclude).await;
    }

    let Some(ctx) = context else {
        // 无向量可比:v1 兼容 —— 归并到事实最多的同名候选
        let best = match candidates.as_slice() {
            [only] => only,
            _ => {
                let ids: Vec<Uuid> = candidates.iter().map(|c| c.id).collect();
                let degree = degrees(pool, kb_id, &ids).await?;
                candidates
                    .iter()
                    .zip(degree)
                    .max_by_key(|(_, d)| *d)
                    .map(|(c, _)| c)
                    .expect("non-empty")
            }
        };
        touch_entity(pool, best.id).await?;
        return Ok(Resolution {
            entity_id: best.id,
            created: false,
            reviews: Vec::new(),
        });
    };

    // 这一次调用**绝不能归上去**的全部:调用方点名排除的(`exclude`),加上这一轮
    // 看过、并且会被判「不是同一个」的同名候选。下面无论走哪条分支决定新建,都要把
    // 这份名单递给 `create_entity`——锁里那条回捞按名字捞,不给名单就会把它们捞回来
    let weighed: Vec<Uuid> = exclude
        .iter()
        .copied()
        .chain(candidates.iter().map(|c| c.id))
        .collect();

    // 有画像的候选算相似度;无画像(历史数据/无 embedding 期创建)单独归类
    let mut scored: Vec<(&Candidate, f32)> = Vec::new();
    let mut unprofiled: Vec<&Candidate> = Vec::new();
    for c in &candidates {
        match c
            .profile_embedding
            .as_ref()
            .and_then(|p| cosine(p.as_slice(), ctx))
        {
            Some(sim) => scored.push((c, sim)),
            None => unprofiled.push(c),
        }
    }
    // 最高分候选:并列时保留先遇到的那个(与旧的 `sim > s` 严格大于一致)
    let best_scored = scored
        .iter()
        .copied()
        .reduce(|acc, cur| if cur.1 > acc.1 { cur } else { acc });

    if let Some((best, sim)) = best_scored {
        if sim >= SIM_ATTACH {
            // 同名并列的灰区:另有一个**同名**候选的分数贴着最高分(差 ≤ SIM_TIE_MARGIN),
            // 画像分不出谁是谁——attach 到分高的那个只是候选顺序掷出的硬币(#270)。
            // 宁分勿合:不 attach,新建实体,对并列的两个候选各入一条**人工**审核对。
            // 分数无论多高都拦:高分并列正是静默错并的危险区,不能因为「够像」就放行。
            if let Some((runner, r_sim)) = scored
                .iter()
                .copied()
                .filter(|(c, s)| {
                    // 同名比较要与召回一致地忽略大小写:召回用 SQL `lower()`,
                    // 「Zhang Wei」与「zhang wei」本就是一对同名候选,不能漏。
                    c.id != best.id
                        && c.canonical_name.to_lowercase() == best.canonical_name.to_lowercase()
                        && sim - *s <= SIM_TIE_MARGIN
                })
                .reduce(|acc, cur| if cur.1 > acc.1 { cur } else { acc })
            {
                // 画像掷硬币之前,先问事实(#331):这句话里提到了其中一个人的
                // 部门或职位吗?提到了就不是硬币,是线索
                if let Some(t) = text {
                    if let Some(c) =
                        corroborating_candidate(pool, kb_id, &[best, runner], t).await?
                    {
                        update_profile(pool, c.id, c.profile_n, ctx).await?;
                        return Ok(Resolution {
                            entity_id: c.id,
                            created: false,
                            reviews: Vec::new(),
                        });
                    }
                }
                let (id, created) =
                    create_entity(pool, kb_id, type_id, name, context, &weighed).await?;
                if !created {
                    // 并行的另一份文档刚建好它:用它的,审核对也是它排的
                    return Ok(Resolution {
                        entity_id: id,
                        created: false,
                        reviews: Vec::new(),
                    });
                }
                refresh_disambiguators(pool, kb_id, name).await?;
                let reviews = [(best, sim), (runner, r_sim)]
                    .into_iter()
                    .map(|(c, s)| ReviewRequest {
                        other_id: c.id,
                        score: s,
                        reason: format!("namesake_tie|{s:.2}"),
                        stage: ReviewStage::Human,
                    })
                    .collect();
                return Ok(Resolution {
                    entity_id: id,
                    created: true,
                    reviews,
                });
            }
            update_profile(pool, best.id, best.profile_n, ctx).await?;
            return Ok(Resolution {
                entity_id: best.id,
                created: false,
                reviews: Vec::new(),
            });
        }
    }
    let unprofiled = match unprofiled.as_slice() {
        [] => None,
        [only] => Some(*only),
        many => {
            let ids: Vec<Uuid> = many.iter().map(|c| c.id).collect();
            let degree = degrees(pool, kb_id, &ids).await?;
            many.iter()
                .copied()
                .zip(degree)
                .reduce(|acc, cur| if cur.1 > acc.1 { cur } else { acc })
                .map(|(c, _)| c)
        }
    };
    if let Some(c) = unprofiled {
        // 无画像候选无从判别:v1 兼容归并,并用本次上下文初始化画像
        update_profile(pool, c.id, c.profile_n, ctx).await?;
        return Ok(Resolution {
            entity_id: c.id,
            created: false,
            reviews: Vec::new(),
        });
    }

    // 走到这里:所有候选都有画像且最高分 < ATTACH → 新建实体(同名不同人)。
    //
    // 但先问一次事实(#331)。灰区的意思是"向量说不好",不是"一定是新人"——
    // 这句话里若正好写着某一个候选的部门或职位,那比余弦值可靠。
    // **只认灰区**(≥ SIM_NEW):分数低于它的候选连审核对都不配入队,
    // 拿一条旁证把它拉成同一人,等于绕过阈值而不是补充它。
    if let Some(t) = text {
        let in_grey: Vec<&Candidate> = scored
            .iter()
            .filter(|(_, s)| *s >= SIM_NEW)
            .map(|(c, _)| *c)
            .collect();
        if let Some(c) = corroborating_candidate(pool, kb_id, &in_grey, t).await? {
            update_profile(pool, c.id, c.profile_n, ctx).await?;
            return Ok(Resolution {
                entity_id: c.id,
                created: false,
                reviews: Vec::new(),
            });
        }
    }
    let (id, created) = create_entity(pool, kb_id, type_id, name, context, &weighed).await?;
    if !created {
        // 并行的另一份文档刚建好它:用它的,审核对也是它排的
        return Ok(Resolution {
            entity_id: id,
            created: false,
            reviews: Vec::new(),
        });
    }
    refresh_disambiguators(pool, kb_id, name).await?;
    let mut reviews = best_scored
        .filter(|(_, sim)| *sim >= SIM_NEW)
        .map(|(c, sim)| {
            vec![ReviewRequest {
                other_id: c.id,
                score: sim,
                reason: format!("ambiguous_name|{sim:.2}"),
                stage: ReviewStage::Adjudicating,
            }]
        })
        .unwrap_or_default();
    // 名字互相包含的既有实体:等值召回看不见它们(前缀枚举不完),
    // 于是简称会静默变成第二个实体。只入队,不合并
    reviews.extend(containment_reviews(pool, kb_id, type_id, name, id, context).await?);
    Ok(Resolution {
        entity_id: id,
        created: true,
        reviews,
    })
}

/// **事实旁证**:这次提及的原文里,出现了某个候选的消歧宾语吗(#331)。
///
/// 画像向量分不出谁是谁时,能分开的线索往往就在事实里——一个张伟 `works_for`
/// 平台工程部,另一个 `works_for` 财务部,而这句话里写着"财务"。人在审核卡上
/// 看的正是这些事实(`top_facts`),这一步是把人做的事交回给代码。
///
/// **证据只往一个方向走。** 一致是"同一人"的弱证据;不一致**什么都不是**——
/// 在 Acme 上班又在 Zenith 兼职的人有两个 `works_for` 值,他仍是一个人。所以
/// 这个函数只回答"哪个候选被原文提到了",永远不回答"哪个候选被排除了"。
///
/// **恰好一个候选命中才算数。** 两个都命中说明这条线索在他们之间也分不开,
/// 与其挑一个不如维持原样。
///
/// 宾语的挑法与 `refresh_disambiguators` 同源(#299 之后从本体的 range 声明选,
/// 不是词表),并且**排除同名同伴也指着的那些**:两个张伟都在同一家公司时,
/// 公司名对分辨他们毫无帮助,却最容易在文档里撞上。
async fn corroborating_candidate<'a>(
    pool: &PgPool,
    kb_id: Uuid,
    candidates: &[&'a Candidate],
    text: &str,
) -> AppResult<Option<&'a Candidate>> {
    // 单个候选也算数:「其他候选都没命中」在只有一个候选时天然成立
    if candidates.is_empty() || text.trim().is_empty() {
        return Ok(None);
    }
    let ids: Vec<Uuid> = candidates.iter().map(|c| c.id).collect();
    // 一次查完所有候选:每个候选取若干个「同伴不指向」的宾语名字。
    //
    // **LEFT JOIN relation_types**(0044):开放陈述没有谓词、只有照抄的短语,
    // 它指着的宾语一样是这个候选的画像——「收购了 Beta」不因为本体没接住
    // 「收购了」就不算佐证。排序里关系的三个布尔位对开放行是 NULL,COALESCE
    // 成 false 排在类型化行之后:类型化行之间的次序一字不变
    let rows: Vec<(Uuid, String)> = sqlx::query_as(
        "SELECT s.subject_id, s.name FROM (
           SELECT f.subject_id, o.canonical_name AS name,
                  row_number() OVER (
                    PARTITION BY f.subject_id
                    ORDER BY EXISTS (SELECT 1 FROM relation_type_ranges rr
                                      WHERE rr.relation_type_id = r.id) DESC,
                             COALESCE(r.temporal = 'state', FALSE) DESC,
                             COALESCE(r.functional, FALSE) DESC,
                             f.confidence DESC, f.recorded_at DESC
                  ) AS rn
           FROM facts f
           LEFT JOIN relation_types r ON r.id = f.predicate_id
           JOIN entities o ON o.id = f.object_id
           WHERE f.kb_id = $1 AND f.subject_id = ANY($2)
             AND f.invalidated_at IS NULL AND f.object_id IS NOT NULL
             -- 同名同伴也指着的宾语没有分辨力,排除
             AND NOT EXISTS (SELECT 1 FROM facts g
                              WHERE g.kb_id = $1 AND g.subject_id = ANY($2)
                                AND g.subject_id <> f.subject_id
                                AND g.object_id = f.object_id
                                AND g.invalidated_at IS NULL)
         ) s WHERE s.rn <= $3",
    )
    .bind(kb_id)
    .bind(&ids)
    .bind(CORROBORATION_OBJECTS)
    .fetch_all(pool)
    .await?;

    let haystack = text.to_lowercase();
    let mut hit: Option<&'a Candidate> = None;
    for (subject_id, object_name) in &rows {
        let needle = object_name.trim().to_lowercase();
        if needle.chars().count() < MIN_CORROBORATION_CHARS || !haystack.contains(&needle) {
            continue;
        }
        let Some(c) = candidates.iter().find(|c| c.id == *subject_id) else {
            continue;
        };
        match hit {
            // 同一个候选的第二条宾语也命中:仍是同一个候选,不算分歧
            Some(prev) if prev.id == c.id => {}
            // 命中了第二个候选:这条线索分不开他们
            Some(_) => return Ok(None),
            None => hit = Some(c),
        }
    }
    Ok(hit)
}

/// 包含关系候选的最短边:两个名字里**较短的那个**至少这么长才算数。
/// 低于它的多是「研究院」「中心」这类通名,配对没有信息量,只会刷爆队列。
const MIN_CONTAIN_CHARS: i32 = 4;

/// 单次最多产出的包含关系审阅对。与 `MAX_DRIFT_REVIEWS` 同理:
/// 一个通名可能包含在几十个实体里,全放进去就把队列淹了。
const MAX_CONTAIN_REVIEWS: usize = 4;

/// SQL 侧多取几行:类型硬互斥的在 Rust 侧才筛得掉,
/// 只取 4 行的话可能 4 行全是互斥类型,真正那一对反而被 LIMIT 切掉。
const CONTAIN_SCAN_LIMIT: i64 = 16;

/// 名字当 LIKE 的字面子串用:不转义的话名字里的 `_` 会匹配任意一个字(#1293)
fn like_escaped(name: &str) -> String {
    name.replace('\\', "\\\\")
        .replace('%', "\\%")
        .replace('_', "\\_")
}

/// 新建实体之后,找出**名字互相包含**的既有实体,作为审阅候选。
///
/// 中文商业文本在一篇之内就会全称转简称(「星云科技上海研究院」→「上海研究院」),
/// 而 [`recall_keys`] 是等值查:它靠枚举泛用后缀命中反向,可前缀是任意组织名,
/// **枚举不完**。于是这三类全部漏网,静默变成第二个实体:
///
/// ```text
/// 上海研究院       ⊂ 星云科技上海研究院      后缀被限定
/// 启明 X7 加速卡   ~ 启明 X7 推理加速卡      中间插词(靠 LIKE 覆盖不到,见下)
/// 沧海             ⊂ 沧海分布式推理平台 2.0  前缀被扩展
/// ```
///
/// **只出候选,永不自动合并。** 同名候选那条路在相似度 ≥ [`SIM_ATTACH`] 时直接归并,
/// 包含关系绝不能走它:`华瑞集团技术中心` 与 `星云科技技术中心` 都含「技术中心」,
/// 同一篇文档里上下文相似度很容易过线,而它们是两个部门。宁分勿合。
///
/// **别的名字一并参与**:合并会把名字事实搬到存活者身上,只查 `canonical_name` 的话,
/// 每成功合并一次就少一条召回的桥——`Holmes` 并入 `Sherlock Holmes` 之后,
/// 后来的 `Mr. Holmes` 就再也搭不上了(它跟 `Sherlock Holmes` 谁也不含谁)。
/// 合并越成功、漏得越多,是个会自我加剧的洞。
///
/// **已知不覆盖**:两个名字既不互相包含、又没有共同别名做桥的情形
///(`启明 X7 加速卡` 与 `启明 X7 推理加速卡`)。那要三元组相似度,而
/// `CREATE EXTENSION pg_trgm` 需要超级权限——本仓库是受限角色连库(见 `migrations/0010_least_privilege_role.sql`),
/// 装扩展会在部署上失败。留给需要时再说。
///
/// **性能**:反向那半(新名字包含旧名字)用不上任何索引,别名那半同样,
/// 所以这里靠 `kb_id` 收窄行集并设上限,且只在**新建实体时**跑一次,
/// 不是每条 mention。大库上如果不够,正解是建一张「后缀键」表走等值查,
/// 而不是加模糊索引。
/// 包含扫描的一行:(id, 本名, 类型 key, 类型 id, 画像)。类型 id 用来比本体声明的互斥
type ContainRow = (Uuid, String, Option<String>, Option<Uuid>, Option<Vector>);

async fn containment_reviews(
    pool: &PgPool,
    kb_id: Uuid,
    // None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
    type_id: Option<Uuid>,
    name: &str,
    new_id: Uuid,
    ctx: Option<&[f32]>,
) -> AppResult<Vec<ReviewRequest>> {
    let lower = name.to_lowercase();
    if lower.chars().count() < MIN_CONTAIN_CHARS as usize {
        return Ok(Vec::new());
    }
    // 实体可能还没判出类型(0009),那时没有 key 可查
    let mention_key: Option<String> = match type_id {
        Some(t) => sqlx::query_as::<_, (String,)>("SELECT key FROM entity_types WHERE id = $1")
            .bind(t)
            .fetch_optional(pool)
            .await?
            .map(|(k,)| k),
        None => None,
    };
    // **不按类型过滤**:简称经常掉进 concept 兜底,而全称是具体类型
    //(实测 上海研究院→concept vs 星云科技上海研究院→organization,
    //  启明 X7 加速卡→concept vs 启明 X7 推理加速卡→product),
    //  按类型相等去查,这两对一个都捞不到。相容性交给下面的 classify_type_drift。
    //  多取一些行,因为硬互斥的会在 Rust 侧被筛掉
    // 本体声明了跟这个类互斥的那些类(含继承),一次取出,逐行比 id
    let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
    // 第三列可空:未分类实体也要参与包含关系扫描(0009)
    let rows: Vec<ContainRow> = sqlx::query_as(
        "SELECT e.id, e.canonical_name, t.key, e.type_id, e.profile_embedding
         FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
         WHERE e.kb_id = $1 AND e.merged_into IS NULL
           AND e.id <> $2
           AND lower(e.canonical_name) <> $3
           AND (
             (char_length(e.canonical_name) >= $4
              AND (lower(e.canonical_name) LIKE '%' || $6 || '%'
                   OR $3 LIKE '%' || replace(replace(replace(lower(e.canonical_name), '\\', '\\\\'), '%', '\\%'), '_', '\\_') || '%'))
             -- **别的名字也要参与召回,否则每合并一次就少一条桥。**
             --
             -- 合并把名字事实搬到存活者身上:Holmes 并入 Sherlock Holmes 之后,
             -- Holmes 那一行 merged_into 非空、被上面第一个条件滤掉了。可十分钟后
             -- 出现的 Mr. Holmes 跟 Sherlock Holmes 谁也不含谁——本来正是靠
             -- Holmes 才桥得上。实测就是这么漏的:同类型那个 bug 修好、Holmes
             -- 正确合并之后,Mr. Holmes 反而永远进不了队列。
             --
             -- 合并越成功,桥拆得越多。这个洞会自我加剧。
             OR EXISTS (
               SELECT 1 FROM facts nf
                 JOIN relation_types nr ON nr.id = nf.predicate_id
                WHERE nf.subject_id = e.id AND nf.kb_id = $1
                  AND nr.builtin AND nr.key = 'known_as'
                  AND nf.invalidated_at IS NULL
                  AND char_length(nf.object_value->>'value') >= $4
                  AND (lower(nf.object_value->>'value') LIKE '%' || $6 || '%'
                       OR $3 LIKE '%' || replace(replace(replace(lower(nf.object_value->>'value'), '\\', '\\\\'), '%', '\\%'), '_', '\\_') || '%'))
           )
         ORDER BY char_length(e.canonical_name)
         LIMIT $5",
    )
    .bind(kb_id)
    .bind(new_id)
    .bind(&lower)
    .bind(MIN_CONTAIN_CHARS)
    .bind(CONTAIN_SCAN_LIMIT)
    .bind(like_escaped(&lower))
    .fetch_all(pool)
    .await?;

    Ok(rows
        .into_iter()
        // 哪些类型对可能指同一个东西,既有规则已经想清楚了,别另发明一套:
        // 本体声明互斥的永不合并,person vs organization 永不合并,
        // concept 兜底与谁都可能是一个
        .filter(|(_, other_name, type_key, other_type, _)| {
            !other_type.is_some_and(|t| disjoint.contains(&t))
                && classify_type_drift(mention_key.as_deref(), type_key.as_deref())
                    != TypeDrift::Disjoint
                // `migration 39` 是 `migration 395` 的子串,但不是它的简称(见 `numbers_differ`)。
                // 筛在 take 之前:带别的数的兄弟不该占掉真候选的名额
                && !crate::names::numbers_differ(name, other_name)
        })
        .take(MAX_CONTAIN_REVIEWS)
        .map(|(id, other_name, _, _, emb)| {
            // 分数只是给队列排序用的参考,**不参与是否合并的判断**——
            // 那个判断本来就不在这条路上
            let score = ctx
                .and_then(|x| emb.as_ref().and_then(|p| cosine(p.as_slice(), x)))
                .unwrap_or(0.0);
            ReviewRequest {
                other_id: id,
                score,
                reason: format!("contains|{other_name}"),
                stage: ReviewStage::Adjudicating,
            }
        })
        .collect())
}

#[derive(Debug, sqlx::FromRow)]
struct CrossCandidate {
    id: Uuid,
    canonical_name: String,
    // None = 这个候选还没判出类型(0009)
    type_key: Option<String>,
    // 同上;`types_are_kin` 要按 id 走类层级
    type_id: Option<Uuid>,
    // 抽取升格要看它:人说过「就是没有类型」时,那也是一个决定
    type_source: String,
    profile_embedding: Option<Vector>,
    profile_n: i32,
}

/// `reason` 存 code,措辞归界面(docs/decisions/0004)——这一列不该一半 code
/// 一半英文句子,那样中文界面上就是一半能翻一半不能。
fn drift_reason(mention_key: Option<&str>, other_key: Option<&str>, sim: Option<f32>) -> String {
    // 未分类的一侧写成 `(untyped)`。这一列存 code 供界面翻译,
    // 留空会让 `a vs b` 变成 `a vs `,读起来像被截断而不像"没有"
    let a = mention_key.unwrap_or("(untyped)");
    let b = other_key.unwrap_or("(untyped)");
    match sim {
        Some(s) => format!("type_drift|{a} vs {b} {s:.2}"),
        None => format!("type_drift|{a} vs {b}"),
    }
}

/// 本体声明了跟这个类互斥的全部类(0016 B3)。
///
/// **互斥是继承的**:Person ⟂ Organization 一条声明,就让 Person 的每个子类跟
/// Organization 的每个子类都互斥。所以先沿父链往上收集这个类的祖先,取它们声明的
/// 互斥对象,再沿子链往下展开。表里两个方向各存一行,问一个方向就够。
///
/// 没判出类型(`None`)时没有类可问,回空集:那一侧本来就走召回候选那一档
async fn declared_disjoint_from(
    pool: &PgPool,
    kb_id: Uuid,
    type_id: Option<Uuid>,
) -> AppResult<HashSet<Uuid>> {
    let Some(type_id) = type_id else {
        return Ok(HashSet::new());
    };
    let rows: Vec<(Uuid,)> = sqlx::query_as(
        "WITH RECURSIVE up(id) AS (
             SELECT $2::uuid
             UNION
             SELECT p.parent_id FROM entity_type_parents p JOIN up ON p.child_id = up.id
         ), hit(id) AS (
             SELECT d.b_id FROM entity_type_disjoint d JOIN up ON d.a_id = up.id
              WHERE d.kb_id = $1
         ), down(id) AS (
             SELECT id FROM hit
             UNION
             SELECT p.child_id FROM entity_type_parents p JOIN down ON p.parent_id = down.id
         )
         SELECT id FROM down",
    )
    .bind(kb_id)
    .bind(type_id)
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().map(|(id,)| id).collect())
}

/// 两个类是不是一家的:一方是另一方的祖先,或者两者共有一个**不是根**的祖先。
///
/// `CONFUSABLE_TYPE_KEYS` 那张三 key 的硬表是给没装包的库准备的;装了 schema.org
/// 之后同一家公司会被抽成 Organization / Corporation / OnlineBusiness 三种类型,
/// 全都在 Organization 之下,却一对都过不了硬表,于是三个同名实体并存、
/// 审阅队列里一条都没有,面板还指着 Review 说"去那里合并"(#226)。
///
/// 根不算共同祖先:schema.org 里万物皆 Thing,算上它 Person 与 Organization
/// 也成了一家。没有根的词汇表(W3C Org 的 Organization 自己就是顶)靠
/// 祖先/后代那一半接住
async fn types_are_kin(pool: &PgPool, a: Uuid, b: Uuid) -> AppResult<bool> {
    let (kin,): (bool,) = sqlx::query_as(
        "WITH RECURSIVE up_a(id) AS (
             SELECT $1::uuid
             UNION
             SELECT p.parent_id FROM entity_type_parents p JOIN up_a ON p.child_id = up_a.id
         ), up_b(id) AS (
             SELECT $2::uuid
             UNION
             SELECT p.parent_id FROM entity_type_parents p JOIN up_b ON p.child_id = up_b.id
         )
         SELECT EXISTS (SELECT 1 FROM up_a WHERE id = $2)
             OR EXISTS (SELECT 1 FROM up_b WHERE id = $1)
             OR EXISTS (SELECT 1 FROM up_a JOIN up_b USING (id)
                         WHERE EXISTS (SELECT 1 FROM entity_type_parents p
                                        WHERE p.child_id = up_a.id))",
    )
    .bind(a)
    .bind(b)
    .fetch_one(pool)
    .await?;
    Ok(kin)
}

fn confusable_reviews(
    // None = 这一侧还没判出类型(0009)
    mention_key: Option<&str>,
    cands: &[&CrossCandidate],
    ctx: Option<&[f32]>,
) -> Vec<ReviewRequest> {
    cands
        .iter()
        .map(|c| {
            let sim = ctx.and_then(|x| {
                c.profile_embedding
                    .as_ref()
                    .and_then(|p| cosine(p.as_slice(), x))
            });
            ReviewRequest {
                other_id: c.id,
                score: sim.unwrap_or(0.0),
                reason: drift_reason(mention_key, c.type_key.as_deref(), sim),
                stage: ReviewStage::Adjudicating,
            }
        })
        .collect()
}

/// 同类型召回为空时的跨类型处置(类型漂移)。
/// concept 兜底型候选跑既有画像分层:高相似直接 ATTACH(漂移的召回修复,concept
/// 侧类型升格为具体类型),灰区/无从判别 → 宁分勿合新建 + 审核对;易混具体类型
/// 一律新建 + 审核对(同名 + 类型摇摆本身就是信号,不设相似度门槛);硬互斥忽略。
async fn resolve_type_drift(
    pool: &PgPool,
    kb_id: Uuid,
    // None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
    type_id: Option<Uuid>,
    name: &str,
    keys: &[String],
    context: Option<&[f32]>,
    exclude: &[Uuid],
) -> AppResult<Resolution> {
    // 这一侧也可能还没判出类型(0009),那时没有 key 可查
    let mention_key: Option<String> = match type_id {
        Some(t) => sqlx::query_as::<_, (String,)>("SELECT key FROM entity_types WHERE id = $1")
            .bind(t)
            .fetch_optional(pool)
            .await?
            .map(|(k,)| k),
        None => None,
    };
    let cross: Vec<CrossCandidate> = sqlx::query_as(&format!(
        "SELECT e.id, e.canonical_name, t.key AS type_key, e.type_id, e.type_source,
                e.profile_embedding, e.profile_n
         FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
         -- IS DISTINCT FROM 而不是 <>:后者遇 NULL 返回 NULL,被 WHERE 当假,
         -- 未分类实体会被整个漏掉(0009)
         WHERE e.kb_id = $1 AND e.type_id IS DISTINCT FROM $2 AND e.merged_into IS NULL
           -- 被描述的东西不参与名字召回(0044),同上
           AND e.description IS NULL
           AND (lower(e.canonical_name) = ANY($3) OR {named})",
        named = crate::names::has_name_in("e", 1, 3),
    ))
    .bind(kb_id)
    .bind(type_id)
    .bind(keys)
    .fetch_all(pool)
    .await?
    .into_iter()
    .filter(|candidate: &CrossCandidate| !exclude.contains(&candidate.id))
    .collect();

    // 本体声明了互斥的类,一次取出(含继承)。声明优先于下面所有启发式
    let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
    let mut recall_cands: Vec<&CrossCandidate> = Vec::new();
    let mut review_cands: Vec<&CrossCandidate> = Vec::new();
    for c in &cross {
        let mut drift = classify_type_drift(mention_key.as_deref(), c.type_key.as_deref());
        if c.type_id.is_some_and(|t| disjoint.contains(&t)) {
            // 本体说这两类互斥:哪怕硬表说易混、类层级说一家,也分开。
            // 声明是人写下的判断,启发式只是没声明时的猜测
            drift = TypeDrift::Disjoint;
        } else if drift == TypeDrift::Disjoint {
            // 硬表判不上的,再看类层级:同一支系下的同名当易混,进审阅队列
            if let (Some(a), Some(b)) = (type_id, c.type_id) {
                if types_are_kin(pool, a, b).await? {
                    drift = TypeDrift::Review;
                }
            }
        }
        match drift {
            TypeDrift::Recall => recall_cands.push(c),
            TypeDrift::Review => review_cands.push(c),
            TypeDrift::Disjoint => {}
        }
    }

    if let Some(ctx) = context {
        let best = recall_cands
            .iter()
            .filter_map(|c| {
                c.profile_embedding
                    .as_ref()
                    .and_then(|p| cosine(p.as_slice(), ctx))
                    .map(|sim| (*c, sim))
            })
            .max_by(|a, b| a.1.total_cmp(&b.1));
        if let Some((best, sim)) = best {
            if sim >= SIM_ATTACH {
                update_profile(pool, best.id, best.profile_n, ctx).await?;
                // 候选还没判出类型而这次抽取判出来了 → 升格。
                // 不是合并(没有第二个实体),不入 entity_merges;本体页可手工改回
                //
                // **人说过的「没有类型」不算「还没判出来」。** 0009 之后两者都是
                // NULL,只看 type_key.is_none() 分不出——于是一个人看过、认为
                // 本体里没有合适类的实体,会在下一次抽取时被安上一个类型
                if best.type_key.is_none() && best.type_source != "human" && type_id.is_some() {
                    sqlx::query(
                        "UPDATE entities
                         SET type_id = $2, type_source = 'extracted', updated_at = now()
                         WHERE id = $1",
                    )
                    .bind(best.id)
                    .bind(type_id)
                    .execute(pool)
                    .await?;
                    // 类型标签兜底的消歧后缀可能已过时
                    refresh_disambiguators(pool, kb_id, &best.canonical_name).await?;
                }
                // mention 已定居到召回实体;同名易混类型实体的疑点仍在 → 照常入队
                let mut reviews =
                    confusable_reviews(mention_key.as_deref(), &review_cands, Some(ctx));
                reviews.truncate(MAX_DRIFT_REVIEWS);
                return Ok(Resolution {
                    entity_id: best.id,
                    created: false,
                    reviews,
                });
            }
        }
    }

    // 同上:点名排除的,加上跨类型同名里掂量过的
    let weighed: Vec<Uuid> = exclude
        .iter()
        .copied()
        .chain(cross.iter().map(|c| c.id))
        .collect();
    let (id, created) = create_entity(pool, kb_id, type_id, name, context, &weighed).await?;
    if !created {
        // 并行的另一份文档刚建好它:用它的,审核对也是它排的
        return Ok(Resolution {
            entity_id: id,
            created: false,
            reviews: Vec::new(),
        });
    }
    if !cross.is_empty() {
        // 跨类型同名并存:消歧后缀按名字分组(不分类型),需要刷新
        refresh_disambiguators(pool, kb_id, name).await?;
    }
    let mut reviews = confusable_reviews(mention_key.as_deref(), &review_cands, context);
    for c in &recall_cands {
        let sim = context.and_then(|ctx| {
            c.profile_embedding
                .as_ref()
                .and_then(|p| cosine(p.as_slice(), ctx))
        });
        match sim {
            // 画像明确不像:完全分开,不打扰审核队列
            Some(s) if s < SIM_NEW => {}
            // 灰区或无从判别(无 embedding / 候选无画像):宁分勿合 + 审核对
            _ => reviews.push(ReviewRequest {
                other_id: c.id,
                score: sim.unwrap_or(0.0),
                reason: drift_reason(mention_key.as_deref(), c.type_key.as_deref(), sim),
                stage: ReviewStage::Adjudicating,
            }),
        }
    }
    reviews.truncate(MAX_DRIFT_REVIEWS);
    // 漂移这条路一样会新建实体,包含关系照查
    reviews.extend(containment_reviews(pool, kb_id, type_id, name, id, context).await?);
    Ok(Resolution {
        entity_id: id,
        created: true,
        reviews,
    })
}

/// 新建一个实体。返回 `(id, 是否真的新建)`。
///
/// **同名同类的新建串行化。** 上面的查找不在事务里:两份文档并行抽取,同一个名字
/// 各自查一遍都没有、各自建一个——实测「澜图数据」在同一秒里建了两个,之后每一次
/// 提到它都撞上两个候选,再各建一个、各排一对审核,一篇语料跑完裂成四个。
/// 这里按(库,名字)拿事务级咨询锁,锁里再查一次:别人刚建好的,就用它的。
/// 不同类型的同名不在此列——那是消歧的事,不是竞态
async fn create_entity(
    pool: &PgPool,
    kb_id: Uuid,
    // None = 抽取器给的类型不在本体里,或库里根本没有类(0009)
    type_id: Option<Uuid>,
    name: &str,
    context: Option<&[f32]>,
    // 调用方**刚刚掂量过、并且决定不并**的那些同名实体。
    //
    // 锁里那条回捞不加这个就分不清两件事:一件是「并行的另一份文档一毫秒前
    // 建好了同名的它」——该用它的;另一件是「这个名字本来就有人,而调用方看过
    // 之后决定另建一个」——这时回捞只会捞回它刚拒绝的那个候选,等于让一把锁
    // 替人把 mention 归到其中一个身上。同名并列那条路上这正是 #270 禁的事:
    // 分不开就别硬分,谁也不归,两个都送审。
    weighed: &[Uuid],
) -> AppResult<(Uuid, bool)> {
    // 名字属性在锁外取:它自己有一次插入,放进锁里会让所有建实体的人排同一把队
    let known_as = crate::names::ensure_known_as(pool, kb_id).await?;
    let mut tx = pool.begin().await?;
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))")
        .bind(kb_id.to_string())
        .bind(name)
        .execute(&mut *tx)
        .await?;
    let existing: Option<(Uuid,)> = sqlx::query_as(
        // 被描述的东西不算「同名的它」(0044):它的 canonical_name 只是显示用的描述
        "SELECT id FROM entities
         WHERE kb_id = $1 AND canonical_name = $2 AND type_id IS NOT DISTINCT FROM $3
           AND merged_into IS NULL AND description IS NULL AND id <> ALL($4)
         ORDER BY id LIMIT 1",
    )
    .bind(kb_id)
    .bind(name)
    .bind(type_id)
    .bind(weighed)
    .fetch_optional(&mut *tx)
    .await?;
    if let Some((id,)) = existing {
        tx.commit().await?;
        return Ok((id, false));
    }
    let id = Uuid::now_v7();
    sqlx::query(
        "INSERT INTO entities (id, kb_id, type_id, canonical_name, profile_embedding, profile_n)
         VALUES ($1, $2, $3, $4, $5, $6)",
    )
    .bind(id)
    .bind(kb_id)
    .bind(type_id)
    .bind(name)
    .bind(context.map(|c| Vector::from(c.to_vec())))
    .bind(i32::from(context.is_some()))
    .execute(&mut *tx)
    .await?;
    // 与实体同一个事务:召回按名字事实找它,建出来却查不到名字的那一瞬间不能有。
    // 出处(哪一块、哪句话)由抽取随后给这条事实补证据
    sqlx::query(
        "INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_value)
         VALUES ($1, $2, $3, $4, jsonb_build_object('value', $5::text))",
    )
    .bind(Uuid::now_v7())
    .bind(kb_id)
    .bind(id)
    .bind(known_as)
    .bind(name)
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    Ok((id, true))
}

/// 一个被描述、没有名字的东西(0044 第一刀,#729):"the buyer's parent company"、
/// 「那家上海的子公司」。它是一个实体——陈述要指着它——但它没有名字。
///
/// `canonical_name` 写成描述本身,**只为显示**;`description` 是它真正的身份。
/// **不写 `known_as`**:名字事实是召回的桥(0041),一段描述做桥会把两篇文档里
/// 碰巧描述得一样的两个东西接到一起。没有名字就没有桥,后来的提及找不到它——
/// 这是对的:一段描述指的是谁,要靠对齐(第二刀)而不是靠字面相同。
///
/// `kind_word` 是文档自己的类别词("company"、「子公司」),落在 `specific_type`
/// 上;`type_id` 留空,`type_source` 走缺省的 extracted。
///
/// 朴素插入:不加锁、不找候选、不去重——同一篇文档里同一段描述由调用方并成一个。
/// 两篇文档各描述一次,就是两个实体,等对齐来判它们是不是一个
pub async fn create_described(
    pool: &PgPool,
    kb_id: Uuid,
    description: &str,
    kind_word: Option<&str>,
) -> AppResult<Uuid> {
    let description = description.trim();
    if description.is_empty() {
        return Err(AppError::invalid(
            "description_missing",
            "a described thing needs the document's description",
        ));
    }
    let id = Uuid::now_v7();
    sqlx::query(
        "INSERT INTO entities (id, kb_id, type_id, canonical_name, description, specific_type)
         VALUES ($1, $2, NULL, $3, $3, left($4, 80))",
    )
    .bind(id)
    .bind(kb_id)
    .bind(description)
    .bind(kind_word.map(str::trim).filter(|k| !k.is_empty()))
    .execute(pool)
    .await?;
    Ok(id)
}

async fn touch_entity(pool: &PgPool, id: Uuid) -> AppResult<()> {
    sqlx::query("UPDATE entities SET updated_at = now() WHERE id = $1")
        .bind(id)
        .execute(pool)
        .await?;
    Ok(())
}

/// 画像增量质心:profile ← (profile·n + ctx) / (n+1)。
/// 维度不匹配(换过 embedding 模型)时用新向量重置画像。
async fn update_profile(pool: &PgPool, id: Uuid, n: i32, ctx: &[f32]) -> AppResult<()> {
    let existing: Option<(Option<Vector>,)> =
        sqlx::query_as("SELECT profile_embedding FROM entities WHERE id = $1")
            .bind(id)
            .fetch_optional(pool)
            .await?;
    let old = existing.and_then(|(v,)| v);
    let (new_vec, new_n) = match old {
        Some(p) if p.as_slice().len() == ctx.len() && n > 0 => {
            let nf = n as f32;
            let merged: Vec<f32> = p
                .as_slice()
                .iter()
                .zip(ctx)
                .map(|(a, b)| (a * nf + b) / (nf + 1.0))
                .collect();
            (merged, n + 1)
        }
        _ => (ctx.to_vec(), 1),
    };
    let dims = new_vec.len();
    sqlx::query(
        "UPDATE entities SET profile_embedding = $2, profile_n = $3, updated_at = now()
         WHERE id = $1",
    )
    .bind(id)
    .bind(Vector::from(new_vec))
    .bind(new_n)
    .execute(pool)
    .await?;
    // 画像表也要索引(0035 / #514):类型消解按主语逐个扫它。在了的话这一句是一次查找
    crate::vector_index::request(pool, crate::vector_index::Target::EntityProfiles, dims).await?;
    Ok(())
}

/// 同名组展示消歧:组内 ≥2 个存活实体时,各自取最能把自己和同名者分开的那条
/// 事实的宾语名,否则退回类型标签;组内唯一则清空。
///
/// **不认谓词的名字**(#299)。原先这里写死 works_at / part_of / located_in / leads
/// 四个 key,而 schema.org 包建出来的库用的是 works_for / member_of / affiliation
/// ——于是两个明明分得清清楚楚的 John Smith(一个在 Acme Robotics,一个在
/// St Mary's Hospital)双双退回类型标签,并排显示成两个 "John Smith · Person"。
/// 一张手写的词表管不住别人的词汇表,这与 #193 那条「封闭动词表换个语料就漏」
/// 是同一个毛病。
///
/// 换成按**这条事实分不分得开**排序,理由都来自本体自己的声明:
///
/// 1. **宾语在同名组里独一份**——后缀存在的全部意义就是这个。两个人都在 Acme
///    时它谁也分不开,那就退到下面几条按信息量取,而不是编一个假的区分
/// 2. **谓词声明过值域**(`relation_type_ranges`)——有人特意说过这条关系指向什么,
///    比抽取顺手长出来的那些更可能是身份性的
/// 3. **状态而非事件**(`temporal`):「在哪儿工作」是身份,「某天开了个会」不是
/// 4. **单值关系**(`functional`):一个主语只能有一个值的关系,本身就是身份锚
///
/// 没有谓词的事实(`predicate_id IS NULL`,0010)不参与:原话留在证据里,
/// 不是本体承认的说法,不该被当成一个人的身份写进后缀。
/// 库里有没有叫这个名字的实体,**不问类型**、并掉的不算。
///
/// 抽取用它判断一个没声明的主宾是不是已知的东西(#559):模型偶尔漏报一个实体
/// 却在事实里用了它,那时库里多半已经有它;库里也没有的,就不是漏报,是一个
/// 描述("lawsuit against OpenAI"),不该成节点。同名多个时取事实最多的那个——
/// 这里只回答「有没有」,谁是谁交给消解
pub async fn existing_by_name(
    pool: &PgPool,
    kb_id: Uuid,
    raw_name: &str,
) -> AppResult<Option<Uuid>> {
    let name = normalize_name(raw_name);
    let keys = recall_keys(&name);
    let id: Option<Uuid> = sqlx::query_scalar(&format!(
        "SELECT e.id FROM entities e
          WHERE e.kb_id = $1 AND e.merged_into IS NULL
            -- 被描述的东西不参与名字召回(0044):描述不是桥
            AND e.description IS NULL
            AND (lower(e.canonical_name) = ANY($2) OR {named})
          ORDER BY (SELECT count(*) FROM facts f
                     WHERE f.kb_id = e.kb_id AND (f.subject_id = e.id OR f.object_id = e.id) AND f.invalidated_at IS NULL AND {not_name}) DESC,
                   e.created_at
          LIMIT 1",
        named = crate::names::has_name_in("e", 1, 2),
        not_name = crate::names::not_a_name("f"),
    ))
    .bind(kb_id)
    .bind(&keys)
    .fetch_optional(pool)
    .await?;
    Ok(id)
}

pub async fn refresh_disambiguators(pool: &PgPool, kb_id: Uuid, name: &str) -> AppResult<()> {
    let group: Vec<(Uuid,)> = sqlx::query_as(
        "SELECT id FROM entities
         WHERE kb_id = $1 AND merged_into IS NULL AND lower(canonical_name) = lower($2)",
    )
    .bind(kb_id)
    .bind(name)
    .fetch_all(pool)
    .await?;

    if group.len() < 2 {
        for (id,) in &group {
            sqlx::query("UPDATE entities SET disambiguator = NULL WHERE id = $1")
                .bind(id)
                .execute(pool)
                .await?;
        }
        return Ok(());
    }

    let peers: Vec<Uuid> = group.iter().map(|(id,)| *id).collect();
    for (id,) in &group {
        // LEFT JOIN(0044):开放陈述指着的宾语也能当消歧后缀——「张三 · 星云科技」
        // 不因为「任职于」没进本体就写不出来。关系的布尔位对开放行 COALESCE 成 false,
        // 类型化行之间的次序不变
        let label: Option<(String,)> = sqlx::query_as(
            "SELECT o.canonical_name FROM facts f
             LEFT JOIN relation_types r ON r.id = f.predicate_id
             JOIN entities o ON o.id = f.object_id
             WHERE f.kb_id = $1 AND f.subject_id = $2
               AND f.invalidated_at IS NULL AND f.object_id IS NOT NULL
             ORDER BY
               -- 同名的另一个也指着它,这条就分不开谁是谁
               (NOT EXISTS (SELECT 1 FROM facts g
                             WHERE g.kb_id = $1 AND g.subject_id = ANY($3)
                               AND g.subject_id <> $2 AND g.object_id = f.object_id
                               AND g.invalidated_at IS NULL)) DESC,
               EXISTS (SELECT 1 FROM relation_type_ranges rr
                        WHERE rr.relation_type_id = r.id) DESC,
               COALESCE(r.temporal = 'state', FALSE) DESC,
               COALESCE(r.functional, FALSE) DESC,
               f.confidence DESC, f.recorded_at DESC
             LIMIT 1",
        )
        .bind(kb_id)
        .bind(id)
        .bind(&peers)
        .fetch_optional(pool)
        .await?;
        // 关联事实找不着就退到类型标签;**类型也可能没有**(0009),
        // 那就没有可写的后缀——留 NULL,界面按同名并列显示,别编一个出来
        let disambiguator: Option<String> = match label {
            Some((l,)) => Some(l),
            None => sqlx::query_as::<_, (String,)>(
                "SELECT t.label FROM entities e JOIN entity_types t ON t.id = e.type_id
                     WHERE e.id = $1",
            )
            .bind(id)
            .fetch_optional(pool)
            .await?
            .map(|(l,)| l),
        };
        sqlx::query("UPDATE entities SET disambiguator = $2 WHERE id = $1")
            .bind(id)
            .bind(disambiguator)
            .execute(pool)
            .await?;
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// 审核队列
// ---------------------------------------------------------------------------

/// 灰区疑似重复对入队(同一 pending 对幂等)。
pub async fn create_review(
    pool: &PgPool,
    kb_id: Uuid,
    left_id: Uuid,
    right_id: Uuid,
    score: f32,
    reason: &str,
    stage: ReviewStage,
) -> AppResult<()> {
    sqlx::query(
        "INSERT INTO resolution_reviews AS existing
             (id, kb_id, left_id, right_id, score, reason, stage)
         VALUES ($1, $2, $3, $4, $5, $6, $7)
         ON CONFLICT (kb_id, least(left_id, right_id), greatest(left_id, right_id))
             WHERE status = 'pending'
         DO UPDATE SET stage = 'human', reason = EXCLUDED.reason
           WHERE EXCLUDED.stage = 'human' AND existing.stage = 'adjudicating'",
    )
    .bind(Uuid::now_v7())
    .bind(kb_id)
    .bind(left_id)
    .bind(right_id)
    .bind(score)
    .bind(reason)
    .bind(stage.as_str())
    .execute(pool)
    .await?;
    Ok(())
}

#[derive(Debug, sqlx::FromRow)]
pub(crate) struct ReviewRow {
    id: Uuid,
    left_id: Uuid,
    right_id: Uuid,
    score: f32,
    reason: Option<String>,
    stage: String,
    created_at: DateTime<Utc>,
}

async fn review_sides(
    pool: &PgPool,
    kb_id: Uuid,
    entity_ids: &[Uuid],
) -> AppResult<HashMap<Uuid, ReviewSide>> {
    #[derive(sqlx::FromRow)]
    struct SideRow {
        id: Uuid,
        name: String,
        type_label: Option<String>,
        color: String,
        disambiguator: Option<String>,
        degree: i64,
    }
    let rows: Vec<SideRow> = sqlx::query_as(&format!(
        "SELECT e.id, e.canonical_name AS name, t.label AS type_label,
                coalesce(t.color, '#94a3b8') AS color, e.disambiguator,
                (SELECT count(*) FROM facts f
                 WHERE f.kb_id = e.kb_id AND (f.subject_id = e.id OR f.object_id = e.id)
                   AND f.invalidated_at IS NULL AND {not_name}) AS degree
         -- LEFT JOIN:没判出类型的实体照样要能进审核(0009)。
         -- 内连接会让它整条审核项取不出来,而漂移审核恰恰最常发生在它们身上
         FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
         WHERE e.kb_id = $1 AND e.id = ANY($2)",
        not_name = crate::names::not_a_name("f"),
    ))
    .bind(kb_id)
    .bind(entity_ids)
    .fetch_all(pool)
    .await?;
    let mut lines = entity_fact_lines_many(pool, kb_id, entity_ids, 4).await?;
    Ok(rows
        .into_iter()
        .map(|row| {
            (
                row.id,
                ReviewSide {
                    id: row.id,
                    name: row.name,
                    type_label: row.type_label,
                    color: row.color,
                    disambiguator: row.disambiguator,
                    degree: row.degree,
                    top_facts: lines.remove(&row.id).unwrap_or_default(),
                },
            )
        })
        .collect())
}

/// 实体的事实摘要行:"works at → 星云科技 (2023-01 → now)",裁决 prompt 与审核 UI 共用。
pub async fn entity_fact_lines(
    pool: &PgPool,
    kb_id: Uuid,
    entity_id: Uuid,
    limit: i64,
) -> AppResult<Vec<String>> {
    Ok(entity_fact_lines_many(pool, kb_id, &[entity_id], limit)
        .await?
        .remove(&entity_id)
        .unwrap_or_default())
}

/// The lateral limit applies to each entity, not to the whole page. Keep this
/// path shared with the single-entity reader used by adjudication.
async fn entity_fact_lines_many(
    pool: &PgPool,
    kb_id: Uuid,
    entity_ids: &[Uuid],
    limit: i64,
) -> AppResult<HashMap<Uuid, Vec<String>>> {
    if entity_ids.is_empty() {
        return Ok(HashMap::new());
    }
    #[derive(sqlx::FromRow)]
    struct Line {
        entity_id: Uuid,
        direction: String,
        predicate_label: String,
        other_name: Option<String>,
        valid_from: Option<DateTime<Utc>>,
        valid_to: Option<DateTime<Utc>>,
    }
    // 名字不算审阅卡上的一条事实(0041):两个同名实体各有一条「known as 张伟」,
    // 摆出来像是一条共同证据,其实它什么也分不出来。
    // 开放陈述(0044)按它照抄的短语读:`phrase` 在关系标签之后、证据众数之前——
    // 类型化行的 phrase 是 NULL,它们的显示一字不变
    let rows: Vec<Line> = sqlx::query_as(&format!(
        "SELECT requested.id AS entity_id, line.*
         FROM unnest($2::uuid[]) AS requested(id)
         CROSS JOIN LATERAL (
         SELECT CASE WHEN f.subject_id = requested.id THEN 'out' ELSE 'in' END AS direction,
                COALESCE(r.label, f.phrase, fact_surface_predicate(f.id)) AS predicate_label,
                -- 字面值的事实没有对端实体:值本身就是这一行要说的(职位、工号),不能读成「?」
                COALESCE(o.canonical_name, left(f.object_value->>'value', 120)) AS other_name,
                f.valid_from, f.valid_to, f.confidence, f.recorded_at
         FROM facts f
         LEFT JOIN relation_types r ON r.id = f.predicate_id
         LEFT JOIN entities o
           ON o.id = CASE WHEN f.subject_id = requested.id THEN f.object_id ELSE f.subject_id END
         WHERE f.kb_id = $1 AND f.invalidated_at IS NULL
           AND (f.subject_id = requested.id OR f.object_id = requested.id)
           AND COALESCE(r.label, f.phrase, fact_surface_predicate(f.id)) IS NOT NULL
           AND {not_name}
         ORDER BY f.confidence DESC, f.recorded_at DESC
         LIMIT $3
         ) line
         ORDER BY requested.id, line.confidence DESC, line.recorded_at DESC",
        not_name = crate::names::not_a_name("f"),
    ))
    .bind(kb_id)
    .bind(entity_ids)
    .bind(limit)
    .fetch_all(pool)
    .await?;

    // 本名以外的名字单独打头一行(0041):「海洋探测器1号」对「海探1」,裁决器要看得见
    // 前者也叫海探1,否则两边的事实各说各的,它只会判「不是同一个」。本名不列——
    // 两个张伟各有一条「known as 张伟」,摆出来像共同证据,其实什么也分不出
    let names = crate::names::other_names_many(pool, entity_ids).await?;
    let mut lines: HashMap<Uuid, Vec<String>> = names
        .into_iter()
        .map(|(id, names)| (id, vec![format!("also known as: {}", names.join(", "))]))
        .collect();
    for l in rows {
        let other = l.other_name.unwrap_or_else(|| "?".into());
        let core = if l.direction == "out" {
            format!("{} → {}", l.predicate_label, other)
        } else {
            format!("{} ← {}", l.predicate_label, other)
        };
        let text = match (l.valid_from, l.valid_to) {
            (Some(f), Some(t)) => {
                format!("{core} ({} → {})", f.format("%Y-%m"), t.format("%Y-%m"))
            }
            (Some(f), None) => format!("{core} ({} → now)", f.format("%Y-%m")),
            _ => core,
        };
        lines.entry(l.entity_id).or_default().push(text);
    }
    Ok(lines)
}

pub(crate) async fn assemble_reviews(
    pool: &PgPool,
    kb_id: Uuid,
    rows: Vec<ReviewRow>,
) -> AppResult<Vec<ReviewItem>> {
    if rows.is_empty() {
        return Ok(Vec::new());
    }
    // An entity can occur on either side of several pairs. Read it once for
    // this page, then reuse its summary without changing the review order.
    let mut entity_ids: Vec<Uuid> = rows.iter().flat_map(|r| [r.left_id, r.right_id]).collect();
    entity_ids.sort_unstable();
    entity_ids.dedup();
    let sides = review_sides(pool, kb_id, &entity_ids).await?;
    // 这一页上开着的建议(0025):一趟查完,按审核行挂上去
    let ids: Vec<Uuid> = rows.iter().map(|r| r.id).collect();
    let proposals: HashMap<Uuid, utopia_core::models::ReviewProposal> =
        sqlx::query_as::<_, (Uuid, Uuid, String, f32, Option<String>)>(
            "SELECT target_id, id, action, confidence, reason FROM agent_decisions
         WHERE target_kind = 'review' AND target_id = ANY($1) AND status = 'proposed'",
        )
        .bind(&ids)
        .fetch_all(pool)
        .await?
        .into_iter()
        .map(|(target, id, action, confidence, reason)| {
            (
                target,
                utopia_core::models::ReviewProposal {
                    id,
                    action,
                    confidence,
                    reason,
                },
            )
        })
        .collect();
    let mut items = Vec::with_capacity(rows.len());
    for r in rows {
        let proposal = proposals.get(&r.id).cloned();
        items.push(ReviewItem {
            id: r.id,
            score: r.score,
            reason: r.reason,
            stage: r.stage,
            created_at: r.created_at,
            left: sides.get(&r.left_id).cloned().ok_or(AppError::NotFound)?,
            right: sides.get(&r.right_id).cloned().ok_or(AppError::NotFound)?,
            proposal,
        });
    }
    Ok(items)
}

/// 重复项按两边类型的关系分三档(#428)。**没类型的一侧哪档都不进**:不知道的
/// 既不能当成一样,也不能当成不一样。`clause()` 是 SQL 片段,别名固定 a / b
/// (左右两个实体),列表与 `review::counts` 共用,两处口径不会分叉。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TypeFilter {
    Any,
    /// 两边都有类型且相等——同名同类,人最先想批量合的那一档
    Same,
    /// 两边都有类型且不等——同名异义,合了就错
    Conflict,
}

impl TypeFilter {
    /// 查询串里的写法:缺省 any;认不出的当契约错误报出来
    pub fn parse(s: Option<&str>) -> AppResult<Self> {
        match s.unwrap_or("any") {
            "any" => Ok(Self::Any),
            "same" => Ok(Self::Same),
            "conflict" => Ok(Self::Conflict),
            other => Err(AppError::invalid(
                "unknown_type_filter",
                format!("types must be any, same or conflict, not {other}"),
            )),
        }
    }

    pub fn clause(self) -> &'static str {
        match self {
            Self::Any => "TRUE",
            Self::Same => "a.type_id IS NOT NULL AND a.type_id = b.type_id",
            Self::Conflict => {
                "a.type_id IS NOT NULL AND b.type_id IS NOT NULL AND a.type_id <> b.type_id"
            }
        }
    }
}

/// 全部待处理审核项(LLM 裁决中 + 等人工的都展示,人工可随时抢先定夺)。
pub async fn list_reviews(
    pool: &PgPool,
    kb_id: Uuid,
    types: TypeFilter,
    limit: i64,
    offset: i64,
) -> AppResult<Vec<ReviewItem>> {
    let sql = format!(
        "SELECT rr.id, rr.left_id, rr.right_id, rr.score, rr.reason, rr.stage, rr.created_at
         FROM resolution_reviews rr
         JOIN entities a ON a.id = rr.left_id
         JOIN entities b ON b.id = rr.right_id
         WHERE rr.kb_id = $1 AND rr.status = 'pending' AND {}
         ORDER BY rr.created_at DESC, rr.id DESC LIMIT $2 OFFSET $3",
        types.clause()
    );
    let rows: Vec<ReviewRow> = sqlx::query_as(&sql)
        .bind(kb_id)
        .bind(limit)
        .bind(offset)
        .fetch_all(pool)
        .await?;
    assemble_reviews(pool, kb_id, rows).await
}

/// 批量裁决 = 逐条的人工裁决(#428):每一条走 `decide_review`,合并方向、状态、
/// decided_by 与单条一模一样。一条失败(不存在、已经裁过、并到一半出错)不拖累
/// 其余的,结果逐条带回;动作不认识整批拒绝——那不是某一条的问题。
pub async fn decide_reviews(
    pool: &PgPool,
    kb_id: Uuid,
    ids: &[Uuid],
    action: &str,
    user_id: Uuid,
    rationale: Option<&str>,
) -> AppResult<Vec<ReviewBatchOutcome>> {
    if action != "merge" && action != "keep" {
        return Err(AppError::Validation("action must be merge or keep".into()));
    }
    let mut out = Vec::with_capacity(ids.len());
    for &id in ids {
        let error = decide_review(pool, kb_id, id, action, user_id, rationale)
            .await
            .err()
            .map(|e| e.to_string());
        out.push(ReviewBatchOutcome { id, error });
    }
    Ok(out)
}

/// 等待 LLM 裁决的审核项(后台裁决任务消费)。
pub async fn pending_adjudications(
    pool: &PgPool,
    kb_id: Uuid,
    limit: i64,
) -> AppResult<Vec<ReviewItem>> {
    let rows: Vec<ReviewRow> = sqlx::query_as(
        "SELECT id, left_id, right_id, score, reason, stage, created_at
         FROM resolution_reviews
         WHERE kb_id = $1 AND status = 'pending' AND stage = 'adjudicating'
         ORDER BY created_at LIMIT $2",
    )
    .bind(kb_id)
    .bind(limit)
    .fetch_all(pool)
    .await?;
    assemble_reviews(pool, kb_id, rows).await
}

/// LLM 不确定 / 未配模型 → 转人工。
/// `reason` 存的是 **code**,可选地跟 `|detail`——不是给人看的句子。
///
/// 界面语言在客户端(见 docs/decisions/0004),服务端没有 locale 可用来措辞;
/// 写进这一列的英文散文会永久留在中文界面上。措辞归 i18n,这里只留稳定的 code。
pub async fn escalate_review(pool: &PgPool, review_id: Uuid, reason: &str) -> AppResult<()> {
    sqlx::query(
        "UPDATE resolution_reviews SET stage = 'human', reason = $2
         WHERE id = $1 AND status = 'pending'",
    )
    .bind(review_id)
    .bind(reason)
    .execute(pool)
    .await?;
    Ok(())
}

/// 自动定夺(LLM 高置信):merged / kept。合并动作本身由调用方先执行。
/// 回关上了几行:0 = 这一对已经不是 pending(人裁了,或另一条路先到),调用方别再记一条一样的裁决
pub async fn close_review_auto(
    pool: &PgPool,
    review_id: Uuid,
    status: &str,
    reason: &str,
) -> AppResult<u64> {
    let res = sqlx::query(
        "UPDATE resolution_reviews SET status = $2, reason = $3, decided_at = now()
         WHERE id = $1 AND status = 'pending'",
    )
    .bind(review_id)
    .bind(status)
    .bind(reason)
    .execute(pool)
    .await?;
    Ok(res.rows_affected())
}

/// 人工定夺。merge 方向:度数高(事实多)的一方作为存活目标,平局取更早创建的。
/// `rationale`:人拍板时写的那一句(0026)。**空着是允许的**——问的是「什么让你
/// 这么定」,不是一张必填的表;但只要写了,它就跟着这一行和台账一起留下,
/// 下一次裁决器和 agent 读先例时读到的就不只是结果。
pub async fn decide_review(
    pool: &PgPool,
    kb_id: Uuid,
    review_id: Uuid,
    action: &str,
    user_id: Uuid,
    rationale: Option<&str>,
) -> AppResult<()> {
    let rationale = rationale.map(str::trim).filter(|s| !s.is_empty());
    let row: Option<ReviewRow> = sqlx::query_as(
        "SELECT id, left_id, right_id, score, reason, stage, created_at
         FROM resolution_reviews WHERE id = $1 AND kb_id = $2 AND status = 'pending'",
    )
    .bind(review_id)
    .bind(kb_id)
    .fetch_optional(pool)
    .await?;
    let row = row.ok_or(AppError::NotFound)?;
    // agent 正在裁的一对(0025):等它的建议,或者关掉开关
    if crate::governance::locked_by_agent(pool, kb_id, review_id).await? {
        return Err(AppError::Conflict(
            "The agent is deciding this pair right now; wait for its proposal or turn governance off."
                .into(),
        ));
    }

    match action {
        "merge" => {
            // 同名连锁(A-B 合了,B-C 还等着):B 已并进 A,这一对实际上是 A-C。
            // 跟着 merged_into 走到活着的那个再合;两边走到同一个,就只剩把审核行关上
            let (l, r) = (
                survivor(pool, kb_id, row.left_id).await?,
                survivor(pool, kb_id, row.right_id).await?,
            );
            if l != r {
                let (target, source) = merge_direction(pool, l, r).await?;
                // 合并日志的 reason 也记这一句:Review › Merges 那一列读的是它
                merge_entities(
                    pool,
                    kb_id,
                    source,
                    target,
                    Some(user_id),
                    rationale.unwrap_or("review decision"),
                )
                .await?;
            }
            sqlx::query(
                "UPDATE resolution_reviews
                 SET status = 'merged', decided_at = now(), decided_by = $2, rationale = $3
                 WHERE id = $1",
            )
            .bind(review_id)
            .bind(user_id)
            .bind(rationale)
            .execute(pool)
            .await?;
        }
        "keep" => {
            sqlx::query(
                "UPDATE resolution_reviews
                 SET status = 'kept', decided_at = now(), decided_by = $2, rationale = $3
                 WHERE id = $1",
            )
            .bind(review_id)
            .bind(user_id)
            .bind(rationale)
            .execute(pool)
            .await?;
        }
        _ => return Err(AppError::Validation("action must be merge or keep".into())),
    }
    Ok(())
}

/// 跟着 `merged_into` 走到还活着的那个实体。同簇连锁合并之后,一对里的一侧可能已经
/// 并进了别人;合并要合的是活着的那个,不是那条已经空了的行
pub async fn survivor(pool: &PgPool, kb_id: Uuid, mut id: Uuid) -> AppResult<Uuid> {
    for _ in 0..16 {
        let next: Option<Option<Uuid>> =
            sqlx::query_scalar("SELECT merged_into FROM entities WHERE id = $1 AND kb_id = $2")
                .bind(id)
                .bind(kb_id)
                .fetch_optional(pool)
                .await?;
        match next {
            Some(Some(n)) => id = n,
            Some(None) => return Ok(id),
            None => return Err(AppError::NotFound),
        }
    }
    Err(AppError::Conflict("merge chain too long".into()))
}

/// 合并方向:返回 (target 存活, source 被并)。
pub async fn merge_direction(pool: &PgPool, a: Uuid, b: Uuid) -> AppResult<(Uuid, Uuid)> {
    // 事实索引以 kb_id 开头;先用标量子查询取库,让 OR 两侧都能按复合索引定位。
    // PG16 上直接 JOIN 可能只按 kb_id 扫描整个库,再过滤 subject/object。
    let (deg_a,): (i64,) = sqlx::query_as(
        "SELECT count(*) FROM facts
         WHERE kb_id = (SELECT kb_id FROM entities WHERE id = $1)
           AND (subject_id = $1 OR object_id = $1) AND invalidated_at IS NULL",
    )
    .bind(a)
    .fetch_one(pool)
    .await?;
    let (deg_b,): (i64,) = sqlx::query_as(
        "SELECT count(*) FROM facts
         WHERE kb_id = (SELECT kb_id FROM entities WHERE id = $1)
           AND (subject_id = $1 OR object_id = $1) AND invalidated_at IS NULL",
    )
    .bind(b)
    .fetch_one(pool)
    .await?;
    // uuidv7 时间有序:度数平局时更早创建的一方存活
    Ok(if deg_a > deg_b || (deg_a == deg_b && a < b) {
        (a, b)
    } else {
        (b, a)
    })
}

// ---------------------------------------------------------------------------
// 合并 / 回滚
// ---------------------------------------------------------------------------

#[derive(Debug, sqlx::FromRow)]
struct EntityFull {
    // None = 还没判出来(0009)
    type_id: Option<Uuid>,
    canonical_name: String,
    profile_embedding: Option<Vector>,
    profile_n: i32,
    merged_into: Option<Uuid>,
}

async fn entity_full(pool: &PgPool, kb_id: Uuid, id: Uuid) -> AppResult<EntityFull> {
    sqlx::query_as(
        "SELECT type_id, canonical_name, profile_embedding, profile_n, merged_into
         FROM entities WHERE kb_id = $1 AND id = $2",
    )
    .bind(kb_id)
    .bind(id)
    .fetch_optional(pool)
    .await?
    .ok_or(AppError::NotFound)
}

/// 合并 source → target:事实改挂 target、互指事实与合并后的重复事实作废、
/// 画像加权合并、source 标记 merged_into。全程记日志可回滚。
///
/// **名字不用特判**(0041):source 的名字是它身上的 `known_as` 事实,跟别的事实一起
/// 搬到 target、记进 `moved_subject_facts`;同名的那条按重复事实作废。撤回合并时一起搬回去
pub async fn merge_entities(
    pool: &PgPool,
    kb_id: Uuid,
    source_id: Uuid,
    target_id: Uuid,
    merged_by: Option<Uuid>,
    reason: &str,
) -> AppResult<Uuid> {
    if source_id == target_id {
        return Err(AppError::invalid(
            "self_merge",
            "Cannot merge an entity into itself",
        ));
    }
    let source = entity_full(pool, kb_id, source_id).await?;
    let target = entity_full(pool, kb_id, target_id).await?;
    if source.merged_into.is_some() || target.merged_into.is_some() {
        return Err(AppError::Conflict("Entity already merged".into()));
    }

    let mut tx = pool.begin().await?;

    // 搬动会牵连的时间线先按固定顺序锁上,再改任何一行(撤回合并同一个顺序,见 temporal
    // 模块头):不锁的话,合并与撤回、合并与落库对账会各拿一半行锁互相等
    let moving: Vec<Uuid> = sqlx::query_scalar(
        "SELECT id FROM facts WHERE kb_id = $1 AND (subject_id = $2 OR object_id = $2)",
    )
    .bind(kb_id)
    .bind(source_id)
    .fetch_all(&mut *tx)
    .await?;
    let timelines =
        crate::temporal::timelines_of(&mut *tx, kb_id, &moving, Some((&[source_id], target_id)))
            .await?;
    crate::temporal::lock_timelines(&mut tx, kb_id, &timelines).await?;

    // 互指事实(合并后变自环)→ 作废
    let cross: Vec<(Uuid,)> = sqlx::query_as(
        "UPDATE facts SET invalidated_at = now()
         WHERE kb_id = $1 AND invalidated_at IS NULL
           AND ((subject_id = $2 AND object_id = $3) OR (subject_id = $3 AND object_id = $2))
         RETURNING id",
    )
    .bind(kb_id)
    .bind(source_id)
    .bind(target_id)
    .fetch_all(&mut *tx)
    .await?;
    let mut invalidated: Vec<Uuid> = cross.into_iter().map(|(id,)| id).collect();

    let moved_subject: Vec<Uuid> = sqlx::query_as::<_, (Uuid,)>(
        "UPDATE facts SET subject_id = $2 WHERE kb_id = $3 AND subject_id = $1 RETURNING id",
    )
    .bind(source_id)
    .bind(target_id)
    .bind(kb_id)
    .fetch_all(&mut *tx)
    .await?
    .into_iter()
    .map(|(id,)| id)
    .collect();
    let moved_object: Vec<Uuid> = sqlx::query_as::<_, (Uuid,)>(
        "UPDATE facts SET object_id = $2 WHERE kb_id = $3 AND object_id = $1 RETURNING id",
    )
    .bind(source_id)
    .bind(target_id)
    .bind(kb_id)
    .fetch_all(&mut *tx)
    .await?
    .into_iter()
    .map(|(id,)| id)
    .collect();

    // 合并后 SPO+valid_from 重复的 live 事实:留最早 recorded_at 的一条,其余作废。
    // 没有谓词的行不参与:开放陈述的不同短语都带 NULL,不能因此当成同一句话。
    //
    // **宾语两侧都要分组。** 字面值事实的 object_id 全是 NULL,只按它分组就等于
    // 把同主同谓下的**所有值**当成同一条断言:一次合并之后,
    // (公司, 成立年份, 2015) 与 (公司, 注册资本, …) 之外,同谓词的多个值只活得下来
    // 最早记的那一个,其余无声消失,且没有 supersedes 可查。
    let dups: Vec<(Vec<Uuid>,)> = sqlx::query_as(
        "SELECT array_agg(id ORDER BY recorded_at, id) FROM facts
         WHERE kb_id = $1 AND invalidated_at IS NULL AND predicate_id IS NOT NULL
           AND (subject_id = $2 OR object_id = $2)
         GROUP BY subject_id, predicate_id, object_id, object_value, valid_from
         HAVING count(*) > 1",
    )
    .bind(kb_id)
    .bind(target_id)
    .fetch_all(&mut *tx)
    .await?;
    let mut dup_ids = Vec::new();
    for (ids,) in dups {
        // 先给存活行接上来源,否则下一次物化可能作废它,再按原文重建,丢掉人的修正。
        // 旧行的链接暂留:撤回合并还用得上;物化按它原有的规则清理失效链接。
        sqlx::query(
            "INSERT INTO typed_fact_sources (fact_id, statement_id)
             SELECT $1, statement_id FROM typed_fact_sources WHERE fact_id = ANY($2)
             ON CONFLICT DO NOTHING",
        )
        .bind(ids[0])
        .bind(&ids[1..])
        .execute(&mut *tx)
        .await?;
        dup_ids.extend_from_slice(&ids[1..]);
    }
    if !dup_ids.is_empty() {
        sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = ANY($1)")
            .bind(&dup_ids)
            .execute(&mut *tx)
            .await?;
        invalidated.extend(dup_ids);
    }

    // 画像加权合并
    let (profile, profile_n) = match (&target.profile_embedding, &source.profile_embedding) {
        (Some(t), Some(s)) if t.as_slice().len() == s.as_slice().len() => {
            let (nt, ns) = (
                target.profile_n.max(1) as f32,
                source.profile_n.max(1) as f32,
            );
            let merged: Vec<f32> = t
                .as_slice()
                .iter()
                .zip(s.as_slice())
                .map(|(a, b)| (a * nt + b * ns) / (nt + ns))
                .collect();
            (
                Some(Vector::from(merged)),
                target.profile_n + source.profile_n,
            )
        }
        (Some(t), _) => (Some(t.clone()), target.profile_n),
        (None, Some(s)) => (Some(s.clone()), source.profile_n),
        (None, None) => (None, 0),
    };

    // 类型调和:**没有类型的一侧让位**。存活方还没判出来而被并方判出来了,
    // 就把那个类型带过来;否则保留存活方的。
    //
    // 从前这里要先查库找出 concept 那行的 id 再跟两侧比对。「还没判出来」
    // 现在是 `None`(0009),一个 `or` 就说完了,那次查询也省了
    let new_type_id = target.type_id.or(source.type_id);

    sqlx::query(
        "UPDATE entities SET profile_embedding = $2, profile_n = $3,
                type_id = $4, updated_at = now() WHERE id = $1",
    )
    .bind(target_id)
    .bind(&profile)
    .bind(profile_n)
    .bind(new_type_id)
    .execute(&mut *tx)
    .await?;
    sqlx::query("UPDATE entities SET merged_into = $2, updated_at = now() WHERE id = $1")
        .bind(source_id)
        .bind(target_id)
        .execute(&mut *tx)
        .await?;

    // 其余涉及 source 的 pending 审核项:**改指到合并目标,不是关掉**。
    //
    // 这里原本一律关掉,理由写的是"疑点若仍在会由后续 mention 重新提起"。
    // **那句是错的**:包含关系召回只在**新建实体时**跑一次,而这些实体早就存在了,
    // 不会再被新建,也就没有"后续 mention"来重提。关掉就是永远关掉。
    //
    // 实测:`Mr. Holmes` 跟 `Holmes` 配对入队(0.70),随后 `Holmes` 并入
    // `Sherlock Holmes`,这一对被关成 superseded by merge——而
    // `Mr. Holmes` vs `Sherlock Holmes` 这个仍然成立的问题,再没人问过。
    //
    // 先关掉两类真正过时的:重定向后会变成自环的,和目标对已经在队列里的。
    sqlx::query(
        "UPDATE resolution_reviews AS r
         SET status = 'kept', reason = 'superseded by merge', decided_at = now()
         WHERE r.kb_id = $1 AND r.status = 'pending'
           AND (r.left_id = $2 OR r.right_id = $2)
           AND NOT (least(r.left_id, r.right_id) = least($2, $3)
                    AND greatest(r.left_id, r.right_id) = greatest($2, $3))
           AND (
             (CASE WHEN r.left_id = $2 THEN r.right_id ELSE r.left_id END) = $3
             OR EXISTS (
               SELECT 1 FROM resolution_reviews d
               WHERE d.kb_id = $1 AND d.status = 'pending' AND d.id <> r.id
                 AND least(d.left_id, d.right_id)
                     = least($3, CASE WHEN r.left_id = $2 THEN r.right_id ELSE r.left_id END)
                 AND greatest(d.left_id, d.right_id)
                     = greatest($3, CASE WHEN r.left_id = $2 THEN r.right_id ELSE r.left_id END))
           )",
    )
    .bind(kb_id)
    .bind(source_id)
    .bind(target_id)
    .execute(&mut *tx)
    .await?;
    // 剩下的改指到目标,问题继续挂在队列上等裁决。
    // (source, target) 这一对本身除外——它正是本次合并的裁决对象,由调用方标记 merged,
    // 在这里动它会让它在历史里错误地显示为"保持分开"
    sqlx::query(
        "UPDATE resolution_reviews
         SET left_id = CASE WHEN left_id = $2 THEN $3 ELSE left_id END,
             right_id = CASE WHEN right_id = $2 THEN $3 ELSE right_id END,
             reason = reason || '|redirected'
         WHERE kb_id = $1 AND status = 'pending' AND (left_id = $2 OR right_id = $2)
           AND NOT (least(left_id, right_id) = least($2, $3)
                    AND greatest(left_id, right_id) = greatest($2, $3))",
    )
    .bind(kb_id)
    .bind(source_id)
    .bind(target_id)
    .execute(&mut *tx)
    .await?;

    let merge_id = Uuid::now_v7();
    sqlx::query(
        "INSERT INTO entity_merges (id, kb_id, source_id, target_id,
                moved_subject_facts, moved_object_facts, invalidated_facts,
                target_profile_before, target_profile_n_before, target_type_before,
                merged_by, reason)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)",
    )
    .bind(merge_id)
    .bind(kb_id)
    .bind(source_id)
    .bind(target_id)
    .bind(&moved_subject)
    .bind(&moved_object)
    .bind(&invalidated)
    .bind(&target.profile_embedding)
    .bind(target.profile_n)
    .bind(target.type_id)
    .bind(merged_by)
    .bind(reason)
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;

    // 搬移后的时态对账:换了主/宾的事实等价于新观察落库——两个对象折成一个后,
    // 唯一性不变量才第一次看得到旧开放区间与继任者相撞(如"星尘"并入"星尘项目",
    // 旧负责人的 leads 应在新任起点闭合)。
    // 修正行 id 记入合并账本,供审计。回滚不靠它:回滚按搬走之后剩下的行重算时间线,
    // 这些引擎画的终点自然跟着变(0057)。
    // 注:本步在事务外,失败有自愈性——这条时间线下一次有事实落库时整条重算。
    let moved_all: Vec<Uuid> = moved_subject
        .iter()
        .chain(moved_object.iter())
        .copied()
        .collect();

    // **合并是第三条改写事实的路**(#196):换掉主语或宾语,就可能把一条合法事实
    // 变成签名违规——抽取写入时掰正过的方向,合并一次就能再反回去。这里不掰、不改,
    // 只报:对搬动过的事实查一遍 domain / range,违反的进 `axiom_violations`
    //(kind = signature),与其它公理违规同一个队列、同样三个出路。
    // 放在事务之后:目标实体的类型在事务里刚调和过,提交了才看得见
    match crate::reasoning::signature_breaks(&mut *pool.acquire().await?, kb_id, Some(&moved_all))
        .await
    {
        Ok(broken) if !broken.is_empty() => {
            if let Err(e) = crate::reasoning::record_signature_breaks(pool, kb_id, &broken).await {
                tracing::warn!(%kb_id, error = %e, "合并后的签名违规没能入库");
            }
        }
        Ok(_) => {}
        Err(e) => tracing::warn!(%kb_id, error = %e, "合并后的签名检查失败"),
    }
    let report = crate::temporal::reconcile_moved_facts(pool, kb_id, &moved_all).await?;
    if !report.corrected.is_empty() {
        sqlx::query("UPDATE entity_merges SET temporal_corrections = $2 WHERE id = $1")
            .bind(merge_id)
            .bind(&report.corrected)
            .execute(pool)
            .await?;
    }

    refresh_disambiguators(pool, kb_id, &source.canonical_name).await?;
    if !source
        .canonical_name
        .eq_ignore_ascii_case(&target.canonical_name)
    {
        refresh_disambiguators(pool, kb_id, &target.canonical_name).await?;
    }
    Ok(merge_id)
}

#[derive(Debug, sqlx::FromRow)]
struct MergeRow {
    source_id: Uuid,
    target_id: Uuid,
    moved_subject_facts: Vec<Uuid>,
    moved_object_facts: Vec<Uuid>,
    invalidated_facts: Vec<Uuid>,
    target_profile_before: Option<Vector>,
    target_profile_n_before: i32,
    target_type_before: Option<Uuid>,
    reverted_at: Option<DateTime<Utc>>,
}

/// 搬过的事实,连同从它们改写出来的每一行(顺着 supersedes 往下走到底,作废的也算)
async fn with_rewrites(
    tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
    roots: &[Uuid],
) -> AppResult<Vec<Uuid>> {
    Ok(sqlx::query_scalar(
        "WITH RECURSIVE chain(id) AS (
             SELECT unnest($1::uuid[])
             UNION
             SELECT f.id FROM facts f JOIN chain c ON f.supersedes = c.id
         )
         SELECT id FROM chain",
    )
    .bind(roots)
    .fetch_all(&mut **tx)
    .await?)
}

/// 精确回滚一次合并:事实原路搬回、作废撤销、target 画像与类型恢复快照、source 复活。
///
/// **搬回去的是搬过来的事实连同从它们改写出来的每一行。** 合并之后引擎把它关上过、人改过
/// 它的区间、人驳回过它——那些行都是它的,跟着回源实体,各自保持原样:人改的区间还在,
/// 驳回的仍是驳回的。合并当时引擎做的闭合不单独撤:两边的时间线在搬完之后按剩下的行重算,
/// 边界随搬走的行走了,关在那里的行自然重新打开,写明的终点不动(0057)。
///
/// 怎么搬分两种,为的是记录轴回放合并窗口时仍答得对(0027 的 `fact_owner_at` 只认账本):
/// 账本上的行原地改回主语/宾语;合并之后才改写出来的行不在账本上,活着的作废、在源实体上
/// 另起一行接着它,作废了的留在目标实体上——它们在那段窗口里确实挂在那里
///
/// 搬动之前先按固定顺序拿下两边所有牵连时间线的锁(见 temporal 模块头):落库对账先拿锁
/// 再锁行,这里要是先改行再拿锁,两边会互相等死
pub async fn revert_merge(pool: &PgPool, kb_id: Uuid, merge_id: Uuid) -> AppResult<()> {
    let m: MergeRow = sqlx::query_as(
        "SELECT source_id, target_id, moved_subject_facts, moved_object_facts,
                invalidated_facts, target_profile_before,
                target_profile_n_before, target_type_before, reverted_at
         FROM entity_merges WHERE id = $1 AND kb_id = $2",
    )
    .bind(merge_id)
    .bind(kb_id)
    .fetch_optional(pool)
    .await?
    .ok_or(AppError::NotFound)?;
    if m.reverted_at.is_some() {
        return Err(AppError::Conflict("Merge already reverted".into()));
    }

    let mut tx = pool.begin().await?;
    // 事实此刻挂在谁身上:目标实体,或者目标后来又并进去的实体(S 并进 T、T 再并进 C,
    // 撤回 S→T 时 S 的事实在 C 身上)。只认目标的话,连环合并里撤回头一环,源实体
    // 复活了、它的事实却留在链尾(#679 第四轮评审)
    let holders: Vec<Uuid> = sqlx::query_scalar(
        "WITH RECURSIVE chain(id) AS (
             SELECT $1::uuid
             UNION SELECT e.merged_into FROM entities e JOIN chain ON e.id = chain.id
              WHERE e.merged_into IS NOT NULL)
         SELECT id FROM chain",
    )
    .bind(m.target_id)
    .fetch_all(&mut *tx)
    .await?;
    let touched: Vec<Uuid> = with_rewrites(&mut tx, &m.moved_subject_facts)
        .await?
        .into_iter()
        .chain(with_rewrites(&mut tx, &m.moved_object_facts).await?)
        .chain(m.invalidated_facts.iter().copied())
        .collect();
    let timelines =
        crate::temporal::timelines_of(&mut *tx, kb_id, &touched, Some((&holders, m.source_id)))
            .await?;
    crate::temporal::lock_timelines(&mut tx, kb_id, &timelines).await?;
    // 锁上之后再走一遍:等锁的时候,引擎可能刚从它们改写出新的一行
    let subject_rows = with_rewrites(&mut tx, &m.moved_subject_facts).await?;
    let object_rows = with_rewrites(&mut tx, &m.moved_object_facts).await?;

    sqlx::query("UPDATE facts SET subject_id = $1 WHERE id = ANY($2) AND subject_id = ANY($3)")
        .bind(m.source_id)
        .bind(&m.moved_subject_facts)
        .bind(&holders)
        .execute(&mut *tx)
        .await?;
    sqlx::query("UPDATE facts SET object_id = $1 WHERE id = ANY($2) AND object_id = ANY($3)")
        .bind(m.source_id)
        .bind(&m.moved_object_facts)
        .bind(&holders)
        .execute(&mut *tx)
        .await?;
    for (rows, ledger, on_object) in [
        (&subject_rows, &m.moved_subject_facts, false),
        (&object_rows, &m.moved_object_facts, true),
    ] {
        let holder = if on_object { "object_id" } else { "subject_id" };
        let live: Vec<Uuid> = sqlx::query_scalar(&format!(
            "SELECT id FROM facts
              WHERE id = ANY($1) AND id <> ALL($2) AND invalidated_at IS NULL AND {holder} = ANY($3)"
        ))
        .bind(rows)
        .bind(ledger)
        .bind(&holders)
        .fetch_all(&mut *tx)
        .await?;
        for id in live {
            let (subject, object) = if on_object {
                (None, Some(m.source_id))
            } else {
                (Some(m.source_id), None)
            };
            crate::temporal::rehome_tx(&mut tx, id, subject, object).await?;
        }
    }
    sqlx::query("UPDATE facts SET invalidated_at = NULL WHERE id = ANY($1)")
        .bind(&m.invalidated_facts)
        .execute(&mut *tx)
        .await?;
    crate::temporal::tidy_timelines_tx(&mut tx, kb_id, &timelines).await?;

    let source = entity_full(pool, kb_id, m.source_id).await?;
    // source 的名字是它的名字事实,已经跟着 moved_subject_facts 搬回去了
    sqlx::query(
        "UPDATE entities SET
            profile_embedding = $2, profile_n = $3,
            type_id = coalesce($4, type_id), updated_at = now()
         WHERE id = $1",
    )
    .bind(m.target_id)
    .bind(&m.target_profile_before)
    .bind(m.target_profile_n_before)
    .bind(m.target_type_before)
    .execute(&mut *tx)
    .await?;
    sqlx::query("UPDATE entities SET merged_into = NULL, updated_at = now() WHERE id = $1")
        .bind(m.source_id)
        .execute(&mut *tx)
        .await?;
    sqlx::query("UPDATE entity_merges SET reverted_at = now() WHERE id = $1")
        .bind(merge_id)
        .execute(&mut *tx)
        .await?;
    tx.commit().await?;

    refresh_disambiguators(pool, kb_id, &source.canonical_name).await?;
    Ok(())
}

/// 合并日志(审核页历史区)。
pub async fn list_merges(
    pool: &PgPool,
    kb_id: Uuid,
    limit: i64,
    offset: i64,
) -> AppResult<Vec<MergeLogView>> {
    let rows: Vec<MergeLogView> = sqlx::query_as(
        "SELECT m.id, s.canonical_name AS source_name, t.canonical_name AS target_name,
                u.display_name AS merged_by_name, m.reason, m.created_at, m.reverted_at
         FROM entity_merges m
         JOIN entities s ON s.id = m.source_id
         JOIN entities t ON t.id = m.target_id
         LEFT JOIN users u ON u.id = m.merged_by
         WHERE m.kb_id = $1
         ORDER BY m.created_at DESC, m.id DESC LIMIT $2 OFFSET $3",
    )
    .bind(kb_id)
    .bind(limit)
    .bind(offset)
    .fetch_all(pool)
    .await?;
    Ok(rows)
}

// ---------------------------------------------------------------------------
// LLM 裁决缓存
// ---------------------------------------------------------------------------

pub async fn get_verdict(
    pool: &PgPool,
    kb_id: Uuid,
    pair_key: &str,
) -> AppResult<Option<(Option<bool>, f32)>> {
    let row: Option<(Option<bool>, f32)> = sqlx::query_as(
        "SELECT same, confidence FROM resolution_verdicts WHERE kb_id = $1 AND pair_key = $2",
    )
    .bind(kb_id)
    .bind(pair_key)
    .fetch_optional(pool)
    .await?;
    Ok(row)
}

pub async fn put_verdict(
    pool: &PgPool,
    kb_id: Uuid,
    pair_key: &str,
    same: Option<bool>,
    confidence: f32,
    model: &str,
) -> AppResult<()> {
    sqlx::query(
        "INSERT INTO resolution_verdicts (kb_id, pair_key, same, confidence, model)
         VALUES ($1, $2, $3, $4, $5)
         ON CONFLICT (kb_id, pair_key)
         DO UPDATE SET same = $3, confidence = $4, model = $5, created_at = now()",
    )
    .bind(kb_id)
    .bind(pair_key)
    .bind(same)
    .bind(confidence)
    .bind(model)
    .execute(pool)
    .await?;
    Ok(())
}

/// 撤销一次实体改类:把它们放回原来的类型。
///
/// 类型本身不删——与谓词那边同一条理由:有实体指向过它,而"它存在过"是历史。
/// `proposed_type` 也一并恢复,否则撤销之后那些实体就再也认领不回来了。
pub async fn unadopt_types(pool: &PgPool, kb_id: Uuid, batch_id: Uuid) -> AppResult<u32> {
    // from_type_id 可能是 NULL:0009 之后最常见的一次改类正是"从没有类到有类",
    // 撤销就是把它推回没有类。解成 Uuid 会在这里当场崩
    let rows: Vec<(Uuid, Option<Uuid>, String)> = sqlx::query_as(
        "SELECT r.entity_id, r.from_type_id, t.key
         FROM entity_retypes r JOIN entity_types t ON t.id = r.to_type_id
         WHERE r.batch_id = $1 AND r.kb_id = $2 AND r.reverted_at IS NULL",
    )
    .bind(batch_id)
    .bind(kb_id)
    .fetch_all(pool)
    .await?;
    if rows.is_empty() {
        return Err(AppError::NotFound);
    }
    let mut names: Vec<String> = Vec::new();
    let mut tx = pool.begin().await?;
    let mut reverted = 0u32;
    for (entity_id, from_type, adopted_key) in &rows {
        let row: Option<(String,)> = sqlx::query_as(
            "UPDATE entities SET type_id = $2, proposed_type = $3, updated_at = now()
             WHERE id = $1 RETURNING canonical_name",
        )
        .bind(entity_id)
        .bind(from_type)
        .bind(adopted_key)
        .fetch_optional(&mut *tx)
        .await?;
        if let Some((name,)) = row {
            names.push(name);
        }
        reverted += 1;
    }
    sqlx::query(
        "UPDATE entity_retypes SET reverted_at = now()
         WHERE batch_id = $1 AND kb_id = $2 AND reverted_at IS NULL",
    )
    .bind(batch_id)
    .bind(kb_id)
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    for n in &names {
        refresh_disambiguators(pool, kb_id, n).await?;
    }
    Ok(reverted)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn like_escaped_turns_backslash_percent_and_underscore_into_literals() {
        assert_eq!(like_escaped(r"a\b%c_d"), r"a\\b\%c\_d");
    }

    #[test]
    fn normalize_fullwidth_and_whitespace() {
        assert_eq!(normalize_name(" ACME  Corp "), "ACME Corp");
        assert_eq!(normalize_name("张三"), "张三");
        assert_eq!(normalize_name("张  三"), "张 三");
    }

    #[test]
    fn markdown_folding_is_conservative() {
        for (raw, expected) in [
            ("**Pump 1**", "Pump 1"),
            ("__Pump 1__", "Pump 1"),
            ("__init__", "__init__"),
            ("`docs/setup.md`", "docs/setup.md"),
            ("`setup.md`", "setup.md"),
            ("`acme`", "`acme`"),
            ("`main()`", "`main()`"),
            ("`1.2`", "`1.2`"),
            ("**Pump 1*", "**Pump 1*"),
            ("***Pump 1***", "***Pump 1***"),
            ("** Pump 1 **", "** Pump 1 **"),
            ("****", "****"),
        ] {
            assert_eq!(fold_markdown_markers(raw), expected, "{raw:?}");
        }
    }

    #[test]
    fn recall_keys_fold_markdown_before_stemming_and_keep_exact_spelling() {
        let normalized = normalize_name(" **Phoenix  Project** ");
        let keys = recall_keys(&normalized);
        assert_eq!(keys[0], name_key(&normalized));
        for key in recall_keys("Phoenix Project") {
            assert!(keys.contains(&key), "must recall {key:?}");
        }
        assert!(keys.contains(&"**phoenix project**".to_string()));
        assert!(keys.len() <= 11);
    }

    #[test]
    fn stem_generic_suffixes() {
        assert_eq!(name_stem("星尘项目").as_deref(), Some("星尘"));
        assert_eq!(name_stem("星辰科技公司").as_deref(), Some("星辰科技"));
        assert_eq!(name_stem("Phoenix Project").as_deref(), Some("phoenix"));
        assert_eq!(name_stem("Project Phoenix").as_deref(), Some("phoenix"));
        assert_eq!(name_stem("Acme Inc.").as_deref(), Some("acme"));
        assert_eq!(name_stem("星尘"), None);
        assert_eq!(name_stem("项目"), None); // 剥空不算词干
        assert_eq!(name_stem("项目团队"), None); // 词干本身是泛用词
        assert_eq!(name_stem("Team Project"), None);
    }

    #[test]
    fn recall_keys_bidirectional() {
        // 无后缀 mention 能召回带后缀实体(增广),反之靠词干
        let k = recall_keys("星尘");
        assert!(k.contains(&"星尘".to_string()));
        assert!(k.contains(&"星尘项目".to_string()));
        let k = recall_keys("星尘项目");
        assert!(k.contains(&"星尘项目".to_string()));
        assert!(k.contains(&"星尘".to_string()));
        let k = recall_keys("Phoenix");
        assert!(k.contains(&"phoenix project".to_string()));
        assert!(k.contains(&"project phoenix".to_string()));
        let k = recall_keys("Project Phoenix");
        assert!(k.contains(&"phoenix".to_string()));
        assert!(recall_keys("张三").len() <= 10);
    }

    #[test]
    fn type_drift_classes() {
        // 还没判出类型的那一侧 → 召回候选。0009 之前这一档比的是 `concept`
        // 这个 key,现在比的是"有没有类"本身
        assert_eq!(
            classify_type_drift(None, Some("organization")),
            TypeDrift::Recall
        );
        assert_eq!(
            classify_type_drift(Some("project"), None),
            TypeDrift::Recall
        );
        // 两边都还没判出来:也归召回,由画像相似度说话
        assert_eq!(classify_type_drift(None, None), TypeDrift::Recall);
        // 易混具体类型两两 → 审核对
        assert_eq!(
            classify_type_drift(Some("organization"), Some("project")),
            TypeDrift::Review
        );
        assert_eq!(
            classify_type_drift(Some("project"), Some("product")),
            TypeDrift::Review
        );
        assert_eq!(
            classify_type_drift(Some("product"), Some("organization")),
            TypeDrift::Review
        );
        // 硬互斥与未知自定义类型 → 完全分开
        assert_eq!(
            classify_type_drift(Some("person"), Some("organization")),
            TypeDrift::Disjoint
        );
        assert_eq!(
            classify_type_drift(Some("person"), Some("project")),
            TypeDrift::Disjoint
        );
        assert_eq!(
            classify_type_drift(Some("event"), Some("location")),
            TypeDrift::Disjoint
        );
        assert_eq!(
            classify_type_drift(Some("team"), Some("organization")),
            TypeDrift::Disjoint
        );
    }

    #[test]
    fn cosine_basics() {
        assert!((cosine(&[1.0, 0.0], &[1.0, 0.0]).unwrap() - 1.0).abs() < 1e-6);
        assert!(cosine(&[1.0, 0.0], &[0.0, 1.0]).unwrap().abs() < 1e-6);
        assert!(cosine(&[1.0], &[1.0, 2.0]).is_none());
        assert!(cosine(&[0.0, 0.0], &[1.0, 1.0]).is_none());
    }
}

/// 一个等着精化类型的实体,连同用来判断它是什么的全部材料。
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct TypeCandidateSubject {
    pub id: Uuid,
    pub canonical_name: String,
    /// 本名以外的名字(名字事实,0041)。给模型看:「海探1」一个人判不出是什么,
    /// 连着「海洋探测器1号」就判得出
    pub other_names: Vec<String>,
    /// 现在挂着的类,**可能没有**(0009:没判出来就是 NULL)。名字里的"粗"
    /// 是历史——抽取现在也可能直接给一个细类,而且可能给错(实测
    /// `绍兴 → address`),所以这里也可能是要被**纠正**的那个
    pub coarse_key: Option<String>,
    pub coarse_id: Option<Uuid>,
    /// 现类的描述。裁决要判"现在这个类对不对",光看 key 不够——
    /// 导入本体的 key 常常自解释不了(`entry_point` 是什么?)
    pub coarse_description: Option<String>,
    /// 抽取时模型自己报的类型名,**词表里没有**才会留在这儿
    pub proposed_type: Option<String>,
    /// 模型对它自己的说法,每个实体都有。
    ///
    /// 这是最强的信号,因为它把任务从"读懂这是什么"换回"本体里哪个类叫这个"
    /// ——短名字对短标签。实测的失败正出在另一头:拿一段中文画像去匹配
    /// schema.org 的 "A software application.",两边形状根本不对等
    pub specific_type: Option<String>,
    /// 它参与的谓词,连着对方的名字(`produces 深蓝`、`leads by 张伟`)。
    /// **跨文档累积**,这正是抽取当场没有的东西
    pub roles: Vec<String>,
    /// 证据引文,最多几句。抽取看的是同一批句子,但那一次要同时做实体识别、
    /// 关系判断、时态解析、JSON 格式化,还要跟几十个别的实体抢注意力
    /// 证据引文,**只取它当主语的那些**。宾语位的引文讲的是主语:
    /// 「上海浦东新区」是 located_in 的宾语,引文却是"星云科技(上海)
    /// 有限公司是一家注册于上海浦东新区的股份有限公司",整句重心在
    /// "股份有限公司"上——实测那一版检索给出的候选全是 corporation 一类
    pub quotes: Vec<String>,
    pub fact_count: i64,
}

/// 值得送去精化类型的实体:**还没有类的**,或者模型报过一个词表外类型的。
///
/// 类型化得已经很具体的实体不动——重判一次只有下降风险,没有上升空间。
///
/// `unattended` = 自动跑(0016 C2):**跳过引擎已经看过的**(`type_resolved_at`)。候选按
/// 事实数排序、一轮六十个,不跳过的话每一轮都是同一批,后面的永远轮不到。人点的那条
/// 路传 false——人要的是把现状重新审一遍
pub async fn entities_for_type_resolution(
    pool: &PgPool,
    kb_id: Uuid,
    limit: i64,
    unattended: bool,
) -> AppResult<Vec<TypeCandidateSubject>> {
    Ok(sqlx::query_as(
        "SELECT e.id, e.canonical_name,
                ARRAY(SELECT DISTINCT nf.object_value->>'value' FROM facts nf
                        JOIN relation_types nr ON nr.id = nf.predicate_id
                       WHERE nf.subject_id = e.id AND nr.builtin AND nr.key = 'known_as'
                         AND nf.invalidated_at IS NULL
                         AND lower(nf.object_value->>'value') <> lower(e.canonical_name)) AS other_names,
                t.key AS coarse_key, t.id AS coarse_id,
                t.description AS coarse_description,
                e.proposed_type, e.specific_type,
                -- 对方写**名字**,不写它的类型 key。
                -- 写 key 是自毁:查询里出现 organization / product / event 这些词,
                -- 而检索的目标正是这些类自己,于是候选就是画像里那几个词。
                -- 实测「张伟」的画像是 leads→organization … works_at→organization,
                -- 回来的候选是 corporation、organization、business_entity_type——
                -- 检索到的是画像自己,不是这个人是什么
                ARRAY(
                  SELECT DISTINCT COALESCE(rt.key, fact_surface_predicate(f.id))
                                  || CASE WHEN f.subject_id = e.id THEN ' ' ELSE ' by ' END
                                  || coalesce(oe.canonical_name, 'a value')
                  FROM facts f
                  LEFT JOIN relation_types rt ON rt.id = f.predicate_id
                  LEFT JOIN entities oe ON oe.id = CASE WHEN f.subject_id = e.id
                                                       THEN f.object_id ELSE f.subject_id END
                  WHERE f.kb_id = $1 AND f.invalidated_at IS NULL
                    AND (f.subject_id = e.id OR f.object_id = e.id)
                    AND COALESCE(rt.key, fact_surface_predicate(f.id)) IS NOT NULL
                    -- 名字不是它扮演的角色,每个实体都有,判不出类型(0041)
                    AND NOT coalesce(rt.builtin AND rt.key = 'known_as', false)
                  LIMIT 12
                ) AS roles,
                ARRAY(
                  SELECT DISTINCT ev.quote FROM fact_evidence ev
                  JOIN facts f2 ON f2.id = ev.fact_id
                  LEFT JOIN relation_types rt2 ON rt2.id = f2.predicate_id
                  WHERE f2.kb_id = $1 AND f2.invalidated_at IS NULL
                    AND f2.subject_id = e.id
                    AND ev.quote IS NOT NULL
                    AND NOT coalesce(rt2.builtin AND rt2.key = 'known_as', false)
                  LIMIT 3
                ) AS quotes,
                (SELECT count(*) FROM facts f3
                 LEFT JOIN relation_types rt3 ON rt3.id = f3.predicate_id
                 WHERE f3.kb_id = $1 AND f3.invalidated_at IS NULL
                   AND (f3.subject_id = e.id OR f3.object_id = e.id)
                   AND NOT coalesce(rt3.builtin AND rt3.key = 'known_as', false)) AS fact_count
         FROM entities e
         LEFT JOIN entity_types t ON t.id = e.type_id
         WHERE e.kb_id = $1 AND e.merged_into IS NULL
           -- **人拍过板的不再重判。**
           --
           -- 少了这一行,下面第三种条件会把它们全都捞回来:一个人工定成
           -- organization 的实体,只要 organization 有子类就够格,于是引擎
           -- 每一轮都去重新裁决一遍人已经决定过的事,而账本事后才看得出是谁改的。
           --
           -- 「不落库」不等于「不许说话」:引擎若认为人定错了,该走 Review 队列,
           -- 而不是直接改掉。憋着不说和直接改掉都是失真,只是方向相反
           AND e.type_source <> 'human'
           -- 值得看的三种:**还没有类的**、模型报过词表外类型的、
           -- **以及现类本身还有子类的**。第三种是主力:抽取只认基类之后,
           -- organization 下面挂着一大批更具体的类,那才是导进来的本体
           -- 唯一的用武之地。只看前两种就把它整个漏掉了
           AND (e.type_id IS NULL OR e.proposed_type IS NOT NULL OR e.specific_type IS NOT NULL
                OR EXISTS (SELECT 1 FROM entity_type_parents p WHERE p.parent_id = t.id))
           AND (NOT $3::bool OR e.type_resolved_at IS NULL)
         ORDER BY fact_count DESC, e.created_at
         LIMIT $2",
    )
    .bind(kb_id)
    .bind(limit)
    .bind(unattended)
    .fetch_all(pool)
    .await?)
}

/// 引擎看过了:三档(改了 / 留给人 / 不动)都算看过,自动跑不再回头。
/// 人手工改类、合并之类的写路径不清这个标记——它们本来也不在自动跑的候选里
pub async fn mark_type_judged(pool: &PgPool, kb_id: Uuid, ids: &[Uuid]) -> AppResult<u64> {
    Ok(sqlx::query(
        "UPDATE entities SET type_resolved_at = now() WHERE kb_id = $1 AND id = ANY($2)",
    )
    .bind(kb_id)
    .bind(ids)
    .execute(pool)
    .await?
    .rows_affected())
}

/// 某个类的全部后代(含自身)。精化只能往粗类的后代走。
///
/// **递归而不是一层**:本体是 DAG,`software_application ⊂ creative_work ⊂ thing`,
/// 只查一层就把绝大多数正确答案挡在门外了。
pub async fn descendants_of(pool: &PgPool, kb_id: Uuid, root: Uuid) -> AppResult<Vec<Uuid>> {
    let rows: Vec<(Uuid,)> = sqlx::query_as(
        "WITH RECURSIVE d(id) AS (
             SELECT $2::uuid
             UNION
             SELECT p.child_id FROM entity_type_parents p JOIN d ON d.id = p.parent_id
         )
         SELECT d.id FROM d JOIN entity_types t ON t.id = d.id WHERE t.kb_id = $1",
    )
    .bind(kb_id)
    .bind(root)
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().map(|(id,)| id).collect())
}

/// 记下模型对这个实体自己的说法。
///
/// **后写者不覆盖先写者**(`IS NULL` 才写),与 `set_proposed_type` 同一条:
/// 同一个实体会被多个分块提到,第一次的说法通常出自最完整的那句话,
/// 后面的分块往往只是顺带一提。
pub async fn set_specific_type(pool: &PgPool, entity_id: Uuid, value: &str) -> AppResult<()> {
    sqlx::query(
        "UPDATE entities SET specific_type = left($2, 80)
         WHERE id = $1 AND specific_type IS NULL",
    )
    .bind(entity_id)
    .bind(value)
    .execute(pool)
    .await?;
    Ok(())
}

/// 跟这个实体最像的**已定类**实体,连同它们的类。
///
/// 类型消解的第二个候选来源。第一个是拿画像去搜类的描述,它的软肋实测很清楚:
/// 中文画像对 schema.org 的 "A software application.",两边形状根本不对等。
/// 这一条绕开了那道坎——**名字对名字、同语言**,而且库越大越准:
/// 「深蓝向量数据库」像「Milvus」,而 Milvus 已经标成 software_application。
///
/// 比的是双方的 `profile_embedding`(出现语境的滑动平均),**同一种向量对同一种
/// 向量**,不是拿文本画像去比语境向量。代价是零——这个向量实体消解本来就在维护。
///
/// 已知弱点:只出现在一篇文档里的实体,语境向量就是那一块的向量,同文档的实体
/// 会互相成为近邻。调用方要看得到 `same_document`,别把它当成类型证据。
/// 一批之内 [`descendants_of`] 的记忆(#514)。
///
/// 粗类来自抽取的小词表(person、organization、product 加几个),六十个主语里
/// 同一个 `coarse_id` 反复出现,同一个递归 CTE 就反复发。批内本体不动,同一输入
/// 同一结果,记住不改答案。**没有粗类的主语不进这张表**:它没有「后代」这个轴
/// (0009),整张类表都是候选;用 `Option` 当键会把它和某个真实的类混在一起
#[derive(Default)]
pub struct DescendantsMemo {
    sets: std::collections::HashMap<Uuid, HashSet<Uuid>>,
}

impl DescendantsMemo {
    pub async fn get(
        &mut self,
        pool: &PgPool,
        kb_id: Uuid,
        root: Option<Uuid>,
    ) -> AppResult<HashSet<Uuid>> {
        let Some(root) = root else {
            return Ok(HashSet::new());
        };
        if let Some(set) = self.sets.get(&root) {
            return Ok(set.clone());
        }
        let set: HashSet<Uuid> = descendants_of(pool, kb_id, root)
            .await?
            .into_iter()
            .collect();
        self.sets.insert(root, set.clone());
        Ok(set)
    }

    /// 记住了几个根
    pub fn len(&self) -> usize {
        self.sets.len()
    }

    pub fn is_empty(&self) -> bool {
        self.sets.is_empty()
    }
}

/// 一个主语的近邻:语境相似的已定类实体,连同「是否同一篇文档」。
///
/// 主语自己的向量先取出来再查:维度要写进 SQL(`vector_index` 规矩 1),SQL 里的
/// 子查询给不了这个数。没有向量的主语没有近邻,回空
pub async fn nearest_typed_entities(
    pool: &PgPool,
    kb_id: Uuid,
    entity_id: Uuid,
    limit: i64,
) -> AppResult<Vec<(String, Uuid, String, f64, bool)>> {
    let me: Option<(Option<Vector>,)> =
        sqlx::query_as("SELECT profile_embedding FROM entities WHERE id = $2 AND kb_id = $1")
            .bind(kb_id)
            .bind(entity_id)
            .fetch_optional(pool)
            .await?;
    let Some(query_vec) = me.and_then(|(v,)| v) else {
        return Ok(Vec::new());
    };
    let dims = query_vec.as_slice().len();
    let mut tx = pool.begin().await?;
    crate::vector_index::relaxed_order(pool, &mut tx).await?;
    let rows = sqlx::query_as(&format!(
        "WITH my_docs AS (
             SELECT DISTINCT ev.document_id FROM fact_evidence ev
             JOIN facts f ON f.id = ev.fact_id
             WHERE f.kb_id = $1 AND (f.subject_id = $2 OR f.object_id = $2)
         ),
         nearest AS MATERIALIZED (
             SELECT e.id, e.canonical_name, t.id AS type_id, t.key,
                    ({distance})::float8 AS distance,
                    EXISTS (SELECT 1 FROM fact_evidence ev2
                            JOIN facts f2 ON f2.id = ev2.fact_id
                            WHERE f2.kb_id = $1 AND (f2.subject_id = e.id OR f2.object_id = e.id)
                              AND ev2.document_id IN (SELECT document_id FROM my_docs))
                    AS same_document
             -- 内连接就是那道门:没判出类型的实体(type_id IS NULL)不是答案,
             -- 拿它当邻居的证据只会把「没判出来」传染开
             FROM entities e
             JOIN entity_types t ON t.id = e.type_id
             WHERE e.kb_id = $1 AND e.merged_into IS NULL AND e.id <> $2
               AND e.profile_embedding IS NOT NULL AND {same_dims}
             ORDER BY {distance}
             LIMIT $4
         )
         -- 次序在外层再排一遍,并列由实体 id 定(`vector_index::RESORT`,#652)
         SELECT canonical_name, type_id, key, distance, same_document
         FROM nearest ORDER BY {resort}",
        distance = crate::vector_index::distance("e.profile_embedding", 3, dims),
        resort = crate::vector_index::RESORT,
        same_dims = crate::vector_index::same_dims("e.profile_embedding", dims),
    ))
    .bind(kb_id)
    .bind(entity_id)
    .bind(&query_vec)
    .bind(limit)
    .fetch_all(&mut *tx)
    .await?;
    tx.commit().await?;
    Ok(rows)
}

/// 同时跑几个近邻查询。池是 32、按「同时跑的短查询」定的(`db.rs`);六十个
/// 全表扫一起上就是那里记的池子被吃空的样子——慢请求和超时,没有一句话说池小了。
/// 八个留足了给请求的余量,而 HNSW 就位之后每个查询只有几毫秒,再高也没意义
pub const NEIGHBOUR_SCANS: usize = 8;

/// 一批主语各自的近邻,**按送进来的顺序回**:下游裁决按这个顺序读。
///
/// 六十个查询彼此无关,串行只因为循环是串行的(#514)。这里有界并发地取,
/// `buffered` 保序,推理仍在原顺序上做
pub async fn nearest_typed_for_each(
    pool: &PgPool,
    kb_id: Uuid,
    ids: &[Uuid],
    limit: i64,
) -> AppResult<Vec<Vec<(String, Uuid, String, f64, bool)>>> {
    nearest_typed_for_each_with(pool, kb_id, ids, limit, NEIGHBOUR_SCANS).await
}

/// 同上,并发上限由调用方给(测试用它证明上限不改答案)
pub async fn nearest_typed_for_each_with(
    pool: &PgPool,
    kb_id: Uuid,
    ids: &[Uuid],
    limit: i64,
    at_once: usize,
) -> AppResult<Vec<Vec<(String, Uuid, String, f64, bool)>>> {
    use futures_util::{stream, StreamExt, TryStreamExt};
    stream::iter(ids.iter().copied())
        .map(|id| nearest_typed_entities(pool, kb_id, id, limit))
        .buffered(at_once.max(1))
        .try_collect()
        .await
}

/// 按实体逐个改类,写进同一本账。返回 (批次 id, 改动数)。
///
/// 由调用方点名:类型消解裁决出来的是"这个实体是那个类",不是"叫这个说法的都是那个类"。
///
/// 账本格式一字不差,所以 [`unadopt_types`] 原样能撤。
pub async fn retype_entities(
    pool: &PgPool,
    kb_id: Uuid,
    picks: &[(Uuid, Uuid)],
    // None = 引擎自动裁决。跟 entity_merges.merged_by 一个约定,
    // 实体历史据此区分"某某某改的"与"高置信自动改的"
    actor: Option<Uuid>,
) -> AppResult<(Uuid, u32)> {
    let batch_id = Uuid::now_v7();
    let mut moved = 0u32;
    let mut names: std::collections::HashSet<String> = std::collections::HashSet::new();
    // 一个实体在一批里只改一次。账本主键是 (batch_id, entity_id),同一个 id
    // 来两次会撞——而调用方拿到的是 500,整批一个都没落。这里挡住比在那边
    // 追每一条产生 picks 的路子可靠:重复的第二条本来也没有意义
    let mut seen: std::collections::HashSet<Uuid> = std::collections::HashSet::new();
    for (entity_id, type_id) in picks {
        if !seen.insert(*entity_id) {
            continue;
        }
        let mut tx = pool.begin().await?;
        // 已经在目标类上的不算改动,也不进账本——撤销时不该把它们推回去。
        //
        // **旧类型要从 CTE 里读**:`UPDATE … RETURNING` 给的是新值,而账本要记的
        // 是改之前那个。直接 RETURNING type_id 拿到的就是刚写进去的那一个,
        // 撤销时等于把实体"放回"它现在的位置——账本看着满满当当,实际什么都撤不了。
        // 条件也一并放进 CTE:这一行还在、没被合并、且确实要变
        //
        // **`IS DISTINCT FROM` 而不是 `<>`**:0009 之后起点常常是 NULL,而
        // `NULL <> uuid` 是 NULL 不是 true——CTE 会空掉,UPDATE 一行不动,
        // 于是"给没有类的实体定类"这个最主要的场景整个变成空操作
        let row: Option<(Option<Uuid>, String)> = sqlx::query_as(
            "WITH before AS (
                 SELECT id, type_id, canonical_name FROM entities
                 WHERE id = $1 AND kb_id = $3 AND merged_into IS NULL
                   AND type_id IS DISTINCT FROM $2
             )
             UPDATE entities e SET type_id = $2, updated_at = now(),
                    type_source = CASE WHEN $4::uuid IS NULL THEN 'inferred' ELSE 'human' END
             FROM before
             WHERE e.id = before.id
             RETURNING before.type_id, before.canonical_name",
        )
        .bind(entity_id)
        .bind(type_id)
        .bind(kb_id)
        .bind(actor)
        .fetch_optional(&mut *tx)
        .await?;
        let Some((from_type, name)) = row else {
            tx.rollback().await?;
            continue;
        };
        sqlx::query(
            "INSERT INTO entity_retypes
                (batch_id, kb_id, entity_id, from_type_id, to_type_id, actor_id)
             VALUES ($1, $2, $3, $4, $5, $6)",
        )
        .bind(batch_id)
        .bind(kb_id)
        .bind(entity_id)
        .bind(from_type)
        .bind(type_id)
        .bind(actor)
        .execute(&mut *tx)
        .await?;
        tx.commit().await?;
        names.insert(name);
        moved += 1;
    }
    // 消歧后缀的兜底值就是类型标签,改了类就得重算
    for n in &names {
        refresh_disambiguators(pool, kb_id, n).await?;
    }
    Ok((batch_id, moved))
}

/// 人认可过的"粗类 → 细类"配对。
///
/// 待人工那一档由"跨没跨分类轴"触发,而那条判据测的常常是**种子类跟导入词汇表
/// 连没连上**,不是风险:schema.org 的 Place 另起 key,内置 location 零子类,
/// 于是每个城市都要问一遍。配对是类与类之间的事,实体只是碰巧撞上它——
/// 认可一次就该一直算数。
pub async fn approved_refinements(
    pool: &PgPool,
    kb_id: Uuid,
) -> AppResult<std::collections::HashSet<(Uuid, Uuid)>> {
    let rows: Vec<(Uuid, Uuid)> = sqlx::query_as(
        "SELECT from_type_id, to_type_id FROM type_refinement_pairs WHERE kb_id = $1",
    )
    .bind(kb_id)
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().collect())
}

/// 记下一个被认可的配对。重复认可是幂等的。
pub async fn approve_refinement(
    pool: &PgPool,
    kb_id: Uuid,
    from_type_id: Uuid,
    to_type_id: Uuid,
    by: Uuid,
) -> AppResult<()> {
    sqlx::query(
        "INSERT INTO type_refinement_pairs (kb_id, from_type_id, to_type_id, approved_by)
         VALUES ($1, $2, $3, $4)
         ON CONFLICT (kb_id, from_type_id, to_type_id) DO NOTHING",
    )
    .bind(kb_id)
    .bind(from_type_id)
    .bind(to_type_id)
    .bind(by)
    .execute(pool)
    .await?;
    Ok(())
}

#[cfg(test)]
mod same_type_tests {
    use super::{classify_type_drift, TypeDrift};

    /// **相同类型是最常见的情形,而它曾经落在 Disjoint 上。**
    ///
    /// 这个函数生来服务"类型漂移"(同名被抽成两种类型),那里两边相同不会发生;
    /// 后来被 `containment_reviews` 借去当相容性判据,那里两边相同是常态。
    /// 结果是 `Sherlock Holmes` 与 `Holmes` 一对都进不了审阅队列。
    #[test]
    fn the_same_type_is_a_recall_candidate() {
        for k in ["person", "location", "organization", "product", "event"] {
            assert_eq!(
                classify_type_drift(Some(k), Some(k)),
                TypeDrift::Recall,
                "{k} 对 {k} 必须可召回"
            );
        }
        // 自定义类型同样——这里判的是"两边是不是同一种东西",不是"它在不在白名单里"
        assert_eq!(
            classify_type_drift(Some("drug"), Some("drug")),
            TypeDrift::Recall
        );
        // 跨类型的老结论一条都不变
        assert_eq!(
            classify_type_drift(Some("person"), Some("organization")),
            TypeDrift::Disjoint
        );
    }
}