Skip to content

World's first open-source enterprise world model.

Reconsider negative bindings when existing definitions change (#775)

Maya Kid30077966d7fb
diff --git a/crates/utopia-store/src/phrase_bindings.rs b/crates/utopia-store/src/phrase_bindings.rs
index 82c5e857..44e76e45 100644
--- a/crates/utopia-store/src/phrase_bindings.rs
+++ b/crates/utopia-store/src/phrase_bindings.rs
@@ -176,8 +176,9 @@ pub async fn bindings(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {
.await?)
}
-/// 不再成立的绑定:绑到的属性在判定之后改过;或判成 none / undecided 之后库里长出了
-/// 新属性。属性或类被删了的,行已随级联消失。
+/// 不再成立的绑定:绑到的属性在判定之后改过;或判成 none / undecided 之后库里有属性
+/// 新建或修改。负向判定没有选中的属性,已有属性的新定义也可能让它对得上。
+/// 属性或类被删了的,行已随级联消失。
pub async fn stale(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {
Ok(sqlx::query_as(
"SELECT b.phrase, b.subject_type_id, b.object_type_id, b.object_is_value,
@@ -187,7 +188,7 @@ pub async fn stale(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {
WHERE b.kb_id = $1
AND ((b.status = 'bound' AND r.updated_at > b.decided_at)
OR (b.status IN ('none', 'undecided')
- AND b.decided_at < (SELECT max(created_at) FROM relation_types
+ AND b.decided_at < (SELECT max(updated_at) FROM relation_types
WHERE kb_id = $1)))
ORDER BY b.phrase",
)
diff --git a/crates/utopia-store/src/type_bindings.rs b/crates/utopia-store/src/type_bindings.rs
index fe473e31..340fdbdf 100644
--- a/crates/utopia-store/src/type_bindings.rs
+++ b/crates/utopia-store/src/type_bindings.rs
@@ -110,8 +110,9 @@ pub async fn bindings(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {
.await?)
}
-/// 不再成立的绑定:绑到的类在判定之后改过;或判成 none / undecided 之后库里长出了
-/// 新类(也许对得上)。绑到的类被删了的,行已随级联消失,这里不会出现。
+/// 不再成立的绑定:绑到的类在判定之后改过;或判成 none / undecided 之后库里有类
+/// 新建或修改。负向判定没有选中的类,已有类的新定义也可能让它对得上。
+/// 绑到的类被删了的,行已随级联消失,这里不会出现。
pub async fn stale(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<String>> {
Ok(sqlx::query_scalar(
"SELECT b.kind_word
@@ -120,7 +121,7 @@ pub async fn stale(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<String>> {
WHERE b.kb_id = $1
AND ((b.status = 'bound' AND t.updated_at > b.decided_at)
OR (b.status IN ('none', 'undecided')
- AND b.decided_at < (SELECT max(created_at) FROM entity_types
+ AND b.decided_at < (SELECT max(updated_at) FROM entity_types
WHERE kb_id = $1)))
ORDER BY b.kind_word",
)
diff --git a/crates/utopia-store/tests/negative_binding_definition_edit.rs b/crates/utopia-store/tests/negative_binding_definition_edit.rs
new file mode 100644
index 00000000..6a76d1fb
--- /dev/null
+++ b/crates/utopia-store/tests/negative_binding_definition_edit.rs
@@ -0,0 +1,313 @@
+//! Negative decisions depend on existing definitions as well as new candidates (#773).
+use sqlx::PgPool;
+use utopia_store::graph::{self, FactObject};
+use utopia_store::{ontology, phrase_bindings as pb, type_bindings as tb};
+use uuid::Uuid;
+
+const WORD: &str = "candidate wording";
+
+#[derive(Clone, Copy, Debug)]
+enum BindingKind {
+ KindWord,
+ Phrase,
+}
+
+impl BindingKind {
+ fn definitions(self) -> &'static str {
+ match self {
+ Self::KindWord => "entity_types",
+ Self::Phrase => "relation_types",
+ }
+ }
+
+ fn bindings(self) -> &'static str {
+ match self {
+ Self::KindWord => "type_bindings",
+ Self::Phrase => "phrase_bindings",
+ }
+ }
+
+ async fn stale(self, pool: &PgPool, kb: Uuid) -> anyhow::Result<bool> {
+ Ok(match self {
+ Self::KindWord => !tb::stale(pool, kb).await?.is_empty(),
+ Self::Phrase => !pb::stale(pool, kb).await?.is_empty(),
+ })
+ }
+
+ async fn decide(
+ self,
+ pool: &PgPool,
+ kb: Uuid,
+ chosen: Option<Uuid>,
+ status: &str,
+ actor: &str,
+ ) -> anyhow::Result<bool> {
+ let votes = serde_json::json!({});
+ Ok(match self {
+ Self::KindWord => {
+ tb::decide(pool, kb, WORD, &[], chosen, status, &votes, actor).await?
+ }
+ Self::Phrase => {
+ let sig = pb::signatures(pool, kb)
+ .await?
+ .into_iter()
+ .find(|s| s.phrase == WORD)
+ .expect("the open statement produces a signature");
+ pb::decide(
+ pool,
+ kb,
+ &sig,
+ pb::Decision {
+ relation_type_id: chosen,
+ direction: chosen.map(|_| "forward"),
+ status,
+ votes: &votes,
+ decided_by: actor,
+ },
+ )
+ .await?
+ }
+ })
+ }
+}
+
+#[derive(Clone, Copy, Debug)]
+enum Change {
+ Edit,
+ Add,
+}
+
+async fn lifecycle(
+ kind: BindingKind,
+ status: &str,
+ change: Change,
+ actor: &str,
+) -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let org = Uuid::now_v7();
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'negative-binding-test')")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ let result = exercise(&pool, org, kind, status, change, actor).await;
+ sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ result
+}
+
+async fn exercise(
+ pool: &PgPool,
+ org: Uuid,
+ kind: BindingKind,
+ status: &str,
+ change: Change,
+ actor: &str,
+) -> anyhow::Result<()> {
+ let (ws, kb, other_kb, definition) = (
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ );
+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'binding-test')")
+ .bind(ws)
+ .bind(org)
+ .execute(pool)
+ .await?;
+ for base in [kb, other_kb] {
+ sqlx::query("INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'test')")
+ .bind(base)
+ .bind(ws)
+ .execute(pool)
+ .await?;
+ }
+ let table = kind.definitions();
+ // Control the ordering without sleeps: creation < decision < the real edit below.
+ sqlx::query(&format!(
+ "INSERT INTO {table} (id, kb_id, key, label, description, created_at, updated_at)
+ VALUES ($1, $2, 'candidate', 'candidate', 'old definition',
+ '2000-01-01', '2000-01-01')"
+ ))
+ .bind(definition)
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ let (subject, object) = (Uuid::now_v7(), Uuid::now_v7());
+ for entity in [subject, object] {
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, canonical_name, specific_type)
+ VALUES ($1, $2, $3, $4)",
+ )
+ .bind(entity)
+ .bind(kb)
+ .bind(entity.to_string())
+ .bind(WORD)
+ .execute(pool)
+ .await?;
+ }
+ graph::insert_open_statement(
+ pool,
+ kb,
+ subject,
+ WORD,
+ FactObject::Entity(object),
+ None,
+ 0.9,
+ )
+ .await?;
+ assert_eq!(tb::signatures(pool, kb).await?[0].kind_word, WORD);
+ let chosen = (status == "bound").then_some(definition);
+ assert!(kind.decide(pool, kb, chosen, status, actor).await?);
+ sqlx::query(&format!(
+ "UPDATE {} SET decided_at = '2000-01-02' WHERE kb_id = $1",
+ kind.bindings()
+ ))
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ assert!(!kind.stale(pool, kb).await?, "unchanged inputs stay cached");
+
+ // A newer candidate in another base must not invalidate this base's decisions.
+ sqlx::query(&format!(
+ "INSERT INTO {table} (id, kb_id, key, label) VALUES ($1, $2, 'other', 'other')"
+ ))
+ .bind(Uuid::now_v7())
+ .bind(other_kb)
+ .execute(pool)
+ .await?;
+ assert!(
+ !kind.stale(pool, kb).await?,
+ "invalidation is scoped to the KB"
+ );
+
+ match change {
+ Change::Add => {
+ sqlx::query(&format!(
+ "INSERT INTO {table} (id, kb_id, key, label) VALUES ($1, $2, 'new', 'new')"
+ ))
+ .bind(Uuid::now_v7())
+ .bind(kb)
+ .execute(pool)
+ .await?;
+ }
+ Change::Edit => match kind {
+ BindingKind::KindWord => {
+ ontology::update_entity_type(
+ pool,
+ kb,
+ definition,
+ "candidate",
+ None,
+ "circle",
+ &[],
+ "expanded definition",
+ )
+ .await?;
+ }
+ BindingKind::Phrase => {
+ ontology::update_relation_type(
+ pool,
+ kb,
+ definition,
+ "candidate",
+ "state",
+ Default::default(),
+ "expanded definition",
+ None,
+ None,
+ None,
+ None,
+ )
+ .await?;
+ }
+ },
+ }
+ let (created_before, updated_after): (bool, bool) = sqlx::query_as(&format!(
+ "SELECT created_at < '2000-01-02'::timestamptz,
+ updated_at > '2000-01-02'::timestamptz FROM {table} WHERE id = $1"
+ ))
+ .bind(definition)
+ .fetch_one(pool)
+ .await?;
+ assert!(created_before);
+ assert_eq!(updated_after, matches!(change, Change::Edit));
+ let stale = kind.stale(pool, kb).await?;
+ eprintln!("DB: {kind:?} {status} {change:?} {actor}: stale={stale}");
+ anyhow::ensure!(stale, "{kind:?} {status} should be stale after {change:?}");
+
+ if actor == "person" {
+ assert!(
+ !kind
+ .decide(pool, kb, Some(definition), "bound", "agent")
+ .await?,
+ "a stale person decision still rejects automatic replacement"
+ );
+ let (saved_status, saved_actor): (String, String) = sqlx::query_as(&format!(
+ "SELECT status, decided_by FROM {} WHERE kb_id = $1",
+ kind.bindings()
+ ))
+ .bind(kb)
+ .fetch_one(pool)
+ .await?;
+ assert_eq!(
+ (saved_status.as_str(), saved_actor.as_str()),
+ (status, actor)
+ );
+ } else {
+ // A fresh decision, including another negative one, must close the work again.
+ assert!(kind.decide(pool, kb, chosen, status, actor).await?);
+ assert!(
+ !kind.stale(pool, kb).await?,
+ "a fresh decision stays cached"
+ );
+ }
+ Ok(())
+}
+
+#[tokio::test]
+async fn new_candidates_and_bound_edits_still_invalidate() -> anyhow::Result<()> {
+ for kind in [BindingKind::KindWord, BindingKind::Phrase] {
+ lifecycle(kind, "bound", Change::Edit, "agent").await?;
+ for status in ["none", "undecided"] {
+ lifecycle(kind, status, Change::Add, "agent").await?;
+ }
+ }
+ Ok(())
+}
+
+#[tokio::test]
+async fn stale_person_decisions_still_reject_agent_writes() -> anyhow::Result<()> {
+ for kind in [BindingKind::KindWord, BindingKind::Phrase] {
+ for status in ["none", "undecided"] {
+ for change in [Change::Add, Change::Edit] {
+ lifecycle(kind, status, change, "person").await?;
+ }
+ }
+ }
+ Ok(())
+}
+
+#[tokio::test]
+async fn class_edit_reconsiders_none() -> anyhow::Result<()> {
+ lifecycle(BindingKind::KindWord, "none", Change::Edit, "agent").await
+}
+
+#[tokio::test]
+async fn class_edit_reconsiders_undecided() -> anyhow::Result<()> {
+ lifecycle(BindingKind::KindWord, "undecided", Change::Edit, "agent").await
+}
+
+#[tokio::test]
+async fn property_edit_reconsiders_none() -> anyhow::Result<()> {
+ lifecycle(BindingKind::Phrase, "none", Change::Edit, "agent").await
+}
+
+#[tokio::test]
+async fn property_edit_reconsiders_undecided() -> anyhow::Result<()> {
+ lifecycle(BindingKind::Phrase, "undecided", Change::Edit, "agent").await
+}
diff --git a/docs/design/ontology.md b/docs/design/ontology.md
index 7533a50a..89b2bb77 100644
--- a/docs/design/ontology.md
+++ b/docs/design/ontology.md
@@ -66,9 +66,15 @@ candidates in opposite orders must agree on the property and the direction (forw
statement's subject is the property's subject, reverse when its object is) for the signature to
bind. A signature the votes disagree on is `undecided` for the alignment queue of #725; one with no
fitting property is `none`, its statements stay in the open graph and it counts toward the
-workbench's suggestions. Bindings live in `phrase_bindings` and go stale when the property they
-bound to changes or a property is added; a burst of ontology edits debounces into one run rather
-than one run each [#757]; a person's decision is never overwritten by the agent. On
+workbench's suggestions. Bindings live in `phrase_bindings`: a bound result goes stale when its
+selected property changes; `none` and `undecided` go stale when any property in the base is added
+or updated, since an existing property's revised definition may now fit [#773]. Kind-word bindings
+use the same rule for classes. Both use `updated_at`, so cosmetic edits can also trigger
+reevaluation. Even one edit can reopen all older automatic negative bindings on that side of the
+base, requiring two votes per eligible item through batched model requests; debouncing reduces
+the number of runs, not the items reconsidered. A burst of ontology edits debounces into one run
+rather than one run each [#757];
+a person's decision is never overwritten by the agent. On
the 25-document batch with a hand-written ontology of 14 classes and 28 properties, and 60 of
400 kind words bound, 423 signatures cover 861 statements: 36 bind (184 statements), 110 bind to
nothing, 1 splits the votes and 276 have no admissible property because an end is unbound; a