World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
Reads return a statement's role-word qualifiers, so the document's own words such as line ranges and amounts are no longer stored but never shown (#1272)
Szabo Bogdanead538e04ca7
diff --git a/crates/utopia-core/src/models.rs b/crates/utopia-core/src/models.rsindex 81ba60c4..4bc79d37 100644--- a/crates/utopia-core/src/models.rs+++ b/crates/utopia-core/src/models.rs@@ -607,6 +607,19 @@ pub struct FactQualifier {pub entity_name: Option<String>,}+/// 开放陈述上的一个属性(0044 第一刀、0061):按文档的角色词记,不按本体属性——没有+/// `qualifier_type_id`,所以不混进 [`FactQualifier`](RDF 导出靠那一格拼 IRI)。+/// 值或实体二选一;实体那一格带上它的显示名。物化出来的类型化行带着抄过去的那一份+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct StatementQualifier {+ /// 文档自己的角色词("amount"、"buyer")+ pub role: String,+ /// 形状与 [`FactQualifier::value`] 一致:{"value": …}+ pub value: Option<serde_json::Value>,+ pub entity_id: Option<Uuid>,+ pub entity_name: Option<String>,+}+/// 一次 OWL 导入的记录。原文按内容寻址存在 blob 里,这行只是账。/// `summary` 记下那次投影做了什么,包括**暂未投影**的公理——将来补上消费者/// 时据此知道哪些导入值得重跑。@@ -729,6 +742,9 @@ pub struct GraphEdge {/// 边上的属性(0037):画布把金额写到边的标签上要靠它#[sqlx(skip)]pub qualifiers: Vec<FactQualifier>,+ /// 按文档角色词记的属性(0061,#1267):与 `qualifiers` 分开,没有就是空列表+ #[sqlx(skip)]+ pub statement_qualifiers: Vec<StatementQualifier>,/// 推它出来的那条规则(`transitive` / `symmetric` / `inverse` / `sub_property`);/// 断言的边为 None。///@@ -804,6 +820,9 @@ pub struct EntityFact {/// 边上的属性(0037)。不在行里——`fact_qualifiers` 另一张表,加载后按事实 id 补#[sqlx(skip)]pub qualifiers: Vec<FactQualifier>,+ /// 按文档角色词记的属性(0061,#1267):`statement_qualifiers` 那张表,同样加载后补+ #[sqlx(skip)]+ pub statement_qualifiers: Vec<StatementQualifier>,pub valid_from: Option<DateTime<Utc>>,pub valid_to: Option<DateTime<Utc>>,/// 精度描述的是这条事实**有的那些日期**的粒度。两端都没有日期时为 None——diff --git a/crates/utopia-server/src/api/mcp_tests.rs b/crates/utopia-server/src/api/mcp_tests.rsindex 6f86a0fb..1c6f1665 100644--- a/crates/utopia-server/src/api/mcp_tests.rs+++ b/crates/utopia-server/src/api/mcp_tests.rs@@ -992,6 +992,36 @@ async fn entity_fact_qualifier_text_preserves_the_stored_string() -> anyhow::Resf.clean().await}+#[tokio::test]+async fn entity_facts_reads_back_a_statements_role_words() -> anyhow::Result<()> {+ let Some(f) = Fixture::new().await? else {+ return Ok(());+ };+ sqlx::query(+ "INSERT INTO statement_qualifiers(fact_id,role,value)+ VALUES ($1,'lines','{\"value\":\"10-42\"}'::jsonb)",+ )+ .bind(f.corrected)+ .execute(&f.state.pool)+ .await?;+ let result = f+ .call("entity_facts", json!({"entity_id":f.subject}))+ .await?;+ let text = result["content"][0]["text"].as_str().unwrap();+ assert!(text.contains("lines: 10-42]"), "{text}");+ let fact = result["structuredContent"]["facts"]+ .as_array()+ .unwrap()+ .iter()+ .find(|fact| uuid(&fact["id"]) == f.corrected)+ .unwrap();+ assert_eq!(+ fact["statement_qualifiers"],+ json!([{"role":"lines","value":{"value":"10-42"},"entity_id":null,"entity_name":null}])+ );+ f.clean().await+}+#[tokio::test]async fn entity_facts_keeps_identity_values_filters_and_both_clocks() -> anyhow::Result<()> {let Some(f) = Fixture::new().await? else {diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rsindex ec5c6b4e..08b216cf 100644--- a/crates/utopia-server/src/api/tools.rs+++ b/crates/utopia-server/src/api/tools.rs@@ -1519,6 +1519,7 @@ mod tests {other_name: None,other_type: None,qualifiers: Vec::new(),+ statement_qualifiers: Vec::new(),object_value: Some(value),valid_from: Some(t("2023-06-01T00:00:00Z")),valid_to: Some(t("2024-02-20T00:00:00Z")),diff --git a/crates/utopia-server/src/api/tools_graph.rs b/crates/utopia-server/src/api/tools_graph.rsindex 70fa110f..eb27a121 100644--- a/crates/utopia-server/src/api/tools_graph.rs+++ b/crates/utopia-server/src/api/tools_graph.rs@@ -343,38 +343,41 @@ pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)/// 事实的另一端:对端实体,或属性值/// 边上的属性(0037)跟在对端后面:`Vega Capital [amount: 5000000000 $]`。-/// 模型读事实行时最常问的就是"投了多少",数不在行里它就答"没有金额信息"+/// 模型读事实行时最常问的就是"投了多少",数不在行里它就答"没有金额信息"。+/// 按文档角色词记的属性(0061)接在后面,名字是角色词:`[lines: 10-42]`fn qualifiers_text(f: &EntityFact) -> String {- if f.qualifiers.is_empty() {- return String::new();- }- let parts: Vec<String> = f+ let typed = f.qualifiers.iter()- .map(|q| {- let v = q- .value- .as_ref()- .and_then(|v| v.get("value"))- .map(|v| match v {- Value::String(s) => s.clone(),- other => other.to_string(),- })- .or_else(|| q.entity_name.clone())- .unwrap_or_else(|| "?".to_string());- let u = q- .value- .as_ref()- .and_then(|v| v.get("unit"))- .and_then(|u| u.as_str())- .map(|u| format!(" {u}"))- .unwrap_or_default();- format!("{}: {v}{u}", q.key)- })- .collect();+ .map(|q| qualifier_text(&q.key, q.value.as_ref(), q.entity_name.as_deref()));+ let worded = f+ .statement_qualifiers+ .iter()+ .map(|q| qualifier_text(&q.role, q.value.as_ref(), q.entity_name.as_deref()));+ let parts: Vec<String> = typed.chain(worded).collect();+ if parts.is_empty() {+ return String::new();+ }format!(" [{}]", parts.join(", "))}+fn qualifier_text(name: &str, value: Option<&Value>, entity_name: Option<&str>) -> String {+ let v = value+ .and_then(|v| v.get("value"))+ .map(|v| match v {+ Value::String(s) => s.clone(),+ other => other.to_string(),+ })+ .or_else(|| entity_name.map(String::from))+ .unwrap_or_else(|| "?".to_string());+ let u = value+ .and_then(|v| v.get("unit"))+ .and_then(|u| u.as_str())+ .map(|u| format!(" {u}"))+ .unwrap_or_default();+ format!("{name}: {v}{u}")+}+fn other_text(f: &EntityFact) -> String {let literal = f.object_value@@ -861,6 +864,7 @@ pub async fn entity_facts(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)"qualifier_type_id": q.qualifier_type_id, "key": q.key, "label": q.label,"value": q.value, "entity_id": q.entity_id, "entity_name": q.entity_name,})).collect::<Vec<_>>(),+ "statement_qualifiers": f.statement_qualifiers,"valid_from": f.valid_from, "valid_to": f.valid_to,"valid_from_precision": f.valid_from_precision,"valid_to_precision": f.valid_to_precision,@@ -1487,6 +1491,7 @@ mod tests {other_name: Some(other.into()),other_type: other_type.map(String::from),qualifiers: Vec::new(),+ statement_qualifiers: Vec::new(),object_value: None,valid_from: Some("2021-01-01T00:00:00Z".parse().unwrap()),valid_to: None,diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rsindex ad2c802c..6d981c00 100644--- a/crates/utopia-store/src/graph.rs+++ b/crates/utopia-store/src/graph.rs@@ -5,7 +5,7 @@ use std::collections::HashMap;use std::collections::HashSet;use utopia_core::models::{ChunkFactView, EntityFact, EntityHistoryEvent, EntityType, EvidenceView, FactQualifier,- FactReviewItem, GraphChange, GraphEdge, GraphNode, RelationType,+ FactReviewItem, GraphChange, GraphEdge, GraphNode, RelationType, StatementQualifier,};use utopia_core::{AppError, AppResult};use uuid::Uuid;@@ -199,17 +199,6 @@ pub async fn fact_qualifiers_for(Ok(out)}-/// 开放陈述上的一个属性(0044 第一刀):按文档的角色词记,不按本体属性。-/// 值或实体二选一;实体那一格带上它的显示名-#[derive(Debug, Clone, serde::Serialize)]-pub struct StatementQualifier {- /// 文档自己的角色词("amount"、"buyer")- pub role: String,- pub value: Option<serde_json::Value>,- pub entity_id: Option<Uuid>,- pub entity_name: Option<String>,-}-/// 往一条开放陈述上写一个按角色词记的属性。**先写者留着**:同一条陈述同一个角色词/// 再听到一次不覆盖(与 [`upsert_fact_qualifier`] 的 Conflict 一条规矩——两次观察/// 不一致该另立一行加一条冲突,这一刀还没走到那一步)。值与实体必须恰好给一个@@ -1523,14 +1512,16 @@ async fn edges_among(.bind(as_of).fetch_all(pool).await?;- // 边上的属性另一张表(0037),按 id 一次取回补上+ // 边上的属性另两张表(0037 按本体属性、0061 按角色词),按 id 一次取回补上{let ids: Vec<Uuid> = edges.iter().map(|x| x.id).collect();- let mut by_fact = fact_qualifiers_for(pool, &ids).await?;+ let (mut typed, mut worded) = tokio::try_join!(+ fact_qualifiers_for(pool, &ids),+ statement_qualifiers_for(pool, &ids)+ )?;for x in edges.iter_mut() {- if let Some(q) = by_fact.remove(&x.id) {- x.qualifiers = q;- }+ x.qualifiers = typed.remove(&x.id).unwrap_or_default();+ x.statement_qualifiers = worded.remove(&x.id).unwrap_or_default();}}Ok(edges)@@ -1870,14 +1861,16 @@ pub async fn entity_detail(.bind(at).fetch_all(pool).await?;- // 边上的属性另一张表(0037),按 id 一次取回补上+ // 边上的属性另两张表(0037 按本体属性、0061 按角色词),按 id 一次取回补上{let ids: Vec<Uuid> = facts.iter().map(|x| x.id).collect();- let mut by_fact = fact_qualifiers_for(pool, &ids).await?;+ let (mut typed, mut worded) = tokio::try_join!(+ fact_qualifiers_for(pool, &ids),+ statement_qualifiers_for(pool, &ids)+ )?;for x in facts.iter_mut() {- if let Some(q) = by_fact.remove(&x.id) {- x.qualifiers = q;- }+ x.qualifiers = typed.remove(&x.id).unwrap_or_default();+ x.statement_qualifiers = worded.remove(&x.id).unwrap_or_default();}}diff --git a/crates/utopia-store/tests/store/an_open_statement_keeps_the_documents_words.rs b/crates/utopia-store/tests/store/an_open_statement_keeps_the_documents_words.rsindex 17bce2b1..ddc0b102 100644--- a/crates/utopia-store/tests/store/an_open_statement_keeps_the_documents_words.rs+++ b/crates/utopia-store/tests/store/an_open_statement_keeps_the_documents_words.rs@@ -194,6 +194,18 @@ async fn an_open_statement_shows_under_its_phrase_and_reuses_its_row() -> anyhow.expect("overview shows it");assert_eq!(e.label.as_deref(), Some("acquired"));assert!(e.inferred, "名字来自原文,不是本体认下的关系");+ // 角色词属性跟着边读回来(#1267),不混进按本体属性记的 qualifiers+ let amount = |q: &[utopia_core::models::StatementQualifier]| {+ serde_json::to_value(q).unwrap()+ == serde_json::json!([{ "role": "amount",+ "value": { "value": "$1.2 billion" }, "entity_id": null, "entity_name": null }])+ };+ assert!(+ amount(&e.statement_qualifiers),+ "{:?}",+ e.statement_qualifiers+ );+ assert!(e.qualifiers.is_empty());let (_, facts) = graph::entity_detail(&pool, f.kb, f.acme, None, None).await?;let d = facts@@ -202,6 +214,11 @@ async fn an_open_statement_shows_under_its_phrase_and_reuses_its_row() -> anyhow.expect("entity detail shows it");assert_eq!(d.predicate_label.as_deref(), Some("acquired"));assert_eq!(d.other_id, Some(f.beta));+ assert!(+ amount(&d.statement_qualifiers),+ "{:?}",+ d.statement_qualifiers+ );let (_, edges) = graph::neighborhood(&pool, f.kb, f.acme, 1, None, None).await?;let n = edgesdiff --git a/docs/decisions/0044-the-ontology-is-a-view-over-what-documents-say.md b/docs/decisions/0044-the-ontology-is-a-view-over-what-documents-say.mdindex d8895511..39e94664 100644--- a/docs/decisions/0044-the-ontology-is-a-view-over-what-documents-say.md+++ b/docs/decisions/0044-the-ontology-is-a-view-over-what-documents-say.md@@ -68,6 +68,8 @@ This is how the facts a reader draws without the text stating them (a place's coWhen the ontology changes, only facts under changed signatures and rules are recomputed. A signature with no property stays in the open graph, loses nothing, and counts toward the workbench's suggestions.+**Revision 2026-10-16 ([#1267](https://github.com/deeplethe/utopia/issues/1267)):** a statement's role-word qualifiers are read back: entity detail, graph edges and `entity_facts` carry them as `statement_qualifiers`, beside the typed `qualifiers`, on the open statement and on the typed rows it materialised.+**Revision 2026-10-15 (the ontology decides a phrase it declares, [#1242](https://github.com/deeplethe/utopia/issues/1242)):** a signature from a document a `statements` source pushed ([0054](0054-a-source-may-push-statements-in-the-open-contract.md)) is bound without the model when its phrase, normalised as kind words are, equals the key or label of exactly one declared relation that is not a state, and the relation's declared domain admits the subject's class and its declared range the object's class, through the class hierarchy and forward only. The binding is recorded `decided_by = 'ontology'` (migration 0113), with `votes = {"reason": "declared_relation"}` and no basis. It is decided when the document's extraction finishes, and that extraction then queues `materialize` unless one is queued, so a base with no chat model gets typed facts from what it is pushed; on a base of 1,220 pushed entities every class was bound up front and every relation stayed open, because the aligner is the only writer of phrase bindings and needs a model.Why it keeps this decision: it binds a signature, never a fact, and it leaves a row the alignment endpoints show and overturn. A person's decision is never replaced (the rule of `decide_on`, which now holds against the ontology too). The aligner leaves an ontology decision alone while the relation still declares it, and re-decides it like any agent decision once it does not (a renamed relation, a narrowed domain). Why it keeps [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md): it fires only on equality with a relation a person declared by importing or editing the ontology, and only when the declared ends agree, so it reads the contract rather than guessing at it.diff --git a/docs/design/ledger.md b/docs/design/ledger.mdindex 5ba4e7f5..34b90822 100644--- a/docs/design/ledger.md+++ b/docs/design/ledger.md@@ -35,8 +35,9 @@ word for open statements; `fact_qualifiers (fact, qualifier_type, value | entitydeclared attribute for typed rows, converted by the attribute's datatype, the unit read from thetext (`$4 billion` becomes 4000000000 with unit `$`) and the declared unit only when the textcarries none; a qualifier is not part of the edge's identity; every superseding writer copies-qualifiers with the evidence [0037, #731]. `time_mentions (fact, chunk, text, char_start)` hold-verbatim time words [#731]. Names are value facts on `known_as` [0041]. `entities.description`+qualifiers with the evidence [0037, #731]. Entity detail, graph edges and the MCP `entity_facts`+tool return both: typed ones in `qualifiers`, role words in `statement_qualifiers` [#1267].+`time_mentions (fact, chunk, text, char_start)` hold verbatim time words [#731]. Names are value facts on `known_as` [0041]. `entities.description`marks a described, unnamed thing [#731].**Derived facts live in their own table** (`derived_facts`, widened to literal objects, withdiff --git a/web/src/api.ts b/web/src/api.tsindex c5e260b5..edea8804 100644--- a/web/src/api.ts+++ b/web/src/api.ts@@ -1071,6 +1071,8 @@ export interface GraphEdge {blocked: boolean;/** 边上的属性(0037) */qualifiers: FactQualifier[];+ /** 文档的角色词(0044):不是本体属性,另放一处 */+ statement_qualifiers: StatementQualifier[];}/** 实体的一个名字(0041)。`canonical` 是面板标题上那个;曾用名在世界轴上有结束 */@@ -1087,6 +1089,14 @@ export interface NameView {evidence_count: number;}+/** 开放陈述按文档角色词记的限定(0044):值或实体 */+export interface StatementQualifier {+ role: string;+ value: unknown | null;+ entity_id: string | null;+ entity_name: string | null;+}+export interface EntityFact {id: string;direction: "out" | "in";@@ -1106,6 +1116,8 @@ export interface EntityFact {object_value: Record<string, unknown> | null;/** 边上的属性(0037) */qualifiers: FactQualifier[];+ /** 文档的角色词(0044):不是本体属性,另放一处 */+ statement_qualifiers: StatementQualifier[];valid_from: string | null;valid_to: string | null;/** 读出来的区间(0022),与 GraphEdge 同义:「此刻成立」按它判 */diff --git a/web/src/docs/mcp.md b/web/src/docs/mcp.mdindex 1417802d..d9c203cf 100644--- a/web/src/docs/mcp.md+++ b/web/src/docs/mcp.md@@ -127,6 +127,9 @@ unit rather than formatting them into a string. `inferred` describes anunaccepted predicate name; it does **not** mean the fact is derived.`qualifiers[]` preserves attributes attached to the relation itself: each has`qualifier_type_id`, `key`, `label`, raw `value`, `entity_id`, and `entity_name`.+`statement_qualifiers[]` holds the document's own role words for the statement+(such as `amount` or `lines`), which are not declared attributes: each has `role`,+raw `value`, `entity_id`, and `entity_name`.A `derived_facts[]` entry contains `id`, `subject_id`, `subject`, `predicate_id`,`predicate`, `object_id`, `object`, raw `object_value`, `rule`, `rule_name`,diff --git a/web/src/pages/Graph.test.ts b/web/src/pages/Graph.test.tsindex bc6434d2..ca8d1410 100644--- a/web/src/pages/Graph.test.ts+++ b/web/src/pages/Graph.test.ts@@ -38,6 +38,7 @@ const base: EntityFact = {other_name: null,object_value: null,qualifiers: [],+ statement_qualifiers: [],valid_from: null,valid_to: null,holds_from: null,