Skip to content

World's first open-source enterprise world model.

A late declaration closes what it should have closed (#354)

WaylandYangd2bfb62a25b7
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index 41d8743e..76b4454b 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -221,6 +221,15 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
patch(ontology_routes::update_relation_type)
.delete(ontology_routes::delete_relation_type),
)
+ // 声明来晚了(#341):谁的哪一端挂着两个以上开放值;补上声明后把账对一遍
+ .route(
+ "/kbs/{id}/ontology/uniqueness",
+ get(ontology_routes::uniqueness_candidates),
+ )
+ .route(
+ "/kbs/{id}/ontology/relation-types/{type_id}/reconcile",
+ post(ontology_routes::reconcile_relation_type),
+ )
.route(
"/kbs/{id}/ontology/misses/dismiss",
post(ontology_routes::dismiss_miss),
diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rs
index a969052d..22e46fc3 100644
--- a/crates/utopia-server/src/api/ontology_routes.rs
+++ b/crates/utopia-server/src/api/ontology_routes.rs
@@ -373,6 +373,79 @@ pub async fn delete_relation_type(
Ok(Json(json!({ "ok": true })))
}
+/// 一条谓词的一端挂着两个以上开放值的持有者(#341)。
+///
+/// 本体自己长出来的库里没人声明过唯一性,接任不会闭合前任,三个人同时在管
+/// 一个项目——而「谁在管」正是这个产品的题。引擎永不自动推断 functional
+/// (bootstrap_ontology.rs 写了为什么),所以它只能被**问**:这里把证据摆出来
+/// ——哪条谓词、哪一端、多少持有者、对账会闭合几条、几条要进人审——人决定。
+/// `declared` 为真的那些是声明了却还没对过账的(导入的、声明之前就在的)。
+pub async fn uniqueness_candidates(
+ State(state): State<AppState>,
+ AuthUser(user): AuthUser,
+ Path(kb_id): Path<Uuid>,
+) -> ApiResult<Json<serde_json::Value>> {
+ require_kb(&state, &user, kb_id, Role::Viewer).await?;
+ let cands = utopia_store::temporal::uniqueness_candidates(&state.pool, kb_id).await?;
+ let items: Vec<serde_json::Value> = cands
+ .iter()
+ .map(|c| {
+ json!({
+ "predicate_id": c.predicate_id,
+ "key": c.key,
+ "label": c.label,
+ "kind": c.kind,
+ "side": c.side,
+ "axiom": if c.side == "subject" { "functional" } else { "inverse_functional" },
+ "declared": c.declared,
+ "holders": c.holders,
+ "open_facts": c.open_facts,
+ "would_close": c.would_close,
+ "would_review": c.would_review,
+ "examples": c.examples.iter().map(|e| json!({
+ "holder": e.holder,
+ "values": e.values.iter().map(|v| json!({
+ "fact_id": v.fact_id,
+ "name": v.name,
+ "valid_from": v.valid_from.map(|t| t.to_rfc3339()),
+ "confidence": v.confidence,
+ })).collect::<Vec<_>>(),
+ })).collect::<Vec<_>>(),
+ })
+ })
+ .collect();
+ Ok(Json(json!({ "candidates": items })))
+}
+
+/// 补上声明之后,把这条谓词已经在账上的开放行对一遍(#341)。
+///
+/// 与落库时同一条路:作废 + 改写,supersedes 链回旧行,记录轴倒回声明之前
+/// 仍看得见原来的行;拿不准的进人审。谓词没有唯一性声明时拒绝——
+/// 声明是人的事,这里只执行。响应里报闭合了几条、几条进了人审。
+pub async fn reconcile_relation_type(
+ State(state): State<AppState>,
+ AuthUser(user): AuthUser,
+ Path((kb_id, id)): Path<(Uuid, Uuid)>,
+) -> ApiResult<Json<serde_json::Value>> {
+ require_kb(&state, &user, kb_id, Role::Editor).await?;
+ let report = utopia_store::temporal::reconcile_predicate(&state.pool, kb_id, id).await?;
+ let _ = utopia_store::audit::record(
+ &state.pool,
+ Some(kb_id),
+ user.id,
+ "relation_type.reconciled",
+ "relation_type",
+ Some(id),
+ json!({ "corrected": report.corrected.len(), "conflicts": report.conflicts }),
+ )
+ .await;
+ Ok(Json(json!({
+ "corrected": report.corrected.len(),
+ "conflicts": report.conflicts,
+ "corrected_ids": report.corrected,
+ })))
+}
+
#[derive(Deserialize)]
pub struct DismissMissReq {
pub kind: String,
diff --git a/crates/utopia-store/src/temporal.rs b/crates/utopia-store/src/temporal.rs
index 9c57b390..0c4b2108 100644
--- a/crates/utopia-store/src/temporal.rs
+++ b/crates/utopia-store/src/temporal.rs
@@ -77,14 +77,16 @@ pub async fn reconcile_new_fact(
AND valid_to IS NULL AND valid_to_precision IS NULL
AND invalidated_at IS NULL
AND id <> $4
- AND (object_id IS DISTINCT FROM $5 OR object_value IS DISTINCT FROM $6)"
+ AND (object_id IS DISTINCT FROM $5 OR object_value IS DISTINCT FROM $6)
+ ORDER BY valid_from ASC NULLS LAST, recorded_at ASC"
}
Uniqueness::ObjectSide => {
"SELECT id, valid_from, valid_from_precision FROM facts
WHERE kb_id = $1 AND object_id = $5 AND predicate_id = $3
AND valid_to IS NULL AND valid_to_precision IS NULL
AND invalidated_at IS NULL
- AND id <> $4 AND subject_id IS DISTINCT FROM $2"
+ AND id <> $4 AND subject_id IS DISTINCT FROM $2
+ ORDER BY valid_from ASC NULLS LAST, recorded_at ASC"
}
};
let q = sqlx::query_as(sql)
@@ -120,15 +122,16 @@ pub async fn reconcile_new_fact(
record_conflict(pool, kb_id, old.id, new_fact_id, "low_confidence").await?;
report.conflicts += 1;
} else {
- report.corrected.push(
- close_superseded(
- pool,
- new_fact_id,
- of,
- old.valid_from_precision.as_deref().unwrap_or("day"),
- )
- .await?,
- );
+ if let Some(id) = close_superseded(
+ pool,
+ new_fact_id,
+ of,
+ old.valid_from_precision.as_deref().unwrap_or("day"),
+ )
+ .await?
+ {
+ report.corrected.push(id);
+ }
}
}
// 常规接替:旧事实闭合在新事实的开始(旧事实无起点也适用——起点未知但已结束)
@@ -137,15 +140,16 @@ pub async fn reconcile_new_fact(
record_conflict(pool, kb_id, old.id, new_fact_id, "low_confidence").await?;
report.conflicts += 1;
} else {
- report.corrected.push(
- close_superseded(
- pool,
- old.id,
- nf,
- new_validity.from_precision.unwrap_or("day"),
- )
- .await?,
- );
+ if let Some(id) = close_superseded(
+ pool,
+ old.id,
+ nf,
+ new_validity.from_precision.unwrap_or("day"),
+ )
+ .await?
+ {
+ report.corrected.push(id);
+ }
}
}
}
@@ -168,8 +172,80 @@ pub async fn reconcile_moved_facts(
if fact_ids.is_empty() {
return Ok(ReconcileReport::default());
}
+ reconcile_open(pool, kb_id, fact_ids, "f.recorded_at").await
+}
+
+/// 声明来晚了:一条谓词上所有开放事实按**年表**重跑一遍落库时的对账(#341)。
+///
+/// 本体自己长出来的库里没人声明过唯一性,接任不会闭合前任——三个人同时在管一个
+/// 项目。人补上声明之后,这里把已经躺在账上的行对一遍。走的是与落库时同一条
+/// 路(作废 + 改写,supersedes 链回旧行),所以记录轴倒回声明之前仍看得见三条
+/// 开放的行;拿不准的(缺时间 / 同时开始 / 低置信)照旧进人审,不硬闭合。
+///
+/// 按 `valid_from` 而不是 `recorded_at` 走:合并搬移按摄入顺序回放是对的,
+/// 因为那是在重演落库;这里三条早就都在账上,谁先谁后只有年表说了算——
+/// 前任必须闭合在**最早的**后任起点上,而周七的文档完全可能比李四的先到。
+///
+/// 没有声明的谓词拒绝:引擎不替人推断(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 valid_to IS NULL AND valid_to_precision IS NULL
+ ORDER BY valid_from ASC NULLS LAST, recorded_at ASC",
+ )
+ .bind(kb_id)
+ .bind(predicate_id)
+ .fetch_all(pool)
+ .await?;
+ if ids.is_empty() {
+ return Ok(ReconcileReport::default());
+ }
+ reconcile_open(
+ pool,
+ kb_id,
+ &ids,
+ "f.valid_from ASC NULLS LAST, f.recorded_at ASC",
+ )
+ .await
+}
+
+/// 一批开放期事实按 `order`(SQL 的 ORDER BY 表达式)逐条当作"新落库的观察"对账。
+async fn reconcile_open(
+ pool: &PgPool,
+ kb_id: Uuid,
+ fact_ids: &[Uuid],
+ order: &str,
+) -> AppResult<ReconcileReport> {
#[derive(sqlx::FromRow)]
- struct MovedFact {
+ struct OpenRow {
id: Uuid,
subject_id: Uuid,
predicate_id: Uuid,
@@ -181,7 +257,7 @@ pub async fn reconcile_moved_facts(
functional: bool,
inverse_functional: bool,
}
- let rows: Vec<MovedFact> = sqlx::query_as(
+ let rows: Vec<OpenRow> = sqlx::query_as(&format!(
"SELECT f.id, f.subject_id, f.predicate_id, f.object_id, f.object_value,
f.valid_from, f.valid_from_precision,
f.confidence, r.functional, r.inverse_functional
@@ -189,8 +265,8 @@ pub async fn reconcile_moved_facts(
WHERE f.kb_id = $1 AND f.id = ANY($2)
AND f.invalidated_at IS NULL AND f.valid_to IS NULL
AND r.temporal = 'state' AND (r.functional OR r.inverse_functional)
- ORDER BY f.recorded_at",
- )
+ ORDER BY {order}"
+ ))
.bind(kb_id)
.bind(fact_ids)
.fetch_all(pool)
@@ -242,13 +318,13 @@ pub async fn reconcile_moved_facts(
}
/// 作废 + 改写:旧行记 invalidated_at(认知轴),插入闭合区间的修正行
-/// (世界轴),证据引用随行复制。返回修正行 id。
+/// (世界轴),证据引用随行复制。返回修正行 id;`None` = 这条已不是开放行,没动。
pub async fn close_superseded(
pool: &PgPool,
fact_id: Uuid,
valid_to: DateTime<Utc>,
valid_to_precision: &str,
-) -> AppResult<Uuid> {
+) -> AppResult<Option<Uuid>> {
let mut tx = pool.begin().await?;
let corrected = Uuid::now_v7();
let inserted: Option<(Uuid,)> = sqlx::query_as(
@@ -266,10 +342,10 @@ pub async fn close_superseded(
.bind(valid_to_precision)
.fetch_optional(&mut *tx)
.await?;
- // 已被并发修正过:不重复动手
+ // 已被改写过(并发,或同一批对账里前一步已经闭合了它):不重复动手,也不算一次修正
if inserted.is_none() {
tx.rollback().await?;
- return Ok(fact_id);
+ return Ok(None);
}
sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = $1")
.bind(fact_id)
@@ -277,7 +353,7 @@ pub async fn close_superseded(
.await?;
copy_evidence(&mut tx, fact_id, corrected).await?;
tx.commit().await?;
- Ok(corrected)
+ Ok(Some(corrected))
}
/// 证据引用随修正行复制。表层谓词一起搬:纠正的是时间区间,不是原文说了什么。
@@ -485,3 +561,319 @@ pub async fn resolve_conflict(
.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,
+}
+
+/// 每个候选带几个例子。
+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>>,
+ 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.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 (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.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.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.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,
+ 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.confidence < AUTO_CLOSE_MIN_CONFIDENCE {
+ review += 1;
+ } else {
+ close += 1;
+ open[i] = false;
+ break;
+ }
+ }
+ (_, Some(_)) => {
+ if new.confidence < AUTO_CLOSE_MIN_CONFIDENCE {
+ 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)>, confidence: f32) -> 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()),
+ confidence,
+ }
+ }
+
+ #[test]
+ fn a_chain_of_three_closes_twice() {
+ let values = [
+ v(Some((2023, 2, 1)), 0.9),
+ v(Some((2024, 7, 5)), 0.9),
+ v(Some((2025, 9, 1)), 0.9),
+ ];
+ 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)), 0.9), v(Some((2024, 1, 1)), 0.9)]),
+ (0, 1)
+ );
+ // 两条都没起点
+ assert_eq!(plan_closures(&[v(None, 0.9), v(None, 0.9)]), (0, 1));
+ // 起点更早的那条置信度不够,不许它改写历史
+ assert_eq!(
+ plan_closures(&[v(Some((2023, 1, 1)), 0.5), v(Some((2024, 1, 1)), 0.9)]),
+ (0, 1)
+ );
+ // 后任没起点:它止于前任的起点(落库时的"旧事实无起点也适用")
+ assert_eq!(
+ plan_closures(&[v(Some((2023, 1, 1)), 0.9), v(None, 0.9)]),
+ (1, 0)
+ );
+ // 一条不成对
+ assert_eq!(plan_closures(&[v(Some((2023, 1, 1)), 0.9)]), (0, 0));
+ // 三条都没起点:每一对都说不清,三对冲突,与引擎一致
+ assert_eq!(
+ plan_closures(&[v(None, 0.9), v(None, 0.9), v(None, 0.9)]),
+ (0, 3)
+ );
+ // 有起点的一条闭合两条没起点的:它们都止于它的起点
+ assert_eq!(
+ plan_closures(&[v(Some((2023, 1, 1)), 0.9), v(None, 0.9), v(None, 0.9)]),
+ (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");
+ }
+}
diff --git a/crates/utopia-store/tests/a_declaration_arrives_late.rs b/crates/utopia-store/tests/a_declaration_arrives_late.rs
new file mode 100644
index 00000000..1e8b6609
--- /dev/null
+++ b/crates/utopia-store/tests/a_declaration_arrives_late.rs
@@ -0,0 +1,312 @@
+//! 声明来晚了:本体自己长出来的库里,接任不会闭合前任(#341)。
+//!
+//! 钉住三样:
+//! - **候选是算出来的,不是猜出来的**——同一端挂着两个以上开放值的持有者才算;
+//! 每人各管一个项目的那一端不报
+//! - **补上声明之后能对账**——按年表走:三条开放事实闭合成一条链,前任闭合在
+//! **最早的**后任起点上,与摄入顺序无关;再跑一遍不动
+//! - **没声明就不动**——对账接口拒绝,引擎不替人推断
+//!
+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆。
+
+use chrono::{DateTime, TimeZone, Utc};
+use sqlx::PgPool;
+use utopia_store::temporal;
+use uuid::Uuid;
+
+struct Fixture {
+ org: Uuid,
+ kb: Uuid,
+ /// 关系,一位公理都没声明
+ leads: Uuid,
+ /// 属性,同样没声明
+ salary: Uuid,
+ aurora: Uuid,
+ zhang: Uuid,
+ li: Uuid,
+ zhou: Uuid,
+ lin: Uuid,
+}
+
+fn day(y: i32, m: u32, d: u32) -> DateTime<Utc> {
+ Utc.with_ymd_and_hms(y, m, d, 0, 0, 0).unwrap()
+}
+
+async fn seed(pool: &PgPool) -> anyhow::Result<Fixture> {
+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let etype = Uuid::now_v7();
+ let (leads, salary) = (Uuid::now_v7(), Uuid::now_v7());
+ let (aurora, zhang, li, zhou, lin) = (
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ );
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'late-declaration-test')")
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'late-declaration-test')",
+ )
+ .bind(ws)
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'late-declaration-test')",
+ )
+ .bind(kb)
+ .bind(ws)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'thing', 'Thing')",
+ )
+ .bind(etype)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO relation_types (id, kb_id, key, label) VALUES ($1, $2, 'leads', 'leads')",
+ )
+ .bind(leads)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO relation_types (id, kb_id, key, label, kind, datatype, unit)
+ VALUES ($1, $2, 'salary', 'salary', 'attribute', 'number', 'CNY')",
+ )
+ .bind(salary)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ for (id, name) in [
+ (aurora, "Project Aurora"),
+ (zhang, "Zhang San"),
+ (li, "Li Si"),
+ (zhou, "Zhou Qi"),
+ (lin, "Lin Zhao"),
+ ] {
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, type_id, canonical_name) VALUES ($1, $2, $3, $4)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(etype)
+ .bind(name)
+ .execute(pool)
+ .await?;
+ }
+ Ok(Fixture {
+ org,
+ kb,
+ leads,
+ salary,
+ aurora,
+ zhang,
+ li,
+ zhou,
+ lin,
+ })
+}
+
+/// 一条开放的关系事实,起点按天。
+async fn edge(
+ pool: &PgPool,
+ kb: Uuid,
+ s: Uuid,
+ p: Uuid,
+ o: Uuid,
+ from: DateTime<Utc>,
+) -> anyhow::Result<Uuid> {
+ let id = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id, valid_from, valid_from_precision)
+ VALUES ($1, $2, $3, $4, $5, $6, 'day')",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(s)
+ .bind(p)
+ .bind(o)
+ .bind(from)
+ .execute(pool)
+ .await?;
+ Ok(id)
+}
+
+/// 一条开放的属性事实,值走 `object_value`。
+async fn attr(
+ pool: &PgPool,
+ kb: Uuid,
+ s: Uuid,
+ p: Uuid,
+ value: serde_json::Value,
+ from: DateTime<Utc>,
+) -> anyhow::Result<Uuid> {
+ let id = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_value, valid_from, valid_from_precision)
+ VALUES ($1, $2, $3, $4, $5, $6, 'day')",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(s)
+ .bind(p)
+ .bind(value)
+ .bind(from)
+ .execute(pool)
+ .await?;
+ Ok(id)
+}
+
+/// 一条谓词上还活着的事实:(主语名, 起点, 终点),按起点排。
+async fn live(
+ pool: &PgPool,
+ kb: Uuid,
+ p: Uuid,
+) -> anyhow::Result<Vec<(String, Option<DateTime<Utc>>, Option<DateTime<Utc>>)>> {
+ Ok(sqlx::query_as(
+ "SELECT e.canonical_name, f.valid_from, f.valid_to
+ FROM facts f JOIN entities e ON e.id = f.subject_id
+ WHERE f.kb_id = $1 AND f.predicate_id = $2 AND f.invalidated_at IS NULL
+ ORDER BY f.valid_from",
+ )
+ .bind(kb)
+ .bind(p)
+ .fetch_all(pool)
+ .await?)
+}
+
+#[tokio::test]
+async fn a_succession_closes_once_someone_declares_it() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let f = seed(&pool).await?;
+
+ let run = async {
+ // 摄入顺序故意打乱:李四先到,周七次之,张三最后——年表与摄入顺序不同
+ edge(&pool, f.kb, f.li, f.leads, f.aurora, day(2024, 7, 5)).await?;
+ edge(&pool, f.kb, f.zhou, f.leads, f.aurora, day(2025, 9, 1)).await?;
+ edge(&pool, f.kb, f.zhang, f.leads, f.aurora, day(2023, 2, 1)).await?;
+ attr(
+ &pool,
+ f.kb,
+ f.lin,
+ f.salary,
+ serde_json::json!({ "value": 28000, "unit": "CNY" }),
+ day(2023, 6, 1),
+ )
+ .await?;
+ attr(
+ &pool,
+ f.kb,
+ f.lin,
+ f.salary,
+ serde_json::json!({ "value": 32000, "unit": "CNY" }),
+ day(2024, 2, 20),
+ )
+ .await?;
+
+ // —— 候选 ——
+ let cands = temporal::uniqueness_candidates(&pool, f.kb).await?;
+ let on_leads: Vec<_> = cands.iter().filter(|c| c.predicate_id == f.leads).collect();
+ assert_eq!(on_leads.len(), 1, "每人各管一个项目:主语侧不该报");
+ let leads = on_leads[0];
+ assert_eq!(leads.side, "object");
+ assert!(!leads.declared);
+ assert_eq!((leads.holders, leads.open_facts), (1, 3));
+ assert_eq!((leads.would_close, leads.would_review), (2, 0));
+ let ex = &leads.examples[0];
+ assert_eq!(ex.holder, "Project Aurora");
+ assert_eq!(
+ ex.values.iter().map(|v| v.name.as_str()).collect::<Vec<_>>(),
+ ["Zhang San", "Li Si", "Zhou Qi"],
+ "例子按年表排,不按摄入顺序"
+ );
+ let salary = cands
+ .iter()
+ .find(|c| c.predicate_id == f.salary)
+ .expect("两份开放的薪资是主语侧的候选");
+ assert_eq!(salary.side, "subject");
+ assert_eq!((salary.holders, salary.open_facts, salary.would_close), (1, 2, 1));
+ assert_eq!(salary.examples[0].values[0].name, "28000 CNY", "字面值带单位");
+
+ // —— 没声明就不动 ——
+ assert!(
+ temporal::reconcile_predicate(&pool, f.kb, f.leads).await.is_err(),
+ "没有唯一性声明的谓词不能对账:引擎不替人推断"
+ );
+ assert_eq!(live(&pool, f.kb, f.leads).await?.len(), 3);
+
+ // —— 声明宾语侧唯一,对账 ——
+ sqlx::query("UPDATE relation_types SET inverse_functional = TRUE WHERE id = $1")
+ .bind(f.leads)
+ .execute(&pool)
+ .await?;
+ let r = temporal::reconcile_predicate(&pool, f.kb, f.leads).await?;
+ assert_eq!((r.corrected.len(), r.conflicts), (2, 0));
+ assert_eq!(
+ live(&pool, f.kb, f.leads).await?,
+ vec![
+ ("Zhang San".to_string(), Some(day(2023, 2, 1)), Some(day(2024, 7, 5))),
+ ("Li Si".to_string(), Some(day(2024, 7, 5)), Some(day(2025, 9, 1))),
+ ("Zhou Qi".to_string(), Some(day(2025, 9, 1)), None),
+ ],
+ "前任闭合在最早的后任起点上:张三止于李四,李四止于周七"
+ );
+ // 被改写的原行还在,记录轴倒回去看得见
+ let invalidated: i64 = sqlx::query_scalar(
+ "SELECT count(*) FROM facts WHERE kb_id = $1 AND predicate_id = $2 AND invalidated_at IS NOT NULL",
+ )
+ .bind(f.kb)
+ .bind(f.leads)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(invalidated, 2);
+
+ // 再跑一遍不动;候选里也不再有它
+ let again = temporal::reconcile_predicate(&pool, f.kb, f.leads).await?;
+ assert!(again.corrected.is_empty() && again.conflicts == 0);
+ assert!(temporal::uniqueness_candidates(&pool, f.kb)
+ .await?
+ .iter()
+ .all(|c| c.predicate_id != f.leads));
+
+ // —— 属性走主语侧 ——
+ sqlx::query("UPDATE relation_types SET functional = TRUE WHERE id = $1")
+ .bind(f.salary)
+ .execute(&pool)
+ .await?;
+ let r = temporal::reconcile_predicate(&pool, f.kb, f.salary).await?;
+ assert_eq!((r.corrected.len(), r.conflicts), (1, 0));
+ let closed: Option<DateTime<Utc>> = sqlx::query_scalar(
+ "SELECT valid_to FROM facts
+ WHERE kb_id = $1 AND predicate_id = $2 AND invalidated_at IS NULL
+ AND object_value->>'value' = '28000'",
+ )
+ .bind(f.kb)
+ .bind(f.salary)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(closed, Some(day(2024, 2, 20)), "旧薪资止于新薪资的起点");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ // 先删库再删 org:pending_facts.proposed_by 之类不级联到 org
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(f.org)
+ .execute(&pool)
+ .await?;
+ run
+}
diff --git a/scripts/bench/README.md b/scripts/bench/README.md
index 655f2f95..ad7e60f0 100644
--- a/scripts/bench/README.md
+++ b/scripts/bench/README.md
@@ -208,12 +208,17 @@ node scripts/bench/run.mjs --corpus pharma --ontology /tmp/schemaorg.ttl --label
`known_gap: true` 的题目**不进主分**,单独一栏。它们钉住的是已知还没做对的行为,
修好那天自己翻绿;让主分一直背着一个我们已经知道的数,只会让人不再看它。
+每一组都带着几条没裁的消解审核项(同名的 Meridian Systems / Project Aurora 分成了两三个
+实体,宁分勿合,等人)。脚本不替人裁,题目按名字取第一个匹配的实体——这是这份数字的
+一个已知噪音源,不藏。
+
## 数字(2026-09-05,dev @ 619061e,DeepSeek-V3 + bge-m3)
| 配置 | 主分 | 世界轴 | 记录轴 | 已知缺口 |
|---|---|---|---|---|
| 声明了唯一性公理 | **35 / 35** | 21 / 21 | 14 / 14 | 0 / 2 |
| 本体自己长(`--no-declare`) | **28 / 35** | 15 / 21 | 13 / 14 | 1 / 2 |
+| 本体自己长,灌完再声明、对账(`--no-declare --reconcile`) | **34 / 35** | 21 / 21 | 13 / 14 | 1 / 2 |
两组的差落在**需要自动闭合**的那几题上:三任接力(谁在管 Aurora 的四个时刻)和
薪资更正(两个时刻)。原因只有一个:自动闭合按 `functional` / `inverse_functional`
@@ -233,6 +238,23 @@ Zhou Qi | leads | Project Aurora | from 2025-09-01 | (无终点) | live
声明那一组里,**合并倒回**与**更正倒回**都是满分——#337 与 #311 两刀在真实摄入
路径上是对的,不只是在连库测试里对。
+第三行是 #341 那一刀之后新用户走的路:先灌、本体自己长、然后有人接受声明。
+`GET /ontology/uniqueness` 报出「哪条谓词的哪一端挂着两个以上开放值」,跑分脚本拿语料的
+公理表当那个人——只接受语料本来就声明了的那一端——PATCH 打开它、POST reconcile 把账上
+已有的行按年表对一遍。世界轴回到满分;记录轴那一题(`adviser-record-wave1`)与声明无关:
+`advises` 只出现过一次,自动扩展没采纳它,那条事实从来没落过账。
+
+**全收过一次,分数反而更歪。** 第一版脚本把候选全接受了——`leads` 的主语侧(一人只管
+一个项目)、`works_for` 的宾语侧(一家公司只有一个员工)也被打开,李四的 Aurora 被
+Helios 闭合,张三反而止于周七。候选是证据,不是判决;这正是产品把这一步留给人的原因,
+bootstrap_ontology.rs 里那句「functional 永不自动」在这里被量了一次。
+
+**先等队列清空再记时刻。** 文档 `done` 之后本体自动扩展还在另一个任务里跑:把本体没认下
+的谓词建出来、把那些事实改写过去。前两次 `--reconcile` 报了零条候选,是因为记时刻、
+算候选时 `leads` 这条谓词还不存在;同一个原因也让灌完的记录轴时刻落在事实之前——
+之前 `--no-declare` 那一组的 28 与 25 之间的抖动,一部分就是它。现在每一波都等
+`jobs` 里这个库的任务清空再记时刻。
+
第一版(25 题、没有更正/合并/三任接力)的数字是 25/25 对 15/25,第二版(36 题主分)
是 36/36 对 29/36,都留在 git 历史里。第三版只是把 `lin-zhao-employer-2023-01` 挪进
已知缺口(它的 `not` 里补了 Platform Group,见 #352),主分的分母跟着少一。
diff --git a/scripts/bench/temporal.mjs b/scripts/bench/temporal.mjs
index b5f7bc10..9debb330 100644
--- a/scripts/bench/temporal.mjs
+++ b/scripts/bench/temporal.mjs
@@ -22,6 +22,8 @@
// # 复用已灌好的库,只重打分
// node scripts/bench/temporal.mjs --corpus zh # 换一套语料与题目(corpus.zh.json)
// node scripts/bench/temporal.mjs --kb … --chat --only a,b # 只重问几题,看它们的工具轨迹
+// node scripts/bench/temporal.mjs --label late --no-declare --reconcile
+// # 本体自己长,灌完再接受声明、对账(#341)
//
// 环境变量:BENCH_BASE / BENCH_EMAIL / BENCH_PASSWORD / BENCH_PSQL(同 run.mjs)。
@@ -202,6 +204,16 @@ async function main() {
process.stderr.write(` 抽取 ${done}/${want} 篇\n`);
return done >= want ? true : done;
});
+ // 文档 done 之后还有活:本体自动扩展(bootstrap_ontology)在**另一个任务里**
+ // 把本体没认下的谓词建出来、把那些事实改写过去;类型消解也是。不等它们,
+ // 时刻就记在 `leads` 还不存在的那一刻——记录轴倒回去看不到接任,候选也是空的
+ // (`--reconcile` 第一次就是这样报了零条)。等队列清空再记时刻
+ await until(async () => {
+ const busy = num(
+ `SELECT count(*) FROM jobs WHERE payload->>'kb_id'='${kb}' AND status IN ('queued','running')`,
+ );
+ return busy === 0 ? true : busy;
+ });
// 删除也是记录轴上的事件(#268):墓碑留着,这一波之前的时刻仍看得见它
for (const filename of wave.delete || []) {
const id = psql(
@@ -248,6 +260,10 @@ async function main() {
}
if (!Object.keys(stamps).length) throw new Error("复用库时要给 --stamps");
+ // 声明来晚了(#341):新用户走的路——先灌、本体自己长、然后才有人接受声明。
+ // 三波都灌完再对账,记录轴上的时刻都在对账之前,倒回去看到的仍是三条开放的行
+ const reconciled = "reconcile" in args ? await acceptUniqueness(kb, corpus.axioms || []) : null;
+
// 实体按名字找一次,后面所有题目复用。**合并掉的实体在这里找不到**——
// 它已经不是一个节点了;问它的题目从留下的那一方或它挂过的项目那边问
const ids = new Map();
@@ -359,6 +375,7 @@ async function main() {
label,
corpus: corpus.name,
declared: !("no-declare" in args),
+ reconciled,
kb,
stamps,
at: new Date().toISOString(),
@@ -405,6 +422,69 @@ async function main() {
);
}
+/// 声明来晚了(#341):`uniqueness` 报出候选,**语料的公理表替人表态**——只接受语料
+/// 本来就声明了那一端的(一个项目一个 leader,一人一份薪资),PATCH 打开它、再 POST
+/// reconcile 把账上已有的行对一遍。其余候选原样记下,不收:第一版全收过一次,
+/// `leads` 主语侧(一人只管一个项目)和 `works_for` 宾语侧(一家公司只有一个员工)
+/// 也被打开了,李四的 Aurora 被 Helios 闭合,分数反而更歪——这正是产品把这一步
+/// 留给人的原因。返回每条候选的估算与实际——两者不一致就是引擎的规则变了
+async function acceptUniqueness(kb, axioms) {
+ const wanted = new Map(
+ axioms.map((a) => [a.key, { functional: !!a.functional, inverse_functional: !!a.inverse_functional }]),
+ );
+ const { candidates } = await api("GET", `/api/v1/kbs/${kb}/ontology/uniqueness`);
+ const { relation_types } = await api("GET", `/api/v1/kbs/${kb}/ontology`);
+ const byId = new Map(relation_types.map((r) => [r.id, r]));
+ const rows = [];
+ for (const c of candidates) {
+ const r = byId.get(c.predicate_id);
+ if (!r) continue;
+ const declared = wanted.get(c.key);
+ if (!declared || !declared[c.axiom]) {
+ rows.push({ key: c.key, axiom: c.axiom, holders: c.holders, skipped: true });
+ process.stderr.write(` 候选 ${c.key} ${c.axiom}:${c.holders} 个持有者——语料没声明,不收\n`);
+ continue;
+ }
+ if (!c.declared) {
+ // 同一谓词两端都是候选时,第二次 PATCH 要带着第一次打开的那一位
+ r.functional = r.functional || c.side === "subject";
+ r.inverse_functional = r.inverse_functional || c.side === "object";
+ await api("PATCH", `/api/v1/kbs/${kb}/ontology/relation-types/${r.id}`, {
+ label: r.label,
+ temporal: r.temporal,
+ functional: r.functional,
+ inverse_functional: r.inverse_functional,
+ is_transitive: r.is_transitive,
+ is_symmetric: r.is_symmetric,
+ is_asymmetric: r.is_asymmetric,
+ is_irreflexive: r.is_irreflexive,
+ inverse_of: r.inverse_of,
+ sub_property_of: r.sub_property_of,
+ description: r.description,
+ datatype: r.datatype,
+ unit: r.unit,
+ });
+ }
+ const rep = await api(
+ "POST",
+ `/api/v1/kbs/${kb}/ontology/relation-types/${r.id}/reconcile`,
+ {},
+ );
+ rows.push({
+ key: c.key,
+ axiom: c.axiom,
+ holders: c.holders,
+ estimated: { close: c.would_close, review: c.would_review },
+ actual: { close: rep.corrected, review: rep.conflicts },
+ });
+ process.stderr.write(
+ ` 声明 ${c.key} ${c.axiom}:${c.holders} 个持有者,` +
+ `估 ${c.would_close} 闭合 / ${c.would_review} 进审,实际 ${rep.corrected} / ${rep.conflicts}\n`,
+ );
+ }
+ return rows;
+}
+
/// 按名字找一个**现在还是节点**的实体。
async function entityByName(kb, name) {
const found = await api("GET", `/api/v1/kbs/${kb}/entities?q=${encodeURIComponent(name)}`);