Skip to content

World's first open-source enterprise world model.

The records catch up with the code, and say what comes next (#188)

WaylandYang9446f8255006
diff --git a/Cargo.lock b/Cargo.lock
index afdd530a..1710a8ee 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4734,10 +4734,6 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
-[[package]]
-name = "utopia-connectors"
-version = "0.1.0"
-
[[package]]
name = "utopia-core"
version = "0.1.0"
@@ -4765,10 +4761,6 @@ dependencies = [
"utopia-llm",
]
-[[package]]
-name = "utopia-graph"
-version = "0.1.0"
-
[[package]]
name = "utopia-ingest"
version = "0.1.0"
@@ -4806,10 +4798,6 @@ dependencies = [
"tracing",
]
-[[package]]
-name = "utopia-mcp"
-version = "0.1.0"
-
[[package]]
name = "utopia-reason"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index af52b8aa..36502a06 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -6,12 +6,9 @@ members = [
"crates/utopia-server",
"crates/utopia-ingest",
"crates/utopia-extract",
- "crates/utopia-graph",
"crates/utopia-reason",
"crates/utopia-search",
"crates/utopia-llm",
- "crates/utopia-mcp",
- "crates/utopia-connectors",
]
[workspace.package]
diff --git a/crates/utopia-connectors/Cargo.toml b/crates/utopia-connectors/Cargo.toml
deleted file mode 100644
index c7916a4c..00000000
--- a/crates/utopia-connectors/Cargo.toml
+++ /dev/null
@@ -1,7 +0,0 @@
-[package]
-name = "utopia-connectors"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-
-[dependencies]
diff --git a/crates/utopia-connectors/src/lib.rs b/crates/utopia-connectors/src/lib.rs
deleted file mode 100644
index f1171457..00000000
--- a/crates/utopia-connectors/src/lib.rs
+++ /dev/null
@@ -1,3 +0,0 @@
-//! utopia-connectors: placeholder. External source connectors (S3/WebDAV, Notion,
-//! Feishu) live here once built; today's web and RSS sync is in utopia-server.
-//! See the Roadmap in README.md.
diff --git a/crates/utopia-graph/Cargo.toml b/crates/utopia-graph/Cargo.toml
deleted file mode 100644
index 22901933..00000000
--- a/crates/utopia-graph/Cargo.toml
+++ /dev/null
@@ -1,7 +0,0 @@
-[package]
-name = "utopia-graph"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-
-[dependencies]
diff --git a/crates/utopia-graph/src/lib.rs b/crates/utopia-graph/src/lib.rs
deleted file mode 100644
index 9c14917b..00000000
--- a/crates/utopia-graph/src/lib.rs
+++ /dev/null
@@ -1,3 +0,0 @@
-//! utopia-graph: placeholder. Graph traversal and neighborhood queries currently
-//! live in utopia-store; this crate is where they land once they outgrow it.
-//! See the Roadmap in README.md.
diff --git a/crates/utopia-mcp/Cargo.toml b/crates/utopia-mcp/Cargo.toml
deleted file mode 100644
index 3e404620..00000000
--- a/crates/utopia-mcp/Cargo.toml
+++ /dev/null
@@ -1,7 +0,0 @@
-[package]
-name = "utopia-mcp"
-version.workspace = true
-edition.workspace = true
-license.workspace = true
-
-[dependencies]
diff --git a/crates/utopia-mcp/src/lib.rs b/crates/utopia-mcp/src/lib.rs
deleted file mode 100644
index f599daef..00000000
--- a/crates/utopia-mcp/src/lib.rs
+++ /dev/null
@@ -1,3 +0,0 @@
-//! utopia-mcp: placeholder. MCP server exposing knowledge and agent memory as
-//! tools (add_memory / search_memory / get_entity_timeline).
-//! See the Roadmap in README.md.
diff --git a/crates/utopia-server/src/bootstrap_ontology.rs b/crates/utopia-server/src/bootstrap_ontology.rs
index 0f566c3f..3b76f7a2 100644
--- a/crates/utopia-server/src/bootstrap_ontology.rs
+++ b/crates/utopia-server/src/bootstrap_ontology.rs
@@ -1,8 +1,9 @@
//! 自动扩本体:抽取遇到本体外的说法时,把它补进本体并改写等它的那些事实。
//!
-//! 新建的库只有 10 个默认关系——那不是任何人选的,是种子数据。传进第一批
-//! 文档,里面的关系大半不在这 10 个里,于是大量事实降级成 related_to,
-//! 图基本没法用,直到有人坐下来点 Suggest、看提案、逐条 Add。
+//! 新建的库不种任何关系,起点是用户挑的本体包(0008)或者空着。包再大也装不下
+//! 一份语料的全部说法:落不上本体的事实谓词留空、原词记在证据上(0010),
+//! 图上这些边只有原文措辞、没有词表语义,直到有人坐下来点 Suggest、看提案、逐条 Add。
+//! 这个模块把那件事自动化:说法够普遍就建成关系,并把等着它的事实改写过去。
//!
//! 敢这么做的前提是采纳可撤销(见 graph::unadopt):错了点一下就回去,
//! 旧事实从来没被销毁过。所以判断轴不是"有多确信"而是"错了有多贵"。
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index 41652dba..50f5d553 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -310,31 +310,6 @@ pub async fn insert_value_fact(
.await
}
-/// 已确认(置信 ≥ threshold)的问数映射:概念名 + 定义。问数 prompt 注入用。
-pub async fn confirmed_mappings(
- pool: &PgPool,
- kb_id: Uuid,
- threshold: f32,
- limit: i64,
-) -> AppResult<Vec<(String, serde_json::Value)>> {
- let rows: Vec<(String, serde_json::Value)> = sqlx::query_as(
- "SELECT s.canonical_name, f.object_value
- FROM facts f
- JOIN relation_types r ON r.id = f.predicate_id AND r.key = 'mapped_to'
- JOIN entities s ON s.id = f.subject_id
- WHERE f.kb_id = $1 AND f.invalidated_at IS NULL AND f.valid_to IS NULL
- AND f.object_value IS NOT NULL AND f.confidence >= $2
- ORDER BY s.canonical_name
- LIMIT $3",
- )
- .bind(kb_id)
- .bind(threshold)
- .bind(limit)
- .fetch_all(pool)
- .await?;
- Ok(rows)
-}
-
/// `proposed`:模型在这一块里实际提议的谓词。命中本体时它等于 key,
/// 本体外的谓词不落到关系上时,它是唯一还留着原意的东西——事实行上只剩
/// "有关联",原文说的"runs on"就靠这里活下来。
@@ -806,23 +781,8 @@ pub async fn confirm_fact(pool: &PgPool, kb_id: Uuid, fact_id: Uuid) -> AppResul
if res.rows_affected() == 0 {
return Err(AppError::NotFound);
}
- // 问数映射的口径唯一性:确认 (概念, 源) 的新定义 = 背书替换,同源旧映射作废。
- // 认知轴修正(旧口径是"我们当时的理解",不是世界里结束的状态);
- // 唯一性只活在这条确认流里,时态引擎保持领域无关。
- sqlx::query(
- "UPDATE facts f SET invalidated_at = now()
- FROM facts nf
- JOIN relation_types r ON r.id = nf.predicate_id
- WHERE nf.id = $1 AND r.key = 'mapped_to'
- AND f.kb_id = $2 AND f.id <> nf.id
- AND f.subject_id = nf.subject_id AND f.predicate_id = nf.predicate_id
- AND f.invalidated_at IS NULL
- AND f.object_value->>'source' = nf.object_value->>'source'",
- )
- .bind(fact_id)
- .bind(kb_id)
- .execute(pool)
- .await?;
+ // 从前这里还有一段:确认 `mapped_to` 事实时把同 (概念, 源) 的旧映射作废。
+ // 映射已搬出账本(0011,`concept_mappings` 自己管唯一性),那段 SQL 恒匹配零行,删了。
Ok(())
}
diff --git a/crates/utopia-store/src/reasoning.rs b/crates/utopia-store/src/reasoning.rs
index 15b39ff8..56db5af4 100644
--- a/crates/utopia-store/src/reasoning.rs
+++ b/crates/utopia-store/src/reasoning.rs
@@ -456,7 +456,7 @@ async fn compile_rules(
if a.symmetric {
want.push((pred, "symmetric"));
}
- // 后两种是 0017 补上的规则源。**规则挂在「有声明的那一侧」**——
+ // 后两种是迁移 0016(a_relation_can_name_its_inverse)补上的规则源。**规则挂在「有声明的那一侧」**——
// 归一化过的逆两边都有声明,所以两个方向各得一条规则,与它们各自
// 推出的派生对得上
if a.inverse_of.is_some() {
diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rs
index 8376ba68..e794f31d 100644
--- a/crates/utopia-store/src/resolution.rs
+++ b/crates/utopia-store/src/resolution.rs
@@ -106,8 +106,11 @@ pub fn recall_keys(name: &str) -> Vec<String> {
/// 易混具体类型:抽取常在这几类间摇摆(一个团队算组织还是项目?平台算项目还是产品?)。
/// 同名跨这组类型 → 照建实体(宁分勿合),但入队审核对交 LLM/人工裁决。
-/// DESIGN.md §3.2 的 disjoint 公理目前只是设计面(0005 仅落了 subClassOf 数据面),
-/// 公理落库后这张表应改从本体读取。
+///
+/// **这张表该从本体读,今天还没有。** `owl:disjointWith` 已经落库(`entity_type_disjoint`,
+/// 有导入有编辑),但消费者只有推理机的本体自检;消解这边仍按这三个硬编码的 key 判。
+/// 没装包的库里这三个 key 不存在,于是这一档永不命中,所有跨类型同名判 `Disjoint`——
+/// 变严不变松,不会错合。改从本体读是 0016 的 B3。
pub const CONFUSABLE_TYPE_KEYS: &[&str] = &["organization", "project", "product"];
/// 单次消解最多入队的漂移审核对(防同名大组刷爆审核队列)。
diff --git a/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs b/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs
index 870eda7e..51b32441 100644
--- a/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs
+++ b/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs
@@ -1,4 +1,4 @@
-//! 个人访问令牌(0014 / 迁移 0015)。
+//! 个人访问令牌(0014 / 迁移 0017)。
//!
//! 这一枚令牌是给 MCP 客户端用的:长命、配在别人机器上的一个文件里、以发它的
//! 人的身份行事。所以它必须撤得掉、过得了期、而且**范围只能比这个人更小**。
diff --git a/docs/decisions/0001-ontology-import-and-governance.md b/docs/decisions/0001-ontology-import-and-governance.md
index c709bcf5..c63cf84d 100644
--- a/docs/decisions/0001-ontology-import-and-governance.md
+++ b/docs/decisions/0001-ontology-import-and-governance.md
@@ -1,6 +1,6 @@
# 0001 · 本体导入与治理路线
-- **状态**:进行中 · P0(实体可编辑)、P1(停止静默丢弃)、P2(OWL 导入)、P2c(属性落库 / 关联表 / 类型签名 / 多继承)已建成;P3a(类型消解)已建成但检索命中率不足以自动跑,见下方修订记录;P3b 部分建成,见 [0003](0003-ontology-growth-loop.md);**P4a(决策不可被遗忘)已建成,P4b/P4c 待做**;P5 由 [0002](0002-reasoning-engine.md) 取代
+- **状态**:进行中 · P0 / P1 / P2 / P2c 全部建成;P3 的「按预算切换」已落地(部署级 `ontology_prompt_budget`,缺省 24,000 字符,超了按块检索),P3a 建成但**只能手动触发**、没有类数阈值这根轴;P3b 两条腿都建成但形态与本文不同(原词落 `fact_evidence.proposed_predicate`,映射由 `predicate_match` + [0003](0003-ontology-growth-loop.md) 的采纳回路承担);**P4a 已建成,P4b / P4c 仍待做**;**P5 已由 [0002](0002-reasoning-engine.md) 落地,`utopia-reason` 不再是空壳**;判据 2 关于「参数顺序」的那一半已被 [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 推翻。2026-09-02 对照代码复核,修订就地
- **成文**:2026-08-27 / 28,随调研持续修订(约定见 [README](README.md))
> 理由比清单重要——清单会过期,理由决定以后遇到新情况怎么判。所以本文把「贯穿性判据」放在分阶段之前,且推翻过的判断就地留痕(见 P1、P3 的修订记录)。
@@ -51,6 +51,7 @@
1. **不是"OWL 有没有",是"我们有没有机器消费它"**——但要加时间维度:**丢弃不可逆,保存近乎免费**。所以原文一律保真,投影只覆盖当下用得上的。推论:**保留了原文,投影就不必语义完整**——简化是 UI/提示词层的取舍,不是数据损失。
2. **本体是引导,不是执法**。声明可能是错的(`part_of` 就是),所以本体应当影响提示词与候选排序,而不是驱动丢弃、覆盖、自动改写。错误的引导模型能靠原文覆盖;错误的执法会系统性地毁数据。
+ > **修订(2026-09-02,据 [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md))**:这条要拆成两半。**哪些类型能参与**仍是引导——本体可能写错,原文说西雅图就写西雅图。**参数顺序**改成执法:它不是关于世界的断言,是这个 key 的编码约定,原文从来没有「说了别的方向」。主语违反 domain 而宾语符合时按签名对调,留 `direction_corrected` 痕迹;对调也不合法则丢掉谓词、保留主宾与证据。留痕的自动动作不属于本条反对的那一类。实测五轮:违反率 57% → 4%,真·反向 39 → 0。
3. **提示词大小必须与本体规模脱钩**。把 N 个类塞进每个分块的提示词,成本是 O(分块 × 本体),而且模型从 800 个选项里挑反而更差。规模问题用检索解,不用"少列几个"解。
4. **同名不能传递任何结论**。判定为同一实体 → 本来就一个类型,无所谓传递;判定为不同 → 名字正是我们刻意不信任的信号(两个张伟)。能携带信息的是上下文。
5. **不确定性浮到人面前**,不要悄悄猜。分层阈值 + 灰区进 Review,与消解的"宁分勿合"同源。
@@ -96,9 +97,9 @@
| 269 | 既无 `value` 也无 `object` | 真丢弃 |
| 274 | datatype 归一化失败 | 有 `debug!` 日志,但用户不可见 |
-关系路径另有两条值得记:`confidence < 0.6`(第 234 行,设计阈值,但同样不可见——用户无从知道"抽到了但不够自信")与 `related_to` 不在本体时**整条事实消失**(第 380 行,删掉默认关系就会踩到)。
+关系路径另有两条值得记:`confidence < 0.6`(第 234 行,设计阈值,但同样不可见——用户无从知道"抽到了但不够自信")与 `related_to` 不在本体时**整条事实消失**(第 380 行,删掉默认关系就会踩到)。〔**后者已不可能发生**:`related_to` 整个删掉,落不上就是 `predicate_id = NULL`,见 [0010](0010-no-relation-is-no-relation.md)。〕
-**顺带发现一个不一致**:关系路径上主宾未声明时会**兜底按 `concept` 消解**(332-362 行),属性路径上同样的缺失却直接丢(255 行)。同一个原因,一边宽容一边静默丢弃。要么两边都兜底,要么两边都记信号——不能一边一个样。
+**顺带发现一个不一致**:关系路径上主宾未声明时会**兜底按 `concept` 消解**(332-362 行),属性路径上同样的缺失却直接丢(255 行)。同一个原因,一边宽容一边静默丢弃。要么两边都兜底,要么两边都记信号——不能一边一个样。〔**已消除**:`concept` 兜底类随 [0009](0009-no-type-is-a-type.md) 删掉,两条路径现在都记 `subject_not_declared`。丢弃原因码今天有 12 个(`extraction_drops::reason`),含 `truncated_reply`、`malformed_item`、`not_an_entity_name`、`direction_corrected`,比本节设想的多一倍。〕
**做**
- 新表 `extraction_drops (kb_id, document_id, reason, detail, count, example, updated_at)`,PK `(kb_id, document_id, reason, detail)`,抽取开始时按 document 清空
@@ -179,7 +180,7 @@ v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_membe
**个体(ABox)永不作为事实导入**——不是能力问题,是原则:每条事实必须有证据链和出处,凭空塞进来的实例破坏的正是这个地基。它们随原文件保存,将来推理机可当背景知识读。
-**依赖**:`oxttl` + `oxrdfxml`(Oxigraph 那套小而专的 crate)。不引 `horned-owl`,我们不需要推理。工作区目前无任何 RDF 依赖。
+**依赖**:`oxttl` + `oxrdfxml`(Oxigraph 那套小而专的 crate)。不引 `horned-owl`,我们不需要推理。工作区目前无任何 RDF 依赖。〔已引入,住在 `utopia-ingest`。〕
> **修订记录 · P2a + P2b 已落地**(`feat/owl-import`)
>
@@ -199,8 +200,10 @@ v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_membe
> 哪个**——这正是本文论证 IRI 必要性时用的那个例子,只是换了个方向出现。所以:
> 报告,不解决。想要导入的那份,先给现有的改名。
>
+> 〔**后来改了一半**(#78、#145):本地同名行**没有 IRI**时被认领——它是种子或手工建的占位者,被词表接管否则整棵树是断的;认领时形状跟着改成「方」(词表声明的)。两边都有 IRI 而 key 撞车的仍然报告不解决。〕
+>
> **暂未落地的三件**——属性落库、domain/range 关联表与类型签名、多继承 DAG——
-> 照着 P2b 的产物重新算过账,独立成节:见下方 **P2c**。初稿在这里写的依赖顺序
+> 照着 P2b 的产物重新算过账,独立成节:见下方 **P2c**。〔四件均已落地,见 P2c 末尾。〕初稿在这里写的依赖顺序
> 有一处高估了(属性落库要等的那个映射,P2b 里已经建好了),那节里就地留痕。
>
> **一个自己犯的错值得记**:`OntologyImportView` 的字段叫 `imported_at`,前端类型
@@ -342,6 +345,10 @@ OWL 里一个属性有多个 domain 是常态。`datatype` 仍留在 `relation_t
前三项是一条链,第四项可以并行。
+> **修订记录(2026-09-02):四项全部建成。** 属性由导入器建(`create_attribute_with_iri`);`relation_type_domains` / `relation_type_ranges` 建表;
+> 签名进提示词(`works_at (person → organization)`),且只提铺出去的类,整侧没选中退回 `*`;`parent_id` 单列**已不存在**,多父落 `entity_type_parents`(带 `is_primary` 供左栏画树),
+> 判定改成广度优先加访问集。另一处与本文不同:`update_relation_type` 现在**允许改 domain / range**——签名不是身份,`kind` 仍不可变。
+> 全部 OWL 公理的投影现状见 P5 的修订。
---
@@ -379,6 +386,9 @@ OWL 里一个属性有多个 domain 是常态。`datatype` 仍留在 `relation_t
> 跟着裁。预算按 token 数而不是类数量——类描述长度差着数量级。**预算定在哪还没量**,
> 那需要把内联类数从 12 逐级加到 968,看事实数与耗时在哪一档开始掉。
>
+> 〔**已落地**,见 [0006](0006-ontology-scale-and-the-prompt.md):预算按**字符**而非 token,落在 `deployment_settings.ontology_prompt_budget`(24,000),每块 40 类 / 30 关系 / 30 属性,三个数都标着「待测」。
+> 「种子基类永远在场」在 #128 之后失效(没有种子了),换成**祖先补齐**:命中什么就把它的祖先一起铺出去。本文下方与开放问题里的「阈值 30」这根轴**从未存在过**。〕
+>
> **三、第二层建成了,但比原文写的复杂**,见下。
#### P3a · 类型消解实测(已建成)
@@ -470,7 +480,7 @@ related_to 事实 359 条
**放在 `fact_evidence` 上,不是 `facts` 上**:`insert_fact_inner`(`graph.rs:164-175`)按 `(kb_id, subject_id, predicate_id, object_id)` 对存活事实去重,所以一条 `(A, related_to, B)` 会吸收多个分块——甲块说 "runs on"、乙块说 "optimized for",合并成同一行。放 `facts` 上就是**先写者胜、其余静默丢弃**,正是本条要修的毛病。`fact_evidence` 每分块一行、已带 `quote`(该块的原文佐证),表层谓词是同一种东西:每次观察的原始形态。粒度对,且无需新增语义。
-加 `fact_evidence.surface_predicate TEXT`,两条路径都写(关系路径写降级前的 `f.predicate`;正常命中时写模型实际给的那个词,因为它可能是别名)。不等映射落地就有独立价值——Review 与实体面板可直接展示"原文说的是 available from,被降级成 related to",而今天前端对 `related_to` 无任何特殊处理(`web/src/` 里零命中),降级对用户完全不可见。
+加 `fact_evidence.surface_predicate TEXT`〔落地时列名叫 **`proposed_predicate`**,下同〕,两条路径都写(关系路径写降级前的 `f.predicate`;正常命中时写模型实际给的那个词,因为它可能是别名)。不等映射落地就有独立价值——Review 与实体面板可直接展示"原文说的是 available from,被降级成 related to",而今天前端对 `related_to` 无任何特殊处理(`web/src/` 里零命中),降级对用户完全不可见。
**映射不取代 miss 报表**:反复出现又映射不上的(`available_from ×9`)正是"本体该加这个关系"的治理信号(P4 燃料)。映射只吃高置信的那部分,其余留在 miss 里变建议。
@@ -486,6 +496,10 @@ related_to 事实 359 条
**第一次抽取一定有类型**:`entities.type_id NOT NULL`,没有"未分类"状态。粗类是真类型不是占位符,小本体下它就是最终类型。升格挂在文档抽取完成的同一条任务链上(与攒批裁决并列),窗口是秒级。
+> **修订记录(2026-09-02):这一段两句都反了。** `type_id` 已改为可空([0009](0009-no-type-is-a-type.md)),「没有类型」就是没有类型,且可能是**人的决定**(`type_source = human`)。
+> 「升格挂在同一条任务链上」**没有实现**:抽取结束只入队 `bootstrap_ontology` 与 `adjudicate_entities`,类型消解今天只能在本体页手动跑 preview → apply。
+> 原因见 P3a——检索命中率不足以自动跑。这是一个真缺口,不是取舍:**大本体下新实体的细化依赖人记得去点一下**。
+
---
### P4 · 治理即经验
@@ -532,7 +546,7 @@ related_to 事实 359 条
> **排期已由 [0002](0002-reasoning-engine.md) 取代**。本节列的"届时能消费什么"仍然成立,但顺序变了:0002 实测发现语料第一天就带 `part_of` 环(传递闭包在深度 5 起振荡不收敛),所以推理机的第一交付是**一致性检查**而非推导——同一套求值引擎反过来用,零风险,且现存 11 处矛盾立刻可查出。
-`utopia-reason` 目前是 3 行空壳。它上线后能消费的,正是 P2 保留而未投影的那些公理:
+`utopia-reason` 目前是 3 行空壳〔**已建成**,近两千行:R0 一致性检查与本体自检、R1 物化推导带开关,见 [0002](0002-reasoning-engine.md) 的修订〕。它上线后能消费的,正是 P2 保留而未投影的那些公理:
- `TransitiveProperty` → "NVIDIA 名下所有东西"(现在只能靠 hops 逐跳猜)
- 非 1 的基数被违反 → **一致性告警进 Review 队列**,本体成为数据质量规则
@@ -542,14 +556,19 @@ related_to 事实 359 条
**这些今天全部读不了,但 P2 的原文保真保证了届时无需用户重新上传。**
+> **修订记录(2026-09-02):大半已经读得了。** 投影落库的公理:`TransitiveProperty` / `SymmetricProperty` / `AsymmetricProperty` / `IrreflexiveProperty` / `FunctionalProperty` / `InverseFunctionalProperty` / `disjointWith` / `inverseOf` / `subPropertyOf`。
+> 仍在「暂未投影」里的:`equivalentClass`、`someValuesFrom` 与类表达式、属性链。
+> 上面五条的兑现情况:Transitive 进 R1 规则(带环检测与每谓词封顶);基数违反进 `axiom_violations` 由 Review 裁;`equivalentClass` / 类表达式未做;`inverseOf` 与 `subPropertyOf` 进 R1(#177 / #179);
+> **`disjointWith` 只兑现一半**——导入落了 `entity_type_disjoint`,消费者只有 R0 的本体自检(类不可满足),消解侧的 `classify_type_drift` 仍用硬编码的 `CONFUSABLE_TYPE_KEYS`,[0009](0009-no-type-is-a-type.md) 点名的「改从本体读」没做。
+
---
## 开放问题
- **升格准确率给不出数**——需要真实企业本体做小样本评测,现在只有推演
- **`active` 标记的定位**:原本当规模解药(错,规模应由 P3 的检索解),现在只剩治理用途(弃用的旧类不参与分配)。是否值得单独做,等有真实大本体再定
-- **阈值 30 是拍的**——类数超过多少才启用类型消解,需要实测校准
-- **`disjointWith` 与 `SymmetricProperty` 收益中等**:前者剪枝防错误合并;后者去重(新语料里测得 8 对互为反向的重复事实,占 910 条的 1%)。排在 P2 之后按需
+- **阈值 30 是拍的**——类数超过多少才启用类型消解,需要实测校准〔这根轴不存在,换成了字符预算;新的待测量是每块 40 / 30 / 30,见 [0006](0006-ontology-scale-and-the-prompt.md)〕
+- **`disjointWith` 与 `SymmetricProperty` 收益中等**:前者剪枝防错误合并;后者去重(新语料里测得 8 对互为反向的重复事实,占 910 条的 1%)。排在 P2 之后按需〔Symmetric 已进 R0 检查与 R1 规则;disjointWith 进了本体自检,**消解侧剪枝仍未做**〕
---
@@ -557,4 +576,6 @@ related_to 事实 359 条
`Industry Corpus` 库保留着(NVIDIA 博客 18 篇 + 微软新闻室 10 篇,RSS 摄入),是上面所有数字的来源,也是后续所有评测的基线——改动前后跑同一个库,数字才可比。别在它上面做破坏性实验。
+〔**2026-09-02**:基线已换。种子本体退场后这个库的起点不可复现,现在的基准是 `scripts/bench/` 上可重跑的语料,本体侧用 `ai-timeline-ends × schema.org + W3C Org`([0012](0012-the-ontology-is-a-contract-not-a-suggestion.md))。本文的数字仍是当时的真实测量,只是不再能与今天对比。〕
+
分支状态不记在这里:git 自己知道,写进文档只会过期。
diff --git a/docs/decisions/0002-reasoning-engine.md b/docs/decisions/0002-reasoning-engine.md
index f3f844bc..a953cf70 100644
--- a/docs/decisions/0002-reasoning-engine.md
+++ b/docs/decisions/0002-reasoning-engine.md
@@ -1,6 +1,6 @@
# 0002 · 推理机
-- **状态**:规划中 · `utopia-reason` 目前是 3 行占位
+- **状态**:R0 已建成(事实层四类违规 + 本体自检八类缺陷,两张表两个 Review 页签);R1 已建成,受 KB 开关 `materialize_inferences` 约束、**默认关**,四种公理规则都编得出(#132、#177、#179);R2 只做了一层直接前提,证明树 API / UI 未建;R3 未做,每次全量重推,靠 `inference_interval_minutes`(缺省 60)定时兜着。2026-09-02 对照代码复核,修订见各节
- **成文**:2026-08-28
- **相关**:[0001](0001-ontology-import-and-governance.md) 的 P5(该节保留原判断,本文取代其排期)
@@ -54,6 +54,11 @@ CREATE TABLE fact_derivations (
这同时是 "with explanations" 的落点:**解释 = 前提集 + 规则**,递归展开成证明树,叶子才是真正的 chunk。`facts.derived_by_rule` 列在 `0004_graph.sql:71` 就留好了,至今零使用——它等的就是这个。
+> **修订记录(2026-09-02):形状不是这样,而且那一列没等到。** 落地时**派生事实不进 `facts`**,另建 `derived_facts`,迁移 `0013_reasoning.sql` 给了三条理由:
+> 四十多处读 `facts` 的查询只有一处认识那个标记,新写一条查询默认就把派生当断言看,**失败方向反了**——分开之后忘了 UNION 的后果是看不见派生,而不是混进去;列本来就不一样;数量级差一档。
+> `fact_derivations` 的实际列是 `(derived_fact_id, premise_fact_id, seq)`,规则挂在 `derived_facts.rule_id` 上。`facts.derived_by_rule` 今天仍然零写入,唯一引用是 Review 的一处过滤。
+> 这条「失败方向」的判据后来被 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 原样引用去否掉了 `facts.nod` 列。
+
### 2. 派生事实绝不能闭合断言事实
`reconcile_new_fact`(`temporal.rs:49`)对 functional 谓词会自动闭合旧事实。派生事实若走同一条路,**一条错规则就能系统性闭掉人工断言的事实**——`part_of` 那个坑的十倍版,而且这次是自动化的。
@@ -68,12 +73,19 @@ CREATE TABLE fact_derivations (
这是 0001 判据 2「本体是引导不是执法」在推理层的同一条:**声明可能是错的,所以它不能驱动对既有数据的改写。**
+> **修订记录(2026-09-02)**:表格三行里只有第一行的前半兑现了——`asserted` 硬性优先,已断言的三元组不再派生(`derive.rs`)。
+> 「记一条规则与事实矛盾的信号」**没有**,「派生 vs 派生进 Review」**没有**(同一三元组的多条推导只留第一条证明)。两者都还是待做。
+
### 3. 前提撤回时——双时态是最优解,不是负担
不能 UPDATE(append-only 是地基)。做法是置 `invalidated_at`,与拒绝一条事实**完全同构**。派生事实的记录轴上于是留下"我们曾据此推出,后来前提没了"。
真值维护在别的系统里是苦活(要么标记删除要么重算全量),在这个数据模型里是既有机制的自然延伸——**而且实体历史页面(PR #37)直接就能展示它**,不需要新 UI。
+> **修订记录(2026-09-02)**:「实体历史直接能展示」**没兑现**——`entity_history` 的 UNION 只有 facts / merges / retypes 三段,不含 `derived_facts`。
+> 派生的可见性落在别处:实体面板单独一档「推出来的」、图上金色专属边(派生为零时开关整个不出现、逆关系推出来的边并到同一条弧上)。
+> 而且今天没有「前提撤回」这个增量动作,R3 未做,每次全量重推并整体对账。
+
---
## 分步
@@ -87,6 +99,13 @@ CREATE TABLE fact_derivations (
价值在于:引擎的难点(规则表示、求值、终止)全部建成并验证,而风险面为零——它不写 `facts` 表。
+> **修订记录(2026-09-02):R0 建成,四处与上面写的不同。**
+> 一、**四类不是三类,且不是那三类**:`self_loop` / `asymmetry` / `cycle` / `functional`(兼含 inverse_functional)。**事实层的 disjointWith 违反没有做**——disjoint 只进了本体自检。
+> 二、**不进 `fact_conflicts`,另建 `axiom_violations`**:那张表问的是「哪条对」,公理违规问的是「错在数据还是错在定义」,出路是 `fact_retracted` / `axiom_relaxed` / `accepted`。「零新界面」也没守住,Review 页多了 `violations` 与 `defects` 两个页签。
+> 三、**多出另一半:本体自身的自洽性**(`ontology_defects`,八类:symmetric 且 asymmetric、transitive 且 functional、子类成环、与祖先 disjoint、继承来的 disjoint、自逆、逆没指回来、子属性成环)。理由是自相矛盾的本体会让事实层的结论全部可疑,所以缺陷优先于违规展示。
+> 四、环检测是深度优先不是半朴素——闭包只告诉你 A 推出了 A,人要的是**路径**;半朴素在 R1。
+> 另:没装本体包的库跑出来是零,那是实情不是故障——没有公理就没有判据。本文「现存 11 处矛盾」的前提(种子本体带 `functional` 声明)已不存在。导入本体后会自动跑一次检查:公理刚变,正是最该重算的时刻。
+
### R1 · 物化推导(打开开关)
- `rules` 表 + `fact_derivations` 表
@@ -95,19 +114,24 @@ CREATE TABLE fact_derivations (
- 深度上限 + 环检测(实测必需)
- 派生事实在图上可视觉区分,且可整体过滤
+> **修订记录(2026-09-02):R1 建成。** `rules` / `derived_facts` / `fact_derivations` 三张表;开关 `materialize_inferences` 默认 FALSE,`inference_interval_minutes` 默认 60,调度器每分钟扫到期库入队,作业里**先记时间再推**防失败循环;开关关着时端点回明确错误而非静默跳过。
+> 规则从四种公理编译:Transitive / Symmetric(#132)、inverseOf / subPropertyOf(#177 / #179,投影侧在迁移 `0016`)。逆的归一化放在载入公理那一处,只补空缺不覆盖人写的,两边指得不一样留给 R0 报 `inverse_not_mutual`。
+> **单谓词封顶 20,000 条,被截掉必须说出来**(`capped`);另有一个正常恒为零的 `unruled` 计数器,记录的是一个真踩过的 bug(落库曾按谓词而非 `via` 查规则,跨谓词规则一加就静默丢弃)。
+> `rules` 的身份是 `(kb, 谓词, 种类)`,公理撤了也不删行——否则每跑一次 `rule_id` 就换新,历史全断。
+> 冷启动自动扩本体现在**一位公理都不替人声明**(`Axioms::default()`):推理机的判据必须是人写下来的。
### R2 · 解释
-证明树 API + UI。展开到叶子(chunk)为止,中间节点是派生事实与规则。
+证明树 API + UI。展开到叶子(chunk)为止,中间节点是派生事实与规则。〔**只做了一层**:`derived_for_entity` 把直接前提展开成文本。递归到叶子的 API 与 UI 未建,数据结构已足够支撑。〕
### R3 · 增量维护
-前提失效 → 派生失效。半朴素增量而非全量重算。放最后是因为前面三步都能靠"重算整个 KB"活着,而增量的正确性最难验。
+前提失效 → 派生失效。半朴素增量而非全量重算。放最后是因为前面三步都能靠"重算整个 KB"活着,而增量的正确性最难验。〔**未做**,每次全量重算并整体对账,迁移注释明写「在增量维护做出来之前每次都是全库重算」。〕
---
## 开放问题
-- **有效时间的交集语义**:前提 A `[2020,2023)`、前提 B `[2022,∞)` → 派生 `[2022,2023)`。属性事实的字面值宾语怎么参与?闭区间与开区间混合时的边界?
-- **物化 vs 查询时求值的临界点**:实测 4.5 倍膨胀(185 → 828)。大语料上这个倍数会怎么变,什么规模该切换?
+- **有效时间的交集语义**:前提 A `[2020,2023)`、前提 B `[2022,∞)` → 派生 `[2022,2023)`。属性事实的字面值宾语怎么参与?闭区间与开区间混合时的边界?〔**已答**:半开区间取交集、空交集不推、端点相接不算重叠;精度取最粗、置信度取前提最小;**字面值宾语不参与**——取边与推导都要求 `object_id IS NOT NULL`。〕
+- **物化 vs 查询时求值的临界点**:实测 4.5 倍膨胀(185 → 828)。大语料上这个倍数会怎么变,什么规模该切换?〔未定。实际做法是每谓词封顶 + 定时全量重推。〕
- **`related_to` 39% 是推理的前置障碍**:推理机面对的图有近四成的边语义是空的。这把 0001 P3b 的优先级顶了上来——**推理机的输入质量取决于它**。补充实测:359 条里只有约 38 条是词表外降级,**321 条是模型自己从提示词清单里挑的 `related_to`**——它就在本体里,被当合法选项列了出去。所以修法是两条腿:**先撤掉提示词里这个逃生舱**,再做映射。细节见 0001 P3b 的修订记录。
-- **环该怎么处置**:检测出来只是第一步。自动拒绝哪一条?还是全部进 Review 让人判?倾向后者——两条都是模型抽的,没有先验理由信任其一。
+- **环该怎么处置**:检测出来只是第一步。自动拒绝哪一条?还是全部进 Review 让人判?倾向后者——两条都是模型抽的,没有先验理由信任其一。〔**已按倾向落地**:`cycle` 违规带完整 `path` 进 Review;R1 一律不推自环。`related_to` 那条前置障碍也随 [0010](0010-no-relation-is-no-relation.md) 消失——空谓词边天然不进推理。〕
diff --git a/docs/decisions/0003-ontology-growth-loop.md b/docs/decisions/0003-ontology-growth-loop.md
index 50eef7bf..c9b85f2a 100644
--- a/docs/decisions/0003-ontology-growth-loop.md
+++ b/docs/decisions/0003-ontology-growth-loop.md
@@ -1,6 +1,6 @@
# 0003 · 本体从语料里长出来,人站在哪一环
-- **状态**:已建成(#44 + `feat/ontology-auto-extend-switch`);末节列出已知缺口
+- **状态**:已建成且仍在跑(#44 + 自动扩展开关);**本文的起点已被 [0010](0010-no-relation-is-no-relation.md)(`related_to` 删除)与 #125 / #128(种子退场)改写**;「拒绝有记忆」一节的实现被 [0007](0007-who-decides-what-becomes-a-relation.md) 推翻重做;末节三条缺口两条已补,「新说法提醒」仍待做(2026-09-02 核)
- **成文**:2026-08-28
- **相关**:[0001](0001-ontology-import-and-governance.md) 的 P3b 与 P4——那两节是计划,本文是实际长出来的东西,两者不一样
@@ -14,7 +14,11 @@
而新建的知识库只有 10 个默认关系,那不是任何人选的,是种子数据。所以每一个新库开局都是这个状态:**图里近一半的边没有语义,直到有人坐下来一条条补本体。**
-抽取侧的修法(撤掉逃生舱、加提示词规则 8、把原词存进 `fact_evidence.surface_predicate`)见 0001 的 P3b。本文接着往下——**原词留住之后,怎么把它变回本体里的关系。**
+抽取侧的修法(撤掉逃生舱、加提示词规则 8、把原词存进 `fact_evidence.surface_predicate`〔落地列名 `proposed_predicate`〕)见 0001 的 P3b。本文接着往下——**原词留住之后,怎么把它变回本体里的关系。**
+
+> **修订记录(2026-09-02):上面两段的世界不在了。** `related_to` 整个删掉,落不上就是空谓词,显示时由 `fact_surface_predicate()` 取回原文说法;新建的库**一个关系都没有**,起点改为预制本体包([0008](0008-ontology-packs-as-cold-start.md))。
+> 40.5% 是当时的数;[0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 在 ai-timeline-ends × schema.org 上量到空谓词 25.6%,而且 41 个关系全部来自本体包,**自动扩本体一条都没长出来**。
+> 所以这条回路的角色变了:冷启动的主力是「先装一份词表」,本文的机制负责「长出来的补缺口」。回路本身一字未改,仍然默认开着。
---
@@ -62,12 +66,17 @@ Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实
**判据一句话:可逆的可以自动,触发级联写入的不行。**
+〔后来扩大到全部公理:冷启动路径传 `Axioms::default()`,八位全 false——推理机([0002](0002-reasoning-engine.md))的判据必须是人写下来的。〕
+
### 拒绝有记忆
`dismiss` 此前是 `DELETE FROM ontology_misses`,下一次抽取遇到同一个词原样插回——**用户的"不要"活不过一轮抽取**。开关关着时这只是恼人;开着时它变成系统覆盖人的明确决定。
改成标记(`dismissed_at`):`record_miss` 不再累加已标记的,人工与自动两条路都跳过。顺带修好了"dismiss 是暂时的"这个现存 bug。
+> **修订记录(据 [0007](0007-who-decides-what-becomes-a-relation.md) 缺陷五)**:「不再累加」这一半**又被推翻**。它把「忽略」做成了单向门:用户看着「出现 1 次」做的判断被记成对所有时间的判断,后面二十篇都在用它,计数仍停在 1,没有人看得见。
+> 现在 `record_miss` 照样累加,抑制移到读取侧——已忽略的连同更新后的计数单列一处,可撤回。「拒绝有记忆」仍然成立,只是记忆的是**态度**不是**计数**。
+
### 自动采纳的门槛
只采纳出现在 **≥2 篇文档**里的说法。理由不是安全(有撤销),是质量:**本体会反馈进抽取提示词,一次偶然用词会变成长期指令。** 副作用正好——单篇文档什么都够不着门槛,于是什么也不做,下一篇再议。
@@ -125,6 +134,8 @@ Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实
一个**负面结果,而它证明了设计**:建议把 `optimized_for` 并进了 `runs_on`——"为 RTX 优化"不等于"跑在 RTX 上"。归并的写法在 tooltip 里可见,过并能被人抓出来。**这就是我不建议全自动归并的最直接证据。**
+〔上表四行都基于已不存在的 `related_to` 与种子本体,是历史记录,不要再当基线引用。采纳路径后来多了两样本文没写的东西:整组说法先过 `predicate_match`,本体里已有等价关系(含 `_by` 反向)就落到它上面并对调主宾(#109);门槛按「谓词 + 类型」合起来算 `MIN_SIGNALS = 3`,此前只数谓词,一个只缺实体类型的语料会被整个跳过。规范 key 不问模型取名,取组内事实最多的那个真实措辞。〕
+
---
## 已知缺口
@@ -135,7 +146,7 @@ Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实
当时列的实测数据(`General` 库里 "rust" 分在 5 个类、`Industry Corpus` 里
`product` 占 37.1%)仍是这条路要解的问题,见 0001 P3 的三层拆解。
- **关掉开关后没有"自上次以来有 88 个新说法"的提醒**,信号在 Unmatched 面板里但没人主动看。
- **待做。**
+ **待做。**〔2026-09-02 核:仍未做。`ontology_proposals_open_idx` 的建表注释把这条缺口原样抄了一遍——索引铺好了,提醒没做。今天只有 `last_auto_extension` 横幅,讲的是「最近一次自动扩本体做了什么」。〕
- ~~**提案不持久化**~~ **已修**(2026-08-30,#112):`ontology_proposals` 表落库。
丢的从来不是原材料(那在 `ontology_misses` 里),是**聚类结果**——哪些说法被归到
同一条提议底下,而那正是唯一能查证过并的东西。
diff --git a/docs/decisions/0004-language-and-localization.md b/docs/decisions/0004-language-and-localization.md
index 1b3238e9..0b7c9dfa 100644
--- a/docs/decisions/0004-language-and-localization.md
+++ b/docs/decisions/0004-language-and-localization.md
@@ -1,9 +1,9 @@
# 0004 · 语言:哪些字跟着看的人走,哪些跟着语料走
-- **状态**:已建成 · 五种文本各就各位:界面词汇在 `web/src/i18n/`、服务端错误已改成 key、
+- **状态**:已建成 · L0–L3 全部落地:界面词汇在 `web/src/i18n/`(约 950 条,含 108 个函数)、服务端错误改成带 `code` 的 `AppError::Invalid`(81 处;23 处 API 契约守卫刻意留英文 `Validation`)、
本体 `description` 跟 `knowledge_bases.ontology_lang`(带部署默认值)、LLM 面向人的输出
- 由调用方在请求里传 `locale`、抽出来的数据逐字跟文档
-- **成文**:2026-08-29(状态于 2026-08-30 更正:文档一直写着「规划中」,而索引与代码都说已建成)
+ 由调用方在请求里传 `locale`、抽出来的数据逐字跟文档。**两处与本文写的不同**,见 2026-09-02 的修订记录:界面首次访问刻意不猜浏览器语言;「中文内置本体」那一支随播种机制退场而作废
+- **成文**:2026-08-29(状态于 2026-08-30 更正:文档一直写着「规划中」,而索引与代码都说已建成;2026-09-02 对照代码复核)
- **相关**:[0001](0001-ontology-import-and-governance.md) 论证过 `description` 是承重字段——本文把「它该用什么语言」补上;[0003](0003-ontology-growth-loop.md) 的 `reason` 与 `description` 之分是本文分界线的起点
> 触发:产品要面向中文企业出中文版。但「加个语言开关」这句话底下藏着**五种性质不同的文本**,它们的正确语言互不相同,用一个开关管必然有一半是错的。
@@ -34,6 +34,12 @@
`localStorage` + [wsStore.ts:22](../../web/src/wsStore.ts) 已有的 `makeStore` 模式,多一行 `makeStore("utopia.lang")`。首次访问按 `navigator.language` 猜一次,之后以人选的为准。
+> **修订记录(2026-09-02)**:「按 `navigator.language` 猜一次」**没有落地,而且是刻意的**。
+> `web/src/i18n/index.ts` 的 `detect()` 只读 `localStorage`,否则一律 `"en"`,注释写着
+> 「等 zh 追平了再把 navigator.language 那一句加回来」。原因是下文「已知会疼的地方」第一条:
+> 中文包在追英文包,漏译的那部分会静默回落成英文。于是把「漂移」的代价换成了
+> 「中文用户默认先看英文」——这是个取舍,不是遗漏,追平之后该把那一句加回来。
+
> **修订记录**:本文初稿把界面语言放在**部署级管理员设置**里,理由是"和并发上限一样,DB 存、即时生效"。那个类比是错的——并发上限是**部署的属性**(供应商速率限制),界面语言是**读者的属性**。判断一个设置该放哪,问的不是"改起来方不方便",是"它描述的是谁"。
中文包写成 `const zh: typeof S = { … }`。**不用 `Partial` + 逐键回退**:那样漏译不报错,只是某一行悄悄变回英文,而这种缺口只有用户会发现。`typeof S` 让漏一条就编译不过——512 条字符串 + 44 个函数,靠人眼对不齐。
@@ -42,7 +48,7 @@
界面语言在客户端之后,**后端不再拥有任何 locale**。所以留在 Rust 里的字符串是**永久不可翻译**的,不是"以后再补"。
-`AppError::Validation` 目前 75 处。分两类处理:
+`AppError::Validation` 目前 75 处〔**已做完**(2026-09-02 核):能撞到的改成了带 `code` 的 `AppError::Invalid`,81 处,前端 `err.*` 表 48 条;留下的 23 处 `Validation` 全是契约守卫。`Invalid` 还多带一个 `detail`——机器给的补充(cron 解析器的报错之类)与措辞分离;`message` 仍是英文原句且刻意保留,给不做本地化的客户端(MCP、CLI)与日志用〕。分两类处理:
- **用户正常操作能撞到的**(密码规则、邮箱格式、空文件、日期格式等)→ 改成 key,前端查表。这样全部措辞收进 `i18n.ts` 一个文件,而不是前端一半后端一半。
- **API 契约守卫**(`role must be admin, editor or viewer`——只有调错接口才会碰到)→ 留英文。它的读者是开发者,永久英文正是它该有的样子。
@@ -63,19 +69,24 @@
`label` 存在库里,跟不了客户端的开关。**而这是对的**:它是那个团队写下的本体。一个中国团队建的库里类叫 `人物`,用英文界面的同事看到的也该是 `人物`——那是他同事定义的概念,不是界面元素。翻译它反而错。
-内置的 9 个类只在**播种那一刻**是应用词汇,落库之后就是这个库的数据,可编辑。
+内置的 9 个类只在**播种那一刻**是应用词汇,落库之后就是这个库的数据,可编辑。〔**已作废**:[0009](0009-no-type-is-a-type.md)、[0010](0010-no-relation-is-no-relation.md)、#125、#128 之后不再有内置类、种子关系与播种函数。冷启动改由英文预制包提供([0008](0008-ontology-packs-as-cold-start.md)),于是「label 是数据」这条的实际后果是:**中文库装到的是纯英文本体**,`ontology_lang = zh` 只影响将来由 LLM 提案长出来的词。见 0008 开放问题。〕
**`key` 永不翻译**:它是标识符(`[a-z0-9_]`,最长 40),是模型读写的令牌,也是 `type_ids` 的查找键。
-**一个连带修改**:提示词现在排成 `- {key} ({label}): {description}`([lib.rs:61](../../crates/utopia-extract/src/lib.rs))。界面语言与语料语言不一致时,这一行会中英混排。`Person` 相对 `person` 本来就近乎零信息量,所以**提示词只送 `key` + `description`,`label` 仅在 description 为空时兜底**。
+**一个连带修改**:提示词当时排成 `- {key} ({label}): {description}`([lib.rs](../../crates/utopia-extract/src/lib.rs),已按下句改掉)。界面语言与语料语言不一致时,这一行会中英混排。`Person` 相对 `person` 本来就近乎零信息量,所以**提示词只送 `key` + `description`,`label` 仅在 description 为空时兜底**。
### LLM 当场生成给人看的 → 调用方在请求里说
-`reason` 是人点 "Suggest with AI" 当场生成、当场显示、接受或忽略后就没了——`suggest` **即时返回不存库**([ontology_routes.rs:328](../../crates/utopia-server/src/api/ontology_routes.rs))。调用者就在现场,那就让请求自己说要什么语言,而不是让后端记一个设置。
+`reason` 是人点 "Suggest with AI" 当场生成、当场显示、接受或忽略后就没了——`suggest` **即时返回不存库**([ontology_routes.rs](../../crates/utopia-server/src/api/ontology_routes.rs))。调用者就在现场,那就让请求自己说要什么语言,而不是让后端记一个设置。
+
+> **修订记录(2026-09-02)**:「不存库」已不成立——#112 之后 `suggest` 算完会写进 `ontology_proposals`,
+> 因为丢掉的不是原材料而是**聚类结果**(见 [0003](0003-ontology-growth-loop.md) 已知缺口)。
+> 但语言的结论不变:`reason` 仍按请求里的 `locale` 生成,label / description 则跟 `kb.ontology_lang`,
+> 两者在**同一次调用**里表达,提示词里写明后者覆盖英文骨架。
冷启动自动扩本体走同一条路但没有人类调用者。它生成的 `reason` 本来就被丢掉(`lastAutoExtension` 只回 relations / classes / facts_remapped / batches),所以那条路不需要 locale。
-**今天真正的毛病不是语言错,是语言没定**:[bootstrap_ontology.rs](../../crates/utopia-server/src/bootstrap_ontology.rs) 的提示词压根没说输出用什么语言,模型看心情。
+**今天真正的毛病不是语言错,是语言没定**:[bootstrap_ontology.rs](../../crates/utopia-server/src/bootstrap_ontology.rs) 的提示词压根没说输出用什么语言,模型看心情。〔**已修**:提示词末尾有一整段 Language 指令,`lang_name()` 把 `zh` 写成 `Chinese` 再送进去——模型认得懂 Chinese,未必认得懂 zh;冷启动那条路显式传 `en`。〕
### 抽出来的数据 → 逐字跟文档,连开关都不给
@@ -119,6 +130,10 @@ locale 必须**在一个函数里解析出来**,其余全部消费它,不各
**L2 里最实的一块不是加列,是重写内置本体的描述**——9 个类 + 14 个关系。它们当初是斟酌着写的(负面例子那部分尤其:「不是角色、职位或团队,那些归 concept 或 organization」——错误聚集在边界上,负面例子才是干活的那半)。**翻译不能敷衍,得按同样的思路用中文重写一遍。**
+> **修订记录(2026-09-02)**:这一块**已无对象**——种子本体整个退场(见上文「label」一节的作废注)。
+> L0、L1、L3 与 L2 的「加列 + 部署默认值」都已建成;中文本体这件事换了形态:
+> 要么用户导入自己的中文词表,要么等本体包有中文标签(0008 开放问题),代码里没有第三条路。
+
---
## 已知会疼的地方
@@ -126,3 +141,4 @@ locale 必须**在一个函数里解析出来**,其余全部消费它,不各
- **中文包与英文包漂移**。`typeof S` 挡住"漏一条",挡不住"英文改了措辞、中文还是旧的"——两边都合法。目前没有好办法,只能靠改文案时同时改两处。
- **一个库里中英文档混放**时,`description` 该用哪种语言没有正确答案。本文选了「知识库单语」,因为混放本身就会让抽取质量下降(不只是描述的问题)。真遇到了再说,别提前设计。
- **中文分词与检索**。Tantivy 那边已经用了 `tantivy-jieba`,不在本文范围,但中文版上线后会被更认真地检验。
+- **(2026-09-02 补)中文包追不上英文包的期间,界面默认英文**。见「界面词汇」一节的修订记录:`detect()` 暂不猜浏览器语言。追平的标志是 `zh.ts` 不再靠 `typeof S` 之外的任何东西撑着,那时把 `navigator.language` 加回去。
diff --git a/docs/decisions/0005-alert-center.md b/docs/decisions/0005-alert-center.md
index 42d8a5ea..ca44ecb9 100644
--- a/docs/decisions/0005-alert-center.md
+++ b/docs/decisions/0005-alert-center.md
@@ -1,7 +1,7 @@
# 0005 · 告警中心
-- **状态**:第一刀已建成(`source.sync_failed` + `llm.unreachable`)。
- 三个决定里第 1、2 条在实现过程中被推翻,就地留痕见下
+- **状态**:已建成 · 五种告警在线(`source.sync_failed`、`llm.unreachable`、`llm.rate_limited` #160、`llm.out_of_credit` #182、`data_source.schema_sync_failed`),面板带搜索与按组分页;
+ 三个决定里第 1、2 条在实现过程中被推翻,就地留痕见下;`document.no_text_layer` 仍未接(2026-09-02 核)
- **成文**:2026-08-29
- **相关**:与 Review 队列(0001 P4)职责相邻,本文划边界
@@ -13,14 +13,14 @@
| 位置 | 记的是 |
|---|---|
-| `jobs.status='failed'` + `jobs.last_error` | 任务失败 —— **没有任何界面** |
+| `jobs.status='failed'` + `jobs.last_error` | 任务失败 —— **没有任何界面**〔现在:任务**最终**失败(`attempts >= max_attempts`)且错误可分类时,经 `observe_job_failure` 变成告警;重试期间不报,重试本就是为了不惊动人〕 |
| `documents.status='failed'` | 摄入失败 |
| `documents.graph_status='failed'` | 抽取失败 |
| `sources.last_sync_status='failed'` | 源的最近一次同步失败 |
| `source_sync_runs.status='failed'` | 单次同步失败 |
| 日志 | 其余一切 |
-而且这个问题**已经被局部修过一次**。迁移 `0021_graph_error.sql` 的第一句是:
+而且这个问题**已经被局部修过一次**。当时的迁移 `0021_graph_error.sql`(#130/#131 折叠后落在 `0002_ingest.sql` 的 `graph_error` 列)的第一句是:
> 抽取失败的原因此前只进日志与 `jobs.last_error`,文档上什么都不留,界面无从显示。
@@ -129,7 +129,7 @@
`kb_id` 可空,两种语义:
```
-kb_id IS NULL 系统级:LLM 端点不可达、数据库连接池打满、镜像版本不一致
+kb_id IS NULL 系统级:LLM 端点不可达(今天实际是三条 LLM 告警:不可达 / 限流 / 欠费)
→ 仅 users.is_admin
kb_id 有值 知识库级:解析失败、抽取失败、源同步失败
@@ -138,6 +138,11 @@ kb_id 有值 知识库级:解析失败、抽取失败、源同步失败
**不新写权限逻辑**:`access::kb_role()` 第一句就是 `if user.is_admin { return Ok(Some(Role::Owner)) }`,告警的可见性判定直接复用它,和 KB 路由走同一条鉴权链。系统管理员因此对知识库级告警也全通。
+> **修订记录(2026-09-02)**:结论(admin 全通、按 `min_role` 比大小)成立,「不新写」没做到。
+> 列表要一条 SQL 里按人过滤,于是走的是 `access::visible_kb_roles()` 加 `alerts.rs` 里一段 `VISIBLE` CASE
+> 加一个 `rank()`——代码自己承认「跟 `Role` 的 `PartialOrd` 同序,也跟 `VISIBLE` 里那个 CASE 同序,三处必须一致」。
+> 记在这里是因为这正是本仓库最怕的那种隐形规则:改角色顺序时得记得改三处。
+
`min_role` 存在 alert 上而不是按 kind 硬编码,因为同一类告警在不同场景下该找的人不同:
- **配置类**(端点、权限、配额)→ admin
@@ -194,6 +199,20 @@ kb_id 有值 知识库级:解析失败、抽取失败、源同步失败
| `source.sync_failed` | KB 级 | 聚合、自愈、`min_role=editor` | 聚合改到视图层;自愈作废;权限如设计 |
| `llm.unreachable` | 系统级 | `kb_id IS NULL` 那条路径、`is_admin` 可见性 | 它没有成功信号,就是这一条逼出了第 2 节的推翻 |
+> **后续(2026-09-02 核)**:第一刀之后又接了三条,**没有一条需要新的检测逻辑**,都是把已有的错误分类接上来:
+> `llm.rate_limited`(#160,退避用尽仍过不去)、`llm.out_of_credit`(#182,402 或「余额不足」文案,与限流分开——该找的人不同)、
+> `data_source.schema_sync_failed`(源挂上了但表结构没摄进来)。分类做成纯函数 `alert_for` 并有单测,
+> 因为判据是错误的**类型**不是文本。最后一条值得记:它报的是「留下的状态」不是「那次失败」,
+> 是第一条不由一次执行失败直接触发的告警,与上文「任何执行路径在失败时上报」的表述有出入。
+>
+> 面板顺带长出了搜索与按组分页(每页 8 组、每组最多 5 条明细)。搜索**刻意搜不到标题**——
+> 标题是前端按 kind 查表拼的([0004](0004-language-and-localization.md):服务端不产出展示文案),
+> 服务端只能匹配库名、detail、kind 代号。
+>
+> **一条本文该划而没划的边界**:`extraction_drops`(11 种丢弃原因,读者是上传文档的人)是另一条完全独立的失败信号通道,
+> 它与告警的分工是「这份文档里有东西没落地」对「系统某处坏了」——前者按文档聚在文库行上,后者进铃铛。
+> 两者都不进 Review:Review 管知识的对错。
+
**如果设计有错,这一刀就会暴露** —— 确实暴露了,见上面两条修订记录。
`llm.unreachable` 的判据在实现中也放宽过一次:起初只认传输层失败(连不上),
diff --git a/docs/decisions/0006-ontology-scale-and-the-prompt.md b/docs/decisions/0006-ontology-scale-and-the-prompt.md
index cfe6be8e..75855dae 100644
--- a/docs/decisions/0006-ontology-scale-and-the-prompt.md
+++ b/docs/decisions/0006-ontology-scale-and-the-prompt.md
@@ -1,6 +1,6 @@
# 0006 · 本体规模与抽取提示词
-- **状态**:已建成 · 预算与按块检索已上线;预算的具体数值仍待更好的语料来定
+- **状态**:已建成 · 预算(24,000 字符)与按块检索在线,数值未动;「内置类恒在」那道地板已被**祖先补齐**取代(见文末修订);预算的具体数值仍待更好的语料来定——外部语料已入库,答案键仍是人填的(2026-09-02 核)
- **成文**:2026-08-29(约定见 [README](README.md))
> 这一篇比别的多一样东西:**数字**。它们来自 `scripts/bench/`,任何人都能重跑。
@@ -22,7 +22,7 @@ token**。这个数字不是某个设计的代价,**是没有设计的结果**
**按预算切换,不按类数量。**
- 装得下 → 全量铺,行为一字不变。四十个类的本体约 2k 字符,检索反而是多余的往返。
-- 装不下 → **每块用它自己的向量检索候选**,内置类恒在,检索不出来就退回全量。
+- 装不下 → **每块用它自己的向量检索候选**,内置类恒在〔已换成祖先补齐,见文末〕,检索不出来就退回全量。
预算按**字符**而不是类数量:类描述的长度差着数量级(`SoftwareApplication` 的描述是
一句话,FIBO 的能有一整段)。判据量的是**实际要排的那段字**(`build_lists` 自己数),
@@ -97,6 +97,29 @@ token 限额(429),同一份本体检索组跑得下来。这不是"慢一
都是拍的,代码里标着。上面的曲线说它偏保守,但在语料这一关过掉之前,
按那条曲线去调只是把过拟合调得更紧。
+## 修订记录(2026-09-02):地板换了材料,索引付了代价
+
+**「内置类恒在」失效了。** 它的前提是种子类正好是那几个通用类,而 #128 之后建库不种任何类,
+`seed_classes` 恒为空。症状在 [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 里量过:向量检索偏爱字面出现在正文里的叶子类
+(976 个类里 `researcher` 第 4、`corporation` 第 27,`organization` 第 177、`person` 第 359,前 40 名里一个泛化基类都没有),
+于是实体判成 `researcher`,`employee (organization → person)` 的签名退化成 `(* → *)`。
+
+**改成:命中什么,就把它的祖先一起铺出去。** 沿 `subClassOf` 上溯,广度优先加访问集(菱形继承会从两条路到达同一祖先)。
+比维护一张「通用类」清单好——继承链本来就是本体自己声明的泛化关系,谁是谁的上位不用我们再判一次。
+代价是每块多铺几层祖先。这是「三个细节」之外的第四个,也是唯一由真实数据逼出来的。
+
+**本体向量索引本身也有两个实测常量**,本文当初只谈了提示词的规模:`BATCH = 64`(曾改成 16,因为拿合成短文本量的「每条更快」,
+改回后吞吐翻倍)、`EMBED_JOBS = 4`(曾用 `join_all` 挂 31 批,把共享的 `model_concurrency` 闸门占死——五篇文档全卡在 embedding,抽取十五分钟零进展)。
+索引陈旧靠「当时嵌的原文与模型名跟现在对不对得上」自愈,不挂钩子。
+
+**按块检索的系统级代价**:每块一次向量检索砸向数据库,并发数由 `worker_concurrency` 决定,而它的上限已从 32 提到 256(#133)。
+连接池是 32。这条账本文没记,迁移 `0011` 的注释记了。
+
+**测量台已经能测 0008 那个开放问题**:`run.mjs --packs schema-org,prov-o` 走产品真实的冷启动路径。工具就位,对照仍未跑。
+
+**语料那一半**:语料从 2 份涨到 8 份,新增的都不是手写的(维基历史快照带可重建的 manifest、公有领域国情咨文、福尔摩斯),
+生成脚本一并入库。但「标准答案由外部数据推导」没做——`scripts/bench/truth/` 仍只有 pharma / tech 两份人填答案,没有任何 Wikidata `P31` 代码。
+
## 撤回
> **「108k 的提示词吃掉了 5 个实体」不成立。** 那条结论来自测量台的默认次序
diff --git a/docs/decisions/0007-who-decides-what-becomes-a-relation.md b/docs/decisions/0007-who-decides-what-becomes-a-relation.md
index 5f398365..9b50c7c4 100644
--- a/docs/decisions/0007-who-decides-what-becomes-a-relation.md
+++ b/docs/decisions/0007-who-decides-what-becomes-a-relation.md
@@ -1,6 +1,6 @@
# 0007 · 谁来决定一个说法值不值得成为关系
-- **状态**:已建成 · 采纳改由计数决定;「叙述动词进了本体」这一条未解
+- **状态**:已建成 · 采纳改由计数决定;六条缺陷的修法全部在线;「叙述动词进了本体」与 `merge_key` 不折 `_by` 两条仍未解;**本文的起点(10 个种子关系、`related_to` 占比)已不存在**,见文末修订(2026-09-02 核)
- **成文**:2026-08-30(约定见 [README](README.md))
> 跟 [0006](0006-ontology-scale-and-the-prompt.md) 一样带数字,也一样标明每个数字
@@ -134,6 +134,25 @@ criticizes/criticized 6 · published/publishes 6 · accused/accuses 6
`related_to` 已整个删掉,见 [0010](0010-no-relation-is-no-relation.md)。这条未决项本身仍然成立:
叙述动词进本体的问题与谓词兜底无关。〕
+## 修订记录(2026-09-02):起点没了,结论还在
+
+本文的问题陈述是「新建的库只有 10 个种子关系,大半说法降级成 `related_to`」。**两个前提今天都不成立**:
+种子关系分三次退场(`related_to` 见 [0010](0010-no-relation-is-no-relation.md),另外八条 #125,`mapped_to` 见 [0011](0011-a-mapping-is-not-a-fact.md)),播种函数随之消失(#128);
+新库的起点是预制包([0008](0008-ontology-packs-as-cold-start.md)),默认 schema.org,1010 类 / 1676 属性。
+
+**于是「量到了什么」那张表的可比性也没了**:A / B / B3 / 计数采纳四组都是从 10 个种子起跑的。
+今天同一份语料从 schema.org 起跑,`related_to` 这个指标本身已经不存在(事实可以没有谓词,原词落 `fact_evidence.proposed_predicate`),
+对应的指标变成「空谓词占比」——[0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 在 ai-timeline-ends 上量到 25.6%,
+与本文 B3 + 计数采纳的 25.8% 是两个不同起点、不同定义下的数,**不要拿来对比**。
+
+**决定本身不受影响。** 采纳由计数决定、`merge_key` 归并、文档并集、`MIN_DOCS = 2`——全部在线,另加一条本文没写的 `MIN_SIGNALS = 3`(够格信号不足三个就不跑 LLM)。
+提案现在落库到 `ontology_proposals`(#112),表过态的不被下一轮刷回。
+
+**起点从 10 变 1500 对采纳回路意味着什么,仍然没人量过**——0008 开放问题最后一条。阈值一个没动。
+
+**`_by` 的下游后果有了结构上的解**:本体现在能声明 inverse(#177/#179),方向由本体签名声明并在写入时掰正(#138,留 `direction_corrected` 痕迹)。
+但那不替代 `merge_key` 折 `_by` 这个缺口——两个方向都不在本体里时,仍会建出两条相反的关系。
+
## 走过的死路
留着它们,因为每一个当时看起来都很合理。
diff --git a/docs/decisions/0008-ontology-packs-as-cold-start.md b/docs/decisions/0008-ontology-packs-as-cold-start.md
index 132d2c06..7d75652f 100644
--- a/docs/decisions/0008-ontology-packs-as-cold-start.md
+++ b/docs/decisions/0008-ontology-packs-as-cold-start.md
@@ -1,6 +1,6 @@
# 0008 · 预制本体包作为冷启动
-- **状态**:规划中 · 建库仍只发 10 个种子关系
+- **状态**:已建成 · 五个包内嵌进二进制、建库时多选(schema.org 默认勾选)、对齐表 22 条静态维护;**建库不再发任何种子关系**——包不是补充,是本体的全部来源;三个开放问题全部仍然开放,且「中文标签」那条变严重了(2026-09-02 核,修订见文末)
- **成文**:2026-08-30(约定见 [README](README.md))
- **相关**:[0001](0001-ontology-import-and-governance.md) 定了 IRI/key 分工与贯穿性判据;
[0006](0006-ontology-scale-and-the-prompt.md) 拆掉了大本体的提示词障碍;
@@ -13,7 +13,7 @@
## 问题
-新建的库只发 10 个种子关系(`graph.rs:290` 的 `RELATION_TEXT_ZH`)。这 10 个里
+新建的库只发 10 个种子关系(成文时 `graph.rs` 的 `RELATION_TEXT_ZH`;今天那张表、`localized()` 与 `ensure_default_ontology` 都不存在,`graph.rs` 开头留了三次退场的理由)。这 10 个里
**零个带类型签名**——没有 domain,没有 range。
抽取提示词是支持签名的(`extract/lib.rs:498` 的测试:`- buys_from (employee|team → *)`),
@@ -29,7 +29,7 @@
**这正是问题所在**:用散文补方向,每个谓语都要单独踩一次坑,而且补丁只在那一条下面生效——
`part_of` 警告过的"能在某服务上玩",换个谓语照样踩。
-`graph.rs:4` 的自陈说明这不是个别谓语的事:
+`graph.rs` 开头的自陈(今天挪到了 `bootstrap_ontology.rs` 开头,**内容已过时**,仍写着 10 个默认关系与降级 `related_to`)说明这不是个别谓语的事:
> 文档,里面的关系大半不在这 10 个里,于是大量事实降级成 related_to
@@ -60,9 +60,9 @@ schema:worksFor Person → Organization
| 包 | 体积 | 类 | 属性 | domain | range | 补什么 |
|---|---|---|---|---|---|---|
-| **schema.org** | 1078 KB | 1010 | 1521 | 1521 | 1521 | 通用:人、组织、产品、事件、创作 |
+| **schema.org** | 1078 KB | 1010 | 1521〔发货的包记 1676〕 | 1521 | 1521 | 通用:人、组织、产品、事件、创作 |
| **W3C Org** | 82 KB | 13 | 34 | 36 | 32 | **组织架构**:Unit、Post、Membership、Role、任期 |
-| **PROV-O** | 110 KB | 62 | 69 | 63 | 62 | 溯源:Activity、Agent、wasDerivedFrom |
+| **PROV-O** | 110 KB | 62〔发货的包记 49〕 | 69 | 63 | 62 | 溯源:Activity、Agent、wasDerivedFrom |
| **FOAF** | 43 KB | 12 | 62 | 60 | 57 | 社交关系 |
| **IOF Core** | 394 KB | 294 | 75 | 94 | 94 | 工业制造 |
@@ -117,8 +117,8 @@ schema:worksFor Person → Organization
### 2. 不做导入撤销
-`ON DELETE RESTRICT`(`0004_graph.sql:41`)加应用层计数(`ontology.rs:232`)加
-`NOT builtin` 三道防线,已经保证了安全边界:**有实体挂着的类型删不掉**。
+`ON DELETE RESTRICT`(今天在 `0003_graph.sql`)加应用层计数(`ontology.rs` 的删类 / 删关系两处)加
+`NOT builtin` 三道防线〔第三道现在是空条件:没有 builtin 行了〕,已经保证了安全边界:**有实体挂着的类型删不掉**。
所以"选错了怎么办"的实际路径是:没被用到的类型直接删,被用到的删不掉——
**而删不掉恰恰是对的**,那些类型上挂着真实知识。
@@ -139,6 +139,34 @@ schema:worksFor Person → Organization
只有五六套,两两重叠有限且可穷举。**把无限的对齐问题缩成一张静态表**,
这与判据 6「治理经验固化进 schema,不要固化成隐形规则」一致。
+## 修订记录(2026-09-02):建成之后对照本文
+
+**三个决定的落地情况。** 多选建库已做(`CreateKbReq.ontology_packs`,前端多选卡片,无任何组合预设);
+**「跟已选项的重叠率」没做**,而且方向反了——`2fa8d57` 把碰撞提示整个拿掉了,因为对齐表已经处理了它们,报给用户等于让人裁一件没得裁的事。
+不做导入撤销守住了,但**替代品「批量视图:这次导入建了 294 个类、12 个在用、282 个空着,一键删空的」没做**,`ImportPanel` 只有导入历史与 plan。
+对齐表 22 条(本文估「约 20 行」),`SameAs` / `Rename` 两类,`org:Role → org_role`、`foaf:status → foaf_status` 都在。
+
+**对齐表长出了三样本文没预见的东西。**
+一是第三种处置 `Aligned`:同义命中记作「已对齐」而不是「冲突」,与 `Create` / `Update` / `KeyTaken` 并列。
+二是**方向敏感**:表是 `(进来的 IRI, 已占的 IRI)`,装包顺序不同命中的是不同条目——直接推出界面上「勾选顺序即安装顺序」这条用户可见语义。
+三是它需要一道防腐:一个跑真包的测试把五个包全投影一遍逐条核对 IRI,防的是写错一个字符静默失效,以及上游改前缀(schema.org 从 `http://` 迁到 `https://` 就发生过)。
+
+**两条推论落在了代码里**:一个包失败不回滚已装的(本体是加法,装了一半的库仍然可用;回滚要撤已建好的类,正是本文不做导入撤销的理由);
+包按 gzip 内嵌、每次建库现解压(1.7 MB → 316 KB,离线内网承诺 + clone 体积)。
+
+**本文没讨论的第三种起点:从 0 开始。** 不装任何包是合法的,空库能用,实体 `type_id` 为 NULL([0009](0009-no-type-is-a-type.md))。本文假定包把起点从 10 变成 1500,实际多了一档「0」。
+
+**「本体是引导不是执法」在包上被推翻了一半。** [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 拿真语料第一次问了「大本体顶不顶用」:词汇量确实接住了东西(215 条有谓词的事实、41 个关系全部来自包),
+但声明的方向一条没被执行,130 条可校验的里 102 条反着落库。修法是写入时按签名掰正并留痕。**包的代价不在提示词长度,在选择难度**:
+包里很多名字通用、含义狭窄的词(`affectedBy` 是医学检验的、`competitor` 是体育赛事的),按名字或向量挑必然撞上。这条该记进本文的成本项。
+
+**开放问题的现状**:
+- 混装准确率——**工具就位、对照未跑**。`run.mjs --packs` 走真实冷启动路径,`truth/` 里仍只有 pharma / tech。
+- schema.org 面向网页——仍然如此。README 把「按行业要包」做成了 issue 模板链接,把这条缺口转成了用户输入通道。
+- 中文标签——**变严重了**。种子那 14 个带中文名的关系没了,五个包全英文,所以今天一个中文库拿到的是**纯英文本体**。
+ [0004](0004-language-and-localization.md) 的分工在这里的实际结果是:`ontology_lang = zh` 只影响将来由 LLM 提案长出来的词,对已装的包一个字不动,且没有任何地方提示这一点。
+- 起点规模——未研究。`MIN_DOCS = 2`、`MIN_SIGNALS = 3` 全部没随起点从 10 变 1500 而调。
+
## 开放问题
- **混装的抽取准确率没人测过。** 0006 的数据是单一本体下的。全选之后本体约 2400 类,
diff --git a/docs/decisions/0009-no-type-is-a-type.md b/docs/decisions/0009-no-type-is-a-type.md
index 9850030c..b01c1fc7 100644
--- a/docs/decisions/0009-no-type-is-a-type.md
+++ b/docs/decisions/0009-no-type-is-a-type.md
@@ -1,6 +1,6 @@
# 0009 · 「还没判出来」不该是一个类
-- **状态**:已实施
+- **状态**:已实施 · `entities.type_id` / `entity_retypes.from_type_id` 可空;内置九类与播种函数已连同种子关系一起退场(#110 / #125 / #128 / [0011](0011-a-mapping-is-not-a-fact.md));两个开放问题仍开放,第二个已有可见代价(2026-09-02 核)
- **成文**:2026-08-30(约定见 [README](README.md))
- **相关**:[0008](0008-ontology-packs-as-cold-start.md) 让真词表成为可选起点,本文把内置的那套拆掉;
[0001](0001-ontology-import-and-governance.md) 的 IRI/key 分工是本文撞名论证的前提
@@ -128,6 +128,8 @@ Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被
它的正解仍然是注释里写的那条——等 `disjointWith` 落库后改从本体读,即 0008 的 R0 第三阶段。
本文不动它。
+〔**2026-09-02**:前提已经成立,动作仍未做。`owl:disjointWith` 有表(`entity_type_disjoint`)、有导入、有编辑接口,消费者只有 R0 的本体自检;`CONFUSABLE_TYPE_KEYS` 仍是硬编码三个 key,且它上面的注释还停留在旧世界。〕
+
## 空白库
删光之后,不选任何包的库是**真的空**:抽出来的实体 `type_id` 为 NULL,事实照常落库,
@@ -136,6 +138,8 @@ Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被
**所以"先建库后建模"是受支持的路径,不是将就。**
+〔落地时多了一列本文没写的 `entities.type_source`(extracted / human / inferred):0009 让 `type_id IS NULL` 同时承载「还没判」和「人判了就是没有」,这一列把两者分开,也是类型消解取材的过滤条件(0001 P4a)。另有 `specific_type` 与 `proposed_type` 分列——前者是模型对这个实体的自由说法,专供类型消解。〕
+
配套:schema.org 在建库对话框里默认勾选,可反选。这在 45 秒的时候不成立,
在 0.42 秒的时候成立(导入改批量插入之后的实测)。
@@ -158,4 +162,4 @@ Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被
两个都没类型的同名实体,今天按 `Recall` 走画像相似度——够不够,没测过。
- **`metric` / `dimension` 的去处**:语义层要用,而没有任何公开词表提供它们。
是让用户自己建,还是我们出一个「Utopia 语义层」包?后者会把内置本体从代码搬到包里,
- 性质完全不同——那是可选、带 IRI、可被替换的。
+ 性质完全不同——那是可选、带 IRI、可被替换的。〔**仍未答,且有了可见代价**:映射探查按 `entity_types.key IN ('metric','dimension')` 找类型,找不到就 `continue`——不装包、也没人手建这两个类的库里,探查会**静默产出零条**。〕
diff --git a/docs/decisions/0010-no-relation-is-no-relation.md b/docs/decisions/0010-no-relation-is-no-relation.md
index 8a8bba3b..219981f1 100644
--- a/docs/decisions/0010-no-relation-is-no-relation.md
+++ b/docs/decisions/0010-no-relation-is-no-relation.md
@@ -1,6 +1,6 @@
# 「说不出是什么关系」不该是一个关系
-**状态**:已实施 · `facts.predicate_id` 改为可空
+**状态**:已实施 · `facts.predicate_id` 改为可空 · 文末两条待做已随 [0011](0011-a-mapping-is-not-a-fact.md)(#126)一并完成——`mapped_to` 不只撤出提示词,它整体退出了 `relation_types`,建库不再播种任何关系(2026-09-02 核)
这是 [0009](0009-no-type-is-a-type.md) 在关系侧的孪生。那一篇讲的是
`concept`——一个"还没判出来"被写成了一个类;这一篇讲 `related_to`——
@@ -128,7 +128,7 @@
0052 只删了 `relation_types` 里的**行**。种子关系是**代码**——`graph.rs` 的
`DEFAULT_RELATION_TYPES` 里那一条还在,而 `ensure_default_ontology` 在建库、
-看本体页、**每次抽取**时都会跑。账本上看得很清楚:
+看本体页、**每次抽取**时都会跑。〔该函数连同种子表在 #128 整体退场,这类「长回来」从此不可能;`no_predicate_still_shows.rs` 里的对照组随之改写。〕账本上看得很清楚:
0052 应用于 08-30 17:54 → 全库 related_to 归零
bench demo-autoextend → 08-30 18:01 又长出一条 builtin=true
@@ -159,10 +159,12 @@ SELECT count(*) FROM relation_types WHERE key = 'related_to' AND builtin
另外两个连带修掉的:全库计数的断言会被并行测试污染(改成按 kb 查),
以及断言 panic 会跳过 teardown(改成开跑前先扫地)。
-## 待做
+## 待做〔均已完成,见状态行〕
- `mapped_to` 从抽取提示词里撤掉。它链接的是实体 → 数据源 schema(JSON 值),
只有 `related_to` 被排除在提示词外,于是模型在实体↔实体上用了它 41 次。
一行过滤的事。
- 再进一步:`mapped_to` 根本不该在本体里,它是问数映射的内部机制,
与这一篇讲的是同一类错误——把控制流写成词汇。
+
+〔**顺带记两处死代码**(2026-09-02):`graph.rs` 的 `confirmed_mappings()` 全仓零调用(问数改走 `mappings::confirmed`);`confirm_fact` 里那段「同 (概念,源) 旧映射作废」的 `r.key = 'mapped_to'` 连接现在恒匹配零行。该清。〕
diff --git a/docs/decisions/0011-a-mapping-is-not-a-fact.md b/docs/decisions/0011-a-mapping-is-not-a-fact.md
index 765e7546..5a5b3b13 100644
--- a/docs/decisions/0011-a-mapping-is-not-a-fact.md
+++ b/docs/decisions/0011-a-mapping-is-not-a-fact.md
@@ -1,6 +1,6 @@
# 0011 · 「怎么算」不是「有什么」
-- **状态**:规划中
+- **状态**:已实施 · 建表与接线(#126,与本文同一提交)、独立的数据映射页(#140)、从 Review 队列里归位(#148);三样重做两样落地、证据链未做;两个开放问题一个已答(2026-09-02 核,修订见文末)
- **成文**:2026-08-31(约定见 [README](README.md))
- **相关**:[0009](0009-no-type-is-a-type.md) 删掉内置实体类、[0010](0010-no-relation-is-no-relation.md)
删掉兜底关系、`#125` 删掉其余八条种子关系——本文是同一条线的最后一段:
@@ -116,10 +116,22 @@ UPDATE facts SET confidence = 1.0 WHERE id = $1
- **短期内多一段 UI**:Review 页要多一个分组。0002 R0 也需要它,两者合并做
一次,别做两遍。
+## 修订记录(2026-09-02):建成之后对照本文
+
+**状态行写着「规划中」,而本文正是与它的实现同一个提交进来的**——这是本次复核里最大的一处偏差,记在这里作为教训:状态行该由实现它的 PR 负责更新。
+
+**形状上的三处小差别**:唯一性 `(kb_id, concept_id, source)` 是 `UNIQUE` 约束不是主键(主键是 `id`),结论不变;表多一列 `derived`(派生指标,如「转化率 = 成交数 / 访问数」);
+**没做数据迁移**——库里是 mock 数据,旧的 `mapped_to` 事实留在账本里没人读。
+
+**三样重做**:Review 分组做了,然后又搬走了——#140 建了独立的「数据映射」页,#148 把 Review 左栏那一档挪到底部只留计数并跳转,理由是数据映射既不是队列也不是历史;审批端点仍留在 `review_routes`(`mapping.decided` 审计流水在那里)。
+历史做了:`revise()` 落整版快照进 `concept_mapping_revisions`,页面有 History 抽屉。**证据链没做**:`concept_mappings` 上没有任何「LLM 读了哪张表的 schema」的记录列,探查提议不留证据。
+
+**两条本文没写的**:`propose()` 用 `ON CONFLICT … DO UPDATE … WHERE status = 'proposed'`,重跑探查不会抹掉人的拒绝(顺带记下 Postgres 的实情:`DO UPDATE … WHERE` 不满足时 `RETURNING` 零行);可见性分级——列表 Viewer 可看、`revise` 要 Editor,「看得见答案却看不见口径,等于要人信一个不给看的算法」。
+
## 开放问题
- **确认过的口径改了怎么办?** 双时态那套答得出「上季度的口径是什么」,
- 换成 revisions 表之后要显式设计。问数回溯历史报表时会撞上它。
+ 换成 revisions 表之后要显式设计。问数回溯历史报表时会撞上它。〔**已答**:`revise` + `concept_mapping_revisions` + History 抽屉。「上季度的口径」能从 revisions 里读出来,问数是否据此回溯仍未做。〕
- **多源同概念**:`(kb_id, concept_id, source)` 允许同一个概念在不同源上有
不同定义,这是有意的(0010 之前的注释就这么写)。但问数该用哪一条?
- 今天靠 prompt 里全给、让模型挑。这条不因本篇改变,但搬表之后更容易加规则。
+ 今天靠 prompt 里全给、让模型挑。这条不因本篇改变,但搬表之后更容易加规则。〔仍是全给(上限 30 条)由模型挑。〕
diff --git a/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md b/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md
index c4092980..bc3624f5 100644
--- a/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md
+++ b/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md
@@ -1,6 +1,6 @@
# 本体是一份契约,不只是一份建议
-**状态**:已实施 · 五轮对照实验 · 违反率 57% → 4%,反向 39 → 0
+**状态**:已实施 · 五轮对照实验 · 违反率 57% → 4%,反向 39 → 0 · 文末三条待做全部仍未做;本文之后本体又能声明 `inverseOf` / `subPropertyOf`(#177 / #179)并被推理机消费,包清单扩到五个而实验只覆盖前两个(2026-09-02 核)
[0008](0008-ontology-packs-as-cold-start.md) 建了预制本体包,但它要回答的那个问题
——**大本体到底顶不顶用**——一次都没被问过:装了包的库全是 5 篇文档、26 条事实的
@@ -167,8 +167,9 @@ distrust with Altman`(65 字符)是从句——字符数分不开,**谓语
## 待做
- **写入时的守卫挡不住写入之后的改动**:实体合并会把主语换成另一个类型的实体,
- 于是事实「变成」违反。实测 6 条残留里 4 条如此。要治得把同样的检查放进合并路径。
+ 于是事实「变成」违反。实测 6 条残留里 4 条如此。要治得把同样的检查放进合并路径。〔仍未做:`merge_entities` 只做互指事实作废、主宾改指、SPO 去重,全程没有 domain / range 复核。〕
- 另外 2 条残留(`Stability AI Ltd`、`Colossus 2 data center`)没有合并也没有改类型,
**原因未查明**。
- 导入本体包时过滤掉需要中间节点才能用的关系(domain 全是 `Action`/`Offer`/
- `LoanOrCredit` 这类具化壳的),它们铺给模型只会产出违反。
+ `LoanOrCredit` 这类具化壳的),它们铺给模型只会产出违反。〔仍未做。〕
+- **(2026-09-02 补)`bootstrap_ontology.rs` 开头的模块注释仍在说「新建的库只有 10 个默认关系……降级成 related_to」**,那是三次退场之前的世界。不属于本篇,但与本条线同源,该改。
diff --git a/docs/decisions/0013-a-source-should-hand-over-its-history.md b/docs/decisions/0013-a-source-should-hand-over-its-history.md
index b2801dba..3d6dc251 100644
--- a/docs/decisions/0013-a-source-should-hand-over-its-history.md
+++ b/docs/decisions/0013-a-source-should-hand-over-its-history.md
@@ -1,6 +1,6 @@
# 0013 · 一个来源该交出它的历史,不是它的现状
-- **状态**:已实施两个(`github_issues` #134、`jira_issues` #135)· 文档协作类待做
+- **状态**:已实施两个(`github_issues` #134、`jira_issues` #135)· 文档协作类(飞书 / Confluence / Notion)仍未开工,`instant` 精度未触发(2026-09-02 核,其余陈述逐条复核为真)
- **成文**:2026-08-31(约定见 [README](README.md))
- **相关**:[0001](0001-ontology-import-and-governance.md) 的双时态地基;
语料侧的同一个判断见 `scripts/bench/fetch-wiki-history.mjs`(#122);
@@ -152,6 +152,11 @@ day 精度,时刻在入库前就没了。
两件都不是这篇的主题,但判据是同一条:**来历要看得见**。
接新来源时值得一并想:这个来源带进来的东西,读者能不能一眼看出它是从哪来的。
+## 相邻的一层:一个源能被谁挂载
+
+本文谈「东西怎么进来」。写完之后加了一层本文没有的东西——**授权**(#142,`data_source_grants`):注册数据源是部署级动作,而它携带的连接串会到达每一个被授权的工作区,所以挂载只能在授权过的集合里挑,守卫在两侧都有(列表按工作区过滤 + 挂载端点复核)。
+判据与本文一致:来历要看得见,去向也要管得住。
+
## 待做:飞书 / Confluence / Notion
文档协作类是下一个该接的——它是 #122 那份维基历史快照语料的**企业版**:
diff --git a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
index edacd80f..5b89926b 100644
--- a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
+++ b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md
@@ -1,6 +1,6 @@
# 0014 · 身份跟着人,范围跟着令牌
-- **状态**:规划中 · MCP 服务端的第一块地基,代码未动
+- **状态**:已实施(#161 记录、#180 落地)· `personal_tokens` + Streamable HTTP 的 MCP 服务端已上线,暴露五个只读工具;**尚无前端界面**——令牌的发放 / 列表 / 撤销与 MCP 配置提示今天都只有 API(2026-09-02 核,修订见文末)
- **成文**:2026-09-01(约定见 [README](README.md))
- **相关**:迁移 `0014_data_source_grants` 刚给数据源补上授权层——本篇是同一个问题
换到「机器来敲门」这一侧;[0004](0004-language-and-localization.md) 定下服务端只说英文,
@@ -117,12 +117,23 @@ CREATE TABLE personal_tokens (
MCP 的对应形态是:握手时校验一次,然后整条连接生命周期里都信任它。工具调用是一个个
独立请求,`revoked_at` 在中途被写上时,正在跑的连接必须立刻失效。
+## 修订记录(2026-09-02):落地之后对照本文
+
+**形状**多一列 `token_prefix`(`utp_pat_…`,与 ingest 的 `utp_` 区分——日志与配置文件里一眼要认得出是哪一种),`token_hash` 加了 `UNIQUE`。哈希选 SHA-256 不选 argon2:高熵串不怕爆破,而每行盐不同就查不了唯一索引。
+
+**「每个工具入口都校验 scope」那条纪律被满足了,但形态与预想不同**:做成完全无状态——每个 POST 重跑一次认证(撤销 / 过期在 SQL 的 `WHERE` 里判)+ `covers()` + `require_kb`,没有「连接」这个东西可以被信任。`scope` 在这一版没有分支:`can_write` 硬编码 `false`,就算令牌勾了 write 也不放开。每次工具调用写一条审计(`mcp.tool_called`,target 是令牌),归因是真的。
+
+**前置条件本文没记**:#175 把七个工具的执行从 `chat.rs` 的 `match` 里抽成 `tools.rs`,对话与 MCP 共用同一份实现——否则「对话里的 `entity_facts` 和 MCP 里的不是同一个东西」。工具的 JSON schema 仍留在 `chat.rs`,MCP 复用它做转换,已知带一处瑕疵:`search_chunks` 的描述里还写着「可以引用成 [n]」,而 MCP 客户端拿不到引用编号。
+
+**一处会误导人的陈述**:`crates/utopia-mcp` 曾是三行占位,宣称的三个工具名(`add_memory` / `search_memory` / `get_entity_timeline`)从未实现,MCP 服务端住在 `utopia-server/src/api/mcp.rs`。〔已删(2026-09-02,连同 `utopia-graph`、`utopia-connectors`),理由见 [0016](0016-close-the-open-seams-before-cutting-new-ones.md) A2。〕
+
## 未决
- **`query_data` 与 `remember` 要不要进第一版。** 倾向不进——先发四个只读工具
(`search_chunks` / `find_entities` / `entity_facts` / `changes`),把身份这条路走通再说。
- 这两个各自还有没答的问题:外部 agent 写进来的事实挂什么证据?跑 SQL 的审计怎么记?
+ 这两个各自还有没答的问题:外部 agent 写进来的事实挂什么证据?跑 SQL 的审计怎么记?〔**已答:不进**。实际发的是五个而非四个,多一个 `search_docs`。`remember` 的前提是 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 那道闸,而闸还没接上。〕
- **传输层**:stdio(本地,配 Claude Desktop 最省事)还是 streamable HTTP(远程,
- 和 Utopia 已经是个服务端相称)。这个选择不影响本篇的结论,两种都要认令牌。
+ 和 Utopia 已经是个服务端相称)。这个选择不影响本篇的结论,两种都要认令牌。〔**已答:Streamable HTTP**,一条路由 `POST /api/v1/kbs/{kb_id}/mcp`,响应用 `application/json` 不用 SSE——工具一问一答,没有服务端主动推的东西。〕
- **令牌能不能跨工作区。** 现在的 `kb_ids` 是库级白名单;如果将来要按工作区发,
- 和数据源授权那张表会长得很像,届时看要不要合并概念。
+ 和数据源授权那张表会长得很像,届时看要不要合并概念。〔仍未做。〕
+- **(2026-09-02 补)没有界面。** 「UI 默认给 90 天」的 90 天在服务端,而前端根本没有令牌那一页。这是 MCP 今天对用户不可用的直接原因。
diff --git a/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md b/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md
index cda3b952..80ddc2af 100644
--- a/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md
+++ b/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md
@@ -1,6 +1,6 @@
# 0015 · 记下一句话,不等于断言一个事实
-- **状态**:规划中 · schema 未动
+- **状态**:进行中 · schema 已落(迁移 `0018_a_fact_awaiting_a_nod`,与本文同一 PR #180)· **抽取侧尚未接线,三条决定一条都没落地;`remember` 已被整体停用作为临时闸**(2026-09-02 核,修订见文末)
- **成文**:2026-09-01(约定见 [README](README.md))
- **相关**:[0010](0010-no-relation-is-no-relation.md) 删掉兜底关系(本篇那条空谓词正是它的
正确行为)、[0011](0011-a-mapping-is-not-a-fact.md) 批过「拿浮点数编码二值状态」——
@@ -122,6 +122,20 @@ object_value, valid_from, valid_to, ..., confidence, derived_by_rule, supersedes
装上这道闸之后,**外部 agent 也只能提议,不能断言**。人先看见才生效,那条顾虑就不
成立了。所以本篇不只是修一个 bug,它是 0014 里那个「未决」的答案。
+## 修订记录(2026-09-02):只有 schema,没有运行时
+
+`pending_facts` 与 `rejected_facts` 两张表在 #180 建好了,形状按「原句在上、三元组在下」设计:`chunk_id NOT NULL` 指回那句记忆、`proposed_predicate` 存模型原话、`predicate_id` **可空**——人要看见的正是这个空、`proposed_by` 补上「谁的话」。失败方向的论证被完整搬进了迁移注释。
+
+**但全仓零读零写。** `memory::is_memory_document()` 为这道判据写好了,零调用;抽取管线没有任何 `pending_facts` 写入点;Review 的八档计数里没有 `pending` 这一档;`remember` 的回话仍是 `Recorded (effective …)`。
+
+**临时闸是把工具整个关掉**:`chat.rs` 的 `REMEMBER_ENABLED = false`,注释写着「抽取侧接上那张表之后改回 true;在那之前宁可没有这个工具,也不要一个会悄悄改图的工具」。所以三条决定里只有隐含的第 0 条(不让说谎继续)实现了。
+
+**于是下文「MCP 开写的障碍消掉了」在代码上还不成立**——闸没装上,MCP 依旧只读。
+
+**一个数字的更正**:「27 处查询按 `invalidated_at IS NULL` 捞活事实,分布在 6 个文件」——今天是 56 处、7 个文件(多出 `ontology.rs`)。论证方向不变,数字若再被引用应重新数。
+
+**同一类问题的另一面**(#173,迁移 `0015_what_it_did_not_just_what_it_said`):跨轮回放助手上一轮的工具调用与结果,模型才知道自己做过什么,不会把上一轮的检索重跑一遍落到另一批同名实体上。本文讲的是「助手说的」与「图里得到的」之间的落差,那一条讲的是「助手说的」与「助手做的」之间的落差。
+
## 未决
- **闸只拦记忆,还是拦所有「单条、交互式」的写入?** 今天只有 `remember` 这一条路,
@@ -130,4 +144,4 @@ object_value, valid_from, valid_to, ..., confidence, derived_by_rule, supersedes
confidence 表达人的态度,那大概是「不动它」——但要想清楚。
- **拒绝之后那条记忆怎么办。** 文档还在(人确实说过那句话),只是没抽出可用的事实。
下一轮重抽会不会又提议一遍?`concept_mappings` 那边靠 `status='rejected'` 挡住了
- 重复提议,这里需要对应的东西。
+ 重复提议,这里需要对应的东西。〔答了一半:`rejected_facts` 表与查重索引建好了,语义就是「这个三元组在这个库里被拒过」,但没有任何代码写它或查它。〕
diff --git a/docs/decisions/0016-close-the-open-seams-before-cutting-new-ones.md b/docs/decisions/0016-close-the-open-seams-before-cutting-new-ones.md
new file mode 100644
index 00000000..5aa818e1
--- /dev/null
+++ b/docs/decisions/0016-close-the-open-seams-before-cutting-new-ones.md
@@ -0,0 +1,118 @@
+# 0016 · 先把开着的口子收上,再开新的
+
+- **状态**:规划中 · v0.1.0 之后的第一份排期
+- **成文**:2026-09-02(约定见 [README](README.md))
+- **相关**:本文是对 [0001](0001-ontology-import-and-governance.md) 到 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 逐篇对照代码复核之后写的;每一条「待做」都能在那十五篇里找到出处。复核本身的产物是各篇里 2026-09-02 的修订记录,本文只排顺序、只讲为什么是这个顺序
+
+> 这一篇没有实验数字。它是一次盘点:v0.1.0 发出去了,README 的能力表写了十二行,
+> 十五篇决策记录里有三篇的状态行落后于同一个 PR 里的代码。**在开下一条大线之前,
+> 先把「说的」和「做的」对齐一遍。**
+
+## 现状,一段话
+
+一个 Rust 二进制加一个 Postgres:摄入(十种格式、URL / RSS / GitHub / Jira 同步、按源令牌推送)→
+混合检索 → 抽取(本体驱动、预算内全铺、超预算按块检索加祖先补齐、写入时按签名掰正方向)→
+三段消解(等值召回、画像相似、包含关系)加攒批裁决 → 双时态账本(证据、supersedes、合并可回滚)→
+本体从语料长出来(计数采纳、可撤销、默认开)→ 推理机 R0 全建、R1 带开关 → 语义层(概念映射另存、口径有历史)→
+问数(Ontology2SQL,源授权到工作区)→ 对话是 agentic 的,七个工具,跨轮回放自己做过什么 → MCP 只读五工具、个人令牌。
+告警五种,审计台账,每库角色矩阵。约 4.7 万行 Rust、2.2 万行前端、18 个连库测试、8 份可重跑语料。
+
+**这些都是真的。** 下面这些也是真的:
+
+| 半成品 | 出处 | 症状 |
+|---|---|---|
+| `pending_facts` 只有表没有运行时;`remember` 整个停用 | 0015 | README 里有 Chat 记忆,用户用不到 |
+| MCP 只有 API,没有令牌界面 | 0014 | README 里有 MCP,用户配不了 |
+| `utopia-mcp` / `utopia-connectors` / `utopia-graph` 三个 crate 是三行占位,其中一个宣称的工具名从未实现 | 0014 | 读源码的人被误导 |
+| 证明树只展开一层;增量维护没做;派生 vs 断言矛盾不记信号 | 0002 | README 说 derivation path expands back to the sentence,只对了一层 |
+| `disjointWith` 落库了,消解侧仍用硬编码 `CONFUSABLE_TYPE_KEYS` | 0009 / 0001 P5 | 本体声明了不相交,合并候选照样跨过去 |
+| 合并路径没有签名复核 | 0012 待做 | 写入时掰正的方向,合并一次就能再反回去 |
+| 类型消解只能手动跑 | 0001 P3a | 大本体下新实体的细化靠人记得点一下 |
+| 中文库拿到纯英文本体;`zh.ts` 没追平所以界面默认英文 | 0008 / 0004 | 中文用户两头都是英文 |
+| `merge_key` 不折 `_by`;叙述动词进本体 | 0007 | 同一关系两个方向并存 |
+| 预算 24,000 与每块 40 / 30 / 30 标着「待测」;答案键仍是人填的;混装准确率没测 | 0006 / 0008 | 所有「更好」都说不清是改动还是方差 |
+| 语义层映射不留证据;多源同概念全给模型挑 | 0011 | 口径是黑箱 |
+| 映射探查硬依赖 `metric` / `dimension` 两个 key,空库静默零条 | 0009 未决 | 不装包就没有问数语义层 |
+| 关掉自动扩本体后没有「新说法」提醒 | 0003 | 索引铺好了,提醒没做 |
+| `document.no_text_layer` 未接,OCR 端点不存在 | 0005 | 扫描件全绿 |
+| 死代码与陈旧注释:`graph.rs` 的 `confirmed_mappings()`、`confirm_fact` 里的 `mapped_to` 连接、`bootstrap_ontology.rs` 开头的注释、`reasoning.rs` 里写错的迁移号、测试抬头写错的迁移号 | 0010 / 0012 / 0002 / 0014 | 下一个读的人会信 |
+
+## 判据
+
+以后再排期,用这几条判,不重新辩论:
+
+1. **说的和做的要一致。** README 的一行承诺、决策记录的一个状态行、代码里的一句注释——三者不一致时,先改到一致,再谈新功能。[0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 讲的是助手对用户,这条是我们对读者。
+2. **写图的东西先于读图的东西。** 一个会悄悄改图的半成品比没有更坏;一个只读的半成品只是少一个功能。所以 `pending_facts` 排在证明树前面。
+3. **能量的先做。** `scripts/bench/` 在,语料在,缺的是外部答案键。没有它,本体与抽取侧的任何调参都是把过拟合调得更紧([0006](0006-ontology-scale-and-the-prompt.md) 未决)。
+4. **模拟与执行门等地基。** README 路线图的头两条——决策推演、执行校验——本质是「**不落账的提议叠加在账本之上**」。0015 的 `pending_facts` 就是这个形状的第一块砖:一条提议、原句在上三元组在下、人点头才进账。先把这块砖砌稳,模拟引擎才有可以叠的东西。
+
+## 四条线,按这个顺序
+
+### A · 收口——两到三周,不加新概念
+
+**A1 · 把 0015 接上。** 抽取遇到记忆文档(`memory::is_memory_document`,已写好零调用)时写 `pending_facts` 而不是 `facts`;
+Review 加 `pending` 一档,界面**原句在上、三元组在下**;确认 → `insert_fact`,**置信度不动**(0011 的教训:别拿浮点数表达人的态度,人的态度在审计台账里);
+拒绝 → 写 `rejected_facts`,下一轮重抽先查它;`remember` 的回话改成「已记录,抽出 N 条待你确认」;然后把 `REMEMBER_ENABLED` 改回 true。
+**验收**:那条实测(「Acme 把总部搬到深圳」)跑一遍,图上不出现空谓词活边,Review 里出现一条带原句的待确认项。
+做完这一条,MCP 可以放 `remember`(scope = write,令牌以人的身份提议,人自己确认)——0014 未决的答案由此成立。
+
+**A2 · 令牌有界面。** Account 页:列表(前缀、名字、scope、库、最后使用、过期)、发放(明文只显示一次)、撤销;旁边给一段可复制的 MCP 客户端配置(URL + Authorization 头)。
+三个占位 crate **删掉**(已做,与 A3 同一刀):`utopia-mcp` 宣称的三个工具从未存在,服务端住在 `utopia-server/src/api/mcp.rs`;`utopia-graph` 没有对应物;`utopia-connectors` 的意图是对的,但两个连接器看不出边界该划在哪,[0013](0013-a-source-should-hand-over-its-history.md) 说等第三个来了再看抽象,crate 是同一个判断。占位是对读者的承诺,兑现不了就别留,需要时 `cargo new` 是几分钟的事。
+
+**A3 · 清死代码与陈旧注释。** 上表最后一行那五处,加上 `resolution.rs` 里 `CONFUSABLE_TYPE_KEYS` 上方停留在旧世界的注释。一个 PR。
+
+**A4 · README 与代码对表。** Reasoning 那一行的 "derivation path expands all the way back to the original sentence" 在 B1 做完之前改成只承诺一层;
+Chat memory 与 MCP 两处在 A1 / A2 落地前标 in development。中英两份一起改。
+
+### B · 推理机补完——A 之后,与 C 并行
+
+**B1 · R2 证明树。** 递归展开到叶子 chunk 的 API + 实体面板里可展开的树。数据结构(`fact_derivations`)已够。
+**B2 · 派生 vs 断言矛盾要有信号。** `axiom_violations` 加一种 kind(`derived_contradiction`),进 Review 同一档——0002 写了没做的那一行。
+**B3 · `disjointWith` 进消解,合并路径复核签名。** `classify_type_drift` 改从 `entity_type_disjoint` 读(没声明就退回今天的行为,不硬编码);
+`merge_entities` 搬事实前跑一遍与写入时相同的 domain / range 检查,违反的进 `axiom_violations` 而不是静默搬过去。这是 0009 与 0012 各自待做的同一件事。
+**B4 · R3 增量维护——后置。** 只在测量台上全量重推超过一个明确阈值(建议:`ai-timeline-ends` 语料超过 10 秒)时才做。今天每次全量重推活得下去。
+
+### C · 本体与抽取质量——先造尺子,再调参
+
+**C1 · 外部答案键。** 0006 未决的那条:维基条目配 Wikidata `P31` 作类型答案,生成脚本入库。有了它,才能跑 0008 的混装对照(`run.mjs --packs` 已支持)与 0006 的预算曲线。
+**C2 · 类型消解自动触发。** 抽取结束入队一次类型消解(与 `bootstrap_ontology` 并列),只自动落「在原类子树里」的那一档,跨轴仍进人工。**排在 C1 后面**:没有尺子,自动跑等于把噪声规模化(0001 P3 的原话)。
+**C3 · 中文本体。** 三选一,倾向第一个:装包时若 `ontology_lang = zh`,由 LLM 批量生成中文 **description**(模型读的那一行,0004 说它该跟语料语言),存进库、原文 IRI 不动、`label` 不动(label 是 key 的展示,key 永不翻译);
+另两个是「等社区出中文包」与「什么都不做只提示」。同时把 `zh.ts` 追平,把 `navigator.language` 加回 `detect()`。
+**C4 · 0007 的两条尾巴。** `merge_key` 折 `_by` 并把整组标成需对调;叙述动词交给那次同义归并的 LLM 调用一并审(「这些里哪些是文章的口吻」),可撤销。
+**C5 · 0003 的提醒。** 关掉开关后 Ontology 页显示「自上次以来有 N 个新说法」,数据从 `ontology_misses` 按 `dismissed_at IS NULL` 算,索引已在。
+
+### D · 语义层与问数——C1 之后
+
+**D1 · 映射留证据。** `concept_mappings` 加 `evidence`(探查时读了哪几张表的 schema 文档,chunk id 数组),数据映射页展示。
+**D2 · `metric` / `dimension` 出包。** 0009 未决的答案:做一个「Utopia 语义层」包,带 IRI、可选、可替换,与其它包同一条装法;`mappings.rs` 改按 IRI 找类型,不按 key。
+**D3 · 多源同概念的选法。** 先做最简单的规则:问数时若挂载的源只有一个,只给那个源的映射;多个源全给。规则写在 `mappings::confirmed` 一处。
+**D4 · MySQL 线协议。** 白捡 TiDB / OceanBase / Doris / StarRocks,`sqlparser` 换方言。README 路线图里的那条。
+
+### E · 企业交付——v0.2 的门槛,可穿插
+
+- **凭据静态加密**(SECURITY.md 承诺「1.0 之前」;LLM key 与连接串同待遇)——小,可提前。
+- **OIDC SSO**;**备份与恢复命令**;**十万文档基准**(先跑再说,数字比设计重要)。
+- **`document.no_text_layer` + OCR**:告警那条接上要先有 OCR 端点(docling-serve sidecar),两件一起做,提示语才完整(0005 留到第二批的那条)。
+- **`instant` 精度**:0013 说了触发条件(按当地营业日统计、或事件聚在午夜附近的源),没触发前不做。
+
+### 后置:模拟引擎与执行门
+
+README 路线图的头两条**不在这份排期里**,理由见判据 4。它们需要三样地基:`pending_facts` 的提议语义(A1)、派生的可解释性(B1)、派生与断言的矛盾信号(B2)。
+A 与 B 做完之后单独写一篇决策记录,那时再排。
+
+## 顺序与理由,一句话
+
+**A → B ∥ C → D → E。** A 是对齐「说的和做的」,不做新东西;B 与 C 互不依赖,B 动写图的路径、C 动尺子;D 等 C1 的尺子;E 可穿插,加密先。
+
+## 一条新约定
+
+**状态行由实现它的 PR 负责更新。** 0011、0014、0015 三篇的状态行都落后于同一个 PR 里的代码——写决策记录的人和写代码的人是同一个人,在同一个提交里,仍然漏了。
+所以不靠记性:PR 模板里加一行「这个改动实现或推翻了哪篇决策记录,状态行改了没有」。已写进 [README](README.md) 的约定。
+
+## 开放问题
+
+- **A1 的闸只拦记忆,还是拦所有单条交互式写入?** 0015 未决。今天只有 `remember` 一条路,先拦它;将来「在图上手工加一条边」的界面出现时,按同一张表走。
+- **C3 生成的中文描述算不算「原文保真」的例外?** 它不是导入的原文,是我们生成的投影。倾向记成投影(可重跑、可丢弃),原文 IRI 与英文描述保留在包里。
+- **B4 的阈值**:10 秒是拍的。
+- **要不要把抽取层拆出 `utopia-server`。** 今天约 6,500 行领域代码(extraction、type_resolution、bootstrap_ontology、predicate_match、adjudication、owl_import、连接器)住在 HTTP crate 里,依赖方向仍是干净的一条线。讨论过(2026-09-02)决定**不拆**:唯一实在的收益是脱离 server 测纯函数,而它们的单测今天已经不起 server;搬动 1,500 行的 `extraction.rs` 会让紧接着的 A1 diff 和 blame 变难看。判据留下:**等它造成实际损失再拆,损失的定义是「有东西没法脱离 server 测试」**。连接器那一块的边界等第三个连接器(飞书)来了再定。
+- **十万文档基准跑出来之后**,单进程 worker 与内嵌 Tantivy 的天花板在哪,决定了要不要在 v0.2 谈横向扩展。现在不谈。
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index 3b0da89a..ac215b94 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -16,32 +16,37 @@
**结论变得太多时**,另起一篇并在旧篇顶部标 `已被 NNNN 取代`,而不是把旧篇改成新的。
+**状态行由实现它的 PR 负责更新。** 0011、0014、0015 三篇的状态行曾落后于同一个 PR 里的代码——写记录的人和写代码的人是同一个人、同一个提交,仍然漏了。所以 PR 描述里要答一句:这个改动实现或推翻了哪篇决策记录,状态行改了没有。(2026-09-02 加,出处见 [0016](0016-close-the-open-seams-before-cutting-new-ones.md)。)
+
+**行号会漂,文件名会换。** 正文里的 `file.rs:123` 是成文时的坐标,不保证仍然准确;迁移在 #130 / #131 从 53 份折成 10 份、一个域一份,所以 2026-08-31 之前写的迁移文件名都要按域重找。引用时优先写函数名、表名、常量名。
+
**语言**:中文,与代码注释一致(UI 与 README 保持英文)。目前的读者是维护者,不是外部贡献者;将来需要时再译。
## 索引
| | 文档 | 状态 |
|---|---|---|
-| 0001 | [本体导入与治理路线](0001-ontology-import-and-governance.md) | 进行中 · P0–P2c 已建成;P3a 已建成(检索命中率见下)、P3b 部分;P4a 已建成,**P4b/P4c 待做**;P5 由 0002 取代 |
-| 0002 | [推理机](0002-reasoning-engine.md) | 规划中 · 取代 0001 P5 的排期 |
-| 0003 | [本体从语料里长出来,人站在哪一环](0003-ontology-growth-loop.md) | 已建成 · 含三次判断变化的留痕 |
-| 0004 | [语言:哪些字跟着看的人走,哪些跟着语料走](0004-language-and-localization.md) | 已建成 · L0–L3 全部落地 |
-| 0005 | [告警中心](0005-alert-center.md) | 第一刀已建成 · 三个决定推翻两个(就地留痕) |
-| 0006 | [本体规模与抽取提示词](0006-ontology-scale-and-the-prompt.md) | 已建成 · 含可重跑的实测数字与一次撤回 |
-| 0007 | [谁来决定一个说法值不值得成为关系](0007-who-decides-what-becomes-a-relation.md) | 已建成 · 采纳改由计数决定 · 含五条走过的死路 · **叙述动词待解** |
-| 0008 | [预制本体包作为冷启动](0008-ontology-packs-as-cold-start.md) | 规划中 · 建库仍只发种子关系 |
-| 0009 | [「还没判出来」不该是一个类](0009-no-type-is-a-type.md) | 已实施 · `entities.type_id` 改为可空 |
-| 0010 | [「说不出是什么关系」不该是一个关系](0010-no-relation-is-no-relation.md) | 已实施 · `facts.predicate_id` 改为可空 · 0009 在关系侧的孪生 · **含一次七分钟后长回来的修订** |
-| 0011 | [「怎么算」不是「有什么」](0011-a-mapping-is-not-a-fact.md) | 规划中 · 语义层映射搬出本体 · 0009/0010 那条线的最后一段 |
-| 0012 | [本体是一份契约,不只是一份建议](0012-the-ontology-is-a-contract-not-a-suggestion.md) | 已实施 · 五轮对照实验 · 违反率 57%→4%、反向 39→0 · 首次拿真语料问 0008 那个问题 |
-| 0013 | [一个来源该交出它的历史,不是它的现状](0013-a-source-should-hand-over-its-history.md) | 已实施两个(GitHub / Jira 工单)· **文档协作类待做** |
-| 0014 | [身份跟着人,范围跟着令牌](0014-identity-from-the-person-scope-from-the-token.md) | 规划中 · MCP 服务端的第一块地基 · 含一条被否掉的岔路(KB 级机器令牌)|
-| 0015 | [记下一句话,不等于断言一个事实](0015-recording-a-sentence-is-not-asserting-a-fact.md) | 规划中 · 起因是一次实测:助手说的与图里落的不是一回事 · **含一次就地推翻**(状态加在 facts 上 → 自己一张表)· 消掉 0014 里「不开写」的顾虑 |
+| 0001 | [本体导入与治理路线](0001-ontology-import-and-governance.md) | 进行中 · P0–P2c 全建成;P3 按预算落地、P3a 只能手动跑;P3b 建成但形态不同;**P4b/P4c 待做**;P5 已由 0002 落地;判据 2 被 0012 推翻一半 |
+| 0002 | [推理机](0002-reasoning-engine.md) | R0 建成(含本体自检八类)· R1 建成带开关默认关 · **R2 只一层、R3 未做** · 派生 vs 断言矛盾无信号 |
+| 0003 | [本体从语料里长出来,人站在哪一环](0003-ontology-growth-loop.md) | 已建成且仍在跑 · 起点已被 0010 与种子退场改写 · 「拒绝有记忆」被 0007 推翻重做 · 新说法提醒待做 |
+| 0004 | [语言:哪些字跟着看的人走,哪些跟着语料走](0004-language-and-localization.md) | 已建成 · L0–L3 全落地 · 界面刻意不猜浏览器语言 · 「中文内置本体」随播种退场作废 |
+| 0005 | [告警中心](0005-alert-center.md) | 已建成 · 五种告警 · 三个决定推翻两个(就地留痕)· `no_text_layer` 待接 |
+| 0006 | [本体规模与抽取提示词](0006-ontology-scale-and-the-prompt.md) | 已建成 · 「内置类恒在」换成祖先补齐 · 预算与候选数仍待测 · 外部答案键未做 |
+| 0007 | [谁来决定一个说法值不值得成为关系](0007-who-decides-what-becomes-a-relation.md) | 已建成 · 六条缺陷全修 · 起点(种子、`related_to`)已不存在 · `_by` 折叠与叙述动词待解 |
+| 0008 | [预制本体包作为冷启动](0008-ontology-packs-as-cold-start.md) | 已建成 · 五包内嵌、多选、对齐表 22 条 · 三个开放问题全开,中文标签变严重 |
+| 0009 | [「还没判出来」不该是一个类](0009-no-type-is-a-type.md) | 已实施 · `disjointWith` 落库但消解侧未消费 · `metric`/`dimension` 去处未答且有可见代价 |
+| 0010 | [「说不出是什么关系」不该是一个关系](0010-no-relation-is-no-relation.md) | 已实施 · 待做两条随 0011 完成 · 两处死代码待清 |
+| 0011 | [「怎么算」不是「有什么」](0011-a-mapping-is-not-a-fact.md) | 已实施(#126 / #140 / #148)· 证据链未做 · 多源选法未做 |
+| 0012 | [本体是一份契约,不只是一份建议](0012-the-ontology-is-a-contract-not-a-suggestion.md) | 已实施 · 违反率 57%→4%、反向 39→0 · 三条待做全未做 |
+| 0013 | [一个来源该交出它的历史,不是它的现状](0013-a-source-should-hand-over-its-history.md) | 已实施两个(GitHub / Jira)· 文档协作类未开工 |
+| 0014 | [身份跟着人,范围跟着令牌](0014-identity-from-the-person-scope-from-the-token.md) | 已实施(#180)· MCP 只读五工具 · **没有令牌界面** · 误导性的占位 crate 已删 |
+| 0015 | [记下一句话,不等于断言一个事实](0015-recording-a-sentence-is-not-asserting-a-fact.md) | 进行中 · schema 已落、**运行时零接线** · `remember` 整体停用作临时闸 |
+| 0016 | [先把开着的口子收上,再开新的](0016-close-the-open-seams-before-cutting-new-ones.md) | 规划中 · v0.1.0 之后的排期:A 收口 → B 推理机 ∥ C 尺子与本体 → D 语义层 → E 企业交付;模拟引擎后置 |
## 不是决策记录的那些
**[../pipeline.md](../pipeline.md) —— 一份文档如何变成图谱。** 决策记录讲「为什么这样
-而不是那样」;那一篇讲「东西怎么流的、在哪一步会被丢掉」,带四张 mermaid 图。
+而不是那样」;那一篇讲「东西怎么流的、在哪一步会被丢掉」,带五张 mermaid 图(2026-09-02 加了公理那一张)。
新来的人先看它,再回来看这里的理由。
这是本目录约定里说的「第二种性质不同的文档」。它没进子目录——放在 `docs/` 根上,
diff --git a/docs/pipeline.md b/docs/pipeline.md
index 6993b8cb..d9ba1c9d 100644
--- a/docs/pipeline.md
+++ b/docs/pipeline.md
@@ -26,6 +26,11 @@ flowchart TB
TR --> G
GROW --> ONT[(本体)]
ONT -.喂回.-> X
+ G --> R0[一致性检查<br/>公理 vs 事实 · 不写库]
+ ONT --> R0
+ G --> R1[物化推导<br/>开关 · 派生另存]
+ ONT --> R1
+ R1 --> G
style RDY fill:#2d4a5a,color:#fff
style G fill:#2d4a5a,color:#fff
@@ -38,6 +43,12 @@ flowchart TB
**本体那条回流虚线是这套东西的循环**:抽取用本体,抽取遇到本体没有的说法就把原词记下来,
提案回流补进本体,下一批文档的抽取就用上了。见 [0003](decisions/0003-ontology-growth-loop.md)。
+**本体从哪来**:建库时什么都不种。起点是可选的预制包(schema.org 默认勾选,另有 W3C Org、PROV-O、FOAF、IOF Core),
+或者用户导入自己的 OWL,或者空着——空库照样能抽,实体没有类型就是没有类型。见 [0008](decisions/0008-ontology-packs-as-cold-start.md)、[0009](decisions/0009-no-type-is-a-type.md)。
+
+**最下面那两个框是本体的公理在干活**:一致性检查不写 `facts`,只把矛盾摆出来(Review 的 violations / defects 两档);
+物化推导默认关,打开后派生事实另存一张表、图上金色,永远不闭合任何断言事实。见第四节。
+
---
## 一、抽取一个分块
@@ -47,7 +58,7 @@ flowchart TB
subgraph 提示词
B{本体装得下预算吗?}
B -->|装得下| FULL[全量铺<br/>小本体的老路]
- B -->|装不下| RET[按这一块的向量检索<br/>约 40 类 / 30 关系 / 30 属性<br/>+ 内置类恒在]
+ B -->|装不下| RET[按这一块的向量检索<br/>约 40 类 / 30 关系 / 30 属性<br/>+ 命中类的祖先一起铺]
end
FULL --> LLM[LLM]
RET --> LLM
@@ -56,8 +67,12 @@ flowchart TB
J -->|entities| EN[实体<br/>type 从清单挑<br/>specific_type 自由文本]
J -->|predicate 命中属性| AT[属性事实<br/>值按 datatype 归一]
J -->|predicate 命中关系| RL[关系事实]
+ RL --> DIR{主宾类型<br/>对得上签名?}
+ DIR -->|对| OK[落库]
+ DIR -->|主语违反且宾语符合| SWAP[按签名对调主宾<br/>留 direction_corrected]
+ DIR -->|对调也不合法| NOP[谓词留空<br/>主宾时间证据都留]
J -->|词表外 + 字面值| LIT[值落 object_value<br/>原词落 proposed_predicate]
- J -->|词表外 + 实体宾语| FB[降级 related_to<br/>原词落 proposed_predicate]
+ J -->|词表外 + 实体宾语| FB[谓词留空<br/>原词落 proposed_predicate]
style LLM fill:#3a3a5a,color:#fff
```
@@ -68,25 +83,36 @@ flowchart TB
因为清单里总有个"差不多"的,模型选了它,心里那个更准的说法就此丢失。
**词表外的两条路都不丢东西**:带字面值的落 `object_value`(而不是凭空造一个叫「2015」的实体),
-带实体宾语的降级成 `related_to`。两者的原词都进 `fact_evidence.proposed_predicate`,
-那是这条事实身上唯一还留着原意的地方。
+带实体宾语的**谓词留空**——不是降级成一个叫「有关联」的关系,那是断言不是含糊([0010](decisions/0010-no-relation-is-no-relation.md))。
+两者的原词都进 `fact_evidence.proposed_predicate`,那是这条事实身上唯一还留着原意的地方,显示时由 `fact_surface_predicate()` 取回。
+
+**命中的关系还要过一道签名**:本体声明了 `employee (organization → person)`,模型照样会写 `Musk employee Microsoft`——
+提示词三轮都压不下去,英语的 "X is an employee of Y" 太强。所以写入时掰正:主语违反 domain 而宾语符合就对调,**绝不静默**,留一条 `direction_corrected`;
+对调也不合法(`OpenAI affectedBy …`,schema.org 里那是医学检验用的)就丢掉谓词、留下主宾与证据。参数顺序是 key 的编码约定,不是关于世界的断言,所以这一处本体是执法的。
+见 [0012](decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md)。
### 这里会丢东西吗
-会。七种,全部记进 `extraction_drops`,界面上可见:
+会。十二种原因码,全部记进 `extraction_drops`,界面上可见(其中一种不是丢弃,是留痕):
| 原因 | 什么时候 |
|---|---|
+| `truncated_reply` | 模型的输出被截断,这一块整块作废 |
+| `malformed_item` | 一条事实格式不对——**只丢这一条**,不丢整块(#127) |
+| `not_an_entity_name` | 「实体名」是一整句话(按词数 + 限定动词判,#143) |
| `low_confidence` | 模型自报置信度低于阈值 |
-| `subject_not_declared` | 属性事实的主语没在 `entities` 里声明,类型不明、domain 无从校验 |
-| `attr_domain_mismatch` | 属性挂到了 domain 之外的类上(沿父类上溯仍不匹配) |
+| `subject_not_declared` | 主语没在 `entities` 里声明——关系与属性两条路径**都**记 |
+| `attr_domain_mismatch` | 属性挂到了 domain 之外的类上(沿父类 DAG 上溯仍不匹配) |
| `attr_no_value` / `attr_datatype` | 属性事实没给值,或值换算不出声明的 datatype |
| `object_missing` | 关系事实没有宾语 |
-| `fallback_relation_missing` | 本体里连兜底关系都被删了 |
+| `direction_corrected` | **不是丢弃**:主宾按签名对调了,记下来是为了不静默 |
+| `domain_mismatch` | 对调也不合法,谓词被丢掉(主宾与证据留下) |
**`attr_domain_mismatch` 是最贵的一种**:它在落地当场丢弃,而事后改类救不回来——
那条事实从没写入过,只能重抽。
+从前还有一种 `fallback_relation_missing`(兜底关系被删了就整条消失)——随 `related_to` 一起没了。
+
---
## 二、实体消解:这一条是谁
@@ -203,16 +229,56 @@ flowchart TB
### 这里会丢东西吗
-不丢事实,但**改类不进时间轴**——它是 `entities` 上一次 UPDATE 加一行 `entity_retypes`,
-而实体历史只读 `facts`。所以改错了不会自己显形。**可撤销不等于会被撤销**,
+不丢事实,但**改类不进时间轴**——它是 `entities` 上一次 UPDATE 加一行 `entity_retypes`〔实体历史现在会显示 `retyped` / `retype_reverted` 两种事件,这一条已经补上〕。**可撤销不等于会被撤销**,
这是先做 preview 再做 apply 的理由。
+**类型消解今天只能手动跑**——本体页 preview → apply,没有任何自动触发。抽取结束只入队本体扩展与实体裁决。
+所以大本体下新实体的细化依赖人记得去点一下,这是个真缺口(0001 P3a)。
+
+**人拍过板的不再被引擎重判**:`entities.type_source` 是 `human` 的实体不进取材,包括「人判了,就是没有类型」(0001 P4a)。
+
**拒绝要给理由。** `left_alone` 曾经只是个数,而这一步的设计押在"选择都不是是个体面答案"上——
最大的一档不透明。记上理由之后第一次跑就回答了此前答不出的问题:失败**全在检索一侧**
(`administrative_area`、`periodical` 从没被端上来过),不在裁决。
---
+## 四、公理:检查与推导
+
+```mermaid
+flowchart TB
+ ONT[(本体的公理<br/>functional · symmetric · asymmetric<br/>transitive · inverseOf · subPropertyOf · disjoint)] --> SELF[本体自检<br/>八类缺陷]
+ SELF --> DEF[(ontology_defects)]
+ ONT --> R0[事实层检查<br/>自环 · 反对称 · 传递环 · 基数]
+ G[(图谱)] --> R0
+ R0 --> VIO[(axiom_violations<br/>带完整路径)]
+ VIO --> DEC{人裁}
+ DEC -->|撤回事实| RET[事实作废]
+ DEC -->|放宽公理| RLX[改本体]
+ DEC -->|接受| ACC[两条都留]
+ ONT --> R1{materialize_inferences<br/>开关,默认关}
+ G --> R1
+ R1 -->|开| DER[(derived_facts<br/>另一张表 · rule_id · 前提链)]
+ DER --> GV[图上金色边<br/>实体面板「推出来的」]
+
+ style DEC fill:#3a3a5a,color:#fff
+```
+
+**检查不写库,推导写另一张表。** 一致性检查(R0)只指出问题,风险面为零;物化推导(R1)会往图里加东西,所以它的每条约束都是必要的:
+规则**只从本体公理编译**,没有用户 DSL;**断言硬性优先于派生**——已经断言过的三元组不再派生,「这条是谁说的」有唯一答案;
+深度上限加环检测,每谓词封顶两万条且被截掉的**要说出来**;有效时间取前提的交集,空交集不推。
+派生不进 `facts`:四十多处读 `facts` 的查询只有一处认得标记,分开之后忘了 UNION 的后果是**看不见**派生,而不是**混进去**。
+
+**本体自检排在前面**:自相矛盾的本体(一个关系既 symmetric 又 asymmetric、子类成环、逆没指回来)会让事实层的结论全部可疑。
+
+**没装本体包的库跑出来是零**,那是实情不是故障——没有公理就没有判据,不报矛盾比猜一个公理出来安全。
+
+**什么时候跑**:导入本体后自动跑一次检查(公理刚变,最该重算的时刻);Review 页可手动跑;推导按 `inference_interval_minutes`(缺省 60)定时全量重推——增量维护还没做。
+
+### 这里会丢东西吗
+
+不丢,但**有两处沉默**:派生 vs 断言矛盾时派生不落地,今天**不记信号**;同一三元组有多条推导路径只留第一条证明。两者都是 [0002](decisions/0002-reasoning-engine.md) 里写了而没做的。
+
## 想自己跑一遍
`scripts/bench/` 是可重跑的测量台,**每一组一个新库**——复用一个库省几分钟,
@@ -238,3 +304,5 @@ node scripts/bench/run.mjs --corpus holmes --label holmes
- [0001](decisions/0001-ontology-import-and-governance.md) 本体导入与治理,含 P3 的实测修订
- [0003](decisions/0003-ontology-growth-loop.md) 本体从语料里长出来,人站在哪一环
- [0006](decisions/0006-ontology-scale-and-the-prompt.md) 本体规模与抽取提示词,含曲线与一次撤回
+- [0002](decisions/0002-reasoning-engine.md) 推理机的顺序与安全边界;[0012](decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md) 写入时的方向掰正
+- [0009](decisions/0009-no-type-is-a-type.md) / [0010](decisions/0010-no-relation-is-no-relation.md) 为什么「还没判出来」不是类、「说不出」不是关系