World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.rsindex 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.rsindex 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() -> anyhof.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::Resultvia_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.rsindex 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) -> Tlet 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.mdindex 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 breakingchange needs a decision record explaining why; the internal tables and UI APIdiff --git a/web/src/docs/mcp.md b/web/src/docs/mcp.mdindex 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, timestampsare 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 resultis a successful read, not an error.