Skip to content

World's first open-source enterprise world model.

An event holds at the moment it names (#487)

WaylandYangb99bcefa9c78
diff --git a/crates/utopia-extract/src/lib.rs b/crates/utopia-extract/src/lib.rs
index 0e7358bc..02c4e1e6 100644
--- a/crates/utopia-extract/src/lib.rs
+++ b/crates/utopia-extract/src/lib.rs
@@ -83,6 +83,9 @@ pub struct PromptRelation {
/// **一律用 key**:模型要输出的就是 key,中文库里 person 的 label 是"人物",
/// 写进签名等于教它输出一个不存在的类型(docs/decisions/0004)
pub signature: String,
+ /// 时间语义(`relation_types.temporal`):`state` / `event` / `eternal`(0028)。
+ /// 只有 event 与 eternal 会在清单里带标记——状态是默认,写出来只多花 token
+ pub temporal: String,
}
/// Response-scoped reference to a persistent entity; database UUIDs must never enter prompts.
@@ -140,15 +143,32 @@ pub fn build_messages(
} else {
String::new()
};
+ // 事件与恒常带方括号标记;状态是默认,不标(0028)
+ let mark = temporal_mark(&r.temporal)
+ .map(|m| format!(" [{m}]"))
+ .unwrap_or_default();
match (paren.is_empty(), d.is_empty()) {
- (false, false) => format!("- {} ({paren}): {d}", r.key),
- (false, true) => format!("- {} ({paren})", r.key),
- (true, false) => format!("- {}: {d}", r.key),
- (true, true) => format!("- {}", r.key),
+ (false, false) => format!("- {} ({paren}){mark}: {d}", r.key),
+ (false, true) => format!("- {} ({paren}){mark}", r.key),
+ (true, false) => format!("- {}{mark}: {d}", r.key),
+ (true, true) => format!("- {}{mark}", r.key),
}
})
.collect::<Vec<_>>()
.join("\n");
+ // 标记也只在真有事件或恒常关系时解释一次;全是状态的库,提示词一字不变。
+ // 说的是**写什么**而不是「它是什么」:事件的那一刻进 valid_from、valid_to 留空
+ // ——不然模型照状态的样子填一个起点,账本就把一次收购读成从那天起一直持续
+ let temporal_note = if relations
+ .iter()
+ .any(|r| temporal_mark(&r.temporal).is_some())
+ {
+ "\n 3b. A relation marked [event] happens at one moment: put the date it happened in \
+ valid_from and leave valid_to null — it has no span and does not end. A relation \
+ marked [eternal] holds regardless of time: leave both dates null."
+ } else {
+ ""
+ };
// 记号只在真有签名时解释一次;没有签名的库,提示词一字不变。
// 说明用英文——提示词的**指令语言**是英文,只有 description 跟语料走
//
@@ -253,7 +273,7 @@ pub fn build_messages(
company\", \"no longer available\", \"until recently\". Use null only for something \
still going on. These are not interchangeable: null asserts it still holds, and \
writing null for a relation the text says is over makes us claim the opposite of \
- the source.\n\
+ the source.{temporal_note}\n\
4. {time_ctx}\n\
5. quote must be a contiguous excerpt from the source text; every fact needs one.\n\
6. confidence in 0~1: 0.9 explicitly stated, 0.7 inferred, 0.5 uncertain.\n\
@@ -291,6 +311,16 @@ pub fn build_messages(
]
}
+/// 清单里给关系带的标记:事件 `[event]`、恒常 `[eternal]`;状态不标。
+/// 认不出的值当状态——数据库的 CHECK 只放这三个进来,这里不再报错
+fn temporal_mark(temporal: &str) -> Option<&'static str> {
+ match temporal {
+ "event" => Some("event"),
+ "eternal" => Some("eternal"),
+ _ => None,
+ }
+}
+
/// 已在本文档中出现过的实体,放进提示词的字符预算。
///
/// 超出就截断(保留先出现的)。中文商业文本先出全称、主角先出场,所以
@@ -791,9 +821,46 @@ mod prompt_shape_tests {
label: key.replace('_', " "),
description: description.into(),
signature: signature.into(),
+ temporal: "state".into(),
+ }
+ }
+
+ fn timed(key: &str, description: &str, temporal: &str) -> PromptRelation {
+ PromptRelation {
+ temporal: temporal.into(),
+ ..rel(key, description, "")
}
}
+ /// 事件与恒常在清单里带标记,说明只出现一次(0028)
+ #[test]
+ fn an_event_and_an_eternal_relation_are_marked() {
+ let rels = vec![
+ rel("works_at", "受雇于某个组织。", "person → organization"),
+ timed("acquired", "One company buys another.", "event"),
+ timed("capital_of", "", "eternal"),
+ ];
+ let msgs = build_messages(&[], &rels, &[], None, "a.txt", &[], "text");
+ let s = &msgs[0].content;
+ assert!(s.contains("- works_at (person → organization): 受雇于某个组织。"));
+ assert!(s.contains("- acquired [event]: One company buys another."));
+ // 没有描述时括号里是 label,标记跟在括号后面
+ assert!(s.contains("- capital_of (capital of) [eternal]"));
+ assert!(s.contains("A relation marked [event] happens at one moment"));
+ assert!(s.contains("leave valid_to null"));
+ }
+
+ /// **全是状态的库,提示词一字不变**:不标、不解释
+ #[test]
+ fn a_base_of_states_pays_nothing_for_the_marks() {
+ let rels = vec![rel("works_at", "d", "")];
+ let msgs = build_messages(&[], &rels, &[], None, "a.txt", &[], "text");
+ let s = &msgs[0].content;
+ assert!(!s.contains("[event]"));
+ assert!(!s.contains("[eternal]"));
+ assert!(!s.contains("happens at one moment"));
+ }
+
/// 签名进括号,而且**一律是 key**:中文库的 label 是"人物",
/// 写进提示词等于教模型输出一个不存在的类型。
#[test]
diff --git a/crates/utopia-server/src/extraction.rs b/crates/utopia-server/src/extraction.rs
index 685a24c9..17ad1726 100644
--- a/crates/utopia-server/src/extraction.rs
+++ b/crates/utopia-server/src/extraction.rs
@@ -1901,6 +1901,7 @@ fn build_lists(
label: r.label.clone(),
description: r.description.clone(),
signature,
+ temporal: r.temporal.clone(),
}
})
.collect();
diff --git a/crates/utopia-server/src/rdf.rs b/crates/utopia-server/src/rdf.rs
index 945d8814..16e0d3e8 100644
--- a/crates/utopia-server/src/rdf.rs
+++ b/crates/utopia-server/src/rdf.rs
@@ -378,6 +378,12 @@ pub fn emit_relation(
sink.r(&iri, &nn(rdf::TYPE.as_str()), &owl(term))?;
}
}
+ // 时间语义也照抄(0028):一个 event 谓词的事实两端是同一刻,一个 eternal 谓词的
+ // 事实没有日期——读的人不看这一条,会把前者读成一天的状态、后者读成从不知何时起。
+ // 状态是默认,不写
+ if r.temporal != "state" {
+ sink.l(&iri, &utopia("temporal"), &text(r.temporal.clone()))?;
+ }
for d in &r.domains {
if let Some(c) = vocab.class(*d) {
let c = c.clone();
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index ae7c62ae..39af0d68 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -188,6 +188,62 @@ pub fn truncate_to(
chrono::Utc.from_utc_datetime(&date.and_time(time))
}
+/// 一个桶的尽头:值加一个精度单位。`2024-03-15`(day)→ `2024-03-16`;`2024-03`(month)
+/// → `2024-04`。事件在它命名的那个桶里成立(0028),读出来的终点就是这个;没有精度
+/// (锚点)原样返回——锚点是一刻,不是一个桶
+pub fn bucket_end(
+ t: chrono::DateTime<chrono::Utc>,
+ precision: Option<&str>,
+) -> chrono::DateTime<chrono::Utc> {
+ use chrono::{Duration, Months};
+ match precision {
+ Some("year") => t.checked_add_months(Months::new(12)).unwrap_or(t),
+ Some("month") => t.checked_add_months(Months::new(1)).unwrap_or(t),
+ Some("day") => t + Duration::days(1),
+ Some("hour") => t + Duration::hours(1),
+ Some("minute") => t + Duration::minutes(1),
+ Some("second") => t + Duration::seconds(1),
+ _ => t,
+ }
+}
+
+/// 关系的时间语义(`relation_types.temporal`,0028)。状态有区间;事件是一刻——两端写
+/// 同一个值,在它命名的那个桶里成立;恒常没有日期,每一刻都成立。
+///
+/// 从图谱层第一份迁移起这一列就在,界面也一直给选;但直到 0028 之前只有 state 驱动
+/// 引擎,event 与 eternal 写进去、读出来都还是区间
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Temporal {
+ #[default]
+ State,
+ Event,
+ Eternal,
+}
+
+impl Temporal {
+ /// 认不出的值当状态:数据库的 CHECK 只放这三个进来,这里不再报错
+ pub fn parse(s: &str) -> Self {
+ match s {
+ "event" => Self::Event,
+ "eternal" => Self::Eternal,
+ _ => Self::State,
+ }
+ }
+}
+
+/// 谓词的时间语义。没有谓词(0010)按状态——三者里唯一不丢信息的那个,与导入本体时
+/// 的判断一致
+pub async fn predicate_temporal(pool: &PgPool, predicate_id: Option<Uuid>) -> AppResult<Temporal> {
+ let Some(id) = predicate_id else {
+ return Ok(Temporal::State);
+ };
+ let t: Option<String> = sqlx::query_scalar("SELECT temporal FROM relation_types WHERE id = $1")
+ .bind(id)
+ .fetch_optional(pool)
+ .await?;
+ Ok(t.as_deref().map(Temporal::parse).unwrap_or_default())
+}
+
impl<'a> Validity<'a> {
/// 起始端已知、结束端未知或不适用。
pub fn starting(
@@ -216,6 +272,42 @@ impl<'a> Validity<'a> {
self
}
+ /// 按谓词的时间语义归一(0028)。写入路径进库前都走一遍,与读出侧 `world_axis`
+ /// 说同一句话。
+ ///
+ /// - 事件:那一刻写在**两端**。原文给了起点用起点;只给了终点,那就是它发生的
+ /// 时候;给了一段,取起点——收购不会持续到明年。没日期就两端都空;「结束了
+ /// 不知哪天」对一刻没有意义,一并抹掉。两端同值是这一行自己就能说清的形状:
+ /// 不看谓词的读者顶多把它读成一天的状态,读不成「从那天起一直如此」
+ /// - 恒常:日期全抹。原文里的日期说的是别的事,不是这条关系何时成立
+ /// - 状态:原样
+ pub fn under(mut self, temporal: Temporal) -> Self {
+ match temporal {
+ Temporal::State => {}
+ Temporal::Eternal => {
+ self.from = None;
+ self.from_precision = None;
+ self.to = None;
+ self.to_precision = None;
+ }
+ Temporal::Event => {
+ let moment = self
+ .from
+ .map(|t| (t, self.from_precision))
+ .or_else(|| self.to.map(|t| (t, self.to_precision)));
+ let (t, p) = match moment {
+ Some((t, p)) => (Some(t), p),
+ None => (None, None),
+ };
+ self.from = t;
+ self.from_precision = p;
+ self.to = t;
+ self.to_precision = p;
+ }
+ }
+ self
+ }
+
/// 原文说它结束了,但没说哪天。
pub fn ended_when_unknown(mut self) -> Self {
self.to = None;
@@ -244,7 +336,10 @@ async fn insert_fact_inner(
validity: Validity<'_>,
confidence: f32,
) -> AppResult<(Uuid, bool)> {
- let validity = validity.truncated();
+ // 按谓词的时间语义归一(0028):事件两端同一刻,恒常无日期。写在这里而不是各个
+ // 写入者那儿——抽取、点头、人自己写的事实都经过这一个门
+ let temporal = predicate_temporal(pool, predicate_id).await?;
+ let validity = validity.under(temporal).truncated();
let same_sql = match object {
FactObject::Entity(_) => {
"SELECT id, valid_from, valid_to, valid_to_precision FROM facts
@@ -303,11 +398,13 @@ async fn insert_fact_inner(
attest_earlier(pool, *existing, validity.attested_at).await?;
return Ok((*existing, false));
}
- // 弱化陈述:新观察无时间,同断言已有开放行 → 并入(取起点最新的开放行)
+ // 弱化陈述:新观察无时间,同断言已有开放行 → 并入(取起点最新的开放行)。
+ // 事件没有「开放」一说——它的两端总是同一刻——所以没日期的再观察并进已有的
+ // 那一刻(0028):说过一次「三月收购了」,再听到一句没日期的「收购了」,不是第二次收购
if validity.from.is_none() && !validity.has_ended() {
if let Some((existing, _, _, _)) = same
.iter()
- .filter(|(_, _, vt, _)| vt.is_none())
+ .filter(|(_, _, vt, _)| vt.is_none() || temporal == Temporal::Event)
.max_by_key(|(_, vf, _, _)| *vf)
{
attest_earlier(pool, *existing, validity.attested_at).await?;
@@ -1937,3 +2034,92 @@ pub async fn adopt_value_facts(
)
.await
}
+
+#[cfg(test)]
+mod temporal_shape_tests {
+ use super::*;
+
+ fn at(s: &str) -> chrono::DateTime<chrono::Utc> {
+ s.parse().unwrap()
+ }
+
+ /// 桶的尽头是加一个精度单位;没有精度(锚点)原样
+ #[test]
+ fn a_bucket_ends_one_unit_later() {
+ let d = at("2024-03-15T00:00:00Z");
+ assert_eq!(bucket_end(d, Some("day")), at("2024-03-16T00:00:00Z"));
+ assert_eq!(
+ bucket_end(at("2024-03-01T00:00:00Z"), Some("month")),
+ at("2024-04-01T00:00:00Z")
+ );
+ assert_eq!(
+ bucket_end(at("2024-12-01T00:00:00Z"), Some("month")),
+ at("2025-01-01T00:00:00Z"),
+ "跨年"
+ );
+ assert_eq!(
+ bucket_end(at("2024-01-01T00:00:00Z"), Some("year")),
+ at("2025-01-01T00:00:00Z")
+ );
+ assert_eq!(
+ bucket_end(at("2024-03-15T14:32:00Z"), Some("minute")),
+ at("2024-03-15T14:33:00Z")
+ );
+ assert_eq!(bucket_end(d, None), d);
+ }
+
+ /// 事件:起点优先,只有终点取终点,一段取起点,「结束了不知哪天」抹掉
+ #[test]
+ fn an_event_collapses_to_one_moment() {
+ let span = Validity {
+ from: Some(at("2024-03-15T00:00:00Z")),
+ from_precision: Some("day"),
+ to: Some(at("2025-01-01T00:00:00Z")),
+ to_precision: Some("day"),
+ attested_at: None,
+ }
+ .under(Temporal::Event);
+ assert_eq!(span.from, Some(at("2024-03-15T00:00:00Z")));
+ assert_eq!(span.to, Some(at("2024-03-15T00:00:00Z")));
+ assert_eq!(
+ (span.from_precision, span.to_precision),
+ (Some("day"), Some("day"))
+ );
+
+ let end_only = Validity {
+ from: None,
+ from_precision: None,
+ to: Some(at("2024-05-01T00:00:00Z")),
+ to_precision: Some("month"),
+ attested_at: None,
+ }
+ .under(Temporal::Event);
+ assert_eq!(end_only.from, Some(at("2024-05-01T00:00:00Z")));
+ assert_eq!(end_only.from_precision, Some("month"));
+
+ let unknown = Validity::default()
+ .ended_when_unknown()
+ .under(Temporal::Event);
+ assert_eq!(
+ (unknown.from, unknown.to, unknown.to_precision),
+ (None, None, None)
+ );
+ assert!(!unknown.has_ended(), "一刻没有「结束」可言");
+ }
+
+ /// 恒常抹掉日期;状态原样
+ #[test]
+ fn an_eternal_fact_keeps_no_dates_and_a_state_keeps_its_own() {
+ let dated = Validity::starting(Some(at("1990-01-01T00:00:00Z")), Some("year"))
+ .attested(Some(at("2024-04-01T00:00:00Z")));
+ let eternal = dated.under(Temporal::Eternal);
+ assert_eq!((eternal.from, eternal.from_precision), (None, None));
+ assert_eq!(
+ eternal.attested_at,
+ Some(at("2024-04-01T00:00:00Z")),
+ "证据日期照记——读出侧不用它,账本仍知道"
+ );
+ let state = dated.under(Temporal::State);
+ assert_eq!(state.from, Some(at("1990-01-01T00:00:00Z")));
+ }
+}
diff --git a/crates/utopia-store/src/reasoning.rs b/crates/utopia-store/src/reasoning.rs
index 286b5e1d..ecd76a9a 100644
--- a/crates/utopia-store/src/reasoning.rs
+++ b/crates/utopia-store/src/reasoning.rs
@@ -850,12 +850,38 @@ type TimedEdges = (
/// 锚点为止。两端都不知道的行读成空区间,求交时自然掉出去——它支撑不了任何派生。
/// 返回 `(from, to, from_anchored, to_anchored)`。
fn read_span(
+ temporal: crate::graph::Temporal,
from: Option<chrono::DateTime<chrono::Utc>>,
+ from_precision: Option<&str>,
to: Option<chrono::DateTime<chrono::Utc>>,
to_precision: Option<&str>,
attested_from: chrono::DateTime<chrono::Utc>,
attested_to: Option<chrono::DateTime<chrono::Utc>>,
) -> (Option<i64>, Option<i64>, bool, bool) {
+ use crate::graph::Temporal;
+ match temporal {
+ // 恒常每一刻都成立,证据日期不闸它(0028)
+ Temporal::Eternal => return (None, None, false, false),
+ // 事件在它命名的那个桶里成立;没日期的事件区间为空——`overlap` 对空交集不推,
+ // 所以一条经过「不知何时收购」的链推不出东西,与读出侧一致(0028)。
+ // 0028 之前写下的事件行终点是空的,按起点那个桶读
+ Temporal::Event => {
+ return match from {
+ None => {
+ let a = attested_from.timestamp();
+ (Some(a), Some(a), true, true)
+ }
+ Some(f) => {
+ let precision = to_precision
+ .filter(|p| *p != crate::graph::ENDED_UNKNOWN)
+ .or(from_precision);
+ let end = crate::graph::bucket_end(to.unwrap_or(f), precision);
+ (Some(f.timestamp()), Some(end.timestamp()), false, false)
+ }
+ };
+ }
+ Temporal::State => {}
+ }
let (f, from_anchored) = match from {
Some(x) => (Some(x.timestamp()), false),
None => (Some(attested_from.timestamp()), true),
@@ -886,6 +912,16 @@ async fn timed_edges(pool: &PgPool, kb_id: Uuid) -> AppResult<TimedEdges> {
.bind(kb_id)
.fetch_all(pool)
.await?;
+ // 谓词的时间语义(0028):事件按它的桶读,恒常两端开放。一次取全,按谓词查
+ let temporal_of: HashMap<Uuid, crate::graph::Temporal> = sqlx::query_as::<_, (Uuid, String)>(
+ "SELECT id, temporal FROM relation_types WHERE kb_id = $1",
+ )
+ .bind(kb_id)
+ .fetch_all(pool)
+ .await?
+ .into_iter()
+ .map(|(id, t)| (id, crate::graph::Temporal::parse(&t)))
+ .collect();
let mut edges = Vec::with_capacity(rows.len());
let mut meta: HashMap<Uuid, PremiseMeta> = HashMap::new();
@@ -894,7 +930,16 @@ async fn timed_edges(pool: &PgPool, kb_id: Uuid) -> AppResult<TimedEdges> {
// 按读出来的区间推(0022):没起点的前提从最早的证据起,结束了不知哪天的
// 到说出它的那份文档为止。读成开放的话,一条经过 "former CEO" 的链会推出
// 一条今天还成立的边
- let (f, t, fa, ta) = read_span(from, to, tp.as_deref(), attested_from, attested_to);
+ let temporal = temporal_of.get(&pred).copied().unwrap_or_default();
+ let (f, t, fa, ta) = read_span(
+ temporal,
+ from,
+ fp.as_deref(),
+ to,
+ tp.as_deref(),
+ attested_from,
+ attested_to,
+ );
edges.push(TimedEdge {
edge: Edge {
fact: id,
@@ -1326,8 +1371,17 @@ async fn attribute_facts(
attested_to,
) in rows
{
- // 与公理那一路同一种读法(0022):读数没日期就从它的文档起算
- let (f, t, fa, ta) = read_span(from, to, tp.as_deref(), attested_from, attested_to);
+ // 与公理那一路同一种读法(0022):读数没日期就从它的文档起算。
+ // 属性一律是状态(建属性时固定 state,界面也不给改)
+ let (f, t, fa, ta) = read_span(
+ crate::graph::Temporal::State,
+ from,
+ fp.as_deref(),
+ to,
+ tp.as_deref(),
+ attested_from,
+ attested_to,
+ );
// 属性事实的字面值是 `{"value": …, "unit": …}`;比较的是里面那个 value。
// 取不到就把整个对象交给求值器——它对认不出的形状一律判不满足
let inner = value.get("value").cloned().unwrap_or_else(|| value.clone());
diff --git a/crates/utopia-store/src/temporal.rs b/crates/utopia-store/src/temporal.rs
index 13bb7fed..2b20de00 100644
--- a/crates/utopia-store/src/temporal.rs
+++ b/crates/utopia-store/src/temporal.rs
@@ -438,7 +438,14 @@ pub async fn correct_interval(
fact_id: Uuid,
validity: crate::graph::Validity<'_>,
) -> AppResult<Option<Uuid>> {
- let validity = validity.truncated();
+ // 人改区间也按谓词的时间语义归一(0028):给一个事件填了一段,落下的仍是它的那一刻
+ let predicate: Option<Option<Uuid>> =
+ sqlx::query_scalar("SELECT predicate_id FROM facts WHERE id = $1")
+ .bind(fact_id)
+ .fetch_optional(pool)
+ .await?;
+ let temporal = crate::graph::predicate_temporal(pool, predicate.flatten()).await?;
+ let validity = validity.under(temporal).truncated();
let mut tx = pool.begin().await?;
let corrected = Uuid::now_v7();
let inserted: Option<(Uuid,)> = sqlx::query_as(
diff --git a/crates/utopia-store/src/world_axis.rs b/crates/utopia-store/src/world_axis.rs
index d2237416..45c0b305 100644
--- a/crates/utopia-store/src/world_axis.rs
+++ b/crates/utopia-store/src/world_axis.rs
@@ -21,28 +21,47 @@
//! 的「NULL 即现在」不同:没有人持有一个晚于此刻的信念,而没有时刻的图是全部
//! 时间的图。
+/// 谓词的时间语义(0028)。一行自己说不出它是状态、事件还是恒常——它的谓词说;
+/// 没有谓词(0010)读作状态,与写入侧 `predicate_temporal` 同一判断
+fn temporal_of(alias: &str) -> String {
+ format!("(SELECT r.temporal FROM relation_types r WHERE r.id = {alias}.predicate_id)")
+}
+
/// `facts`:读出来的下界——原文给了起点用起点,否则从最早的证据起。
+/// 恒常没有下界(NULL 即开放):证据日期闸的是「从何时起知道」,恒常的东西不从何时起
pub fn facts_holds_from(alias: &str) -> String {
- format!("COALESCE({alias}.valid_from, {alias}.attested_from)")
+ format!(
+ "CASE WHEN {temporal} = 'eternal' THEN NULL \
+ ELSE COALESCE({alias}.valid_from, {alias}.attested_from) END",
+ temporal = temporal_of(alias),
+ )
}
/// `facts`:读出来的上界——原文给了终点用终点;说结束了但不知哪天,到最早说出它
/// 的那份文档为止;否则开放(NULL)。
+///
+/// 事件(0028)在它命名的那个桶里成立:上界是那一刻加一个精度单位——`2024-03-15`
+/// 到 `2024-03-16` 为止,`2024-03` 到四月为止。没日期的事件上界与下界同为锚点,
+/// 区间为空:它发生过,但不知何时,任何时刻都不算成立(0022 对未知的收法)。
+/// 0028 之前写下的事件行终点是空的,按起点那个桶读——不必回填。恒常没有上界
pub fn facts_holds_to(alias: &str) -> String {
format!(
- "CASE WHEN {alias}.valid_to IS NOT NULL THEN {alias}.valid_to \
- WHEN {alias}.valid_to_precision = 'unknown' THEN {alias}.attested_to END"
+ "CASE WHEN {temporal} = 'eternal' THEN NULL \
+ WHEN {temporal} = 'event' THEN \
+ CASE WHEN {alias}.valid_from IS NULL THEN {alias}.attested_from \
+ ELSE COALESCE({alias}.valid_to, {alias}.valid_from) \
+ + ('1 ' || COALESCE(NULLIF({alias}.valid_to_precision, 'unknown'), \
+ {alias}.valid_from_precision))::interval END \
+ WHEN {alias}.valid_to IS NOT NULL THEN {alias}.valid_to \
+ WHEN {alias}.valid_to_precision = 'unknown' THEN {alias}.attested_to END",
+ temporal = temporal_of(alias),
)
}
/// `facts`:断言在 T 时刻成立。`$param` 为 NULL 即不过滤。
+/// 两端都可能开放(恒常),所以是纯粹的区间包含
pub fn facts_hold_at(alias: &str, param: usize) -> String {
- format!(
- "(${param}::timestamptz IS NULL \
- OR ({from} <= ${param} AND ({to} IS NULL OR {to} > ${param})))",
- from = facts_holds_from(alias),
- to = facts_holds_to(alias),
- )
+ interval_holds_at(&facts_holds_from(alias), &facts_holds_to(alias), param)
}
/// 纯粹的区间包含,NULL 一端即开放。派生行与幽灵边(0017 §3,区间在 `detail` 里)
diff --git a/crates/utopia-store/tests/an_event_holds_at_the_moment_it_names.rs b/crates/utopia-store/tests/an_event_holds_at_the_moment_it_names.rs
new file mode 100644
index 00000000..cbb83581
--- /dev/null
+++ b/crates/utopia-store/tests/an_event_holds_at_the_moment_it_names.rs
@@ -0,0 +1,697 @@
+//! 事件在它命名的那一刻成立,恒常每一刻都成立(0028 / #486),打在真库上。
+//!
+//! 为什么非要连库:写入侧的归一(`Validity::under`)和读出侧的谓词(`world_axis`)
+//! 各在一处,两处必须说同一句话;而读出侧整个活在 SQL 字符串里——一个写反的 CASE、
+//! 一个拼错的 interval 字面量,`cargo check` 都看不见。
+//!
+//! 钉住的事:
+//! - 事件写进库是两端同一个值;在它命名的那个桶里成立(那一天、那个月),桶外不成立
+//! - 给事件一段、只给终点、说它「结束了不知哪天」——落下的仍是一刻或没有日期
+//! - 没日期的事件任何时刻都不成立,但实体上仍列着它;之后来了日期就精化,再来一句
+//! 没日期的并进去
+//! - 恒常抹掉原文里的日期,证据日期也不闸它——1800 年和 2100 年都成立
+//! - 0028 之前写下的事件行(终点空)按起点那个桶读,不必回填
+//! - 人改一个事件的区间,落下的仍是一刻
+//! - 派生经过事件取它的桶(两端带精度),经过恒常两端开放
+//!
+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
+
+use std::collections::HashSet;
+
+use sqlx::PgPool;
+use utopia_store::graph::Validity;
+use uuid::Uuid;
+
+fn t(s: &str) -> chrono::DateTime<chrono::Utc> {
+ s.parse().unwrap()
+}
+
+/// 一行事实的两端与精度
+type Span = (
+ Option<chrono::DateTime<chrono::Utc>>,
+ Option<String>,
+ Option<chrono::DateTime<chrono::Utc>>,
+ Option<String>,
+);
+
+struct Fixture {
+ org: Uuid,
+ kb: Uuid,
+ nova: Uuid,
+ orion: Uuid,
+ vega: Uuid,
+ paris: Uuid,
+ france: Uuid,
+ /// 状态:领导某组织
+ leads: Uuid,
+ /// 事件:收购
+ acquired: Uuid,
+ /// 事件,对称:合并
+ merged_with: Uuid,
+ /// 恒常:首都
+ capital_of: Uuid,
+ /// 恒常,对称:接壤
+ borders: Uuid,
+}
+
+async fn seed(pool: &PgPool) -> anyhow::Result<Fixture> {
+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let (organization, city, country) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let (nova, orion, vega) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let (paris, france) = (Uuid::now_v7(), Uuid::now_v7());
+ let (leads, acquired, merged_with) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let (capital_of, borders) = (Uuid::now_v7(), Uuid::now_v7());
+
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'event-test')")
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'event-test')")
+ .bind(ws)
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'event-test')",
+ )
+ .bind(kb)
+ .bind(ws)
+ .execute(pool)
+ .await?;
+ for (id, key, label) in [
+ (organization, "organization", "Organization"),
+ (city, "city", "City"),
+ (country, "country", "Country"),
+ ] {
+ sqlx::query("INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, $3, $4)")
+ .bind(id)
+ .bind(kb)
+ .bind(key)
+ .bind(label)
+ .execute(pool)
+ .await?;
+ }
+ for (id, key, temporal, symmetric) in [
+ (leads, "leads", "state", false),
+ (acquired, "acquired", "event", false),
+ (merged_with, "merged_with", "event", true),
+ (capital_of, "capital_of", "eternal", false),
+ (borders, "borders", "eternal", true),
+ ] {
+ sqlx::query(
+ "INSERT INTO relation_types (id, kb_id, key, label, temporal, is_symmetric)
+ VALUES ($1, $2, $3, $3, $4, $5)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(key)
+ .bind(temporal)
+ .bind(symmetric)
+ .execute(pool)
+ .await?;
+ }
+ for (id, ty, name) in [
+ (nova, organization, "Nova Systems"),
+ (orion, organization, "Orion Labs"),
+ (vega, organization, "Vega Analytics"),
+ (paris, city, "Paris"),
+ (france, country, "France"),
+ ] {
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, type_id, canonical_name) VALUES ($1, $2, $3, $4)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(ty)
+ .bind(name)
+ .execute(pool)
+ .await?;
+ }
+ Ok(Fixture {
+ org,
+ kb,
+ nova,
+ orion,
+ vega,
+ paris,
+ france,
+ leads,
+ acquired,
+ merged_with,
+ capital_of,
+ borders,
+ })
+}
+
+async fn teardown(pool: &PgPool, f: &Fixture) -> anyhow::Result<()> {
+ 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?;
+ Ok(())
+}
+
+async fn fact(
+ pool: &PgPool,
+ f: &Fixture,
+ subject: Uuid,
+ predicate: Uuid,
+ object: Uuid,
+ validity: Validity<'_>,
+) -> anyhow::Result<(Uuid, bool)> {
+ Ok(utopia_store::graph::insert_fact(
+ pool,
+ f.kb,
+ subject,
+ Some(predicate),
+ object,
+ validity,
+ 0.9,
+ )
+ .await?)
+}
+
+async fn span(pool: &PgPool, id: Uuid) -> anyhow::Result<Span> {
+ Ok(sqlx::query_as(
+ "SELECT valid_from, valid_from_precision, valid_to, valid_to_precision FROM facts WHERE id = $1",
+ )
+ .bind(id)
+ .fetch_one(pool)
+ .await?)
+}
+
+/// T 时刻某实体面板上的事实(按 id)。`None` = 每一刻
+async fn facts_at(
+ pool: &PgPool,
+ f: &Fixture,
+ entity: Uuid,
+ at: Option<&str>,
+) -> anyhow::Result<HashSet<Uuid>> {
+ let (_, facts) =
+ utopia_store::graph::entity_detail(pool, f.kb, entity, at.map(t), None).await?;
+ Ok(facts.into_iter().map(|x| x.id).collect())
+}
+
+async fn holds(
+ pool: &PgPool,
+ f: &Fixture,
+ entity: Uuid,
+ id: Uuid,
+ at: &str,
+) -> anyhow::Result<bool> {
+ Ok(facts_at(pool, f, entity, Some(at)).await?.contains(&id))
+}
+
+#[tokio::test]
+async fn an_event_is_one_moment_and_holds_through_the_bucket_it_names() -> 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 {
+ // 2024-04-01 的文档说:Nova 于 2024-03-15 收购 Orion
+ let (day, _) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.orion,
+ Validity::starting(Some(t("2024-03-15T00:00:00Z")), Some("day"))
+ .attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+ assert_eq!(
+ span(&pool, day).await?,
+ (
+ Some(t("2024-03-15T00:00:00Z")),
+ Some("day".into()),
+ Some(t("2024-03-15T00:00:00Z")),
+ Some("day".into()),
+ ),
+ "事件写进库是两端同一个值、同一个精度"
+ );
+ // 那一天里的每一刻成立;前一天、后一天都不;证据日期(4 月)更不
+ assert!(!holds(&pool, &f, f.nova, day, "2024-03-14T23:59:59Z").await?);
+ assert!(holds(&pool, &f, f.nova, day, "2024-03-15T00:00:00Z").await?);
+ assert!(holds(&pool, &f, f.nova, day, "2024-03-15T23:59:59Z").await?);
+ assert!(!holds(&pool, &f, f.nova, day, "2024-03-16T00:00:00Z").await?);
+ assert!(
+ !holds(&pool, &f, f.nova, day, "2024-04-01T00:00:00Z").await?,
+ "证据日期不是事件的日期,状态那套「从证据起」不适用"
+ );
+ assert!(
+ facts_at(&pool, &f, f.nova, None).await?.contains(&day),
+ "不限时刻时列出"
+ );
+
+ // 读出来的区间跟着桶走:从那一天起,到下一天为止
+ let (_, all) = utopia_store::graph::entity_detail(&pool, f.kb, f.nova, None, None).await?;
+ let read = all.iter().find(|x| x.id == day).expect("在面板上");
+ assert_eq!(read.holds_from, Some(t("2024-03-15T00:00:00Z")));
+ assert_eq!(read.holds_to, Some(t("2024-03-16T00:00:00Z")));
+ assert_eq!(read.temporal.as_deref(), Some("event"));
+
+ // 月精度的桶是整个月
+ let (month, _) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.vega,
+ Validity::starting(Some(t("2024-06-01T00:00:00Z")), Some("month")),
+ )
+ .await?;
+ assert!(holds(&pool, &f, f.nova, month, "2024-06-30T12:00:00Z").await?);
+ assert!(!holds(&pool, &f, f.nova, month, "2024-07-01T00:00:00Z").await?);
+
+ // 状态照旧:领导从 3 月起、开放——4 月也成立
+ let (lead, _) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.leads,
+ f.orion,
+ Validity::starting(Some(t("2024-03-15T00:00:00Z")), Some("day")),
+ )
+ .await?;
+ assert!(holds(&pool, &f, f.nova, lead, "2024-04-01T00:00:00Z").await?);
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
+
+#[tokio::test]
+async fn a_span_an_ending_or_an_unknown_end_given_to_an_event_collapses() -> 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 {
+ // 模型给了一段:取起点
+ let (ranged, _) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.orion,
+ Validity {
+ from: Some(t("2024-03-15T00:00:00Z")),
+ from_precision: Some("day"),
+ to: Some(t("2025-01-01T00:00:00Z")),
+ to_precision: Some("day"),
+ attested_at: None,
+ },
+ )
+ .await?;
+ let s = span(&pool, ranged).await?;
+ assert_eq!(
+ (s.0, s.2),
+ (
+ Some(t("2024-03-15T00:00:00Z")),
+ Some(t("2024-03-15T00:00:00Z"))
+ )
+ );
+
+ // 只给了终点:那就是它发生的时候
+ let (ended, _) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.vega,
+ Validity {
+ from: None,
+ from_precision: None,
+ to: Some(t("2024-05-01T00:00:00Z")),
+ to_precision: Some("month"),
+ attested_at: None,
+ },
+ )
+ .await?;
+ assert_eq!(
+ span(&pool, ended).await?,
+ (
+ Some(t("2024-05-01T00:00:00Z")),
+ Some("month".into()),
+ Some(t("2024-05-01T00:00:00Z")),
+ Some("month".into()),
+ )
+ );
+
+ // 「结束了不知哪天」对一刻没有意义:落下的是没日期的事件,不是待关的行
+ let (unknown, _) = fact(
+ &pool,
+ &f,
+ f.orion,
+ f.acquired,
+ f.vega,
+ Validity::default()
+ .ended_when_unknown()
+ .attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+ assert_eq!(span(&pool, unknown).await?, (None, None, None, None));
+ let attested_to: Option<chrono::DateTime<chrono::Utc>> =
+ sqlx::query_scalar("SELECT attested_to FROM facts WHERE id = $1")
+ .bind(unknown)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(attested_to, None, "没有「结束」这回事,也就没有结束的锚点");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
+
+#[tokio::test]
+async fn an_undated_event_holds_at_no_moment_and_takes_a_date_when_one_arrives(
+) -> 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 {
+ // 2024-04-01 的文档说 Nova 收购了 Orion,没说哪天
+ let (bare, created) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.orion,
+ Validity::default().attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+ assert!(created);
+ assert!(
+ facts_at(&pool, &f, f.nova, None).await?.contains(&bare),
+ "实体上列着"
+ );
+ for at in [
+ "2024-04-01T00:00:00Z",
+ "2024-04-02T00:00:00Z",
+ "2030-01-01T00:00:00Z",
+ ] {
+ assert!(
+ !holds(&pool, &f, f.nova, bare, at).await?,
+ "不知何时发生的事件,{at} 不算成立(状态会从证据起算,事件不)"
+ );
+ }
+
+ // 后来的文档给了日期:精化——裸行作废,新行两端是那一刻
+ let (dated, created) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.orion,
+ Validity::starting(Some(t("2024-03-15T00:00:00Z")), Some("day"))
+ .attested(Some(t("2024-05-01T00:00:00Z"))),
+ )
+ .await?;
+ assert!(created);
+ assert_ne!(dated, bare);
+ let (supersedes, old_dead): (Option<Uuid>, bool) = sqlx::query_as(
+ "SELECT supersedes, (SELECT invalidated_at IS NOT NULL FROM facts WHERE id = $2)
+ FROM facts WHERE id = $1",
+ )
+ .bind(dated)
+ .bind(bare)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(supersedes, Some(bare));
+ assert!(old_dead);
+ assert!(holds(&pool, &f, f.nova, dated, "2024-03-15T12:00:00Z").await?);
+
+ // 再听到一句没日期的「收购了」:并进已有的那一刻,不是第二次收购
+ let (again, created) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.orion,
+ Validity::default().attested(Some(t("2024-06-01T00:00:00Z"))),
+ )
+ .await?;
+ assert!(!created);
+ assert_eq!(again, dated);
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
+
+#[tokio::test]
+async fn an_eternal_relation_drops_its_dates_and_holds_at_every_moment() -> 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 {
+ // 原文:「1990 年起巴黎是法国首都」——日期说的是别的事;文档是 2024 年的
+ let (cap, _) = fact(
+ &pool,
+ &f,
+ f.paris,
+ f.capital_of,
+ f.france,
+ Validity::starting(Some(t("1990-01-01T00:00:00Z")), Some("year"))
+ .attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+ assert_eq!(
+ span(&pool, cap).await?,
+ (None, None, None, None),
+ "恒常不存日期"
+ );
+ for at in [
+ "1800-01-01T00:00:00Z",
+ "2023-12-31T00:00:00Z",
+ "2100-01-01T00:00:00Z",
+ ] {
+ assert!(
+ holds(&pool, &f, f.paris, cap, at).await?,
+ "{at} 成立——证据日期不闸恒常"
+ );
+ }
+ let (_, all) = utopia_store::graph::entity_detail(&pool, f.kb, f.paris, None, None).await?;
+ let read = all.iter().find(|x| x.id == cap).expect("在面板上");
+ assert_eq!((read.holds_from, read.holds_to), (None, None), "两端开放");
+
+ // 再说一遍并进同一行
+ let (again, created) = fact(
+ &pool,
+ &f,
+ f.paris,
+ f.capital_of,
+ f.france,
+ Validity::starting(Some(t("2000-01-01T00:00:00Z")), Some("year")),
+ )
+ .await?;
+ assert!(!created);
+ assert_eq!(again, cap);
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
+
+#[tokio::test]
+async fn a_row_written_before_the_rule_reads_as_its_start_bucket() -> 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 {
+ // 0028 之前的形状:事件谓词、起点有、终点空——当年被读成「从那天起一直如此」
+ let legacy = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id,
+ valid_from, valid_from_precision, confidence, attested_from)
+ VALUES ($1, $2, $3, $4, $5, '2024-03-15T00:00:00Z', 'day', 0.9, '2024-04-01T00:00:00Z')",
+ )
+ .bind(legacy)
+ .bind(f.kb)
+ .bind(f.nova)
+ .bind(f.acquired)
+ .bind(f.orion)
+ .execute(&pool)
+ .await?;
+ assert!(holds(&pool, &f, f.nova, legacy, "2024-03-15T12:00:00Z").await?);
+ assert!(!holds(&pool, &f, f.nova, legacy, "2024-03-16T00:00:00Z").await?);
+ assert!(!holds(&pool, &f, f.nova, legacy, "2025-01-01T00:00:00Z").await?, "不再是开放的");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
+
+#[tokio::test]
+async fn a_person_correcting_an_event_leaves_it_one_moment() -> 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 {
+ let (original, _) = fact(
+ &pool,
+ &f,
+ f.nova,
+ f.acquired,
+ f.orion,
+ Validity::starting(Some(t("2024-03-15T00:00:00Z")), Some("day")),
+ )
+ .await?;
+ // 人在面板上填了一段 3-20 ~ 6-01:落下的是 3-20 这一刻
+ let corrected = utopia_store::temporal::correct_interval(
+ &pool,
+ original,
+ Validity {
+ from: Some(t("2024-03-20T00:00:00Z")),
+ from_precision: Some("day"),
+ to: Some(t("2024-06-01T00:00:00Z")),
+ to_precision: Some("day"),
+ attested_at: None,
+ },
+ )
+ .await?
+ .expect("改得动");
+ assert_eq!(
+ span(&pool, corrected).await?,
+ (
+ Some(t("2024-03-20T00:00:00Z")),
+ Some("day".into()),
+ Some(t("2024-03-20T00:00:00Z")),
+ Some("day".into()),
+ )
+ );
+ assert!(holds(&pool, &f, f.nova, corrected, "2024-03-20T08:00:00Z").await?);
+ assert!(!holds(&pool, &f, f.nova, corrected, "2024-04-15T00:00:00Z").await?);
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
+
+#[tokio::test]
+async fn a_derivation_reads_an_event_as_its_bucket_and_an_eternal_as_open() -> 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 {
+ // merged_with 对称、事件:Nova 与 Orion 于 2024-03 合并
+ fact(
+ &pool,
+ &f,
+ f.nova,
+ f.merged_with,
+ f.orion,
+ Validity::starting(Some(t("2024-03-01T00:00:00Z")), Some("month"))
+ .attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+ // borders 对称、恒常:法国与……巴黎接壤(测试用的荒唐事实,文档是 2024 年的)
+ fact(
+ &pool,
+ &f,
+ f.france,
+ f.borders,
+ f.paris,
+ Validity::starting(Some(t("2020-01-01T00:00:00Z")), Some("year"))
+ .attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+ // 没日期的事件:Orion 与 Vega 合并,不知何时——推不出反向那条
+ fact(
+ &pool,
+ &f,
+ f.orion,
+ f.merged_with,
+ f.vega,
+ Validity::default().attested(Some(t("2024-04-01T00:00:00Z"))),
+ )
+ .await?;
+
+ utopia_store::reasoning::materialize(&pool, f.kb).await?;
+
+ let derived = |s: Uuid, p: Uuid, o: Uuid| {
+ let pool = pool.clone();
+ async move {
+ let row: Option<Span> = sqlx::query_as(
+ "SELECT valid_from, valid_from_precision, valid_to, valid_to_precision
+ FROM derived_facts
+ WHERE kb_id = $1 AND subject_id = $2 AND predicate_id = $3 AND object_id = $4
+ AND invalidated_at IS NULL",
+ )
+ .bind(f.kb)
+ .bind(s)
+ .bind(p)
+ .bind(o)
+ .fetch_optional(&pool)
+ .await?;
+ Ok::<_, anyhow::Error>(row)
+ }
+ };
+
+ // 反向的合并:那一个月,两端带月精度
+ let back = derived(f.orion, f.merged_with, f.nova)
+ .await?
+ .expect("对称推得出");
+ assert_eq!(
+ back,
+ (
+ Some(t("2024-03-01T00:00:00Z")),
+ Some("month".into()),
+ Some(t("2024-04-01T00:00:00Z")),
+ Some("month".into()),
+ ),
+ "派生取事件的桶:从 3 月起,到 4 月为止"
+ );
+ // 反向的接壤:两端开放,证据日期不进来
+ let back = derived(f.paris, f.borders, f.france)
+ .await?
+ .expect("对称推得出");
+ assert_eq!(back, (None, None, None, None));
+ // 不知何时的合并:空区间,不推
+ assert!(
+ derived(f.vega, f.merged_with, f.orion).await?.is_none(),
+ "没日期的事件任何时刻都不成立,链经过它推不出东西"
+ );
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ teardown(&pool, &f).await?;
+ run
+}
diff --git a/docs/decisions/0028-an-event-holds-at-the-moment-it-names.md b/docs/decisions/0028-an-event-holds-at-the-moment-it-names.md
new file mode 100644
index 00000000..e0cdd983
--- /dev/null
+++ b/docs/decisions/0028-an-event-holds-at-the-moment-it-names.md
@@ -0,0 +1,65 @@
+# 0028 · An event holds at the moment it names
+
+- **Status**: implemented (#486) · `Validity::under` normalises every write by the predicate's `temporal` — in `insert_fact_inner`, so extraction, the nod and a person's own fact all pass through it, and in `correct_interval` · `world_axis` reads an event as the bucket it names and an eternal fact as open at both ends, and the evaluator's `read_span` says the same · the prompt marks `[event]` and `[eternal]` relations and tells the model what to write, for a base that has any · the export carries `utopia:temporal` on a property that is not a state · no schema change, and a row written before this reads correctly · the panel still prints an event as `T ~ T` and the ontology page still does not say what the three values do — that is the UI cut
+- **Written**: 2026-09-08 (conventions in the [README](README.md))
+- **Related**: [0003](0003-ontology-growth-loop.md)'s graph migration gave a relation three temporal semantics and gave the engine one. [0022](0022-an-unknown-date-is-not-an-open-one.md) put the world-axis read in one place; this record adds two branches there and nowhere else. [0024](0024-the-world-axis-reaches-the-second.md)'s ladder is what "the bucket it names" is measured on. [0013](0013-a-source-should-hand-over-its-history.md) hands ticket events over at day precision; those were the first rows this rule was wrong for. From #486.
+
+> `relation_types.temporal` has been `state`, `event` or `eternal` since the first graph migration, and the ontology page offers all three — "State (has interval)", "Event (point in time)", "Eternal (timeless)". Only `state` did anything. "Nova acquired Orion on 2024-03-15" landed as *holds from 2024-03-15, still going on*; "Paris is the capital of France" picked up whatever year sat in the sentence and, having no start, held from its first evidence and not before. The ledger promised a moment and a timeless fact, and wrote and read both as intervals.
+
+## What the ledger did
+
+Three consumers read the column, and each read one value of it.
+
+- **The temporal engine** reconciles only `state` (`reconcile_new_fact`, `reconcile_predicate`). Right — a moment is not closed by a later moment — but that was the whole of it.
+- **The world-axis reads** (`world_axis`, the evaluator's `read_span`) treated every row as an interval: a NULL end read as *still holds* (0022 keeps that for states, on purpose), and a NULL start read as *from the first evidence*. An event with a date therefore held forever after it; an eternal fact held from the day of the document that stated it.
+- **The prompt** never mentioned it. The model filled `valid_from` / `valid_to` for an event the way it does for a state, and for an eternal relation copied whatever date the sentence carried.
+- **The panel** hid dates on `eternal` and nothing else.
+
+So choosing `event` was the same as choosing `state` without a uniqueness axiom, and choosing `eternal` was a display hint.
+
+## Decisions
+
+### 1. An event is one moment, written at both ends
+
+`Validity::under(temporal)` runs on every write, keyed on the predicate's declared semantics. For an event: the start if the text gave one, else the end (only an end means *that is when it happened*), and a span collapses to its start — an acquisition does not run until next year. Both ends get that value and that precision. No date means no dates; "ended, date unknown" means nothing for a moment and is dropped, so an event row never carries `'unknown'` and never gets an `attested_to`.
+
+The rule sits in `insert_fact_inner` and `correct_interval`, not in the writers. Extraction, the pending-facts nod (0015), a person's own fact from the API and a person's edit of an interval all pass through those two doors, and nothing outside the store has to know the rule exists.
+
+Both ends carry the value because that is the one shape the row can explain on its own. A reader that does not consult the predicate — an old client, an export consumer, a hand-written query — sees a fact that held on one day. It cannot see *holds from that day on*, which is what an open end would have told it. The representation fails safe.
+
+An undated observation of an event merges into an existing dated one, the mirror of the refinement path that already lets a dated observation supersede a bare row: "acquired in March" followed by "acquired" is one acquisition, not two.
+
+### 2. An event holds through the bucket it names, and an undated event at no moment
+
+A day-precision event on 2024-03-15 holds at every instant of 2024-03-15 and at no other: `[valid_from, valid_to + one unit of its precision)`. The precision already says "the day is known, the instant is not" (0024); reading the row as holding through the day is what that sentence means. A month-precision event holds through the month.
+
+An event with no date holds at no moment. The read interval is `[attested_from, attested_from)`, empty. This is 0022's rule for the unknown, applied to a moment instead of a bound: a state with no start holds from its first evidence because the document asserts it as current; a document that says "Nova acquired Orion" asserts that it happened, not that it is happening. The row stays on the entity's panel under "undated", and a chain of derivations through it derives nothing, because `overlap` refuses an empty intersection.
+
+The read lives in `world_axis::facts_holds_to` beside the two rules 0022 put there, and `read_span` mirrors it for the evaluator. The predicate's semantics come from a correlated subquery on `relation_types` — a row cannot say what it is, but its predicate can — and a fact with no predicate (0010) reads as a state, the one value that loses nothing, the same judgment the ontology import makes when it writes `state` for every OWL property.
+
+### 3. An eternal fact has no dates and every moment
+
+Under `Eternal`, `Validity::under` clears both ends whatever the text said. A date in a sentence about the capital of France is about something else — when the document was written, when the author learned it — not about when the relation held. And the read opens both ends: `facts_holds_from` is NULL for an eternal row, so the evidence anchor no longer gates it. 0022's anchor answers "since when do we have grounds to say this holds"; for a fact that holds at every moment the question has no bearing on the answer.
+
+### 4. The prompt says what to write, and only when it matters
+
+A relation in the list gets ` [event]` or ` [eternal]` after its signature, and one rule (3b) says what those marks mean for `valid_from` and `valid_to`: an event's date goes in `valid_from` and `valid_to` stays null; an eternal relation gets no dates. A base whose relations are all states sees neither the marks nor the rule — the same discipline as the type-signature note, which also costs nothing to a base that declared none. The instruction is about what to *write*, not what the relation *is*: told only that a relation is a point in time, a model still fills a start the way it does for a state, and the write rule then collapses a span it never needed to produce.
+
+### 5. Rows written before this are read, not rewritten
+
+An event row from before this record has a start and an open end. `facts_holds_to` reads it as its start's bucket — the end falls back to the start, the precision to the start's — and `read_span` does the same. No migration touches the ledger: the rows are what they were, and the new reading is right for them. A base that wants the stored shape can re-extract.
+
+## Dead ends
+
+- **Store the bucket end.** `valid_to = valid_from + one unit` with the existing read predicate unchanged. Nothing to add to `world_axis` — and an auditor reading the export (0020) sees `validFrom 2024-03-15; validThrough 2024-03-16`, a one-day state, for a fact the text placed at a moment. The row would say something the source did not.
+- **Leave the end NULL and let the read handle it.** The smallest write. It is also the shape that reads as *still holds* in every consumer that does not check the predicate — the one that was wrong before this record. A representation that is only correct through the predicate is one forgotten join from being wrong again.
+- **A read rule that ignores the predicate**: "a row whose two ends are equal holds through that bucket", for every row. It would give events the right reading without the subquery. It would also change the meaning of a state row that starts and ends in one bucket, and it sits beside a convention this record does not touch: a state ending "2024-07" has always read as ended at the start of July, not the end. Changing that is a different record, about states.
+- **An `attested_from = -infinity` sentinel for eternal rows.** One column, no subquery — and a magic value in a column whose meaning (0022) is "the earliest evidence", which `attest_earlier` and any future "attested" display would have to know to skip.
+- **A migration that rewrites old event rows.** The read is correct for them as they are (§5), and rewriting a row's stated interval to match a rule it predates is the ledger editing history.
+
+## Open questions
+
+- **A point on the panel.** `fmtInterval` prints an event as `2024-03-15 ~ 2024-03-15` and the timeline draws it as a bar of no length. The point rendering, and a line on the ontology page saying what the three values do, are the UI cut.
+- **The wording the tools give the model.** `time_text` phrases an event's interval the way it phrases a state's. Whether "on 2024-03-15" reads better than "from 2024-03-15 to 2024-03-15" for a timed answer is a prompt question, to be looked at with the tool traces.
+- **An attribute taken at a moment.** Attributes are created as `state` and the UI does not offer otherwise (0021's readings are states that a later reading closes). A reading that is a measurement *at* a time rather than a value *from* a time is not expressible today; nothing has asked for it.
+- **The end convention for states.** Noted above. "Until 2024-07" ends at the start of July under the current read; the bucket reading this record gives events would end it at the start of August. Left alone here.
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index d3f87bbc..1fc3b5fa 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -49,6 +49,7 @@ The test for writing one: if someone (including us) looks at a piece of code in
| 0023 | [RSS observations are not documents](0023-rss-observations-are-not-documents.md) | Implemented in #326 |
| 0024 | [The world axis reaches the second](0024-the-world-axis-reaches-the-second.md) | Implemented · the precision ladder runs year → second (not below: no source states less), a stored value is truncated to its precision by CHECK on all three tables, a clock time without a zone is a date, one list spells the ladder in the extractor, the renderers, the export and the evaluator; a derived bound takes the precision of the premise that set it |
| 0025 | [Governance reads the ledger before it decides](0025-governance-reads-the-ledger-before-it-decides.md) | Cut 1 implemented · a per-base `governance` switch, a `govern` job that works the duplicates queue first in, first out with each head's cluster, precedents pulled from the ledger into the prompt, a gate where the agent's own confidence decides and history lowers the bar or blocks (revised after the first big-file run), every look a row in `agent_decisions`, answers through the person's own decide path · the switch, the Agent queue, the proposal chip and the Overview section in the UI · a pair the batch cannot settle is looked at again with tools and then decided or asked about, within a daily budget · two reverts in a week turn the switch off and raise an alert · identity rules the model reads and two it cannot argue with (name shapes, type families), measured against a hand-labeled set of 411 name pairs by `scripts/bench/govern.mjs` |
+| 0028 | [An event holds at the moment it names](0028-an-event-holds-at-the-moment-it-names.md) | Implemented (#486) · `Validity::under` normalises every write by the predicate's `temporal` (an event is one moment written at both ends, an eternal fact has no dates), `world_axis` and `read_span` read an event as the bucket it names and an undated event at no moment, an eternal fact at every moment · the prompt marks `[event]` / `[eternal]` and says what to write · no schema change, old rows read correctly · the panel's point rendering and the ontology hint are the UI cut |
## Not a decision record