Skip to content

World's first open-source enterprise world model.

92.8 KB
Raw Blame
//! 账本 → RDF(0020)。
//!
//! 读的人不是另一个 Utopia,是一个手里有三元组库、要问「这个结论凭什么」的人。
//! 所以导出的内容是**区间与出处**,不只是当下的那些边——一份读起来干净自信、
//! 却没说其中一半在三月被撤回过的图,比没有导出更坏。
//!
//! 三件事定了这份文件的形状:
//!
//! 1. **导入来的类和关系留着原 IRI**(`entity_types.iri` / `relation_types.iri`)。
//!    schema.org 的库导出去还是 `schema:Organization`,对面手里的词汇表对得上
//! 2. **区间挂在具体化语句上**,不是挂在三元组上。RDF-star 更自然但多数消费者
//!    还读不了,命名图在 Turtle 里根本没有——一份打不开的文件不叫导出
//! 3. **有标准词就不自造**:`prov:invalidatedAtTime` 说的正是我们记录轴上那件事,
//!    另起一个私名只会把一个大家都认识的概念藏起来

use std::io::Write;
use std::sync::{Arc, Mutex};

use chrono::{DateTime, Utc};
use oxrdf::vocab::{rdf, rdfs, xsd};
use oxrdf::{Literal, NamedNode, Term, TripleRef};
use utopia_store::export::{
    ExportAxiomViolation, ExportClass, ExportDerived, ExportDocument, ExportEntity, ExportFact,
    ExportFactConflict, ExportRelation,
};
use uuid::Uuid;

const OWL: &str = "http://www.w3.org/2002/07/owl#";
const PROV: &str = "http://www.w3.org/ns/prov#";
const SCHEMA: &str = "https://schema.org/";
/// 没有标准词的那几样才落在这里:置信度、派生标记、模型原话。
///
/// **URN 而不是 http://**:域名还没定,而一个词汇表 IRI 一旦发出去就不该再改。
/// 指向一个我们并不提供的地址,比指向一个不承诺解引用的 URN 更糟
const UTOPIA: &str = "urn:utopia:ns:";

fn nn(iri: impl Into<String>) -> NamedNode {
    // 拼出来的 IRI 全部来自 uuid / 本体 key / 配置里的 base,越界的字符在
    // `Names::new` 就挡掉了;这里再失败只能是 bug,不该把整份导出变成 500
    NamedNode::new(iri.into()).expect("导出 IRI 必须合法")
}

fn owl(term: &str) -> NamedNode {
    nn(format!("{OWL}{term}"))
}
fn prov(term: &str) -> NamedNode {
    nn(format!("{PROV}{term}"))
}
fn schema(term: &str) -> NamedNode {
    nn(format!("{SCHEMA}{term}"))
}
fn utopia(term: &str) -> NamedNode {
    nn(format!("{UTOPIA}{term}"))
}

/// 这份导出里的 IRI 怎么造。
///
/// 缺省是 URN:`urn:utopia:kb:{kb}:entity:{uuid}`。**稳定优先于可解引用**——
/// 同一个库隔一年再导一次,两份文件必须对得上;而一个自部署的实例并不知道
/// 自己对外的地址是什么。按请求的 Host 头去造,等于让身份取决于走了哪个反代。
/// 部署方知道自己发布在哪时,`?base=https://…/` 换成 http IRI。
pub struct Names {
    prefix: String,
    sep: char,
}

impl Names {
    pub fn new(kb_id: Uuid, base: Option<&str>) -> Result<Self, String> {
        match base.map(str::trim).filter(|b| !b.is_empty()) {
            Some(base) => {
                if !(base.starts_with("http://") || base.starts_with("https://")) {
                    return Err("`base` must be an http(s) IRI".into());
                }
                if base.contains(['<', '>', '"', '{', '}', '|', '\\', '^', '`', ' ']) {
                    return Err("`base` contains characters that cannot appear in an IRI".into());
                }
                let trimmed = base.trim_end_matches('/');
                Ok(Self {
                    prefix: format!("{trimmed}/kb/{kb_id}/"),
                    sep: '/',
                })
            }
            None => Ok(Self {
                prefix: format!("urn:utopia:kb:{kb_id}:"),
                sep: ':',
            }),
        }
    }

    fn mint(&self, kind: &str, id: &str) -> NamedNode {
        nn(format!("{}{kind}{}{id}", self.prefix, self.sep))
    }

    pub fn entity(&self, id: Uuid) -> NamedNode {
        self.mint("entity", &id.to_string())
    }
    pub fn fact(&self, id: Uuid) -> NamedNode {
        self.mint("fact", &id.to_string())
    }
    pub fn derived(&self, id: Uuid) -> NamedNode {
        self.mint("derived", &id.to_string())
    }
    pub fn document(&self, id: Uuid) -> NamedNode {
        self.mint("document", &id.to_string())
    }
    pub fn rule(&self, id: Uuid) -> NamedNode {
        self.mint("rule", &id.to_string())
    }
    /// 事实争议(0062):`…:conflict:{uuid}`
    pub fn fact_conflict(&self, id: Uuid) -> NamedNode {
        self.mint("conflict", &id.to_string())
    }
    /// 公理违规发现(0062):`…:violation:{uuid}`
    pub fn axiom_violation(&self, id: Uuid) -> NamedNode {
        self.mint("violation", &id.to_string())
    }
    /// 本体自己长出来的类/关系用 **key** 而不是 uuid:key 是这个库内部就在用的
    /// 标识(`UNIQUE (kb_id, key)`,抽取提示词和 API 用的都是它),文件因此读得懂。
    /// 导入来的一律用原 IRI
    pub fn class(&self, c: &ExportClass) -> NamedNode {
        match c.iri.as_deref() {
            Some(iri) => NamedNode::new(iri).unwrap_or_else(|_| self.mint("class", &c.key)),
            None => self.mint("class", &c.key),
        }
    }
    pub fn relation(&self, r: &ExportRelation) -> NamedNode {
        match r.iri.as_deref() {
            Some(iri) => NamedNode::new(iri).unwrap_or_else(|_| self.mint("relation", &r.key)),
            None => self.mint("relation", &r.key),
        }
    }
}

/// 序列化器写进来的地方。写完一页就把攒下的字节取走发给客户端——
/// 几十万条事实不能先在内存里拼成一整个 String
#[derive(Clone, Default)]
pub struct SharedBuf(Arc<Mutex<Vec<u8>>>);

impl SharedBuf {
    pub fn take(&self) -> Vec<u8> {
        let mut guard = self.0.lock().expect("导出缓冲区被毒化");
        std::mem::take(&mut *guard)
    }
}

impl Write for SharedBuf {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        self.0
            .lock()
            .expect("导出缓冲区被毒化")
            .extend_from_slice(buf);
        Ok(buf.len())
    }
    fn flush(&mut self) -> std::io::Result<()> {
        Ok(())
    }
}

/// 两种格式共用同一套三元组,只是落笔不同——`oxrdfio` 把两个序列化器收在
/// 同一个类型后面,所以这里没有分支。
pub struct Sink(oxrdfio::WriterQuadSerializer<SharedBuf>);

/// 前缀表。Turtle 里它决定文件读起来是 `schema:Organization` 还是一长串尖括号
const PREFIXES: [(&str, &str); 6] = [
    ("rdf", "http://www.w3.org/1999/02/22-rdf-syntax-ns#"),
    ("rdfs", "http://www.w3.org/2000/01/rdf-schema#"),
    ("owl", OWL),
    ("xsd", "http://www.w3.org/2001/XMLSchema#"),
    ("prov", PROV),
    ("schema", SCHEMA),
];

impl Sink {
    pub fn new(format: Format, buf: SharedBuf) -> Self {
        let mut s = oxrdfio::RdfSerializer::from_format(format.rdf_format());
        for (p, iri) in PREFIXES {
            s = s.with_prefix(p, iri).expect("前缀表是常量,不该解析失败");
        }
        s = s
            .with_prefix("utopia", UTOPIA)
            .expect("前缀表是常量,不该解析失败");
        Sink(s.for_writer(buf))
    }

    fn triple(&mut self, t: TripleRef<'_>) -> std::io::Result<()> {
        self.0
            .serialize_quad(t.in_graph(oxrdf::GraphNameRef::DefaultGraph))
    }

    /// `s p o`,o 是资源。
    fn r(&mut self, s: &NamedNode, p: &NamedNode, o: &NamedNode) -> std::io::Result<()> {
        self.triple(TripleRef::new(s.as_ref(), p.as_ref(), o.as_ref()))
    }

    /// `s p o`,o 是字面值。
    fn l(&mut self, s: &NamedNode, p: &NamedNode, o: &Literal) -> std::io::Result<()> {
        self.triple(TripleRef::new(s.as_ref(), p.as_ref(), o.as_ref()))
    }

    pub fn finish(self) -> std::io::Result<()> {
        self.0.finish().map(|_| ())
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Format {
    Turtle,
    JsonLd,
}

impl Format {
    fn rdf_format(self) -> oxrdfio::RdfFormat {
        match self {
            Format::Turtle => oxrdfio::RdfFormat::Turtle,
            // streaming profile:按主语一组一组往外写,不在内存里攒出整个文档。
            // 导出是这个仓库里唯一一处「一次输出可能比库还大」的地方
            Format::JsonLd => oxrdfio::RdfFormat::JsonLd {
                profile: oxrdfio::JsonLdProfile::Streaming.into(),
            },
        }
    }

    pub fn parse(raw: Option<&str>) -> Option<Self> {
        match raw.unwrap_or("turtle").trim().to_ascii_lowercase().as_str() {
            "turtle" | "ttl" => Some(Format::Turtle),
            "jsonld" | "json-ld" | "json" => Some(Format::JsonLd),
            _ => None,
        }
    }
    pub fn content_type(self) -> &'static str {
        match self {
            Format::Turtle => "text/turtle; charset=utf-8",
            Format::JsonLd => "application/ld+json",
        }
    }
    pub fn extension(self) -> &'static str {
        match self {
            Format::Turtle => "ttl",
            Format::JsonLd => "jsonld",
        }
    }
}

fn dt(at: DateTime<Utc>) -> Literal {
    Literal::new_typed_literal(
        at.to_rfc3339_opts(chrono::SecondsFormat::AutoSi, true),
        xsd::DATE_TIME,
    )
}

/// 世界时间按**当时量到的精度**落字面值:只知道年份就写 `xsd:gYear`。
/// 一律写成 `xsd:date` 等于替账本补上它从来没有过的确定性
fn world_time(at: DateTime<Utc>, precision: Option<&str>) -> Literal {
    let iso = at.format("%Y-%m-%d").to_string();
    match precision {
        Some("year") => Literal::new_typed_literal(iso[..4].to_string(), xsd::G_YEAR),
        Some("month") => Literal::new_typed_literal(iso[..7].to_string(), xsd::G_YEAR_MONTH),
        // 小时以下(0024):xsd:dateTime 说不出「到分为止」,精度由 emit_validity 另写一条
        Some("hour" | "minute" | "second") => Literal::new_typed_literal(
            at.to_rfc3339_opts(chrono::SecondsFormat::Secs, true),
            xsd::DATE_TIME,
        ),
        _ => Literal::new_typed_literal(iso, xsd::DATE),
    }
}

/// 小时以下的精度:XSD 的类型说不出来,另写一条 `utopia:*Precision`。日期粒度不用——
/// gYear / gYearMonth / date 本身就是精度
fn sub_day(precision: Option<&str>) -> Option<&str> {
    precision.filter(|p| matches!(*p, "hour" | "minute" | "second"))
}

fn text(s: impl Into<String>) -> Literal {
    Literal::new_simple_literal(s.into())
}

fn confidence(c: f32) -> Literal {
    Literal::new_typed_literal(format!("{c:.2}"), xsd::DECIMAL)
}

fn flag(b: bool) -> Literal {
    Literal::new_typed_literal(if b { "true" } else { "false" }, xsd::BOOLEAN)
}

/// 一次导出里要反复查的东西:类与关系的 IRI、属性的值域。
pub struct Vocabulary {
    pub classes: Vec<(Uuid, NamedNode)>,
    pub relations: Vec<(Uuid, NamedNode, Option<String>, Option<String>)>,
}

impl Vocabulary {
    pub fn class(&self, id: Uuid) -> Option<&NamedNode> {
        self.classes.iter().find(|(i, _)| *i == id).map(|(_, n)| n)
    }
    pub fn relation(&self, id: Uuid) -> Option<&NamedNode> {
        self.relations
            .iter()
            .find(|(i, _, _, _)| *i == id)
            .map(|(_, n, _, _)| n)
    }
    /// (datatype, unit)
    fn literal_shape(&self, id: Uuid) -> (Option<&str>, Option<&str>) {
        self.relations
            .iter()
            .find(|(i, _, _, _)| *i == id)
            .map(|(_, _, d, u)| (d.as_deref(), u.as_deref()))
            .unwrap_or((None, None))
    }
}

pub fn vocabulary(
    names: &Names,
    classes: &[ExportClass],
    relations: &[ExportRelation],
) -> Vocabulary {
    Vocabulary {
        classes: classes.iter().map(|c| (c.id, names.class(c))).collect(),
        relations: relations
            .iter()
            .map(|r| (r.id, names.relation(r), r.datatype.clone(), r.unit.clone()))
            .collect(),
    }
}

pub fn emit_class(sink: &mut Sink, vocab: &Vocabulary, c: &ExportClass) -> std::io::Result<()> {
    let iri = match vocab.class(c.id) {
        Some(n) => n.clone(),
        None => return Ok(()),
    };
    sink.r(&iri, &nn(rdf::TYPE.as_str()), &owl("Class"))?;
    sink.l(&iri, &nn(rdfs::LABEL.as_str()), &text(c.label.clone()))?;
    if !c.description.is_empty() {
        sink.l(
            &iri,
            &nn(rdfs::COMMENT.as_str()),
            &text(c.description.clone()),
        )?;
    }
    for parent in &c.parents {
        if let Some(p) = vocab.class(*parent) {
            let p = p.clone();
            sink.r(&iri, &nn(rdfs::SUB_CLASS_OF.as_str()), &p)?;
        }
    }
    for other in &c.disjoint {
        if let Some(o) = vocab.class(*other) {
            let o = o.clone();
            sink.r(&iri, &owl("disjointWith"), &o)?;
        }
    }
    Ok(())
}

pub fn emit_relation(
    sink: &mut Sink,
    vocab: &Vocabulary,
    r: &ExportRelation,
) -> std::io::Result<()> {
    let iri = match vocab.relation(r.id) {
        Some(n) => n.clone(),
        None => return Ok(()),
    };
    let kind = if r.kind == "attribute" {
        owl("DatatypeProperty")
    } else {
        owl("ObjectProperty")
    };
    sink.r(&iri, &nn(rdf::TYPE.as_str()), &kind)?;
    sink.l(&iri, &nn(rdfs::LABEL.as_str()), &text(r.label.clone()))?;
    if !r.description.is_empty() {
        sink.l(
            &iri,
            &nn(rdfs::COMMENT.as_str()),
            &text(r.description.clone()),
        )?;
    }
    // 公理照抄,一条不落:一致性检查就是按它们跑的,读的人要能自己复算
    for (on, term) in [
        (r.functional, "FunctionalProperty"),
        (r.inverse_functional, "InverseFunctionalProperty"),
        (r.is_transitive, "TransitiveProperty"),
        (r.is_symmetric, "SymmetricProperty"),
        (r.is_asymmetric, "AsymmetricProperty"),
        (r.is_irreflexive, "IrreflexiveProperty"),
    ] {
        if on {
            sink.r(&iri, &nn(rdf::TYPE.as_str()), &owl(term))?;
        }
    }
    // 只复制已声明的边;不补反向声明或传递闭包,目标也只在本库词汇表中找。
    for (target, predicate) in [
        (r.inverse_of, owl("inverseOf")),
        (r.sub_property_of, nn(rdfs::SUB_PROPERTY_OF.as_str())),
    ] {
        if let Some(target) = target.and_then(|id| vocab.relation(id)) {
            sink.r(&iri, &predicate, target)?;
        }
    }
    // 时间语义也照抄(0031):一个 event 谓词的事实两端是同一刻,一个 eternal 谓词的
    // 事实没有日期——读的人不看这一条,会把前者读成一天的状态、后者读成从不知何时起。
    // `state` 也写:导入把「没写」读成「不动」,不写它,改回 state 的关系重导入后还是 event
    sink.l(&iri, &utopia("temporal"), &text(r.temporal.clone()))?;
    for d in &r.domains {
        if let Some(c) = vocab.class(*d) {
            let c = c.clone();
            sink.r(&iri, &nn(rdfs::DOMAIN.as_str()), &c)?;
        }
    }
    for g in &r.ranges {
        if let Some(c) = vocab.class(*g) {
            let c = c.clone();
            sink.r(&iri, &nn(rdfs::RANGE.as_str()), &c)?;
        }
    }
    if let Some(unit) = &r.unit {
        sink.l(&iri, &utopia("unit"), &text(unit.clone()))?;
    }
    Ok(())
}

pub fn emit_entity(
    sink: &mut Sink,
    names: &Names,
    vocab: &Vocabulary,
    e: &ExportEntity,
) -> std::io::Result<()> {
    let iri = names.entity(e.id);
    sink.l(
        &iri,
        &nn(rdfs::LABEL.as_str()),
        &text(e.canonical_name.clone()),
    )?;
    // 类型可以没有(0009):没判出来就不写,而不是补一个 owl:Thing 充数
    if let Some(t) = e.type_id.and_then(|t| vocab.class(t)) {
        let t = t.clone();
        sink.r(&iri, &nn(rdf::TYPE.as_str()), &t)?;
    }
    Ok(())
}

pub fn emit_document(sink: &mut Sink, names: &Names, d: &ExportDocument) -> std::io::Result<()> {
    let iri = names.document(d.id);
    sink.r(&iri, &nn(rdf::TYPE.as_str()), &prov("Entity"))?;
    sink.l(&iri, &nn(rdfs::LABEL.as_str()), &text(d.filename.clone()))?;
    if let Some(key) = &d.external_key {
        sink.l(&iri, &utopia("externalKey"), &text(key.clone()))?;
    }
    if let Some(t) = d.doc_time {
        sink.l(&iri, &schema("datePublished"), &world_time(t, Some("day")))?;
    }
    sink.l(&iri, &prov("generatedAtTime"), &dt(d.created_at))?;
    // 删掉的文档仍在文件里:它的事实还挂着它当出处,抹掉出处等于抹掉证据链
    if let Some(t) = d.deleted_at {
        sink.l(&iri, &prov("invalidatedAtTime"), &dt(t))?;
    }
    Ok(())
}

/// 一条事实:具体化语句(必出)+ 现行三元组(只在现在仍持有且仍有效时出)。
pub fn emit_fact(
    sink: &mut Sink,
    names: &Names,
    vocab: &Vocabulary,
    f: &ExportFact,
    now: DateTime<Utc>,
) -> std::io::Result<()> {
    let stmt = names.fact(f.id);
    let subject = names.entity(f.subject_id);
    let predicate = f.predicate_id.and_then(|p| vocab.relation(p)).cloned();
    let object: Option<Term> = match (f.object_id, &f.object_value) {
        (Some(o), _) => Some(names.entity(o).into()),
        (None, Some(v)) => {
            // An unbound statement still has an object; only its datatype is unknown.
            let datatype = f.predicate_id.and_then(|p| vocab.literal_shape(p).0);
            // #821:解析不出来就别写,避免 rdf:object="" 这种空字面量把审计
            // 工具误导成「事实无对象」。老代码的漏洞是 `v.get("value").unwrap_or(v)`
            // 在 `{"summary": ...}` 形状里把整个对象序列化成字面文本(#831)。
            literal_value(v, datatype).map(Term::from)
        }
        _ => None,
    };

    sink.r(&stmt, &nn(rdf::TYPE.as_str()), &nn(rdf::STATEMENT.as_str()))?;
    sink.r(&stmt, &nn(rdf::SUBJECT.as_str()), &subject)?;
    match (&predicate, &f.surface_predicate) {
        (Some(p), _) => sink.r(&stmt, &nn(rdf::PREDICATE.as_str()), p)?,
        // 本体没接住这条关系(0010):**不造一个谓词**。原话作为字面值留在这里,
        // 读的人看得见「系统听见的是这个词,而词汇表里没有它」
        (None, Some(word)) => sink.l(&stmt, &utopia("proposedPredicate"), &text(word.clone()))?,
        (None, None) => {}
    }
    if let Some(o) = &object {
        sink.triple(TripleRef::new(stmt.as_ref(), rdf::OBJECT, o.as_ref()))?;
    }
    // 只相对一件事给出的值(「触发日后 45 天」,#681 §4):字面量是原文,这一行说它不是日期
    if f.object_value.as_ref().is_some_and(is_relative) {
        sink.l(&stmt, &utopia("relativeValue"), &flag(true))?;
    }
    emit_validity(
        sink,
        &stmt,
        f.valid_from,
        f.valid_from_precision.as_deref(),
        f.valid_to,
        f.valid_to_precision.as_deref(),
    )?;
    sink.l(&stmt, &prov("generatedAtTime"), &dt(f.recorded_at))?;
    if let Some(t) = f.invalidated_at {
        sink.l(&stmt, &prov("invalidatedAtTime"), &dt(t))?;
    }
    sink.l(&stmt, &utopia("confidence"), &confidence(f.confidence))?;
    // 规则算出来的(0044 决定 3 第五片):不是文档直接陈述的,审计的人要看得见这一层
    if f.implied {
        sink.l(&stmt, &utopia("implied"), &flag(true))?;
    }
    if let Some(old) = f.supersedes {
        let old = names.fact(old);
        sink.r(&stmt, &utopia("supersedes"), &old)?;
    }
    for doc in &f.documents {
        let d = names.document(*doc);
        sink.r(&stmt, &prov("wasDerivedFrom"), &d)?;
    }
    for quote in &f.quotes {
        sink.l(&stmt, &utopia("quote"), &text(quote.clone()))?;
    }
    // 引文从哪来(0040):审计的人要不问我们就分得清一句原文和一段看图描述(0020)
    for origin in &f.quote_origins {
        sink.l(&stmt, &utopia("evidenceOrigin"), &text(origin.clone()))?;
    }
    // 边上的属性(0037):陈述节点上各多一行,谓词是属性的 IRI,字面量按它的 datatype
    for q in &f.qualifiers {
        let Some(p) = vocab.relation(q.qualifier_type_id) else {
            continue;
        };
        if let Some(v) = &q.value {
            let (datatype, _) = vocab.literal_shape(q.qualifier_type_id);
            // #821 + #831:解析不出来就别写这条边上的属性,别塞个空字面量
            if let Some(lit) = literal_value(v, datatype) {
                sink.l(&stmt, p, &lit)?;
            }
        } else if let Some(e) = q.entity_id {
            sink.r(&stmt, p, &names.entity(e))?;
        }
    }

    // 现行三元组:**仍被持有,且现在仍成立**。区间已闭合或已撤回的不写这一条,
    // 否则一个忽略具体化的消费者会读到「张三现在还管着那个项目」。
    // 「现在成立」按读出来的区间判(0022):没起点的从最早证据起,结束了不知哪天
    // 的到说出它的那份文档为止。规则在 world_axis 里,这里只看投影出来的两端
    let held = f.invalidated_at.is_none();
    let holds_now = f.holds_from.is_some_and(|t| t <= now) && f.holds_to.is_none_or(|t| t > now);
    if held && holds_now {
        if let (Some(p), Some(o)) = (&predicate, &object) {
            sink.triple(TripleRef::new(subject.as_ref(), p.as_ref(), o.as_ref()))?;
        }
    }
    Ok(())
}

/// 派生事实(0002)。**不写现行三元组**:它是推出来的,不是谁断言的;
/// 一个忽略具体化的消费者不该把引擎的结论当成文档里的话
pub fn emit_derived(
    sink: &mut Sink,
    names: &Names,
    vocab: &Vocabulary,
    d: &ExportDerived,
) -> std::io::Result<()> {
    let stmt = names.derived(d.id);
    // 推理活动的身份:公理规则有自己的 id,业务规则用它的。两者都要有一个
    // 稳定的 IRI,否则审计读到一条结论却指不出「凭什么」
    let rule = match (d.rule_id, d.attribute_rule_id) {
        (Some(r), _) => names.rule(r),
        (None, Some(r)) => names.rule(r),
        // 库里的 CHECK 保证不会两个都空;真到了这一步宁可跳过整条
        (None, None) => return Ok(()),
    };
    sink.r(&stmt, &nn(rdf::TYPE.as_str()), &nn(rdf::STATEMENT.as_str()))?;
    sink.r(
        &stmt,
        &nn(rdf::SUBJECT.as_str()),
        &names.entity(d.subject_id),
    )?;
    if let Some(p) = vocab.relation(d.predicate_id).cloned() {
        sink.r(&stmt, &nn(rdf::PREDICATE.as_str()), &p)?;
    }
    // 宾语两条通道,与断言事实同一套:实体走 IRI,字面值结论走字面量(0021)
    match (d.object_id, &d.object_value) {
        (Some(o), _) => sink.r(&stmt, &nn(rdf::OBJECT.as_str()), &names.entity(o))?,
        (None, Some(v)) => {
            let (datatype, _) = vocab.literal_shape(d.predicate_id);
            // #821 + #831:解析不出来就别写这条宾语
            if let Some(lit) = literal_value(v, datatype) {
                sink.l(&stmt, &nn(rdf::OBJECT.as_str()), &lit)?;
            }
        }
        (None, None) => {}
    }
    sink.l(&stmt, &utopia("derived"), &flag(true))?;
    emit_validity(
        sink,
        &stmt,
        d.valid_from,
        d.valid_from_precision.as_deref(),
        d.valid_to,
        d.valid_to_precision.as_deref(),
    )?;
    sink.l(&stmt, &prov("generatedAtTime"), &dt(d.derived_at))?;
    if let Some(t) = d.invalidated_at {
        sink.l(&stmt, &prov("invalidatedAtTime"), &dt(t))?;
    }
    sink.l(&stmt, &utopia("confidence"), &confidence(d.confidence))?;
    sink.r(&stmt, &prov("wasGeneratedBy"), &rule)?;
    sink.r(&rule, &nn(rdf::TYPE.as_str()), &prov("Activity"))?;
    // 规则的家族与身份(0020 的 2026-09-25 revision,#902):读的人不再从标签里猜它来自
    // 哪张表。公理规则再写出种类(闭合枚举)和声明所在的谓词——inverse 与 sub_property
    // 时它不是结论的谓词,从导出的 owl:inverseOf / rdfs:subPropertyOf 反推是有歧义的。
    // 业务规则的条件与表达式不导出:规则原地更新,这个 IRI 担保不了旧结论当时依据的定义
    if d.rule_id.is_some() {
        sink.r(&rule, &nn(rdf::TYPE.as_str()), &utopia("AxiomRule"))?;
        sink.l(&rule, &utopia("axiomKind"), &text(d.rule.clone()))?;
        if let Some(p) = d.rule_predicate.and_then(|p| vocab.relation(p).cloned()) {
            sink.r(&rule, &utopia("declaredOn"), &p)?;
        }
    } else {
        sink.r(&rule, &nn(rdf::TYPE.as_str()), &utopia("BusinessRule"))?;
    }
    // 标签用规则自己的名字(业务规则),公理退回它的种类名——审计读到的是
    // 「Gas-bearing well」而不是「business」
    sink.l(
        &rule,
        &nn(rdfs::LABEL.as_str()),
        &text(d.rule_name.clone().unwrap_or_else(|| d.rule.clone())),
    )?;
    // 前提。审计顺着 prov:used 往下走一步就到断言,再走一步就到句子
    for premise in &d.premises {
        let p = names.fact(*premise);
        sink.r(&stmt, &prov("used"), &p)?;
    }
    for premise in &d.premises_derived {
        let p = names.derived(*premise);
        sink.r(&stmt, &prov("used"), &p)?;
    }
    Ok(())
}

/// 一条事实争议(0062):同一槽位上的两条断言互不相让。
///
/// `status` 照原样给:open 是「还在争」;resolved + `utopia:resolution` 是人的
/// 裁决;`withdrawn` 不是裁决——一边作废了题就没了,`utopia:closedAt` 记的是
/// 作废时刻(0051),不是有人打开过审核页的时刻
pub fn emit_fact_conflict(
    sink: &mut Sink,
    names: &Names,
    c: &ExportFactConflict,
) -> std::io::Result<()> {
    let iri = names.fact_conflict(c.id);
    sink.r(&iri, &nn(rdf::TYPE.as_str()), &utopia("FactConflict"))?;
    // 两席分清方向:压着的断言与新到的那条不是对称的(0062)
    for (pred, fact) in [
        (utopia("priorStatement"), c.old_fact_id),
        (utopia("incomingStatement"), c.new_fact_id),
    ] {
        sink.r(&iri, &pred, &names.fact(fact))?;
    }
    sink.l(&iri, &utopia("reason"), &text(c.reason.clone()))?;
    sink.l(&iri, &utopia("status"), &text(c.status.clone()))?;
    if let Some(r) = &c.resolution {
        sink.l(&iri, &utopia("resolution"), &text(r.clone()))?;
    }
    sink.l(&iri, &prov("generatedAtTime"), &dt(c.created_at))?;
    if let Some(t) = c.resolved_at {
        sink.l(&iri, &utopia("closedAt"), &dt(t))?;
    }
    Ok(())
}

/// 一条公理违规发现(0062)。这是**可变的当前状态**,不是历史:`open` 的意思是
/// 已对账于当前本体——所以判据只连在 open 行上,resolved 的行不假装知道自己是
/// 按哪一版本体结案的
pub fn emit_axiom_violation(
    sink: &mut Sink,
    names: &Names,
    vocab: &Vocabulary,
    v: &ExportAxiomViolation,
) -> std::io::Result<()> {
    let iri = names.axiom_violation(v.id);
    sink.r(&iri, &nn(rdf::TYPE.as_str()), &utopia("AxiomViolation"))?;
    sink.l(&iri, &utopia("kind"), &text(v.kind.clone()))?;
    // self_loop/signature 的左右是同一事实——RDF 集合语义下重发无害,但 Turtle
    // 文件里会是一条重复三元组
    let endpoints: &[Uuid] = if v.left_fact == v.right_fact {
        &[v.left_fact]
    } else {
        &[v.left_fact, v.right_fact]
    };
    for fact in endpoints {
        sink.r(&iri, &utopia("onStatement"), &names.fact(*fact))?;
    }
    // 环是有序的证据链(0054):拍扁成一组无序的 facts,「A→B→C→A」就读不回来了。
    // rdf:List 是 Turtle/JSON-LD 都认的保序结构
    if !v.path.is_empty() {
        let items: Vec<Term> = v.path.iter().map(|f| names.fact(*f).into()).collect();
        let head = emit_list(sink, &items)?;
        sink.triple(TripleRef::new(
            iri.as_ref(),
            utopia("evidencePath").as_ref(),
            head.as_ref(),
        ))?;
    }
    sink.l(&iri, &utopia("status"), &text(v.status.clone()))?;
    if let Some(r) = &v.resolution {
        sink.l(&iri, &utopia("resolution"), &text(r.clone()))?;
    }
    sink.l(&iri, &utopia("detectedAt"), &dt(v.detected_at))?;
    if let Some(t) = v.decided_at {
        sink.l(&iri, &utopia("closedAt"), &dt(t))?;
    }
    // 判据(0062 §4):open = 已对账于当前本体,必然指得回一条关系与一个
    // OWL/rdfs 词。signature 的判据是一对签名,两个词都发(行不记哪一侧破的)。
    // resolved 的行不发——它的判据可能早已不在本体里
    if v.status == "open" {
        for term in v.criterion_terms().unwrap_or(&[]) {
            sink.r(&iri, &utopia("criterion"), &criterion_node(term))?;
        }
        if let Some(rel) = v
            .criterion_predicate
            .and_then(|p| vocab.relation(p))
            .cloned()
        {
            sink.r(&iri, &utopia("onRelation"), &rel)?;
        }
    }
    Ok(())
}

/// `utopia:criterion` 的词项:`criterion_terms` 只产 `owl:`/`rdfs:` 两种,
/// 其余值不可能走到这里(export 侧已经拒导)
fn criterion_node(term: &str) -> NamedNode {
    if let Some(t) = term.strip_prefix("owl:") {
        owl(t)
    } else {
        match term {
            "rdfs:domain" => rdfs::DOMAIN.into(),
            "rdfs:range" => rdfs::RANGE.into(),
            _ => unreachable!("criterion_terms 只产 owl:/rdfs: 词"),
        }
    }
}

/// 一串有序资源写成 rdf:List,返回表头节点(空表返回 rdf:nil)。
/// 从尾往前搭:每个空白节点落地时就知道自己的 rest
fn emit_list(sink: &mut Sink, items: &[Term]) -> std::io::Result<Term> {
    let mut head: Term = nn(rdf::NIL.as_str()).into();
    for item in items.iter().rev() {
        let node = oxrdf::BlankNode::default();
        sink.triple(TripleRef::new(node.as_ref(), rdf::FIRST, item.as_ref()))?;
        sink.triple(TripleRef::new(node.as_ref(), rdf::REST, head.as_ref()))?;
        head = node.into();
    }
    Ok(head)
}

fn emit_validity(
    sink: &mut Sink,
    stmt: &NamedNode,
    from: Option<DateTime<Utc>>,
    from_precision: Option<&str>,
    to: Option<DateTime<Utc>>,
    to_precision: Option<&str>,
) -> std::io::Result<()> {
    if let Some(t) = from {
        sink.l(stmt, &schema("validFrom"), &world_time(t, from_precision))?;
        if let Some(p) = sub_day(from_precision) {
            sink.l(stmt, &utopia("validFromPrecision"), &text(p))?;
        }
    }
    match (to, to_precision) {
        (Some(t), p) => {
            sink.l(stmt, &schema("validThrough"), &world_time(t, p))?;
            if let Some(p) = sub_day(p) {
                sink.l(stmt, &utopia("validThroughPrecision"), &text(p))?;
            }
        }
        // 「结束了,但不知道哪天」——账本专门为它留了一个状态,导出不能把它
        // 压成「至今仍成立」(那正是 valid_to 一列承载两个意思时的老毛病)
        (None, Some("unknown")) => sink.l(stmt, &utopia("endedUnknown"), &flag(true))?,
        (None, _) => {}
    }
    Ok(())
}

/// 值上带着 `"relative": true`:原文只相对一件事给出它,没有日历上的日期
fn is_relative(v: &serde_json::Value) -> bool {
    v.get("relative").and_then(|r| r.as_bool()) == Some(true)
}

/// `{"value": …, "unit": …}` 或 `{"summary": …}` 等情况下抽出字面量。
///
/// **Resolves the text first and returns `None` when nothing resolves.** The
/// audit invariant #821 (`an_absent_object_is_not_an_empty_literal`) says that an
/// absent object should produce no `rdf:object` triple at all; the same principle
/// applies here when the value resolves to nothing — better to omit than to emit
/// a literal whose lexical form is `""`, since that turns into JSON serialisation
/// for an object value and is a parser-puzzle for downstream consumers.
///
/// 相对的值写成普通字符串:`"45 days after the Trigger Date"^^xsd:date` 是个不合法的字面量
fn literal_value(v: &serde_json::Value, datatype: Option<&str>) -> Option<Literal> {
    let (text, prose) = literal_text(v)?;
    if prose || is_relative(v) {
        return Some(Literal::new_simple_literal(text));
    }
    Some(match datatype {
        Some("number") => Literal::new_typed_literal(decimal_text(text), xsd::DECIMAL),
        Some("date") => {
            date_literal(&text).unwrap_or_else(|| Literal::new_typed_literal(text, xsd::DATE))
        }
        Some("bool") => Literal::new_typed_literal(text, xsd::BOOLEAN),
        _ => Literal::new_simple_literal(text),
    })
}

/// JSON 数可以带指数,xsd:decimal 不可以。用已有的精确十进制类型展开文本,
/// 不再过一次 f64,也不舍入;没有指数的写法(包括负零)原样保留。
fn decimal_text(text: String) -> String {
    let Some((coefficient, exponent)) = text.split_once(['e', 'E']) else {
        return text;
    };
    // 归一化后的有限 f64 指数只在这个范围内。其他字符串不一定经过归一化,
    // 不让异常的大指数触发无界分配,也不顺手清洗 BigDecimal 能容忍的下划线等写法。
    let supported_exponent = exponent
        .parse::<i32>()
        .is_ok_and(|exponent| (-324..=308).contains(&exponent));
    let decimal_coefficient = coefficient
        .chars()
        .all(|c| c.is_ascii_digit() || matches!(c, '+' | '-' | '.'));
    if supported_exponent && decimal_coefficient {
        if let Ok(number) = text.parse::<sqlx::types::BigDecimal>() {
            return number.to_plain_string();
        }
    }
    text
}

/// 属性日期保留的是原文,不是世界时间区间。parse_time 会截掉小数秒、把无时区
/// 钟点降到天,所以只在没有钟点时借它判断年/月/日;时钟和时区从原文规范化。
/// 无法识别的文本由调用方沿用原输出;输入校验仍可能接受非日期的钟点文本,
/// 本次不收紧它的规则。年份按字段格式化,不能按四个字符切片;chrono 在扩展
/// 正年份前加的 `+` 也需去掉,因为 XSD 年份不允许正号。
fn date_literal(value: &str) -> Option<Literal> {
    let Some((date, clock)) = value.split_once(['T', ' ']) else {
        let (date, precision) = utopia_extract::parse_time(value)?;
        let (format, datatype) = match precision {
            "year" => ("%Y", xsd::G_YEAR),
            "month" => ("%Y-%m", xsd::G_YEAR_MONTH),
            _ => ("%Y-%m-%d", xsd::DATE),
        };
        let lexical = date.format(format).to_string();
        return Some(Literal::new_typed_literal(
            lexical.trim_start_matches('+'),
            datatype,
        ));
    };
    let date = chrono::NaiveDate::parse_from_str(date, "%Y-%m-%d").ok()?;
    let calendar_date = date.format("%Y-%m-%d").to_string();
    let calendar_date = calendar_date.trim_start_matches('+');
    let (clock, zone) = if let Some(clock) = clock.strip_suffix(['Z', 'z']) {
        (clock, "Z".to_string())
    } else if let Some(index) = clock.find(['+', '-']) {
        let (clock, zone) = clock.split_at(index);
        (clock, xsd_timezone(zone)?)
    } else {
        // XSD 允许没有时区的 dateTime;不能替原文猜一个 UTC。
        (clock, String::new())
    };
    let parts: Vec<&str> = clock.split(':').collect();
    let (hour, minute, second) = match parts.as_slice() {
        [hour] => (*hour, "00", "00"),
        [hour, minute] => (*hour, *minute, "00"),
        [hour, minute, second] => (*hour, *minute, *second),
        _ => return None,
    };
    let (second, fraction) = match second.split_once('.') {
        Some((second, fraction)) => {
            if fraction.is_empty() || !fraction.bytes().all(|b| b.is_ascii_digit()) {
                return None;
            }
            (second, format!(".{fraction}"))
        }
        None => (second, String::new()),
    };
    if ![hour, minute, second]
        .iter()
        .all(|part| !part.is_empty() && part.bytes().all(|b| b.is_ascii_digit()))
    {
        return None;
    }
    let hour = hour.parse().ok()?;
    let minute = minute.parse().ok()?;
    let second = second.parse().ok()?;
    chrono::NaiveTime::from_hms_opt(hour, minute, second)?;
    // dateTime 必须有 HH:MM:SS;补零表示该小时/分钟的起点,类型本身不能表达
    // 「只精确到小时/分钟」。小数秒不交给 chrono,避免超过纳秒的原文被截断。
    let lexical = format!("{calendar_date}T{hour:02}:{minute:02}:{second:02}{fraction}{zone}");
    Some(Literal::new_typed_literal(lexical, xsd::DATE_TIME))
}

/// parse_time 也接受 ±HH 和 ±HHMM,XSD 时区则要求 ±HH:MM。
fn xsd_timezone(zone: &str) -> Option<String> {
    if !zone.is_ascii() {
        return None;
    }
    let normalized = match zone.len() {
        3 => format!("{zone}:00"),
        5 => format!("{}:{}", &zone[..3], &zone[3..]),
        6 if zone.as_bytes()[3] == b':' => zone.to_string(),
        _ => return None,
    };
    let digits = [&normalized[1..3], &normalized[4..6]];
    if !digits
        .iter()
        .all(|part| part.bytes().all(|b| b.is_ascii_digit()))
    {
        return None;
    }
    let hour: u32 = digits[0].parse().ok()?;
    let minute: u32 = digits[1].parse().ok()?;
    if hour > 14 || minute > 59 || (hour == 14 && minute != 0) {
        return None;
    }
    Some(normalized)
}

/// 把事实的 `object_value` 形状抽出可写的字面文本,以及这段文本是不是人写的散文。
///
/// 认得的形态(其它都视作缺值):
/// 1. 直接给字符串 / 数字 / 布尔
/// 2. `{"value": …}`:`value` 是标量就取它
/// 3. `{"summary": …}`:`value` 缺席或为空时才看它(`models.rs` 把两者记作二选一,
///    `api/tools.rs` 也是先 `value` 后 `summary`;这里不另立顺序)
/// 4. `{"class": …}`:规则的分类结论(`reasoning.rs` 写的就是这个形状,五处按键读回)
///
/// 老的行为是 `v.get("value").unwrap_or(v)`:键缺失时把整个对象当作字面值,于是
/// `{"summary": …}` 会被序列化成 `{"summary":"…"}` 这种字面文本(#831)。新行为是先解析成
/// 一段真实文字;解析不到(既不是标量,又没有认得的键)就返回 `None`,调用方就不写
/// `rdf:object` 这条三元组。第二个返回值为 `true` 表示文本来自 `summary` / `class`:
/// 那是给人读的散文或一个类名,不该套属性声明的 `xsd:decimal` / `xsd:date`
fn literal_text(v: &serde_json::Value) -> Option<(String, bool)> {
    match v {
        serde_json::Value::Null => None,
        serde_json::Value::Bool(b) => Some((b.to_string(), false)),
        serde_json::Value::Number(n) => Some((n.to_string(), false)),
        serde_json::Value::String(s) => Some((s.clone(), false)),
        serde_json::Value::Array(_) => None,
        serde_json::Value::Object(map) => {
            if let Some((text, _)) = map.get("value").and_then(literal_text) {
                return Some((text, false));
            }
            for key in ["summary", "class"] {
                if let Some(text) = map.get(key).and_then(|s| s.as_str()) {
                    if !text.is_empty() {
                        return Some((text.to_string(), true));
                    }
                }
            }
            None
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use oxrdf::{NamedNodeRef, Quad};

    fn kb() -> Uuid {
        Uuid::parse_str("01a06dc4-f40a-7013-b09f-1b499e2e7441").unwrap()
    }

    fn id(n: u8) -> Uuid {
        Uuid::from_bytes([n; 16])
    }

    fn at(s: &str) -> DateTime<Utc> {
        s.parse().unwrap()
    }

    fn class(n: u8, key: &str, iri: Option<&str>) -> ExportClass {
        ExportClass {
            id: id(n),
            key: key.into(),
            label: key.into(),
            description: String::new(),
            iri: iri.map(str::to_string),
            parents: vec![],
            disjoint: vec![],
        }
    }

    fn relation(n: u8, key: &str, iri: Option<&str>, kind: &str) -> ExportRelation {
        ExportRelation {
            id: id(n),
            key: key.into(),
            label: key.into(),
            description: String::new(),
            iri: iri.map(str::to_string),
            kind: kind.into(),
            datatype: (kind == "attribute").then(|| "number".to_string()),
            unit: None,
            temporal: "state".into(),
            functional: true,
            inverse_functional: false,
            is_transitive: false,
            is_symmetric: false,
            is_asymmetric: false,
            is_irreflexive: false,
            inverse_of: None,
            sub_property_of: None,
            domains: vec![],
            ranges: vec![],
        }
    }

    fn fact(n: u8) -> ExportFact {
        ExportFact {
            qualifiers: Vec::new(),
            id: id(n),
            subject_id: id(10),
            predicate_id: Some(id(2)),
            surface_predicate: None,
            object_id: Some(id(11)),
            object_value: None,
            valid_from: None,
            valid_from_precision: None,
            valid_to: None,
            valid_to_precision: None,
            // 读出来的区间(0022):没起点就从锚点起,这里让它与记下的时刻同一天
            holds_from: Some(at("2026-01-01T00:00:00Z")),
            holds_to: None,
            recorded_at: at("2026-01-01T00:00:00Z"),
            invalidated_at: None,
            confidence: 0.9,
            implied: false,
            supersedes: None,
            documents: vec![],
            quotes: vec![],
            quote_origins: vec![],
            subject_kb: Some(kb()),
            object_kb: Some(kb()),
            predicate_kb: Some(kb()),
            supersedes_kb: None,
            foreign_document: false,
            foreign_chunk: false,
            subject_merged: false,
            object_merged: false,
        }
    }

    /// 导出一遍再解析回来。**必须解析回来**:断言字符串里有没有某一段,
    /// 证明不了文件语法是否合法;字面文本是否符合 XSD 类型仍须另行断言
    fn export(format: Format, emit: impl FnOnce(&mut Sink, &Names, &Vocabulary)) -> Vec<Quad> {
        let names = Names::new(kb(), None).unwrap();
        let classes = vec![
            class(1, "person", Some("https://schema.org/Person")),
            class(3, "team", None),
        ];
        let relations = vec![
            relation(
                2,
                "works_for",
                Some("https://schema.org/worksFor"),
                "relation",
            ),
            relation(4, "headcount", None, "attribute"),
        ];
        let vocab = vocabulary(&names, &classes, &relations);
        let buf = SharedBuf::default();
        let mut sink = Sink::new(format, buf.clone());
        for c in &classes {
            emit_class(&mut sink, &vocab, c).unwrap();
        }
        for r in &relations {
            emit_relation(&mut sink, &vocab, r).unwrap();
        }
        emit(&mut sink, &names, &vocab);
        sink.finish().unwrap();
        let bytes = buf.take();
        oxrdfio::RdfParser::from_format(match format {
            Format::Turtle => oxrdfio::RdfFormat::Turtle,
            Format::JsonLd => oxrdfio::RdfFormat::JsonLd {
                profile: oxrdfio::JsonLdProfileSet::empty(),
            },
        })
        .for_slice(&bytes)
        .map(|q| q.expect("导出的文件必须解析得回来"))
        .collect()
    }

    fn has(quads: &[Quad], s: &str, p: &str, o: &str) -> bool {
        quads.iter().any(|q| {
            q.subject.to_string() == s && q.predicate.to_string() == format!("<{p}>") && {
                let obj = q.object.to_string();
                obj == o || obj == format!("<{o}>")
            }
        })
    }

    fn objects(quads: &[Quad], s: &str, p: &str) -> Vec<String> {
        quads
            .iter()
            .filter(|q| q.subject.to_string() == s && q.predicate.to_string() == format!("<{p}>"))
            .map(|q| q.object.to_string())
            .collect()
    }

    const STMT: &str = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:fact:05050505-0505-0505-0505-050505050505>";
    const SUBJ: &str = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:entity:0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a>";
    const OBJ: &str = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:entity:0b0b0b0b-0b0b-0b0b-0b0b-0b0b0b0b0b0b>";
    const WORKS_FOR: &str = "https://schema.org/worksFor";

    /// 同一个属性值穿过所有出口;RDF 能解析不代表 XSD 字面文本符合其类型。
    fn assert_attribute_literal_exports(
        value: serde_json::Value,
        datatype: &str,
        expected: Option<(&str, NamedNodeRef<'_>)>,
    ) {
        let mut attribute = fact(5);
        attribute.predicate_id = Some(id(4));
        attribute.object_id = None;
        attribute.object_value = Some(value.clone());
        attribute
            .qualifiers
            .push(utopia_core::models::FactQualifier {
                qualifier_type_id: id(4),
                value: Some(value.clone()),
                ..Default::default()
            });
        let derived = ExportDerived {
            id: id(7),
            subject_id: id(10),
            predicate_id: id(4),
            object_id: None,
            object_value: Some(value.clone()),
            rule_id: None,
            attribute_rule_id: Some(id(9)),
            valid_from: None,
            valid_from_precision: None,
            valid_to: None,
            valid_to_precision: None,
            derived_at: at("2026-02-01T00:00:00Z"),
            invalidated_at: None,
            confidence: 0.9,
            rule: "business".into(),
            rule_predicate: None,
            rule_name: Some("Attribute conclusion".into()),
            premises: vec![id(5)],
            premises_derived: Vec::new(),
            subject_kb: Some(kb()),
            object_kb: None,
            predicate_kb: Some(kb()),
            rule_kb: None,
            attribute_rule_kb: Some(kb()),
            foreign_fact_premise: false,
            foreign_derived_premise: false,
            subject_merged: false,
            object_merged: false,
        };
        let names = Names::new(kb(), None).unwrap();
        let mut property = relation(4, "value", None, "attribute");
        property.datatype = Some(datatype.into());
        let property_iri = names.relation(&property);
        let statement_iri = names.fact(attribute.id).to_string();
        let subject_iri = names.entity(attribute.subject_id).to_string();
        let derived_iri = names.derived(derived.id).to_string();
        for format in [Format::Turtle, Format::JsonLd] {
            let quads = export(format, |sink, names, _| {
                let vocab = vocabulary(names, &[], std::slice::from_ref(&property));
                emit_fact(sink, names, &vocab, &attribute, at("2026-06-01T00:00:00Z")).unwrap();
                emit_derived(sink, names, &vocab, &derived).unwrap();
            });
            for (outlet, subject, predicate) in [
                ("fact", &statement_iri, rdf::OBJECT.as_str()),
                ("current triple", &subject_iri, property_iri.as_str()),
                ("qualifier", &statement_iri, property_iri.as_str()),
                ("derived fact", &derived_iri, rdf::OBJECT.as_str()),
            ] {
                let objects: Vec<_> = quads
                    .iter()
                    .filter(|quad| {
                        quad.subject.to_string() == *subject && quad.predicate.as_str() == predicate
                    })
                    .map(|quad| &quad.object)
                    .collect();
                let context = format!("{outlet}, {format:?}, {datatype}, {value}");
                match expected {
                    Some((lexical, expected_datatype)) => {
                        assert_eq!(objects.len(), 1, "{context}");
                        let Term::Literal(literal) = objects[0] else {
                            panic!("expected a literal: {context}");
                        };
                        assert_eq!(literal.value(), lexical, "{context}");
                        assert_eq!(literal.datatype(), expected_datatype, "{context}");
                    }
                    None => assert!(objects.is_empty(), "unexpected object: {context}"),
                }
            }
        }
    }

    #[test]
    fn normalized_numbers_export_as_decimal_without_exponents() {
        for (input, expected) in [
            (serde_json::json!(0.0000001), "0.0000001"),
            (serde_json::json!("1e-7"), "0.0000001"),
            (serde_json::json!(1e20), "100000000000000000000"),
            (serde_json::json!(-1e-7), "-0.0000001"),
            (serde_json::json!(-1e20), "-100000000000000000000"),
            (serde_json::json!(0), "0.0"),
            (serde_json::json!(-0.0), "-0.0"),
            (serde_json::json!(12.375), "12.375"),
            (serde_json::json!(-12.375), "-12.375"),
            (serde_json::json!(1.25e-7), "0.000000125"),
        ] {
            let normalized = utopia_extract::normalize_attr_value("number", &input).unwrap();
            assert_attribute_literal_exports(
                normalized.clone(),
                "number",
                Some((expected, xsd::DECIMAL)),
            );
            assert_attribute_literal_exports(
                serde_json::json!({"value": normalized}),
                "number",
                Some((expected, xsd::DECIMAL)),
            );
        }
        // 已存的整数不能再经过 f64:这个值超过了双精度能逐个表示整数的范围。
        assert_attribute_literal_exports(
            serde_json::json!({"value": 9_007_199_254_740_993_u64}),
            "number",
            Some(("9007199254740993", xsd::DECIMAL)),
        );
        // 最小次正规数和最大有限数:不能因固定小数位变成零,也不能溢出。
        for (input, expected) in [
            (f64::from_bits(1), format!("0.{}5", "0".repeat(323))),
            (f64::MAX, format!("17976931348623157{}", "0".repeat(292))),
        ] {
            let normalized =
                utopia_extract::normalize_attr_value("number", &serde_json::json!(input)).unwrap();
            assert_attribute_literal_exports(normalized, "number", Some((&expected, xsd::DECIMAL)));
        }
    }

    #[test]
    fn normalized_dates_export_their_precision_and_original_clock() {
        for (input, expected, datatype) in [
            ("2024", "2024", xsd::G_YEAR),
            ("2024-07", "2024-07", xsd::G_YEAR_MONTH),
            ("2024-07-15", "2024-07-15", xsd::DATE),
            (
                "2024-07-15T14:32:07Z",
                "2024-07-15T14:32:07Z",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15T14:32:07+08:00",
                "2024-07-15T14:32:07+08:00",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15T14:32:07.382-05:30",
                "2024-07-15T14:32:07.382-05:30",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15T14:32:07.123456789012Z",
                "2024-07-15T14:32:07.123456789012Z",
                xsd::DATE_TIME,
            ),
            ("2024-07-15T14Z", "2024-07-15T14:00:00Z", xsd::DATE_TIME),
            (
                "2024-07-15T14+08:00",
                "2024-07-15T14:00:00+08:00",
                xsd::DATE_TIME,
            ),
            ("2024-07-15T14:32Z", "2024-07-15T14:32:00Z", xsd::DATE_TIME),
            (
                "2024-07-15T14:32+08:00",
                "2024-07-15T14:32:00+08:00",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15T14:32+0800",
                "2024-07-15T14:32:00+08:00",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15T14+08",
                "2024-07-15T14:00:00+08:00",
                xsd::DATE_TIME,
            ),
            ("2024-07-15T14:32z", "2024-07-15T14:32:00Z", xsd::DATE_TIME),
            (
                "2024-07-15T14+14",
                "2024-07-15T14:00:00+14:00",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15T14-14",
                "2024-07-15T14:00:00-14:00",
                xsd::DATE_TIME,
            ),
            (
                "2024-07-15 14:32+08:00",
                "2024-07-15T14:32:00+08:00",
                xsd::DATE_TIME,
            ),
            ("2024-07-15T14", "2024-07-15T14:00:00", xsd::DATE_TIME),
            ("2024-07-15T14:32", "2024-07-15T14:32:00", xsd::DATE_TIME),
            (
                "2024-07-15T14:32:07.382",
                "2024-07-15T14:32:07.382",
                xsd::DATE_TIME,
            ),
        ] {
            let normalized =
                utopia_extract::normalize_attr_value("date", &serde_json::json!(input)).unwrap();
            assert_attribute_literal_exports(
                normalized.clone(),
                "date",
                Some((expected, datatype)),
            );
            assert_attribute_literal_exports(
                serde_json::json!({"value": normalized}),
                "date",
                Some((expected, datatype)),
            );
        }
    }

    #[test]
    fn attribute_calendar_years_are_not_cut_to_four_characters() {
        for (input, expected, datatype) in [
            ("-0001-07", "-0001-07", xsd::G_YEAR_MONTH),
            ("-0001-07-15", "-0001-07-15", xsd::DATE),
            ("+10000-07", "10000-07", xsd::G_YEAR_MONTH),
            ("+10000-07-15", "10000-07-15", xsd::DATE),
            (
                "+10000-07-15T14:32:07.382Z",
                "10000-07-15T14:32:07.382Z",
                xsd::DATE_TIME,
            ),
        ] {
            let normalized =
                utopia_extract::normalize_attr_value("date", &serde_json::json!(input)).unwrap();
            assert_attribute_literal_exports(normalized, "date", Some((expected, datatype)));
        }
    }

    #[test]
    fn typed_attributes_keep_value_precedence_prose_and_missing_objects() {
        for (value, datatype, expected) in [
            (
                serde_json::json!({"value": 12.5, "summary": "estimate"}),
                "number",
                Some(("12.5", xsd::DECIMAL)),
            ),
            (
                serde_json::json!({"value": "2024", "summary": "sometime in 2024"}),
                "date",
                Some(("2024", xsd::G_YEAR)),
            ),
            (
                serde_json::json!({"value": 0, "summary": ""}),
                "number",
                Some(("0", xsd::DECIMAL)),
            ),
            (
                serde_json::json!({"summary": "before the merge"}),
                "date",
                Some(("before the merge", xsd::STRING)),
            ),
            (
                serde_json::json!({"value": null, "summary": "not specified"}),
                "number",
                Some(("not specified", xsd::STRING)),
            ),
            (
                serde_json::json!({"class": "gas_well"}),
                "number",
                Some(("gas_well", xsd::STRING)),
            ),
            (
                serde_json::json!({"value": "45 days after the Trigger Date", "relative": true}),
                "date",
                Some(("45 days after the Trigger Date", xsd::STRING)),
            ),
            (serde_json::json!({"value": null}), "date", None),
            (serde_json::json!({"confidence": 0.9}), "number", None),
            (
                serde_json::json!({"summary": "", "class": ""}),
                "date",
                None,
            ),
            (serde_json::Value::Null, "number", None),
        ] {
            assert_attribute_literal_exports(value, datatype, expected);
        }
    }

    #[test]
    fn unbound_literal_objects_survive_both_formats() {
        for value in [
            serde_json::json!({"value": "待复检"}),
            serde_json::json!({"value": "quote: \" and slash: \\"}),
            serde_json::json!({"value": ""}),
            serde_json::json!({"value": 0}),
            serde_json::json!({"value": false}),
            serde_json::json!({"value": null, "summary": "not specified"}),
            serde_json::Value::Null,
        ] {
            let mut f = fact(5);
            f.predicate_id = None;
            f.surface_predicate = Some("状态".into());
            f.object_id = None;
            f.object_value = Some(value.clone());
            f.documents = vec![id(20)];
            f.quotes = vec!["设备 A 待复检".into()];
            f.supersedes = Some(id(6));
            for retracted in [false, true] {
                f.invalidated_at = retracted.then(|| at("2026-02-01T00:00:00Z"));
                let mut sets = Vec::new();
                for format in [Format::Turtle, Format::JsonLd] {
                    let quads = export(format, |sink, names, vocab| {
                        emit_fact(sink, names, vocab, &f, at("2026-06-01T00:00:00Z")).unwrap();
                    });
                    let expected: Vec<String> = literal_value(&value, None)
                        .map(|lit| lit.to_string())
                        .into_iter()
                        .collect();
                    assert_eq!(
                        objects(&quads, STMT, rdf::OBJECT.as_str()),
                        expected,
                        "unbound statement lost its literal object: {value}"
                    );
                    assert!(objects(&quads, STMT, rdf::PREDICATE.as_str()).is_empty());
                    assert!(!quads.iter().any(|q| q.subject.to_string() == SUBJ));
                    sets.push(quads.into_iter().collect::<std::collections::HashSet<_>>());
                }
                assert_eq!(sets[0], sets[1]);
            }
        }
    }

    #[test]
    fn bound_literal_datatypes_survive_both_formats() {
        for (datatype, value, expected) in [
            (
                "number",
                serde_json::json!(0),
                Literal::new_typed_literal("0", xsd::DECIMAL),
            ),
            (
                "text",
                serde_json::json!("待复检"),
                Literal::new_simple_literal("待复检"),
            ),
            (
                "bool",
                serde_json::json!(false),
                Literal::new_typed_literal("false", xsd::BOOLEAN),
            ),
        ] {
            let mut f = fact(5);
            f.predicate_id = Some(id(4));
            f.object_id = None;
            f.object_value = Some(serde_json::json!({"value": value}));
            for format in [Format::Turtle, Format::JsonLd] {
                let quads = export(format, |sink, names, _| {
                    let mut property = relation(4, "value", None, "attribute");
                    property.datatype = Some(datatype.into());
                    let vocab = vocabulary(names, &[], &[property]);
                    emit_fact(sink, names, &vocab, &f, at("2026-06-01T00:00:00Z")).unwrap();
                });
                assert_eq!(
                    objects(&quads, STMT, rdf::OBJECT.as_str()),
                    vec![expected.to_string()]
                );
                assert!(quads.iter().any(|q| q.subject.to_string() == SUBJ
                    && q.object == Term::Literal(expected.clone())));
            }
        }
    }

    #[test]
    fn an_absent_object_is_not_an_empty_literal() {
        let mut f = fact(5);
        f.predicate_id = None;
        f.object_id = None;
        f.object_value = None;
        for format in [Format::Turtle, Format::JsonLd] {
            let quads = export(format, |sink, names, vocab| {
                emit_fact(sink, names, vocab, &f, at("2026-06-01T00:00:00Z")).unwrap();
            });
            assert!(objects(&quads, STMT, rdf::OBJECT.as_str()).is_empty());
        }
    }

    /// #831:导出时如果 `object_value` 是 `{"summary": "..."}` 或 `{"value": "..."}` 这种带结构
    /// 的对象,老代码 `v.get("value").unwrap_or(v)` 会把整个对象序列化成 JSON 字符串当字面量。
    /// 修复后 `value` 优先,`summary` 是它的替补(与 `models.rs` 和 `api/tools.rs` 一致);
    /// `summary` 和 `class` 是散文或类名,落成 `xsd:string` 而不套属性声明的类型;
    /// 解析失败就**没有 `rdf:object`**,和 #821 同一套原则。
    ///
    /// 七种情形:value 优先于 summary;只有 value;只有 summary(xsd:string);
    /// summary 为空时退回 value;null value 且无 summary → 不写;分类结论 `{"class": …}`
    /// 落成 xsd:string;不认得的键 → 不写。
    #[test]
    fn an_object_value_with_summary_or_value_does_not_emit_a_json_literal() {
        let cases: &[(&str, serde_json::Value, &[&str])] = &[
            (
                "value wins over summary when both are present",
                serde_json::json!({ "value": 12.5, "summary": "about a dozen" }),
                &["\"12.5\"^^<http://www.w3.org/2001/XMLSchema#decimal>"],
            ),
            (
                "value alone resolves to its scalar string",
                serde_json::json!({ "value": "42" }),
                &["\"42\"^^<http://www.w3.org/2001/XMLSchema#decimal>"],
            ),
            (
                "summary alone is prose: a string, never the declared type",
                serde_json::json!({ "summary": "before the merge" }),
                &["\"before the merge\""],
            ),
            (
                "empty summary with a value resolves to the value",
                serde_json::json!({ "summary": "", "value": "0" }),
                &["\"0\"^^<http://www.w3.org/2001/XMLSchema#decimal>"],
            ),
            (
                "null value and no summary → no rdf:object",
                serde_json::json!({ "value": null }),
                &[],
            ),
            (
                "a typing conclusion keeps its class as a string",
                serde_json::json!({ "class": "gas_well" }),
                &["\"gas_well\""],
            ),
            (
                "object with no recognised key → no rdf:object",
                serde_json::json!({ "confidence": 0.9 }),
                &[],
            ),
        ];

        for (what, value, expected_objects) in cases {
            let mut f = fact(5);
            f.predicate_id = Some(id(4));
            f.object_id = None;
            f.object_value = Some(value.clone());
            for format in [Format::Turtle, Format::JsonLd] {
                let quads = export(format, |sink, names, vocab| {
                    emit_fact(sink, names, vocab, &f, at("2026-06-01T00:00:00Z")).unwrap();
                });
                let got: Vec<String> = objects(&quads, STMT, rdf::OBJECT.as_str());
                assert_eq!(
                    got, *expected_objects,
                    "{what} (format={format:?}): got {got:?} expected {expected_objects:?}"
                );
            }
        }
    }

    #[test]
    fn an_imported_class_keeps_its_own_iri() {
        let quads = export(Format::Turtle, |_, _, _| {});
        // 导入来的 schema.org 类导出去还是 schema:Person
        assert!(has(
            &quads,
            "<https://schema.org/Person>",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2002/07/owl#Class"
        ));
        // 本体自己长的用 key 铸 IRI,读得懂
        assert!(has(
            &quads,
            "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:class:team>",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2002/07/owl#Class"
        ));
        // 公理照抄:一致性检查按它跑,读的人要能自己复算
        assert!(has(
            &quads,
            &format!("<{WORKS_FOR}>"),
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/2002/07/owl#FunctionalProperty"
        ));
    }

    /// 改回 state 的关系重导入也得是 state:导入把没写的 `utopia:temporal` 读成「不动」
    #[test]
    fn a_state_relation_exports_its_temporal() {
        let quads = export(Format::Turtle, |_, _, _| {});
        assert!(has(
            &quads,
            &format!("<{WORKS_FOR}>"),
            "urn:utopia:ns:temporal",
            "\"state\""
        ));
    }

    #[test]
    fn a_live_fact_is_both_a_statement_and_a_triple() {
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &fact(5), at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert!(has(
            &quads,
            STMT,
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement"
        ));
        assert!(has(
            &quads,
            STMT,
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#subject",
            SUBJ
        ));
        assert!(
            has(&quads, SUBJ, WORKS_FOR, OBJ),
            "仍然成立的事实要有一条平铺三元组——不看具体化的消费者靠它拿到现状"
        );
        assert_eq!(
            objects(&quads, STMT, "urn:utopia:ns:confidence"),
            vec!["\"0.90\"^^<http://www.w3.org/2001/XMLSchema#decimal>"]
        );
    }

    #[test]
    fn a_closed_or_retracted_fact_is_a_statement_only() {
        // 区间已闭合:世界轴上它已经结束
        let mut closed = fact(5);
        closed.valid_from = Some(at("2023-01-01T00:00:00Z"));
        closed.valid_from_precision = Some("day".into());
        closed.valid_to = Some(at("2024-07-01T00:00:00Z"));
        closed.valid_to_precision = Some("day".into());
        // 读出来的区间随原文(0022):两端都给了,就是它们
        closed.holds_from = Some(at("2023-01-01T00:00:00Z"));
        closed.holds_to = Some(at("2024-07-01T00:00:00Z"));
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &closed, at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert!(
            !has(&quads, SUBJ, WORKS_FOR, OBJ),
            "结束了的关系不该以现在时写出去——那正是导出会骗人的地方"
        );
        assert_eq!(
            objects(&quads, STMT, "https://schema.org/validThrough"),
            vec!["\"2024-07-01\"^^<http://www.w3.org/2001/XMLSchema#date>"]
        );

        // 记录轴上被撤回:世界轴上它甚至还"开着",但我们已经不这么认为了
        let mut retracted = fact(5);
        retracted.invalidated_at = Some(at("2026-03-01T00:00:00Z"));
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &retracted, at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert!(!has(&quads, SUBJ, WORKS_FOR, OBJ), "撤回的不出平铺三元组");
        assert_eq!(
            objects(&quads, STMT, "http://www.w3.org/ns/prov#invalidatedAtTime"),
            vec!["\"2026-03-01T00:00:00Z\"^^<http://www.w3.org/2001/XMLSchema#dateTime>"]
        );
    }

    #[test]
    fn record_axis_subseconds_round_trip_without_changing_world_precision() {
        for timestamp in [
            "2026-09-20T00:00:00Z",
            "2026-09-20T00:00:00.100Z",
            "2026-09-20T00:00:00.100001Z",
            "2026-09-20T00:00:00.100002Z",
            "2026-09-20T00:00:00.123456789Z",
        ] {
            let original = at(timestamp);
            let literal = dt(original);
            assert_eq!(literal.datatype(), xsd::DATE_TIME);
            assert_eq!(literal.value().parse::<DateTime<Utc>>().unwrap(), original);
        }
        assert_eq!(
            dt(at("2026-09-20T00:00:00Z")).value(),
            "2026-09-20T00:00:00Z"
        );
        let instant = at("2026-09-20T12:34:56.123456Z");
        for (precision, lexical, datatype) in [
            ("year", "2026", xsd::G_YEAR),
            ("month", "2026-09", xsd::G_YEAR_MONTH),
            ("day", "2026-09-20", xsd::DATE),
            ("hour", "2026-09-20T12:34:56Z", xsd::DATE_TIME),
            ("minute", "2026-09-20T12:34:56Z", xsd::DATE_TIME),
            ("second", "2026-09-20T12:34:56Z", xsd::DATE_TIME),
        ] {
            assert_eq!(
                world_time(instant, Some(precision)),
                Literal::new_typed_literal(lexical, datatype)
            );
        }
    }

    #[test]
    fn a_year_stays_a_year() {
        let mut coarse = fact(5);
        coarse.valid_from = Some(at("2023-01-01T00:00:00Z"));
        coarse.valid_from_precision = Some("year".into());
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &coarse, at("2026-06-01T00:00:00Z")).unwrap();
        });
        // 只量到年份就写 gYear。一律写成 xsd:date 等于替账本补上它没有过的确定性
        assert_eq!(
            objects(&quads, STMT, "https://schema.org/validFrom"),
            vec!["\"2023\"^^<http://www.w3.org/2001/XMLSchema#gYear>"]
        );
    }

    #[test]
    fn an_ended_but_undated_relation_says_so() {
        let mut ended = fact(5);
        ended.valid_to = None;
        ended.valid_to_precision = Some("unknown".into());
        // 结束了不知哪天:读出来的终点是锚点(说出它的那份文档的日期),SQL 就这么投影
        ended.holds_to = ended.holds_from;
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &ended, at("2026-06-01T00:00:00Z")).unwrap();
        });
        // 「结束了,但不知道哪天」不能压成「至今仍成立」
        assert!(has(
            &quads,
            STMT,
            "urn:utopia:ns:endedUnknown",
            "\"true\"^^<http://www.w3.org/2001/XMLSchema#boolean>"
        ));
        assert!(!has(&quads, SUBJ, WORKS_FOR, OBJ));
    }

    #[test]
    fn a_predicate_the_ontology_never_accepted_is_not_invented() {
        let mut bare = fact(5);
        bare.predicate_id = None;
        bare.surface_predicate = Some("acquired".into());
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &bare, at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert!(
            objects(
                &quads,
                STMT,
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#predicate"
            )
            .is_empty(),
            "本体没有这条关系就不铸一个谓词出来(0010)"
        );
        assert_eq!(
            objects(&quads, STMT, "urn:utopia:ns:proposedPredicate"),
            vec!["\"acquired\""]
        );
    }

    #[test]
    fn an_attribute_carries_its_datatype() {
        let mut attr = fact(5);
        attr.predicate_id = Some(id(4));
        attr.object_id = None;
        attr.object_value = Some(serde_json::json!({ "value": 42, "unit": "people" }));
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &attr, at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert_eq!(
            objects(
                &quads,
                STMT,
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#object"
            ),
            vec!["\"42\"^^<http://www.w3.org/2001/XMLSchema#decimal>"]
        );
    }

    /// 日期属性上相对的值(#681 §4)导出成普通字符串,陈述上另有一行说它是相对的——
    /// 写成 xsd:date 的字面量不合法,严格的解析器会整份拒收
    #[test]
    fn a_relative_deadline_is_a_string_that_says_it_is_relative() {
        let dated =
            literal_value(&serde_json::json!({ "value": "2020-06-23" }), Some("date")).unwrap();
        assert_eq!(dated.datatype(), xsd::DATE);
        let relative = literal_value(
            &serde_json::json!({ "value": "45 days after the Trigger Date", "relative": true }),
            Some("date"),
        )
        .unwrap();
        assert_eq!(relative.datatype(), xsd::STRING);
        assert_eq!(relative.value(), "45 days after the Trigger Date");

        let mut attr = fact(5);
        attr.predicate_id = Some(id(4));
        attr.object_id = None;
        attr.object_value = Some(
            serde_json::json!({ "value": "45 days after the Trigger Date", "relative": true }),
        );
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &attr, at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert!(has(
            &quads,
            STMT,
            "urn:utopia:ns:relativeValue",
            "\"true\"^^<http://www.w3.org/2001/XMLSchema#boolean>"
        ));
    }

    /// 业务规则的结论也要出现在导出里,而且宾语是**字面值**。
    ///
    /// 这一条挡的是一次静默丢失:取数那边原本 `JOIN rules`,而业务规则的
    /// `rule_id` 是 NULL——整条结论会被内连接挡在文件之外,而 0020 承诺的正是
    /// 「审计员不靠我们也能读全」。活动的标签也要是规则自己的名字,
    /// 「business」对读的人没有意义
    #[test]
    fn a_rule_conclusion_reaches_the_export_as_a_literal() {
        let derived = ExportDerived {
            id: id(7),
            subject_id: id(10),
            predicate_id: id(2),
            object_id: None,
            object_value: Some(serde_json::json!({ "class": "gas_well" })),
            rule_id: None,
            attribute_rule_id: Some(id(9)),
            valid_from: None,
            valid_from_precision: None,
            valid_to: None,
            valid_to_precision: None,
            derived_at: at("2026-02-01T00:00:00Z"),
            invalidated_at: None,
            confidence: 0.9,
            rule: "business".into(),
            rule_predicate: None,
            rule_name: Some("Gas-bearing well".into()),
            premises: vec![id(5)],
            premises_derived: Vec::new(),
            subject_kb: Some(kb()),
            object_kb: None,
            predicate_kb: Some(kb()),
            rule_kb: None,
            attribute_rule_kb: Some(kb()),
            foreign_fact_premise: false,
            foreign_derived_premise: false,
            subject_merged: false,
            object_merged: false,
        };
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_derived(sink, names, vocab, &derived).unwrap();
        });
        let stmt = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:derived:07070707-0707-0707-0707-070707070707>";
        // 派生标记还在——它仍旧是推出来的,不是谁断言的
        assert!(has(
            &quads,
            stmt,
            "urn:utopia:ns:derived",
            "\"true\"^^<http://www.w3.org/2001/XMLSchema#boolean>"
        ));
        // 宾语是字面值而不是一个实体 IRI:分类结论 `{"class": …}` 按键解析成类名,
        // 落成 xsd:string。老代码把整个对象序列化成 `{"class":"gas_well"}` 当字面量(#831)
        let obj = objects(
            &quads,
            stmt,
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#object",
        );
        assert_eq!(obj.len(), 1, "结论要有宾语");
        assert_eq!(
            obj[0], "\"gas_well\"",
            "分类结论的宾语该是类名本身的字符串字面量,拿到的是 {}",
            obj[0]
        );
        // 规则资源说出自己的家族(#902):业务规则,没有公理种类可言
        let rule = Names::new(kb(), None).unwrap().rule(id(9)).to_string();
        assert!(has(
            &quads,
            &rule,
            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
            "<urn:utopia:ns:BusinessRule>"
        ));
        assert!(objects(&quads, &rule, "urn:utopia:ns:axiomKind").is_empty());
        assert!(objects(&quads, &rule, "urn:utopia:ns:declaredOn").is_empty());
        // 前提照常挂着:审计顺着 prov:used 走得到那两条读数
        assert_eq!(
            objects(&quads, stmt, "http://www.w3.org/ns/prov#used").len(),
            1
        );
        // 活动的标签是规则的名字
        let rule_iri =
            "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:rule:09090909-0909-0909-0909-090909090909>";
        assert_eq!(
            objects(
                &quads,
                rule_iri,
                "http://www.w3.org/2000/01/rdf-schema#label"
            ),
            vec!["\"Gas-bearing well\""],
            "推理活动要以规则名示人"
        );
    }

    #[test]
    fn declared_property_links_are_local_explicit_and_order_independent() {
        let root = relation(21, "root", Some("https://example.test/root"), "relation");
        let mut inverse = relation(22, "inverse", None, "relation");
        inverse.inverse_of = Some(root.id);
        let mut child = relation(23, "child", None, "relation");
        child.sub_property_of = Some(root.id);
        let mut leaf = relation(24, "leaf", None, "relation");
        leaf.sub_property_of = Some(child.id);
        let mut missing = relation(25, "unresolved", None, "relation");
        missing.inverse_of = Some(id(98));
        missing.sub_property_of = Some(id(99));
        let mut relations = vec![root, inverse, child, leaf, missing];
        let mut sets = Vec::new();
        for reverse in [false, true] {
            if reverse {
                relations.reverse();
            }
            for format in [Format::Turtle, Format::JsonLd] {
                let quads = export(format, |sink, names, _| {
                    let vocab = vocabulary(names, &[], &relations);
                    for r in &relations {
                        emit_relation(sink, &vocab, r).unwrap();
                    }
                });
                let names = Names::new(kb(), None).unwrap();
                let iri = |n| names.relation(relations.iter().find(|r| r.id == id(n)).unwrap());
                let expected: std::collections::HashSet<_> = [
                    (iri(22).into(), owl("inverseOf"), Term::from(iri(21))),
                    (
                        iri(23).into(),
                        nn(rdfs::SUB_PROPERTY_OF.as_str()),
                        Term::from(iri(21)),
                    ),
                    (
                        iri(24).into(),
                        nn(rdfs::SUB_PROPERTY_OF.as_str()),
                        Term::from(iri(23)),
                    ),
                ]
                .into_iter()
                .collect();
                let links: std::collections::HashSet<_> = quads
                    .iter()
                    .filter(|q| {
                        q.predicate == owl("inverseOf") || q.predicate == rdfs::SUB_PROPERTY_OF
                    })
                    .map(|q| (q.subject.clone(), q.predicate.clone(), q.object.clone()))
                    .collect();
                assert_eq!(
                    links, expected,
                    "only stored, local links should be emitted"
                );
                sets.push(quads.into_iter().collect::<std::collections::HashSet<_>>());
            }
        }
        for set in &sets[1..] {
            assert_eq!(&sets[0], set);
        }
    }

    #[test]
    fn a_derivation_says_it_is_one_and_names_its_premises() {
        let derived = ExportDerived {
            id: id(7),
            subject_id: id(10),
            predicate_id: id(2),
            object_id: Some(id(11)),
            object_value: None,
            rule_id: Some(id(8)),
            attribute_rule_id: None,
            valid_from: None,
            valid_from_precision: None,
            valid_to: None,
            valid_to_precision: None,
            derived_at: at("2026-02-01T00:00:00Z"),
            invalidated_at: None,
            confidence: 0.8,
            rule: "transitive".into(),
            rule_predicate: Some(id(2)),
            rule_name: None,
            premises: vec![id(5)],
            premises_derived: vec![id(6)],
            subject_kb: Some(kb()),
            object_kb: Some(kb()),
            predicate_kb: Some(kb()),
            rule_kb: Some(kb()),
            attribute_rule_kb: None,
            foreign_fact_premise: false,
            foreign_derived_premise: false,
            subject_merged: false,
            object_merged: false,
        };
        for format in [Format::Turtle, Format::JsonLd] {
            let quads = export(format, |sink, names, vocab| {
                emit_derived(sink, names, vocab, &derived).unwrap();
            });
            let stmt = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:derived:07070707-0707-0707-0707-070707070707>";
            assert!(has(
                &quads,
                stmt,
                "urn:utopia:ns:derived",
                "\"true\"^^<http://www.w3.org/2001/XMLSchema#boolean>"
            ));
            assert_eq!(
                objects(&quads, stmt, "http://www.w3.org/ns/prov#used"),
                vec![
                    STMT.to_string(),
                    Names::new(kb(), None).unwrap().derived(id(6)).to_string()
                ]
            );
            assert!(
                !has(&quads, SUBJ, WORKS_FOR, OBJ),
                "推出来的边不写成平铺三元组:那会让人把引擎的结论当成文档里的话"
            );
            // 规则资源说出自己的家族、种类和声明所在的谓词(#902):读的人不再
            // 从 rdfs:label 里猜。这里声明谓词就是结论谓词(传递),指向同一个 IRI
            let rule = Names::new(kb(), None).unwrap().rule(id(8)).to_string();
            assert!(has(
                &quads,
                &rule,
                "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
                "<urn:utopia:ns:AxiomRule>"
            ));
            assert_eq!(
                objects(&quads, &rule, "urn:utopia:ns:axiomKind"),
                vec!["\"transitive\""]
            );
            assert_eq!(
                objects(&quads, &rule, "urn:utopia:ns:declaredOn"),
                objects(
                    &quads,
                    stmt,
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#predicate"
                )
            );
        }
    }

    #[test]
    fn evidence_points_back_at_the_document_and_the_sentence() {
        let mut cited = fact(5);
        cited.documents = vec![id(12)];
        cited.quotes = vec!["Lin Zhao joined Acme in 2023.".into()];
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_fact(sink, names, vocab, &cited, at("2026-06-01T00:00:00Z")).unwrap();
        });
        assert_eq!(
            objects(&quads, STMT, "http://www.w3.org/ns/prov#wasDerivedFrom"),
            vec!["<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:document:0c0c0c0c-0c0c-0c0c-0c0c-0c0c0c0c0c0c>"]
        );
        assert_eq!(
            objects(&quads, STMT, "urn:utopia:ns:quote"),
            vec!["\"Lin Zhao joined Acme in 2023.\""]
        );
    }

    #[test]
    fn json_ld_carries_the_same_triples() {
        let emit = |sink: &mut Sink, names: &Names, vocab: &Vocabulary| {
            emit_fact(sink, names, vocab, &fact(5), at("2026-06-01T00:00:00Z")).unwrap();
        };
        let ttl = export(Format::Turtle, emit);
        let jsonld = export(Format::JsonLd, emit);
        assert_eq!(
            ttl.len(),
            jsonld.len(),
            "两种格式是同一张图的两种写法,三元组数目必须一样"
        );
        assert!(has(&jsonld, SUBJ, WORKS_FOR, OBJ));
    }

    #[test]
    fn a_published_deployment_can_mint_http_iris() {
        let names = Names::new(kb(), Some("https://acme.example/utopia/")).unwrap();
        assert_eq!(
            names.entity(id(10)).as_str(),
            "https://acme.example/utopia/kb/01a06dc4-f40a-7013-b09f-1b499e2e7441/entity/0a0a0a0a-0a0a-0a0a-0a0a-0a0a0a0a0a0a"
        );
        // 非 http 的 base 拒掉:拼出来的会是一份谁也解析不了的文件
        assert!(Names::new(kb(), Some("javascript:alert(1)")).is_err());
        assert!(Names::new(kb(), Some("https://acme.example/a b")).is_err());
    }

    const CONFLICT: &str = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:conflict:07070707-0707-0707-0707-070707070707>";
    const VIOLATION: &str = "<urn:utopia:kb:01a06dc4-f40a-7013-b09f-1b499e2e7441:violation:08080808-0808-0808-0808-080808080808>";

    fn conflict(status: &str, resolution: Option<&str>) -> ExportFactConflict {
        ExportFactConflict {
            id: id(7),
            old_fact_id: id(5),
            new_fact_id: id(6),
            reason: "simultaneous".into(),
            created_at: at("2026-03-10T00:00:00Z"),
            status: status.into(),
            resolution: resolution.map(str::to_string),
            resolved_at: (status != "open").then(|| at("2026-03-20T00:00:00Z")),
            old_fact_kb: Some(kb()),
            new_fact_kb: Some(kb()),
        }
    }

    fn violation(
        kind: &str,
        status: &str,
        resolution: Option<&str>,
        path: Vec<Uuid>,
    ) -> ExportAxiomViolation {
        ExportAxiomViolation {
            id: id(8),
            kind: kind.into(),
            left_fact: id(5),
            right_fact: id(6),
            path,
            status: status.into(),
            resolution: resolution.map(str::to_string),
            detected_at: at("2026-03-15T00:00:00Z"),
            decided_at: (status != "open").then(|| at("2026-03-20T00:00:00Z")),
            criterion_predicate: (status == "open").then_some(id(2)),
            criterion_axiom: (status == "open").then_some(kind.to_string()),
            left_kb: Some(kb()),
            right_kb: Some(kb()),
            criterion_predicate_kb: Some(kb()),
            foreign_path: false,
        }
    }

    #[test]
    fn a_contest_names_both_sides_and_its_disposition() {
        let open = conflict("open", None);
        let quads = export(Format::Turtle, |sink, names, _| {
            emit_fact_conflict(sink, names, &open).unwrap();
        });
        assert!(has(
            &quads,
            CONFLICT,
            rdf::TYPE.as_str(),
            "urn:utopia:ns:FactConflict"
        ));
        let names = Names::new(kb(), None).unwrap();
        // 两席有方向:旧断言是 prior,新到的是 incoming
        assert_eq!(
            objects(&quads, CONFLICT, "urn:utopia:ns:priorStatement"),
            vec![names.fact(id(5)).to_string()]
        );
        assert_eq!(
            objects(&quads, CONFLICT, "urn:utopia:ns:incomingStatement"),
            vec![names.fact(id(6)).to_string()]
        );
        assert_eq!(
            objects(&quads, CONFLICT, "urn:utopia:ns:reason"),
            vec!["\"simultaneous\""]
        );
        assert_eq!(
            objects(&quads, CONFLICT, "urn:utopia:ns:status"),
            vec!["\"open\""]
        );
        assert!(objects(&quads, CONFLICT, "urn:utopia:ns:resolution").is_empty());
        assert!(!objects(
            &quads,
            CONFLICT,
            "http://www.w3.org/ns/prov#generatedAtTime"
        )
        .is_empty());
        assert!(objects(&quads, CONFLICT, "urn:utopia:ns:closedAt").is_empty());

        // 人裁过的带裁决词;作废的不是裁决——closedAt 记的是作废时刻(0051),
        // 不带 resolution
        for (status, resolution) in [("resolved", Some("kept_both")), ("withdrawn", None)] {
            let c = conflict(status, resolution);
            let quads = export(Format::Turtle, |sink, names, _| {
                emit_fact_conflict(sink, names, &c).unwrap();
            });
            assert_eq!(
                objects(&quads, CONFLICT, "urn:utopia:ns:status"),
                vec![format!("\"{status}\"")]
            );
            assert_eq!(
                objects(&quads, CONFLICT, "urn:utopia:ns:resolution"),
                resolution
                    .map(|r| vec![format!("\"{r}\"")])
                    .unwrap_or_default()
            );
            assert!(!objects(&quads, CONFLICT, "urn:utopia:ns:closedAt").is_empty());
        }
    }

    #[test]
    fn an_open_violation_points_at_its_criterion() {
        let v = violation("asymmetry", "open", None, vec![]);
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_axiom_violation(sink, names, vocab, &v).unwrap();
        });
        assert!(has(
            &quads,
            VIOLATION,
            rdf::TYPE.as_str(),
            "urn:utopia:ns:AxiomViolation"
        ));
        assert_eq!(
            objects(&quads, VIOLATION, "urn:utopia:ns:kind"),
            vec!["\"asymmetry\""]
        );
        assert_eq!(
            objects(&quads, VIOLATION, "urn:utopia:ns:onStatement").len(),
            2,
            "违规必须指回两条事实"
        );
        // 判据 = OWL 词 + 住在哪条关系上(0062)
        assert_eq!(
            objects(&quads, VIOLATION, "urn:utopia:ns:criterion"),
            vec!["<http://www.w3.org/2002/07/owl#AsymmetricProperty>"]
        );
        assert_eq!(
            objects(&quads, VIOLATION, "urn:utopia:ns:onRelation"),
            vec![format!("<{WORKS_FOR}>")]
        );
        assert!(!objects(&quads, VIOLATION, "urn:utopia:ns:detectedAt").is_empty());
        assert!(objects(&quads, VIOLATION, "urn:utopia:ns:closedAt").is_empty());
    }

    #[test]
    fn a_signature_violation_points_at_the_whole_signature() {
        // signature 的判据是 domain+range 这一对(0062):行不记哪一侧破的,
        // 合同也就不装知道——两个词都发
        let v = violation("signature", "open", None, vec![]);
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_axiom_violation(sink, names, vocab, &v).unwrap();
        });
        let mut criterion = objects(&quads, VIOLATION, "urn:utopia:ns:criterion");
        criterion.sort();
        assert_eq!(
            criterion,
            vec![
                "<http://www.w3.org/2000/01/rdf-schema#domain>".to_string(),
                "<http://www.w3.org/2000/01/rdf-schema#range>".to_string()
            ]
        );
        assert_eq!(
            objects(&quads, VIOLATION, "urn:utopia:ns:onRelation"),
            vec![format!("<{WORKS_FOR}>")]
        );
    }

    #[test]
    fn a_closed_violation_does_not_claim_a_criterion() {
        // resolved 的行不连判据:促成它结案的本体可能早已不在(0062)
        let v = violation("signature", "resolved", Some("criterion_changed"), vec![]);
        let quads = export(Format::Turtle, |sink, names, vocab| {
            emit_axiom_violation(sink, names, vocab, &v).unwrap();
        });
        assert!(objects(&quads, VIOLATION, "urn:utopia:ns:criterion").is_empty());
        assert!(objects(&quads, VIOLATION, "urn:utopia:ns:onRelation").is_empty());
        assert_eq!(
            objects(&quads, VIOLATION, "urn:utopia:ns:resolution"),
            vec!["\"criterion_changed\""]
        );
        assert!(!objects(&quads, VIOLATION, "urn:utopia:ns:closedAt").is_empty());
    }

    /// 顺着 rdf:List 走一遍,把成员按序收回来
    fn list_items(quads: &[Quad], violation_iri: &str) -> Vec<String> {
        let nil: Term = nn(rdf::NIL.as_str()).into();
        let head = quads
            .iter()
            .find(|q| {
                q.subject.to_string() == violation_iri
                    && q.predicate.as_str() == "urn:utopia:ns:evidencePath"
            })
            .map(|q| q.object.clone())
            .expect("环必须带着 path");
        let mut items = Vec::new();
        let mut node = head;
        while node != nil {
            let first = quads
                .iter()
                .find(|q| {
                    q.subject.to_string() == node.to_string()
                        && q.predicate.as_str() == rdf::FIRST.as_str()
                })
                .map(|q| q.object.clone())
                .expect("list 节点必有 first");
            items.push(first.to_string());
            node = quads
                .iter()
                .find(|q| {
                    q.subject.to_string() == node.to_string()
                        && q.predicate.as_str() == rdf::REST.as_str()
                })
                .map(|q| q.object.clone())
                .expect("list 节点必有 rest");
        }
        items
    }

    #[test]
    fn a_cycle_keeps_its_facts_in_order() {
        let path = vec![id(5), id(9), id(6)];
        let v = violation("cycle", "open", None, path.clone());
        let names = Names::new(kb(), None).unwrap();
        let expected: Vec<String> = path.iter().map(|f| names.fact(*f).to_string()).collect();
        for format in [Format::Turtle, Format::JsonLd] {
            let quads = export(format, |sink, names, vocab| {
                emit_axiom_violation(sink, names, vocab, &v).unwrap();
            });
            assert_eq!(
                list_items(&quads, VIOLATION),
                expected,
                "{format:?} 里环的顺序丢了"
            );
        }
    }

    #[test]
    fn contest_and_finding_survive_both_formats() {
        let emit = |sink: &mut Sink, names: &Names, vocab: &Vocabulary| {
            emit_fact_conflict(sink, names, &conflict("resolved", Some("rejected_new"))).unwrap();
            emit_axiom_violation(
                sink,
                names,
                vocab,
                &violation("asymmetry", "open", None, vec![id(5), id(9)]),
            )
            .unwrap();
        };
        let ttl = export(Format::Turtle, emit);
        let jsonld = export(Format::JsonLd, emit);
        assert_eq!(
            ttl.len(),
            jsonld.len(),
            "两种格式是同一张图的两种写法,三元组数目必须一样"
        );
        // 空白节点在两种写法里各自匿名,集合同比不了——比所有非匿名的角,
        // 环那份证据的顺序交给 a_cycle_keeps_its_facts_in_order 按格式各验一遍
        let named = |qs: &[Quad]| {
            qs.iter()
                .filter(|q| q.subject.is_named_node() && !matches!(q.object, Term::BlankNode(_)))
                .cloned()
                .collect::<std::collections::HashSet<_>>()
        };
        assert_eq!(named(&ttl), named(&jsonld));
    }
}