Skip to content

World's first open-source enterprise world model.

An automatic merge is gated by what it can undo (#474)

WaylandYang3e1cb40934aa
diff --git a/crates/utopia-server/src/adjudication.rs b/crates/utopia-server/src/adjudication.rs
index 1176fd61..d6186ece 100644
--- a/crates/utopia-server/src/adjudication.rs
+++ b/crates/utopia-server/src/adjudication.rs
@@ -201,6 +201,24 @@ async fn apply_verdict(
}
match same {
Some(true) if conf >= AUTO_CONF => {
+ // 执行闸门(0027):合并会立刻送出图外的东西——违规、派生、答案——留给人,
+ // 把握再高也不动手。人看到的是留下的原因,不是「裁决器没把握」
+ let impact = utopia_store::execution_gate::impact_of(
+ &state.pool,
+ kb_id,
+ item.left.id,
+ item.right.id,
+ )
+ .await?;
+ if let Some(hold) = utopia_store::execution_gate::hold(&impact) {
+ utopia_store::resolution::escalate_review(
+ &state.pool,
+ item.id,
+ &format!("escalate_impact|{hold}"),
+ )
+ .await?;
+ return Ok(());
+ }
let (target, source) =
utopia_store::resolution::merge_direction(&state.pool, item.left.id, item.right.id)
.await?;
diff --git a/crates/utopia-server/src/governance.rs b/crates/utopia-server/src/governance.rs
index 546f9f6d..ea98b610 100644
--- a/crates/utopia-server/src/governance.rs
+++ b/crates/utopia-server/src/governance.rs
@@ -25,6 +25,7 @@ use utopia_core::AppError;
use utopia_extract::governor::{self, Step};
use utopia_llm::{tool_result_message, LlmClient};
use utopia_store::alerts;
+use utopia_store::execution_gate;
use utopia_store::governance::{self as gov, Gate, NewDecision, Precedents, AUTO_CONF};
use uuid::Uuid;
@@ -458,6 +459,31 @@ async fn apply(ctx: &Ctx<'_>, item: &ReviewItem, p: &Precedents, look: Look) ->
audit(ctx, "review.merge", item, conf, id).await;
return Ok(());
}
+ // 执行闸门(0027):合并会立刻送出图外的东西——违规、派生、答案——留给人,
+ // 把握再高也不动手。agent 的看法照记成建议,理由前面写明是闸门留下的
+ let impact = execution_gate::impact_of(pool, kb_id, l, r).await?;
+ if let Some(hold) = execution_gate::hold(&impact) {
+ utopia_store::resolution::escalate_review(
+ pool,
+ item.id,
+ &format!("escalate_impact|{hold}"),
+ )
+ .await?;
+ let held = match look.why.as_deref() {
+ Some(why) => format!("held for a person: {}; {why}", hold.explain()),
+ None => format!("held for a person: {}", hold.explain()),
+ };
+ gov::record(
+ pool,
+ kb_id,
+ NewDecision {
+ reason: Some(&held),
+ ..decision("proposed", None)
+ },
+ )
+ .await?;
+ return Ok(());
+ }
let (target, source) = utopia_store::resolution::merge_direction(pool, l, r).await?;
match utopia_store::resolution::merge_entities(
pool, kb_id, source, target, None, &reason,
diff --git a/crates/utopia-store/src/execution_gate.rs b/crates/utopia-store/src/execution_gate.rs
new file mode 100644
index 00000000..ce217cd7
--- /dev/null
+++ b/crates/utopia-store/src/execution_gate.rs
@@ -0,0 +1,173 @@
+//! 执行闸门(0027,#357):一次自动合并能不能不经人就落地,看它**撤得回什么**,
+//! 不只看把握。
+//!
+//! 合并在图里撤得回:`revert_merge` 把事实搬回去,0019 之后连合并前的图都读得出。
+//! 撤不回的是它活着那几天离开图的东西——推理据它推出的派生、据它开出的违规与告警、
+//! 进了导出的三元组、带引用给出去的答案。撤销还原的是图,不是图被读进去的那个世界。
+//!
+//! 这里问的只有一件事:**这一次合并会不会立刻把什么送出图外**。会,就留给人,
+//! 把握再高也不动手。只管合并:分开撤起来不费什么,下一次合并就是撤销。
+//!
+//! `hold` 是纯函数,`impact_of` 只取数。攒批裁决器与治理 agent 走同一个闸门;
+//! 路线图上那道「执行闸门」(检查 agent 的调用)以后也接这一个,不长第二个。
+
+use sqlx::PgPool;
+use utopia_core::AppResult;
+use uuid::Uuid;
+
+/// 一次合并会立刻牵动的东西
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct Impact {
+ /// 两边各持一条同一个 functional 谓词的事实、指向不同的实体:合了就是一条
+ /// `functional` 违规,一致性检查下一次跑就会开出来——那是离开图的第一站。
+ /// 记谓词标签;`inverse_functional` 对称地算
+ pub contradictions: Vec<String>,
+ /// 任一边参与的、还成立的派生事实数:合并改了前提,这些派生会被重写
+ pub derived: i64,
+ /// 任一边在对话里被认过的回答数:这个实体是人在问的,错合并就进下一个答案
+ pub answered: i64,
+}
+
+/// 留给人的理由。`Display` 写成 `kind value`,直接接在 `escalate_impact|` 后面,
+/// 界面按 kind 措辞
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Hold {
+ Contradiction(String),
+ Derived(i64),
+ Answered(i64),
+}
+
+impl std::fmt::Display for Hold {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Hold::Contradiction(p) => write!(f, "contradiction {p}"),
+ Hold::Derived(n) => write!(f, "derived {n}"),
+ Hold::Answered(n) => write!(f, "answered {n}"),
+ }
+ }
+}
+
+impl Hold {
+ /// 写给 `agent_decisions.reason` 的一句:人在 Agent 队列里看到 agent 为什么没动手
+ pub fn explain(&self) -> String {
+ match self {
+ Hold::Contradiction(p) => {
+ format!("merging would put two \"{p}\" facts on one entity")
+ }
+ Hold::Derived(n) => format!("{n} derived facts rest on one side"),
+ Hold::Answered(n) => format!("one side was named in {n} answers"),
+ }
+ }
+}
+
+/// 这一次合并该不该留给人。矛盾最先说——它会立刻开出违规;其次派生,其次答案。
+/// 什么都不牵动就是 None:把握够就照旧自动
+pub fn hold(impact: &Impact) -> Option<Hold> {
+ if let Some(p) = impact.contradictions.first() {
+ return Some(Hold::Contradiction(p.clone()));
+ }
+ if impact.derived > 0 {
+ return Some(Hold::Derived(impact.derived));
+ }
+ if impact.answered > 0 {
+ return Some(Hold::Answered(impact.answered));
+ }
+ None
+}
+
+/// 取一对实体合并会牵动什么。三条查询,只在裁决器有把握要合的时候才跑。
+///
+/// 写路径的守卫看的是「当前那一行」(`invalidated_at IS NULL`),与 `resolve_mention`
+/// 数度数一个写法;不走记录轴谓词——修正永远发生在现在(0019)
+pub async fn impact_of(pool: &PgPool, kb_id: Uuid, a: Uuid, b: Uuid) -> AppResult<Impact> {
+ // 与一致性检查同一个口径(`too_many`):只看实体宾语的边,不看时间——它报的
+ // 正是合并之后会报的那一条
+ let contradictions: Vec<String> = sqlx::query_scalar(
+ "SELECT DISTINCT r.label
+ FROM facts x
+ JOIN facts y ON y.predicate_id = x.predicate_id AND y.kb_id = x.kb_id
+ JOIN relation_types r ON r.id = x.predicate_id
+ WHERE x.kb_id = $1
+ AND x.invalidated_at IS NULL AND y.invalidated_at IS NULL
+ AND x.object_id IS NOT NULL AND y.object_id IS NOT NULL
+ AND ((r.functional AND x.subject_id = $2 AND y.subject_id = $3
+ AND x.object_id <> y.object_id)
+ OR (r.inverse_functional AND x.object_id = $2 AND y.object_id = $3
+ AND x.subject_id <> y.subject_id))
+ ORDER BY r.label",
+ )
+ .bind(kb_id)
+ .bind(a)
+ .bind(b)
+ .fetch_all(pool)
+ .await?;
+
+ let derived: i64 = sqlx::query_scalar(
+ "SELECT count(*) FROM derived_facts d
+ WHERE d.kb_id = $1 AND d.invalidated_at IS NULL
+ AND (d.subject_id IN ($2, $3) OR d.object_id IN ($2, $3))",
+ )
+ .bind(kb_id)
+ .bind(a)
+ .bind(b)
+ .fetch_one(pool)
+ .await?;
+
+ // `resolved` 是每一轮回答认下的实体(id、名字、类型);被认过就是被问过
+ let answered: i64 = sqlx::query_scalar(
+ "SELECT count(*) FROM conversation_messages m
+ JOIN conversations c ON c.id = m.conversation_id
+ WHERE c.kb_id = $1 AND m.role = 'assistant'
+ AND EXISTS (SELECT 1 FROM jsonb_array_elements(m.resolved) e
+ WHERE e->>'id' IN ($2, $3))",
+ )
+ .bind(kb_id)
+ .bind(a.to_string())
+ .bind(b.to_string())
+ .fetch_one(pool)
+ .await?;
+
+ Ok(Impact {
+ contradictions,
+ derived,
+ answered,
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn nothing_touched_means_no_hold() {
+ assert_eq!(hold(&Impact::default()), None);
+ }
+
+ #[test]
+ fn a_contradiction_speaks_before_anything_else() {
+ let i = Impact {
+ contradictions: vec!["CEO of".into(), "headquartered in".into()],
+ derived: 4,
+ answered: 2,
+ };
+ assert_eq!(hold(&i), Some(Hold::Contradiction("CEO of".into())));
+ assert_eq!(hold(&i).unwrap().to_string(), "contradiction CEO of");
+ }
+
+ #[test]
+ fn derived_then_answered() {
+ let i = Impact {
+ contradictions: vec![],
+ derived: 3,
+ answered: 1,
+ };
+ assert_eq!(hold(&i), Some(Hold::Derived(3)));
+ let i = Impact { derived: 0, ..i };
+ assert_eq!(hold(&i), Some(Hold::Answered(1)));
+ assert_eq!(Hold::Answered(1).to_string(), "answered 1");
+ assert_eq!(
+ Hold::Contradiction("CEO of".into()).explain(),
+ "merging would put two \"CEO of\" facts on one entity"
+ );
+ }
+}
diff --git a/crates/utopia-store/src/lib.rs b/crates/utopia-store/src/lib.rs
index 26758b3b..332c6a06 100644
--- a/crates/utopia-store/src/lib.rs
+++ b/crates/utopia-store/src/lib.rs
@@ -10,6 +10,7 @@ pub mod conversations;
pub mod datasources;
pub mod db;
pub mod documents;
+pub mod execution_gate;
pub mod export;
pub mod extraction_drops;
pub mod governance;
diff --git a/crates/utopia-store/tests/an_automatic_merge_is_gated_by_what_it_can_undo.rs b/crates/utopia-store/tests/an_automatic_merge_is_gated_by_what_it_can_undo.rs
new file mode 100644
index 00000000..6cd4d53b
--- /dev/null
+++ b/crates/utopia-store/tests/an_automatic_merge_is_gated_by_what_it_can_undo.rs
@@ -0,0 +1,232 @@
+//! 执行闸门(0027):一次自动合并能不能落地,看它撤得回什么。打在真库上。
+//!
+//! 三种会离开图的东西,各造一个最小的例子,再各撤一次,证明闸门看的是「现在」:
+//! - **矛盾**:两边各持一条同一个 functional 谓词、指向不同实体的事实——合了就是一条
+//! `functional` 违规。指向同一个实体的不算;作废了的不算
+//! - **派生**:任一边参与的、还成立的派生事实——合并改前提,派生会被重写
+//! - **回答**:任一边在对话里被认过——它是人在问的东西
+//!
+//! 什么都不牵动的一对,闸门不拦:把握够就照旧自动
+
+use sqlx::PgPool;
+use utopia_store::execution_gate::{hold, impact_of, Hold};
+use uuid::Uuid;
+
+struct Fixture {
+ org: Uuid,
+ kb: Uuid,
+ user: Uuid,
+ ceo_of: Uuid,
+ part_of: Uuid,
+ a: Uuid,
+ b: Uuid,
+ c1: Uuid,
+ c2: Uuid,
+}
+
+async fn seed(pool: &PgPool) -> anyhow::Result<Fixture> {
+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let (user, company) = (Uuid::now_v7(), Uuid::now_v7());
+ let (ceo_of, part_of) = (Uuid::now_v7(), Uuid::now_v7());
+ let (a, b, c1, c2) = (
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ );
+
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'gate-test')")
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'gate-test')")
+ .bind(ws)
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'gate-test')",
+ )
+ .bind(kb)
+ .bind(ws)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO users (id, org_id, email, display_name, password_hash)
+ VALUES ($1, $2, $3, 'Asker', 'x')",
+ )
+ .bind(user)
+ .bind(org)
+ .bind(format!("asker-{}@test.local", user.simple()))
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'company', 'Company')",
+ )
+ .bind(company)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO relation_types (id, kb_id, key, label, functional)
+ VALUES ($1, $2, 'ceo_of', 'CEO of', TRUE)",
+ )
+ .bind(ceo_of)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO relation_types (id, kb_id, key, label) VALUES ($1, $2, 'part_of', 'part of')",
+ )
+ .bind(part_of)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ for (id, name) in [(a, "Acme"), (b, "Acme Corp"), (c1, "Alice"), (c2, "Bob")] {
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, type_id, canonical_name) VALUES ($1, $2, $3, $4)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(company)
+ .bind(name)
+ .execute(pool)
+ .await?;
+ }
+ Ok(Fixture {
+ org,
+ kb,
+ user,
+ ceo_of,
+ part_of,
+ a,
+ b,
+ c1,
+ c2,
+ })
+}
+
+async fn fact(pool: &PgPool, kb: Uuid, s: Uuid, p: Uuid, o: Uuid) -> anyhow::Result<Uuid> {
+ let id = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id)
+ VALUES ($1, $2, $3, $4, $5)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(s)
+ .bind(p)
+ .bind(o)
+ .execute(pool)
+ .await?;
+ Ok(id)
+}
+
+#[tokio::test]
+async fn a_merge_that_would_leave_the_graph_is_held() -> 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 none = impact_of(&pool, f.kb, f.a, f.b).await?;
+ assert_eq!(hold(&none), None, "两边空空的一对,闸门不该拦:{none:?}");
+
+ // 矛盾:a 的 CEO 是 Alice,b 的 CEO 是 Bob。合了就是一个实体两个 CEO
+ fact(&pool, f.kb, f.a, f.ceo_of, f.c1).await?;
+ let clash = fact(&pool, f.kb, f.b, f.ceo_of, f.c2).await?;
+ let i = impact_of(&pool, f.kb, f.a, f.b).await?;
+ assert_eq!(i.contradictions, vec!["CEO of".to_string()]);
+ assert_eq!(hold(&i), Some(Hold::Contradiction("CEO of".into())));
+ // 反过来问也一样
+ let i = impact_of(&pool, f.kb, f.b, f.a).await?;
+ assert_eq!(hold(&i), Some(Hold::Contradiction("CEO of".into())));
+
+ // 撤掉 b 的那条:矛盾没了。再给 b 一条指向同一个 Alice 的:同一个值不是矛盾
+ sqlx::query("UPDATE facts SET invalidated_at = now() WHERE id = $1")
+ .bind(clash)
+ .execute(&pool)
+ .await?;
+ fact(&pool, f.kb, f.b, f.ceo_of, f.c1).await?;
+ let i = impact_of(&pool, f.kb, f.a, f.b).await?;
+ assert!(i.contradictions.is_empty(), "作废的与同值的都不算:{i:?}");
+ assert_eq!(hold(&i), None);
+
+ // 派生:一条靠着 a 推出来的还成立的派生
+ let rule = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO rules (id, kb_id, predicate_id, kind) VALUES ($1, $2, $3, 'transitive')",
+ )
+ .bind(rule)
+ .bind(f.kb)
+ .bind(f.part_of)
+ .execute(&pool)
+ .await?;
+ let derived = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO derived_facts (id, kb_id, subject_id, predicate_id, object_id, rule_id)
+ VALUES ($1, $2, $3, $4, $5, $6)",
+ )
+ .bind(derived)
+ .bind(f.kb)
+ .bind(f.a)
+ .bind(f.part_of)
+ .bind(f.c2)
+ .bind(rule)
+ .execute(&pool)
+ .await?;
+ let i = impact_of(&pool, f.kb, f.a, f.b).await?;
+ assert_eq!(i.derived, 1);
+ assert_eq!(hold(&i), Some(Hold::Derived(1)));
+ sqlx::query("UPDATE derived_facts SET invalidated_at = now() WHERE id = $1")
+ .bind(derived)
+ .execute(&pool)
+ .await?;
+ assert_eq!(
+ hold(&impact_of(&pool, f.kb, f.a, f.b).await?),
+ None,
+ "推翻了的派生不算"
+ );
+
+ // 回答:b 在一轮回答里被认过。人的那一轮与认了别人的那一轮都不算
+ let conv = Uuid::now_v7();
+ sqlx::query("INSERT INTO conversations (id, kb_id, user_id) VALUES ($1, $2, $3)")
+ .bind(conv)
+ .bind(f.kb)
+ .bind(f.user)
+ .execute(&pool)
+ .await?;
+ for (role, who) in [("user", f.b), ("assistant", f.c2), ("assistant", f.b)] {
+ sqlx::query(
+ "INSERT INTO conversation_messages (id, conversation_id, role, content, resolved)
+ VALUES ($1, $2, $3, 'hi', $4)",
+ )
+ .bind(Uuid::now_v7())
+ .bind(conv)
+ .bind(role)
+ .bind(serde_json::json!([{ "id": who.to_string(), "name": "x", "type": null }]))
+ .execute(&pool)
+ .await?;
+ }
+ let i = impact_of(&pool, f.kb, f.a, f.b).await?;
+ assert_eq!(i.answered, 1, "只数认了 a 或 b 的那些回答:{i:?}");
+ assert_eq!(hold(&i), Some(Hold::Answered(1)));
+ assert_eq!(hold(&i).unwrap().to_string(), "answered 1");
+
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ sqlx::query("DELETE FROM users WHERE id = $1")
+ .bind(f.user)
+ .execute(&pool)
+ .await?;
+ let gone = sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(f.org)
+ .execute(&pool)
+ .await?;
+ assert_eq!(gone.rows_affected(), 1, "一次性 org 没删掉");
+ Ok(())
+}
diff --git a/docs/decisions/0027-an-automatic-merge-is-gated-by-what-it-can-undo.md b/docs/decisions/0027-an-automatic-merge-is-gated-by-what-it-can-undo.md
new file mode 100644
index 00000000..7b66687e
--- /dev/null
+++ b/docs/decisions/0027-an-automatic-merge-is-gated-by-what-it-can-undo.md
@@ -0,0 +1,56 @@
+# 0027 · An automatic merge is gated by what it can undo
+
+- **Status**: Implemented · `execution_gate` in the store: `impact_of` reads what a merge would touch, `hold` is the pure judgement; the batch adjudicator and the governor both ask it before an automatic merge, and a held pair goes to a person as `escalate_impact|<kind> <value>`; the governor records its look as a proposal whose reason begins `held for a person` · exports and a per-deployment opt-in stay open · the roadmap's execution gate for agents' calls is this module's next caller
+- **Written**: 2026-09-08 (conventions in the [README](README.md))
+- **Related**: #357 asked for it. [0019](0019-the-second-clock-can-be-rewound.md) made a merge undoable inside the graph, which is what makes inside and outside different things. The 0025 gate (confidence, precedents, two hard rules) is unchanged; this one sits after it. The things a merge can reach are [0002](0002-reasoning-engine.md)'s derivations, [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md)'s violations and the alerts of [0005](0005-alert-center.md), the answers of the chat, and the exports of [0020](0020-an-auditor-reads-it-without-us.md).
+
+> The adjudicator is 0.93 sure that "Acme" and "Acme Corp" are one company, and it is right about that often enough that 0.8 is the bar. It merges them. The consistency check runs and finds one company with two CEOs; the reasoning engine rewrites what "part of Acme" implies; someone asks the chat who runs Acme and gets a cited answer. On Monday a person reverts the merge. The graph is as it was. The violation that was looked at, the derivations that were read and the answer that was given are not.
+
+## What was there
+
+`AUTO_CONF = 0.8` in the adjudicator, 0.85 and 0.75 in the governor, applied to every pair regardless of what the merge goes on to touch. Confidence was the only axis. Rollback is real but stops at the graph: `revert_merge` moves the facts back and `entity_merges` keeps both clocks, so the graph as it stood before the merge can be read again. Anything the wrong merge caused while it was live cannot be recalled: a derivation drawn on it, a violation it opened, an export it entered, an answer it was cited in. Undo restores the graph, not the world the graph was read into.
+
+## Decisions
+
+### 1. A merge is gated on what it would send out of the graph
+
+Three things, checked in this order, and any one of them holds the pair for a person whatever the confidence:
+
+- **A contradiction.** The two sides each hold a fact under the same `functional` predicate pointing at different entities (or, for `inverse_functional`, are each pointed at by different subjects). Merged, that is one entity with two values, which the consistency check reports as a `functional` violation the next time it runs. The check is the first place a merge leaves the graph, so it is the first thing asked.
+- **A derivation.** Any derived fact that still stands and has either side as subject or object. The merge changes its premises and the engine rewrites it; what was read from the old row is gone.
+- **An answer.** Either side was recognised in an assistant turn (`conversation_messages.resolved`, the entities a turn settled on). That entity is something people ask about, and a wrong merge enters the next answer.
+
+Nothing touched, and the confidence bar decides as before.
+
+### 2. Only merges
+
+A keep costs nothing to undo: the next merge is the undo, and nothing outside the graph is told that two things were kept apart. The gate does not look at keeps.
+
+### 3. One gate, two callers, a third on the roadmap
+
+`execution_gate::hold` is a pure function over an `Impact`; `impact_of` is three queries, run only when a decider is about to merge on its own. The batch adjudicator and the governor call the same two functions. The roadmap's execution gate, "checking an agent's calls against ontology rules and symbolic logic", is this gate pointed at someone else's writes rather than our own, and joins this module rather than growing beside it.
+
+### 4. A hold is a reason, not a doubt
+
+The queue reason is `escalate_impact|<kind> <value>`: `contradiction CEO of`, `derived 12`, `answered 3`. The card says "Held for a person; the merge would not stay in the graph — it would put two "CEO of" facts on one entity", so nobody reads it as the adjudicator being unsure. In the governor the look is still recorded, as a proposal whose reason begins `held for a person: …`, with the model's own reason after it; the person answers it like any other proposal.
+
+### 5. The same yardstick as the consistency check
+
+The contradiction query looks at entity-object edges only, ignores time and ignores literal values, because that is what `too_many` in the reasoning crate looks at. A stricter predictor would hold pairs for violations the check would never open; a looser one would let through the ones it would.
+
+## What a reader sees
+
+A pair the adjudicator would have merged shows in Duplicates with the held reason in place of a confidence. In the Agent queue the same pair is a proposal that begins "held for a person". Nothing changes for pairs that touch nothing.
+
+## Dead ends
+
+- **Exports as a hold.** `kb.exported` is in the ledger, but an export is of the base, not of the pair: holding every merge in a base that has ever been exported is a switch, not a gate, and the switch already exists (governance, or the adjudicator's own). A per-deployment opt-in, "automatic merges may leave the system", waits until someone asks for it.
+- **Size as impact.** The number of facts that would move says how visible a mistake is, not whether it comes back; `revert_merge` returns a hub as fully as a shell. And the sample 0026 keeps for people measures how often the machine is wrong, which is the number size would have been a proxy for.
+- **A higher bar instead of a hold.** 0.95 for pairs with derivations, say. A held pair costs a person one look; a merge that leaves the graph costs a revert that does not fully revert. The asymmetry is the whole point of the issue.
+- **Time-aware contradictions.** Two CEOs in different years are not a contradiction in the world, but the check does not know that yet either; when it does, this query follows it (decision 5).
+
+## Open questions
+
+- **Alerts as such.** The alert center's kinds are about pipelines and switches, not the graph; the path from a merge to an alert runs through the consistency check, which is why the contradiction stands in for it. If a direct path appears, it joins `impact_of`.
+- **Answers that cited a side without resolving it.** `sources` carries chunks and facts; `resolved` is the honest entity-level signal today.
+- **How often it holds.** Run the bench with reasoning on and count `escalate_impact`; if derivations hold most of a base, the derived rule wants a finer question than "any".
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 1a0fce9c..d4212170 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -48,8 +48,9 @@ The test for writing one: if someone (including us) looks at a piece of code in
| 0022 | [An unknown date is not an open one](0022-an-unknown-date-is-not-an-open-one.md) | Implemented in two cuts (#394 and the derived cut) · `world_axis` predicate beside `record_axis`, `facts.attested_at` anchors a missing start or an undated end at the document that attests it, every read and both client filters on the read interval, an undated ending closes the dated row it ends, derived rows intersect premise intervals as read and carry no precision on an anchored bound · two anchors (`attested_from` / `attested_to`), so a bare open row closes too (#393) |
| 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 |
-| 0026 | [A decision records why](0026-a-decision-records-why.md) | Implemented · `resolution_reviews.rationale` and `why` on the ledger event from every human decide path, precedents quote it into the prompt and the `ledger_search` tool, the batch adjudicator reads precedents and keys its cache on them, one confident pair in ten goes to a person anyway (`escalate_sample`), the model's own why is kept beside machine decisions · the impact gate (#357) and the investigating adjudicator (#358) follow |
| 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` |
+| 0026 | [A decision records why](0026-a-decision-records-why.md) | Implemented · `resolution_reviews.rationale` and `why` on the ledger event from every human decide path, precedents quote it into the prompt and the `ledger_search` tool, the batch adjudicator reads precedents and keys its cache on them, one confident pair in ten goes to a person anyway (`escalate_sample`), the model's own why is kept beside machine decisions · the impact gate (#357) and the investigating adjudicator (#358) follow |
+| 0027 | [An automatic merge is gated by what it can undo](0027-an-automatic-merge-is-gated-by-what-it-can-undo.md) | Implemented · `execution_gate` in the store, asked by the batch adjudicator and the governor before an automatic merge: a contradiction the consistency check would open, a derivation resting on either side, or an answer that named either side holds the pair for a person as `escalate_impact` whatever the confidence · keeps are not gated · exports and a per-deployment opt-in stay open |
| 0031 | [An event holds at the moment it names](0031-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
diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.ts
index 3be258ce..300301f4 100644
--- a/web/src/i18n/en.ts
+++ b/web/src/i18n/en.ts
@@ -1639,6 +1639,8 @@ export const en = {
escalate_unsure: "The adjudicator was not confident enough",
/* 抽给人看的一份(0026):机器有把握也不动手,detail 是它本来的答案 */
escalate_sample: "Sampled for a person; the adjudicator was confident",
+ /* 执行闸门(0027):合并会立刻送出图外的东西,把握再高也留给人 */
+ escalate_impact: "Held for a person; the merge would not stay in the graph",
proposed: "The agent looked and left a proposal",
governed: "Decided by the agent from precedent",
namesake: "Two entities with this name in one document",
@@ -1651,6 +1653,12 @@ export const en = {
auto_merged: "Merged by the AI adjudicator",
kept_apart: "The AI adjudicator judged these different",
} as Record<string, string>,
+ /** 闸门留下的原因,按 kind 措辞;value 是谓词标签或一个数 */
+ impact: {
+ contradiction: (p: string) => `it would put two “${p}” facts on one entity`,
+ derived: (n: string) => `${n} derived facts rest on one side`,
+ answered: (n: string) => `one side was named in ${n} answers`,
+ } as Record<string, (v: string) => string>,
duplicates: "Possible duplicates",
duplicatesHint:
"Same name, different context. The AI adjudicates clear cases in the background; the rest wait for you. Merging is always reversible.",
diff --git a/web/src/i18n/zh.ts b/web/src/i18n/zh.ts
index 2d3cd984..230b8670 100644
--- a/web/src/i18n/zh.ts
+++ b/web/src/i18n/zh.ts
@@ -1435,6 +1435,7 @@ export const zh: Strings = {
escalate_entity_changed: "裁决过程中实体发生了变化",
escalate_unsure: "裁决的把握不够",
escalate_sample: "抽给人看的一份;裁决器本有把握",
+ escalate_impact: "留给人;这次合并不会只留在图里",
proposed: "agent 看过了,留了一条建议",
governed: "agent 按先例裁的",
namesake: "同一篇文档里有两个同名实体",
@@ -1445,6 +1446,11 @@ export const zh: Strings = {
auto_merged: "AI 裁决已自动合并",
kept_apart: "AI 裁决认为不是同一个",
} as Record<string, string>,
+ impact: {
+ contradiction: (p) => `合了会让一个实体有两条“${p}”`,
+ derived: (n) => `有 ${n} 条派生事实靠着一边`,
+ answered: (n) => `有一边在 ${n} 个回答里被点过名`,
+ } as Record<string, (v: string) => string>,
duplicates: "可能重复",
duplicatesHint:
"同名,但上下文不同。AI 在后台裁决明确的情形;其余等你。合并永远可撤销。",
diff --git a/web/src/pages/Review.tsx b/web/src/pages/Review.tsx
index 08613ad2..3b9802ef 100644
--- a/web/src/pages/Review.tsx
+++ b/web/src/pages/Review.tsx
@@ -53,6 +53,12 @@ function escalationText(reason: string): string {
const [code, detail] = reason.split("|");
const worded = S.review.escalated[code];
if (!worded) return reason;
+ // 执行闸门(0027)留下的:detail 是 `kind value`,按 kind 措辞,不把裸代码给人看
+ if (code === "escalate_impact" && detail) {
+ const [kind, ...rest] = detail.split(" ");
+ const said = S.review.impact[kind]?.(rest.join(" "));
+ if (said) return `${worded} — ${said}`;
+ }
return detail ? S.errDetail(worded, detail) : worded;
}