Skip to content

World's first open-source enterprise world model.

Refresh the ontology vector index when the editor creates or relabels a class or property, before alignment runs (#956)

WaylandYangc7435ecc0a73
diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rs
index 610069d9..6e99e382 100644
--- a/crates/utopia-server/src/api/ontology_routes.rs
+++ b/crates/utopia-server/src/api/ontology_routes.rs
@@ -95,6 +95,43 @@ pub struct EntityTypeReq {
pub description: Option<String>,
}
+/// 编辑器改了本体之后:先补向量索引,再排对齐。
+///
+/// **新元素要有向量,对齐的短名单才看得见它。** 候选多于短名单长度时按向量挑
+/// (`phrase_alignment::shortlist`),类别词的候选类也按向量检索
+/// (`type_alignment::candidates_for`);没向量的元素永远进不了名单,形状的指纹就不变,
+/// 建了也不重判——第一次真跑 `bordered_by` 就是这样(0061 cut 1.1 的采纳路径已经补了,
+/// 这里是编辑器的四个入口)。描述改了也算:向量按「当时嵌的原文」判陈,改了描述的行
+/// 会被同一个任务重嵌。
+///
+/// **排任务,不就地跑。** 就地嵌一次要付一趟嵌入请求的固定开销,本体页一口气建 28 条
+/// 属性就是 28 趟;排任务的话一批编辑只嵌一次。挡的只是排着的(`enqueue_unless_queued_after`),
+/// 不挡在跑的:在跑的那份已经读完待嵌集合,这条编辑它看不见,得再排一份。
+/// 去抖比对齐短,对齐任务开跑前还会看一眼这个任务有没有排着或跑着,排着就等
+/// (见 `align_phrases_reasking` / `align_types_reasking`)。
+async fn reindex_then_align(
+ state: &AppState,
+ kb_id: Uuid,
+ align_kind: &str,
+) -> Result<(), AppError> {
+ utopia_store::jobs::enqueue_unless_queued_after(
+ &state.pool,
+ "embed_ontology",
+ json!({ "kb_id": kb_id }),
+ std::time::Duration::from_secs(2),
+ )
+ .await?;
+ utopia_store::jobs::enqueue_unless_pending(
+ &state.pool,
+ align_kind,
+ json!({ "kb_id": kb_id }),
+ // 去抖:一批编辑(导一个包、建一串属性)只排一次
+ std::time::Duration::from_secs(5),
+ )
+ .await?;
+ Ok(())
+}
+
pub async fn create_entity_type(
State(state): State<AppState>,
AuthUser(user): AuthUser,
@@ -138,15 +175,9 @@ pub async fn create_entity_type(
json!({ "key": key, "label": req.label.trim() }),
)
.await;
- // 本体多了一个类:类别词的绑定里那些「没有」和「没定」的要重判(0044 对齐第一片)
- let _ = utopia_store::jobs::enqueue_unless_pending(
- &state.pool,
- "align_types",
- json!({ "kb_id": kb_id }),
- // 去抖:一批编辑(导一个包、建一串属性)只排一次
- std::time::Duration::from_secs(5),
- )
- .await;
+ // 本体多了一个类:类别词的绑定里那些「没有」和「没定」的要重判(0044 对齐第一片)。
+ // 先补它的向量,候选类的检索才找得到它
+ let _ = reindex_then_align(&state, kb_id, "align_types").await;
Ok(Json(json!({ "id": id })))
}
@@ -185,15 +216,8 @@ pub async fn update_entity_type(
"description": req.description }),
)
.await;
- // 类的定义改了:绑到它的类别词过期,重判
- let _ = utopia_store::jobs::enqueue_unless_pending(
- &state.pool,
- "align_types",
- json!({ "kb_id": kb_id }),
- // 去抖:一批编辑(导一个包、建一串属性)只排一次
- std::time::Duration::from_secs(5),
- )
- .await;
+ // 类的定义改了:绑到它的类别词过期,重判。标签或描述改了向量也陈了,先重嵌
+ let _ = reindex_then_align(&state, kb_id, "align_types").await;
// 对账可能在同一事务里收/开过违规行——审核队列变了,说一声(0062)
state.emit_review(kb_id);
Ok(Json(json!({ "ok": true })))
@@ -331,15 +355,9 @@ pub async fn create_relation_type(
if let Some(q) = req.qualifiers.as_deref() {
utopia_store::ontology::set_relation_qualifiers(&state.pool, kb_id, id, q).await?;
}
- // 多了一个属性:判成 none / undecided 的签名也许对得上了(0044 对齐第二片)
- utopia_store::jobs::enqueue_unless_pending(
- &state.pool,
- "align_phrases",
- serde_json::json!({ "kb_id": kb_id }),
- // 去抖:一批编辑(导一个包、建一串属性)只排一次
- std::time::Duration::from_secs(5),
- )
- .await?;
+ // 多了一个属性:判成 none / undecided 的签名也许对得上了(0044 对齐第二片)。
+ // 先补它的向量,短名单才看得见它
+ reindex_then_align(&state, kb_id, "align_phrases").await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
@@ -378,15 +396,9 @@ pub async fn update_relation_type(
if let Some(q) = req.qualifiers.as_deref() {
utopia_store::ontology::set_relation_qualifiers(&state.pool, kb_id, id, q).await?;
}
- // 属性改了定义或域/值域:绑到它的签名过期,判成 none 的也许对得上了
- utopia_store::jobs::enqueue_unless_pending(
- &state.pool,
- "align_phrases",
- serde_json::json!({ "kb_id": kb_id }),
- // 去抖:一批编辑(导一个包、建一串属性)只排一次
- std::time::Duration::from_secs(5),
- )
- .await?;
+ // 属性改了定义或域/值域:绑到它的签名过期,判成 none 的也许对得上了。
+ // 标签或描述改了向量也陈了,先重嵌(只改域/值域的话补齐任务一查就退)
+ reindex_then_align(&state, kb_id, "align_phrases").await?;
let _ = utopia_store::audit::record(
&state.pool,
Some(kb_id),
diff --git a/crates/utopia-server/src/phrase_alignment.rs b/crates/utopia-server/src/phrase_alignment.rs
index e9b4b968..1094ec79 100644
--- a/crates/utopia-server/src/phrase_alignment.rs
+++ b/crates/utopia-server/src/phrase_alignment.rs
@@ -363,9 +363,20 @@ pub async fn align_phrases_reasking(
.ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align phrases"))?;
// 类别词对齐还排着或跑着:两端的类还没定,现在判的签名指纹马上就变,判了也是重判。
// 等它收尾再来——排一份半分钟后的,排着的至多一份。别的入口(本体页、审核页、每篇文档
- // 抽完)排的短语对齐也从这里过,所以这一道守住就够
- if utopia_store::jobs::pending_for_kb(pool, "align_types", kb_id).await? {
- tracing::info!(%kb_id, "短语对齐:类别词对齐还没收尾,半分钟后再看");
+ // 抽完)排的短语对齐也从这里过,所以这一道守住就够。
+ //
+ // 本体向量还在补也等:编辑器建了属性先排 `embed_ontology` 再排这个任务,没向量的属性
+ // 进不了短名单,形状的指纹不变,现在判了它照样不在候选里(`bordered_by` 第一次真跑
+ // 就是这么漏的)。补齐任务几秒到几分钟,等得起
+ let waiting_on = if utopia_store::jobs::pending_for_kb(pool, "align_types", kb_id).await? {
+ Some("类别词对齐")
+ } else if utopia_store::jobs::pending_for_kb(pool, "embed_ontology", kb_id).await? {
+ Some("本体向量补齐")
+ } else {
+ None
+ };
+ if let Some(what) = waiting_on {
+ tracing::info!(%kb_id, "短语对齐:{what}还没收尾,半分钟后再看");
let payload = if reask == 0 {
serde_json::json!({ "kb_id": kb_id })
} else {
diff --git a/crates/utopia-server/src/phrase_alignment_tests.rs b/crates/utopia-server/src/phrase_alignment_tests.rs
index 4da815fc..fd52f523 100644
--- a/crates/utopia-server/src/phrase_alignment_tests.rs
+++ b/crates/utopia-server/src/phrase_alignment_tests.rs
@@ -39,13 +39,42 @@ async fn reply(State(m): State<Model>, Json(body): Json<Value>) -> impl IntoResp
)
}
+/// 脚本化的嵌入端点:每段文字一个由字节算出的四维向量。只要求确定、条数对得上——
+/// 这里测的是「向量有没有」,不是近不近
+async fn embed(Json(body): Json<Value>) -> impl IntoResponse {
+ let data: Vec<Value> = body["input"]
+ .as_array()
+ .cloned()
+ .unwrap_or_default()
+ .iter()
+ .map(|t| {
+ let bytes = t.as_str().unwrap_or("").as_bytes();
+ let v: Vec<f32> = (0..4)
+ .map(|i| {
+ bytes
+ .iter()
+ .skip(i)
+ .step_by(4)
+ .map(|b| *b as f32)
+ .sum::<f32>()
+ / 255.0
+ })
+ .collect();
+ json!({ "embedding": v })
+ })
+ .collect();
+ Json(json!({ "data": data }))
+}
+
struct Fx {
pool: sqlx::PgPool,
state: AppState,
org: Uuid,
+ ws: Uuid,
kb: Uuid,
legal_entity: Uuid,
organization: Uuid,
+ place: Uuid,
acme: Uuid,
based_in: Uuid,
model: Model,
@@ -106,6 +135,7 @@ impl Fx {
let endpoint = format!("http://{}", listener.local_addr()?);
let router = Router::new()
.route("/chat/completions", post(reply))
+ .route("/embeddings", post(embed))
.with_state(model.clone());
let server = tokio::spawn(async move {
axum::serve(listener, router).await.unwrap();
@@ -135,9 +165,11 @@ impl Fx {
pool,
state,
org,
+ ws,
kb,
legal_entity,
organization,
+ place,
acme,
based_in,
model,
@@ -148,6 +180,71 @@ impl Fx {
fn script(&self, replies: Vec<Value>) {
*self.model.replies.lock().unwrap() = replies;
}
+ /// 给工作区配上嵌入模型(同一个脚本化端点)。缺省不配:多数场景测的是结构候选,
+ /// 配了嵌入会让本体向量补齐与短名单掺进来
+ async fn enable_embeddings(&self) -> anyhow::Result<()> {
+ let settings = utopia_store::settings::get(&self.pool, self.ws)
+ .await?
+ .ok_or_else(|| anyhow::anyhow!("fixture settings missing"))?;
+ let endpoint = settings.chat_base_url.clone();
+ utopia_store::settings::upsert(
+ &self.pool,
+ self.ws,
+ endpoint.as_deref(),
+ None,
+ Some("scripted"),
+ endpoint.as_deref(),
+ None,
+ Some("scripted-embed"),
+ None,
+ )
+ .await?;
+ Ok(())
+ }
+ /// 这个库的一个编辑:走 API 处理函数要有人
+ async fn editor(&self) -> anyhow::Result<utopia_core::models::User> {
+ let id = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO users(id,org_id,email,password_hash,display_name) VALUES($1,$2,$3,'x','Editor')",
+ )
+ .bind(id)
+ .bind(self.org)
+ .bind(format!("editor-{id}@example.test"))
+ .execute(&self.pool)
+ .await?;
+ sqlx::query("INSERT INTO kb_members(kb_id,user_id,role) VALUES($1,$2,'editor')")
+ .bind(self.kb)
+ .bind(id)
+ .execute(&self.pool)
+ .await?;
+ Ok(utopia_core::models::User {
+ id,
+ org_id: self.org,
+ email: format!("editor-{id}@example.test"),
+ password_hash: "x".into(),
+ display_name: "Editor".into(),
+ is_admin: false,
+ created_at: chrono::Utc::now(),
+ })
+ }
+ /// 这个库排着的任务,按先后
+ async fn queued(&self) -> anyhow::Result<Vec<String>> {
+ Ok(sqlx::query_scalar(
+ "SELECT kind FROM jobs WHERE status='queued' AND payload->>'kb_id'=$1 ORDER BY run_at, id",
+ )
+ .bind(self.kb.to_string())
+ .fetch_all(&self.pool)
+ .await?)
+ }
+ /// 一条关系/属性有没有向量,以及嵌的是哪段字
+ async fn vector_of(&self, id: Uuid) -> anyhow::Result<(bool, Option<String>)> {
+ Ok(sqlx::query_as(
+ "SELECT embedding IS NOT NULL, embedded_text FROM relation_types WHERE id=$1",
+ )
+ .bind(id)
+ .fetch_one(&self.pool)
+ .await?)
+ }
async fn run(&self) -> anyhow::Result<()> {
align_phrases_reasking(&self.state, self.kb, 0).await
}
@@ -633,3 +730,135 @@ async fn an_unreadable_reply_is_asked_again_a_bounded_number_of_times() -> anyho
f.cleanup().await?;
run
}
+
+/// 编辑器建的属性先有向量,短语对齐才开跑:处理函数把 `embed_ontology` 排在
+/// `align_phrases` 前面,对齐看见补齐还排着就等;补齐跑完向量在表里,对齐才问模型,
+/// 而且新属性在候选里。改了描述再走一遍:存下的原文对不上,同一个任务把它重嵌
+#[tokio::test]
+async fn a_property_created_in_the_editor_has_its_vector_before_phrases_are_aligned(
+) -> anyhow::Result<()> {
+ use crate::api::ontology_routes::{
+ create_relation_type, update_relation_type, RelationTypeReq,
+ };
+ use crate::auth::AuthUser;
+ use axum::extract::{Path, State};
+ let Some(f) = Fx::new().await? else {
+ return Ok(());
+ };
+ let run = async {
+ f.enable_embeddings().await?;
+ let editor = f.editor().await?;
+ let req: RelationTypeReq = serde_json::from_value(json!({
+ "key": "headquartered_in",
+ "label": "headquartered in",
+ "kind": "relation",
+ "description": "where the main office of an entity is",
+ "domains": [f.legal_entity],
+ "ranges": [f.place],
+ }))?;
+ let created = create_relation_type(
+ State(f.state.clone()),
+ AuthUser(editor.clone()),
+ Path(f.kb),
+ axum::Json(req),
+ )
+ .await
+ .map_err(|e| anyhow::anyhow!("create_relation_type: {:?}", e.0))?;
+ let id: Uuid = serde_json::from_value(created.0["id"].clone())?;
+
+ assert_eq!(
+ f.queued().await?,
+ vec!["embed_ontology".to_string(), "align_phrases".to_string()],
+ "the index refresh is queued ahead of the alignment"
+ );
+ assert_eq!(
+ f.vector_of(id).await?,
+ (false, None),
+ "the handler itself does not embed"
+ );
+
+ // 对齐先到:补齐还排着,不问模型,自己排到后面
+ f.script(bound());
+ f.run().await?;
+ assert_eq!(
+ f.requests().len(),
+ 0,
+ "nothing is asked while the index refresh is still queued"
+ );
+ assert_eq!(
+ f.queued().await?,
+ vec!["embed_ontology".to_string(), "align_phrases".to_string()],
+ "the alignment is queued again behind the refresh"
+ );
+
+ // worker 到补齐这一份:跑它的主体,标成完成
+ let embedded = crate::ontology_index::refresh(&f.state, f.kb).await?;
+ assert_eq!(
+ embedded, 8,
+ "the three classes twice over (full text and label) plus based_in and the new property"
+ );
+ sqlx::query(
+ "UPDATE jobs SET status='done' WHERE kind='embed_ontology' AND payload->>'kb_id'=$1",
+ )
+ .bind(f.kb.to_string())
+ .execute(&f.pool)
+ .await?;
+ let (present, text) = f.vector_of(id).await?;
+ assert!(
+ present,
+ "the property is in the vector table before align_phrases runs"
+ );
+ assert_eq!(
+ text.as_deref(),
+ Some("headquarteredIn\nwhere the main office of an entity is"),
+ "label (camel-cased by the store) and description are what was embedded"
+ );
+
+ // 现在对齐开跑,而且新属性在候选里
+ f.run().await?;
+ assert!(
+ !f.requests().is_empty(),
+ "the refresh done, the model is asked"
+ );
+ let prompt = f.prompt_of(0);
+ assert!(
+ prompt.contains("headquartered_in"),
+ "the new property is offered: {prompt}"
+ );
+
+ // 改描述:存下的原文对不上,补齐任务再排、只重嵌这一条
+ f.clear_jobs().await?;
+ let req: RelationTypeReq = serde_json::from_value(json!({
+ "label": "headquartered in",
+ "kind": "relation",
+ "description": "where the head office of an organization sits",
+ }))?;
+ let updated = update_relation_type(
+ State(f.state.clone()),
+ AuthUser(editor),
+ Path((f.kb, id)),
+ axum::Json(req),
+ )
+ .await
+ .map_err(|e| anyhow::anyhow!("update_relation_type: {:?}", e.0))?;
+ assert_eq!(updated.0["ok"], json!(true));
+ assert_eq!(
+ f.queued().await?,
+ vec!["embed_ontology".to_string(), "align_phrases".to_string()],
+ "a changed description queues the refresh ahead of the alignment again"
+ );
+ assert_eq!(
+ crate::ontology_index::refresh(&f.state, f.kb).await?,
+ 1,
+ "only the row whose text changed is re-embedded"
+ );
+ assert_eq!(
+ f.vector_of(id).await?.1.as_deref(),
+ Some("headquarteredIn\nwhere the head office of an organization sits"),
+ );
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ run
+}
diff --git a/crates/utopia-server/src/type_alignment.rs b/crates/utopia-server/src/type_alignment.rs
index 48f79a1b..06847fc0 100644
--- a/crates/utopia-server/src/type_alignment.rs
+++ b/crates/utopia-server/src/type_alignment.rs
@@ -117,6 +117,25 @@ pub async fn align_types_reasking(state: &AppState, kb_id: Uuid, reask: u32) ->
.ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align kind words"))?;
let client = llm_util::chat_client_thinking(&settings)
.ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align kind words"))?;
+ // 本体向量还在补:编辑器建了类先排 `embed_ontology` 再排这个任务,候选类按向量检索
+ // (`candidates_for`),没向量的类检索不到,现在判了它也不在候选里。等它收尾再来——
+ // 排一份半分钟后的,排着的至多一份。短语对齐等这个任务,所以顺序是向量 → 类别词 → 短语
+ if utopia_store::jobs::pending_for_kb(pool, "embed_ontology", kb_id).await? {
+ tracing::info!(%kb_id, "类别词对齐:本体向量还在补,半分钟后再看");
+ let payload = if reask == 0 {
+ serde_json::json!({ "kb_id": kb_id })
+ } else {
+ serde_json::json!({ "kb_id": kb_id, "reask": reask })
+ };
+ utopia_store::jobs::enqueue_unless_queued_after(
+ pool,
+ "align_types",
+ payload,
+ std::time::Duration::from_secs(30),
+ )
+ .await?;
+ return Ok(());
+ }
// 一个库同时只跑一份:抽完每篇、建每个类都会排一次,排队去重只挡「排队中」的,
// 后一个开跑时前一个还在跑就并行了——实测种 14 个类跑出 14 份并行任务,把模型端点
// 打出 502。拿不到锁的直接退出,正在跑的那份会看到同一批词;本轮没判到的下一轮再来
diff --git a/crates/utopia-server/src/type_alignment_tests.rs b/crates/utopia-server/src/type_alignment_tests.rs
index 8d9d8291..ede11c5f 100644
--- a/crates/utopia-server/src/type_alignment_tests.rs
+++ b/crates/utopia-server/src/type_alignment_tests.rs
@@ -176,6 +176,54 @@ fn vote(class: Option<&str>) -> Value {
json!({"b":[[0,class]]})
}
+/// 本体向量还在补时类别词对齐不动手:编辑器建了类先排 `embed_ontology` 再排这个任务,
+/// 候选类按向量检索,没向量的类检索不到。它给自己排一份半分钟后的,补齐收尾后照常判
+#[tokio::test]
+async fn kind_word_alignment_waits_while_the_ontology_index_is_refreshing() -> anyhow::Result<()> {
+ let Some(f) = Fx::new(vec![vote(Some("organization")), vote(Some("organization"))]).await?
+ else {
+ return Ok(());
+ };
+ let run = async {
+ sqlx::query("INSERT INTO jobs (kind, payload) VALUES ('embed_ontology', $1)")
+ .bind(json!({ "kb_id": f.kb }))
+ .execute(&f.pool)
+ .await?;
+ f.run().await?;
+ assert_eq!(
+ f.requests().len(),
+ 0,
+ "nothing is asked while the ontology index is still being refreshed"
+ );
+ let deferred: Vec<(String, bool)> = sqlx::query_as(
+ "SELECT status, run_at > now() FROM jobs
+ WHERE kind='align_types' AND payload->>'kb_id'=$1",
+ )
+ .bind(f.kb.to_string())
+ .fetch_all(&f.pool)
+ .await?;
+ assert_eq!(
+ deferred,
+ vec![("queued".to_string(), true)],
+ "one kind-word round is queued for later"
+ );
+ sqlx::query("DELETE FROM jobs WHERE payload->>'kb_id'=$1")
+ .bind(f.kb.to_string())
+ .execute(&f.pool)
+ .await?;
+ f.run().await?;
+ assert_eq!(
+ f.requests().len(),
+ 2,
+ "the refresh gone, the two votes are asked"
+ );
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ run
+}
+
#[tokio::test]
async fn disagreement_retracts_previous_aligned_type() -> anyhow::Result<()> {
let Some(f) = Fx::new(vec![vote(Some("organization")), vote(None)]).await? else {
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 c8c543a9..2950f9b8 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
@@ -1,6 +1,6 @@
# 0061 · The ontology is proposed from the open graph and judged by its questions
-- **Status**: Accepted 2026-09-26 · 0044 cut 5 · cut 1 built (#947, migration 0077): competency questions are rows, the agent proposes from unbound signatures and kind words into `ontology_proposals`, adoption writes the element and re-decides its shapes through alignment · cut 1.1 (#950, migration 0078): the agent records every shape it saw, "already in the ontology" becomes a map_to proposal adopted as a person's binding per shape, adoption embeds the element before alignment · measured on a 100-document base: ~9k tokens a call, 12 calls a round, about half of a round's proposals adoptable as-is · cut 3 first slice (#955, migration 0079): the agent proposes questions for a base with none, `competency.mjs` asks the accepted ones through chat and the two numbers are reported (11 of 11 on the bench base) · cut 2, the rest of cut 3 (FDA and statistics corpora) and cut 4 open · the ontology agent reads the open graph's unbound signatures and kind words against the base's competency questions and proposes types, properties and rules with definitions, examples and the signatures they would bind; approval writes the ontology and re-decides those signatures; every approved element carries regression cases; the ontology is measured by the questions it answers
+- **Status**: Accepted 2026-09-26 · 0044 cut 5 · cut 1 built (#947, migration 0077): competency questions are rows, the agent proposes from unbound signatures and kind words into `ontology_proposals`, adoption writes the element and re-decides its shapes through alignment · cut 1.1 (#950, migration 0078): the agent records every shape it saw, "already in the ontology" becomes a map_to proposal adopted as a person's binding per shape, adoption embeds the element before alignment, and the editor's create and update handlers queue the same refresh ahead of alignment, which waits for it · measured on a 100-document base: ~9k tokens a call, 12 calls a round, about half of a round's proposals adoptable as-is · cut 3 first slice (#955, migration 0079): the agent proposes questions for a base with none, `competency.mjs` asks the accepted ones through chat and the two numbers are reported (11 of 11 on the bench base) · cut 2, the rest of cut 3 (FDA and statistics corpora) and cut 4 open · the ontology agent reads the open graph's unbound signatures and kind words against the base's competency questions and proposes types, properties and rules with definitions, examples and the signatures they would bind; approval writes the ontology and re-decides those signatures; every approved element carries regression cases; the ontology is measured by the questions it answers
- **Written**: 2026-09-26 (conventions in the [README](README.md))
- **Related**: [0044](0044-the-ontology-is-a-view-over-what-documents-say.md) §4 decided the workbench and named this cut; [0003](0003-ontology-growth-loop.md) grew the ontology from `ontology_misses` and surface predicates, which [0044](0044-the-ontology-is-a-view-over-what-documents-say.md) cut 1 left idle and #725 retires; [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) makes every element a contract a person signed, which this record keeps; [0053](0053-a-phrase-decision-records-the-inputs-it-considered.md) is what makes approval re-decide signatures without a new mechanism; [0008](0008-ontology-packs-as-cold-start.md) is the second of the three sources; [0043](0043-every-review-queue-is-governed.md) and #725 give the queue its shape. From #725's "Ontology proposals" row and 0044's open question about a base with no questions.
diff --git a/docs/design/ontology.md b/docs/design/ontology.md
index bc3cbf02..cad1702c 100644
--- a/docs/design/ontology.md
+++ b/docs/design/ontology.md
@@ -68,7 +68,13 @@ bind. When the structure fits more than ten properties (a coarse class hierarchy
the aligner opens a **shortlist**: the signature's phrase and one example sentence are embedded and
the ten properties nearest by the ontology's own vectors (`embed_ontology`) are shown, plus any whose
label shares a word with the phrase; without an embedding model the model sees every structural
-candidate. The shortlist is part of the decision's basis, so a changed list re-asks. The candidate
+candidate. A property without a vector never enters the shortlist, so the fingerprint of the
+shapes it could bind does not change and they are never re-decided: every path that adds or
+relabels an element therefore refreshes the index before alignment. The ontology agent's adoption
+refreshes it in place [0061 cut 1.1]; the editor's create and update handlers queue
+`embed_ontology` ahead of the alignment job, and both aligners wait while that job is queued or
+running, so the order is vectors, then kind words, then phrases. The shortlist is part of the
+decision's basis, so a changed list re-asks. The candidate
properties are described once per batch and each item names only its keys. 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`. Candidates are the properties whose