Skip to content

World's first open-source enterprise world model.

Keep MCP read failures and refused calls visible (#604)

Daniel537f7237fade
diff --git a/crates/utopia-server/src/api/mcp.rs b/crates/utopia-server/src/api/mcp.rs
index 68daac9d..a72a58dd 100644
--- a/crates/utopia-server/src/api/mcp.rs
+++ b/crates/utopia-server/src/api/mcp.rs
@@ -219,32 +219,31 @@ pub async fn handle(
return Ok(rpc_err(id, -32601, &message));
}
// 与聊天共用参数守卫:缺少 query 不能变成一次成功的空搜索。
- if let Err((text, step)) = super::chat::check_call(
+ let result = match super::chat::check_call(
&super::chat::tools_schema(can_write, &[]),
name,
&args.to_string(),
) {
- return Ok(ok(
- id,
- tool_result(tools::ToolResult::new(text, step).error()),
- ));
- }
- // `mounted_sources` 仍旧空着:`query_data` 没放出来,给了也没人用。
- // `can_write` 不再写死 false——它现在是令牌与角色一起算出来的
- let ctx = ToolCtx {
- state: &state,
- kb_id,
- workspace_id: kb.workspace_id,
- mounted_sources: &[],
- can_write,
- actor: Some(user.id),
- // 「谁说的」要答到 agent 这一层:一个人可以同时挂三个客户端
- via_token: Some(auth.token_id),
- // agent 的意图不在请求里;同名按事实数排
- question: None,
+ Err((text, step)) => tools::ToolResult::new(text, step).error(),
+ Ok(args) => {
+ // `mounted_sources` 仍旧空着:`query_data` 没放出来,给了也没人用。
+ // `can_write` 不再写死 false——它现在是令牌与角色一起算出来的
+ let ctx = ToolCtx {
+ state: &state,
+ kb_id,
+ workspace_id: kb.workspace_id,
+ mounted_sources: &[],
+ can_write,
+ actor: Some(user.id),
+ // 「谁说的」要答到 agent 这一层:一个人可以同时挂三个客户端
+ via_token: Some(auth.token_id),
+ // agent 的意图不在请求里;同名按事实数排
+ question: None,
+ };
+ let mut sink = ToolSink::default();
+ tools::dispatch(&ctx, &mut sink, name, &args).await
+ }
};
- let mut sink = ToolSink::default();
- let result = tools::dispatch(&ctx, &mut sink, name, &args).await;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
diff --git a/crates/utopia-server/src/api/mcp_tests.rs b/crates/utopia-server/src/api/mcp_tests.rs
index d1b72e2c..44afda72 100644
--- a/crates/utopia-server/src/api/mcp_tests.rs
+++ b/crates/utopia-server/src/api/mcp_tests.rs
@@ -197,6 +197,42 @@ fn uuid(value: &Value) -> Uuid {
value.as_str().unwrap().parse().unwrap()
}
+#[tokio::test]
+async fn refused_and_executed_calls_are_each_audited_once() -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let auth = utopia_store::tokens::authenticate(&f.state.pool, &f.token).await?;
+ for (args, is_error, count) in [(json!({}), true, 1), (json!({"query":"orchard"}), false, 2)] {
+ let result = f.call("search_chunks", args).await?;
+ assert_eq!(result["isError"], is_error);
+ if is_error {
+ assert!(result.get("structuredContent").is_none());
+ }
+ let rows: Vec<(Uuid, Uuid, String, Uuid, Value)> = sqlx::query_as(
+ "SELECT kb_id, actor_id, target_kind, target_id, detail FROM audit_events
+ WHERE kb_id=$1 AND action='mcp.tool_called'",
+ )
+ .bind(f.kb)
+ .fetch_all(&f.state.pool)
+ .await?;
+ assert_eq!(rows.len(), count);
+ for row in rows {
+ assert_eq!(
+ row,
+ (
+ f.kb,
+ auth.user_id,
+ "personal_token".into(),
+ auth.token_id,
+ json!({"tool":"search_chunks"}),
+ )
+ );
+ }
+ }
+ f.clean().await
+}
+
#[tokio::test]
async fn find_entities_returns_ranked_ids_and_keeps_text() -> anyhow::Result<()> {
let Some(f) = Fixture::new().await? else {
@@ -217,6 +253,7 @@ async fn find_entities_returns_ranked_ids_and_keeps_text() -> anyhow::Result<()>
format!("Best match: {} | Alice | Thing | 2 facts", f.subject)
);
let empty = f.call("find_entities", json!({"name":"Nobody"})).await?;
+ assert_eq!(empty["isError"], false);
assert_eq!(empty["structuredContent"]["entities"], json!([]));
assert_eq!(empty["content"][0]["text"], "No matching entities.");
let invalid = f.call("find_entities", json!({})).await?;
@@ -250,6 +287,9 @@ async fn search_chunks_returns_chunk_and_document_ids_with_the_same_excerpt() ->
return Ok(());
};
let result = f.call("search_chunks", json!({"query":"orchard"})).await?;
+ assert_eq!(result["isError"], false);
+ assert_eq!(result["structuredContent"]["limit"], 6);
+ assert_eq!(result["structuredContent"]["limit_reached"], false);
let chunk = &result["structuredContent"]["chunks"][0];
assert_eq!(uuid(&chunk["chunk_id"]), f.chunk);
assert_eq!(uuid(&chunk["document_id"]), f.document);
@@ -270,7 +310,39 @@ async fn search_chunks_returns_chunk_and_document_ids_with_the_same_excerpt() ->
)
.await?;
assert_eq!(empty["structuredContent"]["chunks"], json!([]));
+ assert_eq!(empty["isError"], false);
+ assert_eq!(empty["structuredContent"]["limit_reached"], false);
assert_eq!(empty["content"][0]["text"], "No results.");
+ let mut indexed = vec![(f.chunk.to_string(), "orchard ".repeat(120))];
+ for seq in 2..8 {
+ let id = Uuid::now_v7();
+ let text = format!("orchard section {seq}");
+ sqlx::query("INSERT INTO chunks(id,kb_id,document_id,seq,text) VALUES ($1,$2,$3,$4,$5)")
+ .bind(id)
+ .bind(f.kb)
+ .bind(f.document)
+ .bind(seq)
+ .bind(&text)
+ .execute(&f.state.pool)
+ .await?;
+ indexed.push((id.to_string(), text));
+ }
+ f.state
+ .search
+ .reindex_document(&f.kb.to_string(), &f.document.to_string(), &indexed)?;
+ let capped = f.call("search_chunks", json!({"query":"orchard"})).await?;
+ assert_eq!(capped["isError"], false);
+ assert_eq!(capped["structuredContent"]["limit"], 6);
+ assert_eq!(capped["structuredContent"]["limit_reached"], true);
+ let chunks = capped["structuredContent"]["chunks"].as_array().unwrap();
+ assert_eq!(chunks.len(), 6);
+ let ids: std::collections::HashSet<Uuid> =
+ chunks.iter().map(|c| uuid(&c["chunk_id"])).collect();
+ assert_eq!(ids.len(), 6);
+ for chunk in chunks {
+ assert_eq!(uuid(&chunk["document_id"]), f.document);
+ assert!(indexed.iter().any(|(id, _)| chunk["chunk_id"] == *id));
+ }
f.clean().await
}
@@ -279,6 +351,24 @@ async fn entity_facts_keeps_identity_values_filters_and_both_clocks() -> anyhow:
let Some(f) = Fixture::new().await? else {
return Ok(());
};
+ let broker = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO relation_types(id,kb_id,key,label,kind)
+ VALUES ($1,$2,'broker','Broker','relation')",
+ )
+ .bind(broker)
+ .bind(f.kb)
+ .execute(&f.state.pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO fact_qualifiers(fact_id,qualifier_type_id,entity_id)
+ VALUES ($1,$2,$3)",
+ )
+ .bind(f.corrected)
+ .bind(broker)
+ .bind(f.object)
+ .execute(&f.state.pool)
+ .await?;
let result = f
.call("entity_facts", json!({"entity_id":f.subject}))
.await?;
@@ -290,10 +380,22 @@ async fn entity_facts_keeps_identity_values_filters_and_both_clocks() -> anyhow:
.find(|r| uuid(&r["id"]) == f.corrected)
.unwrap();
assert_eq!(corrected["recorded_at"], CORRECTION);
+ let qualifiers = corrected["qualifiers"].as_array().unwrap();
+ let weight = qualifiers.iter().find(|q| q["key"] == "weight").unwrap();
+ assert_eq!(weight["value"], json!({"value":3,"unit":"kg"}));
+ assert!(weight["entity_id"].is_null());
+ assert!(weight["entity_name"].is_null());
assert_eq!(
- corrected["qualifiers"][0]["value"],
- json!({"value":3,"unit":"kg"})
+ qualifiers.iter().find(|q| q["key"] == "broker").unwrap(),
+ &json!({
+ "qualifier_type_id":broker,"key":"broker","label":"Broker",
+ "value":null,"entity_id":f.object,"entity_name":"Acme",
+ })
);
+ assert!(result["content"][0]["text"]
+ .as_str()
+ .unwrap()
+ .contains("broker: Acme"));
assert_eq!(uuid(&corrected["supersedes"]), f.fact);
assert_eq!(
corrected["document_ids"],
@@ -361,6 +463,7 @@ async fn entity_facts_keeps_identity_values_filters_and_both_clocks() -> anyhow:
.await?;
assert_eq!(empty["structuredContent"]["facts"], json!([]));
assert_eq!(empty["structuredContent"]["derived_facts"], json!([]));
+ assert_eq!(empty["isError"], false);
let history = f
.call(
"entity_facts",
@@ -437,6 +540,25 @@ async fn changes_returns_fact_ids_and_a_reusable_correction_timestamp() -> anyho
.await?;
assert_eq!(empty["structuredContent"]["changes"], json!([]));
assert_eq!(empty["structuredContent"]["limit_reached"], false);
+ assert_eq!(empty["isError"], false);
+ let started = chrono::Utc::now();
+ let open = f.call("changes", json!({"since":"2026-03-20"})).await?;
+ let finished = chrono::Utc::now();
+ let data = &open["structuredContent"];
+ let until: chrono::DateTime<chrono::Utc> = data["until"].as_str().unwrap().parse()?;
+ let since: chrono::DateTime<chrono::Utc> = data["since"].as_str().unwrap().parse()?;
+ assert_eq!(open["isError"], false);
+ assert_eq!(data["since"], "2026-03-20T00:00:00Z");
+ assert!(started <= until && until <= finished);
+ assert_eq!(data["limit_reached"], false);
+ let changes = data["changes"].as_array().unwrap();
+ assert!(changes
+ .iter()
+ .any(|c| uuid(&c["fact_id"]) == f.corrected && c["at"] == CORRECTION));
+ for change in changes {
+ let at: chrono::DateTime<chrono::Utc> = change["at"].as_str().unwrap().parse()?;
+ assert!(since <= at && at < until);
+ }
sqlx::query(
"INSERT INTO facts(id,kb_id,subject_id,predicate_id,object_value,recorded_at)
SELECT gen_random_uuid(),kb_id,subject_id,predicate_id,
@@ -463,6 +585,80 @@ async fn changes_returns_fact_ids_and_a_reusable_correction_timestamp() -> anyho
f.clean().await
}
+#[tokio::test]
+async fn missing_entities_and_empty_graph_reads_keep_their_results() -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ let isolated = Uuid::now_v7();
+ sqlx::query("INSERT INTO entities(id,kb_id,canonical_name) VALUES ($1,$2,'Isolated')")
+ .bind(isolated)
+ .bind(f.kb)
+ .execute(&f.state.pool)
+ .await?;
+ for (name, args, is_error, text) in [
+ (
+ "entity_facts",
+ json!({"entity_id":"Nobody"}),
+ true,
+ "Invalid entity: no entity named \"Nobody\" in this base (expected a name, or the uuid returned by find_entities).",
+ ),
+ (
+ "neighbors",
+ json!({"entity":"Nobody"}),
+ false,
+ "Unknown entity: no entity named \"Nobody\" in this base.",
+ ),
+ (
+ "timeline",
+ json!({"entity":"Nobody"}),
+ false,
+ "Unknown entity: no entity named \"Nobody\" in this base.",
+ ),
+ (
+ "paths_between",
+ json!({"from":"Nobody","to":f.object}),
+ false,
+ "Unknown `from`: no entity named \"Nobody\" in this base.",
+ ),
+ (
+ "paths_between",
+ json!({"from":f.subject,"to":"Nobody"}),
+ false,
+ "Unknown `to`: no entity named \"Nobody\" in this base.",
+ ),
+ ("neighbors", json!({"entity":f.other_kb}), false, "Entity not found."),
+ ("timeline", json!({"entity":f.other_kb}), false, "Entity not found."),
+ (
+ "neighbors",
+ json!({"entity":isolated}),
+ false,
+ "Isolated (untyped): no linked entities.",
+ ),
+ (
+ "timeline",
+ json!({"entity":isolated}),
+ false,
+ "Isolated (untyped): no dated facts; 0 facts carry no date (entity_facts lists them).",
+ ),
+ ] {
+ let result = f.call(name, args).await?;
+ assert_eq!(result["isError"], is_error, "{name}: {result}");
+ assert_eq!(result["content"][0]["text"], text, "{name}");
+ assert!(result.get("structuredContent").is_none());
+ }
+ let empty = f
+ .call("paths_between", json!({"from":f.subject,"to":isolated}))
+ .await?;
+ assert_eq!(empty["isError"], false);
+ assert!(empty["content"][0]["text"]
+ .as_str()
+ .unwrap()
+ .starts_with("No path of up to 3 hops between "));
+ assert!(empty.get("structuredContent").is_none());
+ f.clean().await
+}
+
#[tokio::test]
async fn failed_reads_do_not_become_successful_empty_results() -> anyhow::Result<()> {
let Some(f) = Fixture::new().await? else {
@@ -479,15 +675,73 @@ async fn failed_reads_do_not_become_successful_empty_results() -> anyhow::Result
via_token: None,
question: None,
};
- for (name, args) in [
- ("find_entities", json!({"name":"Alice"})),
- ("search_chunks", json!({"query":"orchard"})),
- ("entity_facts", json!({"entity_id":f.subject})),
- ("changes", json!({"since":"2026"})),
+ for (name, args, text) in [
+ (
+ "find_entities",
+ json!({"name":"Alice"}),
+ "Could not look up entities.",
+ ),
+ (
+ "search_chunks",
+ json!({"query":"orchard"}),
+ "Could not search the documents.",
+ ),
+ (
+ "entity_facts",
+ json!({"entity_id":f.subject}),
+ "Could not read the entity facts.",
+ ),
+ (
+ "entity_facts",
+ json!({"entity_id":"Alice"}),
+ "Could not look up entities.",
+ ),
+ (
+ "neighbors",
+ json!({"entity":"Alice"}),
+ "Could not look up entities.",
+ ),
+ (
+ "timeline",
+ json!({"entity":"Alice"}),
+ "Could not look up entities.",
+ ),
+ (
+ "neighbors",
+ json!({"entity":f.subject}),
+ "Could not read the entity facts.",
+ ),
+ (
+ "timeline",
+ json!({"entity":f.subject}),
+ "Could not read the entity facts.",
+ ),
+ (
+ "paths_between",
+ json!({"from":"Alice","to":f.object}),
+ "Could not look up entities.",
+ ),
+ (
+ "paths_between",
+ json!({"from":f.subject,"to":"Acme"}),
+ "Could not look up entities.",
+ ),
+ // Equal UUIDs return before reading the database; these must be different.
+ (
+ "paths_between",
+ json!({"from":f.subject,"to":f.object}),
+ "Could not search paths.",
+ ),
+ (
+ "changes",
+ json!({"since":"2026"}),
+ "Could not read the graph changes.",
+ ),
] {
let result =
tool_result(tools::dispatch(&ctx, &mut ToolSink::default(), name, &args).await);
assert_eq!(result["isError"], true, "{name}: {result}");
+ assert_eq!(result["content"][0]["text"], text, "{name}: {args}");
assert!(result.get("structuredContent").is_none());
}
// Reconnect only for fixture cleanup.
diff --git a/crates/utopia-server/src/api/tools_graph.rs b/crates/utopia-server/src/api/tools_graph.rs
index b3898b39..732a6be9 100644
--- a/crates/utopia-server/src/api/tools_graph.rs
+++ b/crates/utopia-server/src/api/tools_graph.rs
@@ -93,10 +93,21 @@ struct Resolved {
note: Option<String>,
}
-async fn resolve(ctx: &ToolCtx<'_>, sink: &mut ToolSink, raw: &str) -> Result<Resolved, String> {
+enum ResolveError {
+ Unresolved(String),
+ ReadFailed,
+}
+
+async fn resolve(
+ ctx: &ToolCtx<'_>,
+ sink: &mut ToolSink,
+ raw: &str,
+) -> Result<Resolved, ResolveError> {
let raw = raw.trim();
if raw.is_empty() {
- return Err("an entity name or id is required".to_string());
+ return Err(ResolveError::Unresolved(
+ "an entity name or id is required".to_string(),
+ ));
}
if let Ok(id) = raw.parse::<Uuid>() {
return Ok(Resolved {
@@ -107,11 +118,13 @@ async fn resolve(ctx: &ToolCtx<'_>, sink: &mut ToolSink, raw: &str) -> Result<Re
}
let hits = lookup(ctx, raw).await.map_err(|e| {
tracing::warn!(error = %e, "Entity lookup failed");
- "could not look up entities".to_string()
+ ResolveError::ReadFailed
})?;
let (ranked, by_question) = rank_by_question(ctx, rank(hits, raw), raw).await;
let Some(first) = ranked.first() else {
- return Err(format!("no entity named \"{raw}\" in this base"));
+ return Err(ResolveError::Unresolved(format!(
+ "no entity named \"{raw}\" in this base"
+ )));
};
remember(sink, first);
let others: Vec<String> = ranked
@@ -546,7 +559,14 @@ pub async fn entity_facts(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
.unwrap_or("");
let who = match resolve(ctx, sink, raw).await {
Ok(r) => r,
- Err(e) => {
+ Err(ResolveError::ReadFailed) => {
+ return ToolResult::new(
+ "Could not look up entities.".into(),
+ json!({ "kind": "facts", "label": "?", "detail": "failed" }),
+ )
+ .error();
+ }
+ Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!(
"Invalid entity: {e} (expected a name, or the uuid returned by find_entities)."
@@ -716,7 +736,14 @@ pub async fn neighbors(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) ->
.unwrap_or("");
let who = match resolve(ctx, sink, raw).await {
Ok(r) => r,
- Err(e) => {
+ Err(ResolveError::ReadFailed) => {
+ return ToolResult::new(
+ "Could not look up entities.".into(),
+ json!({ "kind": "neighbors", "label": "?", "detail": "failed" }),
+ )
+ .error();
+ }
+ Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!("Unknown entity: {e}."),
json!({ "kind": "neighbors", "label": "?", "detail": "unknown entity" }),
@@ -726,14 +753,26 @@ pub async fn neighbors(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) ->
let m = moments(args);
let filter = FactFilter::from_args(args);
let limit = limit_of(args, NEIGHBORS_DEFAULT);
- let Ok((node, facts)) =
- utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, m.at, m.as_of).await
- else {
- return ToolResult::new(
- "Entity not found.".to_string(),
- json!({ "kind": "neighbors", "label": "?", "detail": "not found" }),
- );
- };
+ let (node, facts) =
+ match utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, m.at, m.as_of)
+ .await
+ {
+ Ok(detail) => detail,
+ Err(utopia_core::AppError::NotFound) => {
+ return ToolResult::new(
+ "Entity not found.".to_string(),
+ json!({ "kind": "neighbors", "label": "?", "detail": "not found" }),
+ );
+ }
+ Err(e) => {
+ tracing::warn!(error = %e, "Entity neighbors lookup failed");
+ return ToolResult::new(
+ "Could not read the entity facts.".into(),
+ json!({ "kind": "neighbors", "label": "?", "detail": "failed" }),
+ )
+ .error();
+ }
+ };
// 邻居是对端**实体**;属性值不算邻居,entity_facts 里有
let (matched, aligned) = filtered(ctx, &facts, &filter).await;
let linked: Vec<&EntityFact> = matched
@@ -823,7 +862,14 @@ pub async fn timeline(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> T
.unwrap_or("");
let who = match resolve(ctx, sink, raw).await {
Ok(r) => r,
- Err(e) => {
+ Err(ResolveError::ReadFailed) => {
+ return ToolResult::new(
+ "Could not look up entities.".into(),
+ json!({ "kind": "timeline", "label": "?", "detail": "failed" }),
+ )
+ .error();
+ }
+ Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!("Unknown entity: {e}."),
json!({ "kind": "timeline", "label": "?", "detail": "unknown entity" }),
@@ -833,14 +879,26 @@ pub async fn timeline(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> T
let m = moments(args);
let filter = FactFilter::from_args(args);
let limit = limit_of(args, TIMELINE_DEFAULT);
- let Ok((node, facts)) =
- utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, None, m.as_of).await
- else {
- return ToolResult::new(
- "Entity not found.".to_string(),
- json!({ "kind": "timeline", "label": "?", "detail": "not found" }),
- );
- };
+ let (node, facts) =
+ match utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, None, m.as_of)
+ .await
+ {
+ Ok(detail) => detail,
+ Err(utopia_core::AppError::NotFound) => {
+ return ToolResult::new(
+ "Entity not found.".to_string(),
+ json!({ "kind": "timeline", "label": "?", "detail": "not found" }),
+ );
+ }
+ Err(e) => {
+ tracing::warn!(error = %e, "Entity timeline lookup failed");
+ return ToolResult::new(
+ "Could not read the entity facts.".into(),
+ json!({ "kind": "timeline", "label": "?", "detail": "failed" }),
+ )
+ .error();
+ }
+ };
// 只要**说出了世界时间**的事实。没日期的那些起点是摄取时刻,排进时间线只会
// 把一篇文章的日期当成事件的日期
let (matched, aligned) = filtered(ctx, &facts, &filter).await;
@@ -952,7 +1010,14 @@ pub async fn paths_between(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
}
ends.push(r);
}
- Err(e) => {
+ Err(ResolveError::ReadFailed) => {
+ return ToolResult::new(
+ "Could not look up entities.".into(),
+ json!({ "kind": "path", "label": "?", "detail": "failed" }),
+ )
+ .error();
+ }
+ Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!("Unknown `{key}`: {e}."),
json!({ "kind": "path", "label": "?", "detail": "unknown entity" }),
@@ -984,10 +1049,12 @@ pub async fn paths_between(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
{
Ok(p) => p,
Err(e) => {
+ tracing::warn!(error = %e, "Path search failed");
return ToolResult::new(
- format!("Path search failed: {e}"),
+ "Could not search paths.".into(),
json!({ "kind": "path", "label": "?", "detail": "failed" }),
)
+ .error();
}
};
let label = format!("{} ↔ {}", from.name, to.name);
diff --git a/docs/decisions/0020-an-auditor-reads-it-without-us.md b/docs/decisions/0020-an-auditor-reads-it-without-us.md
index f47041c5..6e4447bf 100644
--- a/docs/decisions/0020-an-auditor-reads-it-without-us.md
+++ b/docs/decisions/0020-an-auditor-reads-it-without-us.md
@@ -12,6 +12,16 @@ Not another Utopia. A regulator, an auditor, or the team's own graph tooling: so
## Identity
+**Revision 2026-09-11 ([#601](https://github.com/deeplethe/utopia/pull/601),
+[#603](https://github.com/deeplethe/utopia/issues/603)).** This record originally
+described the RDF mapping without explicitly stating its compatibility boundary.
+#601 added that clarification and structured MCP reads sharing the ledger UUIDs,
+restored the premise links already described under Lineage, and documented the
+remaining gaps: conflict/review state, chunk identity behind quotes, and historical
+proof snapshots. The documented MCP field policy is now explicit too: removing or
+renaming a documented `structuredContent` field requires a decision record; clients should
+tolerate additional fields.
+
The RDF mapping is the supported external machine-readable read contract
(clarified in [#550](https://github.com/deeplethe/utopia/issues/550)). A breaking
change needs a decision record explaining why; the internal tables and UI API
diff --git a/web/src/docs/mcp.md b/web/src/docs/mcp.md
index ea763bc3..85f784b8 100644
--- a/web/src/docs/mcp.md
+++ b/web/src/docs/mcp.md
@@ -89,6 +89,8 @@ Read the JSON field directly; the text is presentation, not a format to parse.
Every structured result includes `kb_id`. IDs are opaque UUID strings, timestamps
are RFC3339 with fractional seconds preserved, unknown optional values are `null`,
and empty collections are `[]`. Clients should tolerate additional fields.
+Removing or renaming a documented `structuredContent` field is a breaking change
+and requires a decision record explaining why.
Failures have `isError: true` and no structured success payload; an empty result
is a successful read, not an error.