Skip to content

World's first open-source enterprise world 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.rs
index 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.rs
index 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::Res
f.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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 = edges
diff --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.md
index 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 co
When 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.md
index 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 | entity
declared attribute for typed rows, converted by the attribute's datatype, the unit read from the
text (`$4 billion` becomes 4000000000 with unit `$`) and the declared unit only when the text
carries 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, with
diff --git a/web/src/api.ts b/web/src/api.ts
index 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.md
index 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 an
unaccepted 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.ts
index 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,