Skip to content

World's first open-source enterprise world model.

Remember approved property examples so definition edits expose alignment regressions. (#1178)

Virtue0396880aa607dab
diff --git a/crates/utopia-cli/src/main.rs b/crates/utopia-cli/src/main.rs
index 7f5ce53f..45c8d256 100644
--- a/crates/utopia-cli/src/main.rs
+++ b/crates/utopia-cli/src/main.rs
@@ -82,7 +82,7 @@ struct ManifestDataDir {
/// not a side effect of a code change.
// 是迁移文件的**个数**,不是最大的编号(守卫 `schema_version_policy_compares_against_current`
// 按个数比):编号有空缺时两者不同——0071 由一个开放 PR 占着,0072 先落,个数是 71
-const CURRENT_SCHEMA_VERSION: u32 = 97;
+const CURRENT_SCHEMA_VERSION: u32 = 98;
fn main() -> anyhow::Result<()> {
dotenvy::dotenv().ok();
diff --git a/crates/utopia-server/src/api/mod.rs b/crates/utopia-server/src/api/mod.rs
index ba7cd2d2..c3627f07 100644
--- a/crates/utopia-server/src/api/mod.rs
+++ b/crates/utopia-server/src/api/mod.rs
@@ -15,6 +15,7 @@ mod mapping_routes;
mod mcp;
mod members_routes;
mod oidc_routes;
+mod ontology_regression_routes;
pub(crate) mod ontology_routes;
mod question_routes;
mod review_routes;
@@ -286,6 +287,10 @@ pub fn router(state: AppState, cfg: &AppConfig) -> Router {
get(documents_routes::extraction_drops),
)
.route("/kbs/{id}/ontology", get(ontology_routes::get))
+ .route(
+ "/kbs/{id}/ontology/regressions",
+ post(ontology_regression_routes::create),
+ )
// 业务规则(0021):读规则要 Viewer,写要 Editor
.route(
"/kbs/{id}/rules",
diff --git a/crates/utopia-server/src/api/ontology_regression_routes.rs b/crates/utopia-server/src/api/ontology_regression_routes.rs
new file mode 100644
index 00000000..1d933a72
--- /dev/null
+++ b/crates/utopia-server/src/api/ontology_regression_routes.rs
@@ -0,0 +1,45 @@
+//! A case records a person's expected interpretation; alignment supplies its result.
+use crate::{auth::AuthUser, error::ApiResult, state::AppState};
+use axum::{
+ extract::{Path, State},
+ http::StatusCode,
+ Json,
+};
+use serde::Deserialize;
+use serde_json::{json, Value};
+use utopia_core::models::Role;
+use utopia_store::{access::require_kb, ontology_regressions as cases};
+use uuid::Uuid;
+
+#[derive(Deserialize)]
+pub struct Create {
+ pub statement_id: Uuid,
+ pub relation_type_id: Uuid,
+ pub direction: String,
+}
+
+pub async fn create(
+ State(state): State<AppState>,
+ AuthUser(user): AuthUser,
+ Path(kb): Path<Uuid>,
+ Json(req): Json<Create>,
+) -> ApiResult<(StatusCode, Json<Value>)> {
+ require_kb(&state.pool, &user, kb, Role::Editor).await?;
+ let id = cases::add(
+ &state.pool,
+ kb,
+ cases::NewCase {
+ statement_id: req.statement_id,
+ expected_property_id: req.relation_type_id,
+ expected_direction: &req.direction,
+ created_by: user.id,
+ origin: "person",
+ },
+ )
+ .await?;
+ Ok((StatusCode::CREATED, Json(json!({"id": id}))))
+}
+
+#[cfg(test)]
+#[path = "ontology_regression_routes_tests.rs"]
+mod tests;
diff --git a/crates/utopia-server/src/api/ontology_regression_routes_tests.rs b/crates/utopia-server/src/api/ontology_regression_routes_tests.rs
new file mode 100644
index 00000000..7d2805f1
--- /dev/null
+++ b/crates/utopia-server/src/api/ontology_regression_routes_tests.rs
@@ -0,0 +1,152 @@
+use axum::{
+ body::{to_bytes, Body},
+ http::{Request, StatusCode},
+ Router,
+};
+use serde_json::json;
+use sqlx::PgPool;
+use std::sync::Arc;
+use tower::ServiceExt;
+use utopia_store::graph;
+use uuid::Uuid;
+
+async fn post(
+ app: &Router,
+ kb: Uuid,
+ token: &str,
+ statement: Uuid,
+ property: Uuid,
+) -> anyhow::Result<axum::response::Response> {
+ Ok(app
+ .clone()
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri(format!("/api/v1/kbs/{kb}/ontology/regressions"))
+ .header("content-type", "application/json")
+ .header("authorization", format!("Bearer {token}"))
+ .body(Body::from(
+ json!({
+ "statement_id": statement,
+ "relation_type_id": property,
+ "direction": "forward"
+ })
+ .to_string(),
+ ))?,
+ )
+ .await?)
+}
+
+#[tokio::test]
+async fn editor_adds_regression_case_while_viewer_and_cross_kb_statement_are_rejected(
+) -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ utopia_store::db::migrate(&pool).await?;
+ let (org, workspace, kb, foreign_kb, editor, viewer, subject, object, foreign_entity, property) = (
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ );
+ // Only locally generated UUIDs are interpolated into this fixture.
+ sqlx::raw_sql(&format!(
+ r#"
+ INSERT INTO organizations(id,name) VALUES ('{org}','case-route-test');
+ INSERT INTO workspaces(id,org_id,name) VALUES ('{workspace}','{org}','case-route-test');
+ INSERT INTO knowledge_bases(id,workspace_id,name,visibility) VALUES
+ ('{kb}','{workspace}','case-route-test','restricted'),
+ ('{foreign_kb}','{workspace}','foreign-case-route-test','restricted');
+ INSERT INTO users(id,org_id,email,password_hash,display_name) VALUES
+ ('{editor}','{org}','{editor}@example.test','unused','Editor'),
+ ('{viewer}','{org}','{viewer}@example.test','unused','Viewer');
+ INSERT INTO kb_members(kb_id,user_id,role) VALUES
+ ('{kb}','{editor}','editor'), ('{kb}','{viewer}','viewer');
+ INSERT INTO entities(id,kb_id,canonical_name) VALUES
+ ('{subject}','{kb}','Alice'), ('{object}','{kb}','Acme'),
+ ('{foreign_entity}','{foreign_kb}','Foreign entity');
+ INSERT INTO relation_types(id,kb_id,key,label,kind) VALUES
+ ('{property}','{kb}','worksFor','works for','relation');
+ "#
+ ))
+ .execute(&pool)
+ .await?;
+ let result = async {
+ let statement = graph::insert_open_statement(
+ &pool,
+ kb,
+ subject,
+ "works for",
+ graph::FactObject::Entity(object),
+ None,
+ 1.0,
+ )
+ .await?
+ .0;
+ let foreign_statement = graph::insert_open_statement(
+ &pool,
+ foreign_kb,
+ foreign_entity,
+ "refers to",
+ graph::FactObject::Entity(foreign_entity),
+ None,
+ 1.0,
+ )
+ .await?
+ .0;
+ let directory = tempfile::tempdir()?;
+ let config = utopia_core::config::AppConfig {
+ data_dir: directory.path().to_string_lossy().into_owned(),
+ ..Default::default()
+ };
+ let search = Arc::new(utopia_search::SearchIndex::open(
+ &directory.path().join("search"),
+ )?);
+ let state = crate::state::AppState::new(pool.clone(), &config, search, "test-only".into());
+ let editor_token = crate::auth::issue_token(&state, editor)?;
+ let viewer_token = crate::auth::issue_token(&state, viewer)?;
+ let app = crate::api::router(state, &config);
+
+ let response = post(&app, kb, &editor_token, statement, property).await?;
+ anyhow::ensure!(response.status() == StatusCode::CREATED);
+ let body: serde_json::Value =
+ serde_json::from_slice(&to_bytes(response.into_body(), 65536).await?)?;
+ let id: Uuid = serde_json::from_value(body["id"].clone())?;
+ let saved: bool = sqlx::query_scalar(
+ "SELECT EXISTS(SELECT 1 FROM ontology_regression_cases WHERE id=$1 AND kb_id=$2
+ AND statement_id=$3 AND expected_property_id=$4 AND expected_direction='forward'
+ AND created_by=$5 AND origin='person')",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(statement)
+ .bind(property)
+ .bind(editor)
+ .fetch_one(&pool)
+ .await?;
+ anyhow::ensure!(saved);
+
+ for (token, statement, expected) in [
+ (&viewer_token, statement, StatusCode::FORBIDDEN),
+ (&editor_token, foreign_statement, StatusCode::NOT_FOUND),
+ ] {
+ let response = post(&app, kb, token, statement, property).await?;
+ anyhow::ensure!(response.status() == expected);
+ }
+ anyhow::Ok(())
+ }
+ .await;
+ sqlx::query("DELETE FROM organizations WHERE id=$1")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ result
+}
diff --git a/crates/utopia-server/src/ontology_agent.rs b/crates/utopia-server/src/ontology_agent.rs
index 5c777e76..979cba57 100644
--- a/crates/utopia-server/src/ontology_agent.rs
+++ b/crates/utopia-server/src/ontology_agent.rs
@@ -51,6 +51,8 @@ fn shape_of(sig: &PhraseSignature) -> Value {
"subject": sig.subject_type_key,
"object": sig.object_type_key,
"value": sig.object_is_value,
+ // Proposals show the first example; keep its identity from the same read.
+ "example_statement_ids": sig.example_statement_ids.first().into_iter().collect::<Vec<_>>(),
})
}
@@ -1000,7 +1002,7 @@ pub async fn adopt(
tracing::warn!(%kb_id, error = %e, "采纳后本体向量没补上,对齐的短名单看不见新元素");
}
}
- utopia_store::ontology::decide_proposal(pool, kb_id, section, key, "adopted", actor).await?;
+ finish_adoption(pool, kb_id, &p, id, actor).await?;
if edited {
utopia_store::ontology::mark_proposal_edited(pool, kb_id, section, key).await?;
}
@@ -1018,6 +1020,78 @@ pub async fn adopt(
Ok(id)
}
+async fn finish_adoption(
+ pool: &sqlx::PgPool,
+ kb_id: Uuid,
+ proposal: &utopia_store::ontology::StoredProposal,
+ property_id: Uuid,
+ actor: Uuid,
+) -> Result<(), AppError> {
+ let mut examples = Vec::new();
+ let property = matches!(
+ proposal.section.as_str(),
+ "relation_types" | "attribute_types"
+ ) || (proposal.section == "map_to"
+ && proposal.payload.get("kind").and_then(Value::as_str) != Some("class"));
+ if property {
+ for shape in proposal
+ .signatures
+ .get("phrases")
+ .and_then(Value::as_array)
+ .into_iter()
+ .flatten()
+ {
+ let ids = match shape.get("example_statement_ids") {
+ Some(ids) => serde_json::from_value::<Vec<Uuid>>(ids.clone()).map_err(|_| {
+ AppError::invalid("invalid_examples", "Invalid proposal statement identities.")
+ })?,
+ None => Vec::new(),
+ };
+ let direction = match shape.get("direction").and_then(Value::as_str) {
+ Some("reverse") => "reverse",
+ _ => "forward",
+ };
+ examples.extend(ids.into_iter().map(|statement| (statement, direction)));
+ }
+ }
+ let mut tx = pool.begin().await?;
+ let open: Option<Uuid> = sqlx::query_scalar(
+ "SELECT id FROM ontology_proposals WHERE kb_id=$1 AND section=$2 AND key=$3 AND status='open' FOR UPDATE"
+ ).bind(kb_id).bind(&proposal.section).bind(&proposal.key).fetch_optional(&mut *tx).await?;
+ if open.is_none() {
+ return Err(AppError::NotFound);
+ }
+ for (statement_id, direction) in examples {
+ // Removed examples cannot be checked; never substitute another statement.
+ let live: Option<Uuid> = sqlx::query_scalar("SELECT id FROM facts WHERE kb_id=$1 AND id=$2 AND layer='open' AND invalidated_at IS NULL FOR SHARE")
+ .bind(kb_id).bind(statement_id).fetch_optional(&mut *tx).await?;
+ if live.is_none() {
+ continue;
+ }
+ utopia_store::ontology_regressions::add_on(
+ &mut tx,
+ kb_id,
+ utopia_store::ontology_regressions::NewCase {
+ statement_id,
+ expected_property_id: property_id,
+ expected_direction: direction,
+ created_by: actor,
+ origin: "adoption",
+ },
+ )
+ .await?;
+ }
+ sqlx::query(
+ "UPDATE ontology_proposals SET status='adopted',decided_by=$2,decided_at=now() WHERE id=$1",
+ )
+ .bind(open)
+ .bind(actor)
+ .execute(&mut *tx)
+ .await?;
+ tx.commit().await?;
+ Ok(())
+}
+
/// map_to 的采纳:目标是属性,提案里的每条形状写成人的绑定(属性 + 方向),投影跟着
/// 排(同审核页的 `decide_alignment_phrase`);目标是类,每个类别词归到它。返回目标的 id
async fn adopt_map_to(
diff --git a/crates/utopia-server/src/ontology_agent_tests.rs b/crates/utopia-server/src/ontology_agent_tests.rs
index fa80992e..ac822692 100644
--- a/crates/utopia-server/src/ontology_agent_tests.rs
+++ b/crates/utopia-server/src/ontology_agent_tests.rs
@@ -272,6 +272,17 @@ async fn an_unbound_shape_becomes_a_proposal_that_serves_a_question_and_adoption
assert_eq!(p.payload["forms"][0], "founded in");
assert_eq!(p.payload["domains"][0], "organization");
assert_eq!(p.payload["ranges"][0], "place");
+ let example_id: Uuid =
+ serde_json::from_value(p.signatures["phrases"][0]["example_statement_ids"][0].clone())?;
+ let phrase: String = sqlx::query_scalar("SELECT phrase FROM facts WHERE id=$1 AND kb_id=$2")
+ .bind(example_id)
+ .bind(f.kb)
+ .fetch_one(&f.pool)
+ .await?;
+ assert_eq!(
+ phrase, "founded in",
+ "the proposed example has a stable source identity"
+ );
assert_eq!(
p.payload["description"],
"the place where an organization was founded"
@@ -340,6 +351,13 @@ async fn an_unbound_shape_becomes_a_proposal_that_serves_a_question_and_adoption
.fetch_one(&f.pool)
.await?;
assert_eq!(status, "adopted");
+ let cases = utopia_store::ontology_regressions::list(&f.pool, f.kb).await?;
+ assert_eq!(cases.len(), 1);
+ assert_eq!(cases[0].statement_id, example_id);
+ assert_eq!(cases[0].expected_property_id, id);
+ assert_eq!(cases[0].expected_direction, "forward");
+ assert_eq!(cases[0].created_by, Some(f.user));
+ assert_eq!(cases[0].origin, "adoption");
assert!(
utopia_store::jobs::pending_for_kb(&f.pool, "align_phrases", f.kb).await?,
"adoption re-decides the shapes through alignment"
@@ -359,6 +377,46 @@ async fn an_unbound_shape_becomes_a_proposal_that_serves_a_question_and_adoption
matches!(again, Err(AppError::NotFound)),
"a decided proposal is not open: {again:?}"
);
+
+ // Older proposals lack source IDs: adoption succeeds without inventing cases.
+ let mut legacy_shape = p.signatures["phrases"][0].clone();
+ legacy_shape
+ .as_object_mut()
+ .unwrap()
+ .remove("example_statement_ids");
+ utopia_store::ontology::save_agent_proposals(
+ &f.pool,
+ f.kb,
+ &[utopia_store::ontology::AgentProposal {
+ section: "map_to".into(),
+ key: "located_in".into(),
+ payload: json!({"kind":"relation"}),
+ serves: vec![],
+ signatures: json!({"phrases":[legacy_shape]}),
+ }],
+ )
+ .await?;
+ adopt(
+ &f.state,
+ f.kb,
+ "map_to",
+ "located_in",
+ AdoptEdits::default(),
+ f.user,
+ )
+ .await?;
+ assert!(
+ utopia_store::ontology::open_proposal(&f.pool, f.kb, "map_to", "located_in")
+ .await?
+ .is_none()
+ );
+ assert_eq!(
+ utopia_store::ontology_regressions::list(&f.pool, f.kb)
+ .await?
+ .len(),
+ 1,
+ "a proposal without example IDs adds no regression case"
+ );
f.cleanup().await
}
diff --git a/crates/utopia-server/src/phrase_alignment.rs b/crates/utopia-server/src/phrase_alignment.rs
index 63160b2a..c5628045 100644
--- a/crates/utopia-server/src/phrase_alignment.rs
+++ b/crates/utopia-server/src/phrase_alignment.rs
@@ -463,6 +463,9 @@ pub async fn align_phrases_reasking(
reask: u32,
) -> anyhow::Result<()> {
let pool = &state.pool;
+ // Human interpretations are deliberately preserved by alignment. Report that preservation
+ // explicitly even when no model is configured; it is not a fresh semantic judgment.
+ utopia_store::ontology_regressions::record_human(pool, kb_id).await?;
let kb = utopia_store::kbs::get(pool, kb_id).await?;
let settings = utopia_store::settings::get(pool, kb.workspace_id)
.await?
@@ -1289,6 +1292,7 @@ mod tests {
count: 1,
examples: Vec::new(),
quotes: Vec::new(),
+ example_statement_ids: Vec::new(),
}
}
diff --git a/crates/utopia-store/src/export_provenance_integrity.sql b/crates/utopia-store/src/export_provenance_integrity.sql
index 03c34517..e6c85f32 100644
--- a/crates/utopia-store/src/export_provenance_integrity.sql
+++ b/crates/utopia-store/src/export_provenance_integrity.sql
@@ -329,6 +329,18 @@ SELECT edge, kind, COUNT(*) AS rows FROM (
LEFT JOIN relation_types p ON p.id = r.conclude_property_id
WHERE r.kb_id = $1
UNION ALL
+ -- @edge ontology_regression_cases.statement_id -> facts.id
+ SELECT 'regression.statement', 'cross_kb', f.kb_id IS DISTINCT FROM c.kb_id
+ FROM ontology_regression_cases c
+ LEFT JOIN facts f ON f.id = c.statement_id
+ WHERE c.kb_id = $1
+ UNION ALL
+ -- @edge ontology_regression_cases.expected_property_id -> relation_types.id
+ SELECT 'regression.property', 'cross_kb', p.kb_id IS DISTINCT FROM c.kb_id
+ FROM ontology_regression_cases c
+ LEFT JOIN relation_types p ON p.id = c.expected_property_id
+ WHERE c.kb_id = $1
+ UNION ALL
-- @edge phrase_readings.entity_id -> entities.id
-- 读数缓存:答出的实体喂给蕴含——别库的实体等于把别库语义读进本库
SELECT 'reading.entity', 'cross_kb', e.kb_id IS DISTINCT FROM pr.kb_id
diff --git a/crates/utopia-store/src/lib.rs b/crates/utopia-store/src/lib.rs
index 5c869395..0f0c8907 100644
--- a/crates/utopia-store/src/lib.rs
+++ b/crates/utopia-store/src/lib.rs
@@ -31,6 +31,7 @@ pub mod model_limits;
pub mod name_vectors;
pub mod names;
pub mod ontology;
+pub mod ontology_regressions;
pub mod palette;
pub mod paths;
pub mod pending;
diff --git a/crates/utopia-store/src/ontology_regressions.rs b/crates/utopia-store/src/ontology_regressions.rs
new file mode 100644
index 00000000..8dbb1bdd
--- /dev/null
+++ b/crates/utopia-store/src/ontology_regressions.rs
@@ -0,0 +1,188 @@
+//! 0061 cut 2 的第一片:人的例子比较现有对齐账本,不额外调用模型。
+use chrono::{DateTime, Utc};
+use serde::Serialize;
+use sqlx::{PgConnection, PgPool};
+use utopia_core::{AppError, AppResult};
+use uuid::Uuid;
+
+use crate::phrase_bindings::PhraseSignature;
+
+#[derive(Debug, Clone, Serialize, sqlx::FromRow)]
+pub struct Case {
+ pub id: Uuid,
+ pub kb_id: Uuid,
+ pub statement_id: Uuid,
+ pub expected_property_id: Uuid,
+ pub expected_direction: String,
+ pub created_by: Option<Uuid>,
+ pub created_at: DateTime<Utc>,
+ pub origin: String,
+ pub last_checked_at: Option<DateTime<Utc>>,
+ pub last_result: Option<serde_json::Value>,
+}
+
+pub struct NewCase<'a> {
+ pub statement_id: Uuid,
+ pub expected_property_id: Uuid,
+ pub expected_direction: &'a str,
+ pub created_by: Uuid,
+ pub origin: &'a str,
+}
+
+pub async fn list(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Case>> {
+ Ok(sqlx::query_as(
+ "SELECT c.* FROM ontology_regression_cases c WHERE c.kb_id=$1
+ AND EXISTS(SELECT 1 FROM facts f WHERE f.id=c.statement_id AND f.kb_id=c.kb_id
+ AND f.layer='open' AND f.invalidated_at IS NULL) ORDER BY c.created_at DESC,c.id",
+ )
+ .bind(kb_id)
+ .fetch_all(pool)
+ .await?)
+}
+
+pub async fn get(pool: &PgPool, kb_id: Uuid, id: Uuid) -> AppResult<Option<Case>> {
+ Ok(
+ sqlx::query_as("SELECT * FROM ontology_regression_cases WHERE kb_id=$1 AND id=$2")
+ .bind(kb_id)
+ .bind(id)
+ .fetch_optional(pool)
+ .await?,
+ )
+}
+
+pub async fn add(pool: &PgPool, kb_id: Uuid, case: NewCase<'_>) -> AppResult<Uuid> {
+ let mut tx = pool.begin().await?;
+ let id = add_on(&mut tx, kb_id, case).await?;
+ tx.commit().await?;
+ Ok(id)
+}
+
+/// Adoption calls this in its own transaction so marking a proposal adopted and keeping
+/// its examples cannot commit separately. Duplicate requests retain the first actor/origin.
+pub async fn add_on(conn: &mut PgConnection, kb_id: Uuid, case: NewCase<'_>) -> AppResult<Uuid> {
+ if !matches!(case.expected_direction, "forward" | "reverse") {
+ return Err(AppError::invalid(
+ "bad_direction",
+ "Direction is forward or reverse.",
+ ));
+ }
+ if !matches!(case.origin, "adoption" | "person") {
+ return Err(AppError::invalid(
+ "bad_origin",
+ "Origin is adoption or person.",
+ ));
+ }
+ let value: Option<bool> = sqlx::query_scalar(
+ "SELECT object_id IS NULL FROM facts
+ WHERE kb_id=$1 AND id=$2 AND layer='open' AND invalidated_at IS NULL
+ AND nullif(btrim(phrase),'') IS NOT NULL FOR SHARE",
+ )
+ .bind(kb_id)
+ .bind(case.statement_id)
+ .fetch_optional(&mut *conn)
+ .await?;
+ let value = value.ok_or(AppError::NotFound)?;
+ let kind: Option<String> =
+ sqlx::query_scalar("SELECT kind FROM relation_types WHERE kb_id=$1 AND id=$2 FOR SHARE")
+ .bind(kb_id)
+ .bind(case.expected_property_id)
+ .fetch_optional(&mut *conn)
+ .await?;
+ let kind = kind.ok_or(AppError::NotFound)?;
+ if value != (kind == "attribute") || (value && case.expected_direction != "forward") {
+ return Err(AppError::invalid(
+ "bad_property_shape",
+ "The property's kind and direction must fit the statement's object.",
+ ));
+ }
+ // DO NOTHING followed by SELECT observes a concurrent inserter after its commit,
+ // without turning an idempotent retry into an edit of the original confirmation.
+ let inserted:Option<Uuid>=sqlx::query_scalar("INSERT INTO ontology_regression_cases
+ (id,kb_id,statement_id,expected_property_id,expected_direction,created_by,origin)
+ VALUES($1,$2,$3,$4,$5,$6,$7)
+ ON CONFLICT(kb_id,statement_id,expected_property_id,expected_direction) DO NOTHING RETURNING id")
+ .bind(Uuid::now_v7()).bind(kb_id).bind(case.statement_id).bind(case.expected_property_id)
+ .bind(case.expected_direction).bind(case.created_by).bind(case.origin).fetch_optional(&mut *conn).await?;
+ let id = match inserted {
+ Some(id) => id,
+ None => {
+ sqlx::query_scalar(
+ "SELECT id FROM ontology_regression_cases WHERE kb_id=$1 AND statement_id=$2
+ AND expected_property_id=$3 AND expected_direction=$4",
+ )
+ .bind(kb_id)
+ .bind(case.statement_id)
+ .bind(case.expected_property_id)
+ .bind(case.expected_direction)
+ .fetch_one(&mut *conn)
+ .await?
+ }
+ };
+ // A pre-existing decision is reported at its original time, never as a new model check.
+ sqlx::query(&format!(
+ "{} AND c.id=$2 AND c.last_checked_at IS NULL",
+ record_sql(false)
+ ))
+ .bind(kb_id)
+ .bind(id)
+ .execute(&mut *conn)
+ .await?;
+ Ok(id)
+}
+
+// The live statement determines the signature, exactly as production alignment does.
+// A person's binding remains authoritative even when it differs from the example; the
+// human_bound flag distinguishes that protection from an independent machine success.
+fn record_sql(fresh: bool) -> String {
+ let checked_at = if fresh { "now()" } else { "b.decided_at" };
+ format!("UPDATE ontology_regression_cases c
+ SET last_checked_at={checked_at},
+ last_result=jsonb_build_object('passed',coalesce((b.decided_by='person' AND b.status='bound') OR
+ (b.status='bound' AND b.relation_type_id=c.expected_property_id AND b.direction=c.expected_direction),false),
+ 'human_bound',b.decided_by='person' AND b.status='bound','actual_property_id',b.relation_type_id,
+ 'actual_direction',b.direction,'status',b.status,'decided_at',b.decided_at)
+ FROM facts f JOIN entities s ON s.id=f.subject_id AND s.kb_id=f.kb_id
+ LEFT JOIN entities o ON o.id=f.object_id AND o.kb_id=f.kb_id
+ JOIN phrase_bindings b ON b.kb_id=f.kb_id
+ AND b.phrase=lower(btrim(regexp_replace(f.phrase,'\\s+',' ','g')))
+ AND b.subject_type_id IS NOT DISTINCT FROM s.type_id
+ AND b.object_type_id IS NOT DISTINCT FROM o.type_id
+ AND b.object_is_value=(f.object_id IS NULL)
+ WHERE c.kb_id=$1 AND c.statement_id=f.id AND f.kb_id=c.kb_id
+ AND f.layer='open' AND f.invalidated_at IS NULL")
+}
+
+pub async fn record_for_signature(
+ conn: &mut PgConnection,
+ kb_id: Uuid,
+ sig: &PhraseSignature,
+) -> AppResult<()> {
+ sqlx::query(&format!(
+ "{} AND b.phrase=$2
+ AND b.subject_type_id IS NOT DISTINCT FROM $3 AND b.object_type_id IS NOT DISTINCT FROM $4
+ AND b.object_is_value=$5",
+ record_sql(true)
+ ))
+ .bind(kb_id)
+ .bind(crate::phrase_bindings::normalize(&sig.phrase))
+ .bind(sig.subject_type_id)
+ .bind(if sig.object_is_value {
+ None
+ } else {
+ sig.object_type_id
+ })
+ .bind(sig.object_is_value)
+ .execute(conn)
+ .await?;
+ Ok(())
+}
+
+/// Capture protected human choices when production skips them, without re-reading cached
+/// agent outputs as though they had just been evaluated after an unsuccessful model call.
+pub async fn record_human(pool: &PgPool, kb_id: Uuid) -> AppResult<()> {
+ sqlx::query(&format!("{} AND b.decided_by='person'", record_sql(true)))
+ .bind(kb_id)
+ .execute(pool)
+ .await?;
+ Ok(())
+}
diff --git a/crates/utopia-store/src/phrase_bindings.rs b/crates/utopia-store/src/phrase_bindings.rs
index b4c1fe9c..cf0c3683 100644
--- a/crates/utopia-store/src/phrase_bindings.rs
+++ b/crates/utopia-store/src/phrase_bindings.rs
@@ -47,6 +47,8 @@ pub struct PhraseSignature {
/// 例句:最多 3 条「主语 —短语→ 宾语」,每条跟着它自己的引文
pub examples: Vec<String>,
pub quotes: Vec<String>,
+ /// Statement identities in the same order as the live examples and quotes.
+ pub example_statement_ids: Vec<Uuid>,
}
/// 库里每条 distinct 的签名:活着的开放陈述,按短语、两端的类、宾语是不是字面值分组。
@@ -88,14 +90,16 @@ pub async fn signatures(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<PhraseSigna
array_agg(r.subject_name || ' —' || r.spelling || '→ ' || r.object_name ORDER BY r.rn)
FILTER (WHERE r.rn <= 3) AS examples,
array_agg(coalesce(substr(c.text, r.quote_start + 1, r.quote_end - r.quote_start), '') ORDER BY r.rn)
- FILTER (WHERE r.rn <= 3) AS quotes
+ FILTER (WHERE r.rn <= 3) AS quotes,
+ array_agg(r.id ORDER BY r.rn) FILTER (WHERE r.rn <= 3) AS example_statement_ids
FROM ranked r
LEFT JOIN chunks c ON c.id = r.chunk_id AND r.rn <= 3
GROUP BY r.phrase, r.subject_type_id, r.object_type_id, r.object_is_value
)
SELECT g.phrase, g.subject_type_id, st.key AS subject_type_key,
g.object_type_id, ot.key AS object_type_key, g.object_is_value, g.count,
- coalesce(g.examples, '{{}}') AS examples, coalesce(g.quotes, '{{}}') AS quotes
+ coalesce(g.examples, '{{}}') AS examples, coalesce(g.quotes, '{{}}') AS quotes,
+ coalesce(g.example_statement_ids, '{{}}'::uuid[]) AS example_statement_ids
FROM grouped g
LEFT JOIN entity_types st ON st.id = g.subject_type_id
LEFT JOIN entity_types ot ON ot.id = g.object_type_id
@@ -116,7 +120,8 @@ pub async fn signature_of(
Ok(sqlx::query_as(
"SELECT b.phrase, b.subject_type_id, st.key AS subject_type_key,
b.object_type_id, ot.key AS object_type_key, b.object_is_value,
- b.statement_count::bigint AS count, b.examples, '{}'::text[] AS quotes
+ b.statement_count::bigint AS count, b.examples, '{}'::text[] AS quotes,
+ '{}'::uuid[] AS example_statement_ids
FROM phrase_bindings b
LEFT JOIN entity_types st ON st.id = b.subject_type_id
LEFT JOIN entity_types ot ON ot.id = b.object_type_id
@@ -293,8 +298,12 @@ pub async fn decide(
d: Decision<'_>,
) -> AppResult<bool> {
validate_decision(sig, &d)?;
- let mut connection = pool.acquire().await?;
- decide_on(&mut connection, kb_id, sig, d).await
+ // The observed regression outcome belongs to this decision, not to a later read that
+ // could see a different person's binding. Commit both together, as delivery already does.
+ let mut tx = pool.begin().await?;
+ let changed = decide_on(&mut tx, kb_id, sig, d).await?;
+ tx.commit().await?;
+ Ok(changed)
}
fn validate_decision(sig: &PhraseSignature, d: &Decision<'_>) -> AppResult<String> {
@@ -385,7 +394,7 @@ async fn decide_with_delivery_budget(
Ok(Some(id))
}
-/// Write on the caller's connection, so related durable work can share its transaction.
+/// Write on the caller's transaction connection, so related durable work shares its commit.
pub async fn decide_on(
connection: &mut sqlx::PgConnection,
kb_id: Uuid,
@@ -434,9 +443,13 @@ pub async fn decide_on(
.bind(d.basis)
.bind(d.marks)
.bind(d.marks_asked)
- .execute(connection)
+ .execute(&mut *connection)
.await?;
- Ok(res.rows_affected() > 0)
+ let changed = res.rows_affected() > 0;
+ if changed {
+ crate::ontology_regressions::record_for_signature(connection, kb_id, sig).await?;
+ }
+ Ok(changed)
}
/// 给这一列之前绑上的签名补问 marks 的结果(0053 修订 2026-09-27)。这一问只问一刻标哪一端,
diff --git a/crates/utopia-store/tests/store/a_plan_step_follows_its_premise.rs b/crates/utopia-store/tests/store/a_plan_step_follows_its_premise.rs
index 7ad0244f..c0a85cc1 100644
--- a/crates/utopia-store/tests/store/a_plan_step_follows_its_premise.rs
+++ b/crates/utopia-store/tests/store/a_plan_step_follows_its_premise.rs
@@ -598,6 +598,7 @@ async fn bind_is_on(pool: &PgPool, f: &Fixture) -> anyhow::Result<()> {
count: 1,
examples: Vec::new(),
quotes: Vec::new(),
+ example_statement_ids: Vec::new(),
};
let written = phrase_bindings::decide(
pool,
diff --git a/crates/utopia-store/tests/store/main.rs b/crates/utopia-store/tests/store/main.rs
index 1f28c5c9..cde15d17 100644
--- a/crates/utopia-store/tests/store/main.rs
+++ b/crates/utopia-store/tests/store/main.rs
@@ -136,6 +136,7 @@ mod merge_direction_counts_live_facts_in_each_base;
mod migration_0070_runs_under_any_search_path;
mod negative_binding_definition_edit;
mod no_predicate_still_shows;
+mod ontology_regressions;
mod phrase_signature_evidence;
mod review_stages;
mod rss_full_content;
diff --git a/crates/utopia-store/tests/store/migration_0070_runs_under_any_search_path.rs b/crates/utopia-store/tests/store/migration_0070_runs_under_any_search_path.rs
index 296dece3..7949f114 100644
--- a/crates/utopia-store/tests/store/migration_0070_runs_under_any_search_path.rs
+++ b/crates/utopia-store/tests/store/migration_0070_runs_under_any_search_path.rs
@@ -319,6 +319,7 @@ const LEDGER_TABLES: &[&str] = &[
"facts",
"implication_rules",
"name_vectors",
+ "ontology_regression_cases",
"phrase_bindings",
"phrase_readings",
"relation_types",
@@ -618,7 +619,7 @@ struct Coverage {
impl Coverage {
/// 完备 = 没有未归类的边、没有腐掉的登记、面与机制互证得上,
/// 每条受保护边都进了导出体检、体检里没有腐掉的分支,
- /// 且两类已覆盖边的数量与迁移记录的 26/13 一致。
+ /// 且两类已覆盖边的数量与当前迁移链的 44/16 一致。
fn assert_complete(&self) -> anyhow::Result<()> {
let mut problems = String::new();
let mut dump = |name: &str, xs: &[String]| {
@@ -633,9 +634,10 @@ impl Coverage {
dump("SURFACE_DRIFT", &self.surface_drift);
dump("PREFLIGHT_MISSING", &self.preflight_missing);
dump("STALE_PREFLIGHT", &self.stale_preflight);
- if self.declarative.len() != 42 {
+ // 0109 adds the statement and expected-property references on regression cases.
+ if self.declarative.len() != 44 {
problems.push_str(&format!(
- " DECLARATIVE_EDGES = {} (expected 42)\n",
+ " DECLARATIVE_EDGES = {} (expected 44)\n",
self.declarative.len()
));
}
@@ -1060,8 +1062,8 @@ async fn a_protected_edge_missing_from_preflight_fails_the_guard() -> anyhow::Re
#[test]
fn the_preflight_check_notices_a_dropped_or_stray_edge() -> anyhow::Result<()> {
let surface = preflight_surface()?;
- // 同一份文件两个方向各数一次:58 条结构边 + 5 条 merged 过滤检查
- assert_eq!(surface.edges.len(), 58, "preflight 必须覆盖全部保护边");
+ // 同一份文件两个方向各数一次:60 条结构边 + 5 条 merged 过滤检查
+ assert_eq!(surface.edges.len(), 60, "preflight 必须覆盖全部保护边");
assert_eq!(
surface.filters,
[
diff --git a/crates/utopia-store/tests/store/ontology_regressions.rs b/crates/utopia-store/tests/store/ontology_regressions.rs
new file mode 100644
index 00000000..c9bb4284
--- /dev/null
+++ b/crates/utopia-store/tests/store/ontology_regressions.rs
@@ -0,0 +1,70 @@
+use sqlx::PgPool;
+use utopia_store::{graph, ontology_regressions as regressions, phrase_bindings};
+use uuid::Uuid;
+
+#[tokio::test]
+async fn committed_decisions_report_matches_and_human_bindings() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ utopia_store::db::migrate(&pool).await?;
+ let (org, workspace, kb, actor, subject, object, property) = (
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ );
+ sqlx::query("INSERT INTO organizations(id,name) VALUES($1,'regression-cases')")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ let result = async {
+ sqlx::query("INSERT INTO workspaces(id,org_id,name) VALUES($1,$2,'regression-cases')")
+ .bind(workspace).bind(org).execute(&pool).await?;
+ sqlx::query("INSERT INTO knowledge_bases(id,workspace_id,name) VALUES($1,$2,'regression-cases')")
+ .bind(kb).bind(workspace).execute(&pool).await?;
+ sqlx::query("INSERT INTO users(id,org_id,email,password_hash,display_name) VALUES($1,$2,$3,'fixture','Reviewer')")
+ .bind(actor).bind(org).bind(format!("{actor}@example.test")).execute(&pool).await?;
+ for (id, name) in [(subject, "A"), (object, "B")] {
+ sqlx::query("INSERT INTO entities(id,kb_id,canonical_name) VALUES($1,$2,$3)")
+ .bind(id).bind(kb).bind(name).execute(&pool).await?;
+ }
+ sqlx::query("INSERT INTO relation_types(id,kb_id,key,label) VALUES($1,$2,'acquired','acquired')")
+ .bind(property).bind(kb).execute(&pool).await?;
+ let statement_id = graph::insert_open_statement(
+ &pool, kb, subject, "acquired", graph::FactObject::Entity(object), None, 1.0,
+ ).await?.0;
+ let case_id = regressions::add(&pool, kb, regressions::NewCase {
+ statement_id, expected_property_id: property, expected_direction: "forward",
+ created_by: actor, origin: "person",
+ }).await?;
+ let signature = phrase_bindings::signatures(&pool, kb).await?.remove(0);
+ for (direction, decided_by, passed, human_bound) in [
+ ("forward", "agent", true, false),
+ ("reverse", "agent", false, false),
+ ("reverse", "person", true, true),
+ ] {
+ phrase_bindings::decide(&pool, kb, &signature, phrase_bindings::Decision {
+ relation_type_id: Some(property), direction: Some(direction), status: "bound",
+ decided_by, votes: &serde_json::Value::Null, basis: None,
+ marks: None, marks_asked: false,
+ }).await?;
+ let case = regressions::get(&pool, kb, case_id).await?.unwrap();
+ let report = case.last_result.unwrap();
+ anyhow::ensure!(report["passed"] == passed);
+ anyhow::ensure!(report["human_bound"] == human_bound);
+ anyhow::ensure!(report["actual_direction"] == direction);
+ anyhow::ensure!(case.last_checked_at.is_some());
+ }
+ Ok(())
+ }.await;
+ sqlx::query("DELETE FROM organizations WHERE id=$1")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ result
+}
diff --git a/crates/utopia-store/tests/store/tied_signatures_come_in_a_fixed_order.rs b/crates/utopia-store/tests/store/tied_signatures_come_in_a_fixed_order.rs
index 6059ee85..eaa6a96c 100644
--- a/crates/utopia-store/tests/store/tied_signatures_come_in_a_fixed_order.rs
+++ b/crates/utopia-store/tests/store/tied_signatures_come_in_a_fixed_order.rs
@@ -105,6 +105,7 @@ async fn tied_signatures_come_in_a_fixed_order() -> anyhow::Result<()> {
"{shape:#?}"
);
let supplied = &sigs[0];
+ anyhow::ensure!(supplied.example_statement_ids == supplies[..3]);
anyhow::ensure!(
supplied.examples
== vec![
diff --git a/docs/decisions/0061-the-ontology-is-proposed-from-the-open-graph-and-judged-by-its-questions.md b/docs/decisions/0061-the-ontology-is-proposed-from-the-open-graph-and-judged-by-its-questions.md
index 947e0d05..661d27ab 100644
--- a/docs/decisions/0061-the-ontology-is-proposed-from-the-open-graph-and-judged-by-its-questions.md
+++ b/docs/decisions/0061-the-ontology-is-proposed-from-the-open-graph-and-judged-by-its-questions.md
@@ -50,6 +50,29 @@ The open graph holds statements with their phrases, quotes, kind words and names
- Proposals against an imported pack: a proposed property that a pack already has under another name should become a `map_to`, and the agent needs the pack's definitions to see it.
- Whether a rejected proposal's reason should suppress the element for a time or until the signatures behind it change.
+## Cut 2 implementation boundary — 2026-10-10
+
+The [first slice agreed in #1103](https://github.com/deeplethe/utopia/issues/1103#issuecomment-6063201562)
+keeps a statement's expected property and direction, actor, and `adoption` / `person`
+origin. An Editor adds a case with `POST /api/v1/kbs/{kb_id}/ontology/regressions`
+and `{statement_id, relation_type_id, direction}`; the statement and property must
+belong to that base. Literal objects use forward attribute bindings. Repeated
+confirmation retains the original attribution.
+
+The existing signatures query returns statement IDs alongside its examples and quotes.
+A proposal keeps the first example's ID with each shape, and adoption writes those
+cases and the proposal's adopted status in one transaction. Older proposals without
+IDs write no cases; removed examples are skipped rather than replaced, as requested
+in the [review of #1178](https://github.com/deeplethe/utopia/pull/1178#pullrequestreview-5477521283).
+
+A binding decision records the latest comparison in the same transaction: property
+and direction must match, except that a person's bound signature always passes and
+explicitly reports `human_bound`. Rejections do not pass. The result retains the actual
+binding and its decision time alongside the check time; an existing decision is initially
+reported at its original time. These cases observe alignment without another evaluator,
+model call, evaluation job, or version identity. They are not a semantic accuracy
+benchmark. The workbench view follows in a second PR.
+
## Status history
The status line as it stood on 2026-09-27, before status lines were cut to one line:
diff --git a/migrations/0109_a_human_example_records_the_existing_alignment_outcome.sql b/migrations/0109_a_human_example_records_the_existing_alignment_outcome.sql
new file mode 100644
index 00000000..ed16eb62
--- /dev/null
+++ b/migrations/0109_a_human_example_records_the_existing_alignment_outcome.sql
@@ -0,0 +1,23 @@
+-- 0061 cut 2 第一片:人留的例子比较已有对齐结果,不另起模型或调度器。
+-- 原陈述、目标属性属于同一个库;删掉它们时例子也消失,避免悬空预期。
+CREATE TABLE ontology_regression_cases (
+ id UUID PRIMARY KEY,
+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+ statement_id UUID NOT NULL,
+ expected_property_id UUID NOT NULL,
+ expected_direction TEXT NOT NULL CHECK (expected_direction IN ('forward', 'reverse')),
+ created_by UUID REFERENCES users(id) ON DELETE SET NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ origin TEXT NOT NULL CHECK (origin IN ('adoption', 'person')),
+ last_checked_at TIMESTAMPTZ,
+ last_result JSONB,
+ FOREIGN KEY (kb_id, statement_id) REFERENCES facts(kb_id, id) ON DELETE CASCADE,
+ FOREIGN KEY (kb_id, expected_property_id) REFERENCES relation_types(kb_id, id) ON DELETE CASCADE,
+ UNIQUE (kb_id, statement_id, expected_property_id, expected_direction)
+);
+CREATE INDEX ontology_regression_cases_property
+ ON ontology_regression_cases(kb_id, expected_property_id);
+CREATE TRIGGER ontology_regression_cases_keep_their_kb
+ BEFORE UPDATE OF kb_id ON ontology_regression_cases
+ FOR EACH ROW EXECUTE FUNCTION kb_ownership_is_not_reassigned();
+