World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 导出用的读取面(0020)。
//!
//! 与界面那几个视图分开写,因为问的东西不一样:界面要「现在是什么样」,
//! 导出要**全部**——闭合的区间、撤回的行、修正链,一条都不能少,否则导出的
//! 是一张干净自信的图,而那正是审计要看的东西被抹掉的样子。
//!
//! 除本体外一律**按 id 分页**:一个库的事实可以有几十万条,全读进内存再序列化
//! 会在最需要它的那种部署上炸掉。id 是 uuid v7,按它排序即按写入顺序排序。
//! 第一页没有下界(`$2 IS NULL OR id > $2`):uuid 没有更小的哨兵可垫——
//! `id > NIL` 会把主键恰为 NIL 的合法行永远挡在导出外,而指向它的
//! (document_id, version) 定位器照样解析,留下一条没有本体的边。
//!
//! **同一份快照**:所有取数口吃调用方的事务(`&mut Transaction`),路由侧把它
//! 定成只读 REPEATABLE READ——体检、词汇表与每一页读的是同一个时刻的库。
//! 若每页各自向连接池要一条连接,词汇表发完之后才提交的规则会在派生页里
//! 留下一条指向它的 `wasGeneratedBy`——图里就出现没有本体的引用。
//!
//! **逐页校验用的是留下的那几行自己**:每个 page 查询把被引行的
//! kb_id 与行本体**原子地一并选出**,校验在内存里跑。不能「先取一页、再去库里
//! 问一次」——第二次问的是另一个时刻的状态,留下的行早已不是它。
//!
//! 体检范围覆盖 **0070/0091 保护的每一条结构引用边**——不只这份导出真正解析的
//! 那些。导出还没读的边(规则表自身、陈述属性、时间提及等)也在同一个快照里
//! 先查:catalog 守卫(migration_0070_runs_under_any_search_path.rs)核对
//! export_provenance_integrity.sql 的每条扫描分支都对应一条受保护的
//! catalog 边,将来新加的受保护引用漏登记体检就直接红。
use chrono::{DateTime, Utc};
use sqlx::{Postgres, Transaction};
use utopia_core::{AppError, AppResult};
use uuid::Uuid;
/// 一次取多少行。够大以免把往返次数拉满,够小以免一页就撑爆内存。
pub const PAGE: i64 = 500;
/// 出处体检的唯一一份 SQL:运行时就跑它,catalog 守卫读的也是它——
/// 边集合只有这一处登记,没有第二份要手工对齐的清单
const PREFLIGHT_SQL: &str = include_str!("export_provenance_integrity.sql");
/// 出处链越界的一类引用。同库外键只认 id、不认库:A 库的
/// 行可以引用 B 库的对象,schema 什么都不拦。0070 的触发器挡新行;这里拦的是
/// **存量坏行**与绕过触发器写进来的行。
///
/// 处置一律是**整份拒导**:把别库对象的 id 铸进本库 IRI
/// (`urn:utopia:kb:A:document:{B 的文档}`)等于伪造身份——那份文件看着
/// 完整,实则悬空。被词汇表解析的引用(谓词、属性类型、实体类型)越库则
/// 静默消失——坏行一样不许放行。少导一行、换个 IRI 都不在选项里
#[derive(Debug, sqlx::FromRow)]
pub struct CrossKbViolation {
/// 哪条边:evidence.chunk | derivation.premise_fact | …
pub edge: String,
pub rows: i64,
}
fn cross_kb_error(violations: &[CrossKbViolation]) -> AppError {
let detail = violations
.iter()
.map(|v| format!("{}: {} row(s)", v.edge, v.rows))
.collect::<Vec<_>>()
.join("; ");
AppError::invalid_detail(
"cross_kb_provenance",
"export refused: KB-scoped provenance points outside the knowledge base",
detail,
)
}
/// 引用指着的东西**在本库,却不在导出集里**(合并掉的实体是唯一会缺席的
/// 实体——`entities_page` 滤掉 `merged_into` 非空的行)。同库但缺席的引用
/// 不能换 IRI、也不能静默省略:整份拒导,与越库同一处置。
fn unexported_error(violations: &[CrossKbViolation]) -> AppError {
let detail = violations
.iter()
.map(|v| format!("{}: {} row(s)", v.edge, v.rows))
.collect::<Vec<_>>()
.join("; ");
AppError::invalid_detail(
"unexported_target",
"export refused: a reference points at a row that is not in this KB's exported set",
detail,
)
}
fn tally(violations: &mut Vec<CrossKbViolation>, edge: &str, rows: i64) {
if rows > 0 {
violations.push(CrossKbViolation {
edge: edge.into(),
rows,
});
}
}
/// 引用列的判定:**留下的是谁,就查谁**。`ref_kb` 由 page 查询与行本体原子地
/// 一并选出——别库、悬空(NULL)都不算本库,一律判违规
fn foreign(ref_kb: Option<Uuid>, kb_id: Uuid) -> bool {
ref_kb != Some(kb_id)
}
/// 导出前的出处体检。逐类数一遍越界引用,有一行就整份拒导。
/// 越界有两类,各自一条错:**别库/悬空**(`cross_kb`)与**同库但不在导出集**
/// (`unexported`——合并掉的实体)。只报哪条边坏了、坏了几行——具体哪些行
/// 坏是库里的事,不进面向导出的报错
///
/// 扫的边 = **0070/0091 保护的全部结构引用边**(export_provenance_integrity.sql,
/// 每条分支带一条 `@edge`/`@filter` 标记给 catalog 守卫核对)——连导出尚未
/// 序列化的边也算:一份账本上任何一条受保护的同库引用断了,这份导出都不可信,
/// 宁可整份拒。**必须在导出用的那条事务里跑**(REPEATABLE READ):
/// 体检与每一页查询看的是同一个快照,先体检后换连接会在两个时刻之间
/// 漏掉刚提交的坏行
pub async fn provenance_integrity(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
) -> AppResult<()> {
#[derive(sqlx::FromRow)]
struct ScanViolation {
edge: String,
kind: String,
rows: i64,
}
let violations: Vec<ScanViolation> = sqlx::query_as(PREFLIGHT_SQL)
.bind(kb_id)
.fetch_all(&mut **tx)
.await?;
let cross_kb: Vec<CrossKbViolation> = violations
.iter()
.filter(|v| v.kind == "cross_kb")
.map(|v| CrossKbViolation {
edge: v.edge.clone(),
rows: v.rows,
})
.collect();
let unexported: Vec<CrossKbViolation> = violations
.iter()
.filter(|v| v.kind == "unexported")
.map(|v| CrossKbViolation {
edge: v.edge.clone(),
rows: v.rows,
})
.collect();
if !cross_kb.is_empty() {
return Err(cross_kb_error(&cross_kb));
}
if !unexported.is_empty() {
return Err(unexported_error(&unexported));
}
Ok(())
}
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportClass {
pub id: Uuid,
pub key: String,
pub label: String,
pub description: String,
/// 导入来的类留着它原来的 IRI——schema.org 的 Organization 导出去还是
/// `schema:Organization`,读的人手里的词汇表对得上
pub iri: Option<String>,
pub parents: Vec<Uuid>,
pub disjoint: Vec<Uuid>,
}
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportRelation {
pub id: Uuid,
pub key: String,
pub label: String,
pub description: String,
pub iri: Option<String>,
/// relation | attribute(后者值域是字面值)
pub kind: String,
pub datatype: Option<String>,
pub unit: Option<String>,
pub temporal: String,
pub functional: bool,
pub inverse_functional: bool,
pub is_transitive: bool,
pub is_symmetric: bool,
pub is_asymmetric: bool,
pub is_irreflexive: bool,
/// 同表自指:导出 owl:inverseOf / rdfs:subPropertyOf。存量的合法性在
/// 迁移的递延约束里管,这里只负责把集合带上(越库/悬空 → 拒导)
pub inverse_of: Option<Uuid>,
pub sub_property_of: Option<Uuid>,
pub domains: Vec<Uuid>,
pub ranges: Vec<Uuid>,
}
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportEntity {
pub id: Uuid,
pub canonical_name: String,
pub type_id: Option<Uuid>,
/// type_id 指着的类的 kb(LEFT JOIN 一并选出)。别库/悬空 → 拒导:
/// 序列化按 id 进本库词汇表查类,查不着就是静默丢类型
pub type_kb: Option<Uuid>,
}
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportFact {
pub id: Uuid,
pub subject_id: Uuid,
pub predicate_id: Option<Uuid>,
/// 本体没接住这条关系时,模型的原话(0010)。导出去是为了让读的人看见
/// 「系统当时听见的是这个词,而词汇表里没有」
pub surface_predicate: Option<String>,
pub object_id: Option<Uuid>,
pub object_value: Option<serde_json::Value>,
/// 边上的属性(0037),加载后按事实 id 补
#[sqlx(skip)]
pub qualifiers: Vec<utopia_core::models::FactQualifier>,
pub valid_from: Option<DateTime<Utc>>,
pub valid_from_precision: Option<String>,
pub valid_to: Option<DateTime<Utc>>,
pub valid_to_precision: Option<String>,
/// 读出来的区间(0022):「现在仍成立」那条三元组按它判,不再自己解释 NULL
pub holds_from: Option<DateTime<Utc>>,
pub holds_to: Option<DateTime<Utc>>,
pub recorded_at: DateTime<Utc>,
pub invalidated_at: Option<DateTime<Utc>>,
pub confidence: f32,
/// 规则算出来的隐含行(0044 决定 3 第五片):读的人要能分辨它不是陈述直接说的
pub implied: bool,
pub supersedes: Option<Uuid>,
pub documents: Vec<Uuid>,
pub quotes: Vec<String>,
/// 证据文字的来源(0040),去重:一条陈述的引文里有没有扫描、转写、看图描述来的
pub quote_origins: Vec<String>,
/// 以下各列是被引行的 kb,与行本体原子地一并选出。
/// 别库或悬空(NULL)的引用不许被铸成本库 IRI,也不许静默跳过
pub subject_kb: Option<Uuid>,
pub object_kb: Option<Uuid>,
pub predicate_kb: Option<Uuid>,
pub supersedes_kb: Option<Uuid>,
/// documents[] 里是否有别库或悬空的文档指针
pub foreign_document: bool,
/// 引文 JOIN 的段落里是否有别库或悬空的(quote_origins 的来源会静默消失)
pub foreign_chunk: bool,
/// 主语/宾语指着**已合并**的实体:同库但不在导出集(merged_into IS NOT NULL
/// 的行 entities_page 不导)。与行本体原子地一并选出
pub subject_merged: bool,
pub object_merged: bool,
}
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportDerived {
pub id: Uuid,
pub subject_id: Uuid,
pub predicate_id: Uuid,
/// 字面值结论(业务规则的归类与属性)没有实体宾语(0021)
pub object_id: Option<Uuid>,
pub object_value: Option<serde_json::Value>,
/// 公理规则。业务规则推的为 None——它的身份在 attribute_rule_id 上
pub rule_id: Option<Uuid>,
pub attribute_rule_id: Option<Uuid>,
pub valid_from: Option<DateTime<Utc>>,
pub valid_from_precision: Option<String>,
pub valid_to: Option<DateTime<Utc>>,
pub valid_to_precision: Option<String>,
pub derived_at: DateTime<Utc>,
pub invalidated_at: Option<DateTime<Utc>>,
pub confidence: f32,
/// transitive | symmetric | inverse | sub_property,或 business
pub rule: String,
/// 公理规则声明在哪个谓词上(`rules.predicate_id`)。inverse 与 sub_property 时它
/// 不是结论的谓词,导出要写明(0020 的 2026-09-25 revision,#902)。业务规则为 None
pub rule_predicate: Option<Uuid>,
/// 业务规则的名字,进 RDF 当这条推理活动的标签
pub rule_name: Option<String>,
/// 前提事实。审计要顺着它往下走到句子
pub premises: Vec<Uuid>,
/// 前提里是**另一条派生**的那些(0030)。与上面那列分开,是因为读回来的人
/// 要知道该去哪张表接着往下走;合成一列的话,一条链在导出里就断了
pub premises_derived: Vec<Uuid>,
/// 被引行的 kb,与行本体原子地一并选出
pub subject_kb: Option<Uuid>,
pub object_kb: Option<Uuid>,
pub predicate_kb: Option<Uuid>,
/// rule_id / attribute_rule_id 指着的规则行的 kb——它铸成 wasGeneratedBy
/// 的 Activity IRI
pub rule_kb: Option<Uuid>,
pub attribute_rule_kb: Option<Uuid>,
/// premises[] / premises_derived[] 里是否有别库或悬空的前提(两种前提分开报边)
pub foreign_fact_premise: bool,
pub foreign_derived_premise: bool,
/// 主语/宾语指着已合并的实体:同库但不在导出集
pub subject_merged: bool,
pub object_merged: bool,
}
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportDocument {
pub id: Uuid,
pub filename: String,
pub external_key: Option<String>,
pub doc_time: Option<DateTime<Utc>>,
pub created_at: DateTime<Utc>,
/// 删过的文档留着墓碑(#268)。导出里它仍在,只是记录轴上已经结束
pub deleted_at: Option<DateTime<Utc>>,
}
pub async fn classes(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
) -> AppResult<Vec<ExportClass>> {
let classes: Vec<ExportClass> = sqlx::query_as(
"SELECT t.id, t.key, t.label, t.description, t.iri,
COALESCE(ARRAY(SELECT p.parent_id FROM entity_type_parents p
WHERE p.child_id = t.id ORDER BY p.parent_id), '{}') AS parents,
COALESCE(ARRAY(SELECT CASE WHEN d.a_id = t.id THEN d.b_id ELSE d.a_id END
FROM entity_type_disjoint d
WHERE d.kb_id = $1 AND (d.a_id = t.id OR d.b_id = t.id)
ORDER BY 1), '{}') AS disjoint
FROM entity_types t WHERE t.kb_id = $1 ORDER BY t.key",
)
.bind(kb_id)
.fetch_all(&mut **tx)
.await?;
// 父类与互斥类稍后要进本库词汇表按 id 查——查不着就是被静默丢掉。
// 能解析的就地解析:词汇表全集就在手里,不在集合里的引用就是越库/悬空
let own: std::collections::HashSet<Uuid> = classes.iter().map(|c| c.id).collect();
let mut violations = Vec::new();
for c in &classes {
let bad_parents = c.parents.iter().filter(|p| !own.contains(p)).count() as i64;
let bad_disjoint = c.disjoint.iter().filter(|p| !own.contains(p)).count() as i64;
tally(&mut violations, "class.parent", bad_parents);
tally(&mut violations, "class.disjoint", bad_disjoint);
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
Ok(classes)
}
pub async fn relations(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
) -> AppResult<Vec<ExportRelation>> {
let relations: Vec<ExportRelation> = sqlx::query_as(
"SELECT r.id, r.key, r.label, r.description, r.iri, r.kind, r.datatype, r.unit,
r.temporal, r.functional, r.inverse_functional,
r.is_transitive, r.is_symmetric, r.is_asymmetric, r.is_irreflexive,
r.inverse_of, r.sub_property_of,
COALESCE(ARRAY(SELECT d.entity_type_id FROM relation_type_domains d
WHERE d.relation_type_id = r.id ORDER BY 1), '{}') AS domains,
COALESCE(ARRAY(SELECT g.entity_type_id FROM relation_type_ranges g
WHERE g.relation_type_id = r.id ORDER BY 1), '{}') AS ranges
FROM relation_types r WHERE r.kb_id = $1 ORDER BY r.key",
)
.bind(kb_id)
.fetch_all(&mut **tx)
.await?;
// domain/range 的类 id 与 inverse/sub_property 的关系 id 都要进本库词汇表
// 查——查不着就静默丢公理。**两行全集都在手里**,不在集合里的引用就是
// 越库/悬空
let own_types: Vec<Uuid> = sqlx::query_scalar(
"SELECT COALESCE(ARRAY(SELECT id FROM entity_types WHERE kb_id = $1), '{}')",
)
.bind(kb_id)
.fetch_one(&mut **tx)
.await?;
let own: std::collections::HashSet<Uuid> = own_types.into_iter().collect();
let own_rel: std::collections::HashSet<Uuid> = relations.iter().map(|r| r.id).collect();
let mut violations = Vec::new();
for r in &relations {
let bad_domains = r.domains.iter().filter(|t| !own.contains(t)).count() as i64;
let bad_ranges = r.ranges.iter().filter(|t| !own.contains(t)).count() as i64;
tally(&mut violations, "relation.domain", bad_domains);
tally(&mut violations, "relation.range", bad_ranges);
if let Some(t) = r.inverse_of {
tally(
&mut violations,
"relation.inverse",
(!own_rel.contains(&t)) as i64,
);
}
if let Some(t) = r.sub_property_of {
tally(
&mut violations,
"relation.sub_property",
(!own_rel.contains(&t)) as i64,
);
}
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
Ok(relations)
}
/// 合并掉的实体不导出:它已经不是一个东西了,它的事实早已搬到留下的那个身上。
pub async fn entities_page(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
after: Option<Uuid>,
) -> AppResult<Vec<ExportEntity>> {
let page: Vec<ExportEntity> = sqlx::query_as(
"SELECT e.id, e.canonical_name, e.type_id, t.kb_id AS type_kb
FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
WHERE e.kb_id = $1 AND e.merged_into IS NULL
AND ($2 IS NULL OR e.id > $2)
ORDER BY e.id LIMIT $3",
)
.bind(kb_id)
.bind(after)
.bind(PAGE)
.fetch_all(&mut **tx)
.await?;
let mut violations = Vec::new();
for e in &page {
if e.type_id.is_some() && foreign(e.type_kb, kb_id) {
tally(&mut violations, "entity.type", 1);
}
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
Ok(page)
}
/// **不过滤 `invalidated_at`。** 撤回的、被修正顶掉的、区间早已闭合的,全在里面
/// ——它们各自带着两根轴上的时刻,读的人自己判断当时成立不成立(0019、0020)。
pub async fn facts_page(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
after: Option<Uuid>,
) -> AppResult<Vec<ExportFact>> {
let mut facts: Vec<ExportFact> = sqlx::query_as(&format!(
"SELECT f.id, f.subject_id, f.predicate_id,
fact_surface_predicate(f.id) AS surface_predicate,
f.object_id, f.object_value,
f.valid_from, f.valid_from_precision, f.valid_to, f.valid_to_precision,
{holds_from} AS holds_from, {holds_to} AS holds_to,
f.recorded_at, f.invalidated_at, f.confidence, f.implied, f.supersedes,
COALESCE(ARRAY(SELECT DISTINCT e.document_id FROM fact_evidence e
WHERE e.fact_id = f.id AND e.document_id IS NOT NULL), '{{}}')
AS documents,
COALESCE(ARRAY(SELECT e.quote FROM fact_evidence e
WHERE e.fact_id = f.id AND e.quote IS NOT NULL
ORDER BY e.chunk_id), '{{}}') AS quotes,
COALESCE(ARRAY(SELECT DISTINCT c.origin FROM fact_evidence e
JOIN chunks c ON c.id = e.chunk_id
WHERE e.fact_id = f.id ORDER BY c.origin), '{{}}')
AS quote_origins,
s.kb_id AS subject_kb, o.kb_id AS object_kb,
p.kb_id AS predicate_kb, sp.kb_id AS supersedes_kb,
EXISTS(SELECT 1 FROM fact_evidence e
LEFT JOIN documents ed ON ed.id = e.document_id
WHERE e.fact_id = f.id AND e.document_id IS NOT NULL
AND ed.kb_id IS DISTINCT FROM f.kb_id) AS foreign_document,
EXISTS(SELECT 1 FROM fact_evidence e
LEFT JOIN chunks ec ON ec.id = e.chunk_id
WHERE e.fact_id = f.id
AND ec.kb_id IS DISTINCT FROM f.kb_id) AS foreign_chunk,
(s.merged_into IS NOT NULL) AS subject_merged,
(o.merged_into IS NOT NULL) AS object_merged
FROM facts f
LEFT JOIN entities s ON s.id = f.subject_id
LEFT JOIN entities o ON o.id = f.object_id
LEFT JOIN relation_types p ON p.id = f.predicate_id
LEFT JOIN facts sp ON sp.id = f.supersedes
WHERE f.kb_id = $1 AND ($2 IS NULL OR f.id > $2)
ORDER BY f.id LIMIT $3",
holds_from = crate::world_axis::facts_holds_from("f"),
holds_to = crate::world_axis::facts_holds_to("f"),
))
.bind(kb_id)
.bind(after)
.bind(PAGE)
.fetch_all(&mut **tx)
.await?;
// 留下的行逐个过:被铸成本库 IRI 的引用不许越库,进词汇表的引用不许查空。
// 检查用的是随行原子选出的 ref_kb——不是再去库里问一次的另一个时刻
let mut violations = Vec::new();
let mut unexported = Vec::new();
for f in &facts {
tally(
&mut violations,
"fact.subject",
foreign(f.subject_kb, kb_id) as i64,
);
tally(
&mut unexported,
"fact.subject(merged)",
f.subject_merged as i64,
);
if f.object_id.is_some() {
tally(
&mut violations,
"fact.object",
foreign(f.object_kb, kb_id) as i64,
);
tally(
&mut unexported,
"fact.object(merged)",
f.object_merged as i64,
);
}
if f.predicate_id.is_some() {
tally(
&mut violations,
"fact.predicate",
foreign(f.predicate_kb, kb_id) as i64,
);
}
if f.supersedes.is_some() {
tally(
&mut violations,
"fact.supersedes",
foreign(f.supersedes_kb, kb_id) as i64,
);
}
tally(
&mut violations,
"evidence.document",
f.foreign_document as i64,
);
tally(&mut violations, "evidence.chunk", f.foreign_chunk as i64);
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
if !unexported.is_empty() {
return Err(unexported_error(&unexported));
}
// 边上的属性另一张表(0037),按事实 id 一次取回补上——把属性类型的 kb 与
// 实体值的 kb 一并选出:别库类型会被词汇表静默跳过,别库实体会被铸进本库
// IRI,两种行都得在序列化之前拦下来
{
let ids: Vec<Uuid> = facts.iter().map(|f| f.id).collect();
let mut by_fact = qualifiers_for_export(tx, &ids, kb_id).await?;
for f in facts.iter_mut() {
if let Some(q) = by_fact.remove(&f.id) {
f.qualifiers = q;
}
}
}
Ok(facts)
}
#[derive(sqlx::FromRow)]
struct ExportQualifierRow {
fact_id: Uuid,
qualifier_type_id: Uuid,
key: Option<String>,
label: Option<String>,
value: Option<serde_json::Value>,
entity_id: Option<Uuid>,
entity_name: Option<String>,
type_kb: Option<Uuid>,
entity_kb: Option<Uuid>,
entity_merged: bool,
}
/// 导出专用的属性取数:与 graph::fact_qualifiers_for 同一形状,多选两列 kb。
/// 那边用 INNER JOIN——被引类型不在时整行属性**静默消失**;导出不能这么吞。
/// 别库的属性类型会被词汇表查空而静默跳过,别库的实体值会被铸进本库
/// entity IRI——两种都按坏行拒
async fn qualifiers_for_export(
tx: &mut Transaction<'_, Postgres>,
fact_ids: &[Uuid],
kb_id: Uuid,
) -> AppResult<std::collections::HashMap<Uuid, Vec<utopia_core::models::FactQualifier>>> {
let mut out: std::collections::HashMap<Uuid, Vec<utopia_core::models::FactQualifier>> =
std::collections::HashMap::new();
if fact_ids.is_empty() {
return Ok(out);
}
let rows: Vec<ExportQualifierRow> = sqlx::query_as(
"SELECT q.fact_id, q.qualifier_type_id, r.key, r.label, q.value, q.entity_id,
e.canonical_name AS entity_name,
r.kb_id AS type_kb, e.kb_id AS entity_kb,
(e.merged_into IS NOT NULL) AS entity_merged
FROM fact_qualifiers q
LEFT JOIN relation_types r ON r.id = q.qualifier_type_id
LEFT JOIN entities e ON e.id = q.entity_id
WHERE q.fact_id = ANY($1)
ORDER BY q.fact_id, r.key",
)
.bind(fact_ids)
.fetch_all(&mut **tx)
.await?;
let mut violations = Vec::new();
let mut unexported = Vec::new();
for r in &rows {
tally(
&mut violations,
"qualifier.type",
foreign(r.type_kb, kb_id) as i64,
);
if r.entity_id.is_some() {
tally(
&mut violations,
"qualifier.entity",
foreign(r.entity_kb, kb_id) as i64,
);
tally(
&mut unexported,
"qualifier.entity(merged)",
r.entity_merged as i64,
);
}
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
if !unexported.is_empty() {
return Err(unexported_error(&unexported));
}
for r in rows {
out.entry(r.fact_id)
.or_default()
.push(utopia_core::models::FactQualifier {
qualifier_type_id: r.qualifier_type_id,
// 过了校验 r 必然在:key/label 不会取不到
key: r.key.unwrap_or_default(),
label: r.label.unwrap_or_default(),
value: r.value,
entity_id: r.entity_id,
entity_name: r.entity_name,
});
}
Ok(out)
}
pub async fn derived_page(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
after: Option<Uuid>,
) -> AppResult<Vec<ExportDerived>> {
let page: Vec<ExportDerived> = sqlx::query_as(
// **两个 LEFT JOIN。** 表拓宽之后(0021)派生可能没有实体宾语、
// 也可能来自业务规则而不是公理——内连接会把这类结论整条挡在导出之外,
// 而 0020 承诺的正是「审计员不靠我们也能读全」
"SELECT d.id, d.subject_id, d.predicate_id, d.object_id, d.object_value,
d.rule_id, d.attribute_rule_id,
d.valid_from, d.valid_from_precision, d.valid_to, d.valid_to_precision,
d.derived_at, d.invalidated_at, d.confidence,
COALESCE(ru.kind, 'business') AS rule, ru.predicate_id AS rule_predicate,
ar.name AS rule_name,
COALESCE(ARRAY(SELECT fd.premise_fact_id FROM fact_derivations fd
WHERE fd.derived_fact_id = d.id
AND fd.premise_fact_id IS NOT NULL
ORDER BY fd.seq), '{}') AS premises,
COALESCE(ARRAY(SELECT fd.premise_derived_id FROM fact_derivations fd
WHERE fd.derived_fact_id = d.id
AND fd.premise_derived_id IS NOT NULL
ORDER BY fd.seq), '{}') AS premises_derived,
s.kb_id AS subject_kb, o.kb_id AS object_kb, p.kb_id AS predicate_kb,
ru.kb_id AS rule_kb, ar.kb_id AS attribute_rule_kb,
EXISTS(SELECT 1 FROM fact_derivations fd
LEFT JOIN facts pf ON pf.id = fd.premise_fact_id
WHERE fd.derived_fact_id = d.id AND fd.premise_fact_id IS NOT NULL
AND pf.kb_id IS DISTINCT FROM d.kb_id) AS foreign_fact_premise,
EXISTS(SELECT 1 FROM fact_derivations fd
LEFT JOIN derived_facts pd ON pd.id = fd.premise_derived_id
WHERE fd.derived_fact_id = d.id AND fd.premise_derived_id IS NOT NULL
AND pd.kb_id IS DISTINCT FROM d.kb_id) AS foreign_derived_premise,
(s.merged_into IS NOT NULL) AS subject_merged,
(o.merged_into IS NOT NULL) AS object_merged
FROM derived_facts d
LEFT JOIN rules ru ON ru.id = d.rule_id
LEFT JOIN attribute_rules ar ON ar.id = d.attribute_rule_id
LEFT JOIN entities s ON s.id = d.subject_id
LEFT JOIN entities o ON o.id = d.object_id
LEFT JOIN relation_types p ON p.id = d.predicate_id
WHERE d.kb_id = $1 AND ($2 IS NULL OR d.id > $2)
ORDER BY d.id LIMIT $3",
)
.bind(kb_id)
.bind(after)
.bind(PAGE)
.fetch_all(&mut **tx)
.await?;
let mut violations = Vec::new();
let mut unexported = Vec::new();
for d in &page {
tally(
&mut violations,
"derived.subject",
foreign(d.subject_kb, kb_id) as i64,
);
tally(
&mut unexported,
"derived.subject(merged)",
d.subject_merged as i64,
);
if d.object_id.is_some() {
tally(
&mut violations,
"derived.object",
foreign(d.object_kb, kb_id) as i64,
);
tally(
&mut unexported,
"derived.object(merged)",
d.object_merged as i64,
);
}
// 派生的谓词非空(CHECK 保证),NULL 的 ref_kb 一样是越界/悬空
tally(
&mut violations,
"derived.predicate",
foreign(d.predicate_kb, kb_id) as i64,
);
if d.rule_id.is_some() {
tally(
&mut violations,
"derived.rule",
foreign(d.rule_kb, kb_id) as i64,
);
}
if d.attribute_rule_id.is_some() {
tally(
&mut violations,
"derived.attribute_rule",
foreign(d.attribute_rule_kb, kb_id) as i64,
);
}
tally(
&mut violations,
"derivation.premise_fact",
d.foreign_fact_premise as i64,
);
tally(
&mut violations,
"derivation.premise_derived",
d.foreign_derived_premise as i64,
);
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
if !unexported.is_empty() {
return Err(unexported_error(&unexported));
}
Ok(page)
}
pub async fn documents_page(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
after: Option<Uuid>,
) -> AppResult<Vec<ExportDocument>> {
Ok(sqlx::query_as(
"SELECT id, filename, external_key, doc_time, created_at, deleted_at
FROM documents
WHERE kb_id = $1 AND ($2 IS NULL OR id > $2)
ORDER BY id LIMIT $3",
)
.bind(kb_id)
.bind(after)
.bind(PAGE)
.fetch_all(&mut **tx)
.await?)
}
/* ---- 认知状态(0062)----
*
* 两张表两种东西,不合成一类:
* fact_conflicts 同一槽位上两条断言互不相让——数据里有争议,判据没毛病
* axiom_violations 当前数据撞上当前判据——数据或本体至少一边要动
*
* 只读:不走 `temporal::list_conflicts` 那种带惰性清理的读面(0051 已把它删了),
* 也不触发检出。导出的是库里记下的状态。 */
/// 两条事实争同一个槽位。`resolved` 的行也在——它记的是有过的争议,不是
/// 待办;`withdrawn` 的是事实作废后由触发器退场的(0051),`resolved_at` 记的是
/// 作废时刻,不是有人开过页面
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportFactConflict {
pub id: Uuid,
pub old_fact_id: Uuid,
pub new_fact_id: Uuid,
/// 争议怎么被记下的:no_time | simultaneous | low_confidence | described_evidence
/// (此列无 CHECK,库里的旧值也可能进来;合同词表以 contest_integrity 为准)
pub reason: String,
pub created_at: DateTime<Utc>,
/// open | resolved | withdrawn
pub status: String,
/// closed | kept_both | rejected_new;只在 resolved 时有
pub resolution: Option<String>,
/// resolved:裁决时刻;withdrawn:先作废那一边的时刻(0051)
pub resolved_at: Option<DateTime<Utc>>,
/// 两条事实的 kb,随行原子地一并选出:越库/悬空 → 拒导
pub old_fact_kb: Option<Uuid>,
pub new_fact_kb: Option<Uuid>,
}
pub async fn fact_conflicts_page(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
after: Option<Uuid>,
) -> AppResult<Vec<ExportFactConflict>> {
let page: Vec<ExportFactConflict> = sqlx::query_as(
"SELECT c.id, c.old_fact_id, c.new_fact_id, c.reason, c.created_at,
c.status, c.resolution, c.resolved_at,
of_.kb_id AS old_fact_kb, nf.kb_id AS new_fact_kb
FROM fact_conflicts c
LEFT JOIN facts of_ ON of_.id = c.old_fact_id
LEFT JOIN facts nf ON nf.id = c.new_fact_id
WHERE c.kb_id = $1 AND ($2 IS NULL OR c.id > $2)
ORDER BY c.id LIMIT $3",
)
.bind(kb_id)
.bind(after)
.bind(PAGE)
.fetch_all(&mut **tx)
.await?;
let mut violations = Vec::new();
for c in &page {
tally(
&mut violations,
"conflict.old_fact",
foreign(c.old_fact_kb, kb_id) as i64,
);
tally(
&mut violations,
"conflict.new_fact",
foreign(c.new_fact_kb, kb_id) as i64,
);
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
Ok(page)
}
/// 一条「当前数据与当前判据不一致」的发现。`open` 意味着它已对账于**当前**
/// 本体(0062)——改判据的那笔事务把它收编或重检出过了。
///
/// 行是**可变的当前状态**,不是追加历史:resolved 之后又被算出来的同一处
/// 违规会重开,`detected_at` 记的是最近一次检出/重开的时刻;更早的循环
/// 不留在行里,导出也就照实不说它。
#[derive(Debug, Clone, sqlx::FromRow)]
pub struct ExportAxiomViolation {
pub id: Uuid,
pub kind: String,
pub left_fact: Uuid,
pub right_fact: Uuid,
/// 环按顺序的完整事实链(其余种类存检出的证据,自环/签名为空)
pub path: Vec<Uuid>,
pub status: String,
/// fact_retracted | fact_closed | axiom_relaxed | accepted | criterion_changed
pub resolution: Option<String>,
/// 最近一次检出或重开的时刻(不是第一次发现)
pub detected_at: DateTime<Utc>,
/// 不再是 open 的时刻(收编或人裁)
pub decided_at: Option<DateTime<Utc>>,
/// 以下两列**只在 open 行上解析**(0062):open = 已按当前本体对账,
/// 判据必然指得回去;resolved 的行不连判据——促成它结案的本体可能早已不在
pub criterion_predicate: Option<Uuid>,
/// 判据的词:kind 本身,或 derived_contradiction 记下的 detail.axiom
/// (self_loop | asymmetry | cycle | functional | inverse_functional | signature)
pub criterion_axiom: Option<String>,
/// 被引行的 kb,随行原子地一并选出
pub left_kb: Option<Uuid>,
pub right_kb: Option<Uuid>,
pub criterion_predicate_kb: Option<Uuid>,
/// path 里是否有越库或悬空的事实(环的证据链会按序铸成 IRI)
pub foreign_path: bool,
}
/// detail.predicate_id 存成 JSON 文本,落到 uuid 前先验形——
/// 畸形的值宁可解析失败(→ 拒导)也不能静默指错关系
const UUID_TEXT_RE: &str =
"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
/// open 行的判据谓词解析式:derived_contradiction 的判据挂在 detail 记下的
/// **派生谓词**上(axiom 声明在它那里);其余种类就是 left_fact 的谓词。
/// 分页与预检共用同一串——两处各写一份迟早漂移
fn criterion_predicate_sql() -> String {
format!(
"CASE WHEN v.kind = 'derived_contradiction'
THEN CASE WHEN v.detail->>'predicate_id' ~ '{UUID_TEXT_RE}'
THEN (v.detail->>'predicate_id')::uuid END
ELSE lf.predicate_id END"
)
}
/// open 行的判据词解析式:derived_contradiction 看 detail.axiom,其余看 kind
const CRITERION_AXIOM_SQL: &str =
"CASE WHEN v.kind = 'derived_contradiction' THEN v.detail->>'axiom' ELSE v.kind END";
/// kind / detail.axiom 的存储值 → 判据该用的词(0062 §4)。
/// signature 的判据是一对签名(行不记哪一侧破的,合同也不装知道)。
/// None = 不认识的存储值——open 行撞上它就要拒导,不能静默丢判据
fn criterion_terms(axiom: &str) -> Option<&'static [&'static str]> {
Some(match axiom {
"self_loop" => &["owl:IrreflexiveProperty"],
"asymmetry" => &["owl:AsymmetricProperty"],
"cycle" => &["owl:TransitiveProperty"],
"functional" => &["owl:FunctionalProperty"],
"inverse_functional" => &["owl:InverseFunctionalProperty"],
"signature" => &["rdfs:domain", "rdfs:range"],
_ => return None,
})
}
impl ExportAxiomViolation {
/// 判据的 RDF 词项(`utopia:criterion` 的宾语,可能不止一个)。
/// open 行必然取得到——取不到说明存储值进了合同不认识的东西,拒导而不是瞎编
pub fn criterion_terms(&self) -> Option<&'static [&'static str]> {
self.criterion_axiom.as_deref().and_then(criterion_terms)
}
}
pub async fn axiom_violations_page(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
after: Option<Uuid>,
) -> AppResult<Vec<ExportAxiomViolation>> {
let page: Vec<ExportAxiomViolation> = sqlx::query_as(&format!(
"SELECT v.id, v.kind, v.left_fact, v.right_fact, v.path, v.status, v.resolution,
v.detected_at, v.decided_at,
CASE WHEN v.status = 'open' THEN {criterion_predicate}
END AS criterion_predicate,
CASE WHEN v.status = 'open' THEN {criterion_axiom}
END AS criterion_axiom,
lf.kb_id AS left_kb, rf.kb_id AS right_kb, cp.kb_id AS criterion_predicate_kb,
EXISTS(SELECT 1 FROM unnest(v.path) AS member(fact_id)
WHERE NOT EXISTS(SELECT 1 FROM facts pf
WHERE pf.id = member.fact_id
AND pf.kb_id = v.kb_id)) AS foreign_path
FROM axiom_violations v
LEFT JOIN facts lf ON lf.id = v.left_fact
LEFT JOIN facts rf ON rf.id = v.right_fact
LEFT JOIN relation_types cp ON cp.id =
CASE WHEN v.status = 'open' THEN {criterion_predicate} END
WHERE v.kb_id = $1 AND ($2 IS NULL OR v.id > $2)
ORDER BY v.id LIMIT $3",
criterion_predicate = criterion_predicate_sql(),
criterion_axiom = CRITERION_AXIOM_SQL,
))
.bind(kb_id)
.bind(after)
.bind(PAGE)
.fetch_all(&mut **tx)
.await?;
let mut violations = Vec::new();
let mut unresolvable = Vec::new();
for v in &page {
tally(
&mut violations,
"violation.left_fact",
foreign(v.left_kb, kb_id) as i64,
);
tally(
&mut violations,
"violation.right_fact",
foreign(v.right_kb, kb_id) as i64,
);
tally(&mut violations, "violation.path", v.foreign_path as i64);
if v.status == "open" {
// open 的承诺是「已按当前本体对账」:判据指不回去,这份导出就在
// 替一个坏掉的不变式背书——拒导与越库同一条纪律
if v.criterion_predicate.is_none() || v.criterion_terms().is_none() {
unresolvable.push(CrossKbViolation {
edge: "violation.criterion".into(),
rows: 1,
});
} else {
tally(
&mut violations,
"violation.criterion",
foreign(v.criterion_predicate_kb, kb_id) as i64,
);
}
}
}
if !violations.is_empty() {
return Err(cross_kb_error(&violations));
}
if !unresolvable.is_empty() {
let detail = unresolvable
.iter()
.map(|v| format!("{}: {} row(s)", v.edge, v.rows))
.collect::<Vec<_>>()
.join("; ");
return Err(AppError::invalid_detail(
"unresolvable_criterion",
"export refused: an open axiom violation has no governing criterion to link",
detail,
));
}
Ok(page)
}
/// 认知状态的**流前预检**(0062):分页查询里也带同一批检查,但那时文件头
/// 已经发出去,只能截断——所以先在这里数一遍,有一行就整份拒。
///
/// 三类问题:
/// - **越库/悬空**:conflict 的两条事实、violation 的 left/right/path 成员必须
/// 是本库的 facts 行(悬空=铸出不存在的 IRI,与越库同罪)
/// - **合同外的值**:status/resolution/kind/reason 落进词表以外、或
/// status↔resolution 不自洽(open 带着 resolution 之类)的脏行——
/// `fact_conflicts.reason` 没有 CHECK 挡着,其余列有但 CHECK 只在新写时
/// 生效,存量脏行一样照实拒,不 echo 出去
/// - **open 行判据不可解析**:open = 已对账于当前本体,判据必然指得回本库
/// 一条关系与一个合同认识的词(derived_contradiction 的 detail.predicate_id
/// 畸形也算——静默退到 left_fact 的谓词等于瞎指)
pub async fn contest_integrity(tx: &mut Transaction<'_, Postgres>, kb_id: Uuid) -> AppResult<()> {
#[derive(sqlx::FromRow)]
struct ContestViolation {
edge: String,
kind: String,
rows: i64,
}
let violations: Vec<ContestViolation> = sqlx::query_as(&format!(
"SELECT edge, kind, count(*) AS rows FROM (
SELECT 'conflict.old_fact' AS edge, 'cross_kb' AS kind
FROM fact_conflicts c LEFT JOIN facts f ON f.id = c.old_fact_id
WHERE c.kb_id = $1 AND f.kb_id IS DISTINCT FROM c.kb_id
UNION ALL
SELECT 'conflict.new_fact', 'cross_kb'
FROM fact_conflicts c LEFT JOIN facts f ON f.id = c.new_fact_id
WHERE c.kb_id = $1 AND f.kb_id IS DISTINCT FROM c.kb_id
UNION ALL
SELECT 'conflict.vocabulary', 'contract'
FROM fact_conflicts c
WHERE c.kb_id = $1 AND (
COALESCE(c.status, '') NOT IN ('open', 'resolved', 'withdrawn')
OR COALESCE(c.reason, '') NOT IN
('no_time', 'simultaneous', 'low_confidence', 'described_evidence')
OR c.resolution IS NOT NULL
AND c.resolution NOT IN ('closed', 'kept_both', 'rejected_new')
-- 0051:resolved=人裁了(resolution 必有值),其余状态不该有
OR c.status = 'resolved' AND c.resolution IS NULL
OR c.status IN ('open', 'withdrawn') AND c.resolution IS NOT NULL)
UNION ALL
SELECT 'violation.left_fact', 'cross_kb'
FROM axiom_violations v LEFT JOIN facts f ON f.id = v.left_fact
WHERE v.kb_id = $1 AND f.kb_id IS DISTINCT FROM v.kb_id
UNION ALL
SELECT 'violation.right_fact', 'cross_kb'
FROM axiom_violations v LEFT JOIN facts f ON f.id = v.right_fact
WHERE v.kb_id = $1 AND f.kb_id IS DISTINCT FROM v.kb_id
UNION ALL
SELECT 'violation.path', 'cross_kb'
FROM axiom_violations v
WHERE v.kb_id = $1 AND EXISTS(
SELECT 1 FROM unnest(v.path) AS member(fact_id)
WHERE NOT EXISTS(SELECT 1 FROM facts pf
WHERE pf.id = member.fact_id
AND pf.kb_id = v.kb_id))
UNION ALL
SELECT 'violation.vocabulary', 'contract'
FROM axiom_violations v
WHERE v.kb_id = $1 AND (
COALESCE(v.kind, '') NOT IN
('self_loop', 'asymmetry', 'cycle', 'functional',
'inverse_functional', 'signature', 'derived_contradiction')
OR COALESCE(v.status, '') NOT IN ('open', 'resolved')
OR v.resolution IS NOT NULL AND v.resolution NOT IN
('fact_retracted', 'fact_closed', 'axiom_relaxed', 'accepted',
'criterion_changed')
-- 写路从来都是成对落(决定+时间戳);open 带着 resolution
-- 或 resolved 丢了 resolution 都是自相矛盾的脏行
OR v.status = 'resolved' AND v.resolution IS NULL
OR v.status = 'open' AND v.resolution IS NOT NULL)
UNION ALL
SELECT 'violation.criterion', 'unresolvable'
FROM axiom_violations v
LEFT JOIN facts lf ON lf.id = v.left_fact
WHERE v.kb_id = $1 AND v.status = 'open' AND (
COALESCE({criterion_axiom}, '') NOT IN
('self_loop', 'asymmetry', 'cycle', 'functional',
'inverse_functional', 'signature')
OR NOT EXISTS(
SELECT 1 FROM relation_types rt
WHERE rt.kb_id = v.kb_id
AND rt.id = {criterion_predicate}))
) t GROUP BY edge, kind",
criterion_axiom = CRITERION_AXIOM_SQL,
criterion_predicate = criterion_predicate_sql(),
))
.bind(kb_id)
.fetch_all(&mut **tx)
.await?;
let cross_kb: Vec<CrossKbViolation> = violations
.iter()
.filter(|v| v.kind == "cross_kb")
.map(|v| CrossKbViolation {
edge: v.edge.clone(),
rows: v.rows,
})
.collect();
if !cross_kb.is_empty() {
return Err(cross_kb_error(&cross_kb));
}
let rest: Vec<&ContestViolation> = violations.iter().filter(|v| v.kind != "cross_kb").collect();
if !rest.is_empty() {
let detail = rest
.iter()
.map(|v| format!("{}: {} row(s)", v.edge, v.rows))
.collect::<Vec<_>>()
.join("; ");
return Err(AppError::invalid_detail(
"contested_state_contract",
"export refused: contested-state rows fall outside the contract vocabulary or an open violation has no resolvable criterion",
detail,
));
}
Ok(())
}