World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 时态引擎(S3):functional 状态关系的矛盾检测与自动闭合。
//!
//! 原则:
//! - 纯规则判定,零 LLM——模糊性已在上游(消解归并实体、本体标 functional)消化
//! - 闭合走"作废 + 改写"而非原地改:旧断言 invalidated_at 记下"何时被修正",
//! 修正行闭合区间并以 supersedes 链回旧行——"以当时的认知回放当时"得以成立
//! - 闭合点只用世界时间:后任的 valid_from;后任没有起点时,前任写成「结束了,不知哪天」,
//! 锚在后任的事实见证上(0022 的形状,0064 的章节日期)。见证日期从不写进日期列
//! - 拿不准(缺时间/同时开始/低置信)绝不硬闭合,进 fact_conflicts 由人裁决
//!
//! **一条时间线是一个整体。** 同一 (库, 持有者, 谓词, 唯一性方向) 的所有现存行按时间排成
//! 一列。一行的终点要么是原文或人写明的,从不重算;要么由引擎推出(`facts.end_derived`,
//! 0057):开着的行、引擎关上的行,都止于它之后最近的另一个值开始时。事实落库或又被观察到、
//! 合并搬来或撤回、文档删除或恢复,都把这一列按当下有哪些行**一次**重算到这个形状——结果
//! 只取决于有哪些行,与它们到达的先后无关(#679)。
//!
//! 一条关系两侧都唯一(functional 且 inverse functional,「一个人同时只领导一个项目,一个
//! 项目同时只有一个领导」)时,一行同时在两条时间线上:它的终点是两侧各推一个、取早的那个。
//!
//! 重算在一个事务里、持着这条时间线的咨询锁做完。一次要动几条时间线的事务(撤回合并、删除
//! 文档)先按固定顺序把这些锁全拿到,再改任何一行:落库对账也是先拿锁再锁行,两边顺序一致,
//! 谁也不会拿着行锁去等咨询锁。两侧都唯一的关系一条谓词一把锁——重算一侧要读另一侧。
use std::collections::{BTreeSet, HashMap, HashSet};
use chrono::{DateTime, Utc};
use sqlx::{PgPool, Postgres, Transaction};
use utopia_core::models::ConflictView;
use utopia_core::AppResult;
use uuid::Uuid;
/// 事实自己的见证,与世界轴的下界同源(0064)。同一版文档的不同章节可以有不同日期;
/// NULL 明确表示没有时间,不能退回文档日期。类型化行由来源陈述同步这份见证。
const DATED_AT: &str = "f.attested_from";
/// 这一行的出处里有看图描述出来的文字吗,按 `facts` 的别名 `f` 投影(0040 决定 4)。
/// 类型化的行自己没有出处,它的出处是物化它的那些陈述的(0044 第 2 刀)
const DESCRIBED: &str = "(EXISTS (SELECT 1 FROM fact_evidence fe
JOIN chunks ch ON ch.id = fe.chunk_id
WHERE fe.fact_id = f.id AND ch.origin = 'described')
OR EXISTS (SELECT 1 FROM typed_fact_sources ts
JOIN fact_evidence fe ON fe.fact_id = ts.statement_id
JOIN chunks ch ON ch.id = fe.chunk_id
WHERE ts.fact_id = f.id AND ch.origin = 'described'))";
/// [`DESCRIBED`] 换成另一个别名:读的时候找关上一行的后任(#970),与引擎排除同样的行
pub(crate) fn described_sql(alias: &str) -> String {
DESCRIBED.replace("= f.id", &format!("= {alias}.id"))
}
/// 唯一性方向:functional = 主语侧(张三同时只 reports_to 一人);
/// inverse functional = 宾语侧(一个项目同时只有一个 leads 它的人)。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Uniqueness {
SubjectSide,
ObjectSide,
}
impl Uniqueness {
fn other(self) -> Self {
match self {
Self::SubjectSide => Self::ObjectSide,
Self::ObjectSide => Self::SubjectSide,
}
}
}
/// 一条唯一性时间线:谁(持有者)在哪个谓词、哪个方向上同时只能有一个值
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Timeline {
pub holder: Uuid,
pub predicate_id: Uuid,
pub side: Uniqueness,
/// 谓词两侧都唯一:这条线上的每一行也在另一侧的一条线上
pub both_sides: bool,
}
impl Timeline {
fn lock_key(&self, kb_id: Uuid) -> String {
if self.both_sides {
format!("timeline:{kb_id}:{}:both", self.predicate_id)
} else {
format!(
"timeline:{kb_id}:{}:{}:{:?}",
self.holder, self.predicate_id, self.side
)
}
}
}
/// 对账结果:自动闭合产生的修正行 id(调用方按需记账)与这次新进人审的冲突数。
#[derive(Debug, Default)]
pub struct ReconcileReport {
pub corrected: Vec<Uuid>,
pub conflicts: u32,
}
/// 时间线上的一行
#[derive(Debug, Clone, sqlx::FromRow)]
struct Row {
id: Uuid,
subject_id: Uuid,
object_id: Option<Uuid>,
object_value: Option<serde_json::Value>,
valid_from: Option<DateTime<Utc>>,
valid_from_precision: Option<String>,
valid_to: Option<DateTime<Utc>>,
valid_to_precision: Option<String>,
attested_to: Option<DateTime<Utc>>,
end_derived: bool,
dated_at: Option<DateTime<Utc>>,
/// 起点是怎么来的:`A` 写明、`B` 按文档自己的锚点算出、`C` 有时间词却锚不到;
/// `None` = 没经过时间解析(人写的、规则算的),按 A 算
valid_from_grade: Option<String>,
/// 这一行的出处里有看图描述出来的文字(0040 决定 4)
described: bool,
}
/// 一行的终点
#[derive(Debug, Clone, PartialEq)]
enum End {
/// 仍在持续
Open,
/// 在这一刻结束,带精度
At(DateTime<Utc>, String),
/// 结束了,不知哪天;读出侧读到锚点为止
Unknown(Option<DateTime<Utc>>),
}
impl End {
/// 读出来止于哪一刻;开着的没有
fn instant(&self) -> Option<DateTime<Utc>> {
match self {
End::Open => None,
End::At(at, _) => Some(*at),
End::Unknown(anchor) => *anchor,
}
}
/// 两个终点里早的那个;同一刻时写着日期的胜过锚点
fn earlier(self, other: End) -> End {
match (self.instant(), other.instant()) {
(None, _) => other,
(_, None) => self,
(Some(a), Some(b)) if b < a => other,
(Some(a), Some(b)) if a == b && matches!(other, End::At(..)) => other,
_ => self,
}
}
}
impl Row {
/// 这一行的起点锚不到吗:有时间词、代码没能把它放到世界轴上(等级 C)。**没有等级
/// 的行不算**——它的日期是直接给的(人写的、规则算的、这一列之前的每一行),不是
/// 从别处猜的。锚不到的行仍进得了时间线(它按见证日期排),只是不许它改写历史
fn start_unanchored(&self) -> bool {
self.valid_from_grade.as_deref() == Some("C")
}
/// 排序用的时刻:起点。没有起点时,事实的见证——但只对还开着、或者由引擎
/// 关上的行成立:它们的证据说那天还成立。原文说已经结束的行,证据的日期只说明「那天
/// 之前结束了」,拿它排序会让一个早就结束的值去关上当下的值(#679 第三轮评审)
fn key(&self) -> Option<DateTime<Utc>> {
match self.valid_from {
Some(start) => Some(start),
None if self.is_open() || self.end_derived => self.dated_at,
None => None,
}
}
fn is_open(&self) -> bool {
self.valid_to.is_none() && self.valid_to_precision.is_none()
}
/// 终点由引擎按时间线定:开着的,或引擎关上的
fn recomputable(&self) -> bool {
self.is_open() || self.end_derived
}
/// 终点的时刻:日期;「结束了,不知哪天」的锚点(读出侧同样读到它为止)
fn end(&self) -> Option<DateTime<Utc>> {
match (self.valid_to, self.valid_to_precision.as_deref()) {
(Some(to), _) => Some(to),
(None, Some(crate::graph::ENDED_UNKNOWN)) => self.attested_to,
_ => None,
}
}
/// 眼下写着的终点
fn current_end(&self) -> End {
match (self.valid_to, self.valid_to_precision.as_deref()) {
(Some(to), p) => End::At(to, p.unwrap_or("day").to_string()),
(None, Some(crate::graph::ENDED_UNKNOWN)) => End::Unknown(self.attested_to),
_ => End::Open,
}
}
/// 前一段止于这一行开始时,终点写成什么:有起点就是那一刻;没有起点,是「结束了,
/// 不知哪天」,锚在这一行的见证上
fn end_before(&self) -> End {
match self.valid_from {
Some(start) => {
let precision = self.valid_from_precision.as_deref().unwrap_or("day");
End::At(
crate::graph::truncate_to(start, Some(precision)),
precision.to_string(),
)
}
None => End::Unknown(self.dated_at),
}
}
/// 在 `at` 这一刻还成立
fn holds_at(&self, at: DateTime<Utc>) -> bool {
self.is_open() || self.end().is_some_and(|end| end > at)
}
/// 这一行在 `side` 那一侧的持有者
fn holder(&self, side: Uniqueness) -> Option<Uuid> {
match side {
Uniqueness::SubjectSide => Some(self.subject_id),
Uniqueness::ObjectSide => self.object_id,
}
}
}
/// 两行说的是不是同一个值(同一侧:主语侧比宾语,宾语侧比主语)
fn same_value(side: Uniqueness, a: &Row, b: &Row) -> bool {
match side {
Uniqueness::SubjectSide => a.object_id == b.object_id && a.object_value == b.object_value,
Uniqueness::ObjectSide => a.subject_id == b.subject_id,
}
}
async fn lock_timeline(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
timeline: Timeline,
) -> AppResult<()> {
lock_timelines(tx, kb_id, &[timeline]).await
}
/// 一次锁的时间线超过这么多条,改拿谓词一级的排他锁(见 [`lock_timelines`])
const BULK_TIMELINES: usize = 256;
/// 拿下几条时间线的咨询锁,**按固定顺序**。一次要动多条时间线的事务都走这里:
/// 大家按同一个顺序排队,谁也不会拿着一条去等另一条。同一事务里重复拿同一把锁无妨。
///
/// **锁分两级。** 平常先拿谓词一级的共享锁,再拿时间线一级的排他锁——同一个谓词上
/// 不同持有者的时间线互不相干,照旧并行。一次要锁的时间线太多时(删一篇给几千个实体
/// 各记了一个属性的表格),改拿这些谓词的排他锁、不再逐条锁:逐条锁时 8000 条要拿
/// 8000 把锁,两万条时 Postgres 的锁表(`max_locks_per_transaction`)直接装不下,
/// 文档就删不掉了(#679 第四轮评审)。谓词锁在前、时间线锁在后,各自排序,
/// 两级之间不会反着等
pub async fn lock_timelines(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
timelines: &[Timeline],
) -> AppResult<()> {
if timelines.is_empty() {
return Ok(());
}
let mut predicates: Vec<String> = timelines
.iter()
.map(|t| format!("predicate:{kb_id}:{}", t.predicate_id))
.collect();
predicates.sort();
predicates.dedup();
let bulk = timelines.len() > BULK_TIMELINES;
let predicate_lock = if bulk {
"SELECT pg_advisory_xact_lock(hashtextextended($1, 0))"
} else {
"SELECT pg_advisory_xact_lock_shared(hashtextextended($1, 0))"
};
for key in predicates {
sqlx::query(predicate_lock)
.bind(key)
.execute(&mut **tx)
.await?;
}
if bulk {
return Ok(());
}
let mut keys: Vec<String> = timelines.iter().map(|t| t.lock_key(kb_id)).collect();
keys.sort();
keys.dedup();
for key in keys {
sqlx::query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))")
.bind(key)
.execute(&mut **tx)
.await?;
}
Ok(())
}
async fn load_timeline(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
timeline: Timeline,
) -> AppResult<Vec<Row>> {
let holder_column = match timeline.side {
Uniqueness::SubjectSide => "f.subject_id",
Uniqueness::ObjectSide => "f.object_id",
};
let rows = sqlx::query_as(&format!(
"SELECT f.id, f.subject_id, f.object_id, f.object_value,
f.valid_from, f.valid_from_precision, f.valid_to, f.valid_to_precision,
f.attested_to, f.end_derived, {DATED_AT} AS dated_at,
f.valid_from_grade, {DESCRIBED} AS described
FROM facts f
WHERE f.kb_id = $1 AND {holder_column} = $2 AND f.predicate_id = $3
AND f.invalidated_at IS NULL
ORDER BY f.recorded_at
FOR UPDATE OF f"
))
.bind(kb_id)
.bind(timeline.holder)
.bind(timeline.predicate_id)
.fetch_all(&mut **tx)
.await?;
Ok(rows)
}
/// 这些事实所在的全部唯一性时间线(只算 temporal = state、声明了唯一性的谓词)。
///
/// `swap = (from, to)`:主语或宾语是 `from` 的事实,换成 `to` 之后落在的那条也算上——
/// 撤回合并要在搬动任何一行之前,把搬走前、搬回后两边的锁都拿到
pub async fn timelines_of<'e, E>(
executor: E,
kb_id: Uuid,
fact_ids: &[Uuid],
// 这些持有者上的时间线,另记一份换到后面那个实体上(合并、撤回合并时两边都要锁)
swap: Option<(&[Uuid], Uuid)>,
) -> AppResult<Vec<Timeline>>
where
E: sqlx::PgExecutor<'e>,
{
#[derive(sqlx::FromRow)]
struct Placed {
subject_id: Uuid,
object_id: Option<Uuid>,
predicate_id: Uuid,
functional: bool,
inverse_functional: bool,
}
if fact_ids.is_empty() {
return Ok(Vec::new());
}
let placed: Vec<Placed> = sqlx::query_as(
"SELECT DISTINCT f.subject_id, f.object_id, f.predicate_id, r.functional, r.inverse_functional
FROM facts f JOIN relation_types r ON r.id = f.predicate_id
WHERE f.kb_id = $1 AND f.id = ANY($2)
AND r.temporal = 'state' AND (r.functional OR r.inverse_functional)",
)
.bind(kb_id)
.bind(fact_ids)
.fetch_all(executor)
.await?;
let swapped = |id: Uuid| {
swap.filter(|(from, _)| from.contains(&id))
.map(|(_, to)| to)
};
let mut seen = HashSet::new();
let mut out = Vec::new();
for p in placed {
let both_sides = p.functional && p.inverse_functional;
let mut holders = Vec::new();
if p.functional {
holders.push((p.subject_id, Uniqueness::SubjectSide));
holders.extend(swapped(p.subject_id).map(|to| (to, Uniqueness::SubjectSide)));
}
// 宾语侧唯一性只对实体宾语有意义(字面值不"被占用")
if let (true, Some(object)) = (p.inverse_functional, p.object_id) {
holders.push((object, Uniqueness::ObjectSide));
holders.extend(swapped(object).map(|to| (to, Uniqueness::ObjectSide)));
}
for (holder, side) in holders {
let timeline = Timeline {
holder,
predicate_id: p.predicate_id,
side,
both_sides,
};
if seen.insert(timeline) {
out.push(timeline);
}
}
}
Ok(out)
}
/// 一条 state 事实**被观察到**之后、沿指定唯一性方向的对账。新落库的要调,**又被观察到**
/// 的也要调(同一断言多了一份证据,那份证据的日期可能更早,时间线的形状跟着变),写完
/// 证据再调。调用方负责判断关系确实带该方向的唯一性且 temporal = state。
///
/// 宾语可以是实体(object_id)或字面值(object_value,属性事实)——
/// "宾语不同"的判定是 (object_id, object_value) 组合比较:工资从 3 万变 3.5 万
/// 与"从张三换成李四"走同一条闭合路径。
///
/// 这条事实的时间、置信度从库里读,参数只用来决定对哪条时间线
#[allow(clippy::too_many_arguments)]
pub async fn reconcile_new_fact(
pool: &PgPool,
kb_id: Uuid,
new_fact_id: Uuid,
subject_id: Uuid,
predicate_id: Uuid,
object_id: Option<Uuid>,
_object_value: Option<&serde_json::Value>,
direction: Uniqueness,
_new_validity: crate::graph::Validity<'_>,
_new_confidence: f32,
) -> AppResult<ReconcileReport> {
let holder = match direction {
Uniqueness::SubjectSide => subject_id,
Uniqueness::ObjectSide => match object_id {
Some(o) => o,
None => return Ok(ReconcileReport::default()),
},
};
let both_sides: bool = sqlx::query_scalar(
"SELECT functional AND inverse_functional FROM relation_types WHERE id = $1",
)
.bind(predicate_id)
.fetch_optional(pool)
.await?
.unwrap_or(false);
let timeline = Timeline {
holder,
predicate_id,
side: direction,
both_sides,
};
let mut report = ReconcileReport::default();
let mut tx = pool.begin().await?;
lock_timeline(&mut tx, kb_id, timeline).await?;
arrive(&mut tx, kb_id, timeline, new_fact_id, &[], &mut report).await?;
tidy(&mut tx, kb_id, timeline, &mut report).await?;
tx.commit().await?;
Ok(report)
}
/// 一条事实来到它的时间线上,记下重算裁不了的,交给人(调用方已持锁):
///
/// - 与别的值同一时刻开始、两边那一刻都还成立:谁接替谁说不清
/// - 两边都还开着,有一边说不出时间(没起点、也没有见证):谁先谁后无从谈起。
/// 不论哪一边先到都是这一对冲突,不替人关上任何一边
///
/// `settled`:同一批里已经来过的事实,不再与它们重复成对
async fn arrive(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
timeline: Timeline,
fact_id: Uuid,
settled: &[Uuid],
report: &mut ReconcileReport,
) -> AppResult<()> {
let rows = load_timeline(tx, kb_id, timeline).await?;
let Some(new) = rows.iter().find(|r| r.id == fact_id) else {
return Ok(());
};
let others = rows
.iter()
.filter(|r| r.id != new.id && !same_value(timeline.side, r, new))
.filter(|r| !settled.contains(&r.id));
for other in others {
let reason = match (new.key(), other.key()) {
(Some(at), Some(theirs)) if at == theirs && new.holds_at(at) && other.holds_at(at) => {
"simultaneous"
}
(None, _) | (_, None) if new.is_open() && other.is_open() => "no_time",
_ => continue,
};
if record_conflict_tx(tx, kb_id, other.id, new.id, reason).await? {
report.conflicts += 1;
}
}
Ok(())
}
/// 重算一条时间线要改的地方(单元测试看的形状)
#[cfg(test)]
#[derive(Debug, Default, PartialEq)]
struct Plan {
/// (行, 它该有的终点)
ends: Vec<(Uuid, End)>,
/// (行, 看图描述出来、没让它关上的最近那个后任):交给人
held: Vec<(Uuid, Uuid)>,
}
/// 一条时间线上每一行该有的终点(纯函数,不碰库):只含终点由引擎定的行。
///
/// 能排进时间线的行(有起点,或有见证)按时刻排好;终点是写明的行不动。其余
/// 每一行——开着的、引擎关上的——止于它之后最近的、值不同的那一行开始时;后面没有这样
/// 的行就开着。后任的起点锚不到(等级 C)时跳过它:它在轴上的位置是见证给的,不是
/// 那句话给的(0045 第 3 刀)。后任是看图描述出来的时也跳过,那一对交给人(0040 决定 4)。
///
/// 每一行的终点只取决于各行的时刻、值和起点的来历,改写终点不改这三样,所以一次算完
/// 就是最终的样子,不必一轮一轮地来;行怎么排进来的也不影响结果
fn desired_ends(side: Uniqueness, rows: &[Row]) -> (HashMap<Uuid, End>, Vec<(Uuid, Uuid)>) {
let mut keyed: Vec<&Row> = rows.iter().filter(|r| r.key().is_some()).collect();
// 同一刻开始的几行,写着起点的排前面:后任取它,前任就止于一个日期而不是一个锚点
keyed.sort_by_key(|r| (r.key(), r.valid_from.is_none(), r.id));
// 无时间的行不能保留旧引擎仅凭文档日期推出来的终点;人工写明的终点仍不重算。
let mut ends: HashMap<Uuid, End> = rows
.iter()
.filter(|row| row.recomputable() && row.key().is_none())
.map(|row| (row.id, End::Open))
.collect();
let mut held = Vec::new();
for (i, row) in keyed.iter().enumerate() {
if !row.recomputable() {
continue;
}
let mut end = End::Open;
let mut doubtful = None;
for later in keyed[i + 1..]
.iter()
.filter(|later| later.key() > row.key() && !same_value(side, row, later))
{
// 起点锚不到:不关,也不记矛盾——这一对没有什么可判的,待锚的提及归时间
// 锚点队列(0045:等级 C 既不关时间线也不开矛盾)
if later.start_unanchored() {
continue;
}
// 看图描述出来的事实能进图、能被引用,却不许单独关掉一段正确的旧值:柱状图
// 读错一个数是常事,而库里没有一行会说这次关闭靠的是一张图(0040 决定 4)
if later.described {
doubtful.get_or_insert(later.id);
continue;
}
end = later.end_before();
break;
}
if let Some(later) = doubtful {
held.push((row.id, later));
}
ends.insert(row.id, end);
}
(ends, held)
}
/// 单侧时间线的重算计划:该有的终点与眼下写着的不同的那些行
#[cfg(test)]
fn plan_timeline(side: Uniqueness, rows: &[Row]) -> Plan {
let (ends, held) = desired_ends(side, rows);
Plan {
ends: diff(rows, ends),
held,
}
}
/// 该有的终点里与眼下不同的,按行在时间线上的顺序
fn diff(rows: &[Row], mut ends: HashMap<Uuid, End>) -> Vec<(Uuid, End)> {
rows.iter()
.filter_map(|r| {
let end = ends.remove(&r.id)?;
(r.current_end() != end).then_some((r.id, end))
})
.collect()
}
/// 把一条时间线重算到 [`desired_ends`] 说的样子(调用方已持锁)。两侧都唯一的关系,
/// 每一行再按它另一侧的时间线推一次,取早的那个终点
async fn tidy(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
timeline: Timeline,
report: &mut ReconcileReport,
) -> AppResult<()> {
let rows = load_timeline(tx, kb_id, timeline).await?;
let (mut ends, mut held) = desired_ends(timeline.side, &rows);
if timeline.both_sides {
let other = timeline.side.other();
let holders: BTreeSet<Uuid> = rows.iter().filter_map(|r| r.holder(other)).collect();
for holder in holders {
let across = Timeline {
holder,
side: other,
..timeline
};
let across_rows = load_timeline(tx, kb_id, across).await?;
let (across_ends, across_held) = desired_ends(other, &across_rows);
for (id, end) in across_ends {
if let Some(mine) = ends.remove(&id) {
ends.insert(id, mine.earlier(end));
}
}
held.extend(
across_held
.into_iter()
.filter(|(row, _)| ends.contains_key(row)),
);
}
}
let mut rewritten: HashMap<Uuid, Uuid> = HashMap::new();
for (id, end) in diff(&rows, ends) {
// 重新打开的行只是开着,终点不是谁推出来的
let derived = end != End::Open;
if let Some(corrected) = rewrite_end_tx(tx, id, &end, derived, false, false).await? {
rewritten.insert(id, corrected);
report.corrected.push(corrected);
}
}
for (row, later) in held {
let row = rewritten.get(&row).copied().unwrap_or(row);
let later = rewritten.get(&later).copied().unwrap_or(later);
if record_conflict_tx(tx, kb_id, row, later, "described_evidence").await? {
report.conflicts += 1;
}
}
Ok(())
}
/// 两个实体合成一个之后,哪些唯一性关系上**还会**有两个值同时成立(执行闸门,0027)。
///
/// 两边各有一个不同的值不等于矛盾:租约的房东先是 HPBB1、后来换成 BBHQ1,两个名字各挂
/// 一个,合起来是一条先后接替的时间线。这里把两边的行当成一条时间线,按引擎会怎么排
/// ([`desired_ends`])推出每一行的终点,再看不同的值有没有哪一刻叠在一起——排不开的
/// (同一刻开始、说不出时间、置信度不够接替、两份原文写明的区间相交)才是合了之后一致性
/// 检查会报的矛盾。只看实体宾语的边,与一致性检查(`utopia_reason::check`)同一个口径。
/// 返回谓词标签,按标签排
pub async fn merge_would_overlap(
pool: &PgPool,
kb_id: Uuid,
a: Uuid,
b: Uuid,
) -> AppResult<Vec<String>> {
#[derive(sqlx::FromRow)]
struct Shared {
predicate_id: Uuid,
label: String,
functional: bool,
inverse_functional: bool,
temporal: String,
}
let shared: Vec<Shared> = sqlx::query_as(
"SELECT DISTINCT r.id AS predicate_id, r.label, r.functional, r.inverse_functional,
r.temporal
FROM facts x
JOIN facts y ON y.predicate_id = x.predicate_id AND y.kb_id = x.kb_id
JOIN relation_types r ON r.id = x.predicate_id
WHERE x.kb_id = $1
AND x.invalidated_at IS NULL AND y.invalidated_at IS NULL
AND x.object_id IS NOT NULL AND y.object_id IS NOT NULL
AND ((r.functional AND x.subject_id = $2 AND y.subject_id = $3
AND x.object_id <> y.object_id)
OR (r.inverse_functional AND x.object_id = $2 AND y.object_id = $3
AND x.subject_id <> y.subject_id))",
)
.bind(kb_id)
.bind(a)
.bind(b)
.fetch_all(pool)
.await?;
let mut labels = Vec::new();
for s in shared {
let mut sides = Vec::new();
if s.functional {
sides.push(Uniqueness::SubjectSide);
}
if s.inverse_functional {
sides.push(Uniqueness::ObjectSide);
}
for side in sides {
let holder_column = match side {
Uniqueness::SubjectSide => "f.subject_id",
Uniqueness::ObjectSide => "f.object_id",
};
let mut rows: Vec<Row> = sqlx::query_as(&format!(
"SELECT f.id, f.subject_id, f.object_id, f.object_value,
f.valid_from, f.valid_from_precision, f.valid_to, f.valid_to_precision,
f.attested_to, f.end_derived, {DATED_AT} AS dated_at,
f.valid_from_grade, {DESCRIBED} AS described
FROM facts f
WHERE f.kb_id = $1 AND {holder_column} = ANY($2) AND f.predicate_id = $3
AND f.invalidated_at IS NULL AND f.object_id IS NOT NULL"
))
.bind(kb_id)
.bind(vec![a, b])
.bind(s.predicate_id)
.fetch_all(pool)
.await?;
// **只算合并带进来的冲突。** 一边持有的值另一边全都已经持有,合起来还是那几个值:
// 同一个宾语并成一行,冲突要有也是那一边原本就有的,合不合都在。租约链上实测:
// 一份租约自己已经挂着两个没日期的房东,另一个写法只挂着其中一个,0.98 的合并被
// 「两个房东」挡下,而那两个房东合并之前就在
let values_of = |holder: Uuid| -> HashSet<Uuid> {
rows.iter()
.filter_map(|r| match side {
Uniqueness::SubjectSide => (r.subject_id == holder).then_some(r.object_id?),
Uniqueness::ObjectSide => {
(r.object_id == Some(holder)).then_some(r.subject_id)
}
})
.collect()
};
let (held_by_a, held_by_b) = (values_of(a), values_of(b));
if held_by_a.is_subset(&held_by_b) || held_by_b.is_subset(&held_by_a) {
continue;
}
// 合成一个之后的样子:持有者那一侧都是同一个实体
for row in &mut rows {
match side {
Uniqueness::SubjectSide => row.subject_id = a,
Uniqueness::ObjectSide => row.object_id = Some(a),
}
}
if still_overlaps(side, &rows, s.temporal == "state") {
labels.push(s.label.clone());
break;
}
}
}
labels.sort();
labels.dedup();
Ok(labels)
}
/// 一行排完之后的 [起, 止),`None` 是那一侧无界
type Span = (Option<DateTime<Utc>>, Option<DateTime<Utc>>);
/// 一条时间线按引擎排完之后,不同的值有没有哪一刻同时成立(纯函数)。`placed`:谓词是
/// 状态,引擎会排它;事件与恒常不排,照行上写着的终点比
fn still_overlaps(side: Uniqueness, rows: &[Row], placed: bool) -> bool {
let ends = if placed {
desired_ends(side, rows).0
} else {
HashMap::new()
};
// 每一行排完之后的 [起, 止):起点是排序用的时刻,说不出时间的行从无穷早起;
// 终点是引擎推的,或原文写明的
let spans: Vec<Span> = rows
.iter()
.map(|r| {
let end = ends.get(&r.id).map(End::instant).unwrap_or_else(|| r.end());
(r.key(), end)
})
.collect();
for i in 0..rows.len() {
for j in i + 1..rows.len() {
if same_value(side, &rows[i], &rows[j]) {
continue;
}
let ((si, ei), (sj, ej)) = (spans[i], spans[j]);
let starts_before_end =
|s: Option<DateTime<Utc>>, e: Option<DateTime<Utc>>| match (s, e) {
(Some(s), Some(e)) => s < e,
_ => true,
};
if starts_before_end(si, ej) && starts_before_end(sj, ei) {
return true;
}
}
}
false
}
/// 把几条时间线各自重算一遍(调用方已按 [`lock_timelines`] 拿到锁)。撤回合并、删除或
/// 恢复文档在自己的事务里改完行之后调
pub async fn tidy_timelines_tx(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
timelines: &[Timeline],
) -> AppResult<ReconcileReport> {
let mut report = ReconcileReport::default();
for timeline in timelines {
tidy(tx, kb_id, *timeline, &mut report).await?;
}
Ok(report)
}
/// 实体合并搬移事实后的对账:换了主/宾的事实等价于"新落库的观察"——
/// 两个对象折成一个之后,唯一性不变量才第一次看得到它们相撞。人改过区间之后也走这里。
/// 返回的修正行 id 由调用方记入合并账本,供审计
pub async fn reconcile_moved_facts(
pool: &PgPool,
kb_id: Uuid,
fact_ids: &[Uuid],
) -> AppResult<ReconcileReport> {
reconcile_facts(pool, kb_id, fact_ids).await
}
/// 一批事实所在的每条时间线:批里的事实逐条「来到」时间线上(记下该交给人的),整条
/// 重算一遍。一条时间线一个事务。物化把陈述算成类型化行之后也走这里(#899):
/// 这些行是「新落库的观察」,和抽取、点头写下的一样要对账
pub(crate) async fn reconcile_facts(
pool: &PgPool,
kb_id: Uuid,
fact_ids: &[Uuid],
) -> AppResult<ReconcileReport> {
let mut report = ReconcileReport::default();
let batch: HashSet<Uuid> = fact_ids.iter().copied().collect();
for timeline in timelines_of(pool, kb_id, fact_ids, None).await? {
let mut tx = pool.begin().await?;
lock_timeline(&mut tx, kb_id, timeline).await?;
let rows = load_timeline(&mut tx, kb_id, timeline).await?;
let mut arriving: Vec<&Row> = rows.iter().filter(|r| batch.contains(&r.id)).collect();
arriving.sort_by_key(|r| (r.key().is_none(), r.key(), r.id));
let arriving: Vec<Uuid> = arriving.iter().map(|r| r.id).collect();
for (i, id) in arriving.iter().enumerate() {
arrive(&mut tx, kb_id, timeline, *id, &arriving[..i], &mut report).await?;
}
tidy(&mut tx, kb_id, timeline, &mut report).await?;
tx.commit().await?;
}
Ok(report)
}
/// 声明来晚了:一条谓词上所有现存事实所在的时间线重算一遍(#341)。
///
/// 本体自己长出来的库里没人声明过唯一性,接任不会闭合前任——三个人同时在管一个
/// 项目。人补上声明之后,这里把已经躺在账上的行对一遍。走的是与落库时同一条
/// 路(作废 + 改写,supersedes 链回旧行),所以记录轴倒回声明之前仍看得见三条
/// 开放的行;拿不准的(缺时间 / 同时开始 / 低置信)照旧进人审,不硬闭合。
///
/// 没有声明的谓词拒绝:引擎不替人推断(bootstrap_ontology.rs 写了为什么)。
pub async fn reconcile_predicate(
pool: &PgPool,
kb_id: Uuid,
predicate_id: Uuid,
) -> AppResult<ReconcileReport> {
let declared: Option<(bool, bool, String)> = sqlx::query_as(
"SELECT functional, inverse_functional, temporal FROM relation_types
WHERE kb_id = $1 AND id = $2",
)
.bind(kb_id)
.bind(predicate_id)
.fetch_optional(pool)
.await?;
let Some((functional, inverse_functional, temporal)) = declared else {
return Err(utopia_core::AppError::NotFound);
};
if temporal != "state" {
return Err(utopia_core::AppError::invalid(
"not_a_state",
"only a state relation has intervals to close",
));
}
if !functional && !inverse_functional {
return Err(utopia_core::AppError::invalid(
"not_unique",
"declare the relation functional or inverse-functional first; the engine does not infer it",
));
}
let ids: Vec<Uuid> = sqlx::query_scalar(
"SELECT id FROM facts
WHERE kb_id = $1 AND predicate_id = $2 AND invalidated_at IS NULL
AND (object_id IS NOT NULL OR object_value IS NOT NULL)",
)
.bind(kb_id)
.bind(predicate_id)
.fetch_all(pool)
.await?;
reconcile_facts(pool, kb_id, &ids).await
}
/// 撤掉一条事实(人判它是抽取错误):它从来不在,时间线按剩下的行重算——关在它开始时的
/// 前任重新接上。先锁时间线再作废(见模块头)。返回有没有撤掉一行;已经作废的不算
pub async fn retract(pool: &PgPool, kb_id: Uuid, fact_id: Uuid) -> AppResult<bool> {
let mut tx = pool.begin().await?;
let timelines = timelines_of(&mut *tx, kb_id, &[fact_id], None).await?;
lock_timelines(&mut tx, kb_id, &timelines).await?;
let retracted = sqlx::query(
"UPDATE facts SET invalidated_at = now()
WHERE id = $1 AND kb_id = $2 AND invalidated_at IS NULL",
)
.bind(fact_id)
.bind(kb_id)
.execute(&mut *tx)
.await?
.rows_affected()
> 0;
if retracted {
tidy_timelines_tx(&mut tx, kb_id, &timelines).await?;
}
tx.commit().await?;
Ok(retracted)
}
/// 作废 + 改写成**写明的**终点:旧行记 invalidated_at(认知轴),插入闭合区间的修正行
/// (世界轴),证据引用随行复制。人裁决把它关上走这里,拒绝早于起点的终点;原文写入
/// 走 `close_stated`。这个终点此后不再由引擎重算。返回修正行 id;`None` = 已作废,没动。
pub async fn close_superseded<'a>(
pool: impl sqlx::Acquire<'a, Database = Postgres>,
fact_id: Uuid,
valid_to: DateTime<Utc>,
valid_to_precision: &str,
) -> AppResult<Option<Uuid>> {
let valid_to = crate::graph::truncate_to(valid_to, Some(valid_to_precision));
let mut tx = pool.begin().await?;
let row: Option<(Option<DateTime<Utc>>, Option<String>)> = sqlx::query_as(
"SELECT valid_from, valid_from_precision FROM facts
WHERE id = $1 AND invalidated_at IS NULL FOR UPDATE",
)
.bind(fact_id)
.fetch_optional(&mut *tx)
.await?;
let Some((from, from_precision)) = row else {
return Ok(None);
};
// 锁住起点后再比,避免并发修正穿过检查;两端都按各自精度截断(#1294)。
// 放在审核的 store 入口,也管住冲突默认取新事实起点的闭合,不改原文写入的规则。
if from
.is_some_and(|from| valid_to < crate::graph::truncate_to(from, from_precision.as_deref()))
{
return Err(utopia_core::AppError::invalid(
"interval_inverted",
"The start of the interval is after its end.",
));
}
// 按日期关上的(审核里关、冲突的 close_at、违规的 fact_closed)给的就是终点那一刻,不标
let end = End::At(valid_to, valid_to_precision.to_string());
let corrected = rewrite_end_tx(&mut tx, fact_id, &end, false, false, false).await?;
tx.commit().await?;
Ok(corrected)
}
/// [`close_superseded`],外加这个终点是不是原文所说时段之后的那一刻(`end_after_period`,
/// #994):写入路径把「2024 年离开」关在 2025-01-01 时标上,读者才印得出 2024
pub(crate) async fn close_stated<'a>(
pool: impl sqlx::Acquire<'a, Database = Postgres>,
fact_id: Uuid,
valid_to: DateTime<Utc>,
valid_to_precision: &str,
after_period: bool,
) -> AppResult<Option<Uuid>> {
// 闭合点截到它的精度(0024):月精度的闭合就是那个月的 1 日 0 点
let end = End::At(
crate::graph::truncate_to(valid_to, Some(valid_to_precision)),
valid_to_precision.to_string(),
);
let mut tx = pool.begin().await?;
let corrected = rewrite_end_tx(&mut tx, fact_id, &end, false, false, after_period).await?;
tx.commit().await?;
Ok(corrected)
}
/// 作废 + 改写成「结束了,不知哪天」(0022 / #393):旧行记 invalidated_at,修正行终点仍是
/// NULL、精度 'unknown',`attested_to` 锚在**说出结束的那份文档**——读出来就是「到它为止」;
/// `attested_from` 从旧行继承——没起点的裸行靠它记着第一份证据,读出来是「从那时起」。
/// 这是原文写明的结束,引擎不重算。证据引用随行复制。返回修正行 id;`None` = 这条已不是
/// 开放行,没动。
pub async fn close_with_unknown_end<'a>(
pool: impl sqlx::Acquire<'a, Database = Postgres>,
fact_id: Uuid,
attested_at: Option<DateTime<Utc>>,
) -> AppResult<Option<Uuid>> {
let mut tx = pool.begin().await?;
let corrected = rewrite_end_tx(
&mut tx,
fact_id,
&End::Unknown(attested_at),
false,
true,
false,
)
.await?;
tx.commit().await?;
Ok(corrected)
}
/// 原文说出了一条**引擎关上**的行的终点:改写成原文说的,此后不再重算(#679 第三轮评审)。
/// `valid_to` 为 `None` 是「结束了,不知哪天」,锚在 `attested_at`;`after_period`:原文说的
/// 是那一刻之前的那个时段(#994)。返回修正行 id;行已作废,或它的终点本来就是写明的,
/// 返回 `None`
pub async fn state_derived_end<'a>(
pool: impl sqlx::Acquire<'a, Database = Postgres>,
fact_id: Uuid,
valid_to: Option<(DateTime<Utc>, &str)>,
after_period: bool,
attested_at: Option<DateTime<Utc>>,
) -> AppResult<Option<Uuid>> {
let end = match valid_to {
Some((at, precision)) => End::At(
crate::graph::truncate_to(at, Some(precision)),
precision.to_string(),
),
None => End::Unknown(attested_at),
};
let mut tx = pool.begin().await?;
let derived: Option<bool> = sqlx::query_scalar(
"SELECT end_derived FROM facts WHERE id = $1 AND invalidated_at IS NULL FOR UPDATE",
)
.bind(fact_id)
.fetch_optional(&mut *tx)
.await?;
let corrected = match derived {
Some(true) => rewrite_end_tx(&mut tx, fact_id, &end, false, false, after_period).await?,
_ => None,
};
tx.commit().await?;
Ok(corrected)
}
/// 一条写明的终点又被另一种说法说了一遍:「until 2025」关上的行又读到「left in 2024」。
/// 时刻不变,改写成带标记的一行(#994);反过来的顺序在收尾那条路上已经标了,两种顺序
/// 写下同一行。
///
/// 调用方(`insert_fact_on`)只比了时刻,这里锁住那一行再查两件事:精度与这次说的相同——
/// 日精度写明的 2025-01-01 是那一天,不是 2024 年的尽头;终点不是人改过的
/// (`corrected_ends` 为空或只有起点)——人把显示的 2024 改成 2025,就是要到 2025 年。
/// 已经标过的不再标。那一行带不带得了标记(引擎画的终点、没有起点的行带不了),读出来交给
/// `graph::period_mark_fits` 判。返回修正行 id;不必标的返回 `None`
pub(crate) async fn mark_end_after_period<'a>(
pool: impl sqlx::Acquire<'a, Database = Postgres>,
fact_id: Uuid,
precision: &str,
) -> AppResult<Option<Uuid>> {
let mut tx = pool.begin().await?;
#[allow(clippy::type_complexity)]
let locked_row: Option<(Option<DateTime<Utc>>, Option<DateTime<Utc>>, bool, bool)> =
sqlx::query_as(
"SELECT f.valid_from, f.valid_to, f.end_derived,
COALESCE(r.temporal = 'state', false) AS declared_state
FROM facts f LEFT JOIN relation_types r ON r.id = f.predicate_id
WHERE f.id = $1 AND f.invalidated_at IS NULL
AND f.valid_to_precision = $2 AND NOT f.end_after_period
AND (f.corrected_ends IS NULL OR f.corrected_ends = 'start')
FOR UPDATE OF f",
)
.bind(fact_id)
.bind(precision)
.fetch_optional(&mut *tx)
.await?;
let marked = match locked_row {
// 起点那一半人改过的照旧是人的:改写的 CASE 把 'start' 原样带过去
Some((from, Some(at), end_derived, declared_state))
if crate::graph::period_mark_fits(declared_state, from, Some(at), end_derived) =>
{
let end = End::At(at, precision.to_string());
rewrite_end_tx(&mut tx, fact_id, &end, false, false, true).await?
}
_ => None,
};
tx.commit().await?;
Ok(marked)
}
/// 作废 + 改写一行的终点。`derived`:这个终点是引擎按时间线推出来的(0057),之后随
/// 时间线重算;`require_open`:只改还开着的行;`after_period`:终点是原文所说时段之后的
/// 那一刻(#994)。
///
/// 先 `FOR UPDATE` 锁住旧行:并行的两次改写只有一次看得见它还活着,另一次拿到 `None`,
/// 不会各插一条修正行;往这一行上添证据的也要等它(`graph::add_evidence`),证据不会落在
/// 刚被作废的旧行上。还没人裁的冲突跟着换到修正行上:问题还在,只是这一行换了终点
async fn rewrite_end_tx(
tx: &mut Transaction<'_, Postgres>,
fact_id: Uuid,
end: &End,
derived: bool,
require_open: bool,
after_period: bool,
) -> AppResult<Option<Uuid>> {
let alive: Option<(Option<DateTime<Utc>>, Option<Uuid>)> = sqlx::query_as(
"SELECT valid_from, predicate_id FROM facts
WHERE id = $1 AND invalidated_at IS NULL
AND (NOT $2 OR (valid_to IS NULL AND valid_to_precision IS NULL))
FOR UPDATE",
)
.bind(fact_id)
.bind(require_open)
.fetch_optional(&mut **tx)
.await?;
let Some((from, predicate)) = alive else {
return Ok(None);
};
// 声明成状态的行关在它自己的起点,就是一段任何时刻都不成立的状态(#966,与
// `Validity::under` 同一条不变量)。人关一条事实走这里;引擎只把一行关在严格更晚的
// 起点上,写入路径也不拿开放行自己的起点来关它
if let End::At(at, _) = end {
if predicate.is_some()
&& from == Some(*at)
&& crate::graph::predicate_temporal(&mut **tx, predicate).await?
== crate::graph::Temporal::State
{
return Err(crate::graph::empty_state_span());
}
}
let (valid_to, precision, anchor) = match end {
End::Open => (None, None, None),
End::At(at, precision) => (Some(*at), Some(precision.as_str()), None),
End::Unknown(anchor) => (None, Some(crate::graph::ENDED_UNKNOWN), *anchor),
};
// 标记只落在带得了它的终点上(`graph::period_mark_fits`):时间线画的、不知哪天的、重新
// 打开的终点,没有起点或属性不是状态的行,一律不带——起点和谓词是上面锁住时读的。要标时
// 才去查属性:不标的改写(时间线重画、关成不知哪天)不多一次查询
let after_period = after_period && {
let declared_state = predicate.is_some()
&& crate::graph::predicate_temporal(&mut **tx, predicate).await?
== crate::graph::Temporal::State;
crate::graph::period_mark_fits(declared_state, from, valid_to, derived)
};
let corrected = Uuid::now_v7();
sqlx::query(
"INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id, object_value,
valid_from, valid_from_precision, valid_from_grade,
valid_to, valid_to_precision, confidence, supersedes,
attested_from, attested_by, attested_to, end_derived,
from_statement_id, implied, corrected_ends, end_after_period)
SELECT $1, kb_id, subject_id, predicate_id, object_id, object_value,
valid_from, valid_from_precision, valid_from_grade, $3, $4, confidence, id,
attested_from, attested_by,
CASE WHEN $4::text = 'unknown' THEN COALESCE($5, now()) END, $6,
from_statement_id, implied,
-- 终点在这里被重新写下(文档说了终点,或时间线推了一个),人改过的终点就不在了;
-- 起点那一半照旧
CASE corrected_ends WHEN 'both' THEN 'start' WHEN 'end' THEN NULL
ELSE corrected_ends END,
$7
FROM facts WHERE id = $2",
)
.bind(corrected)
.bind(fact_id)
.bind(valid_to)
.bind(precision)
.bind(anchor)
.bind(derived)
.bind(after_period)
.execute(&mut **tx)
.await?;
carry_open_conflicts(tx, fact_id, corrected).await?;
sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = $1")
.bind(fact_id)
.execute(&mut **tx)
.await?;
copy_evidence(tx, fact_id, corrected).await?;
copy_qualifiers(tx, fact_id, corrected).await?;
copy_materialization_links(tx, fact_id, corrected).await?;
Ok(Some(corrected))
}
/// 物化出来的行改写之后还是物化出来的行(#899):它由哪些陈述、哪条规则算出
/// (`typed_fact_sources` / `implied_fact_sources`)随修正行复制,`from_statement_id` 和
/// `implied` 在 INSERT 里一起带过去。不带的话下一轮物化看见陈述没有活着的类型化行,
/// 会再算一行——旧行的来源由物化自己清(它只删挂在作废行上的)
async fn copy_materialization_links(
tx: &mut Transaction<'_, Postgres>,
from: Uuid,
to: Uuid,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO typed_fact_sources (fact_id, statement_id)
SELECT $2, statement_id FROM typed_fact_sources WHERE fact_id = $1
ON CONFLICT DO NOTHING",
)
.bind(from)
.bind(to)
.execute(&mut **tx)
.await?;
sqlx::query(
"INSERT INTO implied_fact_sources (fact_id, rule_id, statement_id, entity_id)
SELECT $2, rule_id, statement_id, entity_id FROM implied_fact_sources WHERE fact_id = $1
ON CONFLICT DO NOTHING",
)
.bind(from)
.bind(to)
.execute(&mut **tx)
.await?;
Ok(())
}
/// 作废 + 改写一行的持有者:主语或宾语换成另一个实体,其余照旧(证据、边上的属性随行)。
/// 撤回合并把合并之后才改写出来的行送回源实体时用——原地改主语,记录轴回放合并窗口时
/// 就找不到它当时挂在哪(0027 只认合并账本上的行)。返回新行 id;`None` = 已作废
pub async fn rehome_tx(
tx: &mut Transaction<'_, Postgres>,
fact_id: Uuid,
subject_id: Option<Uuid>,
object_id: Option<Uuid>,
) -> AppResult<Option<Uuid>> {
let alive: Option<(Uuid,)> =
sqlx::query_as("SELECT id FROM facts WHERE id = $1 AND invalidated_at IS NULL FOR UPDATE")
.bind(fact_id)
.fetch_optional(&mut **tx)
.await?;
if alive.is_none() {
return Ok(None);
}
let moved = Uuid::now_v7();
sqlx::query(
"INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id, object_value,
valid_from, valid_from_precision, valid_to, valid_to_precision,
confidence, derived_by_rule, supersedes,
attested_from, attested_to, end_derived,
from_statement_id, implied, corrected_ends, end_after_period)
SELECT $1, kb_id, COALESCE($3, subject_id), predicate_id, COALESCE($4, object_id),
object_value, valid_from, valid_from_precision, valid_to, valid_to_precision,
confidence, derived_by_rule, id, attested_from, attested_to, end_derived,
from_statement_id, implied, corrected_ends, end_after_period
FROM facts WHERE id = $2",
)
.bind(moved)
.bind(fact_id)
.bind(subject_id)
.bind(object_id)
.execute(&mut **tx)
.await?;
// 开着的冲突先换到新行上:旧行一作废,0051 的触发器就把它们撤下,之后重算也不会
// 再记同一天开始的那一对——撤回完两行叠在一起,审核队列却是空的(#679 第四轮评审)
carry_open_conflicts(tx, fact_id, moved).await?;
sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = $1")
.bind(fact_id)
.execute(&mut **tx)
.await?;
copy_evidence(tx, fact_id, moved).await?;
copy_qualifiers(tx, fact_id, moved).await?;
copy_materialization_links(tx, fact_id, moved).await?;
Ok(Some(moved))
}
/// 还开着的冲突从旧行换到修正行上(旧行一作废,0051 的触发器就会把它们撤下)。
/// 修正行上已经有同一对的,留着旧的那条随作废撤下
async fn carry_open_conflicts(
tx: &mut Transaction<'_, Postgres>,
from: Uuid,
to: Uuid,
) -> AppResult<()> {
sqlx::query(
"UPDATE fact_conflicts c SET old_fact_id = $2
WHERE c.status = 'open' AND c.old_fact_id = $1
AND NOT EXISTS (SELECT 1 FROM fact_conflicts d
WHERE d.old_fact_id = $2 AND d.new_fact_id = c.new_fact_id)",
)
.bind(from)
.bind(to)
.execute(&mut **tx)
.await?;
sqlx::query(
"UPDATE fact_conflicts c SET new_fact_id = $2
WHERE c.status = 'open' AND c.new_fact_id = $1
AND NOT EXISTS (SELECT 1 FROM fact_conflicts d
WHERE d.new_fact_id = $2 AND d.old_fact_id = c.old_fact_id)",
)
.bind(from)
.bind(to)
.execute(&mut **tx)
.await?;
Ok(())
}
/// 边上的属性随修正行复制(0037):纠正的是时间区间,边上的金额、职务照旧——
/// 不搬的话,闭合一段任职就丢了它的职务
async fn copy_qualifiers(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
from: Uuid,
to: Uuid,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO fact_qualifiers (fact_id, qualifier_type_id, value, entity_id)
SELECT $1, qualifier_type_id, value, entity_id
FROM fact_qualifiers WHERE fact_id = $2
ON CONFLICT DO NOTHING",
)
.bind(to)
.bind(from)
.execute(&mut **tx)
.await?;
Ok(())
}
/// 证据引用随修正行复制。表层谓词一起搬:纠正的是时间区间,不是原文说了什么。
async fn copy_evidence(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
from: Uuid,
to: Uuid,
) -> AppResult<()> {
sqlx::query(
"INSERT INTO fact_evidence (fact_id, chunk_id, quote, proposed_predicate, document_id, doc_version,
quote_start, quote_end)
SELECT $1, chunk_id, quote, proposed_predicate, document_id, doc_version,
quote_start, quote_end
FROM fact_evidence WHERE fact_id = $2
ON CONFLICT DO NOTHING",
)
.bind(to)
.bind(from)
.execute(&mut **tx)
.await?;
Ok(())
}
/// 人工修正一条事实的有效区间。与自动闭合同一机制(作废 + 改写),区别只在
/// 两端都来自参数,而不是继承旧行的起点。
///
/// 抽取把「2023 年上半年」读成 1 月 1 日,在此之前只能删掉文档重抽一遍:
/// 名字判错有 Review 可改,时间判错没有入口,而整条时间线都歪在那一个值上。
///
/// **不原地 UPDATE。** 原地改会把修正本身抹掉,而那正是记录轴要回放的东西
/// (0019)——改过之后,问三月与问九月应当得到不同的区间。这也是这个函数
/// 与一条 `UPDATE facts SET valid_from = …` 的全部差别。
///
/// 人改的是时间,不是出处:物化出来的行改完仍是那几条陈述算出来的,与时间线的
/// 改写同一条规矩([`copy_materialization_links`])。不带过去的话,陈述不再被活着的
/// 类型化行代表,画面上它按原话、原来的区间回来,下一轮物化还照它再算一行。
///
/// 改了哪一端记在修正行上(`corrected_ends`,#970):值或精度(终点还有标记)变了的那一端,
/// 与旧行已有的取并集,与修正同一个事务——事实行据此说「这个日期是人改的」,不再靠事后那条审计。
/// 人交来的是整段区间,改完两端都是人的(`end_derived` 清掉,时间线不再重画它):原来
/// 是时间线推出来的终点,人没改它的值也是把它钉住了,一样算人的;原来就是原文说的那一端
/// 没改,仍是原文的
///
/// 终点是不是原文所说时段之后的那一刻(`end_after_period`,#994)由调用方给,这里只归一:
/// 修正路由按请求定它,从不替人换算
///
/// 返回修正行 id;`None` 表示这条已被并发改写或作废,本次没有动手。
pub async fn correct_interval(
pool: &PgPool,
fact_id: Uuid,
validity: crate::graph::Validity<'_>,
) -> AppResult<Option<Uuid>> {
// 人改区间也按谓词的时间语义归一(0031):给一个事件填了一段,落下的仍是它的那一刻
let predicate: Option<Option<Uuid>> =
sqlx::query_scalar("SELECT predicate_id FROM facts WHERE id = $1")
.bind(fact_id)
.fetch_optional(pool)
.await?;
let predicate = predicate.flatten();
let temporal = crate::graph::predicate_temporal(pool, predicate).await?;
// 两端相等的状态只对声明成状态的属性拒(#966):开放陈述与空谓词的行按状态读只是
// 读法,「那天」照旧写成两端同值
let validity = match predicate {
Some(_) => validity.truncated().under(temporal)?,
None => validity.truncated(),
}
.drop_period_mark_unless(predicate.is_some() && temporal == crate::graph::Temporal::State);
let mut tx = pool.begin().await?;
let corrected = Uuid::now_v7();
// 标记变了也算终点变了(#994):人把显示的 2024 改成 2025,存的时刻没动,说的却是另一年
let inserted: Option<(Uuid,)> = sqlx::query_as(
"INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id, object_value,
valid_from, valid_from_precision,
valid_to, valid_to_precision, confidence, supersedes,
attested_from, attested_to,
from_statement_id, implied, corrected_ends, end_after_period)
SELECT $1, kb_id, subject_id, predicate_id, object_id, object_value,
$3, $4, $5, $6, confidence, id,
attested_from,
CASE WHEN $6::text = 'unknown' THEN COALESCE(attested_to, now()) END,
from_statement_id, implied,
CASE WHEN start_marked AND end_marked THEN 'both'
WHEN start_marked THEN 'start'
WHEN end_marked THEN 'end' END,
$7
FROM (SELECT f.*,
c.start_changed OR COALESCE(f.corrected_ends IN ('start', 'both'), false)
AS start_marked,
c.end_changed OR f.end_derived
OR COALESCE(f.corrected_ends IN ('end', 'both'), false)
AS end_marked
FROM facts f,
LATERAL (SELECT f.valid_from IS DISTINCT FROM $3::timestamptz
OR f.valid_from_precision IS DISTINCT FROM $4::text
AS start_changed,
f.valid_to IS DISTINCT FROM $5::timestamptz
OR f.valid_to_precision IS DISTINCT FROM $6::text
OR f.end_after_period IS DISTINCT FROM $7::boolean
AS end_changed) c
WHERE f.id = $2 AND f.invalidated_at IS NULL) old
RETURNING id",
)
.bind(corrected)
.bind(fact_id)
.bind(validity.from)
.bind(validity.from_precision)
.bind(validity.to)
.bind(validity.to_precision)
.bind(validity.end_after_period)
.fetch_optional(&mut *tx)
.await?;
// 已被并发修正过:不重复动手(与 close_superseded 同一防线)
if inserted.is_none() {
tx.rollback().await?;
return Ok(None);
}
sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = $1")
.bind(fact_id)
.execute(&mut *tx)
.await?;
copy_evidence(&mut tx, fact_id, corrected).await?;
copy_qualifiers(&mut tx, fact_id, corrected).await?;
copy_materialization_links(&mut tx, fact_id, corrected).await?;
tx.commit().await?;
Ok(Some(corrected))
}
/// 记一对冲突。返回这一对是不是第一次记:时间线每次重算都会再看见同一对,
/// 已经在队列里(或人已经裁过)的不再算作新冲突
async fn record_conflict_tx(
tx: &mut Transaction<'_, Postgres>,
kb_id: Uuid,
old_fact_id: Uuid,
new_fact_id: Uuid,
reason: &str,
) -> AppResult<bool> {
// 人已经裁过「两个都留着」的,不因为两行后来被改写(换了 id)就再问一遍:
// 顺着 supersedes 往上找两行的前身,那一对裁过就不记(#679 第三轮评审)
let inserted = sqlx::query(
"INSERT INTO fact_conflicts (id, kb_id, old_fact_id, new_fact_id, reason)
SELECT $1, $2, $3, $4, $5
WHERE NOT EXISTS (
WITH RECURSIVE a(id) AS (
SELECT $3::uuid
UNION SELECT f.supersedes FROM facts f JOIN a ON f.id = a.id
WHERE f.supersedes IS NOT NULL),
b(id) AS (
SELECT $4::uuid
UNION SELECT f.supersedes FROM facts f JOIN b ON f.id = b.id
WHERE f.supersedes IS NOT NULL)
SELECT 1 FROM fact_conflicts c
WHERE c.status = 'resolved' AND c.resolution = 'kept_both'
AND ((c.old_fact_id IN (SELECT id FROM a) AND c.new_fact_id IN (SELECT id FROM b))
OR (c.old_fact_id IN (SELECT id FROM b) AND c.new_fact_id IN (SELECT id FROM a))))
-- 同一对反过来记过的也算记过:重算按时间线顺序看,谁是「旧」谁是「新」
-- 随到达顺序变,不去重的话一次全量重算会翻出一堆方向相反的重复
AND NOT EXISTS (SELECT 1 FROM fact_conflicts r
WHERE r.old_fact_id = $4 AND r.new_fact_id = $3 AND r.status = 'open')
ON CONFLICT (old_fact_id, new_fact_id) DO NOTHING",
)
.bind(Uuid::now_v7())
.bind(kb_id)
.bind(old_fact_id)
.bind(new_fact_id)
.bind(reason)
.execute(&mut **tx)
.await?;
Ok(inserted.rows_affected() > 0)
}
/// Review 页的冲突列表(双方事实带名字与区间)。
/// 惰性清理:任一方已被作废(被驳回/被别的闭合改写)的冲突已无意义,
/// 自动出队标 stale——防止在僵尸冲突上误裁(如把 Eve 闭合在已驳回的 Ivan 上)。
pub async fn list_conflicts(
pool: &PgPool,
kb_id: Uuid,
limit: i64,
offset: i64,
) -> AppResult<Vec<ConflictView>> {
// **这里从前有一条 UPDATE。**读之前先把「有一边已经作废」的冲突改成
// resolved / stale / now()——清理是对的,位置是错的:`resolved_at` 于是记的是
// 有人打开这一页的时刻,而没人打开的库里陈冲突永远开着。退场现在钉在作废
// 发生的地方(0051 的触发器),这里只读
let rows: Vec<ConflictView> = sqlx::query_as(
"SELECT c.id, c.reason, c.created_at, r.label AS predicate_label,
c.old_fact_id, os.canonical_name AS old_subject,
oo.canonical_name AS old_object, fo.valid_from AS old_valid_from,
c.new_fact_id, ns.canonical_name AS new_subject,
no_.canonical_name AS new_object, fn_.valid_from AS new_valid_from,
fn_.confidence AS new_confidence
FROM fact_conflicts c
JOIN facts fo ON fo.id = c.old_fact_id
JOIN facts fn_ ON fn_.id = c.new_fact_id
JOIN entities os ON os.id = fo.subject_id
JOIN entities ns ON ns.id = fn_.subject_id
JOIN relation_types r ON r.id = fo.predicate_id
LEFT JOIN entities oo ON oo.id = fo.object_id
LEFT JOIN entities no_ ON no_.id = fn_.object_id
WHERE c.kb_id = $1 AND c.status = 'open'
ORDER BY c.created_at DESC, c.id DESC
LIMIT $2 OFFSET $3",
)
.bind(kb_id)
.bind(limit)
.bind(offset)
.fetch_all(pool)
.await?;
Ok(rows)
}
/// 人工裁决:close(旧事实闭合于 close_at 或新事实起点)/ keep(并存不矛盾)/
/// reject_new(新事实是抽取错误,作废)。
/// 一条待裁决的冲突:旧事实、新事实、新事实的起点及其精度
type ConflictRow = (Uuid, Uuid, Option<DateTime<Utc>>, Option<String>);
pub async fn resolve_conflict(
pool: &PgPool,
kb_id: Uuid,
conflict_id: Uuid,
resolution: &str,
close_at: Option<DateTime<Utc>>,
close_at_precision: &str,
) -> AppResult<()> {
let row: Option<ConflictRow> = sqlx::query_as(
"SELECT c.old_fact_id, c.new_fact_id, fn_.valid_from, fn_.valid_from_precision
FROM fact_conflicts c JOIN facts fn_ ON fn_.id = c.new_fact_id
WHERE c.id = $1 AND c.kb_id = $2 AND c.status = 'open'",
)
.bind(conflict_id)
.bind(kb_id)
.fetch_optional(pool)
.await?;
let Some((old_fact_id, new_fact_id, new_from, new_from_precision)) = row else {
return Err(utopia_core::AppError::NotFound);
};
let stored = match resolution {
"close" => {
// 闭合点带着它的精度走:人给了日期就用人给的精度,没给就闭合在新事实的
// 起点——那个起点是几月还是几号,闭合点就是几月还是几号。从前一律写 day,
// 「2023 年 6 月接任」把前任闭合成了 6 月 1 日
let (at, precision) = match close_at {
Some(at) => (at, close_at_precision),
None => (
new_from.ok_or_else(|| {
utopia_core::AppError::invalid(
"close_at_required",
"close_at is required when the new fact has no start time",
)
})?,
new_from_precision.as_deref().unwrap_or("day"),
),
};
close_superseded(pool, old_fact_id, at, precision).await?;
"closed"
}
"keep" => "kept_both",
"reject_new" => {
retract(pool, kb_id, new_fact_id).await?;
// 波及:同一新事实撞出的其他 open 冲突一并出队(新事实已死,无从裁起)
sqlx::query(
"UPDATE fact_conflicts
SET status = 'resolved', resolution = 'rejected_new', resolved_at = now()
WHERE new_fact_id = $1 AND status = 'open' AND id <> $2",
)
.bind(new_fact_id)
.bind(conflict_id)
.execute(pool)
.await?;
"rejected_new"
}
other => {
return Err(utopia_core::AppError::Validation(format!(
"Unknown resolution: {other}"
)))
}
};
sqlx::query(
"UPDATE fact_conflicts SET status = 'resolved', resolution = $3, resolved_at = now()
WHERE id = $1 AND kb_id = $2",
)
.bind(conflict_id)
.bind(kb_id)
.bind(stored)
.execute(pool)
.await?;
Ok(())
}
/// 一条谓词的一端挂着**两个以上开放值**的持有者——唯一性没声明(或声明来晚了)
/// 时账本的样子(#341)。这是给人看的提议依据,不是判决:`declared` 为假时它说
/// "这里像是该声明的",为真时它说"声明了,但这些行还没对过账"。
#[derive(Debug, Clone)]
pub struct UniquenessCandidate {
pub predicate_id: Uuid,
pub key: String,
pub label: String,
/// relation | attribute
pub kind: String,
/// "subject"(→ functional)或 "object"(→ inverse_functional)
pub side: &'static str,
/// 这一端的唯一性是否已经声明
pub declared: bool,
/// 挂着两个以上开放值的持有者数
pub holders: usize,
/// 那些持有者身上的开放事实数
pub open_facts: usize,
/// 对账会闭合的区间数(估算,按落库时的规则:起点更早者止于后任起点)
pub would_close: usize,
/// 对账会送进人审的对数(缺时间 / 同时开始 / 低置信)
pub would_review: usize,
/// 头几个持有者与它们的开放值,按年表排
pub examples: Vec<HolderExample>,
}
#[derive(Debug, Clone)]
pub struct HolderExample {
pub holder: String,
pub values: Vec<OpenValue>,
}
#[derive(Debug, Clone)]
pub struct OpenValue {
pub fact_id: Uuid,
pub name: String,
pub valid_from: Option<DateTime<Utc>>,
pub confidence: f32,
/// 起点是怎么来的(同 [`Row::start_unanchored`])
pub valid_from_grade: Option<String>,
}
/// 每个候选带几个例子。
const EXAMPLE_HOLDERS: usize = 3;
pub async fn uniqueness_candidates(
pool: &PgPool,
kb_id: Uuid,
) -> AppResult<Vec<UniquenessCandidate>> {
#[derive(sqlx::FromRow)]
struct Row {
id: Uuid,
predicate_id: Uuid,
key: String,
label: String,
kind: String,
declared: bool,
holder_name: String,
other_name: Option<String>,
object_value: Option<serde_json::Value>,
valid_from: Option<DateTime<Utc>>,
valid_from_grade: Option<String>,
confidence: f32,
}
// 两端各查一遍。`crowded` 先按 (谓词, 持有者) 数不同的值,再把那些持有者
// 身上的开放事实整批取回来——估算要看每一对相邻值的起点与置信度,
// 光有计数不够。开放 = 世界轴没有终点,与落库时对账用的是同一个不变量
let subject_side: Vec<Row> = sqlx::query_as(
"WITH open AS (
SELECT f.id, f.predicate_id, f.subject_id AS holder, f.object_id, f.object_value,
COALESCE(f.object_id::text, f.object_value::text) AS value_key,
f.valid_from, f.valid_from_grade, f.confidence, f.recorded_at
FROM facts f JOIN relation_types r ON r.id = f.predicate_id
WHERE f.kb_id = $1 AND f.invalidated_at IS NULL
AND f.valid_to IS NULL AND f.valid_to_precision IS NULL
AND r.temporal = 'state'
-- 名字不算:一个实体有两个名字是常态,不是「这个属性该唯一」的证据(0041)
AND NOT (r.builtin AND r.key = 'known_as')
AND (f.object_id IS NOT NULL OR f.object_value IS NOT NULL)
),
crowded AS (
SELECT predicate_id, holder FROM open
GROUP BY predicate_id, holder HAVING count(DISTINCT value_key) >= 2
)
SELECT o.id, o.predicate_id, r.key, r.label, r.kind, r.functional AS declared,
h.canonical_name AS holder_name, e.canonical_name AS other_name,
o.object_value, o.valid_from, o.valid_from_grade, o.confidence
FROM open o
JOIN crowded c ON c.predicate_id = o.predicate_id AND c.holder = o.holder
JOIN relation_types r ON r.id = o.predicate_id
JOIN entities h ON h.id = o.holder
LEFT JOIN entities e ON e.id = o.object_id
ORDER BY r.key, h.canonical_name, o.valid_from ASC NULLS LAST, o.recorded_at ASC",
)
.bind(kb_id)
.fetch_all(pool)
.await?;
let object_side: Vec<Row> = sqlx::query_as(
"WITH open AS (
SELECT f.id, f.predicate_id, f.object_id AS holder, f.subject_id,
f.valid_from, f.valid_from_grade, f.confidence, f.recorded_at
FROM facts f JOIN relation_types r ON r.id = f.predicate_id
WHERE f.kb_id = $1 AND f.invalidated_at IS NULL
AND f.valid_to IS NULL AND f.valid_to_precision IS NULL
AND r.temporal = 'state' AND r.kind = 'relation'
AND f.object_id IS NOT NULL
),
crowded AS (
SELECT predicate_id, holder FROM open
GROUP BY predicate_id, holder HAVING count(DISTINCT subject_id) >= 2
)
SELECT o.id, o.predicate_id, r.key, r.label, r.kind, r.inverse_functional AS declared,
h.canonical_name AS holder_name, e.canonical_name AS other_name,
NULL::jsonb AS object_value, o.valid_from, o.valid_from_grade, o.confidence
FROM open o
JOIN crowded c ON c.predicate_id = o.predicate_id AND c.holder = o.holder
JOIN relation_types r ON r.id = o.predicate_id
JOIN entities h ON h.id = o.holder
JOIN entities e ON e.id = o.subject_id
ORDER BY r.key, h.canonical_name, o.valid_from ASC NULLS LAST, o.recorded_at ASC",
)
.bind(kb_id)
.fetch_all(pool)
.await?;
let mut out = Vec::new();
for (side, rows) in [("subject", subject_side), ("object", object_side)] {
// 行已按 (谓词, 持有者, 年表) 排好,顺着切段就是分组
let mut i = 0;
while i < rows.len() {
let pred = rows[i].predicate_id;
let mut cand = UniquenessCandidate {
predicate_id: pred,
key: rows[i].key.clone(),
label: rows[i].label.clone(),
kind: rows[i].kind.clone(),
side,
declared: rows[i].declared,
holders: 0,
open_facts: 0,
would_close: 0,
would_review: 0,
examples: Vec::new(),
};
while i < rows.len() && rows[i].predicate_id == pred {
let holder = rows[i].holder_name.clone();
let mut values = Vec::new();
while i < rows.len()
&& rows[i].predicate_id == pred
&& rows[i].holder_name == holder
{
let r = &rows[i];
values.push(OpenValue {
fact_id: r.id,
name: r
.other_name
.clone()
.or_else(|| r.object_value.as_ref().map(literal_name))
.unwrap_or_else(|| "?".to_string()),
valid_from: r.valid_from,
valid_from_grade: r.valid_from_grade.clone(),
confidence: r.confidence,
});
i += 1;
}
let (close, review) = plan_closures(&values);
cand.holders += 1;
cand.open_facts += values.len();
cand.would_close += close;
cand.would_review += review;
if cand.examples.len() < EXAMPLE_HOLDERS {
cand.examples.push(HolderExample { holder, values });
}
}
out.push(cand);
}
}
Ok(out)
}
/// 一个持有者的开放值按年表排好后,对账会怎么处置:(闭合数, 进人审数)。
///
/// 把 `reconcile_predicate` 的过程干跑一遍,不落库:逐条当"新落库的观察",与
/// 后面还开着的每一条比——起点更早者止于后任起点(自己的起点锚得住才许改写历史);
/// 两条都没起点、或同一天开始,说不清谁接替谁,进人审,两条都还开着;后任没起点
/// 的,它止于前任的起点。三条都没起点的持有者会报三对冲突,与引擎一致。
/// 这是估算——真跑一遍的结果才作数
fn plan_closures(values: &[OpenValue]) -> (usize, usize) {
let mut open = vec![true; values.len()];
let mut close = 0;
let mut review = 0;
for i in 0..values.len() {
if !open[i] {
continue;
}
let new = &values[i];
for j in (i + 1)..values.len() {
if !open[j] {
continue;
}
let old = &values[j];
match (old.valid_from, new.valid_from) {
(_, None) => review += 1,
(Some(of), Some(nf)) if of == nf => review += 1,
(Some(of), Some(nf)) if nf < of => {
if new.valid_from_grade.as_deref() == Some("C") {
review += 1;
} else {
close += 1;
open[i] = false;
break;
}
}
(_, Some(_)) => {
if new.valid_from_grade.as_deref() == Some("C") {
review += 1;
} else {
close += 1;
open[j] = false;
}
}
}
}
}
(close, review)
}
/// 字面值给人看的样子:`{value, unit}` → "28000 CNY",裸标量读成它自己。
fn literal_name(v: &serde_json::Value) -> String {
match v {
serde_json::Value::String(s) => s.clone(),
serde_json::Value::Object(o) => {
let value = match o.get("value") {
Some(serde_json::Value::String(s)) => s.clone(),
Some(other) => other.to_string(),
None => return v.to_string(),
};
match o
.get("unit")
.and_then(|u| u.as_str())
.filter(|u| !u.is_empty())
{
Some(unit) => format!("{value} {unit}"),
None => value,
}
}
other => other.to_string(),
}
}
#[cfg(test)]
mod tests {
use super::*;
use chrono::TimeZone;
fn v(from: Option<(i32, u32, u32)>, grade: Option<&str>) -> OpenValue {
OpenValue {
fact_id: Uuid::now_v7(),
name: String::new(),
valid_from: from.map(|(y, m, d)| Utc.with_ymd_and_hms(y, m, d, 0, 0, 0).unwrap()),
valid_from_grade: grade.map(str::to_string),
confidence: 0.9,
}
}
fn day(y: i32, m: u32, d: u32) -> DateTime<Utc> {
Utc.with_ymd_and_hms(y, m, d, 0, 0, 0).unwrap()
}
/// 时间线上的一行:值、起点、没起点时自带日期的证据
fn row(value: &str, from: Option<DateTime<Utc>>, dated: Option<DateTime<Utc>>) -> Row {
Row {
id: Uuid::now_v7(),
subject_id: Uuid::nil(),
object_id: None,
object_value: Some(serde_json::json!({ "value": value })),
valid_from: from,
valid_from_precision: from.map(|_| "day".to_string()),
valid_to: None,
valid_to_precision: None,
attested_to: None,
end_derived: false,
dated_at: dated,
valid_from_grade: None,
described: false,
}
}
/// 把计划落到行上(改写成新 id 的事与此无关,原地换终点),直到计划为空
fn settle(rows: &mut [Row]) {
let plan = plan_timeline(Uniqueness::SubjectSide, rows);
for (id, end) in plan.ends {
let r = rows.iter_mut().find(|r| r.id == id).unwrap();
r.end_derived = end != End::Open;
(r.valid_to, r.valid_to_precision, r.attested_to) = match end {
End::Open => (None, None, None),
End::At(t, p) => (Some(t), Some(p), None),
End::Unknown(a) => (None, Some("unknown".into()), a),
};
}
assert_eq!(
plan_timeline(Uniqueness::SubjectSide, rows).ends,
vec![],
"一次算完就是最终的样子"
);
}
fn shape(rows: &[Row]) -> Vec<(String, End)> {
let mut out: Vec<_> = rows
.iter()
.map(|r| {
(
r.object_value.as_ref().unwrap()["value"]
.as_str()
.unwrap()
.to_string(),
r.current_end(),
)
})
.collect();
out.sort_by(|a, b| a.0.cmp(&b.0));
out
}
/// 同一批行,不论以什么顺序排进来,算出来的时间线一样
#[test]
fn a_timeline_does_not_depend_on_the_order_its_rows_arrive() {
let base = vec![
row("v1", Some(day(2020, 2, 18)), None),
row("v2", Some(day(2020, 3, 17)), None),
row("v3", None, Some(day(2020, 4, 14))),
row("v4", Some(day(2020, 5, 26)), None),
row("v5", None, Some(day(2020, 6, 8))),
];
let mut first = base.clone();
settle(&mut first);
assert_eq!(
shape(&first),
vec![
("v1".into(), End::At(day(2020, 3, 17), "day".into())),
("v2".into(), End::Unknown(Some(day(2020, 4, 14)))),
("v3".into(), End::At(day(2020, 5, 26), "day".into())),
("v4".into(), End::Unknown(Some(day(2020, 6, 8)))),
("v5".into(), End::Open),
]
);
for rotation in 1..base.len() {
let mut rows = base.clone();
rows.rotate_left(rotation);
rows.reverse();
settle(&mut rows);
assert_eq!(shape(&rows), shape(&first));
}
}
/// 后面那一段挪了、走了,引擎画的终点跟着变;写明的终点不动
#[test]
fn a_derived_end_follows_what_comes_next_and_a_stated_one_stays() {
let mut rows = vec![
row("A", Some(day(2016, 5, 16)), None),
row("B", None, Some(day(2020, 8, 13))),
];
settle(&mut rows);
assert_eq!(rows[0].current_end(), End::Unknown(Some(day(2020, 8, 13))));
// 后来的文件说 B 从 7 月 31 日起:A 止于那一天
rows[1].valid_from = Some(day(2020, 7, 31));
rows[1].valid_from_precision = Some("day".into());
settle(&mut rows);
assert_eq!(
rows[0].current_end(),
End::At(day(2020, 7, 31), "day".into())
);
// B 被撤回:A 重新开着
rows.pop();
settle(&mut rows);
assert_eq!(rows[0].current_end(), End::Open);
assert!(!rows[0].end_derived);
// 原文写明 C 到 2019 年底,后面的 D 从 2019 年 6 月起:两份原文说法相左,不替人挑
let mut stated = vec![
row("C", Some(day(2018, 1, 1)), None),
row("D", Some(day(2019, 6, 1)), None),
];
stated[0].valid_to = Some(day(2019, 12, 31));
stated[0].valid_to_precision = Some("day".into());
assert_eq!(
plan_timeline(Uniqueness::SubjectSide, &stated),
Plan::default()
);
}
/// 合并前的闸门:两个值能排成先后接替就不算叠在一起;排不开的才算
#[test]
fn two_values_overlap_only_when_the_engine_cannot_order_them() {
let succession = vec![
row("HPBB1", Some(day(2016, 5, 16)), None),
row("BBHQ1", None, Some(day(2020, 8, 13))),
];
assert!(!still_overlaps(Uniqueness::SubjectSide, &succession, true));
let same_day = vec![
row("P", Some(day(2020, 1, 1)), None),
row("Q", Some(day(2020, 1, 1)), None),
];
assert!(still_overlaps(Uniqueness::SubjectSide, &same_day, true));
let no_time = vec![row("K", None, None), row("N", Some(day(2020, 1, 1)), None)];
assert!(still_overlaps(Uniqueness::SubjectSide, &no_time, true));
// 两份原文写明的区间相交:引擎不替人挑
let mut stated = vec![
row("C", Some(day(2018, 1, 1)), None),
row("D", Some(day(2019, 6, 1)), None),
];
stated[0].valid_to = Some(day(2019, 12, 31));
stated[0].valid_to_precision = Some("day".into());
assert!(still_overlaps(Uniqueness::SubjectSide, &stated, true));
// 事件与恒常不经引擎排:两个说不出时间的值照旧算撞
let eternal = vec![row("X", None, None), row("Y", None, None)];
assert!(still_overlaps(Uniqueness::SubjectSide, &eternal, false));
}
/// 起点锚不到的后任不许关上前任,也不开矛盾(0045 第 3 刀:等级 C 两样都不做);
/// 前任止于它之后第一个锚得住的后任
#[test]
fn an_unanchored_successor_closes_nothing_and_opens_no_conflict() {
let mut rows = vec![
row("A", Some(day(2020, 1, 1)), None),
row("B", Some(day(2020, 2, 1)), None),
row("C", Some(day(2020, 3, 1)), None),
];
rows[1].valid_from_grade = Some("C".to_string());
let plan = plan_timeline(Uniqueness::SubjectSide, &rows);
assert_eq!(
plan.ends,
vec![
(rows[0].id, End::At(day(2020, 3, 1), "day".into())),
(rows[1].id, End::At(day(2020, 3, 1), "day".into())),
]
);
assert!(plan.held.is_empty(), "锚不到的一对没有什么可判的");
}
/// 读的时候找关上一行的后任,用的是引擎同一条「看图描述出来的」判据,只换了别名(#970)
#[test]
fn the_described_check_takes_another_alias() {
let n = described_sql("n");
assert!(!n.contains("= f.id"), "{n}");
assert_eq!(n.matches("= n.id").count(), 2, "{n}");
}
/// 看图描述出来的后任不许单独关上前任,这一对交给人(0040 决定 4);
/// 前任止于它之后第一个不是描述出来的后任
#[test]
fn a_described_successor_is_held_and_the_next_stated_one_closes() {
let mut rows = vec![
row("A", Some(day(2020, 1, 1)), None),
row("B", Some(day(2020, 2, 1)), None),
row("C", Some(day(2020, 3, 1)), None),
];
rows[1].described = true;
let plan = plan_timeline(Uniqueness::SubjectSide, &rows);
assert_eq!(
plan.ends,
vec![
(rows[0].id, End::At(day(2020, 3, 1), "day".into())),
(rows[1].id, End::At(day(2020, 3, 1), "day".into())),
]
);
assert_eq!(plan.held, vec![(rows[0].id, rows[1].id)]);
}
#[test]
fn a_chain_of_three_closes_twice() {
let values = [
v(Some((2023, 2, 1)), None),
v(Some((2024, 7, 5)), None),
v(Some((2025, 9, 1)), None),
];
assert_eq!(plan_closures(&values), (2, 0));
}
#[test]
fn what_the_engine_would_not_close_goes_to_review() {
// 同一天开始
assert_eq!(
plan_closures(&[v(Some((2024, 1, 1)), None), v(Some((2024, 1, 1)), None)]),
(0, 1)
);
// 两条都没起点
assert_eq!(plan_closures(&[v(None, None), v(None, None)]), (0, 1));
// 起点更早的那条锚不到,不许它改写历史
assert_eq!(
plan_closures(&[
v(Some((2023, 1, 1)), Some("C")),
v(Some((2024, 1, 1)), None)
]),
(0, 1)
);
// 后任没起点:它止于前任的起点(落库时的"旧事实无起点也适用")
assert_eq!(
plan_closures(&[v(Some((2023, 1, 1)), None), v(None, None)]),
(1, 0)
);
// 一条不成对
assert_eq!(plan_closures(&[v(Some((2023, 1, 1)), None)]), (0, 0));
// 三条都没起点:每一对都说不清,三对冲突,与引擎一致
assert_eq!(
plan_closures(&[v(None, None), v(None, None), v(None, None)]),
(0, 3)
);
// 有起点的一条闭合两条没起点的:它们都止于它的起点
assert_eq!(
plan_closures(&[v(Some((2023, 1, 1)), None), v(None, None), v(None, None)]),
(2, 0)
);
}
#[test]
fn a_literal_reads_as_a_value_with_its_unit() {
assert_eq!(
literal_name(&serde_json::json!({ "value": 28000, "unit": "CNY" })),
"28000 CNY"
);
assert_eq!(
literal_name(&serde_json::json!({ "value": "Staff Engineer" })),
"Staff Engineer"
);
assert_eq!(literal_name(&serde_json::json!(32000)), "32000");
assert_eq!(literal_name(&serde_json::json!("plain")), "plain");
}
}