World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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