Skip to content

World's first open-source enterprise world model.

73.9 KB
Raw Blame
//! 关系短语按签名绑到属性(0044 决定 3 的第二片;账本侧见 `utopia_store::phrase_bindings`,
//! 合同见 `utopia_extract::phrase_align`)。
//!
//! 签名 = 短语 × 主语的类 × 宾语的类(宾语是字面值时记「值」)。两端的类来自类别词绑定
//! 写到实体上的 `type_id`,所以这一步排在类别词对齐之后。一个库里 distinct 的签名比陈述
//! 少得多,每条只判一次:**两票一致**才绑(第二票候选倒序,防「选第一个」冒充一致),
//! 不一致记 undecided 留给审核(#725 对齐队列),没有属性对得上记 none——陈述留在开放
//! 图谱,什么都不丢,签名计入工作台的建议。绑定按属性的 `updated_at` 与库里最新的属性
//! 判过期,本体一改只重判过期的。这一片只记判定;按绑定把陈述算成类型化事实是下一片。
//!
//! 候选属性怎么来:先按声明的定义域/值域筛——签名两端的类落在属性的域/值域里的,或者
//! 属性没声明域/值域的(两个方向都算,绑定可以是反向的)。**一端没绑到类的签名,只有
//! 没声明那一端的属性才算候选**:类别词还没绑上时把声明了域的属性也给模型,NVDA 四篇上
//! 现金流量表的每一行都绑到了泛泛的 value(主语 NVIDIA 没类,value 的域是指标)——裁判
//! 判成写错的一半是它。筛完仍超过上限就不判,瞎判比不判糟。

use crate::extraction::chat_retrying_rate_limits_at;
use crate::llm_util;
use crate::state::AppState;
use sha2::{Digest, Sha256};
use std::collections::{HashMap, HashSet};
use utopia_core::models::RelationTypeView;
use utopia_extract::phrase_align::{
    build_phrase_messages, parse_phrase_response, Direction, Marks, PhraseItem, PropertyCandidate,
};
use utopia_store::phrase_bindings::{self, Decision, PhraseSignature};
use uuid::Uuid;

/// 一次问多少条签名。
const BATCH: usize = 12;
/// 筛过定义域/值域之后候选属性最多这么多,再多就不判。
const CANDIDATE_LIMIT: usize = 60;

/// 一票:这条签名选了哪个属性、哪个方向,属性是状态时还有一刻标哪一端(#966)。
/// None = 没有属性对得上
type Vote = Option<(String, Direction, Option<Marks>)>;

/// 代理绑到状态属性、却从没问过一刻标哪一端的绑定(这一列之前的判定,#966):指纹没变也问
/// 一次,只问这一格,不重判绑定(0053 修订 2026-09-27)。问过的不再问,没得到值的列进对齐
/// 队列等人。只进开跑时的 todo,不进收尾的「变了没有」
fn awaits_marks(b: &phrase_bindings::Binding, props: &[RelationTypeView]) -> bool {
    b.status == "bound"
        && b.marks.is_none()
        && b.marks_asked_at.is_none()
        && b.relation_type_id
            .and_then(|id| props.iter().find(|p| p.id == id))
            .is_some_and(|p| p.temporal == "state")
}

/// 一个类连同它的全部祖先。候选按它命中:属性的定义域声明在 legal_entity 上,
/// organization 是它的子类,这条属性对 organization 的签名就是候选(#807 第一条)。
pub(crate) type Closure = HashMap<Uuid, Vec<Uuid>>;

pub(crate) fn closures<'a>(classes: impl IntoIterator<Item = (Uuid, &'a [Uuid])>) -> Closure {
    let classes: Vec<(Uuid, &[Uuid])> = classes.into_iter().collect();
    let parents: HashMap<Uuid, &[Uuid]> = classes.iter().copied().collect();
    classes
        .iter()
        .map(|(id, direct)| {
            let mut seen: Vec<Uuid> = vec![*id];
            let mut stack: Vec<Uuid> = direct.to_vec();
            // 多继承与菱形:UNION 语义,同一个祖先只进一次;环不会有(编辑器不允许)
            while let Some(p) = stack.pop() {
                if seen.contains(&p) {
                    continue;
                }
                seen.push(p);
                if let Some(pp) = parents.get(&p) {
                    stack.extend_from_slice(pp);
                }
            }
            seen.sort();
            (*id, seen)
        })
        .collect()
}

/// 一条候选怎么命中的:`via` 是经继承命中的依据(空 = 直接命中或没声明)。
struct Fit {
    via: Vec<(Uuid, Uuid)>,
}

/// 声明的类里有没有一个是这一端的类或其祖先。没声明不限;这一端没绑到类时只被没声明
/// 的接受。返回命中的 (声明的类, 这一端的类) 当它不是直接命中时
fn within(
    declared: &[Uuid],
    class: Option<Uuid>,
    closure: &Closure,
) -> Option<Option<(Uuid, Uuid)>> {
    if declared.is_empty() {
        return Some(None);
    }
    let c = class?;
    if declared.contains(&c) {
        return Some(None);
    }
    let up = closure.get(&c)?;
    declared
        .iter()
        .find(|d| up.contains(d))
        .map(|d| Some((*d, c)))
}

/// 结构上对得上(本体代理给每批裁词表时用的判据,同对齐的候选)
pub(crate) fn structurally_fits(
    p: &RelationTypeView,
    sig: &PhraseSignature,
    closure: &Closure,
) -> bool {
    fits(p, sig, closure).is_some()
}

/// 签名两端的类落在属性声明的域/值域里,经继承也算;正反两个方向都算。
fn fits(p: &RelationTypeView, sig: &PhraseSignature, closure: &Closure) -> Option<Fit> {
    fits_direction(p, sig, closure, Direction::Forward)
        .or_else(|| fits_direction(p, sig, closure, Direction::Reverse))
}

// Admitting a property in either orientation does not admit both orientations.
// Two agreeing model votes used to turn a forward-only candidate into a reverse binding.
fn fits_direction(
    p: &RelationTypeView,
    sig: &PhraseSignature,
    closure: &Closure,
    direction: Direction,
) -> Option<Fit> {
    let mut via = Vec::new();
    if sig.object_is_value {
        if p.kind != "attribute" || direction != Direction::Forward {
            return None;
        }
        via.extend(within(&p.domains, sig.subject_type_id, closure)?);
        return Some(Fit { via });
    }
    if p.kind != "relation" {
        return None;
    }
    let (subject, object) = match direction {
        Direction::Forward => (sig.subject_type_id, sig.object_type_id),
        Direction::Reverse => (sig.object_type_id, sig.subject_type_id),
    };
    let a = within(&p.domains, subject, closure)?;
    let b = within(&p.ranges, object, closure)?;
    via.extend(a);
    via.extend(b);
    Some(Fit { via })
}

fn invalid_agent_direction(
    b: &phrase_bindings::Binding,
    sig: &PhraseSignature,
    props: &[RelationTypeView],
    closure: &Closure,
) -> bool {
    b.decided_by == "agent"
        && b.status == "bound"
        && b.relation_type_id
            .and_then(|id| props.iter().find(|p| p.id == id))
            .is_some_and(|p| match b.direction.as_deref() {
                Some("forward") => fits_direction(p, sig, closure, Direction::Forward).is_none(),
                Some("reverse") => fits_direction(p, sig, closure, Direction::Reverse).is_none(),
                _ => true,
            })
}

/// 这条关系叫这个短语:键或标签归一后与它相等(同类别词的归一)。像不算——
/// 「validated by tests」不是 validated_by,那是模型的题
fn named_by(p: &RelationTypeView, phrase: &str) -> bool {
    phrase_bindings::normalize(&p.key) == phrase || phrase_bindings::normalize(&p.label) == phrase
}

/// 签名的短语正好是一条声明了的关系(#1242):它叫这个短语,主语的类落在声明的域里、
/// 宾语的类落在值域里(经继承也算),只认正向。域或值域没声明的不算——没声明是「不限」,
/// 不是「就是它」;一端没有类的也不算。状态关系不算:绑上它还得说只带一个日期的陈述那个
/// 日期标哪一端(`marks`,#966),本体答不了,留给对齐器——它绑上、顺带问这一格,问不到的
/// 进队列等人。叫这个短语、两端也都对得上的不止一条,谁也不认:两条关系叫得一样,该由人
/// 或模型来挑
fn declared<'a>(
    sig: &PhraseSignature,
    props: &'a [RelationTypeView],
    closure: &Closure,
) -> Option<&'a RelationTypeView> {
    if sig.object_is_value {
        return None;
    }
    let mut fitting = props.iter().filter(|p| {
        p.kind == "relation"
            && p.temporal != "state"
            && !p.domains.is_empty()
            && !p.ranges.is_empty()
            && named_by(p, &sig.phrase)
            && fits_direction(p, sig, closure, Direction::Forward).is_some()
    });
    let only = fitting.next()?;
    fitting.next().is_none().then_some(only)
}

/// 对齐器不再判的判定:人的;本体判的、此刻仍是它声明的那条关系的。本体判的行没有指纹,
/// 按指纹比永远「过期」——不先放过它,每轮都会把它送去问模型、收尾时又以为变了再排一份
fn settled(
    b: &phrase_bindings::Binding,
    sig: &PhraseSignature,
    props: &[RelationTypeView],
    closure: &Closure,
) -> bool {
    b.decided_by == "person"
        || (b.decided_by == "ontology"
            && b.relation_type_id.is_some()
            && declared(sig, props, closure).map(|p| p.id) == b.relation_type_id)
}

/// 推送来的文档抽完(0054):它的陈述落在的签名里,短语正好是一条声明了的关系的,由本体
/// 直接绑上,记成本体判的(#1242)。不问模型,没配对话模型也照判;别的签名照旧留给对齐器。
/// 判定照旧是签名上的一行(0044 决定 3),人看得见、改得了;人的判定不动(`decide_on`
/// 的规矩),已经由本体按同一条关系判过的不重写——判定时刻和回归记录不该随每次推送翻新。
/// 返回写下的判定数
pub(crate) async fn bind_declared(
    pool: &sqlx::PgPool,
    kb_id: Uuid,
    document_id: Uuid,
) -> anyhow::Result<usize> {
    let props = utopia_store::ontology::relation_type_views(pool, kb_id).await?;
    let keys: HashSet<SignatureKey> =
        phrase_bindings::signature_keys_of_document(pool, kb_id, document_id)
            .await?
            .into_iter()
            .filter(|(phrase, ..)| props.iter().any(|p| named_by(p, phrase)))
            .collect();
    // 多数推送没有一个短语叫得出关系的名字:库级的签名就不必数了
    if keys.is_empty() {
        return Ok(0);
    }
    let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
    let closure = closures(classes.iter().map(|c| (c.id, c.parents.as_slice())));
    let existing: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
        .await?
        .into_iter()
        .map(|b| (b.key(), b))
        .collect();
    // 判过的先剔掉:库级的签名是整库分组,每次推送都数一遍太贵(#1296)
    let keys: HashSet<SignatureKey> = keys
        .into_iter()
        .filter(|k| {
            !existing
                .get(k)
                .is_some_and(|b| settled(b, &keyed(k), &props, &closure))
        })
        .collect();
    if keys.is_empty() {
        return Ok(0);
    }
    let mut written = 0;
    for s in phrase_bindings::signatures(pool, kb_id)
        .await?
        .iter()
        .filter(|s| keys.contains(&s.key()))
    {
        let Some(p) = declared(s, &props, &closure) else {
            continue;
        };
        if phrase_bindings::decide(
            pool,
            kb_id,
            s,
            Decision {
                relation_type_id: Some(p.id),
                direction: Some(Direction::Forward.as_str()),
                status: "bound",
                votes: &serde_json::json!({ "reason": "declared_relation" }),
                decided_by: "ontology",
                basis: None,
                marks: None,
                marks_asked: false,
            },
        )
        .await?
        {
            written += 1;
        }
    }
    Ok(written)
}

/// 签名的键:短语 + 两端的类 + 宾语是不是字面值(与 `PhraseSignature::key` 同形)
type SignatureKey = (String, Option<Uuid>, Option<Uuid>, bool);

/// 只有键的签名:`settled` 只看键上的这几格,不必为它把库里的签名数一遍
fn keyed(
    (phrase, subject_type_id, object_type_id, object_is_value): &SignatureKey,
) -> PhraseSignature {
    PhraseSignature {
        phrase: phrase.clone(),
        subject_type_id: *subject_type_id,
        subject_type_key: None,
        object_type_id: *object_type_id,
        object_type_key: None,
        object_is_value: *object_is_value,
        count: 0,
        examples: Vec::new(),
        quotes: Vec::new(),
        example_statement_ids: Vec::new(),
    }
}

/// 每条签名此刻的候选与指纹
type Considered<'a> = HashMap<SignatureKey, (Vec<&'a RelationTypeView>, String)>;

/// 每条活着的签名此刻的候选(经继承命中)与指纹(0053)。开跑时算一次决定要判谁,
/// 收尾时用重新加载的输入再算一次决定要不要再排——两次之间世界可能变了
fn consider<'a>(
    sigs: &[PhraseSignature],
    props: &'a [RelationTypeView],
    closure: &Closure,
    versions: &HashMap<Uuid, chrono::DateTime<chrono::Utc>>,
    shortlist: Option<&Shortlist>,
) -> Considered<'a> {
    let empty: Vec<Uuid> = Vec::new();
    sigs.iter()
        .map(|s| {
            let mut fitting: Vec<&RelationTypeView> = props
                .iter()
                .filter(|p| fits(p, s, closure).is_some())
                .collect();
            // 结构对得上的太多时只留最近的几条(见 `shortlist`),按相关度排:第一票先看最像的
            if let Some(keep) = shortlist.and_then(|m| m.get(&s.key())) {
                fitting.retain(|p| keep.contains(&p.id));
                fitting.sort_by_key(|p| keep.iter().position(|k| *k == p.id));
            }
            let cands: Vec<(Uuid, chrono::DateTime<chrono::Utc>)> = fitting
                .iter()
                .filter_map(|p| versions.get(&p.id).map(|at| (p.id, *at)))
                .collect();
            let up = |c: Option<Uuid>| -> &[Uuid] {
                c.and_then(|c| closure.get(&c))
                    .map(Vec::as_slice)
                    .unwrap_or(&empty)
            };
            let basis = phrase_bindings::basis_of(
                up(s.subject_type_id),
                up(s.object_type_id),
                s.object_is_value,
                &cands,
            );
            (s.key(), (fitting, basis))
        })
        .collect()
}

/// 第二票要不要投。第二票防的是「选第一个」冒充一致,要两票一致的是**绑定**;第一票
/// 说没有一条对得上的签名,第二票怎么答都绑不上:答没有是「无」,答了一条是「拿不定」。
/// 测量库一轮 864 条签名里第一票说没有的 317 条,没有一条最后绑上(bench README,
/// 2026-09-28),这一票省下。第一票没答到的也不投:少一票本来就不下结论。
/// 补问 marks 的照旧投两票:它要两票说同一个值
fn second_vote_is_due(first: &Vote, first_answered: bool, marks_only: bool) -> bool {
    marks_only || (first_answered && first.is_some())
}

/// 类别词规则的宾语是从类别词自己的字里读出来的(「british film」读出英国),只有中心词
/// 的类别词(「state」「ship」)没有可读的字:一轮 159 个类别词里 127 个是单个词,提出
/// 的 8 条规则没有一条读得出宾语(bench README,2026-09-28)。这种不问。
///
/// 只认得出用空格分词的写法:一串 ASCII 字母是一个词。带连字符、数字的(「1968」、
/// 「british-governed」)和不分词的文字(「英国电影」)看不出有没有修饰语,照旧问
fn has_modifier(kind_word: &str) -> bool {
    !kind_word.trim().chars().all(|c| c.is_ascii_alphabetic())
}

/// 把签名分成批,候选相近的放在一起。返回每批里签名的下标。
///
/// 属性定义表在一批里只写一遍,占一次调用输入的将近一半:按到来的次序每十二条切一批时,
/// 同批的签名互不相干(一条讲出生地、一条讲导演、一条讲所属球队),各自十条候选几乎不
/// 重叠,合起来就是本体的一半(测量库上九十六条属性里约五十条)。这里只改排法:每条签名
/// 看到的候选一条不少,判断一字不变。
///
/// 贪心:每批从还没排的第一条起,每次加进让这一批的候选并集长得最少的那一条,并列时取
/// 靠前的——结果只由输入决定,同样的签名每次排成同样的批。没有候选的签名不问模型,
/// 排在最后,不占有候选的批里的位置
fn batch_by_candidates<K: Copy + Eq + std::hash::Hash>(
    sets: &[Vec<K>],
    size: usize,
) -> Vec<Vec<usize>> {
    let size = size.max(1);
    let mut left: Vec<usize> = (0..sets.len()).filter(|i| !sets[*i].is_empty()).collect();
    let empty: Vec<usize> = (0..sets.len()).filter(|i| sets[*i].is_empty()).collect();
    let mut out: Vec<Vec<usize>> = Vec::new();
    while !left.is_empty() {
        let first = left.remove(0);
        let mut batch = vec![first];
        let mut union: HashSet<K> = sets[first].iter().copied().collect();
        while batch.len() < size && !left.is_empty() {
            let (at, _) = left
                .iter()
                .enumerate()
                .map(|(at, i)| (at, sets[*i].iter().filter(|k| !union.contains(k)).count()))
                .min_by_key(|(at, added)| (*added, *at))
                .expect("left is not empty");
            let i = left.remove(at);
            union.extend(sets[i].iter().copied());
            batch.push(i);
        }
        out.push(batch);
    }
    out.extend(empty.chunks(size).map(<[usize]>::to_vec));
    out
}

/// 日志里放得下的一段回复:空白折成一个空格,最多这么多字符。
const SNIPPET_CHARS: usize = 240;

fn snippet(text: &str) -> String {
    let flat = text.split_whitespace().collect::<Vec<_>>().join(" ");
    let mut out: String = flat.chars().take(SNIPPET_CHARS).collect();
    if flat.chars().count() > SNIPPET_CHARS {
        out.push('…');
    }
    out
}

/// 一条签名结构对得上的属性多过这个数,就按相关度只留这么多给模型看。第一次真跑里每条
/// 签名平均拖着几十条候选(六个粗类切不掉什么),一次请求 1.8 万 token,对齐占了一轮
/// 八成的用量(bench README,2026-09-24);十条里若没有对的,多半是本体里就没有
const SHORTLIST: usize = 10;
/// 同时在飞的对齐批次数;模型闸门(工作区的并发上限)在下面再限一次
const PARALLEL_BATCHES: usize = 4;
/// 一次嵌入多少条签名的文本
const SHORTLIST_EMBED_BATCH: usize = 32;

/// 签名 → 留给模型看的候选 id(按相关度)。没进表的签名照旧看全部结构候选
type Shortlist = HashMap<SignatureKey, Vec<Uuid>>;

/// 按相关度给候选多的签名开短名单:签名的文本(短语加一条例句)嵌入后,与属性的向量比
/// 近(`embed_ontology` 建的那份),留最近的 [`SHORTLIST`] 条;标签里的词出现在短语里的
/// 属性无论远近都留着("based in" 对 "based in")。没配嵌入模型、属性还没向量、或候选本来
/// 就不多的签名不进表——那时模型看的还是全部结构候选。
///
/// 签名的向量按 (库, 嵌入模型, 文本的哈希) 存在 `signature_vectors` 里,一轮只嵌没见过的
/// 文本(#1097):签名的文本两轮之间几乎不变,从前每轮全部重嵌,判的可能只是新来的几十条
async fn shortlist(
    state: &AppState,
    settings: &utopia_core::models::LlmSettings,
    kb_id: Uuid,
    sigs: &[PhraseSignature],
    full: &Considered<'_>,
) -> anyhow::Result<Shortlist> {
    let mut out = Shortlist::new();
    let (Some(client), Some(model)) = (
        llm_util::embed_client(settings),
        settings.embed_model.as_deref(),
    ) else {
        return Ok(out);
    };
    let wide: Vec<&PhraseSignature> = sigs
        .iter()
        .filter(|s| full.get(&s.key()).is_some_and(|(f, _)| f.len() > SHORTLIST))
        .collect();
    let pool = &state.pool;
    let texts: Vec<String> = wide.iter().map(|s| signature_text(s)).collect();
    let hashes: Vec<Vec<u8>> = texts
        .iter()
        .map(|t| Sha256::digest(t.as_bytes()).to_vec())
        .collect();
    // 这一轮不再出现的文本、别的模型嵌的向量删掉。按全部候选多的签名留,不只按下面嵌了的:
    // 一批嵌入失败时,上一轮存好的不跟着丢
    utopia_store::signature_vectors::prune(pool, kb_id, model, &hashes).await?;
    if wide.is_empty() {
        return Ok(out);
    }
    // 先问这一类属性有没有向量,没有的签名不嵌:嵌了最近邻也是空,照样看全部。一个没跑过
    // `embed_ontology` 的库从前每轮把一万七千条签名送去嵌入、短名单一条没开(#1097)。
    // 一类问一句,至多两句
    let mut has_vectors = HashMap::new();
    for kind in ["relation", "attribute"] {
        if wide.iter().any(|s| property_kind(s) == kind) {
            let has =
                utopia_store::ontology::has_relation_type_vectors(pool, kb_id, Some(kind)).await?;
            has_vectors.insert(kind, has);
        }
    }
    let usable: Vec<usize> = (0..wide.len())
        .filter(|&i| has_vectors.get(property_kind(wide[i])) == Some(&true))
        .collect();
    let wanted: Vec<Vec<u8>> = usable.iter().map(|&i| hashes[i].clone()).collect();
    let mut vectors = utopia_store::signature_vectors::get(pool, kb_id, model, &wanted).await?;
    let reused = vectors.len();
    // 没存过的才嵌;两条签名文本相同(例句、引文都一样)只嵌一次
    let mut queued = HashSet::new();
    let missing: Vec<usize> = usable
        .iter()
        .copied()
        .filter(|&i| !vectors.contains_key(&hashes[i]) && queued.insert(&hashes[i]))
        .collect();
    let mut embedded = 0;
    for batch in missing.chunks(SHORTLIST_EMBED_BATCH) {
        let batch_texts: Vec<String> = batch.iter().map(|&i| texts[i].clone()).collect();
        let got = {
            let _permit = llm_util::acquire_embed(state, settings).await;
            match client.embed(&batch_texts).await {
                Ok(v) if v.len() == batch.len() => v,
                Ok(v) => {
                    tracing::warn!(%kb_id, sent = batch.len(), got = v.len(), "签名向量数量对不上,这一批不开短名单");
                    continue;
                }
                Err(e) => {
                    tracing::warn!(%kb_id, error = %e, "签名向量没算出来,这一批不开短名单");
                    continue;
                }
            }
        };
        let items: Vec<(Vec<u8>, Vec<f32>)> =
            batch.iter().map(|&i| hashes[i].clone()).zip(got).collect();
        utopia_store::signature_vectors::put(pool, kb_id, model, &items).await?;
        embedded += items.len();
        vectors.extend(items);
    }
    for &i in &usable {
        let s = wide[i];
        // 这一批没嵌出来:不开短名单,模型看全部
        let Some(vector) = vectors.get(&hashes[i]) else {
            continue;
        };
        let (fitting, _) = &full[&s.key()];
        let near = utopia_store::ontology::nearest_relation_type_ids(
            pool,
            kb_id,
            vector,
            (fitting.len() * 2) as i64,
            Some(property_kind(s)),
        )
        .await?;
        if near.is_empty() {
            // 属性还没有向量:不开短名单,模型看全部
            continue;
        }
        let fitting_ids: Vec<Uuid> = fitting.iter().map(|p| p.id).collect();
        let must_keep: Vec<Uuid> = fitting
            .iter()
            .filter(|p| label_in_phrase(&p.label, &s.phrase))
            .map(|p| p.id)
            .collect();
        out.insert(
            s.key(),
            pick_shortlist(&near, &fitting_ids, &must_keep, SHORTLIST),
        );
    }
    tracing::info!(
        %kb_id,
        wide = wide.len(),
        skipped = wide.len() - usable.len(),
        reused,
        embedded,
        shortlisted = out.len(),
        "候选短名单开好"
    );
    Ok(out)
}

/// 嵌入用的签名文本:短语加第一条例句和它的引文。缓存按它的哈希认,改了这里旧向量都对不上,
/// 下一轮全部重嵌一次
fn signature_text(s: &PhraseSignature) -> String {
    match (s.examples.first(), s.quotes.first()) {
        (Some(e), Some(q)) => format!("{} · {e} · {q}", s.phrase),
        (Some(e), None) => format!("{} · {e}", s.phrase),
        _ => s.phrase.clone(),
    }
}

/// 签名能绑的是哪一类属性:宾语是字面值的绑属性,否则绑关系
fn property_kind(s: &PhraseSignature) -> &'static str {
    if s.object_is_value {
        "attribute"
    } else {
        "relation"
    }
}

/// 类别词 → 留给提规则看的属性 id(按相关度)。词的文本加几个例名嵌入,取最近的
/// [`SHORTLIST`] 条;没配嵌入模型、属性没向量的不进表
async fn shortlist_kind_words(
    state: &AppState,
    settings: &utopia_core::models::LlmSettings,
    kb_id: Uuid,
    words: &[&utopia_store::type_bindings::KindWordSignature],
) -> anyhow::Result<HashMap<String, Vec<Uuid>>> {
    let mut out = HashMap::new();
    let Some(client) = llm_util::embed_client(settings) else {
        return Ok(out);
    };
    // 一条带向量的属性都没有,嵌了也是空手而回(理由同 `shortlist`)
    if words.is_empty()
        || !utopia_store::ontology::has_relation_type_vectors(&state.pool, kb_id, None).await?
    {
        return Ok(out);
    }
    for batch in words.chunks(SHORTLIST_EMBED_BATCH) {
        let texts: Vec<String> = batch
            .iter()
            .map(|k| format!("{} · {}", k.kind_word, k.examples.join(", ")))
            .collect();
        let vectors = {
            let _permit = llm_util::acquire_embed(state, settings).await;
            match client.embed(&texts).await {
                Ok(v) if v.len() == batch.len() => v,
                Ok(_) | Err(_) => {
                    tracing::warn!(%kb_id, "类别词向量没算出来,这一批看全部候选");
                    continue;
                }
            }
        };
        for (k, vector) in batch.iter().zip(vectors) {
            let near = utopia_store::ontology::nearest_relation_type_ids(
                &state.pool,
                kb_id,
                &vector,
                SHORTLIST as i64,
                None,
            )
            .await?;
            if !near.is_empty() {
                out.insert(k.kind_word.clone(), near);
            }
        }
    }
    Ok(out)
}

/// 标签里有一个像样的词(四个字母以上)出现在短语里
fn label_in_phrase(label: &str, phrase: &str) -> bool {
    let phrase = phrase.to_lowercase();
    label
        .to_lowercase()
        .split(|c: char| !c.is_alphanumeric())
        .any(|w| w.len() >= 4 && phrase.contains(w))
}

/// 短名单:先是标签对上的(无论远近),再按向量距离补到上限;都是结构对得上的
fn pick_shortlist(near: &[Uuid], fitting: &[Uuid], must_keep: &[Uuid], limit: usize) -> Vec<Uuid> {
    let mut out: Vec<Uuid> = must_keep
        .iter()
        .copied()
        .filter(|id| fitting.contains(id))
        .collect();
    for id in near {
        if out.len() >= limit {
            break;
        }
        if fitting.contains(id) && !out.contains(id) {
            out.push(*id);
        }
    }
    out
}

/// 一轮里没判完的(调用失败、回复读不出、模型漏答)自己再排几次;超过这个数就等
/// 下一篇文档或本体的改动再问。不设上限的话,温度为零下一段每次都读不出的回复会让
/// 任务每隔几十秒把同一段提示词再送一遍,没有尽头(同类别词对齐)
pub(crate) const MAX_REASK: u32 = 3;

/// 对一个库跑一遍:新出现的和过期的签名各判一次。
/// `reask` 是这份任务已经是第几次自己排的(文档、本体、类别词对齐排的是 0)。
pub async fn align_phrases_reasking(
    state: &AppState,
    kb_id: Uuid,
    reask: u32,
) -> anyhow::Result<()> {
    let pool = &state.pool;
    // Human interpretations are deliberately preserved by alignment. Report that preservation
    // explicitly even when no model is configured; it is not a fresh semantic judgment.
    utopia_store::ontology_regressions::record_human(pool, kb_id).await?;
    let kb = utopia_store::kbs::get(pool, kb_id).await?;
    let settings = utopia_store::settings::get(pool, kb.workspace_id)
        .await?
        .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align phrases"))?;
    // 对齐是判断题:让模型按端点默认的强度想,不用工作区给抽取设的 minimal
    let client = llm_util::chat_client(&settings)
        .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align phrases"))?;
    // 类别词对齐还排着或跑着:两端的类还没定,现在判的签名指纹马上就变,判了也是重判。
    // 等它收尾再来——排一份半分钟后的,排着的至多一份。别的入口(本体页、审核页、每篇文档
    // 抽完)排的短语对齐也从这里过,所以这一道守住就够。
    //
    // 本体向量还在补也等:编辑器建了属性先排 `embed_ontology` 再排这个任务,没向量的属性
    // 进不了短名单,形状的指纹不变,现在判了它照样不在候选里(`bordered_by` 第一次真跑
    // 就是这么漏的)。补齐任务几秒到几分钟,等得起
    let waiting_on = if utopia_store::jobs::pending_for_kb(pool, "align_types", kb_id).await? {
        Some("类别词对齐")
    } else if utopia_store::jobs::pending_for_kb(pool, "embed_ontology", kb_id).await? {
        Some("本体向量补齐")
    } else {
        None
    };
    if let Some(what) = waiting_on {
        tracing::info!(%kb_id, "短语对齐:{what}还没收尾,半分钟后再看");
        let payload = if reask == 0 {
            serde_json::json!({ "kb_id": kb_id })
        } else {
            serde_json::json!({ "kb_id": kb_id, "reask": reask })
        };
        utopia_store::jobs::enqueue_unless_queued_after(
            pool,
            "align_phrases",
            payload,
            std::time::Duration::from_secs(30),
        )
        .await?;
        return Ok(());
    }
    // 一个库同时只跑一份,理由同类别词对齐(并行跑会把端点打出 502)
    let mut guard = pool.acquire().await?;
    let locked: bool =
        sqlx::query_scalar("SELECT pg_try_advisory_lock(hashtext('align_phrases'), hashtext($1))")
            .bind(kb_id.to_string())
            .fetch_one(&mut *guard)
            .await?;
    if !locked {
        // 正在跑的那份结束时会自己看一眼有没有新东西(见 align_phrases_locked 末尾);这里
        // 不排——排回去会和跑着的那份互相踢成死循环
        tracing::info!(%kb_id, "短语对齐已有一份在跑,这次跳过");
        return Ok(());
    }
    let result = align_phrases_locked(state, kb_id, reask, &settings, &client).await;
    let _ = sqlx::query("SELECT pg_advisory_unlock(hashtext('align_phrases'), hashtext($1))")
        .bind(kb_id.to_string())
        .execute(&mut *guard)
        .await;
    result
}

async fn align_phrases_locked(
    state: &AppState,
    kb_id: Uuid,
    reask: u32,
    settings: &utopia_core::models::LlmSettings,
    client: &utopia_llm::LlmClient,
) -> anyhow::Result<()> {
    let pool = &state.pool;
    let props = utopia_store::ontology::relation_type_views(pool, kb_id).await?;
    let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
    let class_key: HashMap<Uuid, &str> = classes.iter().map(|c| (c.id, c.key.as_str())).collect();
    let by_key: HashMap<&str, &RelationTypeView> =
        props.iter().map(|p| (p.key.as_str(), p)).collect();
    let closure = closures(classes.iter().map(|c| (c.id, c.parents.as_slice())));
    let versions = phrase_bindings::property_versions(pool, kb_id).await?;
    let sigs = phrase_bindings::signatures(pool, kb_id).await?;
    let existing: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
        .await?
        .into_iter()
        .map(|b| (b.key(), b))
        .collect();
    // 每条活着的签名此刻的候选与指纹。候选按继承命中,多了再按相关度开短名单;指纹是判定
    // 看到的全部输入(0053),短名单也算在内——名单变了就再问
    let full = consider(&sigs, &props, &closure, &versions, None);
    let short = shortlist(state, settings, kb_id, &sigs, &full).await?;
    let considered = consider(&sigs, &props, &closure, &versions, Some(&short));
    // 过期 = 存下的指纹和此刻的不一样(没有指纹的是这一列出现前判的,各重判一次)。
    // 不再按时间戳:父边的增删、请求途中的编辑(#795)时间戳看不见。人的判定、本体仍认的
    // 判定(`settled`)不重判。绑到状态属性、从没问过一刻标哪一端的代理判定也问(`awaits_marks`,#966)
    let todo: Vec<&PhraseSignature> = sigs
        .iter()
        .filter(|s| match existing.get(&s.key()) {
            None => true,
            Some(b) => {
                !settled(b, s, &props, &closure)
                    && (b.basis.as_deref() != Some(considered[&s.key()].1.as_str())
                        || awaits_marks(b, &props)
                        || invalid_agent_direction(b, s, &props, &closure))
            }
        })
        .collect();
    let attempted: HashSet<_> = todo.iter().map(|s| s.key()).collect();
    // 其中指纹没变、只为补问 marks 进来的:这一问只能写 marks,绑定原样(0053 修订 2026-09-27)。
    // 从前整条重判,两票没选属性就把绑上的签名判成 none,它的类型化行跟着作废
    let marks_only: HashMap<_, &phrase_bindings::Binding> = todo
        .iter()
        .filter_map(|s| {
            let b = existing.get(&s.key())?;
            (b.basis.as_deref() == Some(considered[&s.key()].1.as_str())
                && awaits_marks(b, &props)
                && !invalid_agent_direction(b, s, &props, &closure))
            .then_some((s.key(), b))
        })
        .collect();
    tracing::info!(%kb_id, signatures = sigs.len(), to_decide = todo.len(), properties = props.len(), "短语对齐开始");

    // 没有属性可绑:每条都是「没有」;属性出现后指纹变了,它们会再交回来
    if props.is_empty() {
        for s in &todo {
            phrase_bindings::decide(
                pool,
                kb_id,
                s,
                Decision {
                    relation_type_id: None,
                    direction: None,
                    status: "none",
                    votes: &serde_json::json!({ "reason": "no_properties" }),
                    decided_by: "agent",
                    basis: Some(&considered[&s.key()].1),
                    marks: None,
                    marks_asked: false,
                },
            )
            .await?;
        }
        return Ok(());
    }

    let keys_of = |ids: &[Uuid]| -> Vec<&str> {
        ids.iter()
            .filter_map(|id| class_key.get(id).copied())
            .collect()
    };
    let (mut bound, mut none, mut undecided, mut skipped) = (0usize, 0usize, 0usize, 0usize);
    // 调用或解析失败的批次:这轮跳过,结束时自己再排一次
    let mut failed = 0usize;
    // 问了、模型也答了、却没答到的签名:两票缺一票就不下结论
    let mut unanswered = 0usize;
    // marks:补问写下了值的;问过却没得到两票同一个值、列进对齐队列的
    let (mut marked, mut unsettled) = (0usize, 0usize);
    // 批与批并行([`PARALLEL_BATCHES`] 个在飞,模型闸门再限一次):一批两票串行要等模型
    // 想两回,串着跑 22 批就是半小时,其中一次卡住的调用能把整轮拖住 18 分钟(bench README,
    // 2026-09-24)。每批各记各的数,回来再加
    {
        use futures_util::StreamExt;
        // 只把引用搬进各批的 future
        let (considered, full, closure, class_key, by_key, marks_only) = (
            &considered,
            &full,
            &closure,
            &class_key,
            &by_key,
            &marks_only,
        );
        // 先把每批的 future 造出来再排队:直接在 map 里返回 async 块会让借用的生命周期
        // 满足不了 tokio::spawn 要的 Send
        // 候选相近的签名排进同一批(见 `batch_by_candidates`):属性表一批只写一遍,同批的
        // 签名候选重叠得越多,这张表越短
        let sets: Vec<Vec<Uuid>> = todo
            .iter()
            .map(|s| {
                let fitting = &considered[&s.key()].0;
                if fitting.len() > CANDIDATE_LIMIT {
                    Vec::new()
                } else {
                    fitting.iter().map(|p| p.id).collect()
                }
            })
            .collect();
        let batches: Vec<Vec<&PhraseSignature>> = batch_by_candidates(&sets, BATCH)
            .into_iter()
            .map(|group| group.into_iter().map(|i| todo[i]).collect())
            .collect();
        let futures: Vec<_> = batches
            .iter()
            .map(|batch| batch.as_slice())
            .map(|batch| async move {
                let (mut bound, mut none, mut undecided, mut skipped, mut failed, mut unanswered) =
                    (0usize, 0usize, 0usize, 0usize, 0usize, 0usize);
                let (mut marked, mut unsettled) = (0usize, 0usize);
        // 候选超过上限的不问模型:记成 undecided 交给人,指纹照记——属性少下去指纹就变,
        // 到时再问。从前超限和无候选一样静默跳过,签名永远排着又永远不可执行(#807)
        let cands: Vec<Vec<&RelationTypeView>> = batch
            .iter()
            .map(|s| {
                let fitting = &considered[&s.key()].0;
                if fitting.len() > CANDIDATE_LIMIT {
                    Vec::new()
                } else {
                    fitting.clone()
                }
            })
            .collect();
        let mut votes: Vec<(Vote, Vote)> = vec![(None, None); batch.len()];
        let mut answered = vec![(false, false); batch.len()];
        // 读得出回复的遍数:补问 marks 时,两遍的回复都回来了才算问过
        let mut replied = 0usize;
        for pass in 0..2 {
            let items: Vec<PhraseItem<'_>> = batch
                .iter()
                .enumerate()
                .filter(|(i, _)| !cands[*i].is_empty())
                .filter(|(i, s)| pass == 0 || second_vote_is_due(&votes[*i].0, answered[*i].0, marks_only.contains_key(&s.key())))
                .map(|(i, s)| {
                    let mut list: Vec<&RelationTypeView> = cands[i].clone();
                    if pass == 1 {
                        list.reverse();
                    }
                    PhraseItem {
                        id: i as i64,
                        phrase: &s.phrase,
                        subject_class: s.subject_type_key.as_deref(),
                        object_class: s.object_type_key.as_deref(),
                        object_is_value: s.object_is_value,
                        statement_count: s.count,
                        examples: &s.examples,
                        quotes: &s.quotes,
                        candidates: list
                            .iter()
                            .map(|p| PropertyCandidate {
                                key: &p.key,
                                label: &p.label,
                                description: &p.description,
                                kind: &p.kind,
                                temporal: &p.temporal,
                                domains: keys_of(&p.domains),
                                ranges: keys_of(&p.ranges),
                                via: fits(p, s, closure)
                                    .map(|f| {
                                        f.via
                                            .iter()
                                            .map(|(declared, class)| {
                                                format!(
                                                    "{} is a subclass of {}",
                                                    class_key.get(class).copied().unwrap_or("?"),
                                                    class_key.get(declared).copied().unwrap_or("?"),
                                                )
                                            })
                                            .collect()
                                    })
                                    .unwrap_or_default(),
                            })
                            .collect(),
                        // 结构对得上却没进短名单的键:模型若从批里的属性表选了它,算票
                        also_allowed: full[&s.key()]
                            .0
                            .iter()
                            .filter(|p| !cands[i].iter().any(|c| c.id == p.id))
                            .map(|p| p.key.as_str())
                            .collect(),
                    }
                })
                .collect();
            if items.is_empty() {
                continue;
            }
            let messages = build_phrase_messages(&items);
            let reply =
                match chat_retrying_rate_limits_at(state, settings, client, &messages, Some(0.0))
                    .await
                {
                    Ok(r) => r,
                    Err(e) => {
                        tracing::warn!(%kb_id, error = %e, "短语对齐调用失败,这一批留到下次");
                        failed += 1;
                        continue;
                    }
                };
            let (choices, malformed) = match parse_phrase_response(&reply.text, &items) {
                Ok(x) => x,
                Err(e) => {
                    tracing::warn!(%kb_id, error = %e, "短语对齐回复解析失败,这一批留到下次");
                    failed += 1;
                    continue;
                }
            };
            skipped += malformed;
            if choices.is_empty() {
                // 解出来了却一条都没读到:回复的形状不是我们认得的。这和解析失败是一回事,
                // 按失败算、留到下次。从前这里什么都不说,每一条签名都当「有一票没答到」
                // 静静跳过,日志里只有一串「完成 bound=0」——回复的开头要进日志,下次才
                // 知道它长什么样(同类别词对齐)
                tracing::warn!(
                    %kb_id,
                    pass,
                    items = items.len(),
                    item_ids = ?items.iter().map(|item| item.id).collect::<Vec<_>>(),
                    malformed,
                    finish_reason = ?reply.finish_reason,
                    repeating = reply.repeating,
                    chars = reply.text.chars().count(),
                    reply = %snippet(&reply.text),
                    "短语对齐回复读不出一条,这一批留到下次"
                );
                failed += 1;
                continue;
            }
            replied += 1;
            if malformed > 0 {
                // 坏票长什么样得看得见:第一次真跑里一半签名被判坏票,查了一天才知道模型答的是标签
                tracing::info!(%kb_id, malformed, reply = %snippet(&reply.text), "短语对齐的回复里有坏票");
            }
            for c in choices {
                let Ok(i) = usize::try_from(c.id) else {
                    continue;
                };
                if let Some(slot) = votes.get_mut(i) {
                    let vote = c.property.map(|(key, direction)| (key, direction, c.marks));
                    if pass == 0 {
                        slot.0 = vote;
                        answered[i].0 = true;
                    } else {
                        slot.1 = vote;
                        answered[i].1 = true;
                    }
                }
            }
        }
        for (i, s) in batch.iter().enumerate() {
            let basis = considered[&s.key()].1.as_str();
            if let Some(asked) = marks_only.get(&s.key()) {
                // 补问 marks(0053 修订 2026-09-27):两票都认这条绑定的属性与方向、又说了同一个
                // 值,写下它;别的答案——没选属性、选了别的、没说或说得不一样——都让绑定原样。
                // 两种都记下问过:不再问,没有值的列进对齐队列等人。回复没回来不算问过,
                // 下次再问(同没答到的签名);问不了的(候选超限)直接交给人
                if !cands[i].is_empty() && replied < 2 {
                    unanswered += 1;
                    continue;
                }
                // 这一票认的是这条绑定,又说了值:认了就是它说的值
                let value_of = |v: &Vote| match v {
                    Some((k, d, m)) => m.filter(|_| {
                        by_key.get(k.as_str()).map(|p| p.id) == asked.relation_type_id
                            && asked.direction.as_deref() == Some(d.as_str())
                    }),
                    None => None,
                };
                let (a, b) = &votes[i];
                let value = value_of(a).filter(|m| value_of(b) == Some(*m));
                if phrase_bindings::record_marks(pool, kb_id, asked, value.map(Marks::as_str))
                    .await?
                {
                    if value.is_some() {
                        marked += 1;
                    } else {
                        unsettled += 1;
                    }
                }
                continue;
            }
            if cands[i].is_empty() {
                let fitting = considered[&s.key()].0.len();
                // 两种「没问模型」各自落库,投影才退得掉、队列才收得住:
                // 没有一条属性对得上 → none(绑过的签名失去支撑,类型化行随物化作废);
                // 对得上的太多 → undecided 交给人,不再每轮重排
                let (status, votes) = if fitting == 0 {
                    ("none", serde_json::json!({ "reason": "no_candidates" }))
                } else {
                    (
                        "undecided",
                        serde_json::json!({ "first": null, "second": null,
                                            "reason": "too_many_candidates", "candidates": fitting }),
                    )
                };
                if phrase_bindings::decide(
                    pool,
                    kb_id,
                    s,
                    Decision {
                        relation_type_id: None,
                        direction: None,
                        status,
                        votes: &votes,
                        decided_by: "agent",
                        basis: Some(basis),
                        marks: None,
                        marks_asked: false,
                    },
                )
                .await?
                {
                    if status == "none" {
                        none += 1;
                    } else {
                        undecided += 1;
                    }
                }
                skipped += 1;
                continue;
            }
            let (a, b) = &votes[i];
            let (ans_a, ans_b) = answered[i];
            // 第一票说没有的不投第二票(见 `second_vote_is_due`):结论就是没有
            let asked_twice = second_vote_is_due(a, ans_a, false);
            if !ans_a || (asked_twice && !ans_b) {
                // 有一票没答到:不下结论,下次再问
                unanswered += 1;
                continue;
            }
            let show = |v: &Vote| {
                v.as_ref()
                    .map(|(k, d, m)| {
                        serde_json::json!({ "property": k, "direction": d.as_str(),
                                            "marks": m.map(Marks::as_str) })
                    })
                    .unwrap_or(serde_json::Value::Null)
            };
            let mut record = if asked_twice {
                serde_json::json!({ "first": show(a), "second": show(b) })
            } else {
                serde_json::json!({ "first": null, "reason": "first_vote_none" })
            };
            let valid = |v: &Vote| v.as_ref().is_none_or(|(k, d, _)| {
                by_key.get(k.as_str()).is_some_and(|p| fits_direction(p, s, closure, *d).is_some())
            });
            let invalid_direction = !valid(a) || !valid(b);
            if invalid_direction {
                // Keep both votes for review; an invalid direction is neither a
                // semantic none nor permission to silently flip the model's answer.
                record["reason"] = serde_json::json!("invalid_direction");
            }
            // 两票选的属性与方向(或都说没有)是否一致
            let agree = match (a, b) {
                (Some((ka, da, _)), Some((kb, db, _))) => ka == kb && da == db,
                (None, None) => true,
                _ => false,
            };
            if !agree || invalid_direction {
                phrase_bindings::decide(
                    pool,
                    kb_id,
                    s,
                    Decision {
                        relation_type_id: None,
                        direction: None,
                        status: "undecided",
                        votes: &record,
                        decided_by: "agent",
                        basis: Some(basis),
                        marks: None,
                        marks_asked: false,
                    },
                )
                .await?;
                undecided += 1;
                continue;
            }
            // 属性是状态时,两票还说一刻标哪一端(#966):说了同一个值才写下它。没说、或说得
            // 不一样,绑定照绑、这一格空着,记下问过——不再问,列进对齐队列等人(0053 修订
            // 2026-09-27)。从前没说的算没答到,模型一直只答三格时每轮重问、永远绑不上。
            // 事件与恒常不问这一格
            let state = a
                .as_ref()
                .and_then(|(k, _, _)| by_key.get(k.as_str()))
                .is_some_and(|p| p.temporal == "state");
            let marks = match (a, b) {
                (Some((_, _, ma)), Some((_, _, mb))) if state && ma == mb => *ma,
                _ => None,
            };
            match a
                .as_ref()
                .and_then(|(k, d, _)| by_key.get(k.as_str()).map(|p| (p, *d)))
            {
                Some((p, d)) => {
                    if phrase_bindings::decide(
                        pool,
                        kb_id,
                        s,
                        Decision {
                            relation_type_id: Some(p.id),
                            direction: Some(d.as_str()),
                            status: "bound",
                            votes: &record,
                            decided_by: "agent",
                            basis: Some(basis),
                            marks: marks.map(Marks::as_str),
                            marks_asked: state,
                        },
                    )
                    .await?
                    {
                        bound += 1;
                        if state && marks.is_none() {
                            unsettled += 1;
                        }
                    }
                }
                None => {
                    if phrase_bindings::decide(
                        pool,
                        kb_id,
                        s,
                        Decision {
                            relation_type_id: None,
                            direction: None,
                            status: "none",
                            votes: &record,
                            decided_by: "agent",
                            basis: Some(basis),
                            marks: None,
                            marks_asked: false,
                        },
                    )
                    .await?
                    {
                        none += 1;
                    }
                }
            }
        }

                Ok::<_, anyhow::Error>((
                    (bound, none, undecided, skipped, failed, unanswered),
                    (marked, unsettled),
                ))
            })
            .collect();
        let mut results = futures_util::stream::iter(futures).buffer_unordered(PARALLEL_BATCHES);
        while let Some(r) = results.next().await {
            let ((b, n, u, sk, f, un), (m, us)) = r?;
            bound += b;
            none += n;
            undecided += u;
            skipped += sk;
            failed += f;
            unanswered += un;
            marked += m;
            unsettled += us;
        }
    }
    // Old invalid agent bindings have matching fingerprints, so explicitly retry
    // them above. If the model fails, structural invalidity still cannot support
    // their typed rows: keep the old votes in an undecided result for a person.
    // Read again so a person who decided during the request remains protected.
    let repair: Vec<_> = todo
        .iter()
        .copied()
        .filter(|s| {
            existing
                .get(&s.key())
                .is_some_and(|b| invalid_agent_direction(b, s, &props, &closure))
        })
        .collect();
    if !repair.is_empty() {
        let now: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
            .await?
            .into_iter()
            .map(|b| (b.key(), b))
            .collect();
        for s in repair {
            let Some(b) = now.get(&s.key()) else {
                continue;
            };
            if !invalid_agent_direction(b, s, &props, &closure) {
                continue;
            }
            let previous: Option<serde_json::Value> = sqlx::query_scalar(
                "SELECT votes FROM phrase_bindings WHERE kb_id=$1 AND phrase=$2
             AND subject_type_id IS NOT DISTINCT FROM $3
             AND object_type_id IS NOT DISTINCT FROM $4 AND object_is_value=$5",
            )
            .bind(kb_id)
            .bind(&s.phrase)
            .bind(s.subject_type_id)
            .bind(s.object_type_id)
            .bind(s.object_is_value)
            .fetch_optional(pool)
            .await?;
            let Some(previous) = previous else {
                continue;
            };
            if phrase_bindings::decide(
                pool,
                kb_id,
                s,
                Decision {
                    relation_type_id: None,
                    direction: None,
                    status: "undecided",
                    votes: &serde_json::json!({"reason":"invalid_direction", "previous":previous,
                                      "previous_decided_at":b.decided_at}),
                    decided_by: "agent",
                    basis: Some(&considered[&s.key()].1),
                    marks: None,
                    marks_asked: false,
                },
            )
            .await?
            {
                undecided += 1;
            }
        }
    }
    tracing::info!(%kb_id, bound, none, undecided, skipped, failed, unanswered, marked, unsettled, "短语对齐完成");
    if unanswered > 0 {
        tracing::warn!(%kb_id, unanswered, "短语对齐有签名模型没答到,这些签名这轮没有结论");
    }
    // 提规则(0044 决定 3 第五片):本轮刚判过的签名,和带类别词的东西,问模型「这种形状
    // 还蕴含什么」。只问本轮判过的:指纹没变的形状上一轮已经问过,答案(提案或代理驳回)
    // 还在 implication_rules 里;指纹变了它就在 todo 里,自然再问
    {
        let decided_now: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
            .await?
            .into_iter()
            .map(|b| (b.key(), b))
            .collect();
        let kind_words = utopia_store::type_bindings::signatures(pool, kb_id).await?;
        let existing_rules = utopia_store::implication_rules::list(pool, kb_id, None).await?;
        let asked_kind: HashSet<&str> = existing_rules
            .iter()
            .filter(|r| r.trigger == "kind_word")
            .map(|r| r.phrase.as_str())
            .collect();
        let mut asks: Vec<crate::implication::RuleAsk<'_>> = Vec::new();
        for s in &todo {
            // 只补问了 marks 的没有重判:指纹没变,它的规则上一轮问过
            if marks_only.contains_key(&s.key()) {
                continue;
            }
            let Some(b) = decided_now.get(&s.key()) else {
                continue;
            };
            // 只问绑上的签名:判「无」的形状一轮 1121 条问下来提了不到 1% 的规则,却占了
            // 提规则一半以上的调用(bench README,2026-09-24);拿不定的等人先定
            if b.status != "bound" {
                continue;
            }
            let (fitting, basis) = &considered[&s.key()];
            let bound_to = b
                .relation_type_id
                .and_then(|id| props.iter().find(|p| p.id == id))
                .map(|p| p.key.as_str());
            asks.push(crate::implication::RuleAsk {
                phrase: Some(s),
                kind_word: None,
                bound_to,
                candidates: fitting
                    .iter()
                    .copied()
                    .filter(|p| Some(p.key.as_str()) != bound_to)
                    .collect(),
                basis,
            });
        }
        // 类别词:每个词问一次;候选是主语能落在它绑到的类(或没声明)的关系属性
        let kind_basis: Vec<String> = kind_words
            .iter()
            .map(|k| {
                phrase_bindings::basis_of(
                    &[],
                    &[],
                    false,
                    &versions
                        .iter()
                        .map(|(id, at)| (*id, *at))
                        .collect::<Vec<_>>(),
                ) + ":"
                    + &k.kind_word
            })
            .collect();
        // 类别词的候选也开短名单:词加例名嵌入后取最近的属性;没有向量时看全部
        let fresh: Vec<&utopia_store::type_bindings::KindWordSignature> = kind_words
            .iter()
            .filter(|k| !asked_kind.contains(k.kind_word.as_str()) && has_modifier(&k.kind_word))
            .collect();
        let kind_short = shortlist_kind_words(state, settings, kb_id, &fresh).await?;
        for (k, basis) in kind_words.iter().zip(kind_basis.iter()) {
            if asked_kind.contains(k.kind_word.as_str()) || !has_modifier(&k.kind_word) {
                continue;
            }
            let mut candidates: Vec<&RelationTypeView> = props
                .iter()
                .filter(|p| p.kind == "relation" || p.kind == "attribute")
                .collect();
            if let Some(keep) = kind_short.get(&k.kind_word) {
                candidates.retain(|p| keep.contains(&p.id));
                candidates.sort_by_key(|p| keep.iter().position(|id| *id == p.id));
            }
            asks.push(crate::implication::RuleAsk {
                phrase: None,
                kind_word: Some(k),
                bound_to: None,
                candidates,
                basis,
            });
        }
        if !asks.is_empty() {
            match crate::implication::propose_rules(
                state, kb_id, settings, client, &asks, &class_key, &by_key,
            )
            .await
            {
                Ok((proposed, rule_failed)) => {
                    tracing::info!(%kb_id, asked = asks.len(), proposed, failed = rule_failed, "提规则完成");
                    if proposed > 0 {
                        state.emit_review(kb_id);
                    }
                }
                Err(e) => tracing::warn!(%kb_id, error = %e, "提规则失败,下一轮再提"),
            }
        }
    }
    // 绑定定了,视图跟着算:绑上的签名下的陈述成类型化行,绑定变了的行作废(0067)
    let typed = utopia_store::materialize::materialize(pool, kb_id).await?;
    tracing::info!(%kb_id, added = typed.added, merged = typed.merged, retired = typed.retired, "类型化事实按绑定算完");
    if typed.added > 0 || typed.merged > 0 || typed.retired > 0 {
        state.emit_graph(kb_id);
    }
    // 这一轮跑着的时候世界没停:新文档带来新签名,改了的属性、动了的父边让刚判的绑定
    // 过期,本轮没排上的触发也都落在这里。有没试过的新签名、有本轮判完指纹又变了的绑定
    // (请求途中的编辑,#795),就再排一次(从头算一份,新签名换了提示词)。
    // 只看**活着的**签名:端点的类换了,旧签名的行没有陈述可判,它永远「过期」却永远
    // 不可执行——从前 `stale` 把这种孤儿每轮交回来,一条孤儿排一次 job,三轮三次(#807)
    let changed = {
        // **重新加载**,不是拿开跑时的快照比:快照就是判定写下的那份指纹,跟它比永远
        // 相等。模型答着的时候改了定义(#795)、加了父边、来了新文档,只有再读一遍才看得见
        let props = utopia_store::ontology::relation_type_views(pool, kb_id).await?;
        let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
        let closure = closures(classes.iter().map(|c| (c.id, c.parents.as_slice())));
        let versions = phrase_bindings::property_versions(pool, kb_id).await?;
        let sigs = phrase_bindings::signatures(pool, kb_id).await?;
        // 短名单沿用开跑时算的那份:向量没变,名单就没变;变了的签名本轮之后自然再问
        let now_considered = consider(&sigs, &props, &closure, &versions, Some(&short));
        let now: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
            .await?
            .into_iter()
            .map(|b| (b.key(), b))
            .collect();
        sigs.iter().any(|s| match now.get(&s.key()) {
            None => !attempted.contains(&s.key()),
            Some(b) => {
                !settled(b, s, &props, &closure)
                    && b.basis.as_deref() != Some(now_considered[&s.key()].1.as_str())
            }
        })
    };
    // 本轮没判完的(调用失败、回复读不出、模型漏答了几条)自己再排,最多 MAX_REASK 次,
    // 每次多等一会。从前只有失败的批次会再排,读不出的回复解成「零条、零坏」不算失败,
    // 漏答的签名就只能等下一篇文档来排——最后一篇之后没有下一篇,它们就永远没有结论;
    // 而漏答不写任何行,审核队列也看不见(同类别词对齐)
    let unfinished = failed > 0 || unanswered > 0;
    // 对齐收尾:没绑上的形状够多,叫本体代理来看(0061 决定 2)。代理自己跳过提过的,
    // 所以这里只数不筛;一分钟的去抖让连着几篇文档只叫一次
    if !changed && !unfinished {
        let unbound = phrase_bindings::bindings(pool, kb_id)
            .await?
            .iter()
            .filter(|b| matches!(b.status.as_str(), "none" | "undecided"))
            .count();
        if unbound >= crate::ontology_agent::TRIGGER_UNBOUND {
            utopia_store::jobs::enqueue_unless_pending(
                pool,
                "propose_ontology",
                serde_json::json!({ "kb_id": kb_id }),
                std::time::Duration::from_secs(60),
            )
            .await?;
        }
    }
    if changed {
        utopia_store::jobs::enqueue_unless_queued(
            pool,
            "align_phrases",
            serde_json::json!({ "kb_id": kb_id }),
        )
        .await?;
    } else if unfinished && reask < MAX_REASK {
        let delay = std::time::Duration::from_secs(20 * u64::from(reask + 1));
        tracing::info!(%kb_id, failed, unanswered, reask = reask + 1, delay_secs = delay.as_secs(), "短语对齐没判完,稍后再问");
        utopia_store::jobs::enqueue_unless_pending(
            pool,
            "align_phrases",
            serde_json::json!({ "kb_id": kb_id, "reask": reask + 1 }),
            delay,
        )
        .await?;
    } else if unfinished {
        tracing::warn!(%kb_id, failed, unanswered, reask, "短语对齐问了几轮仍没判完,等下一篇文档或本体改动再问");
    }
    Ok(())
}

#[cfg(test)]
#[path = "phrase_alignment_tests.rs"]
mod lifecycle_tests;

#[cfg(test)]
#[path = "phrase_alignment_declared_tests.rs"]
mod declared_tests;

#[cfg(test)]
mod tests {
    #[test]
    fn a_kind_word_that_is_only_a_head_word_has_nothing_to_read() {
        for bare in ["state", "ship", " settlement "] {
            assert!(!has_modifier(bare), "{bare}");
        }
        for readable in [
            "british film",
            "1968",
            "british-governed",
            "英国电影",
            "wine area",
        ] {
            assert!(has_modifier(readable), "{readable}");
        }
    }

    #[test]
    fn signatures_with_the_same_candidates_share_a_batch() {
        // 六条签名、三种候选集,交错着来;每批两条
        let sets: Vec<Vec<u32>> = vec![
            vec![1, 2],
            vec![7, 8],
            vec![],
            vec![2, 1],
            vec![8, 9],
            vec![1, 2, 3],
        ];
        let batches = batch_by_candidates(&sets, 2);
        // 每条签名恰好出现一次
        let mut all: Vec<usize> = batches.iter().flatten().copied().collect();
        all.sort_unstable();
        assert_eq!(all, vec![0, 1, 2, 3, 4, 5]);
        // 候选一样的排在一起,没有候选的在最后
        assert_eq!(batches, vec![vec![0, 3], vec![1, 4], vec![5], vec![2]]);
        // 同样的输入排成同样的批
        assert_eq!(batch_by_candidates(&sets, 2), batches);
        // 一批的候选并集比按次序切的小
        let union = |b: &Vec<usize>| {
            b.iter()
                .flat_map(|i| sets[*i].iter())
                .collect::<HashSet<_>>()
                .len()
        };
        let in_order: usize = [vec![0, 1], vec![2, 3], vec![4, 5]].iter().map(union).sum();
        let grouped: usize = batches.iter().map(union).sum();
        assert!(grouped < in_order, "{grouped} < {in_order}");
    }

    #[test]
    fn a_shortlist_keeps_label_matches_and_fills_by_distance_within_the_fitting_set() {
        let ids: Vec<Uuid> = (0..6).map(|_| Uuid::now_v7()).collect();
        // near 按距离:ids[3] 最近,但不在结构候选里;ids[5] 标签对上,排在最后也留
        let near = vec![ids[3], ids[0], ids[1], ids[2], ids[4], ids[5]];
        let fitting = vec![ids[0], ids[1], ids[2], ids[4], ids[5]];
        let picked = pick_shortlist(&near, &fitting, &[ids[5]], 3);
        assert_eq!(picked, vec![ids[5], ids[0], ids[1]]);
        assert!(label_in_phrase(
            "headquarters location",
            "has its headquarters in"
        ));
        assert!(!label_in_phrase("country", "is based in"));
        assert!(
            !label_in_phrase("in", "is based in"),
            "short words do not count"
        );
    }

    use super::*;

    fn view(kind: &str, domains: Vec<Uuid>, ranges: Vec<Uuid>) -> RelationTypeView {
        RelationTypeView {
            id: Uuid::now_v7(),
            key: "p".into(),
            label: "p".into(),
            temporal: "state".into(),
            functional: false,
            inverse_functional: false,
            is_transitive: false,
            is_symmetric: false,
            is_asymmetric: false,
            is_irreflexive: false,
            inverse_of: None,
            sub_property_of: None,
            builtin: false,
            description: String::new(),
            kind: kind.into(),
            domains,
            ranges,
            datatype: None,
            unit: None,
            qualifiers: Vec::new(),
            usage: 0,
        }
    }

    fn sig(subject: Option<Uuid>, object: Option<Uuid>, value: bool) -> PhraseSignature {
        PhraseSignature {
            phrase: "x".into(),
            subject_type_id: subject,
            subject_type_key: None,
            object_type_id: object,
            object_type_key: None,
            object_is_value: value,
            count: 1,
            examples: Vec::new(),
            quotes: Vec::new(),
            example_statement_ids: Vec::new(),
        }
    }

    /// 域/值域筛候选:声明了的要落在里面(正反都算),没声明的不限,类为空的一端不限
    #[test]
    fn a_property_fits_a_signature_by_its_declared_ends_in_either_direction() {
        let (org, place, person) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
        // 没有父边时闭包为空:每个类只等于它自己,行为与从前一样
        let ok = |p: &RelationTypeView, s: &PhraseSignature| fits(p, s, &Closure::new()).is_some();
        let hq = view("relation", vec![org], vec![place]);
        assert!(ok(&hq, &sig(Some(org), Some(place), false)));
        assert!(ok(&hq, &sig(Some(place), Some(org), false)), "反向也算");
        assert!(!ok(&hq, &sig(Some(person), Some(place), false)));
        assert!(
            !ok(&hq, &sig(None, Some(place), false)),
            "没绑到类的一端不算落在声明的域里"
        );
        let any_to_place = view("relation", vec![], vec![place]);
        assert!(
            ok(&any_to_place, &sig(None, Some(place), false)),
            "没声明的一端接受没绑到类的"
        );
        assert!(!ok(&hq, &sig(Some(org), None, true)), "关系不接字面值");
        let open = view("relation", vec![], vec![]);
        assert!(
            ok(&open, &sig(Some(person), Some(person), false)),
            "没声明就不限"
        );
        let revenue = view("attribute", vec![org], vec![]);
        assert!(ok(&revenue, &sig(Some(org), None, true)));
        assert!(!ok(&revenue, &sig(Some(person), None, true)));
        assert!(
            !ok(&revenue, &sig(Some(org), Some(place), false)),
            "属性只接字面值"
        );
    }
    /// 声明在祖先上的属性经继承命中子类的签名(#807 第一条);依据要能说给模型听
    #[test]
    fn a_property_declared_on_an_ancestor_fits_a_subclass_by_inheritance() {
        let (legal_entity, org, place) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
        let mut closure = Closure::new();
        closure.insert(org, {
            let mut v = vec![org, legal_entity];
            v.sort();
            v
        });
        closure.insert(legal_entity, vec![legal_entity]);
        closure.insert(place, vec![place]);
        let hq = view("relation", vec![legal_entity], vec![place]);
        let fit =
            fits(&hq, &sig(Some(org), Some(place), false), &closure).expect("fits via parent");
        assert_eq!(
            fit.via,
            vec![(legal_entity, org)],
            "the basis names the declared ancestor and the class"
        );
        let direct =
            fits(&hq, &sig(Some(legal_entity), Some(place), false), &closure).expect("direct");
        assert!(direct.via.is_empty(), "a direct hit needs no explanation");
        assert!(
            fits(&hq, &sig(Some(place), Some(org), false), &closure).is_some(),
            "reverse direction walks the hierarchy too"
        );
        assert!(
            fits(&hq, &sig(Some(org), Some(place), false), &Closure::new()).is_none(),
            "without the parent edge the property is not a candidate"
        );
    }

    #[test]
    fn a_selected_direction_respects_inheritance_unknown_types_and_literal_shape() {
        let (parent, child, place) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
        let closure = closures([(parent, &[][..]), (child, &[parent][..]), (place, &[][..])]);
        let relation = view("relation", vec![parent], vec![place]);
        let attribute = view("attribute", vec![parent], vec![]);
        let open = view("relation", vec![], vec![]);
        let any_to_place = view("relation", vec![], vec![place]);
        for (p, s, allowed) in [
            (
                &relation,
                sig(Some(child), Some(place), false),
                [true, false],
            ),
            (
                &relation,
                sig(Some(place), Some(child), false),
                [false, true],
            ),
            (&relation, sig(None, Some(place), false), [false, false]),
            (&any_to_place, sig(None, Some(place), false), [true, false]),
            (&any_to_place, sig(Some(place), None, false), [false, true]),
            (&open, sig(None, None, false), [true, true]),
            (&attribute, sig(Some(child), None, true), [true, false]),
            (
                &attribute,
                sig(Some(child), Some(place), false),
                [false, false],
            ),
            (&relation, sig(Some(child), None, true), [false, false]),
        ] {
            for (direction, expected) in [Direction::Forward, Direction::Reverse]
                .into_iter()
                .zip(allowed)
            {
                assert_eq!(
                    fits_direction(p, &s, &closure, direction).is_some(),
                    expected
                );
            }
        }
    }

    /// 闭包:多继承与菱形,每个祖先只出现一次,且含自己
    #[test]
    fn closures_walk_the_hierarchy_once_per_ancestor() {
        let (thing, agent, legal, org) = (
            Uuid::now_v7(),
            Uuid::now_v7(),
            Uuid::now_v7(),
            Uuid::now_v7(),
        );
        // org ⊂ agent ⊂ thing 且 org ⊂ legal ⊂ thing:菱形
        let (a, l, o) = ([thing], [thing], [agent, legal]);
        let c = closures([
            (thing, &[][..]),
            (agent, &a[..]),
            (legal, &l[..]),
            (org, &o[..]),
        ]);
        let mut expect = vec![org, agent, legal, thing];
        expect.sort();
        assert_eq!(c[&org], expect);
        assert_eq!(c[&thing], vec![thing]);
    }
}