Skip to content

World's first open-source enterprise world model.

The decision records are condensed into English (#244)

WaylandYang953c048fb4f7
diff --git a/docs/decisions/0001-ontology-import-and-governance.md b/docs/decisions/0001-ontology-import-and-governance.md
index c63cf84d..1d5f5dd4 100644
--- a/docs/decisions/0001-ontology-import-and-governance.md
+++ b/docs/decisions/0001-ontology-import-and-governance.md
@@ -1,581 +1,265 @@
-# 0001 · 本体导入与治理路线
-
-- **状态**:进行中 · 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 的修订记录)。
-
-## 为什么是这条线
-
-产品的差异化是"时间"与"可信",而这两样的上游都是**本体**:抽取器按本体决定抽什么、归成什么类;时态引擎按本体的 `functional` 决定什么算矛盾;消解按类型决定谁能和谁是同一个。本体不对,下游全歪,而且歪得沉默。
-
-企业已经有自己的本体(FIBO、行业标准、Protégé 自建),让他们在界面上一条条重建不现实。所以这条线的终点是:**把企业本体导进来,让抽取按他们的词汇工作,并且治理过程本身能沉淀。**
-
----
-
-## 已验证的事实(2026-08-28,真实语料测得)
-
-用公开企业新闻稿建了 `Industry Corpus` 库(NVIDIA 博客 18 篇 + 微软新闻室 10 篇,RSS 摄入):
-
-| 指标 | 数值 |
-|---|---|
-| 文档 / 分块 | 28 / 181 |
-| 实体 / 事实 | 917 / 922 |
-| **实体密度** | **5.07 个 / 分块** |
-| 消解:自动合并 / 待人工 | 10 对 / 5 对 |
-| 攒批裁决任务数 | 22(处理 917 实体的消解对) |
-| 图谱总览查询 | 103 ms |
-| as-of 查询 | 107 ms |
-| 实体变更历史(NVIDIA 122 事件) | 16 ms |
-| 当前 9 类本体在提示词中的体积 | 466 字符 |
-
-**跨文档消解成立**:NVIDIA 聚合了 16 篇文档的 118 条事实,没有裂成同名副本。
-
-**已修的三个缺陷**(分支见文末):
-
-1. HTTP 客户端不发 User-Agent → 维基百科等站点 403,URL/RSS 对一大片真实网站直接失效
-2. HTML 提取全文档遍历 → 一篇维基条目 60 个分块,首块整块是侧栏菜单、末块是版权声明
-3. `part_of` 被标成 `functional` → 28 篇新闻稿积压 59 条假冲突("属于 Microsoft Learn"与"属于 Microsoft"并存不是矛盾)
-
-**未解决的质量问题**:Product 类占 40%(368 个),抽样约四分之一是泛化短语("row power center"、"financial databases")。补救手段是给类写描述(description 进抽取提示词)。
-
-> **原文这里写「目前只能整库重抽,因为实体不可单独编辑」——P0 建成后不再成立。**
-> 今天有三条更细的路:实体面板直改(受 P4a 的 `type_source` 保护)、类型消解批量精化、
-> 本体长出新类后的 `adopt_proposed_types` 认领。整库重抽不再是唯一手段。
-
----
-
-## 贯穿性判据
-
-以后遇到新构造、新特性,用这几条判,不要重新辩论:
-
-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,与消解的"宁分勿合"同源。
-6. **治理经验固化进 schema,不要固化成隐形规则**。改一次类描述是可见、可评审、进审计台账的;从点击里长出来的自动规则半年后没人知道为什么。
-7. **唯一 ≠ 身份**。`key` 有 `UNIQUE (kb_id, key)`,但它派生自会变的东西(label / 局部名),而身份要求跨时间稳定。只要两个不同的全局事物可能想要同一个 key,key 就必须附带"来自何处"才能当标识符——那就是 IRI。另:**IRI 是名字不是地址**,绝大多数不可访问,不要去抓取,也不要把 http/https、末尾斜杠"规范化"成同一个。
-
----
-
-## 分阶段
-
-### P0 · 实体可编辑 —— 地基,且现在就在流血
-
-**问题**:实体是只读的。`/kbs/{id}/entities/{entity_id}` 只有 GET,store 层唯一的 `UPDATE entities SET type_id` 在 `resolution.rs:388`(合并时自动升格),前端面板没有任何编辑入口。类型判错、名字抽歪,只能整库重抽这把大锤。
-
-**做**
-- `PATCH /kbs/{id}/entities/{entity_id}`,Editor 权限,可改 `type_id` / `canonical_name`
-- 落审计台账:`entity.retyped` / `entity.renamed`,detail 带前后值快照(沿用决策台账的自包含快照约定)
-- 前端:实体面板头部加编辑入口
-
-> **修订记录**:初稿写「`entities` 上有唯一索引,改名会撞 409」。**两处都错**——`entities_kb_type_name_idx` 是**普通索引不是唯一索引**,而且同类同名的重复**现在就存在**(`General` 库「张伟」×2、「rust compiler」×2)。更要紧的是:不该加那个约束。
-
-**碰撞是提示,不是拒绝**:「张伟」×2 正是"宁分勿合"的设计产物——两个不同的人可以同名同类,消解的整个灰区逻辑依赖于能把他们分开存放。所以改名/改类型撞上同名时:**查出来、提示"已有同名实体,是否合并?"、但允许继续**。加唯一约束会砸掉消解的地基,报 409 会让用户无法录入第二个张伟。
-
-**动机数据**:`General` 库里跨类型同名的——"rust" **5 个**、"java" 3 个、"c++" 3 个。同一个东西被分进五个类,今天无法收拾。
-
-**验收**:能把 "row power center" 从 Product 改成 Concept,改动出现在审计台账,图谱与本体页的计数同步。
-
----
-
-### P1 · 停止静默丢弃 —— 小,但现在就在流血
-
-> **修订记录**:这一格原本是"关系的 range 校验",理由是"对现有语料立刻生效"。**那句是错的**——查证后:23 个关系里只有 2 个有 domain(就是那两个属性),**range 一条都没有**,因为 UI 里没有这一项、没有任何东西会写它。range 数据只可能来自 OWL 导入,所以它不可能独立于 P2 生效。range 的正确位置见 P2(导入并保存)与 P3(作为信号之一消费)。
-
-**真正现在就在流血的**:抽取器把事实**静默丢弃**——抽出来了、被挡掉、不留任何痕迹,用户看不见,只是图里少了东西。与"账本 append-only、每条事实都有证据、不确定性浮到人面前"三条原则直接冲突。
-
-**范围比最初判断的大**(2026-08-28 逐行核过 `extraction.rs`)。属性路径不是一个 `continue`,是四个真丢弃:
-
-| 行 | 条件 | 性质 |
-|---|---|---|
-| 255 | 主语未在 `entities` 中声明 | 真丢弃 |
-| 257 | `domain_type_id` 为 NULL | **不可达**——`ontology.rs:197` 强制 attribute 必有 domain,`update_relation_type` 又不许改 kind/domain(`ontology.rs:290`)。且无 domain 的属性连提示词都进不去(`extraction.rs:122` 的 `r.domain_type_id?`)。防御性代码,不需要信号 |
-| 261 | domain 不匹配 | 真丢弃(最初只点了这一条) |
-| 269 | 既无 `value` 也无 `object` | 真丢弃 |
-| 274 | datatype 归一化失败 | 有 `debug!` 日志,但用户不可见 |
-
-关系路径另有两条值得记:`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` 兜底类随 [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 清空
-- 不复用 `ontology_misses`:那张表语义是"你的本体缺这些"(面向本体演进),丢弃是"这些事实没落地"(面向数据完整性),两者的读者和动作都不同
-- 按 document 归集顺带修好生命周期:`ontology_misses` 只在整库 rebuild 时清(`graph.rs:689`),来源级重抽不清,会攒陈旧条目。新表按 document 清则天然正确
-
-**验收**:故意给 Person 专属属性喂一个 Organization 主语,Library 的文档行能看到"3 条事实未落地",点开有原因与样例,事实不再无声消失。
-
----
-
-### P2 · OWL 导入
-
-**架构分三层,关键在第一层**
-
-1. **原文保真**:导入的本体文件原样进 blob store(内容寻址那套摄入管道在用),`ontology_imports` 记录 (kb_id, blob sha, 文件名, 时间, 投影版本)。这一步不理解语义,只负责不丢。
-2. **投影**:把今天能消费的子集映射进 `entity_types` / `relation_types`。**是可重跑的推导,不是一次性转换。**
-3. **重投影**:推理机上线或我们补上新校验时重跑,用户什么都不用做。
-
-这样"我们表达不了"从**能力缺口**降级成**投影暂未覆盖**。
-
-**映射表**
-
-| OWL / RDFS | Utopia | 备注 |
-|---|---|---|
-| `owl:Class` | entity_type | |
-| `rdfs:subClassOf` | **多父**(见下) | |
-| `rdfs:label` | `label` | 优先 `@en`/`@zh` |
-| **`rdfs:comment`** | **`description`** | 承重:进抽取提示词,也是 P3 检索的匹配依据 |
-| `owl:ObjectProperty` | relation_type (`kind=relation`) | |
-| `owl:DatatypeProperty` | relation_type (`kind=attribute`) | |
-| `rdfs:domain` | `relation_type_domains`(多值关联表) | 见下"多值域" |
-| `rdfs:range` | `relation_type_ranges`(多值关联表)/ `datatype` | 同上;**只存不强制**,消费者是 P3/P5 |
-| `owl:FunctionalProperty` | `functional` | max-cardinality-1,时态引擎的命根子 |
-| `owl:InverseFunctionalProperty` | `inverse_functional` | |
-| IRI | 新增 `iri` 列 | 见下"IRI 与 key 的分工" |
-| 其余公理 | **保留在原文,报告为"暂未投影"** | 不是"已跳过" |
-
-**IRI 与 key 的分工**:`key` 有硬约束——只允许 `[a-z0-9_]`、最长 40 字符(`ontology.rs:77`),而且它是**给模型读写的令牌**:提示词列的是 key,模型返回的 `type` 是 key,`type_ids` 按 key 查。IRI 塞不进去(冒号斜杠井号全非法),放宽约束的话提示词变成 800 行 URL,还要模型逐字复现——截断或幻觉一个字符就匹配失败。
-
-所以:**IRI 是全局身份(权威),key 是模型标签**。key 从 IRI 派生(命名空间前缀 + 局部名,snake_case,冲突加后缀),短而稳定。存储:一个可空 TEXT 列 + `UNIQUE (kb_id, iri) WHERE iri IS NOT NULL`;手工建的类为 NULL,无负担。
-
-**为什么 key 唯一了还要它**——重导入是本体功能上线就会撞到的第一件事:
-
-```
-v1: http://acme.com/hr#Employee rdfs:label "Employee" → key = employee
-v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_member ← 同一个类
-```
-
-没有 IRI 只能二选一,都错:建新类 `staff_member` 把 `employee` 变孤儿(实体全挂在上面),或按 label 匹配(label 正是刚变的那个)。有 IRI 就是一次 `WHERE iri = $1`,改名字,实体不动。
-
-想「那 key 就从局部名派生」也撑不住:`foaf:Person` 与 `acme:Person` 都要 `person`,谁拿 `_2` 后缀取决于导入顺序,下次重导入分不出 `person_2` 是谁的——除非记下它来自哪个 IRI,那就是 IRI 列绕一圈重新发明。另两个用途:**溯源**(上游类被手改后重导入要调和,得先知道它是上游的)与 **P5 导出**(key 反推不出命名空间,有损)。
-
-**多值域(domain / range)**:OWL 里并集是常态(`works_at` 的值域可能是 `Organization ∪ Project`),单列表达不了,用关联表存,判定走子类 DAG。
-
-导入的语义陷阱:RDFS 中同一属性的**多条 `rdfs:range` 是交集**("必须同时是两者"),不是并集——极常见的建模错误,但规范如此。`owl:unionOf` → 直接进表;多条独立 `rdfs:range` → 一者是另一者的子类则取更具体的,互不包含则**报告"暂未投影",不猜**。
-
-**domain/range 的正确用法是提示词里的类型签名,不是闸门**
-
-关系在提示词里从 `- works_at (works at): 描述` 变成 `- works_at (works at): Person → Organization。描述`。这是**给模型的类型签名**,在源头减少 "Alice works_at 西雅图" 这类三元组,而不是等错了再修——事后校验面对的是既成事实(丢掉可惜、留着是脏数据),签名是在生成那一刻掰正。
-
-**是引导不是强制**:本体写错时模型看到原文说了别的仍可覆盖;强制闸门则会系统性丢数据(`part_of` 烧我们的正是这种方式)。
-
-大本体下(P3 规模)它换位置继续有用:预测谓词时,**domain/range 与实际主宾类型匹配的候选关系排名更高**,作为检索排序信号。
-
-三件事的必要性不同:**存**(是,P5 的正经输入,成本在解析器里本来就要写)、**进提示词当签名**(是,最高性价比,约十行)、**校验/自动升格/违规队列**(否,P3 用更丰富的证据做同一件事,且用可能错的声明驱动自动动作风险高)。
-
-**交集不实现,理由是架构性的**:**因为保留了原文,投影就不必语义完整**。投影只服务提示词与界面展示,两者都接受简化;需要完整语义的是推理机,而它读的是 blob 里的原文。实现交集意味着要表达"既是 A 又是 B"的匿名类——往描述逻辑走的第一步,会把 schema 拖进类表达式的泥潭,而收益只是提示词多一行字。
-
-**多继承要真支持**:`type_matches_domain`(`extraction.rs:137`)沿单父链上溯。丢掉一个父分支,那分支上的属性会**静默失配**——抽出来了、写入时被挡、不报错。补法:`entity_type_parents` 关联表存全部父类,domain/range 判定走 DAG(访问集防环),左栏仍按主父展示成树,避免同一个类出现多次。
-
-**两个必须在预览里说清的**
-- **哪些关系会因 `functional` 而开启冲突检测**——这正是 `part_of` 那个坑,企业本体声明为函数性但数据不遵守,导完就是一队假冲突
-- **有多少类没有 `rdfs:comment`**——它们在 P3 的自动分类里质量会明显偏低
-
-**流程**:上传 → **dry-run 预览**(新建/更新/暂未投影各多少、上述两项警告)→ 确认才落库。绝不让上传一个文件就不可逆地改掉本体。
-
-**v1 砍掉**:OWL/XML 与 Manchester 语法(Turtle + RDF/XML 覆盖 Protégé 导出的绝大多数)、任何推理、个体导入、反向导出。
-
-**个体(ABox)永不作为事实导入**——不是能力问题,是原则:每条事实必须有证据链和出处,凭空塞进来的实例破坏的正是这个地基。它们随原文件保存,将来推理机可当背景知识读。
-
-**依赖**:`oxttl` + `oxrdfxml`(Oxigraph 那套小而专的 crate)。不引 `horned-owl`,我们不需要推理。工作区目前无任何 RDF 依赖。〔已引入,住在 `utopia-ingest`。〕
-
-> **修订记录 · P2a + P2b 已落地**(`feat/owl-import`)
->
-> 落地的是三层里的前两层与整条预览流程:解析(`utopia-ingest/src/ontology_rdf.rs`)、
-> 计划与执行(`utopia-server/src/owl_import.rs`,预览与落库**共用同一个 `plan()`**)、
-> 界面(本体页左栏底部 Import 入口 → 选文件 → 计划 → 确认)。
-> `ontology_imports` 表与 `entity_types.iri` / `relation_types.iri` 见 `ontology_imports` 的建表注释。
->
-> **对着真实词汇表验证,不是自己写的样例**。FOAF(RDF/XML,635 三元组):
-> 15 类 + 89 属性,`functional` / `inverse_functional` / domain / range 全部读出;
-> DCTerms(Turtle,700 三元组):22 类 + 55 属性。**自己手写的样例文件全部通过,
-> 而真实的 FOAF 在第一行就死了**——格式判定写反了,而且文件开头的 `<!--` 注释把
-> `<rdf:` 推出了嗅探窗口。现在扩展名是强信号,内容只在明显是 Turtle 时才推翻它。
->
-> **预览多报一件本文没写的事:key 撞车**。FOAF 的 `Person` 与我们内置的 `person`
-> 同名不同身份。当时想的是自动加后缀,但那会让**下一次重导入认不出自己上次建的是
-> 哪个**——这正是本文论证 IRI 必要性时用的那个例子,只是换了个方向出现。所以:
-> 报告,不解决。想要导入的那份,先给现有的改名。
->
-> 〔**后来改了一半**(#78、#145):本地同名行**没有 IRI**时被认领——它是种子或手工建的占位者,被词表接管否则整棵树是断的;认领时形状跟着改成「方」(词表声明的)。两边都有 IRI 而 key 撞车的仍然报告不解决。〕
->
-> **暂未落地的三件**——属性落库、domain/range 关联表与类型签名、多继承 DAG——
-> 照着 P2b 的产物重新算过账,独立成节:见下方 **P2c**。〔四件均已落地,见 P2c 末尾。〕初稿在这里写的依赖顺序
-> 有一处高估了(属性落库要等的那个映射,P2b 里已经建好了),那节里就地留痕。
->
-> **一个自己犯的错值得记**:`OntologyImportView` 的字段叫 `imported_at`,前端类型
-> 写成了 `created_at`。TypeScript 一声不吭——类型是我声明的,它只保证代码内部自洽,
-> 不保证与服务端一致。界面上显示成 `Invalid Date` 才发现。同一次还有服务端往
-> `conflict_with` 里塞了中文兜底文案 `(手工建的)`,直接漏进英文界面。
-> 两件事同一个教训:**服务端不产出展示文案**,措辞归界面;跨语言的边界要用真数据看一眼。
-
----
-
-### P2c · 属性落库、domain/range、类型签名、多继承
-
-> 这一节是 P2a/P2b 落地后照着代码重新算的账。三件事的依赖顺序与初稿不同,
-> **其中一件比初稿估计的近**——原文说属性落库要等 domain 解析,而那个映射
-> 在 P2b 里已经建好了。
-
-#### 一、属性落库:单域的现在就能做
-
-属性在产品里早已完整:`relation_types` 一表两用(`kind='attribute'`),
-`domain_type_id` 指明挂在哪个类下,`datatype` / `unit` 描述取值,值走
-`facts.object_value`,时态、证据、审阅全套复用(见 `relation_types.kind`)。
-
-缺的只是**导入器不建它们**。FOAF 的 54 个 `owl:DatatypeProperty` 解析出来了、
-预览里报了数,但 `apply()` 跳过。初稿把原因记成"要 domain,而 domain 要等类
-先建好并解析 IRI → id"——**那个映射 `id_of: HashMap<IRI, Uuid>` 在 P2b 里
-已经为解析父类建好了**。真正缺的是三小件:
-
-- **`rdfs:range` → `datatype`,三路而不是两路**:
-
- | 情形 | 处置 |
- |---|---|
- | range 能映射 | 照映射建。number 收 `decimal` `integer` 及其全部有界/无符号变体、`double` `float`、`owl:real` `owl:rational`;date 收 `date` `dateTime` `dateTimeStamp` `gYear` `gYearMonth`(我们的日期格式本就是 `YYYY[-MM[-DD]]`,逐级可省);bool 收 `boolean`;text 收 `string` 及其派生、`anyURI`、`rdf:langString`、`rdfs:Literal` |
- | **没写 range** | 建成 `text`,在预览里列出。词汇表没做声明,我们只知道是字面量,`text` 是诚实的超集 |
- | range 存在但**类型**表达不了 | 建成 `text` **并报告**:`time` `gMonth` `gDay` `gMonthDay`(缺年)、`duration` 系列(时长不是时点)、多条 `rdfs:range`(交集陷阱:不猜类型,但值仍是字面量)、以及任何我们不认识的类型 IRI |
- | 抽取器**不可能从散文里读出**这种值 | **跳过并报告**:`base64Binary` `hexBinary`(二进制块)、`rdf:XMLLiteral`(XML 片段)、`QName` `ID` `IDREF` `ENTITY`(XML 内部管道) |
-
- > **两次修订,第二次推翻了第一次。**
- >
- > 初稿说「不猜成 text,因为类型错的属性会让取值被 `attr_datatype` 挡掉」。
- > 查 `normalize_attr_value` 后不成立——**`text` 接受任何字符串,从不拦**,
- > 会拦的是 number / date / bool。
- >
- > 于是改成「range 存在就是词汇表做了声明,降级成 text 会把它扔掉且不留痕迹」。
- > **这条也站不住**:预览就在报告它,何来「不留痕迹」。而跳过的代价是属性根本
- > 不存在,抽取器不会被告知它,那条知识**彻底不会被捕获**——这正是本仓库反复
- > 当成最坏结果的那种失败。
- >
- > 正确的分界不是「能不能精确映射」,也不是「该不该进图谱」——属性值本来就在图谱里。
- > 是**「抽取器有没有可能从散文里读出这个值」**。「门店每天 9:00 开门」里有
- > `09:00`,所以 `xsd:time` 的属性填得上,按 text 存只丢排序语义,值还在。
- > 一张 base64 平面图不会出现在散文里,所以那个属性建了也永远是空的。
- >
- > 跳过它保护的不是数据(本来就不会有值),是**提示词**:每个属性都是抽取
- > 提示词里的一行,每个文本块付一遍,永远填不上的那些就是逐块付费的死噪音。
-- **domain 指向没被导入的类**(外部词汇表里的类):跳过 + 计入预览,不静默。
-- **多个 `rdfs:domain`**:存不下。这一条才真的要等关联表。
-
-所以顺序是:**先落单域属性**(P2b 的产物已经够用),多域的随关联表一起。
-
-> **顺带查明的一件事:属性抽取这条路此前是死的。**
->
-> 代码是全的——提示词里有属性段与规则 10,`ExtractedFact` 有 `value`,
-> `normalize_attr_value` 按 datatype 校验,值落 `facts.object_value`,证据/时态/审阅全套复用。
-> 但**内置本体一个属性都没有**,所以 `attr_lines` 一直是空的,整段属性提示词从未出现过。
-> 除非有人手工建属性,这条路从落地起就没被执行过。
->
-> OWL 导入开始建属性,它就变成活的了。端到端验过一遍(三个 datatype 各一个):
->
-> ```
-> floor_area {"value": 860} number,不是字符串
-> opened_on {"value": "2024-09-01"} date
-> opens_at {"value": "10:00"} text(降级的 xsd:time)
-> ```
->
-> 证据、置信度、界面渲染都对,零丢弃信号。**`opens_at` 那两条在旧的跳过规则下
-> 根本不会存在**——这是存得下就别丢那个决定的直接证据。
-
-#### 二、关联表:多值 domain/range
-
-```sql
-relation_type_domains(relation_type_id, entity_type_id) -- 谁能当主语
-relation_type_ranges (relation_type_id, entity_type_id) -- 谁能当宾语
-```
-
-OWL 里一个属性有多个 domain 是常态。`datatype` 仍留在 `relation_types` 行上——
-数据属性的 range 是字面量类型不是类,`ranges` 表只服务对象属性。
-
-**规范上的坑(前文已述,此处只标处置)**:同一属性的多条 `rdfs:domain` 在 RDFS 里
-是**交集**不是并集。一者是另一者的子类则取更具体的;互不包含则报"暂未投影",不猜。
-
-#### 三、提示词类型签名
-
-关系行 `- works_at: 描述` 变成 `- works_at (person → organization): 描述`。
-
-**它是签名不是闸门**——在生成那一刻减少"Alice works_at 西雅图",而不是等错了再拦。
-事后校验面对的是既成事实(丢掉可惜、留着是脏数据),签名是在写出来之前掰正。
-本体写错时模型看到原文说了别的仍可覆盖;硬闸门会系统性丢数据,`part_of` 烧我们
-的正是那种方式。
-
-> **新增约束(来自 0004 的语言工作):签名里必须用 key,不能用 label。**
-> 中文库里 `person` 的 label 是「人物」,写成 `(人物 → 组织)` 等于教模型输出
-> 一个不存在的类型。这与"描述里引用其它类型一律用 key"是同一条理由,
-> 而且今天已经把 label 整个撤出了提示词(有描述时不送),签名不该把它请回来。
-
-#### 四、多继承 DAG
-
-`entity_types.parent_id` 曾是单列,只能表达树。而多继承在真实词汇表里
-是常态——FOAF 的 `Person` 同时是 `foaf:Agent` 与 `geo:SpatialThing`,两个方向,
-不是同一根链上的祖孙。P2b 目前**只投影第一个父类**。
-
-丢掉一支的后果:`type_matches_domain`(`extraction.rs`)沿存下来的那条单链上溯,
-所以 domain 在另一支上的属性判定不过——`latitude` 的 domain 是 `SpatialThing`,
-而 `person` 只挂在 `agent` 下,这条事实抽出来了却被挡掉。
-
-> **修订**:初稿把这个后果写成"静默失配"。#41 之后不再静默——
-> `extraction.rs` 会发 `attr_domain_mismatch` 丢弃信号,在文库里显示成
-> "属性挂在了错误的类上"。仍然是错的(那条事实本该落地),但看得见。
-> 严重度因此从"无声丢知识"降到"可见地少一条",优先级相应后移。
-
-改动落在四处:
-
-| | 现在 | 之后 |
-|---|---|---|
-| 存储 | `parent_id` 单列 | `entity_type_parents(child_id, parent_id)` 关联表 |
-| 上溯 | 单链循环 10 次 | 广度优先 + **访问集**(菱形继承会重复到达同一祖先) |
-| 建/改类 | 无环风险 | **必须查环**:A→B→A 会让上溯死循环 |
-| 左栏 | 直接是树 | 仍按**主父**展示成树 |
-
-最后一行是产品判断:**存储是 DAG,展示是树**。左栏若如实画 DAG,`person` 会同时
-出现在 `agent` 和 `spatial_thing` 底下,用户点哪个都对,但会以为是两个东西。
-所以保留"主父"专供展示——它不再是唯一的父,只是画树时选的那一支。
-
-#### 顺序与理由
-
-1. **单域属性落库** —— 只欠 range→datatype 映射,把一个自陈的洞补完
-2. **domain/range 关联表** —— 解锁多域属性,且是签名的前提
-3. **提示词类型签名** —— 十行,本文认定的最高性价比项
-4. **多继承 DAG** —— 独立于前三项,但因为不再静默而排在最后
-
-前三项是一条链,第四项可以并行。
-
-> **修订记录(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 的修订。
-
----
-
-### P3 · 类型消解 —— 让大本体可用
-
-**问题**:今天类型由 LLM 在抽取时从**内联清单**里挑。9 个类很好;800 个类时提示词爆炸且准确率下降。
-
-**分三层,第一层最要紧**
-
-1. **抽取只给粗类型**——提示词永远只列基础类(person/organization/product/place/event/concept)。**提示词大小从此与本体规模无关。**
-2. **类型消解(新后台任务)**——类的 `label + description` 嵌入成向量(一次性);实体积累名字和事实后,用**合成文本**(名字 + 参与的谓词 + 粗类)嵌入检索 top-k 候选类,只把这 k 个交给 LLM 裁决。高置信自动升格,灰区进 Review,结果缓存。
-3. **推理推出的类型**——有 `equivalentClass` 定义的类无需模型判断(等 P5)。
-
-> **修订记录(跑过真实本体之后)**。上面三条写在没人量过真实本体的时候,实测把
-> 其中两条推翻了。原文留着,因为推翻它的理由比结论有用。
->
-> **一、「800 个类」是低估,而且类清单不是大头。** schema.org 当前版实测 1010 类 /
-> 1676 属性,抽取提示词 **109,083 tokens 一个分块**。三段的占比是
-> 类 38% / 关系 34% / 属性 28%——**第一层只碰得到 38% 的那一段**,且原文完全没提
-> 属性段。就算把类砍到只剩顶层,提示词仍有约 64k。
->
-> **二、「只列基础类」是错的**,理由有三条,都在数据里:
-> - 它把用户自己编的本体从抽取里整个拿掉。40 个类约 2k tokens,**根本不构成问题**;
-> 拿 968 个类的数字去论证所有本体都只列 6 个,是过度外推。我们只有 12 个类(好)
-> 与 968 个类(坏)两个点,中间一片空白。
-> - 它是 `related_to` 那个坑的镜像:**给了逃生舱模型就会用**。只列基类等于让所有
-> 东西都只能是 `organization`。
-> - 抽取当场因粗类丢掉的事实**改类救不回来**(`type_matches_domain` 在落地时就
-> 校验 domain,实测见 `attr_domain_mismatch: position@person`);而粗类还会让
-> 实体互相更"像",`classify_type_drift` 判不出 `Disjoint`,可合并候选变多,
-> **合并是真写账本的**。
->
-> **改成按预算**:本体小于预算就全列(今天就是这样且工作正常);超了才按分块检索
-> top-K 内联,**且种子基类永远在场**当兜底。属性按 domain 逐类展开,类被裁了它自动
-> 跟着裁。预算按 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 · 类型消解实测(已建成)
-
-抽取给粗类,另给一个 **`specific_type`**:自由文本、不校验、不入本体,就是模型自己
-对这个实体的说法。**它是这一步的关键**——没有它,实测 17 个实体的 `proposed_type`
-全是空的,因为清单里总有个"差不多"的(本体有 `product`,模型选了它,心里那个
-"向量数据库软件"就此丢失)。有了它,任务从「读懂这是什么」变回「本体里哪个类叫
-这个名字」:短名字对短标签,正是向量索引擅长的形状。加上它之后,检索命中从
-**4/17 变成约 13/20**。
-
-**候选两路来,取并集不合分数**:一路拿画像搜类的描述,一路拿语境向量搜已定类的
-实体、把它们的类当票投。第二路冷启动时结构性无效(库里已定类的实体全挂着基类,
-投不出更细的东西),它是第一路跑过一轮之后的放大器。
-
-**距离不可比,三处都栽过**:跨实体不可比(`清华大学计算机系→computer_store` 0.46
-比 `星云科技→corporation` 0.59 还近,而前者荒谬);两路之间不可比(类空间 vs
-实体空间);**同一路的两个查询之间也不可比**——短查询"医药集团"产生的距离系统性地
-小于一整段画像,按距离合并就让名字那一路独占前几名,实测挤掉了三个上一轮自动
-通过的正确答案。**一律交替取,不合分数。**
-
-**分档不能用模型自报的 confidence**:实测是双峰的(15 条全 ≥0.85、4 条 null,
-中间没有)——自报置信度是语气不是概率。改用「选中的类在不在粗类子树里」:在 =
-往下走一格,自动;不在 = 换了分类轴,进人工。
-
-> **但这条判据测的往往不是风险。** 第二份语料 24 个实体报了 14 条跨轴、条条正确,
-> 因为它实际在测**种子类跟导入词汇表的分类树连没连上**:`organization`/`product`
-> 的 key 撞上了 schema.org 的同名类(被认领,子树 167/8 个后代),而 `location`
-> 没撞上——schema.org 的 `Place` 另起一个 key、209 个后代全挂那边,内置 `location`
-> 零子类,于是每一次 `location → city` 都算跨轴。
->
-> 缓解办法是**按类对认可,不按实体**(`type_refinement_pairs`):跨轴是
-> (粗类, 目标类) 这一对的属性,人认可一次就不再问。根治要把种子类接进导入本体的
-> 分类树——那是本体对齐,比这一步大。
-
-**拒绝必须给理由。** `left_alone` 一开始只是个数,而这一步的整个设计押在"选择
-'都不是'是个体面答案"上——最大的一档不透明。记上理由之后第一次跑就回答了此前
-答不出的问题:失败**全在检索一侧**(`administrative_area`、`periodical` 从没被端
-上来过),不在裁决。
-
-**改类不进时间轴**:它是 `entities` 上一次 UPDATE 加一行 `entity_retypes`,
-实体历史只读 `facts`。所以错了不会自己显形——可撤销不等于会被撤销。这是先做
-preview 再做 apply 的理由。**该补的是让改类在实体历史里显形**,而不是把类型搬上
-双时态账本(P0 明确把实体做成可变行)。
-
-#### P3b · 关系清单同样会膨胀(原先漏掉的)
-
-
-> **本节的抽取侧已建成**(撤逃生舱、提示词规则 8、表层谓词落在证据上);
-> **映射回本体那一半也建成了,但形态与这里写的不同**——不是全自动的检索裁决,
-> 而是「聚类 → 带影响面的提案 → 一键采纳并改写 → 可撤销」,加一个默认开启的开关。
-> 见 [0003](0003-ontology-growth-loop.md),含三次判断变化的留痕。
-
-上面只解决了实体类型。但提示词里紧挨着类清单的是**关系清单**,同样由本体全量展开、同样每个分块重发。实测(Industry Corpus):9 个类 197 字符,10 个关系 **250 字符**——关系已经是更大的那一半。且**代码库无任何 prompt caching**(`cache_control` 零命中),O(分块 × 本体) 没有缓存兜底。部门级本体(300 类 / 400 属性)约每分块 4200 token,181 分块 76 万输入 token——而这才 28 篇文档。
-
-**当初漏掉的原因是一个不对称**:`(NVIDIA, acquired, Mellanox)` 不知道 NVIDIA 是 Organization 也是完整事实——**类型是挂在节点上的注解,可延后**;而 `(NVIDIA, ?, Mellanox)` 不是事实,**谓词就是事实本身**,"先空着后补"不通。
-
-**出路是换中间态**:延后到**表层谓词**而非延后到空——`(NVIDIA, "acquired", Mellanox)`,自由文本,可存,模型无需词表即可产出。第二遍带着完整句子和检索候选映射到本体关系,与类型消解同一套机器。domain/range 在这里作排序信号(主宾类型匹配的候选排名更高)。
-
-三档处置与实体消解同源:高置信改写谓词(**必须追加而非原地改**——插入新行 + `supersedes`,与人工纠正同构,实体历史页直接可展示"先记成 related to,后精化成 builds");灰区进 Review;**没有像样候选就保持 `related_to`** 并把短语变成本体建议。最后一档是关键——**`related_to` 是诚实的含糊,猜错则是自信的错误**〔**后被推翻**:保持「我不知道」确实比猜一个具体关系诚实,但那份诚实不该实现成本体里的一个词——界面上显示「有关联」不是含糊而是断言。见 [0010](0010-no-relation-is-no-relation.md)〕,而下游推理机会拿着错的具体关系去推导。
-
-#### 但映射只是一半:更大的一半是撤掉逃生舱
-
-> **修订记录**:本节原本只写"抽取产出表层谓词、再映射"。查证后发现**那只覆盖约一成**,得拆成两条腿。
-
-实测(Industry Corpus):
-
-```
-ontology_misses 16 种谓词 / 38 次降级
-related_to 事实 359 条
-```
-
-**只有约 38 条是降级来的,其余 321 条(89%)是模型自己挑的 `related_to`。** 因为它就在本体清单里,提示词把它当合法选项列了出去(`rel_pairs` 只过滤 `kind == "attribute"`)。模型读到说不清的关系时不会去造词,直接拿这个万能选项——**我们递了个逃生舱,它用了 321 次,而这个逃生舱销毁信息。**
-
-(核对过其他来源:`mappings.rs` 写的是 `mapped_to` 不是 `related_to`;`record_miss` 在事实循环里每条一次,所以 38 是降级事实数的上界。)
-
-所以两条腿:
-
-1. **把 `related_to` 从提示词里撤掉**(保留在本体中当代码层兜底,但不列给模型)〔**括号内已作废**:`related_to` 整个删掉了,兜底改在读的时候发生,见 [0010](0010-no-relation-is-no-relation.md)〕。这样模型要么用真关系、要么写出原文说法,**兜底发生在代码里而非模型脑子里,短语一定被记下**。改动就是 `rel_pairs` 加一个过滤,极便宜——但**必须先有 `surface_predicate` 列**,否则只是把信息从"变成 related_to"换成"变成 related_to 外加一次 miss 计数"。
-2. **映射**(上文那套检索裁决)。
-
-**存量修不回来**:现有 359 条没有 surface predicate,其中 321 条根本无原词可恢复。**只能靠重抽。** `Industry Corpus` 是基准语料,重抽是分内事;但这套逻辑若落到用户跑了半年的库上,必须明说"只对新抽取生效,存量要重建"。
-
-**流水线已跑了三分之二**:`ontology_misses` 有活数据(`available_from ×9`、`scales_to ×5`、`runs_on ×4`、`collaborated_with ×4`),`extraction.rs:366-383` 已在接受词表外谓词并记录表层形式,缺的只有映射那一步。今天它只是给人看的报表,不是消解器的输入。
-
-**前置缺陷(需先修)**:降级有损——`f.predicate` 只进了 `record_miss` 的聚合,**事实上一字未留**,今天无法回答"哪些事实从 `available_from` 降级而来"。同"原文保真"原则:**先别扔,扔了不可逆**。
-
-> **修订记录**:初判是加 `facts.surface_predicate`。**错了**——查 `graph.rs:164-175` 后发现事实是去重的,该列会先写者胜。正确位置是 `fact_evidence`。
-
-**放在 `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`〔落地时列名叫 **`proposed_predicate`**,下同〕,两条路径都写(关系路径写降级前的 `f.predicate`;正常命中时写模型实际给的那个词,因为它可能是别名)。不等映射落地就有独立价值——Review 与实体面板可直接展示"原文说的是 available from,被降级成 related to",而今天前端对 `related_to` 无任何特殊处理(`web/src/` 里零命中),降级对用户完全不可见。
-
-**映射不取代 miss 报表**:反复出现又映射不上的(`available_from ×9`)正是"本体该加这个关系"的治理信号(P4 燃料)。映射只吃高置信的那部分,其余留在 miss 里变建议。
-
-**不要用 `profile_embedding` 做检索**:它是实体所在分块的质心,代表"出现在什么样的文档里"而非"是什么"。人物出现在 GPU 发布稿里,质心也是 GPU 味的。必须用合成文本重新嵌入。
-
-**成本(按实测数据推算)**
-- 对现有小本体部署:**0**——类数低于阈值(约 30)时不启用,粗类即细类
-- 对比"天真导入 500 类":**大幅省**。500 类塞进提示词约 8,000 tokens × 181 分块 = 140 万额外输入 tokens;检索方案把提示词按回 466 字符
-- 净增:**调用次数 +15~20%,tokens 约 +5%**——类型消解调用不含分块正文,比抽取调用小一个数量级;攒批(现有裁决任务已做到约 40:1)+ 分层阈值让多数实体不进 LLM
-- 新增:917 个短文本嵌入,量级相当于再嵌一百来个分块
-
-**真正的风险不是成本是质量**:大本体下错判会把噪声规模化。缓解仍是判据 4——只有相似度高且与次优拉开差距的才自动升格,灰区进 Review。
-
-**第一次抽取一定有类型**:`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 · 治理即经验
-
-> 实际长出来的治理闭环是另一个形状——采纳即改写、可撤销、开关控制自动,
-> 见 [0003](0003-ontology-growth-loop.md)。三件事里**第 1 件已建成(2026-08-30,#114)**,
-> 2、3 待做。
-
-**顺序不能反**:先有 P0 的编辑能力,才有"人工决策"可保护、可学习。
-
-1. **决策不可被遗忘(正确性,不是功能)** —— **已建成**(`entities.type_source` · #114)。
- `entities.type_source`(extracted / human / inferred),四条路径各有守卫:
- 类型消解取材、本体新类认领、抽取升格、改类落库(`actor` 有值即 `human`)。
-
- > **原文的前提当时就已经不成立,记在这儿因为找错方向比没找更费时间。**
- > 这里写的是「重抽会静默吃掉治理成果」,而抽取那条路早有守卫
- >(`resolve_type_drift` 只在 `type_key.is_none()` 时升格)。真正的漏在
- > **类型消解**:取材条件里「现类还有子类就纳入」会把人拍过板的实体一并捞回去重判。
- >
- > 而 [0009](0009-no-type-is-a-type.md) 之后又多一种:「没有类型」现在可能是
- > **人的决定**,`type_id IS NULL` 分不出「还没判」和「人判了,就是没有」。
-
-2. **决策记忆做检索** —— **待做**。`resolution_verdicts` 已经是这个模式的一半,
- 但按 `pair_key` 精确匹配、不泛化。类型决策要走一步:存下人工改类时的检索向量与结果,
- 下次分类时**检索最相近的历史决策当证据**交给裁决器。按语境相似度泛化,不按名字相等(判据 3)。
-
- > **建议排在评测语料之后**:这是三件里唯一一件「做完了也说不清是不是更好」的,
- > 而本文头号开放问题正是缺真实企业本体做小样本评测。没有基准就调它,等于再拍一次脑袋。
-
-3. **纠正聚合成本体信号(收益最高)** —— **待做**。一个月里 37 个实体从 Product 挪到
- Concept,该修的不是那 37 条,是 Product 的描述太松。Ontology 页加信号面板:
- "Product → Concept 迁移 37 次(近 30 天)",点开看样例,旁边"用 AI 起草更严格的描述"
- ——与现有 misses 面板的 Suggest with AI 完全同构。
-
- > **数据源是 `audit_events`,不是 `entity_retypes`。** 人的纠正走两个动作:
- > `entity.retyped`(实体面板直改,逐条)与 `ontology.refinement_approved`
- >(审核队列批准,批次带 from/to/moved),两条都带 actor。
- > `entity_retypes` 是**撤销台账**(批次作用域),拿它聚合会混进引擎自己的改类——
- > 那读出来是「引擎在反复改主意」,不是「人在反复纠正你」。
-
----
-
-### P5 · 推理机(远期)
-
-> **排期已由 [0002](0002-reasoning-engine.md) 取代**。本节列的"届时能消费什么"仍然成立,但顺序变了:0002 实测发现语料第一天就带 `part_of` 环(传递闭包在深度 5 起振荡不收敛),所以推理机的第一交付是**一致性检查**而非推导——同一套求值引擎反过来用,零风险,且现存 11 处矛盾立刻可查出。
-
-`utopia-reason` 目前是 3 行空壳〔**已建成**,近两千行:R0 一致性检查与本体自检、R1 物化推导带开关,见 [0002](0002-reasoning-engine.md) 的修订〕。它上线后能消费的,正是 P2 保留而未投影的那些公理:
-
-- `TransitiveProperty` → "NVIDIA 名下所有东西"(现在只能靠 hops 逐跳猜)
-- 非 1 的基数被违反 → **一致性告警进 Review 队列**,本体成为数据质量规则
-- `someValuesFrom` / 类表达式 → 自动归类,实体无需显式标注类型
-- `equivalentClass` / `inverseOf` / 属性链 → 常规推理输入
-- `disjointWith` → 剪掉可证伪的跨类型合并候选(`resolution.rs:103` 的"类型漂移"逻辑会跨类型召回,这里能拦下不可能的组合)
-
-**这些今天全部读不了,但 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 是拍的**——类数超过多少才启用类型消解,需要实测校准〔这根轴不存在,换成了字符预算;新的待测量是每块 40 / 30 / 30,见 [0006](0006-ontology-scale-and-the-prompt.md)〕
-- **`disjointWith` 与 `SymmetricProperty` 收益中等**:前者剪枝防错误合并;后者去重(新语料里测得 8 对互为反向的重复事实,占 910 条的 1%)。排在 P2 之后按需〔Symmetric 已进 R0 检查与 R1 规则;disjointWith 进了本体自检,**消解侧剪枝仍未做**〕
-
----
-
-## 基准语料
-
-`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 自己知道,写进文档只会过期。
+# 0001 · Ontology import and governance
+
+- **Status**: In progress. P0, P1, P2 and P2c built. P3's budget switch built
+ (`deployment_settings.ontology_prompt_budget`, default 24,000 characters; over budget the ontology
+ is retrieved per chunk, [0006](0006-ontology-scale-and-the-prompt.md)). P3a built but runs only by
+ hand. P3b built in a different shape: the surface predicate lands on
+ `fact_evidence.proposed_predicate`, and mapping back is `predicate_match` plus the adoption loop of
+ [0003](0003-ontology-growth-loop.md). P4a built (`entities.type_source`, #114); P4b and P4c pending.
+ P5 delivered by [0002](0002-reasoning-engine.md). The "argument order" half of criterion 2
+ overturned by [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md). Checked against the code
+ 2026-09-02.
+- **Written**: 2026-08-27 / 28 · condensed into English 2026-09-03
+- **Related**: [0002](0002-reasoning-engine.md) replaces P5's schedule;
+ [0003](0003-ontology-growth-loop.md) is what P3b and P4 became;
+ [0006](0006-ontology-scale-and-the-prompt.md) holds the prompt budget;
+ [0009](0009-no-type-is-a-type.md), [0010](0010-no-relation-is-no-relation.md) and
+ [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) each overturn one claim below;
+ conventions in [README](README.md)
+
+> Reasons outlive lists. The cross-cutting criteria come before the phases, and overturned judgments
+> stay on the page.
+
+## The problem
+
+The product's differentiation is time and trust, and both sit downstream of the ontology: the
+extractor decides what to extract and which class it lands in; the temporal engine reads `functional`
+to decide what counts as a contradiction; resolution uses type to decide who may be the same entity.
+A wrong ontology bends everything below it, silently.
+
+Enterprises already have ontologies (FIBO, industry standards, Protégé models), and rebuilding one
+class at a time in a UI is unrealistic. So the target is: import the enterprise ontology, extract in
+its vocabulary, and let the governance work leave a trace.
+
+Baseline, measured 2026-08-28 on `Industry Corpus` (18 NVIDIA blog posts + 10 Microsoft newsroom
+items): 28 documents / 181 chunks, 917 entities / 922 facts, 5.07 entities per chunk, cross-document
+resolution holding. Product was 40% of entities and about a quarter of a sample were generic phrases
+("row power center"). `part_of` marked `functional` had produced 59 false conflicts. The bench has
+since moved to `scripts/bench/` (0012); these numbers are real but no longer comparable.
+
+## Decisions
+
+### Cross-cutting criteria
+
+1. **Keep the original; project what we consume.** Discarding is irreversible, storing is nearly
+ free. The imported file is kept verbatim and the projection covers only what has a consumer
+ today. Corollary: because the original is kept, the projection need not be semantically complete;
+ a simplification is a UI or prompt trade-off, never data loss.
+2. **The ontology guides which types take part.** A declaration can be wrong (`part_of` was), so the
+ ontology shapes the prompt and candidate ranking and drives no discard, overwrite or rewrite: a
+ wrong guide is overridden by the text, a wrong gate destroys data systematically. **Argument
+ order is enforced** (0012): it is the key's encoding convention, no claim about the world. A
+ subject that violates the domain while the object fits is swapped and marked
+ `direction_corrected`; if the swap is also illegal the predicate is dropped and subject, object
+ and evidence are kept. Five rounds measured: violation rate 57% → 4%, true reversals 39 → 0.
+3. **Prompt size is decoupled from ontology size.** N classes in every chunk's prompt costs
+ O(chunks × ontology), and a model choosing among 800 options chooses worse. Scale is solved with
+ retrieval.
+4. **A shared name carries no conclusion.** Same entity: one type already. Different entities: the
+ name is exactly the signal we distrust (two people called 张伟). Context carries the information.
+5. **Uncertainty surfaces to a person.** Tiered thresholds, gray zone into Review; same root as
+ resolution's "keep apart when unsure".
+6. **Governance experience is fixed in the schema.** Changing a class description is visible,
+ reviewable and audited; a rule grown out of clicks is a mystery six months later.
+7. **Uniqueness and identity are different things.** `key` is `UNIQUE (kb_id, key)` but derived from
+ a label that changes; identity must hold across time, so it needs a "where from": the IRI. An IRI
+ is a name and never an address: never fetch it, never normalize http/https or trailing slashes.
+
+### P0 · Editable entities (built)
+
+8. `PATCH /kbs/{id}/entities/{entity_id}` (Editor role) changes `type_id` and `canonical_name`; the
+ audit ledger gets `entity.retyped` / `entity.renamed` with before and after snapshots; the entity
+ panel has the edit entry. Before this the only repair was re-extracting the whole KB.
+9. **A name collision is a prompt.** Two 张伟 of the same type are the intended product of "keep apart
+ when unsure"; `entities_kb_type_name_idx` is a plain index and duplicates already exist. On rename
+ or retype the UI says "an entity with this name exists, merge?" and lets the user continue. A
+ unique constraint or a 409 would break resolution's ground.
+
+### P1 · No silent drops (built)
+
+10. The extractor used to drop facts with no trace, which contradicts an append-only ledger, evidence
+ on every fact, and uncertainty in front of a person. Table `extraction_drops (kb_id, document_id,
+ reason, detail, count, example, updated_at)`, primary key on the first four, cleared per document
+ when extraction starts. Eleven reason codes today, including `subject_not_declared`,
+ `attr_domain_mismatch`, `truncated_reply`, `malformed_item`, `not_an_entity_name` and
+ `direction_corrected`; the Library shows "N facts did not land" per document.
+11. It is separate from `ontology_misses`: misses say "your ontology lacks these" (read by whoever
+ evolves the ontology), drops say "these facts did not land" (data completeness). Clearing per
+ document also fixes a lifecycle bug: misses were cleared only on a full rebuild.
+
+### P2 · OWL import (built)
+
+12. **Three layers.** The file goes verbatim into the blob store (the content-addressed ingest path)
+ and `ontology_imports` records kb, blob sha, filename, time and projection version. The
+ projection into `entity_types` / `relation_types` is a re-runnable derivation, redone when a new
+ consumer appears with nothing asked of the user. "We cannot express it" thereby becomes "not yet
+ projected".
+13. **Mapping.** `owl:Class` → entity type; `rdfs:subClassOf` → `entity_type_parents`; `rdfs:label` →
+ `label` (`@en` / `@zh` preferred); `rdfs:comment` → `description`, load-bearing because it enters
+ the extraction prompt and is what P3's retrieval matches on; `owl:ObjectProperty` → relation and
+ `owl:DatatypeProperty` → attribute (`relation_types.kind`); `rdfs:domain` / `rdfs:range` →
+ `relation_type_domains` / `relation_type_ranges`, stored as signals, never as gates;
+ `owl:FunctionalProperty` / `InverseFunctionalProperty` → the two flags; the IRI → `iri` column,
+ `UNIQUE (kb_id, iri) WHERE iri IS NOT NULL`. Every other axiom stays in the original and is
+ reported as not yet projected (P5 has the current list).
+14. **IRI is identity, key is the model's token.** `key` is `[a-z0-9_]`, at most 40 characters, what
+ the prompt lists and the model returns; an IRI cannot fit there. A key cannot be identity either:
+ on re-import `hr#Employee` relabelled "Staff Member" would orphan `employee` or be matched on the
+ label that just changed; with the IRI it is one `WHERE iri = $1` and no entity moves. Keys from
+ local names fail the same way (`foaf:Person` and `acme:Person` both want `person`). Hand-made
+ types have `iri = NULL`.
+15. **Multi-valued domain and range** live in link tables and are checked through the subclass DAG.
+ RDFS treats several `rdfs:range` on one property as an intersection; the importer takes the more
+ specific when one subsumes the other and otherwise reports it as not projected. Intersection
+ itself is not implemented: it is the first step into class expressions, and the projection only
+ serves prompt and UI (criterion 1).
+16. **Domain and range are a type signature in the prompt**: `works_at (person → organization)`. It
+ corrects "Alice works_at Seattle" at generation time. Only classes laid out in the prompt are
+ named, a side with none selected falls back to `*`, and the signature uses keys, never labels: a
+ Chinese KB's label 「人物」 would teach the model a type that does not exist.
+17. **Preview before commit.** Upload → dry run (new / updated / not projected counts, which relations
+ turn on conflict detection through `functional`, how many classes lack `rdfs:comment`) → confirm.
+ A key collision between two IRIs is reported and left to the user; a local row without an IRI
+ (seed or hand-made placeholder) is claimed by the vocabulary and takes its shape (#78, #145).
+18. **Individuals (ABox) are never imported as facts.** Every fact needs an evidence chain; instances
+ stay in the stored file as future background knowledge for the reasoner.
+19. **Parser**: `oxttl` + `oxrdfxml` in `utopia-ingest`, Turtle and RDF/XML only; no `horned-owl`, no
+ reasoning, no export. Validated on FOAF (635 triples) and DCTerms (700 triples). The file
+ extension is the strong format signal; content overrides it only when it is clearly Turtle.
+20. **Attributes** (`create_attribute_with_iri`): `rdfs:range` → `datatype` three ways. A mappable XSD
+ type gets its datatype; no range → `text`, listed in the preview; a type we cannot express
+ (`time`, `gMonth`, `duration`, several ranges, unknown IRIs) → `text` and reported; a type the
+ extractor could never read out of prose (`base64Binary`, `hexBinary`, `XMLLiteral`, `QName`,
+ `ID`, `IDREF`, `ENTITY`) is skipped and reported. The dividing line is "can this value appear in a
+ sentence": skipping protects the prompt, where every attribute is a line paid per chunk. A domain
+ pointing at a class that was not imported is skipped and counted.
+21. **Multiple inheritance is real.** FOAF's `Person` is both `foaf:Agent` and `geo:SpatialThing`;
+ keeping one parent makes attributes on the other branch fail their domain check.
+ `entity_type_parents (child_id, parent_id, is_primary)` replaces the old single column; ancestry
+ is breadth-first with a visited set; creating or editing a type checks for cycles; the left pane
+ still draws a tree by primary parent, because a class shown twice reads as two classes.
+ `update_relation_type` may change domain and range (a signature is no identity); `kind` stays
+ immutable.
+
+### P3 · Type resolution and the prompt budget
+
+22. **A character budget decides how much ontology enters the prompt.** Under
+ `ontology_prompt_budget` (24,000) the whole ontology is listed, which is how every small KB
+ works. Over it, each chunk retrieves its top-K classes, relations and attributes (40 / 30 / 30,
+ untested) and the ancestors of every hit are laid out with it. Attributes expand under their
+ domain class, so a pruned class prunes its attributes. Details in 0006.
+23. **P3a · Type resolution** (built; runs from the Ontology page as preview → apply → undo).
+ Extraction returns a coarse type plus `specific_type`: free text, unvalidated, never written to
+ the ontology. Without it 17 of 17 `proposed_type` were empty, because the list always had
+ something close enough (`product` chosen, "vector database software" lost); with it the task
+ becomes "which class has this name", and retrieval hits went from 4/17 to about 13/20.
+ Candidates come from two routes, the profile against class descriptions and the context vector
+ against typed entities whose classes vote, taken alternately and never merged by score. Tiering
+ asks "is the chosen class inside the coarse type's subtree" (one level down → automatic; another
+ axis → a person), acknowledged per `(coarse, target)` pair in `type_refinement_pairs`. Every
+ `left_alone` carries a reason. A retype is an UPDATE on `entities` plus an `entity_retypes` row,
+ and entity history reads `facts` only, so a wrong retype does not show itself; hence preview
+ before apply.
+24. **P3b · Surface predicates** (built, in a different shape). A predicate is the fact itself, so it
+ cannot be deferred to "empty" the way a type can; it is deferred to the surface phrasing, stored
+ on `fact_evidence.proposed_predicate`, one per observation, written on both paths (the phrase that
+ failed to map, or the model's actual word on a hit, which may be an alias). `facts` deduplicates
+ on `(kb_id, subject_id, predicate_id, object_id)`, so a column there would be first-writer-wins.
+ Mapping back is `predicate_match` plus 0003's adoption loop; a phrasing that keeps missing stays
+ an ontology signal.
+
+### P4 · Governance as experience
+
+25. **A human decision is never forgotten** (built, #114). `entities.type_source` is `extracted` /
+ `human` / `inferred`, guarded on four paths: type-resolution sampling, class claiming
+ (`adopt_proposed_types`), extraction upgrade, and retype (an `actor` makes it `human`). The real
+ leak was type resolution's sampling rule "current class still has subclasses → include", which
+ re-judged entities a person had settled; extraction was already guarded (`resolve_type_drift`
+ upgrades only when `type_key.is_none()`). Since 0009 "no type" can itself be a human decision.
+26. **Decision memory as retrieval** (pending). Store the retrieval vector and outcome of a human
+ retype and hand the nearest past decisions to the judge as evidence, generalizing by context
+ (criterion 4). `resolution_verdicts` is half of this pattern but exact on `pair_key`. Waits for
+ an evaluation corpus: it is the one item whose benefit cannot be judged without one.
+27. **Corrections aggregate into ontology signals** (pending). "Product → Concept 37 times in 30
+ days" means Product's description is too loose; the Ontology page should show it with samples
+ and "draft a stricter description", like the misses panel. Source is `audit_events`
+ (`entity.retyped`, `ontology.refinement_approved`, both with an actor); `entity_retypes` is the
+ undo ledger and includes the engine's own retypes.
+
+### P5 · Reasoner
+
+28. Delivered by 0002. Projected today: `TransitiveProperty`, `SymmetricProperty`,
+ `AsymmetricProperty`, `IrreflexiveProperty`, `FunctionalProperty`, `InverseFunctionalProperty`,
+ `disjointWith` (`entity_type_disjoint`), `inverseOf`, `subPropertyOf`. Still not projected:
+ `equivalentClass`, `someValuesFrom` and class expressions, property chains. `disjointWith` is
+ consumed only by R0's ontology self-check; `classify_type_drift` still uses the hardcoded
+ `CONFUSABLE_TYPE_KEYS` (0009 named this).
+
+## Dead ends
+
+- **A unique index on entity names, 409 on rename.** Duplicates already existed, and two people with
+ one name are what "keep apart when unsure" is for.
+- **"Range validation on relations" as P1.** No relation had a range and only two had a domain; the
+ UI never wrote one. Range can only come from import.
+- **Auto-suffixing a colliding key.** The next re-import cannot tell `person_2` from `person`; the
+ IRI argument in reverse. Report instead.
+- **Sniffing the format from content.** Hand-written OWL samples all passed and real FOAF died on
+ line one: the check was inverted and a leading `<!--` pushed `<rdf:` out of the window. The
+ extension decides; content overrides it only when clearly Turtle.
+- **Waiting for an IRI → id map before importing attributes.** `id_of` already existed from parent
+ resolution; only the range → datatype mapping was missing.
+- **Skipping attributes whose range we cannot map.** Two arguments fell in turn: "text would be
+ blocked by `attr_datatype`" (text is never blocked) and "downgrading loses the declaration
+ silently" (the preview reports it). A skipped attribute is never told to the extractor, so the
+ knowledge is never captured; the end-to-end check produced `opens_at 10:00` (downgraded `xsd:time`)
+ that the skip rule would have lost.
+- **"List only the base classes" for large ontologies.** schema.org measured 1010 classes / 1676
+ properties, 109,083 tokens per chunk, classes only 38% of it. Six base classes would remove a
+ 40-class user ontology (about 2k tokens, no problem) from extraction, hand the model an escape
+ hatch as `related_to` did, and lose facts at extraction time that a later retype cannot recover
+ (`attr_domain_mismatch: position@person`); coarser types also make entities look alike, and the
+ resulting merges write the ledger.
+- **A class-count threshold (about 30) for enabling type resolution.** Never existed; the axis is
+ the character budget. "Seed base classes always present" died with the seeds (#128); ancestor
+ fill-in replaced it.
+- **Merging retrieval scores.** Distances are incomparable across entities (清华大学计算机系 →
+ `computer_store` at 0.46 beat 星云科技 → `corporation` at 0.59), across the two routes, and between
+ two queries on one route: a short name query scores systematically lower than a whole profile and
+ pushed out three correct answers.
+- **The model's self-reported confidence for tiering.** Bimodal (15 at ≥ 0.85, 4 null, nothing
+ between): tone, no probability.
+- **The subtree test as a risk measure.** On the second corpus 14 of 24 were "cross-axis" and all
+ correct: the test measured whether seed classes were connected to the imported taxonomy
+ (`location` had zero subclasses, schema.org's `Place` had 209). Per-pair acknowledgement mitigates;
+ the cure is ontology alignment, larger than this step.
+- **`profile_embedding` for class retrieval.** It is the centroid of the entity's chunks, "what
+ documents it appears in", so a person in GPU launch posts smells of GPUs. Re-embed a synthetic text
+ (name + predicates + coarse type).
+- **Keeping `related_to` as honest vagueness.** "I don't know" is honest; a relation named "related
+ to" on the graph is an assertion. Of 359 such facts 321 were the model choosing it from the list,
+ so the hatch was removed from the prompt, then the relation deleted (0010).
+- **Upgrading types on the extraction job chain.** Extraction only enqueues `bootstrap_ontology` and
+ `adjudicate_entities`; the retrieval hit rate was too low to run unattended.
+- **"Re-extraction silently eats governance" as P4a's premise.** Extraction was already guarded; the
+ leak sat in type-resolution sampling. Looking in the wrong place cost more than looking nowhere.
+- **Server-produced display text.** A Chinese fallback `(手工建的)` leaked into the English UI, and a
+ frontend type declared `created_at` for the server's `imported_at` and rendered `Invalid Date`.
+ Wording belongs to the interface; cross-language seams get checked with real data.
+
+## Revisions
+
+- 2026-09-02: assumed `type_id` was NOT NULL and the coarse type always the first type; 0009 made it
+ nullable, and "no type" may be a person's decision.
+- 2026-09-02: assumed argument order was guidance like everything else; 0012 made it enforced.
+
+## Open questions
+
+- Upgrade accuracy has no number; it needs a real enterprise ontology for a small-sample evaluation,
+ and P4b waits behind it.
+- The 24,000-character budget and the 40 / 30 / 30 per-chunk counts are untested; the measurement
+ is to raise the inlined class count from 12 towards 968 and watch fact count and latency.
+- Type resolution runs only when someone clicks: under a large ontology, refinement of new entities
+ depends on a person remembering to.
+- `disjointWith` pruning of merge candidates on the resolution side is not done.
+- The `active` flag has only a governance use left (retired classes take no new entities); whether
+ it is worth building waits for a real large ontology.
diff --git a/docs/decisions/0002-reasoning-engine.md b/docs/decisions/0002-reasoning-engine.md
index d18a742b..3363ae5b 100644
--- a/docs/decisions/0002-reasoning-engine.md
+++ b/docs/decisions/0002-reasoning-engine.md
@@ -1,140 +1,89 @@
-# 0002 · 推理机
-
-- **状态**: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(该节保留原判断,本文取代其排期)
-
-placeholder 里写着意图:*"Temporal Datalog interpreter for derived facts with explanations, plus the ontology axiom compiler."* 方向对。本文定的是**顺序**和**安全边界**。
-
----
-
-## 核心判断:第一交付是一致性检查,不是推导
-
-**推理机是缺陷放大器。** 在 `Industry Corpus`(28 篇公开新闻稿)上实测的底子:
-
-| 指标 | 数值 | 含义 |
-|---|---|---|
-| `related_to` 占比 | **359 / 922 = 39%** | 近四成的边语义是空的(词表外谓词降级,见 0001 P3b) |
-| `part_of` 事实 | 185 | 传递规则的第一个目标 |
-| `part_of` 传递闭包 | 828(深度上限 10) | 4.5 倍膨胀,且**不收敛** |
-| 闭包深度分布 | 1:185 2:181 3:141 4:45 5:52 6:40 7:52 8:40 9:52 10:40 | 深度 5 起振荡而非衰减 = **有环** |
-
-环是真的,抽取错误造成:
-
-```
-Microsoft → FarmBeats for Students → Microsoft
-FarmBeats for Students → National FFA Organization → FarmBeats for Students
-```
-
-「FarmBeats for Students 属于 Microsoft」是对的,反向那条是模型从"Microsoft 的 FarmBeats 项目"这类句式里抽反了。**语料第一天就带环**——环检测不是防御性编程,是开工前提。
-
-在这个底子上开传递闭包,第一天就产出「Microsoft 属于 Microsoft」,而且**带证据链**——比没有更难收拾。
-
-但同一套规则求值机器反过来用就是**一致性检查**:找环、找反对称违反、找 disjoint 违反。没有真值维护负担、没有爆炸风险、输出直接进现有的 `fact_conflicts` + Review UI。**先用检查把引擎建起来并把语料洗干净,再打开物化开关。**
-
-现存可检出的矛盾(三个 KB 合计 11 处,全是真缺陷):`part_of` 双向环 2 处、任意谓词双向重复 9 对、自环 0(`extraction.rs:363` 已拦)。
-
----
-
-## 三个架构前提
-
-### 1. 派生事实没有证据位
-
-`fact_evidence.chunk_id` 是 `NOT NULL`。派生事实没有分块——**它的证据是别的事实**。而 README 的承诺是 "Nothing enters the graph without evidence",所以这不是可选项。
-
-```sql
-CREATE TABLE fact_derivations (
- fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
- premise_fact_id UUID NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
- rule_id UUID NOT NULL,
- seq SMALLINT NOT NULL,
- PRIMARY KEY (fact_id, premise_fact_id, seq)
-);
-```
-
-这同时是 "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` 那个坑的十倍版,而且这次是自动化的。
-
-硬性优先级 **asserted > derived**:
-
-| 情形 | 处理 |
-|---|---|
-| 派生 vs 断言 | 派生**不落地**,记一条"规则与事实矛盾"信号 |
-| 派生 vs 派生 | 规则集自相矛盾 → 进 Review,**不自动裁** |
-| 断言 vs 断言 | 现有逻辑不变 |
-
-这是 0001 判据 2「本体是引导不是执法」在推理层的同一条:**声明可能是错的,所以它不能驱动对既有数据的改写。**
-
-> **修订记录(2026-09-02)**:表格三行里只有第一行的前半兑现了——`asserted` 硬性优先,已断言的三元组不再派生(`derive.rs`)。
-> 「记一条规则与事实矛盾的信号」**没有**,「派生 vs 派生进 Review」**没有**(同一三元组的多条推导只留第一条证明)。两者都还是待做。
->
-> **修订记录(2026-09-03)**:两行都兑现了,方案见 [0017](0017-a-contradiction-points-upstream.md)。派生撞断言:`derive::contradictions` 逐条算出,`run` 记成 `axiom_violations` 一种 `derived_contradiction`(单谓词封顶 50),`materialize` 用同一个函数拦下不落地;卡片给线索(旧断言没结束日期、同名实体、置信度低)与修法(闭合、撤回、认可)。派生撞派生:按规则对聚合进 `ontology_defects` 一种 `rules_disagree`,两边都不落——根子是那两条声明,不是哪条事实。
-
-### 3. 前提撤回时——双时态是最优解,不是负担
-
-不能 UPDATE(append-only 是地基)。做法是置 `invalidated_at`,与拒绝一条事实**完全同构**。派生事实的记录轴上于是留下"我们曾据此推出,后来前提没了"。
-
-真值维护在别的系统里是苦活(要么标记删除要么重算全量),在这个数据模型里是既有机制的自然延伸——**而且实体历史页面(PR #37)直接就能展示它**,不需要新 UI。
-
-> **修订记录(2026-09-02)**:「实体历史直接能展示」**没兑现**——`entity_history` 的 UNION 只有 facts / merges / retypes 三段,不含 `derived_facts`。
-> 派生的可见性落在别处:实体面板单独一档「推出来的」、图上金色专属边(派生为零时开关整个不出现、逆关系推出来的边并到同一条弧上)。
-> 而且今天没有「前提撤回」这个增量动作,R3 未做,每次全量重推并整体对账。
-
----
-
-## 分步
-
-### R0 · 一致性检查(不产生任何事实)
-
-- 规则求值引擎:半朴素求值 + 环检测 + 深度上限
-- 三类检查:**反对称违反**(`part_of` 双向)、**函数性违反**(漏网的)、**disjointWith 违反**(等 0001 P2 导入)
-- 输出进 `fact_conflicts`,复用现有 Review UI,零新界面
-- **立刻有货**:现存 11 处矛盾直接冒出来
-
-价值在于:引擎的难点(规则表示、求值、终止)全部建成并验证,而风险面为零——它不写 `facts` 表。
-
-> **修订记录(2026-09-02):R0 建成,四处与上面写的不同。**
-> 一、**四类不是三类,且不是那三类**:`self_loop` / `asymmetry` / `cycle` / `functional`(兼含 inverse_functional)。**事实层的 disjointWith 违反没有做**——disjoint 只进了本体自检。
-> 〔后来多了第五类 `signature`(#190 / #196):主语不在谓词的 domain、或宾语不在 range。它不由纯逻辑引擎算——要看实体类型与闭包,那是库里的东西——`store::reasoning::signature_breaks` 用 SQL 量,算出来后与其它四类走同一条落库、清陈、裁决的路。合并之后对搬动过的事实立刻查,手动跑检查时全量查。未分类实体不算。〕
-> 二、**不进 `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` 表
-- 规则**只从本体公理编译**:`TransitiveProperty` / `SymmetricProperty` / `inverseOf` / `subPropertyOf`。不做用户自定义 DSL——那是另一个产品
-- 优先级 asserted > derived,硬性
-- 深度上限 + 环检测(实测必需)
-- 派生事实在图上可视觉区分,且可整体过滤
-
-> **修订记录(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)为止,中间节点是派生事实与规则。〔**已做**(0016 B1,`feat/proof-tree`):`reasoning::proof` + `GET /kbs/{id}/derived/{id}/proof`,实体面板里派生行展开即证明链。**形状是链不是树**——`fact_derivations` 只记断言前提(推导的输入排除派生),所以「递归展开」退化成按 `seq` 的一条链:派生 → 断言 → 各自的证据 → chunk,界面一路点到文档。撤了的前提照样列出并打标记,派生失效后证明仍可回看——记录轴的用法。先前写的「中间节点是派生事实」在这个数据模型里不会出现。〕
-
-### R3 · 增量维护
-
-前提失效 → 派生失效。半朴素增量而非全量重算。放最后是因为前面三步都能靠"重算整个 KB"活着,而增量的正确性最难验。〔**未做**,每次全量重算并整体对账,迁移注释明写「在增量维护做出来之前每次都是全库重算」。〕
-
----
-
-## 开放问题
-
-- **有效时间的交集语义**:前提 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 让人判?倾向后者——两条都是模型抽的,没有先验理由信任其一。〔**已按倾向落地**:`cycle` 违规带完整 `path` 进 Review;R1 一律不推自环。`related_to` 那条前置障碍也随 [0010](0010-no-relation-is-no-relation.md) 消失——空谓词边天然不进推理。〕
+# 0002 · Reasoning engine
+
+- **Status**: R0 built: six fact-level violation kinds in `axiom_violations` (five checks plus
+ `derived_contradiction`, 0017), eight ontology defect kinds in `ontology_defects`, two Review tabs. R1 built behind the KB switch `materialize_inferences`
+ (default off), rules from four axiom kinds (#132, #177, #179). R2 built as a proof chain
+ (`GET /kbs/{id}/derived/{id}/proof`, 0016 B1). Contradiction signals for derivations built per
+ [0017](0017-a-contradiction-points-upstream.md). R3 not built: every run recomputes the whole KB,
+ on `inference_interval_minutes` (default 60).
+- **Written**: 2026-08-28 · condensed into English 2026-09-03
+- **Related**: [0001](0001-ontology-import-and-governance.md) P5 (this record replaces its schedule);
+ [0010](0010-no-relation-is-no-relation.md);
+ [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) reuses decision 3's criterion;
+ [0016](0016-close-the-open-seams-before-cutting-new-ones.md); [0017](0017-a-contradiction-points-upstream.md)
+
+## The problem
+
+A reasoner amplifies defects. On `Industry Corpus` (28 press releases) 39% of edges were `related_to`,
+and 185 `part_of` facts expanded to 828 under transitive closure at depth cap 10, with per-depth counts
+oscillating from depth 5 instead of decaying: cycles, real ones, from extraction errors such as
+`Microsoft → FarmBeats for Students → Microsoft`. Closure on day one would derive "Microsoft part_of
+Microsoft" with an evidence chain attached. The same rule evaluator run backwards is a consistency
+check with no truth maintenance and no explosion, so the engine is built as a checker first, the
+corpus is cleaned, then materialization is switched on.
+
+## Decisions
+
+1. **R0 checks and writes no facts.** Pure logic in `utopia-reason`; kinds `self_loop`, `asymmetry`,
+ `cycle` (depth-first, with the full `path`), `functional` (including inverse-functional) and
+ `signature` (#190 / #196: subject outside the domain or object outside the range, computed in SQL
+ by `store::reasoning::signature_breaks`; untyped entities excluded). Rows go to `axiom_violations`,
+ which asks "wrong data or wrong definition": `fact_retracted` / `axiom_relaxed` / `accepted`.
+2. **The ontology checks itself first.** `ontology_defects`, eight kinds (symmetric and asymmetric,
+ transitive and functional, subclass cycle, disjoint with an ancestor, inherited disjoint,
+ self-inverse, inverse not mutual, sub-property cycle), shown before violations because a
+ self-contradicting ontology makes every fact-level conclusion suspect. A KB without an ontology
+ pack reports zero, since there is no criterion; importing a pack runs a check.
+3. **Derived facts live in their own table.** `derived_facts`, with
+ `fact_derivations (derived_fact_id, premise_fact_id, seq)` and the rule on `derived_facts.rule_id`
+ (migration `0013_reasoning.sql`). `fact_evidence.chunk_id` is NOT NULL and a derivation's evidence
+ is other facts; and of forty-odd queries over `facts` one knew a flag, so a new query would read
+ derivations as assertions by default. Separate tables fail the safe way: a forgotten UNION hides
+ derivations. `facts.derived_by_rule` is never written; its only reference is a Review filter.
+4. **Asserted beats derived, hard.** `reconcile_new_fact` auto-closes older facts of a functional
+ predicate, so a derivation on that path would let one wrong rule close human assertions. An
+ asserted triple is never derived (`derive.rs`); derived vs asserted does not land and becomes an
+ `axiom_violations` row of kind `derived_contradiction` (cap 50 per predicate); derived vs derived
+ aggregates per rule pair into `ontology_defects` kind `rules_disagree` and neither lands (0017).
+5. **Rules come only from ontology axioms.** Transitive, Symmetric (#132), inverseOf, subPropertyOf
+ (#177, #179; projection in migration `0016`); no user DSL. Rule identity is `(kb, predicate, kind)`
+ and rows are kept when an axiom is withdrawn, so `rule_id` and history survive. Inverse
+ normalization at axiom load fills gaps only; a mismatched pair goes to `inverse_not_mutual`.
+ Cold-start bootstrap declares no axiom (`Axioms::default()`): the reasoner's criteria are
+ written by people.
+6. **Materialization is a KB switch, default off.** The job records its run time before deriving so
+ a failure cannot loop; endpoints return an explicit error while off. `MAX_DERIVED_PER_PREDICATE` =
+ 20,000, truncation reported as `capped`; an `unruled` counter that should stay zero records a
+ real bug (rule lookup by predicate instead of `via` dropped cross-predicate rules silently).
+ Derived edges are gold on the graph behind a toggle; the entity panel has a "derived" section.
+7. **Explanation is a chain** (`reasoning::proof`). `fact_derivations` records asserted premises
+ only, so the proof runs derivation → assertions → evidence → chunk → document by `seq`.
+ Retracted premises stay listed and flagged, so a proof stays readable after invalidation.
+8. **Validity intervals intersect**: half-open, empty means nothing derived, touching endpoints do
+ not overlap, precision the coarsest premise, confidence the minimum, literal objects excluded
+ (`object_id IS NOT NULL`). Cycles go to Review with their path, since both edges came from the
+ model and neither deserves prior trust; R1 never derives a self-loop.
+
+## Dead ends
+
+- **R0 output into `fact_conflicts`, "zero new UI".** That table asks "which one is right";
+ violations ask "data or definition". New table, two new Review tabs.
+- **Fact-level `disjointWith` violations** as an R0 kind: not built; disjointness feeds the ontology
+ self-check only.
+- **Derivations shown by `entity_history` for free.** Its UNION has facts, merges and retypes;
+ visibility went to the graph and the panel instead.
+
+## Revisions
+
+- 2026-09-02: assumed derivations enter `facts` under the `derived_by_rule` column reserved in
+ `0004_graph.sql`; the code has `derived_facts` and the column is never written.
+- 2026-09-02: the "11 existing contradictions" rested on the seed ontology's `functional`
+ declarations; with the seeds gone, a KB without a pack reports zero.
+- 2026-09-03: the contradiction signals promised in decision 4 exist (0017); the `related_to`
+ obstacle (39% empty edges) vanished with 0010, since null-predicate edges never enter reasoning.
+
+## Open questions
+
+- Materialize or evaluate at query time: 4.5× expansion on a small corpus, unknown at scale. For now
+ a per-predicate cap and a periodic full recompute.
+- R3 incremental maintenance: correctness is the hardest to verify, and full recompute holds.
diff --git a/docs/decisions/0003-ontology-growth-loop.md b/docs/decisions/0003-ontology-growth-loop.md
index c9b85f2a..0e727ace 100644
--- a/docs/decisions/0003-ontology-growth-loop.md
+++ b/docs/decisions/0003-ontology-growth-loop.md
@@ -1,152 +1,96 @@
-# 0003 · 本体从语料里长出来,人站在哪一环
-
-- **状态**:已建成且仍在跑(#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——那两节是计划,本文是实际长出来的东西,两者不一样
-
-> 本文最有价值的部分是**三次判断变化**那一节。结论本身从代码里读得出来,理由读不出来,而三次变化的理由各不相同——按 [README](README.md) 的约定就地留痕。
-
----
-
-## 问题
-
-抽取器读到"《星球大战:零号连队》可在 GeForce NOW 上玩",而本体里没有"可在…上玩",只能降级成 `related_to`——**等于什么都没说**。真实语料上这类边曾占 40.5%。
-
-而新建的知识库只有 10 个默认关系,那不是任何人选的,是种子数据。所以每一个新库开局都是这个状态:**图里近一半的边没有语义,直到有人坐下来一条条补本体。**
-
-抽取侧的修法(撤掉逃生舱、加提示词规则 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 个关系全部来自本体包,**自动扩本体一条都没长出来**。
-> 所以这条回路的角色变了:冷启动的主力是「先装一份词表」,本文的机制负责「长出来的补缺口」。回路本身一字未改,仍然默认开着。
-
----
-
-## 建成的东西
-
-### 采纳的收益在后半句
-
-Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实**——本体长大了,图没变好,那 49 条继续写着"有关联"。
-
-现在采纳做两件事:建关系类型 + **把等着它的事实改写过去**。提案上直接写"将重新归类 21 条",并列出归并了哪些写法。
-
-改写走追加:插入带 `supersedes` 的新行、作废旧行,与人工纠正、时态闭合同一条路。实体历史里因此读得到「先记成 related to,后精化成 available on,某某某改的」。
-
-**只改写说法全部落在采纳集合内的事实。** 一条事实可能跨分块积累多种说法,只认领其中一种就改写等于替另一种做了决定。实测这类占比不到 1%。
-
-### 可以撤销
-
-`fact_adoptions` 记每一条的去向:批次、谓词、旧事实、新事实、以及**是"新建取代"还是"并入已存在"**。撤销按批次回滚:新行作废、旧行复活。
-
-**关系类型不删**——有事实指向过它(`delete_relation_type` 也会拒绝),而按 append-only 的规矩"它存在过"本身是历史,一个没人用的关系是惰性的。撤销标记账本行而不是删除,因为采纳发生过、撤销也发生过,两件都是真的。
-
-撤销要二次确认(轻确认,不是打字解锁——它本身可逆)。
-
-### 三档动作
-
-| | 谁决定 | 何时用 |
-|---|---|---|
-| 逐条 Add | 人 | 挑着采纳 |
-| Add all | 人 | 常见情形是"这些都对",一次决定 |
-| 自动 | 开关 | 见下 |
-
-### 开关
-
-`knowledge_bases.auto_extend_ontology`,KB 设置页,**默认开启**。
-
-它只管**自动采纳**,永远不管**留意**:关掉之后未匹配的说法照常累积、照常在 Unmatched 面板可见,只是变成你点一下的提案。文案里必须明说这一点——"停止扩展"太容易被读成"停止留意"。
-
-默认开启的前提是它的动作**可见且可退**:Ontology 页有横幅说明加了什么、改了多少条、附撤销。**审计台账是事后查证用的,不是通知用的。**
-
-### 永不自动的那一样
-
-`functional` 无论建议方说什么、开关开着也一样,永远是 `false`。
-
-它驱动时态引擎**自动闭合事实、生成冲突**,等发现时那些闭合本身已是一串 supersede 链,撤销要反向拆解。`part_of` 曾被误标为 functional,28 篇新闻稿积压 59 条假冲突。
-
-**判据一句话:可逆的可以自动,触发级联写入的不行。**
-
-〔后来扩大到全部公理:冷启动路径传 `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 篇文档**里的说法。理由不是安全(有撤销),是质量:**本体会反馈进抽取提示词,一次偶然用词会变成长期指令。** 副作用正好——单篇文档什么都够不着门槛,于是什么也不做,下一篇再议。
-
----
-
-## 三次判断变化
-
-### 一、我反对自动化,理由是错的
-
-**原判断**:不该自动写本体。同义词会爆炸(四种 "available" 变四个关系)、通用动词会混进来(`is`/`has`/`includes`)、频次不等于语义、`functional` 猜错会成批制造假冲突。
-
-**这些论据本身没错**,错的是结论所依赖的隐含前提:**"错了代价高"**。
-
-代价并不高。采纳走的是 supersede,旧事实从来没被销毁过。**可逆性是我自己设计的,然后论证时没把它算进去**——拿一个已经设计掉的不可逆去反对自动化。
-
-**判断轴不是"有多确信",是"错了有多贵"。**
-
-(同义词与通用动词那两条论据仍然成立,只是它们要的不是"人来点头",是**聚类**——自动化的是审批,不是归并。)
-
-### 二、接受自动化后,我用了一个猜测当判据
-
-**原判断**:本体"有没有被碰过"(存在非内置类型)可以判断该不该自动跑。
-
-**那是从行为推断意图,两个方向都错。**
-
-在提案上点一次 Add 会记一条带操作人的本体动作——**参与治理闭环,导致治理闭环停止工作**。改个描述里的错别字也一样。
-
-而且它一旦为假就永不再真:自动跑完第一轮,本体"被碰过了",于是**词汇永久冻结在第一批文档碰巧包含的那些上**,而 RSS 与文件夹来源是每天持续进文档的。
-
-### 三、开关(用户指出)
-
-**声明取代猜测。** 开关不只是加了个控制,它**删掉了一个坏机制**——没有猜测就没有荒唐的开关,没有自动关闭就没有冻结,迭代变成"开着就一直跑",不需要任何聪明劲。
-
-默认开启则解掉了开关本身的老问题:新用户找不到它,只能忍受一个近半边没有语义的图。
-
----
-
-## 两个在已上线代码里发现的缺陷
-
-**并入分支让历史说了谎。** 采纳时若目标断言已存在,旧行被作废且**没有任何后继指向它**。实体历史把"已作废且无后继"判为 `rejected`,于是界面上写着「关于 GeForce NOW 的这条记录被撤回了」——它其实一字未少地并进了另一条断言。这跟 [#37](https://github.com/deeplethe/utopia/pull/37) 修的是同一类:**界面自信地陈述一件没发生的事。** `fact_adoptions` 是它的直接由来。
-
-**单篇文档能定下整个本体。** 触发条件"没有别的文档在处理中",在批次只有一篇时立刻为真——而代码里我自己的注释写着"逐篇触发是错的"。≥2 篇文档那条门槛修的是它。
-
----
-
-## 实测
-
-| | |
-|---|---|
-| 采纳 `available_on`(归并 4 种写法) | 改写 **49** 条(48 新建 + 1 并入) |
-| 采纳 `supports` 后撤销 | `related_to` 精确回到采纳前的数,24 行标记已撤销,关系类型留着 |
-| 冷启动(一次性库,3 篇文档) | 自动建 5 个关系(全 `functional=false`),改写 19 条,**剩余 `related_to` 为 0** |
-| 拒绝 `runs_on` 后模拟下一轮抽取 | 计数停在 41 不涨(此前会删掉再插回) |
-
-一个**负面结果,而它证明了设计**:建议把 `optimized_for` 并进了 `runs_on`——"为 RTX 优化"不等于"跑在 RTX 上"。归并的写法在 tooltip 里可见,过并能被人抓出来。**这就是我不建议全自动归并的最直接证据。**
-
-〔上表四行都基于已不存在的 `related_to` 与种子本体,是历史记录,不要再当基线引用。采纳路径后来多了两样本文没写的东西:整组说法先过 `predicate_match`,本体里已有等价关系(含 `_by` 反向)就落到它上面并对调主宾(#109);门槛按「谓词 + 类型」合起来算 `MIN_SIGNALS = 3`,此前只数谓词,一个只缺实体类型的语料会被整个跳过。规范 key 不问模型取名,取组内事实最多的那个真实措辞。〕
-
----
-
-## 已知缺口
-
-- ~~**实体类型这半边完全没有对应机制。**~~ **已补上**(2026-08-30):类型消解
- (0001 P3a)给了提案与裁决,`adopt_proposed_types` 给了采纳并改类,
- `entity_retypes` 给了可撤销的台账。原文说的「只有一个 PATCH 端点」不再成立。
- 当时列的实测数据(`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` 里),是**聚类结果**——哪些说法被归到
- 同一条提议底下,而那正是唯一能查证过并的东西。
+# 0003 · The ontology grows out of the corpus
+
+- **Status**: Built and running (#44; switch `knowledge_bases.auto_extend_ontology`, default on). Its
+ starting point has moved: `related_to` is deleted ([0010](0010-no-relation-is-no-relation.md)) and
+ the seed ontology retired (#125, #128), so a new KB starts from an ontology pack
+ ([0008](0008-ontology-packs-as-cold-start.md)) and this loop fills the gaps a pack leaves.
+ "Dismissal has memory" redone per [0007](0007-who-decides-what-becomes-a-relation.md). Two of three
+ known gaps closed (`adopt_proposed_types` + `entity_retypes`; `ontology_proposals`, #112); the "new
+ phrasings since you last looked" reminder still pending. Checked against the code 2026-09-02.
+- **Written**: 2026-08-28 · condensed into English 2026-09-03
+- **Related**: [0001](0001-ontology-import-and-governance.md) P3b and P4 are the plan, this is what
+ grew; [0007](0007-who-decides-what-becomes-a-relation.md); [0008](0008-ontology-packs-as-cold-start.md);
+ [0010](0010-no-relation-is-no-relation.md); [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md)
+
+## The problem
+
+The extractor reads "《星球大战:零号连队》可在 GeForce NOW 上玩", the ontology has no "playable on", and
+the fact lands as `related_to`, which says nothing. On real corpora 40.5% of edges were like that, and
+every new KB began with ten seed relations nobody had chosen. The extraction side (0001 P3b) removed
+the escape hatch and kept the original phrasing on `fact_evidence.proposed_predicate`. This record is
+the other half: turning kept phrasings back into relations, with a person somewhere in the loop.
+
+That world is gone: an unmapped fact now has a null predicate and shows its phrasing through
+`fact_surface_predicate()`, and a new KB has no relations until a pack is installed. 0012 measured
+25.6% null predicates on ai-timeline-ends × schema.org, all 41 relations from the pack and none grown
+by this loop. The loop itself is unchanged and still on by default.
+
+## Decisions
+
+1. **Adoption rewrites the facts waiting for it.** Add used to create the relation type and leave the
+ facts saying "related to". Now it also rewrites every fact whose phrasings all fall inside the
+ adopted set (a fact with several phrasings across chunks is left alone; under 1% of cases), and
+ the proposal says "will reclassify N" with the phrasings merged. The rewrite is an append (new row
+ with `supersedes`, old row invalidated), the same path as human correction, so entity history
+ reads "recorded as related to, refined to available on, by whom". `predicate_match` runs first: an
+ equivalent relation already in the ontology (including `_by` inverses) absorbs the group with
+ subject and object swapped (#109). The canonical key is the group's most frequent real phrasing.
+2. **Undo is per batch.** `fact_adoptions` records batch, predicate, old fact, new fact, and whether
+ the new row superseded or merged into an existing assertion. Undo invalidates the new rows and
+ revives the old; the relation type stays (facts pointed at it, and both the adoption and the undo
+ happened). Light confirmation, no typed unlock.
+3. **Three tiers**: Add one (a person, picking), Add all (a person, one decision), automatic (the
+ switch).
+4. **The switch governs adoption, never attention.** Off, unmatched phrasings still accumulate in the
+ Unmatched panel as proposals, and the copy must say so, since "stop extending" reads as "stop
+ noticing". Default-on is justified because every automatic action is visible and reversible: the
+ Ontology page banner (`last_auto_extension`) shows what was added, how many facts changed, and
+ undo. The audit ledger is for later verification, never a notification.
+5. **No axiom is set automatically**, `functional` first and now all of them (`Axioms::default()` on
+ the cold-start path). Criterion: a reversible action may be automatic; one that triggers cascading
+ writes may not. `functional` drives auto-closing and conflicts, and undoing that means unpicking
+ supersede chains; `part_of` mislabelled once produced 59 false conflicts from 28 press releases.
+6. **Dismissal remembers an attitude, and counts go on.** `ontology_misses.dismissed_at`;
+ `record_miss` keeps counting; suppression happens on read, with dismissed entries listed
+ separately with current counts, revocable (0007).
+7. **Automatic adoption needs a phrasing in at least two documents**, `MIN_SIGNALS = 3` counted over
+ predicate and type signals together (counting predicates alone skipped a corpus that lacked only
+ entity types). The reason is quality: the ontology feeds back into the extraction prompt, so one
+ document's accidental wording would become a standing instruction.
+
+## Dead ends
+
+- **Opposing automation.** Synonym explosion (four "available" phrasings, four relations), generic
+ verbs (`is`, `has`), frequency taken for meaning, a guessed `functional`. The arguments stand; the
+ hidden premise "being wrong is expensive" does not, because adoption supersedes and destroys
+ nothing. The axis is the cost of an error. What gets automated is approval; synonyms and verbs
+ call for clustering, and merging stays human.
+- **"Has the ontology been touched" as the trigger.** Inferring intent from behavior fails both
+ ways: one click on Add stops the loop, and once false it never turns true again, freezing the
+ vocabulary on the first batch while RSS keeps delivering. The declared switch (a user's
+ suggestion) removed a bad mechanism.
+- **`dismiss` as `DELETE FROM ontology_misses`.** The next extraction re-inserted it. The first fix,
+ "stop counting after dismissal", was a one-way door: a judgment made at count 1 applied to twenty
+ later documents, count frozen, invisible.
+- **A merge branch that made history lie.** When the target assertion already existed, the old row
+ was invalidated with no successor and entity history rendered "retracted" for a fact merged intact.
+ `fact_adoptions` exists because of this.
+- **Triggering when no other document is in flight.** True at once for a batch of one, so a single
+ document could set the whole ontology; the two-document threshold fixes it.
+- **Automatic merging of phrasings.** A suggestion folded `optimized_for` into `runs_on` ("optimized
+ for RTX" is not "runs on RTX"); the merged phrasings were visible in the tooltip and a person
+ caught it. This is the direct evidence for keeping merges human.
+
+## Revisions
+
+- 2026-08-30 (#112): proposals persist in `ontology_proposals`; what used to be lost was the
+ clustering, the only thing that lets a person check a merge, never the raw misses.
+- 2026-09-02: the measured rows (49 rewrites for `available_on`, 24 undone for `supports`, a cold
+ start growing 5 relations and rewriting 19 facts) rest on `related_to` and the seeds; history, no
+ longer a baseline.
+
+## Open questions
+
+- With the switch off there is no "88 new phrasings since you last looked"; the index
+ `ontology_proposals_open_idx` was laid for it and the reminder never built. The only banner today
+ is `last_auto_extension`, which reports the last automatic run.
diff --git a/docs/decisions/0004-language-and-localization.md b/docs/decisions/0004-language-and-localization.md
index 0b7c9dfa..b6fe5a24 100644
--- a/docs/decisions/0004-language-and-localization.md
+++ b/docs/decisions/0004-language-and-localization.md
@@ -1,144 +1,84 @@
-# 0004 · 语言:哪些字跟着看的人走,哪些跟着语料走
+# 0004 · Language follows the reader of each text
-- **状态**:已建成 · L0–L3 全部落地:界面词汇在 `web/src/i18n/`(约 950 条,含 108 个函数)、服务端错误改成带 `code` 的 `AppError::Invalid`(81 处;23 处 API 契约守卫刻意留英文 `Validation`)、
- 本体 `description` 跟 `knowledge_bases.ontology_lang`(带部署默认值)、LLM 面向人的输出
- 由调用方在请求里传 `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` 之分是本文分界线的起点
+- **Status**: Built · UI strings in `web/src/i18n/`; user-reachable server errors carry a
+ `code` (`AppError::Invalid`, 81 sites; 23 `Validation` guards stay English);
+ `description` follows `knowledge_bases.ontology_lang`; LLM output for people takes
+ `locale` from the request; extracted data stays verbatim; the UI does not guess the
+ browser language yet.
+- **Written**: 2026-08-29 · condensed into English 2026-09-03
+- **Related**: [0001](0001-ontology-import-and-governance.md) made `description`
+ load-bearing; [0003](0003-ontology-growth-loop.md) separated `reason` from
+ `description`; [0008](0008-ontology-packs-as-cold-start.md) supplies the English packs a
+ Chinese knowledge base starts from.
-> 触发:产品要面向中文企业出中文版。但「加个语言开关」这句话底下藏着**五种性质不同的文本**,它们的正确语言互不相同,用一个开关管必然有一半是错的。
+## The problem
----
+One language switch cannot serve five kinds of text with different readers and sources:
-## 五种文本
-
-平时都叫「文案」,但读者和来源完全不同:
-
-| | 例子 | 读者 | 来源 |
-|---|---|---|---|
-| **界面词汇** | "Import an ontology" | 人 | 我们写死在 `i18n.ts` |
-| **服务端错误** | "Password must be at least 8 characters" | 人 | 我们写死在 Rust 里 |
-| **本体的 label / description** | `person` / "A named individual human being…" | **description 的读者是模型** | 内置播种 + 用户撰写 + OWL 导入 |
-| **LLM 当场生成给人看的** | 建议的 `reason` | 人 | 模型,按需生成 |
-| **抽出来的数据** | 实体名 `张三`、`surface_predicate` "runs on" | 人与模型 | **原文,逐字** |
-
-最后一行不是文案。**它是引文。**
-
----
-
-## 分界线
-
-### 界面词汇 → 客户端,每个人自己设
-
-和暗色模式同类:这是**看的人**的偏好,不是部署的属性。中国企业里的外籍同事不该为了看英文界面去找管理员。
-
-`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 个函数,靠人眼对不齐。
-
-### 服务端错误 → 改成 key,措辞归前端
-
-界面语言在客户端之后,**后端不再拥有任何 locale**。所以留在 Rust 里的字符串是**永久不可翻译**的,不是"以后再补"。
-
-`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`——只有调错接口才会碰到)→ 留英文。它的读者是开发者,永久英文正是它该有的样子。
-
-关键是**逐条判断并认下来**,而不是含糊地"以后再说"。
-
-> 这让本仓库一条既有原则从好品味变成硬约束:**服务端不产出展示形态**。此前违反它只是不优雅(OWL 导入把 `(手工建的)` 塞进 `conflict_with`,直接漏进英文界面);现在违反它等于制造一个永远翻不了的字符串。
-
-### 本体的 description → 跟语料,不跟界面
-
-`description` 逐字进抽取提示词([0001](0001-ontology-import-and-governance.md) 已论证它是承重字段),**读者是模型,而模型正在读你的文档**。
-
-所以正确语言是**语料的语言**,不是界面的语言。中国企业读英文技术文档是常见组合:界面要中文,而类描述**应该是英文**——描述与被判断的文本同语言时,模型判断"这段文字里的东西算不算 `product`"更稳。
-
-这是一个**知识库级**的属性(一个库就是一份语料),不是部署级,更不是客户端。
-
-### 本体的 label → 是数据,不跟任何开关
-
-`label` 存在库里,跟不了客户端的开关。**而这是对的**:它是那个团队写下的本体。一个中国团队建的库里类叫 `人物`,用英文界面的同事看到的也该是 `人物`——那是他同事定义的概念,不是界面元素。翻译它反而错。
-
-内置的 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](../../crates/utopia-extract/src/lib.rs),已按下句改掉)。界面语言与语料语言不一致时,这一行会中英混排。`Person` 相对 `person` 本来就近乎零信息量,所以**提示词只送 `key` + `description`,`label` 仅在 description 为空时兜底**。
-
-### LLM 当场生成给人看的 → 调用方在请求里说
-
-`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) 的提示词压根没说输出用什么语言,模型看心情。〔**已修**:提示词末尾有一整段 Language 指令,`lang_name()` 把 `zh` 写成 `Chinese` 再送进去——模型认得懂 Chinese,未必认得懂 zh;冷启动那条路显式传 `en`。〕
-
-### 抽出来的数据 → 逐字跟文档,连开关都不给
-
-实体名之所以是 `张三`,因为文档第 3 段就是这么写的——证据链指着那个位置。翻译成 `Zhang San` 同时坏掉三件事:证据对不上原文、同一个人在中英文档里裂成两个实体、`surface_predicate` 那一整套「原文用的什么词」的记录失去意义。
-
-**不是语言偏好问题,是出处问题。**
-
----
-
-## 于是后端只剩一个语言概念
-
-| 层 | 管什么 | 存哪 |
-|---|---|---|
-| 客户端 | 界面词汇(512 条 + 44 个函数) | `localStorage` |
-| 单次请求 | LLM 当场生成给人看的文本 | 请求参数 |
-| **知识库** | `description`、播种哪套内置本体 | `knowledge_bases` 一列 |
-| 部署 | 上一行的默认值 | 管理员设置 |
-
-最后一行是「系统语言」唯一剩下的东西。它值得留——中文部署不该每次建库都手动选——但**必须换个名字**。叫「系统语言」的话,三个月后一定有人试图把界面语言挂上去,然后发现挂不上。叫**「新建知识库的默认本体语言」**,名字本身就把误用挡住了。
-
----
-
-## 一条架构约束
-
-locale 必须**在一个函数里解析出来**,其余全部消费它,不各自去读来源。
-
-这样将来要不要做「每用户语言」「跟随浏览器」「按知识库切界面」,改的是那一个函数,而不是翻遍 512 个调用点。**设置放哪会变,解析在一处不会变。**
-
----
-
-## 分步
-
-| | 内容 | 依赖 |
+| Text | Reader | Source |
|---|---|---|
-| **L0** | 前端 i18n 骨架:locale store + 语言切换 + `zh.ts`(`typeof S` 全量) | 无 |
-| **L1** | 服务端错误文案分类,能撞到的改 key | L0 |
-| **L2** | 知识库本体语言列 + 中文内置本体 + 部署级默认值 | 无(可与 L0 并行) |
-| **L3** | 提示词去掉 `label`;`suggest` 带 locale;提示词钉死输出语言 | L0(locale 来源) |
-
-**L2 独立于界面语言,且今天就有收益**:中文语料配中文类描述,抽取质量直接受益,不必等中文界面。
-
-**L2 里最实的一块不是加列,是重写内置本体的描述**——9 个类 + 14 个关系。它们当初是斟酌着写的(负面例子那部分尤其:「不是角色、职位或团队,那些归 concept 或 organization」——错误聚集在边界上,负面例子才是干活的那半)。**翻译不能敷衍,得按同样的思路用中文重写一遍。**
-
-> **修订记录(2026-09-02)**:这一块**已无对象**——种子本体整个退场(见上文「label」一节的作废注)。
-> L0、L1、L3 与 L2 的「加列 + 部署默认值」都已建成;中文本体这件事换了形态:
-> 要么用户导入自己的中文词表,要么等本体包有中文标签(0008 开放问题),代码里没有第三条路。
-
----
-
-## 已知会疼的地方
-
-- **中文包与英文包漂移**。`typeof S` 挡住"漏一条",挡不住"英文改了措辞、中文还是旧的"——两边都合法。目前没有好办法,只能靠改文案时同时改两处。
-- **一个库里中英文档混放**时,`description` 该用哪种语言没有正确答案。本文选了「知识库单语」,因为混放本身就会让抽取质量下降(不只是描述的问题)。真遇到了再说,别提前设计。
-- **中文分词与检索**。Tantivy 那边已经用了 `tantivy-jieba`,不在本文范围,但中文版上线后会被更认真地检验。
-- **(2026-09-02 补)中文包追不上英文包的期间,界面默认英文**。见「界面词汇」一节的修订记录:`detect()` 暂不猜浏览器语言。追平的标志是 `zh.ts` 不再靠 `typeof S` 之外的任何东西撑着,那时把 `navigator.language` 加回去。
+| UI strings ("Import an ontology") | people | the i18n bundle |
+| Server errors ("Password must be at least 8 characters") | people | Rust |
+| Ontology `label` / `description` | the model reads `description` | packs, users, OWL import |
+| LLM text generated on the spot (a suggested `reason`) | people | the model, on demand |
+| Extracted data (`张三`, `surface_predicate` "runs on") | people and the model | the document, verbatim |
+
+The last row is not copy. It is a quotation.
+
+## Decisions
+
+1. **UI strings are a per-person client setting**, like dark mode: a foreign colleague in
+ a Chinese company should not need an administrator to see English. Kept in
+ `localStorage` via `makeStore`, resolved in one function that everything else consumes.
+ The Chinese bundle is `const zh: typeof S = { … }`: a missing key fails compilation,
+ where `Partial` with fallback would leave a silently English line.
+2. **Server errors become keys.** With the locale in the client, any string left in Rust
+ is permanently untranslatable. Errors a user can hit are `AppError::Invalid` with a
+ `code` for the frontend `err.*` table (the English `message` stays for MCP, CLI and
+ logs). API-contract guards (`role must be admin, editor or viewer`) stay English
+ `Validation`: their reader is a developer. Hence a hard rule: **the server produces no
+ display text**.
+3. **Ontology `description` follows the corpus.** It goes verbatim into the extraction
+ prompt beside the documents, and Chinese UI with English class descriptions is common.
+ So it is a knowledge-base property, `knowledge_bases.ontology_lang`, whose deployment
+ default is named "default ontology language for new knowledge bases"; call it "system
+ language" and someone will hang the UI language on it.
+4. **`label` is data and follows no switch.** A class a Chinese team named `人物` reads `人物`
+ on the English UI too: it is their concept. `key` is never translated; it is the
+ model's token. The prompt lists `key` + `description`, `label` only when the
+ description is empty: `Person` beside `person` adds nothing and mixes scripts.
+5. **LLM text for people takes `locale` from the request.** `reason` is generated when
+ someone clicks "Suggest with AI", so the caller states the language;
+ `label`/`description` in the same call follow `kb.ontology_lang`. `lang_name()` sends
+ `Chinese` rather than `zh`; the cold-start path passes `en`.
+6. **Extracted data stays verbatim.** An entity is `张三` because paragraph 3 says so;
+ translating it breaks the evidence match, splits one person across Chinese and English
+ documents, and empties `surface_predicate`. Provenance has no switch.
+
+## Dead ends
+
+- **UI language as a deployment-level admin setting**, "like the concurrency limit". That
+ limit describes the deployment; the UI language describes the reader. A setting lives
+ with whatever it describes.
+- **A Chinese rewrite of the built-in ontology** (9 classes, 14 relations, negative
+ examples included) lost its object when seeding was removed (#125, #128,
+ [0009](0009-no-type-is-a-type.md), [0010](0010-no-relation-is-no-relation.md)). A
+ Chinese knowledge base now starts from an all-English pack; `ontology_lang = zh` affects
+ only terms the LLM proposes later. What remains is an imported vocabulary or packs with
+ Chinese labels ([0008](0008-ontology-packs-as-cold-start.md), open question).
+
+## Revisions
+
+- 2026-09-02: "guess `navigator.language` once" was never shipped, deliberately:
+ `detect()` reads `localStorage` and otherwise returns `"en"`, because the Chinese bundle
+ trails the English one and untranslated lines fall back silently. The line goes back in
+ when the bundle catches up.
+- 2026-09-02: since #112 `suggest` writes `ontology_proposals`
+ ([0003](0003-ontology-growth-loop.md)); the language conclusion is unchanged.
+
+## Open questions
+
+- **Bundle drift**: `typeof S` catches a missing key but not "the English wording changed
+ and the Chinese did not". Edit both together.
+- **Mixed-language corpora in one knowledge base**: one language per KB; design it when it
+ happens.
diff --git a/docs/decisions/0005-alert-center.md b/docs/decisions/0005-alert-center.md
index ca44ecb9..b55c0162 100644
--- a/docs/decisions/0005-alert-center.md
+++ b/docs/decisions/0005-alert-center.md
@@ -1,256 +1,128 @@
-# 0005 · 告警中心
-
-- **状态**:已建成 · 五种告警在线(`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)职责相邻,本文划边界
-
----
-
-## 为什么
-
-失败状态目前散在六处,各有各的字段,没有一个地方能一眼看全:
-
-| 位置 | 记的是 |
-|---|---|
-| `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`(#130/#131 折叠后落在 `0002_ingest.sql` 的 `graph_error` 列)的第一句是:
-
-> 抽取失败的原因此前只进日志与 `jobs.last_error`,文档上什么都不留,界面无从显示。
-
-那次的修法是往 `documents` 上加错误字段。**这是打补丁**:每出现一类新的失败,就往对应的表上加一列。推演层、执行层、OCR 端点、湖仓连接都还没进来,每一个都会带来自己的失败面。照这个路子走下去,会有十几个错误字段散在十几张表上,而用户仍然没有"现在系统哪里不对"的入口。
-
-真正伤人的不是失败本身,是**失败无声**。拖 100 份 PDF 进去、其中 12 份是扫描件,界面上 100 份全绿 —— 用户以为都进去了,直到某天问一个问题、答案里没有那份合同,而他不会想到去怀疑摄入环节。
-
----
-
-## 边界:与 Review 队列的分工
-
-两者都是"待处理的列表",不划清会互相蚕食。
-
-| | Review 队列 | 告警中心 |
-|---|---|---|
-| 性质 | 需要人**做决定** | 需要人**知道** |
-| 例子 | 这两个实体合不合并、这条低置信事实要不要收 | 这份文档没进去、源连不上、端点挂了 |
-| 不处理的后果 | 知识停在半路 | **你以为进去了,其实没有** |
-| 谁产生 | 抽取与消解在拿不准时主动入队 | 任何执行路径在失败时上报 |
-
-一句话:**Review 管知识的对错,告警管系统的死活。**
-
----
-
-## 三个决定
-
-### 1. 聚合属于视图,不属于表
-
-> **修订记录**:这一条原本写的是"同一类未解决的只有一条",让 `(kb_id, kind)`
-> 在表里唯一,多次故障并成一行、往 `subject_ids` 数组里追加。
-> **前半句是对的,后半句是错的**,而且它是第 2 条那套状态机的根源。
-
-拖 100 份 PDF、12 份是扫描件,界面上该读到**一条**「12 份文档没有文本层」,不是 12 条。
-没有聚合的告警中心两周后就没人看了 —— 这不是优化,是能不能用的前提。这句仍然成立。
-
-**但聚合必须是读出来的,不能存下来。** 存在表里的聚合是**活的**,活的东西要维护:
-东西好了得从数组里摘掉,不摘就撒谎。而"什么时候算好了"正是下面第 2 条那个坑。
-实现时先按存储聚合写了一版,三个 bug 全出自同一个根源 —— 那一行在自愈过程中被
-一路掏空,于是它既说不出自己曾经是什么事(`subject_ids` 与 `detail` 都空了),
-又会写出"0 个来源同步失败"这种标题。
-
-现在的做法:**存储一次故障一行,读的时候把连着的同 `(kb, kind)` 折成一组。**
-折叠在 SQL 里做(两个 `row_number()` 相减,gaps and islands),因为分页得按组分 ——
-放前端折的话一段连续故障跨了页边界就会断成两组,点一下也只标到边界为止。
-计数是算出来的,永远不会过期。
-
-只折**相邻**的:中间隔了别的故障就说明那是另一段时间的事,不该并进来。
-
-### 2. 「修好了没有」不是告警中心该回答的问题
-
-> **修订记录**:这一条原本是"自愈优先于人工关闭",理由是"做不到自愈的告警,
-> 用户很快学会无视它"。**那个担心是真的,但这个解法是错的**,而且错得很贵 ——
-> 整节推翻,留在这里是因为这个主意足够诱人,不留痕就会被再提一次。
-
-原方案:`resolved_at` 由产生方清空,配好 OCR 端点、那 12 份重新处理成功,告警自己消失。
-
-**它要求每一种新告警都自己实现一遍"怎么算修好了"。** 第一刀两种告警就要了两套机制:
-`source.sync_failed` 有天然的成功信号(`finish_sync` 成功失败走同一个出口,白捡的);
-`llm.unreachable` 没有,只好为它单独造一个后台探针 —— 每分钟敲一次端点,
-而且得先判断"这条告警还亮着吗"才敢发请求,否则健康的部署也在空转。
-第三种告警要造第三套。**而漏写清除是编译期看不出来的**,症状是告警永远亮着 ——
-恰好就是这个功能最怕的那件事。
-
-更根本的一层:**那不是告警中心的职责。** 现在还坏不坏,来源页面上写着、文档状态里写着。
-告警的职责是让人去看一眼,不是当实时看板。
-
-那"用户学会无视"怎么办?靠**每次故障发一条新的**:修好了就不再有新故障,
-读过的那些沉下去、角标自己灭;两个月后再坏,那是一条新的告警,角标重新亮。
-不需要成功信号,不需要探针,不需要任何时间常数。
-
-代价只有一个,也确实要付:**行数**。一个坏掉的来源按小时同步,一天写 24 行。
-所以有保留期(30 天,`alerting::RETAIN_DAYS`)—— 不清理这张表会长成第二个日志文件。
-
-> 也考虑过按 `(kb, kind, subject)` 去重、重复发生只推时间戳:行数有界、不用保留期。
-> **否掉了**,因为那样"复发"和"一直没好"在数据上无法区分,除非引入时钟或者成功信号;
-> 于是只能二选一 —— 读过就永久已读(两个月后复发静默,**漏报**),
-> 或者时间戳一动就重新变未读(已知故障每小时点亮,**噪音**)。漏报比行数贵得多。
-
-### 3. 读是各人的(这一条完好无损)
-
-**这条推翻了一个更省事的方案,理由值得记下来。**
-
-被否决的方案:一条告警被任何一个管理员点开,就对所有人标记已读。看起来省了重复劳动。
-
-失效方式:
-
-> 知识库有三个管理员。A 早上顺手点开看了一眼,没处理。这条告警从 B、C 的未读列表里**永远消失**了 —— 他们不知道曾经发生过这件事,而 A 想着"等会儿再说"。
-
-这是共享已读的经典失效:**所有人都以为别人在处理**,而且发生之后没有任何痕迹能让人发现漏了。
-
-根子在于把两件事合并了:**「已读」是我看没看过,「已解决」是事情完没完**。一个人读过不代表事情解决。
-
-> **修订记录**:原文接着写"而事情解决了,才是所有人都该从列表里移除它的时刻",
-> 并把"告警消失 = `resolved_at` 落下,对所有人同时消失"列成与已读并列的一半。
-> **那半边随第 2 条一起没了** —— 没有"已解决",告警也不会消失,
-> 它只是随时间沉下去、到期被清理。这一条真正立得住的部分是**已读逐人**,
-> 而那部分一个字没改。
-
-所以:**未读 = 我可见的告警里我没点过的** —— 每人独立,一张两列小表。
-换来的是**没有人能替别人把一件事读掉**。GitHub 通知、Slack 未读都这么做,不是巧合。
-
----
-
-## 可见性
-
-`kb_id` 可空,两种语义:
-
-```
-kb_id IS NULL 系统级:LLM 端点不可达(今天实际是三条 LLM 告警:不可达 / 限流 / 欠费)
- → 仅 users.is_admin
-
-kb_id 有值 知识库级:解析失败、抽取失败、源同步失败
- → 该库中角色 ≥ min_role 的人
-```
-
-**不新写权限逻辑**:`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
-- **内容类**(解析失败、抽取失败、源同步)→ **editor 及以上**
-
-内容类不能只给 admin:拿扫描件举例,admin 需要知道"该配 OCR 了",但**上传那 12 份文件的人**更需要知道"你传的东西没进去"。只给 admin 的话,真正被影响的人反而看不见。
-
----
-
-## 数据模型
-
-> **修订记录**:这一节原本是一份草案,含 `subject_ids UUID[]`、`resolved_at`、
-> 以及一个 `WHERE resolved_at IS NULL` 的部分唯一索引。随上面前两条决定一起作废。
-> **不在这里重抄一份 schema** —— 一份和迁移不一致的草案比没有草案更坏。
-
-真实定义见 [`migrations/0009_alerts.sql`](../../migrations/0009_alerts.sql)。形状是:
-
-- `alerts` 一次故障一行,写完不再改。`subject_id` 是**单列**不是数组 ——
- 一行只讲一个对象,`detail` 里存一份当时的名字,所以对象被删了这条告警仍然显示得出来。
-- `alert_reads` 两列,逐人。
-- 没有唯一索引,没有 `resolved_at`,没有状态机。
-
-有一个坑草案里记对了,值得留着:**`kb_id IS NULL` 的那些行**。当初打算用
-`WHERE resolved_at IS NULL` 的部分唯一索引做聚合,而 NULL 不参与唯一性判定,
-系统级告警会每次上报插新行 —— 聚合对最需要它的那一类静默失效。
-现在没有唯一索引了所以这个坑不存在,但**同类问题还在别处**:
-`mark_group_read` 里比 `kb_id` 用的是 `IS NOT DISTINCT FROM` 而不是 `=`,
-就是同一件事。
-
-**推送**复用现有的 `AppEvent` broadcast(加了一个 `alert` kind)。
-但 SSE 路由是**按库**的(`/kbs/{id}/events`),而角标跨库、系统级告警根本没有库,
-所以另开了一条全局流 `/alerts/events`。那条流**不带数据也不判权限**:
-收到的人一律回头重取,谁能看见什么由列表查询判且只判一次 ——
-代价是没权限的人也被叫醒一次,换来的是推送这条路上一行权限逻辑都没有。
-
----
-
-## 第一刀的范围
-
-**不先建空框架。**
-
-迁移是最难回头的部分。空表建好、发布了,等真接入时发现 schema 不够用(聚合该用数组还是关联表、`min_role` 该在行上还是按 kind 硬编码),改迁移就得走升级路径。而现在还没打 tag,迁移可以推倒重来 —— 这个窗口不该浪费在一张没有数据流过的表上。
-
-更要紧的是:**聚合、自愈、per-user 已读这三件最容易设计错的事,只有真有数据经过才验得出来。** 空框架把它们全留到了以后。
-
-> **这一段被验证了,方式跟预期的不一样**:真有数据经过之后,三件里有两件被证明是错的
-> ——而且都是先照原设计写出来、跑起来才看出来的。要是先建了空框架、
-> 等到有第二第三种告警才接真实数据,这两个设计早就随迁移发出去了。
-
-所以第一刀接**两条真实告警源**,各验一条权限路径,且都不需要新的检测逻辑:
-
-| kind | 级别 | 验证什么 | 结果 |
-|---|---|---|---|
-| `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` 的判据在实现中也放宽过一次:起初只认传输层失败(连不上),
-结果最常见的那种故障——URL 配错、代理挡在中间回了 HTML——**一条告警都不产生**,
-正是"失败无声"本身。现在它的含义是"没能从端点拿到一个能解析的回答":
-连不上,或者连上了但回来的不是这个 API。端点干干净净地回 4xx 不算 ——
-那说明它就是模型 API,只是密钥或配额不对,该找的人不同。
-
-UI:顶栏铃铛 + **弹出面板**,不是页面 —— 告警是顺手瞄一眼的东西,
-做成页面会逼人离开手头的事,而离开的代价就是没人去看。
-未读是一个红点不是数字("有事没看"是二元的,而数字会随重试一路往上跳),
-**点击才算读过,不是划过**(鼠标经过一列告警不代表看过它们,而已读落下就不会自己回来)。
-
-### 留到第二批
-
-**`document.no_text_layer`(扫描件)** —— 它需要先写检测逻辑(判断解析结果为空),
-而且真正有用是在有了 OCR 端点之后:那时提示语才完整 ——「文档没有文本层,
-配置 OCR 端点后可重新处理」,同时是错误说明和功能引导。
-
-接它的时候**不要再想"什么时候算修好了"**(见第 2 条):一份扫描件解析为空就记一条,
-12 份就是 12 行,面板把连着的折成一行并显示计数。重新处理成功之后不用去清任何东西 ——
-不再有新故障,那些行自己沉下去,到期被保留期清理。
-
----
-
-## 被否决的方案
-
-**复用 `audit_events`。** 那张表是"谁做了什么"的台账,性质是不可变记录;告警是"出了什么事",需要 per-user 已读与折叠展示。塞进同一张表会让台账不再是台账。
-
-> **修订记录**:原文这一条的理由是"告警需要状态流转(未读 → 已读 → 已解决)"。
-> 状态流转那部分随第 2 条作废了 —— 告警行现在也是不可变记录。
-> **但结论不变**,只是理由换了一条:台账记的是人做的事,告警记的是系统出的事,
-> 两者的保留期、可见性规则、读者都不同(告警 30 天到期清理,台账不能清)。
-
-**不建表,把六处失败状态 union 起来查询展示。** 零迁移、零新概念,但存不下 per-user 已读,
-也留不住历史 —— 来源修好之后 `last_sync_status` 就变了,"上周三那次为什么没进来"再也查不到。
-
-**共享已读**。见上文「三个决定」第 3 条。
-
-**存储层聚合**、**自愈 + 探针**、**按 `(kb, kind, subject)` 去重**。
-见第 1、2 条的修订记录 —— 前两个是先建成再拆的,第三个在纸面上就否掉了。
+# 0005 · The alert center
+
+- **Status**: Built · five kinds live (`source.sync_failed`, `llm.unreachable`,
+ `llm.rate_limited` #160, `llm.out_of_credit` #182, `data_source.schema_sync_failed`);
+ the panel has search and per-group paging; decisions 1 and 2 were overturned during
+ implementation; `document.no_text_layer` still unwired.
+- **Written**: 2026-08-29 · condensed into English 2026-09-03
+- **Related**: adjacent to the Review queue
+ ([0001](0001-ontology-import-and-governance.md) P4);
+ [0004](0004-language-and-localization.md) is why titles are assembled on the client.
+
+## The problem
+
+Failure state was scattered over six places with no single view: `jobs.status='failed'` +
+`jobs.last_error` (no UI at all), `documents.status='failed'`,
+`documents.graph_status='failed'`, `sources.last_sync_status='failed'`,
+`source_sync_runs.status='failed'`, and the log. It had been patched once, by adding
+`graph_error` to `documents`: one column per failure class. With reasoning, execution, OCR
+and lakehouse connections still to come, that road ends with a dozen error columns and no
+answer to "what is wrong right now".
+
+The real harm is silent failure. Drop in 100 PDFs, 12 of them scans, and the UI shows 100
+green rows; the user finds out when an answer lacks that contract, and never suspects
+ingestion.
+
+**Boundary with Review.** Review holds what needs a decision (merge these two entities?);
+the alert center holds what a person needs to know (this document did not get in). Review
+guards the correctness of knowledge; alerts guard the health of the system.
+`extraction_drops` (11 drop reasons, shown per document on the library row) is a third
+channel: something in this document did not land. None of it goes to Review.
+
+## Decisions
+
+1. **Aggregation belongs to the view.** 100 PDFs with 12 scans must read as one line, "12
+ documents have no text layer", or the alert center is ignored within two weeks. But a
+ stored aggregate is live and must be cleared when things recover, or it lies. So: one
+ row per failure, never updated; the read side folds adjacent rows of the same `(kb,
+ kind)` in SQL (gaps and islands, two `row_number()` subtractions), because paging is by
+ group and a client-side fold would split a run at a page boundary. Counts are computed
+ and never stale; a different failure in between is a different episode.
+2. **"Is it fixed?" is a question the alert center does not answer.** Every failure is a
+ new row. Once the fault is fixed there are no new rows; read ones sink and the badge
+ goes dark; a recurrence two months later is a new alert. No success signal, no probe,
+ no time constant. The cost is rows (a broken hourly source writes 24 a day), purged
+ after `alerting::RETAIN_DAYS` (30). Whether something is still broken is on the source
+ page and in document status; an alert's job is to make someone look.
+3. **Read state is per person.** `alert_reads` is a two-column table; unread means
+ "visible to me and not clicked by me". Reading says whether I have seen it, nothing
+ about whether it is over. Nobody can read an alert away for someone else, as with
+ GitHub notifications and Slack unread.
+4. **Visibility reuses the KB role chain.** `kb_id IS NULL` marks a system-level alert
+ (the three LLM kinds), visible to `users.is_admin` only; a KB-level alert is visible to
+ roles ≥ `min_role` in that KB, and admins see everything, as in `access::kb_role()`.
+ `min_role` lives on the row: configuration alerts go to admins, content alerts (parse,
+ extraction, source sync) to editors and above, because whoever uploaded the 12 scans
+ needs to know more than the admin does.
+5. **A row names one subject and carries no display text.** `subject_id` is a single
+ column, and `detail` keeps the subject's name so the alert renders after the subject is
+ deleted. Titles are assembled on the client by kind
+ ([0004](0004-language-and-localization.md)), so search matches KB name, `detail` and
+ the kind code, never the title.
+6. **Push is one global stream with no data and no permission check.** The per-KB SSE
+ route cannot carry a cross-KB badge, so `/alerts/events` rides the existing `AppEvent`
+ broadcast (kind `alert`) and only tells clients to refetch; the list query decides
+ visibility once. Someone without permission is woken for nothing, and the push path
+ holds no permission logic.
+7. **Classification is a pure function on error types.** `alert_for` decides the kind from
+ the error's type, never its text, and has unit tests; job failures reach it through
+ `observe_job_failure` only once retries are exhausted. `llm.unreachable` means "no
+ parseable answer from the endpoint": connection refused, or a proxy answering HTML. A
+ clean 4xx is the API saying the key or quota is wrong, another person's problem
+ (`rate_limited`, `out_of_credit`).
+8. **A bell with a popover**, because a page pulls people away from their work and then
+ nobody goes. The badge is a red dot ("something unseen" is binary; a count jumps with
+ every retry); a click marks read, hovering does not.
+
+## Dead ends
+
+- **Stored aggregation**: `(kb_id, kind)` unique among unresolved rows, repeats appended
+ to `subject_ids UUID[]`. Built first; three bugs shared one root: the row was hollowed
+ out as things self-healed (empty `subject_ids` and `detail`) and produced titles like "0
+ sources failed to sync". Its `WHERE resolved_at IS NULL` partial unique index would also
+ have failed silently for `kb_id IS NULL`, since NULL never collides; the same trap is
+ why `mark_group_read` compares `kb_id` with `IS NOT DISTINCT FROM`.
+- **Self-healing** (`resolved_at` cleared by the producer). Every new kind must implement
+ its own "what counts as fixed": `source.sync_failed` gets it free from `finish_sync`;
+ `llm.unreachable` needed a background probe hitting the endpoint every minute, guarded
+ by "is the alert still lit?". A missing clear is invisible at compile time and shows as
+ an alert that never goes out. Recorded because the idea is tempting enough to be
+ proposed again.
+- **Dedup by `(kb, kind, subject)` with a bumped timestamp**: bounded rows, no retention,
+ rejected on paper. Recurrence and "never fixed" become indistinguishable, so either
+ read-once-forever (a recurrence is silent) or every bump re-unreads (a known fault
+ lights up hourly). Missed alerts cost more than rows.
+- **Shared read state**: any admin opening an alert marks it read for all. A glances in
+ the morning and puts it off; B and C never learn it happened, and no trace shows the
+ gap.
+- **Reusing `audit_events`**: the ledger records what people did; alerts record what the
+ system did, with different retention (30 days versus never), visibility and readers.
+- **A UNION over the six status columns, no table**: zero migrations, but no per-user
+ reads and no history; once the source recovers, "why did last Wednesday's sync fail" is
+ gone.
+- **An empty framework first**: migrations are the hardest thing to take back, and
+ aggregation, self-healing and per-user reads can only be validated with data flowing.
+ Two real sources went first (`source.sync_failed`, and `llm.unreachable` for `kb_id IS
+ NULL`), and two of the three original decisions failed on them before any tag was cut.
+
+## Revisions
+
+- The "resolved for everyone at once" half of decision 3 went with decision 2; the
+ per-person half stands.
+- 2026-09-02: "no new permission logic" did not hold. The list filters in one SQL
+ statement through `access::visible_kb_roles()`, a `VISIBLE` CASE and a `rank()` in
+ `alerts.rs` that must stay in the same order as `Role`'s `PartialOrd`: three places to
+ edit when roles change, exactly the hidden rule this repository fears.
+- 2026-09-02: three more kinds were wired from existing error classes with no new
+ detection logic. `data_source.schema_sync_failed` is raised from a state left behind
+ (source attached, schema never ingested), so "any execution path reports on failure" was
+ too narrow.
+- `llm.unreachable` first matched only transport failures, so the commonest fault (a wrong
+ URL, a proxy answering HTML) produced no alert at all.
+
+## Open questions
+
+- **`document.no_text_layer`** waits for detection (an empty parse result) and an OCR
+ endpoint, so the message can say "no text layer; configure OCR and reprocess". When
+ wired, do not ask when it is fixed: one row per scan, the panel folds adjacent rows,
+ reprocessing needs no cleanup.
diff --git a/docs/decisions/0006-ontology-scale-and-the-prompt.md b/docs/decisions/0006-ontology-scale-and-the-prompt.md
index 75855dae..e57ac1df 100644
--- a/docs/decisions/0006-ontology-scale-and-the-prompt.md
+++ b/docs/decisions/0006-ontology-scale-and-the-prompt.md
@@ -1,131 +1,80 @@
-# 0006 · 本体规模与抽取提示词
-
-- **状态**:已建成 · 预算(24,000 字符)与按块检索在线,数值未动;「内置类恒在」那道地板已被**祖先补齐**取代(见文末修订);预算的具体数值仍待更好的语料来定——外部语料已入库,答案键仍是人填的(2026-09-02 核)
-- **成文**:2026-08-29(约定见 [README](README.md))
-
-> 这一篇比别的多一样东西:**数字**。它们来自 `scripts/bench/`,任何人都能重跑。
-> 每个数字后面都标了它**不能**说明什么——一次运行的差别常常只是跑次方差,
-> 而把方差当成效果,是这轮里我犯过不止一次的错。
-
-## 问题
-
-抽取提示词把**整个本体**铺进去,每个文本块重发一遍。`extraction.rs` 从前只有一句
-`entity_types(kb)`,一个不落。
-
-导入 schema.org 当前版之后:968 个类、1034 个关系、599 个属性,**每个文本块 108,133
-token**。这个数字不是某个设计的代价,**是没有设计的结果**——代码里根本没有"选"这个
-动作。0001 的 P3 曾把它归到"800 个类时提示词爆炸",但那时没人量过真实本体,而且
-猜错了大头:类清单只占 38%,关系 34%、属性 28%。
-
-## 决定
-
-**按预算切换,不按类数量。**
-
-- 装得下 → 全量铺,行为一字不变。四十个类的本体约 2k 字符,检索反而是多余的往返。
-- 装不下 → **每块用它自己的向量检索候选**,内置类恒在〔已换成祖先补齐,见文末〕,检索不出来就退回全量。
-
-预算按**字符**而不是类数量:类描述的长度差着数量级(`SoftwareApplication` 的描述是
-一句话,FIBO 的能有一整段)。判据量的是**实际要排的那段字**(`build_lists` 自己数),
-不是另写一个估算公式——公式会跟排版分叉。
-
-分块向量是**现成的**:`chunk.embedding` 在抽取循环里本来就加载了(实体消解在用),
-所以按块检索一次嵌入调用都不加。
-
-预算落在 `deployment_settings.ontology_prompt_budget` 而不是常量或环境变量,
-理由是测量本身:定它需要每档两组对照,靠重启服务改一档的话,那条曲线不会有人跑第二遍。
-
-### 三个细节只在"选择"存在时才有
-
-1. **签名只能提到铺出去的类。** `works_at (person → organization)` 里那两个 key 必须是
- 模型看得见的——写一个没铺出去的类名,等于教它输出一个不存在的类型。整侧都没选中
- 就退回 `*`。
-2. **属性跟着 domain 走。** 属性行是 `class.attr`,它的类没铺出去这行就没意义。
- 这顺带解决了属性段(提示词的 28%)的裁剪,不用单独处理。
-3. **两条路共用一个 `build_lists`。** 两份排版代码迟早分叉,而分叉在这里的后果是
- 提示词说的与代码认的不是一回事。
-
-## 量到了什么
-
-同一份语料(`scripts/bench/corpora/pharma.json`,5 篇中文医药文档),**每组一个新库**,
-先导本体再灌语料(抽取当场就看得见本体)。
-
-| 内联的类 | 本体段字符 | 模式 | 抽到实体/事实 | 抽取秒 |
-|---|---|---|---|---|
-| 32 | 2,977 | 全量 | 23 / 25 | 47 |
-| 32 | 2,977 | 检索 | 28 / 27 | 31 |
-| 78 | 19,187 | 全量 | 25 / 26 | 41 |
-| 78 | 19,187 | 检索 | 23 / 26 | 36 |
-| 202 | 58,651 | 全量 | 26 / 27 | 36 |
-| 202 | 58,651 | 检索 | 23 / 26 | 36 |
-| 394 | 169,380 | 全量 | **跑不完(429 TPM 限流)** | — |
-| 394 | 169,380 | 检索 | 28 / 26 | 52 |
-
-**一、到 58,651 字符(约 15k token)为止看不到退化。** 实体数在 23–28 之间摆动,
-没有趋势。这跟"提示词一大抽取就掉东西"的直觉不符,也跟我先前的一个结论不符
-(见下方的撤回)。所以现在的 24,000 字符预算**偏保守**,但改它之前需要更好的语料。
-
-**二、全量内联有一个跟质量无关的硬天花板。** 400 类那一档全量组撞穿了供应商的每分钟
-token 限额(429),同一份本体检索组跑得下来。这不是"慢一点",是**跑不完**。
-
-**三、大本体确实带来正确的类型,但要靠检索送到眼前。** 另一组对照(schema.org 全量,
-968 类):只有种子本体时 19 个实体里 2 个类型正确;大本体只作用于事后消解时 7 个;
-大本体 + 按块检索进提示词时 12 个。
-
-## 这些数字**不能**说明什么
-
-- **每组只跑了一次。** 同一份输入、同一套设置,我们观测到过 25 个实体与 18 个实体的
- 差别。所以实体数那一列的个位数差异**读不出信息**,只有趋势(或没有趋势)可读。
-- **子集是按字母序取的。** `subset.mjs` 取前 N 个类,所以 200 类那一档全是 A–B 开头的
- (`AdultEntertainment`、`Brand`…),不含 `hospital`、`pharmacy`、`drug`、`city`。
- 上表**没有列命中率**就是因为这个:正确答案不在子集里,命中涨不上去不是系统的问题。
- 要量"词汇量对质量的贡献",子集得按语料里实际出现的类采样。
-- **语料是我们自己写的,标准答案也是自己填的。** 语料、答案、系统三样出自同一只手,
- 过拟合无从检验。这是目前最大的短板,见下。
-
-## 未决
-
-**语料的合法性。** 现在两份语料(科技 / 医药)都是手写的,答案键是逐条人填的。
-它们作为 smoke fixture 是称职的——不联网、跑得快、结果确定——但**不足以支撑
-"这个改动更好"这种结论**,外部贡献者也无从基于它们做比较。
-
-方向是引入一份外部语料,且**标准答案由外部数据推导而不是由我们填**:中文维基百科
-正文(CC BY-SA,可入库可引用)配维基数据的 `P31` 作类型答案。要点不是"维基百科更
-真实"——它是百科体,跟企业文档并不一致——而是**答案不再是我们的意见**。
-生成脚本必须一并入库,否则"挑哪些条目"又成了一个没人能检查的选择。
-
-**预算与每块候选数的具体值。** 24,000 字符、每块 40 类 / 30 关系 / 30 属性,
-都是拍的,代码里标着。上面的曲线说它偏保守,但在语料这一关过掉之前,
-按那条曲线去调只是把过拟合调得更紧。
-
-## 修订记录(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 个实体」不成立。** 那条结论来自测量台的默认次序
->(先灌语料再导本体),两组抽取时提示词里都只有 9 个种子类,`prompt_tokens_est`
-> 量的是**导入之后**的本体——抽取从没见过它。25 vs 18 是跑次方差。
->
-> 台子当时没拦住这个错,因为指标名暗示了顺序没兑现的东西。现在两份规模分开报
->(`ontology_at_extraction` / `ontology_at_resolution`),并有 `--ontology-first`,
-> 次序写在输出里而不是靠人记得。
+# 0006 · Ontology scale and the extraction prompt
+
+- **Status**: Built · the character budget (`deployment_settings.ontology_prompt_budget`,
+ 24,000) and per-chunk retrieval are live, values unchanged; the "built-in classes always
+ present" floor is replaced by ancestor completion; answer keys are still hand-filled.
+- **Written**: 2026-08-29 · condensed into English 2026-09-03
+- **Related**: [0008](0008-ontology-packs-as-cold-start.md) packs are now the starting
+ ontology; [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) measured the bias
+ that forced ancestor completion.
+
+## The problem
+
+The extraction prompt inlined the whole ontology once per chunk; `extraction.rs` called
+`entity_types(kb)` with no selection step. After importing schema.org (968 classes, 1034
+relations, 599 attributes) each chunk cost 108,133 tokens.
+[0001](0001-ontology-import-and-governance.md) P3 had guessed "800 classes blows the
+prompt" and got the shares wrong: classes 38%, relations 34%, attributes 28%.
+
+## Decisions
+
+1. **Switch by budget.** If the ontology fits, inline it all, unchanged: a forty-class
+ ontology is 2k characters and retrieval would be a wasted round trip. If not, each
+ chunk retrieves its own candidates with `chunk.embedding` (already loaded for entity
+ resolution), falling back to the full list when nothing is retrieved. The budget is in
+ characters because description lengths differ by orders of magnitude, and it measures
+ the text `build_lists` actually lays out. It is a deployment setting because tuning it
+ needs paired runs per level, and nobody reruns a curve that needs a server restart per
+ point.
+2. **Three details that exist only once there is a choice.** Signatures may name only
+ inlined classes (an absent class in `works_at (person → organization)` teaches the
+ model a type that does not exist; an unselected side becomes `*`); attributes follow
+ their domain class; both paths share one `build_lists`, or the prompt stops matching
+ what the code accepts.
+3. **Ancestor completion** (2026-09-02): whatever retrieval hits, its `subClassOf`
+ ancestors are inlined too, breadth-first with a visited set. The chain is the
+ ontology's own declaration of generalization; no hand-kept list of "general classes".
+ The only detail forced by real data.
+
+**The bench** (`scripts/bench/corpora/pharma.json`, 5 Chinese pharmaceutical documents,
+one run each) showed no degradation up to 58,651 characters of ontology (about 15k tokens,
+202 classes): entities per run swung 23–28 with no trend, so 24,000 is conservative. Full
+inline has a ceiling unrelated to quality: at 394 classes (169,380 characters) it hit the
+vendor's per-minute token limit (429) and never finished; retrieval did. With schema.org,
+correctly typed entities went 2 of 19 with seeds only, 7 with the large ontology in
+post-hoc resolution, 12 with per-chunk retrieval. Caveats: single runs (the same input has
+produced 25 and 18 entities) and alphabetical subsets (`subset.mjs` takes the first N
+classes), hence no hit rate.
+
+## Dead ends
+
+- **A fixed floor of built-in classes.** Its premise, that seed classes are the general
+ ones, died when #128 stopped seeding.
+ [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) measured the symptom:
+ retrieval favors leaf classes that appear literally in the text (`researcher` ranks 4th
+ of 976, `person` 359th), so `employee (organization → person)` degraded to `(* → *)`.
+- **`BATCH = 16` in the ontology index**, chosen from synthetic short texts; 64 doubled
+ throughput. **`join_all` over 31 embedding batches** held the shared `model_concurrency`
+ gate for fifteen minutes; now `EMBED_JOBS = 4`.
+
+## Revisions
+
+- Withdrawn: "the 108k prompt ate 5 entities". The bench ingested first and imported
+ later, so both runs extracted with 9 seed classes and `prompt_tokens_est` measured an
+ ontology extraction never saw; 25 vs 18 was run variance. The bench now reports
+ `ontology_at_extraction` and `ontology_at_resolution` separately and has
+ `--ontology-first`.
+- 2026-09-02: per-chunk retrieval sends one vector query per chunk with concurrency up to
+ `worker_concurrency` (cap 256 since #133) against a pool of 32; migration `0011` records
+ it.
+
+## Open questions
+
+- **Legitimacy of the corpus.** The set grew from two to eight, with generation scripts
+ committed, but `scripts/bench/truth/` still holds only the hand-filled `pharma` and
+ `tech` keys. The intended fix is Chinese Wikipedia text with Wikidata `P31` as the type
+ answer, so the answer stops being our opinion; no `P31` code exists yet.
+- **Budget and per-chunk candidate counts** (24,000; 40 classes / 30 relations / 30
+ attributes) are guesses; tuning before the corpus question is settled only tightens the
+ overfit. `run.mjs --packs schema-org,prov-o` walks the real cold-start path, but that
+ comparison has not been run.
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 9b50c7c4..804d5ad9 100644
--- a/docs/decisions/0007-who-decides-what-becomes-a-relation.md
+++ b/docs/decisions/0007-who-decides-what-becomes-a-relation.md
@@ -1,182 +1,107 @@
-# 0007 · 谁来决定一个说法值不值得成为关系
-
-- **状态**:已建成 · 采纳改由计数决定;六条缺陷的修法全部在线;「叙述动词进了本体」与 `merge_key` 不折 `_by` 两条仍未解;**本文的起点(10 个种子关系、`related_to` 占比)已不存在**,见文末修订(2026-09-02 核)
-- **成文**:2026-08-30(约定见 [README](README.md))
-
-> 跟 [0006](0006-ontology-scale-and-the-prompt.md) 一样带数字,也一样标明每个数字
-> **不能**说明什么。这一篇额外记了走过的死路——四个被数据否掉的方案,
-> 其中三个是我自己提的。留着它们,是因为它们看起来都很合理。
-
-## 问题
-
-新建的库只有 10 个种子关系。灌进第一批文档,模型说出的关系大半不在这 10 个里,
-于是降级成 `related_to`——一个什么都没说的兜底谓词。
-
-实测(ai-timeline 语料,15 篇维基百科 AI 公司条目,348 块):**49.8% 的事实是
-`related_to`**,`ontology_misses` 里 398 个不同的关系名、895 次使用。
-
-`bootstrap_ontology` 本来就是为这件事设计的:抽取完把候选交给 LLM,让它提案、
-采纳、并改写等着它的旧事实。但它效果不好,而查下去发现原因不止一个。
-
-## 找到了什么
-
-按发现顺序,每一条都是独立的缺陷:
-
-**一、词汇明明在本体里,只因说法不同就被扔了。** 抽取只做精确字符串比对,
-`produced_by | ChatGPT → OpenAI` 想说的就是已有的 `produces`,主宾对调而已。
-→ [`predicate_match`](../../crates/utopia-server/src/predicate_match.rs):
-精确 key → 写法对齐 → 屈折归一,各再试一次去掉结尾的 `by`(命中就交换主宾)。
-
-**二、最后一篇文档失败,整个库永久卡住。** 自动扩本体的入队只写在成功路径上,
-而它的触发条件是「这一批都抽完了」。第 15 篇重试耗尽变 `failed` 时,条件恰好为真,
-可再没有任何一篇会完成来做这次检查。提案堆在池子里,本体永远停在种子那几个关系。
-→ 入队点挪到成功/失败都会走到的位置。
-
-**三、门槛算了却没生效。** `bootstrap_ontology` 把「出现在 ≥2 篇文档」筛出来,
-只用于判断值不值得跑一次 LLM,随后调 `build_proposals` 时只传 `kb_id`——那个函数
-重查一遍**没过滤的**全量。交给模型的 526 个说法里 **456 个(86.7%)只在一篇里
-出现过**。反方向也漏:5 个单篇说法被采纳了,其中两个建成了新属性。
-
-**四、`doc_count` 数的是残渣。** 它只数「还挂在兜底谓词上、还活着、宾语是实体」的
-事实。说法一旦被采纳、被谓词匹配接住、或被修正作废,行就离开积压,篇数随之下降。
-**一篇一篇往里灌的库因此永远攒不够两篇,本体就此冻死。**
-→ 普遍程度改从全量证据数,改写量仍从积压数。
-
-**五、「忽略」是一扇单向门。** `record_miss` 带着 `WHERE dismissed_at IS NULL`,
-点一次忽略既不再呈现、也**不再计数**。用户看着「出现 1 次」做的判断,被系统记成了
-对所有时间的判断——后面二十篇都在用它,计数仍停在 1,没有任何人看得见。
-→ 抑制与计数分开:计数照走,已忽略的连同更新后的计数单列一处,可撤回。
-
-**六、没有日期的事实自称精确到日。** `valid_precision` 是 `NOT NULL DEFAULT 'day'`,
-于是每一条两端都没有日期的事实都带着 `'day'` 落库(实测两个库分别 728 和 843 条活行)。
-→ 改成可空 + 「有日期才有精度」的 CHECK(见 `facts.valid_from_precision`)。
-
-## 决定
-
-**采纳由计数决定,不问模型。**
-
-LLM 从前被问的是「哪些说法值得建成关系」。那个问题数据已经答了——`runs_on` 出现在
-8 篇文档、13 条事实里,不是判断题。而模型实测答错:漏掉 `runs_on`,却采纳了只在
-一篇里出现过的 `pledged_capital`。
-
-三步,全部确定性:
-
-1. **按屈折基归并**(`predicate_match::merge_key`):`sued` 与 `sues` 是一个关系
-2. **算文档并集**:不能相加——同一篇可能两种写法都用过
-3. **过门槛**(≥2 篇),规范 key 取组里事实最多的那个说法
-
-模型没有被撤走,只是换了个问题:**同义归并**(`collaborates_with` 是不是就是
-`partnered_with`)。那个才需要理解意义,且答错了 `unadopt` 一键回退。
-
-**副作用是这条路最值钱的地方:采纳变成确定性的。** 同一份语料重跑得到同一个本体,
-测量台第一次能对这一段做对照——在此之前,两组之间 3 个百分点的差别究竟是改动
-还是跑次方差,答不上来。
-
-## 量到了什么
-
-同一份语料(`scripts/bench/corpora/ai-timeline.json`),348 块:
-
-| 组 | 本体关系 | `related_to` | 说明 |
-|---|---|---|---|
-| A | 10 | 55.5% | 自动扩本体关 |
-| B | 17 | 39.1% | LLM 采纳 |
-| B3 | 15 | 42.3% | LLM 采纳 + 门槛修复 |
-| **B3 + 计数采纳** | **104** | **25.8%** | 本篇的决定 |
-
-归并的贡献可以单独看:够格的候选从 **70 组 / 281 条**涨到 **85 组 / 355 条**,
-40 组吸收了 80 个说法,每组都是同一个动词的不同时态
-(`sued`/`sues`、`reported`/`report`、`integrated_with`/`integrates_with`、
-`announced`/`announces`、`develops`/`developed`……)。
-
-`_by` 是唯一值得处理的反向标记:31 种写法,`founded_by` 42 条、`released_by` 19、
-`produced_by` 15。而且几乎每个都有主动版本共存(`produces` 265 条),
-不折叠就会建出两个方向相反的关系。`has_X`/`X_of` 只有两对,证据不够。
-
-> **后续(2026-08-30,#109)**:采纳前先过一遍 `PredicateIndex`——本体里已经有
-> 等价关系(含 `_by` 反向)就不新建,直接改写过去并对调主宾。`adopt` 也因此
-> 学会了交换主宾(此前它从旧行原样复制主语)。
->
-> **仍待做**:两边都不在本体里时(`founded_by` 42 条 vs `founded` 4 条,
-> 都够票且都没被采纳过),`merge_key` 不把 `_by` 折进同一组,于是仍会建出
-> 两个方向相反的关系。当初不折的理由是「采纳路径不能对调」,而那个理由
-> 已经不成立了——现在是笔小账,只差把 `_by` 加进 `merge_key` 并把整组标成需对调。
-
-## 这些数字**不能**说明什么
-
-- **B 与 B3 之间的 3 个百分点读不出信息。** 两组中间都夹着一次 LLM 调用,
- 同输入的跑次方差在这个语料上量到过 25 vs 18 个实体。能确定的只有确定性的部分:
- 单篇说法被采纳从 5 降到 0。
-- **`related_to` 占比不是质量指标。** 它衡量的是"有多少事实挂在一个什么都没说的
- 谓词上",压低它的最省事办法是把一切都收进本体——而那正是下面那个未决问题。
-- **语料在训练数据里密度极高。** 这批 AI 公司条目适合做 demo(认得出是优点),
- 不适合当准确率基准(量到的是背诵)。0006 里那条「语料的合法性」未决项仍然成立。
-
-## 未决:叙述动词进了本体
-
-104 个关系里混着维基百科的口吻:
-
-```
-reported/report 11 条 · states/stated 6 · describes/described 5
-criticizes/criticized 6 · published/publishes 6 · accused/accuses 6
-```
-
-这些是**文章在引述来源**,不是 AI 公司之间的结构。它们跨篇复现得很好,
-计数拦不住。而本体会反馈进抽取提示词——下一批文档抽取时,模型看见清单上有
-`states` 和 `describes`,会更倾向于把叙述也抽成事实。
-
-**区分叙述与结构需要判断,这是计数做不到的第三件事**(前两件是同义归并和
-介词变体,都已有去处)。候选方向:把它交给那次同义归并的 LLM 调用一并审
-("这些里哪些是文章的口吻"),问题小、可撤销。维护一张叙述动词表则太脆,
-换一个语料就失效。
-
-暂不处理:`related_to` 从 55.5% 降到 25.8% 已经是大改善,而叙述关系至少还带着
-原文措辞,比"有关联"多说了东西。〔**后续**:剩下那 25.8% 也不再显示成"有关联"了——
-`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` 这个缺口——两个方向都不在本体里时,仍会建出两条相反的关系。
-
-## 走过的死路
-
-留着它们,因为每一个当时看起来都很合理。
-
-**Snowball 词干器。** 用 `rust-stemmers` 做屈折归一,实测**方向是反的**:
-词表 10 个词时捞回 49 次,换成 schema.org 的 629 个词只剩 18 次。原因是它连派生
-后缀一起削,`producer`(一个人)与 `produces`(一个动作)都成了 `produc`,
-撞车规则于是拒绝匹配——**词表越大越不敢动**。改成只削屈折后缀后是 49 → 59。
-
-**主语多样性替代文档数。** 想法是"这个说法连接了多少个不同的主语"比"出现在几篇
-文档里"更贴近普适性。实测更严:捡 6 个丢 33 个。而且那 6 个里大多数是**并列主语**
-造成的假象——"A、B、C 都提议了 X"被拆成 3 条事实,3 个主语 1 个宾语,
-量到的是句子语法不是词汇普适性。
-
-**`docs>=2 OR subjects>=3` 并联。** 上一条的补救,被同一个并列主语问题击穿。
-
-**每篇文档完成就触发一次自动扩本体。** 想解决"最后一篇失败就永久卡住",但会把
-`>=2 篇` 的语义从"语料的"变成"到目前为止的",更要紧的是**合并判断会变差**——
-池子完整时 LLM 同时看得见 `acquired`/`acquires`/`acquisition_of`,能一次并成一个;
-拆成 8 次跑,每次只看见一两个,看不见簇就合不动。而且采纳批次从 1 个变成 8 个,
-撤销要逐个点。最后走的是最小修法:入队挪到成功/失败都会走到的位置。
-
-**为「真新关系卡在一篇」再加一个阈值。** 直觉是"事实数 ≥3 也算够格"。
-数据否掉:那样放进来的**头两名恰恰是最差的两个**(`has_property` 11 条、
-`intends_to` 5 条)。单篇 ≥3 条的一共 20 组 86 条,看着像关系的约 5 组 25 条
-——占全库 1.2%。不为它加第四个拍脑袋的阈值;会长大的库自己会解决,
-静态语料则交给手动面板(`min_docs = 0`,看得见全部)。
+# 0007 · Counting decides what becomes a relation
+
+- **Status**: Built · adoption by counting (`MIN_DOCS = 2`; an LLM run needs `MIN_SIGNALS
+ = 3`); six defects fixed; proposals persist in `ontology_proposals` (#112); open:
+ narrative verbs in the ontology, `merge_key` not folding `_by`; the starting point (10
+ seeds, the `related_to` share) no longer exists.
+- **Written**: 2026-08-30 · condensed into English 2026-09-03
+- **Related**: [0006](0006-ontology-scale-and-the-prompt.md) for the bench and its
+ caveats; [0010](0010-no-relation-is-no-relation.md) and
+ [0011](0011-a-mapping-is-not-a-fact.md) removed the seed relations this record started
+ from; [0008](0008-ontology-packs-as-cold-start.md) packs are now the start;
+ [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) has the successor metric.
+
+## The problem
+
+A new knowledge base started with 10 seed relations. Most relations the model produced
+were not among them and degraded to `related_to`, a predicate that says nothing: 49.8% of
+facts on the ai-timeline corpus (15 Wikipedia articles on AI companies, 348 chunks).
+`bootstrap_ontology` existed for exactly this and worked badly, for six independent
+reasons:
+
+1. Exact-string matching discarded vocabulary already in the ontology: `produced_by |
+ ChatGPT → OpenAI` missed `produces`. Fix: `predicate_match` (spelling, inflection, and
+ a trailing `by` that swaps subject and object).
+2. If the last document failed, the KB stuck forever: auto-extension was enqueued on the
+ success path only. Fix: enqueue on both paths.
+3. The ≥ 2 documents threshold only gated the LLM run; `build_proposals` re-queried the
+ unfiltered set, so 86.7% of the phrasings shown to the model came from one document.
+4. `doc_count` counted leftovers still on the fallback predicate, so a KB fed one document
+ at a time never reached two. Fix: prevalence counts all evidence.
+5. "Ignore" was a one-way door: `record_miss` skipped dismissed phrasings, so counts froze
+ at 1 while twenty later documents used them. Fix: count everything; list dismissed
+ apart, undoable.
+6. Undated facts claimed day precision (`valid_precision NOT NULL DEFAULT 'day'`; 728 and
+ 843 live rows). Fix: nullable, CHECK-tied to a date (`facts.valid_from_precision`).
+
+## Decisions
+
+1. **Counting decides adoption.** The model is not asked: the data answers "which
+ phrasings deserve to become relations", and the model got it wrong: it skipped
+ `runs_on` (8 documents, 13 facts) and adopted a single-document `pledged_capital`.
+ Three deterministic steps: group by inflectional base (`predicate_match::merge_key`:
+ `sued` and `sues` are one), take the union of documents per group (never a sum), pass
+ `MIN_DOCS = 2`; the group is named by its most frequent phrasing. From 10 seeds,
+ `related_to` went 55.5% with auto-extension off, 39.1% with LLM adoption (17
+ relations), 25.8% with counted adoption (104).
+2. **The model keeps the question that needs meaning**: synonym merging (is
+ `collaborates_with` the same as `partnered_with`), reversible with `unadopt`.
+3. **Deterministic adoption is the most valuable side effect**: the same corpus produces
+ the same ontology, so the bench can compare this stage at all.
+4. **`_by` is the only inverse marker worth handling** (#109): 31 forms (`founded_by` 42
+ facts), nearly all coexisting with an active form (`produces` 265). Before adopting,
+ `PredicateIndex` is consulted; an existing equivalent, `_by` inverse included, is
+ rewritten to with subject and object swapped. `has_X`/`X_of` had two pairs, not enough
+ evidence.
+
+Caveats: differences between LLM groups are within run variance (25 vs 18 entities on the
+same input); only the deterministic part is certain (single-document adoptions 5 → 0). The
+`related_to` share is no quality metric, since adopting everything lowers it fastest, and
+the corpus is dense in training data.
+
+## Dead ends
+
+- **Snowball stemming** (`rust-stemmers`) went the wrong way: 49 matches with a 10-word
+ vocabulary, 18 with schema.org's 629, because it strips derivational suffixes too;
+ `producer` and `produces` both become `produc` and the collision rule refuses to match.
+ Inflectional suffixes only: 49 → 59.
+- **Subject diversity instead of document count**: stricter in practice (6 gained, 33
+ lost), and most of the 6 were coordinated subjects ("A, B and C proposed X" split into
+ three facts). `docs >= 2 OR subjects >= 3` fell to the same problem.
+- **Auto-extension after every document**: "≥ 2 documents" becomes a so-far property, and
+ merging degrades, since the LLM merges `acquired`/`acquires`/`acquisition_of` only when
+ it sees them together.
+- **A fact-count threshold (≥ 3) for new single-document relations**: the top two it
+ admits are the worst two (`has_property` 11, `intends_to` 5); about 5 of 20 groups look
+ like relations, 1.2% of the KB. Growing KBs solve this themselves; static corpora have
+ the manual panel (`min_docs = 0`).
+
+## Revisions
+
+- 2026-09-02: both premises are gone. Seed relations left in three steps (`related_to` in
+ [0010](0010-no-relation-is-no-relation.md), eight more in #125, `mapped_to` in
+ [0011](0011-a-mapping-is-not-a-fact.md)) and the seeding function with them (#128); a
+ new KB starts from a pack ([0008](0008-ontology-packs-as-cold-start.md)). The numbers
+ above are not comparable with anything measured today: a fact may now have no predicate
+ (the original word goes to `fact_evidence.proposed_predicate`), and the successor
+ metric, empty-predicate share, measured 25.6% in
+ [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) under a different start and
+ definition. The decisions are unaffected and all live.
+- 2026-09-02: the ontology can declare inverses (#177/#179) and direction is corrected on
+ write (#138, leaving a `direction_corrected` trace). That does not close the `merge_key`
+ gap below.
+
+## Open questions
+
+- **Narrative verbs enter the ontology.** Among the 104 relations: `reported/report` 11,
+ `states/stated` 6, `describes/described` 5, `criticizes/criticized` 6: the article
+ citing sources, no structure between companies. They recur across documents, so counting
+ cannot stop them, and the ontology feeds back into the prompt. Candidate: ask the
+ synonym-merging LLM call "which of these are the article's voice", small and reversible;
+ a verb list would break with the next corpus.
+- **`merge_key` does not fold `_by`.** When neither direction is in the ontology
+ (`founded_by` 42 vs `founded` 4, both qualifying), two opposite relations are still
+ created. The original reason, "the adoption path cannot swap", no longer holds; fold
+ `_by` into the group and mark it for swapping.
+- **What a 1,500-term start does to the adoption loop** has not been measured; no
+ threshold has moved.
diff --git a/docs/decisions/0008-ontology-packs-as-cold-start.md b/docs/decisions/0008-ontology-packs-as-cold-start.md
index 7d75652f..53216bd5 100644
--- a/docs/decisions/0008-ontology-packs-as-cold-start.md
+++ b/docs/decisions/0008-ontology-packs-as-cold-start.md
@@ -1,184 +1,119 @@
-# 0008 · 预制本体包作为冷启动
-
-- **状态**:已建成 · 五个包内嵌进二进制、建库时多选(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) 拆掉了大本体的提示词障碍;
- [0007](0007-who-decides-what-becomes-a-relation.md) 定了从种子长大的采纳规则
-
-> 与 0006、0007 同规格:先摆数字,并标明每个数字**不能**说明什么。
-> 本篇的数字**只来自官方发布文件**(2026-08-30 抓取),任何人都能重跑。
-> **刻意不引用开发库的统计**——那是 mock 语料,能说明错误的形状,
-> 不能说明真实部署的比率,写进决策记录只会被后人当成依据。
-
-## 问题
-
-新建的库只发 10 个种子关系(成文时 `graph.rs` 的 `RELATION_TEXT_ZH`;今天那张表、`localized()` 与 `ensure_default_ontology` 都不存在,`graph.rs` 开头留了三次退场的理由)。这 10 个里
-**零个带类型签名**——没有 domain,没有 range。
-
-抽取提示词是支持签名的(`extract/lib.rs:498` 的测试:`- buys_from (employee|team → *)`),
-有签名的谓语会带上「主语类型 → 宾语类型」。种子没得可喂,于是退化成一句白话:
-`- works_at: 受雇于某个组织。`
-
-**一句白话约束不了方向。** `produces` 的定义是「一个组织或项目制造、发布或推出了宾语」——
-「组织或项目」是对主语的**类型提示**,不是**方向约束**。模型读到「Anthropic 的 Claude」,
-知道两者有 `produces` 关系,但没有任何机器可检的东西告诉它谁该在主语位。
-而产品在本体里往往也归到 Project 或 Product,于是两个方向读起来都合法。
-
-十个种子里只有 `part_of` 写了反例("**不是「可以在……上用」**"),显然是踩过坑之后补的。
-**这正是问题所在**:用散文补方向,每个谓语都要单独踩一次坑,而且补丁只在那一条下面生效——
-`part_of` 警告过的"能在某服务上玩",换个谓语照样踩。
-
-`graph.rs` 开头的自陈(今天挪到了 `bootstrap_ontology.rs` 开头,**内容已过时**,仍写着 10 个默认关系与降级 `related_to`)说明这不是个别谓语的事:
-
-> 文档,里面的关系大半不在这 10 个里,于是大量事实降级成 related_to
-
-**十个谓语覆盖不了真实文档,而扩到几十个也不解决方向问题**——只要方向靠散文写,
-就是 O(谓语数) 次踩坑。
-
-## schema.org 把方向变成结构
-
-| | 类 | 属性 | domain+range 齐全 |
+# 0008 · Ontology packs as the cold start
+
+- **Status**: Built · five packs embedded in the binary (gzip, 1.7 MB → 316 KB),
+ multi-select at KB creation with schema.org checked by default, 22-row static alignment
+ table · a new KB seeds no relations: the packs are the whole ontology · the three open
+ questions stay open; the Chinese-label one got worse (2026-09-02 check)
+- **Written**: 2026-08-30 · condensed into English 2026-09-03
+- **Related**: [0001](0001-ontology-import-and-governance.md) criteria and IRI/key split;
+ [0006](0006-ontology-scale-and-the-prompt.md) prompt budget;
+ [0007](0007-who-decides-what-becomes-a-relation.md) growth loop;
+ [0009](0009-no-type-is-a-type.md) the empty start;
+ [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) the packs on a real corpus
+
+## The problem
+
+The ten seed relations a new KB used to receive (since removed) had no domain or range. The
+extraction prompt supports signatures (`- buys_from (employee|team → *)`), but with none to
+feed it each predicate degraded to prose, and prose cannot fix direction: `produces` — "an
+organization or project makes or releases the object" — hints at the subject's type without
+constraining it, so a model reading "Anthropic's Claude" has nothing machine-checkable to
+say which side is the subject. Only `part_of` had a counter-example written in, after a
+mishap; fixing direction with prose costs one mishap per predicate and holds only under that
+line. Ten predicates do not cover real documents either (most facts degraded to
+`related_to`), and widening to dozens does not fix direction.
+
+schema.org turns direction into structure: 1010 classes, 1521 properties, **1488 (97.8%)
+with both domain and range**. With `schema:manufacturer Product → Organization`, `Claude
+manufacturer Anthropic` is legal and the reverse is stopped at domain validation before it
+reaches the graph.
+
+## Candidates
+
+Counted from the official release files of 2026-08-30 (not from the dev database: a mock
+corpus shows the shape of errors, not real ratios). Criteria: readable by the current
+importer (Turtle / RDF-XML), open license, has domain/range.
+
+| Pack | Size | Classes / properties | Fills |
|---|---|---|---|
-| 我们的 10 个种子 | — | 10 | **0** |
-| schema.org(2026-08-30) | 1010 | 1521 | **1488 = 97.8%** |
-
-```
-schema:manufacturer Product → Organization
-schema:worksFor Person → Organization
-```
-
-`Claude manufacturer Anthropic` 合法;反向因为 `Anthropic` 不是 `Product`,
-**在 domain 校验时就被拦掉**,根本进不了图。方向不再靠散文描述,而是靠声明。
-
-注意 `manufacturer` 的方向与我们的 `produces`(组织 → 产品)**正好相反**。
-这不影响结论——重点不是哪个方向对,是方向被显式声明了。
-
-## 候选包(实测)
-
-抓取并按各自语法计数。判据三条:能被现有导入器吃下(Turtle / RDF-XML)、开放许可、带 domain/range。
-
-| 包 | 体积 | 类 | 属性 | domain | range | 补什么 |
-|---|---|---|---|---|---|---|
-| **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〔发货的包记 49〕 | 69 | 63 | 62 | 溯源:Activity、Agent、wasDerivedFrom |
-| **FOAF** | 43 KB | 12 | 62 | 60 | 57 | 社交关系 |
-| **IOF Core** | 394 KB | 294 | 75 | 94 | 94 | 工业制造 |
-
-**W3C Org 只有 13 类 34 属性,却补上 schema.org 最弱的一块。** schema.org 的
-`Organization` 是给网页用的,没有部门、职位、任期、汇报关系的概念。
-
-**PROV-O 顺带补上一个对外的缺口**:竞品对比里"Provenance: W3C PROV-O"与
-"Compliance export"两格,我们今天是自有 schema,导进来就有了标准词汇。
-
-### 下不到或不适合的
-
-- **FIBO**(金融)模块化发布,完整版要按 catalog 抓几百个文件。单模块(People)
- 只有 31 类。想做金融是单独一件工程,不是随手加一个包。
-- **Brick**(1438 类)与 **QUDT**:属性对类的比例极低(Brick 是 25 : 1438)——
- 它们是分类树不是关系本体,对抽取帮助有限。
-- **SAREF**:解析出的类与属性都是 0,声明形式我们的投影暂不覆盖,需先验证。
-- **SNOMED CT**:需授权。
-
-## 重叠有多少
-
-按 `key_from_iri()` 的实际算法比对——撞的是 key 不是 IRI。
-
-| 组合 | 撞名 | 具体 |
-|---|---|---|
-| org ∩ schema | **6** / 43 | `identifier` `location` `member` `member_of` `organization` `role` |
-| foaf ∩ schema | **15** / 72 | `agent` `name` `person` `knows` `member` `organization` `title` `image` `logo` `thumbnail` `given_name` `family_name` `gender` `project` `status` |
-| prov ∩ schema | **4** / 95 | `agent` `contributor` `creator` `publisher` |
-| org ∩ foaf | 2 | `member` `organization` |
-
-去重后**约 20 个词**。而且分两类,不能一概映射:
-
-**真同义 —— 映射掉**:`foaf:Person ≡ schema:Person`、`org:Organization ≡ schema:Organization`、
-`foaf:knows ≡ schema:knows`
-
-**同名不同义 —— 必须两份**:
-- `org:role` 是组织中的职位,`schema:role` 是创作作品里的角色(演员饰演)
-- `foaf:status` 是即时通讯的在线状态(2000 年代遗留),`schema:status` 是订单/动作状态
-
-**FOAF 重叠率最高(21%)而独有价值最低**——核心概念 schema.org 全有,剩下的
-`mbox_sha1sum`、`icqChatID` 是遗物。它进候选列表,但不进推荐默认。
-
-## 决定
-
-### 1. 建库时多选,不做预制捆绑
-
-初稿曾拟三个固定组合(通用 / 溯源合规 / 工业)。**否掉**:对齐表是两两声明的,
-`foaf:Person ≡ schema:Person` 这条不管用户选了几个包都成立,所以多选**不增加对齐成本**。
-而固定捆绑是拍脑袋的分类,现实里一定不匹配——做金融科技的要 IOF 加未来的 FIBO,
-咨询公司要 schema 加 Org 加 PROV,没有哪个捆绑覆盖得了。
-
-界面上每个包标出规模与**跟已选项的重叠率**,让用户自己掂量,而不是我们替他决定。
-
-### 2. 不做导入撤销
-
-`ON DELETE RESTRICT`(今天在 `0003_graph.sql`)加应用层计数(`ontology.rs` 的删类 / 删关系两处)加
-`NOT builtin` 三道防线〔第三道现在是空条件:没有 builtin 行了〕,已经保证了安全边界:**有实体挂着的类型删不掉**。
-
-所以"选错了怎么办"的实际路径是:没被用到的类型直接删,被用到的删不掉——
-**而删不掉恰恰是对的**,那些类型上挂着真实知识。
-
-需要的不是 `undo_import`,是一个**批量视图**:「这次导入建了 294 个类,
-12 个有实体在用,282 个空着」,一键删空的。比真正的撤销简单得多,
-且语义清楚——不碰任何有数据的东西。
-
-> 这三道防线值得单独记一笔,它是判据 2「本体是引导不是执法」的**反面**:
-> 本体不执法,但**知识可以否决本体的删除**。方向是知识保护本体,不是本体裁剪知识。
-
-### 3. 对齐表静态维护,不做运行时推断
-
-约 20 行,我们自己写。**上游已经写好了一部分**——W3C Org 官方文档声明了与 FOAF 的
-对齐,PROV-O 声明了与 FOAF、Dublin Core 的对齐,抄过来即可。
-
-不做自动对齐(标签相似度、嵌入匹配):预制包是我们选的,不是用户随便传的,
-只有五六套,两两重叠有限且可穷举。**把无限的对齐问题缩成一张静态表**,
-这与判据 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 类,
- 按块检索会同时召回 `org:role` 与 `schema:role`。0006 的预算保证**塞得下**,
- 但塞得下不等于**选得准**。这是本篇最大的未知,应在实施前用 `scripts/bench/` 补一组对照。
-- **schema.org 面向网页内容**(Recipe、JobPosting、Event),企业语料的"合同""审批"
- "供应商资质"它没有。它是好的冷启动底座,不是终点——0007 的增长回路仍然必要,
- 只是起点从 10 变成 1500。
-- **中文标签**:schema.org 与所有候选包都只有英文。我们 10 个种子是带中文名的
- (`produces` → 出品)。1500 个属性的中文化不可能手工做,也不该机器翻——
- `rdfs:label` 是模型读的令牌,译错比不译更糟。[0004](0004-language-and-localization.md)
- 定的分工在这里够不够用,待查。
-- **起点规模本身是个变量。** 0007 的死路里那条 Snowball 实测顺带证明了这点:
- 词表从 10 涨到 629,匹配行为会质变(捞回 49 次 → 18 次)。没人正面研究过
- "从 1500 个词起步"对采纳回路意味着什么——高频提议还会提议什么?
+| schema.org | 1078 KB | 1010 / 1521 (the shipped pack counts 1676) | general: people, organizations, products, events, creative works |
+| W3C Org | 82 KB | 13 / 34 | what `schema:Organization` lacks: Unit, Post, Membership, Role, tenure, reporting lines |
+| PROV-O | 110 KB | 62 (shipped: 49) / 69 | provenance: Activity, Agent, wasDerivedFrom |
+| FOAF | 43 KB | 12 / 62 | social relations; 21% overlap with schema.org and the least unique value — a candidate, not a default |
+| IOF Core | 394 KB | 294 / 75 | industrial manufacturing |
+
+Overlap by `key_from_iri()` (keys collide, not IRIs) is about 20 words in total: org ∩
+schema 6, foaf ∩ schema 15, prov ∩ schema 4. True synonyms are mapped (`foaf:Person ≡
+schema:Person`); same name with a different meaning stays as two (`org:role` is a post,
+`schema:role` a part in a creative work; `foaf:status` is chat presence, `schema:status` an
+order status).
+
+## Decisions
+
+1. **Multi-select at KB creation, no bundles.** Alignment is declared pairwise —
+ `foaf:Person ≡ schema:Person` holds whatever else is selected — so multi-select adds no
+ alignment cost, and fixed bundles are guesswork that never matches: fintech wants IOF
+ plus a future FIBO, a consultancy wants schema plus Org plus PROV. The UI shows each
+ pack's size and lets the user weigh it.
+2. **No import undo.** Three guards — `ON DELETE RESTRICT` (`0003_graph.sql`),
+ application-level counts in `ontology.rs`, and `NOT builtin` (now an empty condition) —
+ already mean a type with entities cannot be deleted. That is right: the inverse of "the
+ ontology guides, it does not enforce" — **knowledge can veto the deletion of ontology**.
+ What "wrong pack" needs is a bulk view ("this import created 294 classes, 12 in use, 282
+ empty — delete the empty ones"): simpler than undo, touches nothing that holds data. Not
+ built yet.
+3. **Static alignment table, no runtime inference.** About 20 rows by hand (22 built,
+ `SameAs` and `Rename`, e.g. `org:Role → org_role`), partly copied from upstream: W3C Org
+ declares its alignment with FOAF, PROV-O with FOAF and Dublin Core. No label similarity
+ or embedding matching — the packs are ours, five or six of them, and the overlaps can be
+ enumerated. An unbounded problem shrinks to a table, per 0001's criterion 6: governance
+ experience goes into the schema, not into hidden rules.
+
+## Dead ends
+
+- **Three fixed bundles** (general / provenance-compliance / industrial) and
+ **`undo_import`**, both in the first draft — rejected, see decisions 1 and 2.
+- **Showing overlap with the packs already selected** was planned; `2fa8d57` removed the
+ collision hint entirely. The alignment table handles the collisions, and reporting them
+ asks the user to rule on something with nothing to rule on.
+- **Packs that do not fit**: FIBO is modular, hundreds of files by catalog (finance is a
+ project, not a pack); Brick (1438 classes, 25 properties) and QUDT are taxonomies, not
+ relation ontologies; SAREF projects to 0 classes and 0 properties, its declaration form is
+ not covered yet; SNOMED CT needs a license.
+
+## Revisions
+
+- 2026-09-02: the alignment table grew three things not foreseen: a third disposition
+ `Aligned` (beside `Create` / `Update` / `KeyTaken`); direction sensitivity — rows are
+ (incoming IRI, occupying IRI), so install order decides which row hits, hence the visible
+ rule "check order is install order"; and a guard test that projects all five real packs
+ and checks every IRI, against a silent typo and upstream prefix changes (schema.org moved
+ from `http://` to `https://`).
+- 2026-09-02: a failing pack does not roll back the packs already installed — the ontology
+ is additive, and rollback is the undo this record refuses. And there is a start at **0**:
+ no pack is legal, entities carry `type_id` NULL ([0009](0009-no-type-is-a-type.md)).
+- 2026-09-02: "the ontology guides, it does not enforce" was half overturned. On a real
+ corpus (0012) the vocabulary caught things — 215 facts with predicates, all 41 relations
+ from packs — but not one declared direction was enforced: 102 of 130 checkable facts were
+ stored reversed; the fix bends to the signature at write time and leaves a trace. The cost
+ of packs is not prompt length but **choice**: many names are generic with narrow meanings
+ (`affectedBy` is a medical test, `competitor` a sports event), and picking by name or
+ vector will hit them.
+
+## Open questions
+
+- **Mixed-pack extraction accuracy is untested.** 0006 measured one ontology; all packs
+ together are about 2400 classes, and chunk retrieval recalls `org:role` and `schema:role`
+ side by side. Fitting the budget is not picking right. `run.mjs --packs` runs the real
+ cold-start path, but `truth/` still holds only pharma and tech.
+- **schema.org is web-facing** (Recipe, JobPosting, Event); enterprise "contract",
+ "approval", "supplier qualification" are absent. 0007's growth loop stays, starting from
+ 1500 instead of 10; the README turns "packs by industry" into an issue-template link.
+- **Chinese labels**, worse since the 14 Chinese-named seed relations left: a Chinese KB now
+ gets a purely English ontology, `ontology_lang = zh` affects only terms the LLM proposes
+ later, and nothing tells the user. 1500 properties cannot be translated by hand and should
+ not be machine-translated — `rdfs:label` is a token the model reads, and a wrong label is
+ worse than none.
+- **Starting scale is a variable.** 0007's Snowball run showed that growing the vocabulary
+ from 10 to 629 changes matching (49 recalls → 18). Nobody has studied what starting at
+ 1500 does to the adoption loop; `MIN_DOCS = 2` and `MIN_SIGNALS = 3` were never retuned.
diff --git a/docs/decisions/0009-no-type-is-a-type.md b/docs/decisions/0009-no-type-is-a-type.md
index b01c1fc7..9498662c 100644
--- a/docs/decisions/0009-no-type-is-a-type.md
+++ b/docs/decisions/0009-no-type-is-a-type.md
@@ -1,165 +1,98 @@
-# 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 分工是本文撞名论证的前提
-
-> 本篇没有 benchmark 数字。它是一次归类的更正——`concept` 一直被当成本体的一部分,
-> 而它其实是控制流的一部分。更正的依据是代码事实与一个撞名推演,都能重跑。
-
-## 起点:内置九个类,一个都不该留
-
-建库播种九个实体类(`graph.rs` 的 `DEFAULT_ENTITY_TYPES`):
-
-```
-person organization project metric dimension product event concept location
-```
-
-0008 论证过它们的通病——**零个带类型签名**,方向只能靠散文写。装了 schema.org 之后
-它们更是多余:`Person` / `Organization` / `Product` / `Event` / `Project` 会按 key 撞名
-被认领,等于内置那份从头到尾只是个占位。
-
-**`location` 是反例中的反例**:schema.org 里它叫 `Place`,key 对不上,于是不被认领,
-`City` / `AdministrativeArea` 挂到另建的 `place` 底下,跟 `location` 成了两棵树。
-一个我们自己起的名字,把整条地理子树割断了。
-
-`metric` / `dimension` 是语义层概念,schema.org 里确实没有——但代码里除测试外零引用,
-它们只是**播种的默认值**,不是机制。
-
-## `concept` 是控制流,不是词表
-
-八个是词表内容,可以换、可以不同意、可以被 schema.org 顶替。`concept` 不是:
-
-```rust
-// extraction.rs
-let concept_type = *type_ids.get("concept")
- .ok_or_else(|| anyhow!("Ontology missing the 'concept' type"))?;
-```
-
-它编码的是**「抽取器抽到了东西,但本体里没有对应的类」**。这个状态在任何本体下都存在,
-跟装了 schema.org 还是 FIBO 无关。没有它,抽出来的实体只能被丢掉——而 0001 的 P1
-整节就是在修「静默丢弃」。
-
-它承担三件事:白名单外类型的落点(同时 `record_miss` 作为本体扩展信号)、
-类型消解的取材范围(`entities_for_type_resolution(kb, DUMPING_GROUND, …)`)、
-实体合并时的类型调和(兜底侧让位给具体侧)。
-
-## 决定:不是给它改名,是让它不存在
-
-初稿拟保留哨兵行、改 key 为 `_unclassified`。**否掉**,但这个方案值得记下来,
-因为否掉它的理由才是本文的结论。
-
-改名方案能成立,是因为 `key_from_iri` 永远产不出前导下划线——第一个字符若非字母数字,
-`out.is_empty()` 为真,那个 `_` 不会被推入。实测:
-
-```
-skos:Concept -> "concept" ← 会撞
-http://x#_Concept -> "concept" ← 前导下划线被剥掉
-http://x#__unclass -> "unclassified"
-```
-
-所以 `_unclassified` 是导入够不到的命名空间。**这是算法保证,不是约定。**
-
-而且不改名会出真事故:哨兵行**没有 IRI**,而导入逻辑是「占位者没有 IRI 就认领它」——
-`skos:Concept` 会**接管哨兵**。于是所有"还没判出来"的实体一夜之间变成正经的
-`skos:Concept`。不是撞名被跳过,是语义被静默改写。SKOS 不是冷门词表。
-
-**但改名解决的只是撞名,解决不了泄漏。** 哨兵行必须从每一个消费者那里被过滤掉:
-本体页、抽取提示词、候选列表、图谱图例、导出、统计。漏掉任何一处,它就作为一个正经的类
-出现在那里,而且是静默出现。
-
-这正是本仓库反复警告的那类缺陷。`ontology_index.rs` 开篇:
-
-> **自愈,不挂钩子。**……漏挂一个钩子会悄悄烂掉,而对比原文不会。
-
-`_unclassified` 是**用命名约定替代类型保证**:它管得住导入撞名,管不住某个 SELECT
-忘了写 `WHERE key NOT LIKE '\_%'`。
-
-**所以 `entities.type_id` 改为可空。** 「没有类型」就是没有类型,不用一行假类冒充。
-
-初稿在这里写的是「NULL 忘不掉——SQL 与类型系统会当场让人知道」。**实现下来只对了一半,
-记在这儿因为错的那一半更要紧。**
-
-Rust 这边全中:每把一个字段改成 `Option`,编译器就把它的每一个消费点列出来,
-一处不漏(`graph.rs` 的取节点语句、审核项两侧、裁决提示词、聊天里的实体清单)。
-漏掉一个哨兵不会有任何提示,漏掉一个 `Option` 连编译都过不去。
-
-**SQL 这边不会。** `NULL <> uuid` 求值为 NULL 而不是 true,于是这样的条件
-
-```sql
-AND type_id <> $2 -- 认领 / 改类都靠它挑出"要变的那些行"
-```
-
-**一行都选不中**,而且不报错。踩到两处,都在最主要的那条路上:`adopt_proposed_types`
-(本体长出新类之后认领等着它的实体)与 `retype_entities`(类型消解裁决落库)。
-两处的输入几乎全是 `type_id IS NULL` 的实体——功能会静默空转,测试也照样绿。
-正解是 `IS DISTINCT FROM`。同一次实测(一个 `proposed_type='vehicle'` 的未分类实体):
-`<>` 选中 0 行,`IS DISTINCT FROM` 选中 1 行。
-
-所以这条决定的真实代价不是「90 处引用要改」,而是**26 处 SQL 里的每一个比较都要重看一遍**:
-类型系统数得清 Rust 那 64 处,数不到 SQL 里去。
-
-## 代价,逐条
-
-**90 处引用,26 处在 SQL 字符串里。** 逐个过完了,实际改动 14 个文件、
-`+316 / -369`——**删的比加的多**,因为内置那两张表(九个类与它们的中文措辞)
-连同播种循环一起没了。
-
-**两个唯一索引带 `type_id` 前缀:**
-
-```sql
-CREATE UNIQUE INDEX … ON entities (kb_id, type_id, lower(canonical_name))
- WHERE merged_into IS NULL;
-```
-
-Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被它拦住——两个都没类型的
-「张三」可以并存。
-
-**这是要的行为,不是缺陷**:该索引本来的意图就是「同类同名允许重复」(0001 P0 论证过
-两个张伟必须能分开存放,宁分勿合)。未分类时我们对它们是不是同一个东西**知道得更少**,
-更没有理由合并。写在这里是因为半年后有人看到「未分类的同名实体可以重复」会以为是 bug。
-
-**`CONFUSABLE_TYPE_KEYS` 不受影响。** 它按 key 查(`["organization","project","product"]`),
-而这些 key 装了 schema.org 之后仍然存在——只是来源从内置播种变成了词表导入。
-没装包的库里它们不存在,于是那一档永不命中,所有跨类型同名判 `Disjoint`(完全分开)。
-**那是变严不是变松**,不会造成错误合并。
-
-它的正解仍然是注释里写的那条——等 `disjointWith` 落库后改从本体读,即 0008 的 R0 第三阶段。
-本文不动它。
-
-〔**2026-09-02**:前提已经成立,动作仍未做。`owl:disjointWith` 有表(`entity_type_disjoint`)、有导入、有编辑接口,消费者只有 R0 的本体自检;`CONFUSABLE_TYPE_KEYS` 仍是硬编码三个 key,且它上面的注释还停留在旧世界。〕
-
-## 空白库
-
-删光之后,不选任何包的库是**真的空**:抽出来的实体 `type_id` 为 NULL,事实照常落库,
-证据链照常。之后装一个包再跑一次类型消解,实体会被重新分配——
-`entities_for_type_resolution` 本来就是取「落在兜底上的」,改成取 `type_id IS NULL` 即可。
-
-**所以"先建库后建模"是受支持的路径,不是将就。**
-
-〔落地时多了一列本文没写的 `entities.type_source`(extracted / human / inferred):0009 让 `type_id IS NULL` 同时承载「还没判」和「人判了就是没有」,这一列把两者分开,也是类型消解取材的过滤条件(0001 P4a)。另有 `specific_type` 与 `proposed_type` 分列——前者是模型对这个实体的自由说法,专供类型消解。〕
-
-配套:schema.org 在建库对话框里默认勾选,可反选。这在 45 秒的时候不成立,
-在 0.42 秒的时候成立(导入改批量插入之后的实测)。
-
-## 落地时定下的两件事
-
-**图谱怎么画它。** 取节点的语句从 `JOIN entity_types` 改成 `LEFT JOIN`——内连接会让
-未分类实体**整个从图上消失**,事实还在库里却查无此人,是最难发现的一种数据丢失。
-`key` 与 `label` 留 NULL,**颜色和形状给缺省值**(灰色圆点):前者是身份,没有就该说没有;
-后者是画布必须拿到的东西,编不出来就没法渲染。同一处理也用在审核项两侧。
-
-**给它定类不算「跨轴」。** 类型消解把「选中的类不在现类子树里」判为重新分类而非精化,
-一律进人工。未分类实体身上**没有一个抽取判断要被推翻**,第一次定类是补齐;
-若也判跨轴,删掉哨兵的代价就是每个实体都要人看一眼,整条自动化直接废掉。
-配套地 `entity_retypes.from_type_id` 改为可空——最常见的一次改类正是「从没有类到有类」,
-而那张表是撤销的唯一依据;非空的话第一次定类就写不进账,那批改动不可撤。
-
-## 开放问题
-
-- **未分类实体的消解**:画像里没有类型这一维,`classify_type_drift` 少一个判据。
- 两个都没类型的同名实体,今天按 `Recall` 走画像相似度——够不够,没测过。
-- **`metric` / `dimension` 的去处**:语义层要用,而没有任何公开词表提供它们。
- 是让用户自己建,还是我们出一个「Utopia 语义层」包?后者会把内置本体从代码搬到包里,
- 性质完全不同——那是可选、带 IRI、可被替换的。〔**仍未答,且有了可见代价**:映射探查按 `entity_types.key IN ('metric','dimension')` 找类型,找不到就 `continue`——不装包、也没人手建这两个类的库里,探查会**静默产出零条**。〕
+# 0009 · An undecided type stays empty
+
+- **Status**: Implemented · `entities.type_id` and `entity_retypes.from_type_id` are
+ nullable; the nine builtin classes and the seeding function left with the seed relations
+ (#110 / #125 / #128 / [0011](0011-a-mapping-is-not-a-fact.md)) · `owl:disjointWith` is
+ stored but resolution still reads the hard-coded `CONFUSABLE_TYPE_KEYS`; since #226 same-name
+ entities of kin classes (ancestor, descendant or a shared non-root ancestor) go to Review · `metric` /
+ `dimension` are created on demand by mapping exploration (#231); a semantic-layer pack is
+ still planned
+- **Written**: 2026-08-30 · condensed into English 2026-09-03
+- **Related**: [0008](0008-ontology-packs-as-cold-start.md) makes a real vocabulary the
+ optional start; [0001](0001-ontology-import-and-governance.md) IRI/key split behind the
+ collision argument; [0010](0010-no-relation-is-no-relation.md) the twin on the relation
+ side
+
+## The problem
+
+A new KB used to seed nine entity classes: `person organization project metric dimension
+product event concept location`. None carried a signature (0008), and once schema.org is
+installed `Person` / `Organization` / `Product` / `Event` / `Project` are claimed by key, so
+the builtin set was a placeholder. `location` was worse: schema.org calls it `Place`, the
+keys differ, so `City` / `AdministrativeArea` hung under a separately created `place` — a
+name of our own cut the geographic subtree in two.
+
+`concept` was different: it was **control flow**. `extraction.rs` required it ("Ontology
+missing the 'concept' type") as the landing place for entities whose type is not in the
+whitelist — a state that exists under any ontology — and as the candidate pool for type
+resolution (`entities_for_type_resolution(kb, DUMPING_GROUND, …)`). A "not decided yet" sat
+in the ontology as a class, as if someone had decided it.
+
+## Decisions
+
+1. **Remove all nine classes; a KB without packs is truly empty.** Extracted entities get
+ `type_id` NULL, facts and evidence land as usual; install a pack later, rerun type
+ resolution, and they are assigned — `entities_for_type_resolution` now takes `type_id IS
+ NULL`. "Build the KB first, model later" is a supported path; schema.org is pre-checked
+ in the create dialog. Landing added `entities.type_source` (extracted / human / inferred)
+ to separate "not decided" from "a human decided there is none".
+2. **`entities.type_id` becomes nullable, no sentinel row.** The Rust compiler lists every
+ consumer of the new `Option`. SQL does not: `NULL <> uuid` evaluates to NULL, so `AND
+ type_id <> $2` selects **no rows and raises nothing**. Hit twice on the main path —
+ `adopt_proposed_types` and `retype_entities`, whose inputs are almost all `type_id IS
+ NULL` — running silently empty with green tests. The fix is `IS DISTINCT FROM` (measured:
+ `<>` selects 0 rows, `IS DISTINCT FROM` 1). The real cost was rereading every comparison
+ in 26 SQL strings; the change touched 14 files, `+316 / -369`.
+3. **Untyped same-name entities may coexist.** The unique index `(kb_id, type_id,
+ lower(canonical_name)) WHERE merged_into IS NULL` does not stop two untyped "张三", because
+ NULL ≠ NULL. Intended: the index allows same name across types (0001 P0: two 张伟 must be
+ storable apart), and untyped we know even less, so there is even less reason to merge.
+ Recorded so nobody files it as a bug.
+4. **Drawing it.** The node query switched from `JOIN entity_types` to `LEFT JOIN` — an
+ inner join makes an untyped entity vanish from the graph while its facts stay, the
+ hardest data loss to notice. `key` and `label` stay NULL; color and shape get defaults
+ (gray dot: the canvas must receive something). Review items likewise.
+5. **First typing is a completion.** Type resolution treats "chosen class outside the
+ current subtree" as reclassification and sends it to a human; an untyped entity has no
+ extraction judgment to overturn, and judging it cross-axis would put every entity in
+ front of a person. `entity_retypes.from_type_id` is nullable accordingly — the commonest
+ retype is none → some, and that table is the only basis for undo.
+6. **`CONFUSABLE_TYPE_KEYS` stays** (`["organization","project","product"]`): the keys still
+ exist after schema.org, from import rather than seeding; without packs the tier never
+ hits and every cross-type same-name pair is `Disjoint` — stricter, no wrong merges. The
+ proper fix is to read `disjointWith` from the ontology.
+
+## Dead ends
+
+- **Keep the sentinel, rename its key to `_unclassified`** (first draft). It would have
+ held: `key_from_iri` never emits a leading underscore (measured: `skos:Concept → concept`,
+ `http://x#_Concept → concept`, `http://x#__unclass → unclassified`), so the namespace is
+ unreachable by import. And a rename was necessary: the sentinel had no IRI, import claims
+ IRI-less placeholders, so `skos:Concept` would take over the sentinel and every undecided
+ entity would silently become a real `skos:Concept`. But renaming fixes collision, not
+ **leakage**: the sentinel must be filtered from every consumer — ontology page, prompt,
+ candidate lists, legend, export, statistics — and one forgotten `WHERE key NOT LIKE '\_%'`
+ fails silently. A naming convention in place of a type guarantee, the defect class
+ `ontology_index.rs` warns about ("self-heal, don't hang hooks").
+- **"NULL cannot be forgotten — SQL and the type system will tell you."** Half right; the
+ SQL half is decision 2.
+
+## Revisions
+
+- 2026-09-02: `owl:disjointWith` now has a table (`entity_type_disjoint`), import and an
+ edit endpoint, but its only consumer is R0's ontology self-check; `CONFUSABLE_TYPE_KEYS`
+ is still three hard-coded keys (0016 B3).
+- 2026-09-02: `metric` / `dimension` had a visible cost — mapping exploration looked up
+ `entity_types.key IN ('metric','dimension')` and `continue`d when missing, so a KB without
+ those classes silently produced zero mappings. 2026-09-03: exploration now creates both as
+ builtin types before exploring (#231); a semantic-layer pack with IRIs is still planned
+ (0016 D2).
+
+## Open questions
+
+- **Resolving untyped entities.** The profile has no type dimension, so
+ `classify_type_drift` lacks one criterion. Two untyped same-name entities go `Recall` and
+ rely on profile similarity; whether that is enough is untested.
+- **Where `metric` / `dimension` belong.** Today they are builtin-on-demand. A "Utopia
+ semantic layer" pack would move the last builtin classes out of code into something
+ optional, with IRIs, replaceable (0016 D2).
diff --git a/docs/decisions/0010-no-relation-is-no-relation.md b/docs/decisions/0010-no-relation-is-no-relation.md
index 219981f1..0b038631 100644
--- a/docs/decisions/0010-no-relation-is-no-relation.md
+++ b/docs/decisions/0010-no-relation-is-no-relation.md
@@ -1,170 +1,99 @@
-# 「说不出是什么关系」不该是一个关系
-
-**状态**:已实施 · `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`——
-一个"本体里没有对应关系"被写成了一个关系。
-
-## 它是控制流,不是词汇
-
-`related_to` 编码的是**抽取器抽到了一条边、但本体里没有对应的关系**。
-那是一个程序状态。它却以 `builtin` 关系的身份躺在 `relation_types` 里,
-在本体页上跟 `acquired`、`works_at` 并排列着,像是有人决定过"这两个东西
-之间的关系就叫有关联"。没有人这样决定过。
-
-代价不是抽象的。删之前量过:某个 348 块的库里 533 条事实挂在它上面,
-界面上**全部显示"有关联"**四个字。而这 533 条**每一条都带着原文说法**
-(`fact_evidence.proposed_predicate`),一条不落——原意一直在库里,
-被那行假词汇盖着。
-
-## 删掉之后信息更多
-
-同一份数据,读者看得见的从一个词变成五百多个词。真实语料上的验证
-(14706 条事实的库,见下):图上 93 条边过去统统是"有关联",
-现在各自显示 `placed_pressure_on` / `agreed_to_resign` / `countersued` /
-`revived_legal_action` / `license_from`。
-
-一条事实带多种说法的只占 3.0%(16/533),所以"显示哪一个"不是拦路虎:
-取出现最多的那个,出现次数相同时按字典序——与 `predicate_match::merge_key`
-挑规范 key 同一个规矩,且**确定**,于是同一条边在图上、实体面板、
-变更历史里叫同一个名字。
-
-做成 SQL 函数 `fact_surface_predicate(uuid)` 而不是在每条读查询里塞子查询:
-读事实的路径有八条,八份同样的 SQL 迟早分叉,而分叉在这里的后果正是
-"同一条边在不同页面上叫不同的名字"。
-
-**有 420 条例外,全是历史遗留。** 5934 条兜底事实里 420 条拿不出原文说法,
-且**全部**来自 `Industry Corpus`(275) 与 `General`(145) 两个最早的库——
-那时 `add_evidence` 还没无条件记录 `proposed_predicate`。它们改完显示成空,
-但本来显示的是"有关联",信息量同样是零,没有变糟。
-
-## 推翻了 0001 里的一句话
-
-[0001](0001-ontology-import-and-governance.md) 第 441 行写过:
-
-> **`related_to` 是诚实的含糊,猜错则是自信的错误**
-
-前半句错了,后半句仍然对。**保持"我不知道"确实比猜一个具体关系诚实**——
-这一点 0001 是对的,也是这篇没有推翻的部分。错在把这份诚实实现成了
-**本体里的一个词**。一个界面上显示为"有关联"的关系不是含糊,是一句**断言**:
-它声称这两个东西之间存在一种叫"有关联"的联系。真正诚实的表达是空——
-连同旁边那句"原文说的是 `acquired`"。
-
-同一篇第 460 行的括号"(保留在本体中当代码层兜底)"也随之作废:
-兜底现在发生在**读的时候**,不是写的时候。
-
-## 二十条内连接,编译器一条都看不见
-
-`predicate_id` 改成可空之后,读路径上每一条 `JOIN relation_types`
-都变成了一个**静默的过滤器**——内连接丢掉 NULL 行不报错、不告警,
-`cargo check` 和 clippy 一个字都不说。这与 0009 的 `NULL <> uuid`
-是同一个陷阱的两副面孔:三值逻辑下"没有值"被当成"不匹配"。
-
-二十条里 **11 条改成 `LEFT JOIN` + 回落**,6 条内连接**本来就对**
-(4 条按 `r.key` 过滤,NULL 谓词本就不可能命中;2 条要读
-`functional`/`temporal`,没有谓词的事实本就不该参与时态推理)。
-
-漏改的三处全部由数据库抓出来,没有一处是编译器发现的:
-
-| 漏掉的 | 症状 | 谁抓到的 |
-|---|---|---|
-| `document_extractions` 的 `r.label` 没包 COALESCE | 运行时解码失败 | 事后逐条核对 |
-| `entity_history` / `graph_changes` 外层 `FROM ev`(CTE)里写了 `f.id` | `missing FROM-clause entry for table "f"` | 新增的连库测试 |
-| `proposed_predicates` 去掉 `rt` 的连接后,示例子查询还引着 `rt.id` | `missing FROM-clause entry for table "rt"` | 既有的 `proposal_counts` 测试 |
-
-还有两处占位符错位(去掉 `$2` 后 `$3` 没降号),也是测试抓的。
-
-**这是"SQL 对编译器隐身"在本仓库的第 8 次。** 结论没有变,只是又贵了一次:
-碰 SQL 字符串的改动,连库测试不是加分项。
-
-新增 [`no_predicate_still_shows.rs`](../../crates/utopia-store/tests/no_predicate_still_shows.rs)
-守这条线:造一条没有谓词的事实,要求每条读路径都还能看见它。
-把任何一条 `LEFT JOIN relation_types` 改回 `JOIN`,它必须红——
-两个对照组都验过(改回内连接 → 断言失败;把 `ev.id` 写回 `f.id` → SQL 报错)。
-
-## 界面上要看得出区别
-
-一个词来自本体、还是来自原文,**读者必须能分辨**——否则等于用另一种方式
-再撒一次谎。所以行上带 `inferred` 标记:
-
-- 图的边:本体外的关系用更淡的灰,不与词表里的关系一样重
-- 实体面板 / 文档产出:悬停说明"本体里没有这个关系,这是原文的说法"
-- 两者都拿不出的(那 420 条):斜体显示"说不出是什么关系",**不编一个词**
-
-## 端到端验证
-
-在 `utopia` 的完整克隆上跑(14706 条事实,5934 条挂在 `related_to` 上):
-
-| 环节 | 结果 |
-|---|---|
-| 全新空库跑迁移 | 0052 应用成功,`related_to` 为 0 |
-| 真实数据跑迁移 | 5934 条转空,其中 5514 条取回原文说法 |
-| 图总览 | 457 条边:本体关系 364,原文说法 93,说不出 0 |
-| 实体面板(OpenAI,252 条事实) | 64 条显示原文说法,`inferred` 为真的一律 `temporal` 为空 |
-| 文档产出(509 条) | 134 条显示原文说法 |
-| 消解画像(去重页) | `offered_to_employ` / `hiring_effort` / `feared_retaliation` 等原文说法 |
-| 驳回一条无谓词事实 | 决策台账留下自包含快照 `Southeast Memphis — has_higher → risk of developing cancer` |
-
-最后一行是内连接**最贵**的那处:`fact_snapshot` 走内连接时返回 `None`,
-这条驳回在台账上将没有任何记录——而台账的全部意义就是事实删了它还在。
-
-## 数据直接改,不做搬迁
-
-现在库里全是测试数据,产品未发布。这句话在这里成立,
-换成用户跑了半年的库就不成立了——那时 0001 第 464 行那条
-"只对新抽取生效,存量要重建"仍然适用。
-
-## 顺带清掉的
-
-- `graph::FALLBACK_RELATION_KEY` 常量与两处 `FALLBACK_RELATION_MISSING` 分支
-- `extraction_drops` 里"本体里连兜底关系都没有 → 整条消失"这个掉落原因
- (见 0001 第 99 行提到的那个坑,现在不可能再发生)
-- 代码与文档里"兜底谓词""兜底关系"的措辞
-
-## 修订:删了数据,没删代码,七分钟后它长回来了
-
-**状态**:已实施 · 与上一节同一篇的直接后续
-
-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
-
-**比"没删干净"更糟的是第二层。** 0052 同时删掉了抽取提示词里那条排除过滤,
-理由写在代码注释里:"现在它连行都没有了,逃生舱和'记得别列它'这两件事一起消失。"
-前半句是错的,于是后半句造成了倒退:`related_to` 不但活着,而且**第一次被列进
-提示词给模型看**。0001 量过这件事的代价——359 次使用里 321 次是模型从清单上挑的,
-只有约 38 次是代码降级。逃生舱一旦摆上台面,模型就不再去说原文究竟说了什么。
-
-**教训不是"要记得改两处",是"这两处必须同时改,只改一处比都不改更糟"。**
-删数据不删词汇 = 词汇长回来;删排除过滤不删词汇 = 把它递给模型。
-
-### 而守这条线的断言当时是空的
-
-0052 里有一条自认为的对照组:
-
-```sql
-SELECT count(*) FROM relation_types WHERE key = 'related_to' AND builtin
-```
-
-它通过了,因为**测试夹具是裸 SQL 建的库,从没调用过 `ensure_default_ontology`**——
-种子一次都没种下,断言在一片空地上成立。这是本会话第二次踩"空测试"
-(第一次是抽取守卫那条:`ctx = None` 根本到不了要守的分支)。
-
-现在的版本先把种子种下去再查,并且验过对照:把 `related_to` 加回种子表,测试变红。
-
-另外两个连带修掉的:全库计数的断言会被并行测试污染(改成按 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'` 连接现在恒匹配零行。该清。〕
+# 0010 · An unnamed relation stays empty
+
+- **Status**: Implemented · `facts.predicate_id` is nullable, `related_to` is gone, display
+ falls back to the source's wording through `fact_surface_predicate(uuid)`, guarded by
+ `no_predicate_still_shows.rs` · both `mapped_to` follow-ups done with
+ [0011](0011-a-mapping-is-not-a-fact.md) (#126); the seed table and
+ `ensure_default_ontology` left with #128 · the two pieces of dead code noted 2026-09-02 are
+ cleared
+- **Written**: 2026-08-30 (undated in the original; the day its migration ran) · condensed
+ into English 2026-09-03
+- **Related**: [0009](0009-no-type-is-a-type.md) the twin on the type side;
+ [0001](0001-ontology-import-and-governance.md) holds the sentence this record overturns;
+ [0011](0011-a-mapping-is-not-a-fact.md) takes `mapped_to` the rest of the way
+
+## The problem
+
+`related_to` encoded "the extractor found an edge but the ontology has no matching relation"
+— a program state. Yet it sat in `relation_types` as a `builtin` relation, listed on the
+ontology page beside `acquired` and `works_at`, as though someone had decided the relation
+between the two things is called "related". Nobody had.
+
+The cost was measured before deleting it: in one 348-chunk KB, 533 facts hung on it and
+every one displayed as 有关联, while every one also carried the source's wording in
+`fact_evidence.proposed_predicate`. The meaning was in the database all along, covered by a
+fake vocabulary word.
+
+## Decisions
+
+1. **`facts.predicate_id` becomes nullable and `related_to` is deleted.** The reader sees
+ more: on a real corpus (14,706 facts, 5,934 on `related_to`), 93 graph edges that all
+ read "related" now read `placed_pressure_on` / `agreed_to_resign` / `countersued` /
+ `revived_legal_action` / `license_from`.
+2. **Display falls back to the source's wording through one SQL function,
+ `fact_surface_predicate(uuid)`.** The most frequent wording wins, ties by lexical order —
+ the rule `predicate_match::merge_key` uses, and deterministic, so one edge has one name
+ on the graph, in the panel and in the history. Only 3.0% of facts (16 of 533) had more
+ than one wording. One function rather than a subquery in each of the eight read paths:
+ eight copies diverge, and divergence here means different names on different pages.
+3. **The reader must see where a word comes from**, or the lie is retold another way. Rows
+ carry `inferred`: edges outside the ontology are drawn in a lighter gray; the panel and
+ document output say on hover "not in the ontology; this is the source's wording"; facts
+ with neither show an italic "unnamed relation" — never a made-up word.
+4. **Data changed in place, no migration path.** The database held test data before release.
+ Once users have run for half a year, 0001's "only new extractions; rebuild the backlog"
+ applies again.
+5. **`mapped_to` follows.** Only `related_to` was excluded from the prompt, so the model
+ used `mapped_to` (entity → data-source schema) on entity↔entity pairs 41 times. It leaves
+ the prompt, then `relation_types` altogether ([0011](0011-a-mapping-is-not-a-fact.md)):
+ the same error, control flow written as vocabulary. The `FALLBACK_RELATION_*` constant
+ and branches, the `extraction_drops` reason "no fallback relation", and the "fallback
+ predicate" wording went with it.
+
+## Dead ends
+
+- **0001's sentence "`related_to` is honest vagueness; a wrong guess is confident error."**
+ The second half stands, the first is wrong. Staying at "I don't know" is more honest than
+ guessing — but implementing that honesty as a word in the ontology turned it into an
+ **assertion**: a relation displayed as "related" claims such a relation exists. The honest
+ expression is empty, next to "the source said `acquired`". 0001's aside "(kept in the
+ ontology as the code-level fallback)" is void: the fallback now happens at read time.
+- **Twenty inner joins the compiler cannot see.** Once the column is nullable, every `JOIN
+ relation_types` on a read path is a silent filter; `cargo check` and clippy say nothing —
+ the same three-valued trap as 0009's `NULL <> uuid`. Eleven became `LEFT JOIN` plus
+ fallback; six were already right (four filter by `r.key`, two read `functional` /
+ `temporal`). Three misses were caught by the database and none by the compiler (an
+ `r.label` without COALESCE, an `f.id` referenced outside its CTE, a stale `rt.id`), plus
+ two mis-numbered placeholders — the eighth time "SQL is invisible to the compiler" in this
+ repository, so DB tests are not optional when SQL strings change. The most expensive miss:
+ `fact_snapshot` through an inner join returned `None`, so rejecting a predicate-less fact
+ would have left no ledger entry — and the ledger exists so the record survives the fact.
+- **420 legacy exceptions.** Of 5,934 fallback facts, 420 have no source wording, all from
+ the two oldest KBs (`Industry Corpus` 275, `General` 145), before `add_evidence` recorded
+ `proposed_predicate` unconditionally. They now display empty; they used to display
+ "related" — zero information either way.
+- **End-to-end on the full clone**: 5,934 facts go NULL and 5,514 recover their wording;
+ graph 457 edges — 364 ontology, 93 wording, 0 unnamed; rejecting a predicate-less fact
+ leaves a self-contained snapshot in the decision ledger. `no_predicate_still_shows.rs`
+ guards the line: a fact with no predicate must be visible on every read path, and turning
+ any `LEFT JOIN relation_types` back into `JOIN` makes it red (both controls verified).
+
+## Revisions
+
+- 2026-08-30: we deleted the data, not the code, and it grew back in seven minutes.
+ Migration 0052 deleted the `relation_types` **row**; the seed was code
+ (`DEFAULT_RELATION_TYPES`), and `ensure_default_ontology` ran at KB creation, on the
+ ontology page and at every extraction — 0052 applied at 17:54, `bench demo-autoextend`
+ re-created a `builtin=true` row at 18:01. Worse, 0052 also dropped the prompt's exclusion
+ filter on the premise "no row now, so the escape hatch and the reminder disappear
+ together"; the premise was false, so `related_to` was listed in the prompt for the first
+ time — and 0001 had measured that of 359 uses, 321 were the model picking from the list.
+ The two must change together; changing one is worse than neither. (#128 removed the
+ function and the seed table; regrowth is now impossible.)
+- 2026-08-30: the guard assertion was empty. `SELECT count(*) FROM relation_types WHERE key
+ = 'related_to' AND builtin` passed because the fixture built the KB with raw SQL and never
+ called `ensure_default_ontology` — asserting on bare ground. The test now seeds first, and
+ the control was verified (adding `related_to` back to the seed table turns it red).
+- 2026-09-02: two pieces of dead code. `graph.rs` `confirmed_mappings()` had zero callers
+ (chat reads `mappings::confirmed`), and the `r.key = 'mapped_to'` join in `confirm_fact`
+ matched zero rows. Both removed since (0016 A3).
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 5a5b3b13..5e67c2b7 100644
--- a/docs/decisions/0011-a-mapping-is-not-a-fact.md
+++ b/docs/decisions/0011-a-mapping-is-not-a-fact.md
@@ -1,137 +1,89 @@
-# 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` 删掉其余八条种子关系——本文是同一条线的最后一段:
- **本体里只该剩下词表**
-
-> 本篇是拆一个当初有意为之的复用。原设计不是疏忽,它买到了三样具体的东西,
-> 所以这里先把买到的列清楚,再说为什么仍然要拆。
-
-## 现状
-
-问数语义层把「业务概念 → 数据资产定义」存成一条事实:
-
-```
-主语 = 概念实体(Metric / Dimension)
-谓词 = mapped_to ← relation_types 里的一行,与 works_at 并列
-宾语 = object_value JSON { source, table?, expr?, sql?, unit?, summary? }
-置信 = 0.6 提议 / 1.0 已确认
-```
-
-整条路:
-
-```
-探索任务读挂载源 schema → LLM 提议 → 0.6 置信的 mapped_to 事实
- ↓ review_routes 的 low_confidence_facts 按 <0.75 捞起来
-人在 Review 页 Confirm → confirm_fact 把 confidence 改成 1.0
- ↓ chat.rs 读 confirmed_mappings(≥0.75)
-注入问数 system prompt
-```
-
-## 复用买到了什么
-
-**一、Review 流零新 UI。** 提议以低置信落库,自动流进「低置信事实」那一档,
-Confirm / Reject 用的是现成的按钮。`mappings.rs` 的模块注释把这一点写成了设计
-意图,不是事后总结。
-
-**二、双时态历史。** 口径改过没有、什么时候改的、改之前是什么——账本本来就答得出来。
-
-**三、证据链。** 与其它事实同构,实体历史页面直接就能展示。
-
-这三样都是真的,拆开就要重做。
-
-## 为什么仍然要拆
-
-### 1. 它不是关于世界的断言
-
-本体回答「世界上有什么、它们之间是什么关系」。`mapped_to` 回答的是
-「**这个数在我们的数据库里怎么算出来**」——它是实现细节,跟 `works_at`
-不是一类东西。
-
-这一条与 0009 删掉内置实体类、0010 删掉 `related_to` 是同一句话的三次应用:
-**代码层面的机制不该混进词表**。0009 说的是「`concept` 是控制流不是词表」,
-这里是「`mapped_to` 是配置不是词表」。
-
-### 2. 它出现在不该出现的地方
-
-`relation_types` 里的一行意味着:本体页把它列成一条关系、抽取提示词把它端给
-模型、本体规模统计把它算进去、`#125` 之后它还是**唯一一条种子关系**——
-一个新库开局本体里只有它,而它跟用户要建的知识图谱毫无关系。
-
-### 3. 「确认」这个动作已经在违反账本的地基
-
-```rust
-// graph.rs — confirm_fact
-UPDATE facts SET confidence = 1.0 WHERE id = $1
-```
-
-账本是 append-only 的:纠正一条事实要插新行 + `supersedes` 旧行,因为
-**认知变更本身是信息**(0001 P0 的立论)。而确认口径是**原地 UPDATE**——
-它改的不是「我们对世界的认知」,是「这条配置生效了没有」。
-
-一个需要原地改状态的东西住在一张不许原地改的表里,这本身就是它不合身的证据。
-今天没出事,是因为口径确认的语义恰好简单到用一个浮点数就能表达。
-
-### 4. 形状对不上
-
-一条映射真正的字段是 `source / table / expr / sql / unit / summary`,
-现在全塞在 `object_value` 这个 JSONB 里。于是:
-
-- 查不动。「哪些概念映射到了 orders 这张表」要扒 JSON
-- 约束不了。同一个概念同一个源应该只有一条,而唯一性粒度
- `(概念, 源)` 藏在 `object_value` 内部,数据库管不到——今天靠确认流程
- 显式闭合,靠的是流程不是约束
-- 说不清。`mapped_to` 的 range 是什么?没有答案,因为宾语不是实体也不是
- 某个数据类型,是一份配置
-
-## 决定
-
-**单独一张 `concept_mappings` 表。** 概念(entity id)→ 数据资产定义,
-字段展开成列,唯一性 `(kb_id, concept_id, source)` 由主键管。
-
-`mapped_to` 从 `relation_types` 退场,`DEFAULT_RELATION_TYPES` 随之清空——
-建库不再播种任何关系,本体从第一天起就只有用户自己导入的词表。
-
-## 要重做的三样,逐条
-
-**Review 流**:不再借低置信事实那一档。语义层的待确认项是另一种东西
-(配置提议,不是知识断言),Review 页给它一个自己的分组。这与 0002 R0
-的一致性检查落在同一处——那一档也是「引擎提议、人裁决」。
-
-**历史**:表上自带 `created_at / confirmed_at / confirmed_by`,加一张
-`concept_mapping_revisions` 记口径演变。**不做双时态**——口径没有「有效时间」
-与「记录时间」两条轴,它只有「什么时候生效的」一条。硬套账本那套是把复杂度
-搬过来而不是解决它。
-
-**证据链**:映射的证据是「LLM 读了哪张表的 schema 提议的」,与事实的
-「哪一句原文」不是一回事,本来就该分开记。
-
-## 代价,写在前面
-
-- **一次数据迁移**:现有的 `mapped_to` 事实要搬进新表。库里是 mock 数据,
- 所以这一刀不写迁移,直接换(与 `#125` 同)。真发布之后就没有这个便利了。
-- **三处接线要改**:`mappings.rs` 写入、`review_routes` 读取、`chat.rs` 注入。
-- **短期内多一段 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 表之后要显式设计。问数回溯历史报表时会撞上它。〔**已答**:`revise` + `concept_mapping_revisions` + History 抽屉。「上季度的口径」能从 revisions 里读出来,问数是否据此回溯仍未做。〕
-- **多源同概念**:`(kb_id, concept_id, source)` 允许同一个概念在不同源上有
- 不同定义,这是有意的(0010 之前的注释就这么写)。但问数该用哪一条?
- 今天靠 prompt 里全给、让模型挑。这条不因本篇改变,但搬表之后更容易加规则。〔仍是全给(上限 30 条)由模型挑。〕
+# 0011 · A mapping is configuration
+
+- **Status**: Implemented · `concept_mappings` table and wiring (#126, the same commit as
+ this record), a standalone Data Mappings page (#140), moved out of the Review queue (#148)
+ · of the three things to rebuild, the Review flow and history are done, the evidence chain
+ is not · one of two open questions answered (2026-09-02 check)
+- **Written**: 2026-08-31 · condensed into English 2026-09-03
+- **Related**: [0009](0009-no-type-is-a-type.md) removes the builtin entity classes,
+ [0010](0010-no-relation-is-no-relation.md) the fallback relation, #125 the other eight
+ seed relations — this record is the last step on that line: **only vocabulary remains in
+ the ontology**
+
+## The problem
+
+The semantic layer stored "business concept → data asset definition" as a fact: subject a
+concept entity (Metric / Dimension), predicate `mapped_to` — a row in `relation_types`
+beside `works_at` — object an `object_value` JSON `{ source, table?, expr?, sql?, unit?,
+summary? }`, confidence 0.6 proposed / 1.0 confirmed. `review_routes` picked it up as a
+low-confidence fact (< 0.75), Confirm set 1.0, and `chat.rs` read `confirmed_mappings` (≥
+0.75) into the query prompt.
+
+The reuse was deliberate and bought three real things: a Review flow with zero new UI,
+bitemporal history for free, and an evidence chain like any other fact's. Splitting means
+rebuilding all three.
+
+## Dead ends
+
+- **Keep the mapping as a fact.** Rejected on four grounds:
+ 1. It is not an assertion about the world. The ontology answers "what exists and how
+ things relate"; `mapped_to` answers "how this number is computed in our database". The
+ third application of one sentence: 0009 (`concept` is control flow), 0010 (`related_to`
+ is control flow), here `mapped_to` is configuration.
+ 2. It appeared where it should not: the ontology page listed it, the extraction prompt
+ offered it, ontology size counted it, and after #125 it was the **only** seed relation
+ — a new KB's ontology held exactly one thing, unrelated to the graph the user wants.
+ 3. "Confirm" already broke the ledger's foundation: `UPDATE facts SET confidence = 1.0` in
+ an append-only table where a correction inserts a new row with `supersedes`, because
+ the change of belief is itself information (0001 P0). Confirming changes not our belief
+ but whether a configuration is in effect; it only worked because that state happened to
+ fit in one float.
+ 4. The shape was wrong. The real fields `source / table / expr / sql / unit / summary` sat
+ inside JSONB: unqueryable ("which concepts map to `orders`"), unconstrainable
+ (uniqueness per (concept, source) hidden in JSON, closed by process rather than by the
+ database), unexplainable (`mapped_to` has no range — the object is neither an entity
+ nor a datatype).
+- **Bitemporal history for the new table.** A definition has one axis, "when it took
+ effect"; forcing the ledger's two axes would move complexity rather than solve it.
+
+## Decisions
+
+1. **Its own table, `concept_mappings`**: concept entity id → definition, fields as columns,
+ `UNIQUE (kb_id, concept_id, source)` (a constraint; `id` is the primary key), plus a
+ `derived` column for derived metrics. `mapped_to` leaves `relation_types`,
+ `DEFAULT_RELATION_TYPES` empties, and a new KB seeds no relations at all.
+2. **Review without borrowing the low-confidence tier.** A proposal is configuration, not a
+ knowledge assertion. Built first as its own Review group, then (#140) as a standalone
+ Data Mappings page, with Review keeping only a count and a link (#148: a mapping is
+ neither a queue nor a history). The approval endpoints stay in `review_routes`, where the
+ `mapping.decided` audit stream lives.
+3. **History as revisions.** `created_at / confirmed_at / confirmed_by` on the row, full
+ snapshots in `concept_mapping_revisions` written by `revise()`, and a History drawer on
+ the page.
+4. **Evidence recorded separately** — a mapping's evidence is "which table's schema the LLM
+ read", not "which sentence". Not built: `concept_mappings` has no such column, and
+ exploration proposals leave no evidence.
+5. **No data migration.** Mock data only; the old `mapped_to` facts stay in the ledger
+ unread (as with #125). After release this convenience is gone.
+6. **Two things that landed unplanned.** `propose()` uses `ON CONFLICT … DO UPDATE … WHERE
+ status = 'proposed'`, so rerunning exploration does not erase a human rejection (when the
+ `WHERE` fails, `RETURNING` yields zero rows). Visibility is tiered: a Viewer can read the
+ list, `revise` needs Editor — seeing the answer without the definition means trusting an
+ algorithm you are not shown.
+
+## Revisions
+
+- 2026-09-02: the status line said "planned" while the record arrived in the same commit as
+ its implementation. The status line is the implementing PR's responsibility; now a README
+ rule.
+- 2026-09-02: we assumed a Review group would be the mapping's home; in use it became its
+ own page (#140, #148).
+
+## Open questions
+
+- **A confirmed definition changes.** Answered by `revise` + `concept_mapping_revisions` +
+ the History drawer: "last quarter's definition" can be read back. Whether querying uses it
+ to replay historical reports is not built.
+- **One concept, several sources.** `(kb_id, concept_id, source)` allows a different
+ definition per source, on purpose. Which one does querying use? Today all go into the
+ prompt (cap 30) and the model picks; rules are easier to add now that it is a table.
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 382a2661..e1cb6007 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,175 +1,103 @@
-# 本体是一份契约,不只是一份建议
-
-**状态**:已实施 · 五轮对照实验 · 违反率 57% → 4%,反向 39 → 0 · 文末三条待做全部仍未做;本文之后本体又能声明 `inverseOf` / `subPropertyOf`(#177 / #179)并被推理机消费,包清单扩到五个而实验只覆盖前两个(2026-09-02 核)
-
-[0008](0008-ontology-packs-as-cold-start.md) 建了预制本体包,但它要回答的那个问题
-——**大本体到底顶不顶用**——一次都没被问过:装了包的库全是 5 篇文档、26 条事实的
-基准跑,量的是提示词开销,不是质量。这一篇是第一次拿真语料问它。
-
-答案分两半:**词汇量确实在接住东西,而声明出来的约束一条都没被执行。**
-
-## 一、包的收益是真的
-
-`ai-timeline-ends`(6 篇维基百科条目)× schema.org + W3C Org(1655 关系 / 973 类),
-**零种子**(#125、#128 之后建库不播任何关系):
-
-- 215 条有谓词的事实、41 个不同关系,**全部来自本体包**,自动扩本体一个都没长出来
-- 空谓词 25.6%——历史上 10 个种子时 `related_to` 占 55.5%
-
-## 二、但方向是反着写进去的
-
-```
-Elon Musk (person) --employee--> Microsoft
-```
-
-而 schema.org 声明 `employee (organization → person)`。**130 条可校验的事实里 102 条这样反着落库。**
-
-这恰恰是选 schema.org 的理由失效——`ontology_packs.rs` 写着「1488 个属性带
-domain + range,方向是**声明的**不是描述的」。声明了,然后没人执行。
-
-而且它比空谓词严重得多:**空谓词是诚实的沉默,反向边是自信的错误**。图上写着
-Musk 雇佣了 Microsoft,而 0002 说推理机是缺陷放大器——这正是它会放大的那种输入。
-
-## 三、一个根因,两个症状
-
-查下去,类型判错与方向反向是同一件事的两副面孔:
-
-```
-#128 撤掉种子 → seed_classes 空(它取的是 builtin 的类)
- ↓
-检索偏爱字面出现在正文里的叶子类
-(讲 Sutskever 的分块,976 个类里 researcher 第 4、person 第 359、organization 第 795)
- ↓
- ┌──────────────────────┬──────────────────────────┐
-实体判成 researcher employee 的签名退化成 (* → *)
-(schema.org 里它是 (sig_of 只认铺出去的类,
- Audience 的子类,不是人) 一侧没铺就写 *)
-```
-
-`build_lists` 的注释早写过这道地板:「**内置类恒在**。检索漏掉的分块仍然要有地方
-落脚,否则模型无类可选」。种子退场后判据悬空了——**它当初碰巧等价,只因为种子类
-正好是那几个通用类**。
-
-## 四、五轮实验
-
-同语料同本体,每次只动一个变量,全部 60/60 块:
-
-| 变体 | 事实 | 空谓词 | 可校验 | 违反 | **真·反向** | 违反率 |
-|---|---|---|---|---|---|---|
-| 只改提示词 | 429 | 138 | 172 | 98 | 39 | 57.0% |
-| + 祖先地板 | 451 | 138 | 181 | 63 | 31 | 34.8% |
-| + 签名类恒在 | — | — | — | — | 26 | 37.2% |
-| + 按库内类型掰正 | 447 | 139 | 179 | **0** | **0** | 29.6% |
-| + 前缀归并 + 不适用则沉默 | 447 | 179 | 149 | **6** | **0** | **4.0%** |
-
-(第三行停在 41/60 块——服务器被杀,只能看比率。)
-
-### 提示词能做的,和不能做的
-
-第一版把两件事混成一句 "hint, not a rule — when the text says otherwise, write what
-the text says",于是模型连参数顺序也按原文说法写。两件事的可覆盖性根本不同:
-
-- **哪些类型能参与**:提示不是闸门。本体可能写错,原文说西雅图就写西雅图。
- [0001](0001-ontology-import-and-governance.md) 的判断在这里不变——硬闸门会
- 系统性丢数据,`part_of` 烧我们的正是那样。
-- **参数顺序**:由签名定。**顺序不是关于世界的断言,是这个 key 的编码约定**;
- 原文从来没有「说了别的方向」,它只说两个实体之间存在某种关系。
-
-改了之后有效,但**不是主力**:三轮提示词把违反率从 57% 压到 35%,压下去的
-**全是类型判错那一半**,真·反向纹丝不动(22.7% → 17.1% → 17.6%,后两个在噪声里)。
-
-**模型看得见签名,就是不照做**——英语的 "X is an employee of Y" 太强。
-继续加措辞不会赢。
-
-### 于是在写入时掰正
-
-主语违反 domain **而宾语符合**时,按签名交换主宾。
-
-这不是新原则:`produced_by` 命中 `produces` 时(#109)早就在自动翻转主宾了,
-区别只在触发条件是**措辞**还是**签名**。
-
-当初反对自动掰正的理由是实体类型不可靠——实测 Elon Musk 被判成 `researcher`。
-**祖先地板修好之后那个前提不成立了**,同一批人判成了 `person`。
-
-类型**从库里的实体读**,不用抽取器手上那份 `entity_type_of`——那份只覆盖模型在
-这一块里声明过的实体,而宾语常是别处已存在的实体。**这一处差别就是反向从 10 降到 0
-的原因。**
-
-**绝不静默**:每次掰正落一条 `direction_corrected`。0001 反对的是「用可能错的声明
-驱动**自动动作**」,而留痕的动作不属于那一类。29 次里有 1 次掰错(`spatial`,
-schema.org 对它的 domain 定义本就模糊)——这是这个机制的固有成本:
-**它信任本体的声明,而声明可能不适用于这对实体。**
-
-### 不适用的关系该沉默
-
-对调也不合法时,从前照原样落库,等于**用本体的名义说一件本体不同意的事**:
-
-```
-OpenAI --affectedBy--> … schema.org 的 affectedBy 是医学检验用的
-Mistral --amount--> €105 million amount 属于融资工具,不属于公司
-Anthropic --competitor--> OpenAI schema.org 的 competitor 是 SportsEvent 的属性
-```
-
-现在丢掉谓词,保留主宾、时间、证据,原词留在 `fact_evidence.proposed_predicate`,
-显示时由 `fact_surface_predicate()` 取回([0010](0010-no-relation-is-no-relation.md))。
-验过没有变哑:**退回的 179 条空谓词事实,179 条全部拿得出原文说法。**
-
-## 五、剩下的不是抽取的错
-
-- **具化建模缺口**(`amount` 13 / `target` 8 / `participant` 5):schema.org 用中间
- 节点建模(Action / LoanOrCredit / Offer),我们是扁平二元关系。
-- **同名词**(`affected_by` / `competitor` / `uses_device`):包里有很多名字通用、
- 含义狭窄的词,按名字或向量相似度挑必然撞上。跟 `Researcher` 被拿来标人同源。
-
-**这两类是本体包的本质成本**,0008 该记进去:**包的代价不在提示词长度,在选择难度。**
-
-### 为什么不引入更强的建模语言
-
-数据模型**已经支持**中间节点——`entities` + `facts` 就是属性图,
-`[某轮融资] --amount--> €105M` 今天就能存,库里也确实有 10 个 `event`、
-9 个 `monetary_amount` 实体。卡住的不是表达力。
-
-卡住的是**提示词的规则 1 与 2**:「用文中写出的规范全名」+「每条事实的主宾都必须
-出现在 entities 里」。而一轮融资在原文里**没有名字**——要满足签名就得凭空造一个实体,
-而提示词从头到尾在教它不要造。**模型做的是对的。**
-
-真要支持具化,动的是这两条规则的地基,还得给无名节点一套命名与去重办法
-(同一轮融资在两篇文章里怎么认成一个?它没有名字可比)——那是实体消解的新问题。
-
-判据应该是**限定词本身需不需要被查询**:「2024 年 A 轮里由 General Catalyst
-领投的公司有哪些」——那个「领投」挂在融资轮上。**今天问不了这种问题,那才是该做的信号**,
-而不是「schema.org 这么建模所以我们也要」。
-
-## 六、顺带修掉的两处
-
-**领头的轻动词不算区别**:`has_funding` 与 `funding` 是同一个关系。实测空谓词里
-`has_funding` ×4 落空而本体有 `funding`,`product` ×2 落空而本体有 `has_product`。
-过度归并不会造成错配——撞车即作废,最坏退回「匹配不上」。
-
-**「实体名」是一句话时不该造成实体**。实测 421 个实体里 76 个无类型,最长的 111 字符
-是一整个从句。守卫本来就有(`> 100 字符` 就 `continue`),但**只装在声明实体那条路上**,
-而未声明的主宾会绕过去直接 `resolve()` 造实体——**前门有锁,后门开着**。而且那个
-`continue` 是静默的,正是 `drop_signal` 当初为之而建的七处之一。
-
-判据改成**词数 + 限定动词**而不是字符数:`US District Court for the Northern District
-of California`(57 字符)是真实体,`removal was driven by growing discontent and
-distrust with Altman`(65 字符)是从句——字符数分不开,**谓语分得开**。
-
-效果:最长实体名 111 → 57 字符(57 那个正是上面那个法院),无类型实体 76 → 60。
-被挡下的全是真句子,没有误伤。
-
-**孤点(一条事实都没有的实体)14.0% → 17.5%,但这不能归因于守卫**:守卫总共只挡了
-个位数,而孤点多了 14 个,更可能是跑次方差(两次跑的模型输出本来就不同,
-后一次还中途重启过、被回收的文档整篇重抽)。孤点的真实成因是另一回事——
-**模型在 `entities` 里声明了实体却没产出用到它的事实**,孤点列表里是法院、SEC、
-特斯拉总部这些正当实体。这个比例值得单独记,但它跟这次的守卫无关。
-
-## 待做
-
-- **写入时的守卫挡不住写入之后的改动**:实体合并会把主语换成另一个类型的实体,
- 于是事实「变成」违反。实测 6 条残留里 4 条如此。要治得把同样的检查放进合并路径。〔**已做**(#190 / #196,`fix/one-domain-check-for-three-paths`):写入时的判断抽成 `ontology::judge_direction`,抽取与**采纳**共用——采纳是第二条写谓词的路,实测把违反率从 0 抬到 12.3%,全在包关系上;两边都不合的采纳**不挂谓词**,条数随 `facts_left_off` 上报。**合并**不掰不改只报:搬动过的事实查一遍 domain / range,违反的进 `axiom_violations`(新 kind `signature`)。一致性检查(0002 R0)也多了这一类,全量量、事实撤了就清,所以本体事后改 domain 也逃不过。未分类实体不算违反——「不知道」不是「不符合」。〕
-- 另外 2 条残留(`Stability AI Ltd`、`Colossus 2 data center`)没有合并也没有改类型,
- **原因未查明**。
-- 导入本体包时过滤掉需要中间节点才能用的关系(domain 全是 `Action`/`Offer`/
- `LoanOrCredit` 这类具化壳的),它们铺给模型只会产出违反。〔仍未做。〕
-- **(2026-09-02 补)`bootstrap_ontology.rs` 开头的模块注释仍在说「新建的库只有 10 个默认关系……降级成 related_to」**,那是三次退场之前的世界。不属于本篇,但与本条线同源,该改。
+# 0012 · The ontology is a contract
+
+- **Status**: implemented · five controlled runs on `ai-timeline-ends` × schema.org + W3C Org took the violation rate from 57% to 4% and true reversals from 39 to 0 · the write-time judgment (`ontology::judge_direction`) now also covers adoption and merge (#190 / #196; merge reports `signature` rows into `axiom_violations`, R0 re-checks the same class) · filtering reified-shell relations out of pack import is still not done · since this record the ontology can also declare `inverseOf` / `subPropertyOf` (#177 / #179) and the pack list grew to five; the runs cover only the first two
+- **Written**: 2026-08-31 (inferred: the source is undated and sits between 0011 and 0013, both dated 2026-08-31) · condensed into English 2026-09-03
+- **Related**: [0008](0008-ontology-packs-as-cold-start.md) built the packs but never asked whether a large ontology holds up on real text; criterion 2 of [0001](0001-ontology-import-and-governance.md) ("the ontology guides, it does not enforce") is overturned by half here; [0010](0010-no-relation-is-no-relation.md) supplies the empty-predicate behavior; [0013](0013-a-source-should-hand-over-its-history.md) is the other end of the same line — how things come in, versus the rules they land by
+
+## The problem
+
+The packs earn their keep. Six Wikipedia articles with schema.org + W3C Org (1655 relations,
+973 classes) and zero seeds: all 215 predicated facts and all 41 distinct relations came from
+the pack, and the empty-predicate share fell to 25.6% (55.5% `related_to` in the ten-seed days).
+
+But not one declared constraint was enforced. schema.org declares
+`employee (organization → person)`; the graph said `Elon Musk --employee--> Microsoft`, and
+102 of 130 checkable facts were written backwards — the reason for choosing schema.org, 1488
+properties with declared domain and range, went unused. An empty predicate is honest silence;
+a reversed edge is a confident error, exactly the input the engine of
+[0002](0002-reasoning-engine.md) amplifies.
+
+One root cause, two symptoms. After #128 removed the seeds, `seed_classes` was empty and
+retrieval favored leaf classes that appear literally in the text (in a chunk about Sutskever,
+`researcher` ranked 4th of 976 classes, `person` 359th, `organization` 795th). Entities got
+typed `researcher` (a subclass of `Audience` in schema.org), and `sig_of`, which only knows
+classes that were laid out, degraded the signature of `employee` to `(* → *)`.
+
+## Decisions
+
+1. **Which types may participate stays guidance; argument order is enforced by the
+ signature.** The first prompt merged the two into "hint, not a rule — when the text says
+ otherwise, write what the text says", and the model applied that to argument order too.
+ Order is not a claim about the world, it is the encoding convention of the key; the text
+ never "says another direction", it only says a relation exists. For types, 0001 still
+ holds: a hard gate loses data systematically, as `part_of` showed.
+
+2. **The ancestor floor.** The ancestors of every retrieved class join the list, so `person`
+ and `organization` are always available. This removed the type half of the violations and
+ made entity types trustworthy: the people typed `researcher` became `person`.
+
+3. **Correct direction at write time.** When the subject violates the domain and the object
+ satisfies it, swap them by signature — the move `produced_by` → `produces` already made
+ (#109), triggered by the signature instead of the wording. Types are read from the entity
+ in the store, not from the extractor's `entity_type_of`, which only covers entities
+ declared in the current chunk while the object usually already exists. That single
+ difference took reversals from 10 to 0.
+
+4. **Never silently.** Every swap leaves a `direction_corrected` trace. 0001 objected to
+ automatic action driven by possibly wrong declarations; a traced action is a different
+ thing. One of 29 swaps was wrong (`spatial`, whose schema.org domain is vague) — the
+ built-in cost of trusting a declaration that may not apply to this pair.
+
+5. **A relation that does not apply falls silent.** When swapping is also illegal, keeping
+ the predicate would assert in the ontology's name something the ontology disagrees with
+ (`OpenAI --affectedBy--> …` is a medical-test property; `competitor` belongs to
+ `SportsEvent`). The predicate is dropped, subject, object, time and evidence stay, the
+ model's word goes to `fact_evidence.proposed_predicate` and `fact_surface_predicate()`
+ shows it (0010). All 179 facts pushed back to an empty predicate still surface their wording.
+
+6. **Two side repairs.** A leading light verb is not a distinction: `has_funding` and
+ `funding` merge, and over-merging is harmless because a collision voids the match. A clause
+ is not an entity name: the 100-character guard sat only on the declared-entities path while
+ undeclared subjects and objects went straight to `resolve()`; the criterion is now word
+ count plus a finite verb, since a 57-character court name and a 65-character clause cannot
+ be told apart by length. Longest name 111 → 57 characters, untyped entities 76 → 60.
+
+## Dead ends
+
+- **More prompt wording.** Three rounds moved the violation rate from 57% to 35%, all of it
+ type errors; true reversals stayed flat (22.7% → 17.1% → 17.6%, within noise). The model
+ sees the signature and does not follow it — English "X is an employee of Y" is too strong.
+- **Automatic swapping before the floor.** Rejected earlier because entity types were
+ unreliable (Musk typed `researcher`); once the floor landed the premise fell away.
+- **A richer modeling language for reification.** `amount` (13), `target` (8) and
+ `participant` (5) fail because schema.org models them through intermediate nodes (Action /
+ LoanOrCredit / Offer) and we write flat binary relations. Expressiveness is not the blocker:
+ `entities` + `facts` already form a property graph. The blocker is prompt rules 1 and 2 —
+ canonical names from the text, every subject and object an entity — and a funding round has
+ no name in the text, so the model would have to invent one. The model is right. Revisit when
+ a query needs the qualifier itself ("companies whose 2024 Series A was led by General
+ Catalyst"); unnamed nodes would also need their own naming and dedup.
+- **Blaming the guard for orphans** (entities with no fact, 14.0% → 17.5%). The guard blocked
+ single digits; the run was restarted mid-way. The real cause is the model declaring
+ entities it never uses (courts, the SEC, Tesla HQ) — worth measuring separately.
+
+The remaining cost of a pack is selection difficulty, not prompt length: many names are
+generic with narrow meanings (`affected_by`, `competitor`, `uses_device`, `Researcher`) and
+get picked by name or vector similarity. 0008 should carry this.
+
+## Revisions
+
+- 2026-09-02: the write-time guard could not stop later edits — a merge swaps the subject for
+ an entity of another type and the fact "becomes" a violation (4 of the 6 residuals). Done in
+ #190 / #196: `ontology::judge_direction` is shared by extraction and adoption (adoption was
+ a second path writing predicates and had pushed the rate back to 12.3%); adoption that fits
+ neither way leaves the predicate off, counted under `facts_left_off`; merge does not swap,
+ it reports `signature` violations on moved facts, and R0 re-checks them so a later change of
+ domain cannot hide. An unclassified entity is not a violation — "unknown" is not "does not fit".
+
+## Open questions
+
+- Two residual violations (`Stability AI Ltd`, `Colossus 2 data center`) were neither merged
+ nor retyped; the cause is unknown.
+- Pack import still lays out relations whose domain is a reified shell (`Action`, `Offer`,
+ `LoanOrCredit`); shown to the model they can only produce violations.
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 3d6dc251..1e6ccc1f 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,202 +1,109 @@
-# 0013 · 一个来源该交出它的历史,不是它的现状
-
-- **状态**:已实施两个(`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);
- [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 是同一件事的另一头——
- 这一篇管**东西怎么进来**,那一篇管**进来之后按什么规矩落**
-
-## 判据:一个来源值不值得接
-
-这产品是双时态账本,所以看四条,缺一条就退化成"又一个抓网页的":
-
-1. **有没有真实时间戳** —— 认知时间那根轴靠它
-2. **会不会自我推翻** —— `supersedes` 才有事可做
-3. **有没有稳定身份** —— 同一份东西的新版能认出来(`external_key`)
-4. **企业知识是不是真的住在那儿**
-
-工单系统四条全中:每张工单的状态天生随时间变,而且信噪比远高于聊天记录。
-
-## 核心判断:别取现在,取变化
-
-**工单最有价值的部分不是"它现在是 closed"**,而是"8-18 开出、8-20 关掉、
-中间被指派给谁、优先级怎么变的"。
-
-只抓当前状态,这条时间线要靠一次次同步慢慢攒——第一次同步只能看见此刻,
-之前发生的全丢了。而多数系统**已经把变更史准备好了**,只是要多问一句。
-
-这与 #122 给维基百科语料做的是同一个判断。区别是维基要从修订列表里采样,
-工单系统直接把变更事件给你。
-
-落进正文的形状(两个来源一致,刻意的):
-
-```
-# KAFKA-9 Consumer logs ERROR during close
-
-Type Bug.
-Currently Closed.
-Resolved on 2011-07-19.
-
-## History
-- 2011-08-05 — Alan Cabrera changed Workflow: jira → no-reopen-closed
-- 2015-09-01 — Tony Stevenson changed Workflow: no-reopen-closed → Apache Kafka Workflow
-
-## Comments
-### Luke Chen on 2026-08-24
-…
-```
-
-**抬头写成带日期的陈述句,不是键值对。** `Opened by X on 2026-08-18` 能抽出带
-`valid_from` 的事实;`created_at: 2026-08-18` 则要模型自己猜这是什么意思。
-
-## 两个供应商教的不同的事
-
-| | GitHub | Jira |
-|---|---|---|
-| 取法 | 三次拉取 + **逐工单**取事件 | **一次调用**取全(`expand=changelog`)|
-| 增量 | `since` 参数 | JQL `updated >= "…"` |
-| 变更史 | 事件级("发生了 labeled")| **字段级**(`Workflow: A → B`)|
-| 时间戳 | RFC3339 | `+0000` **无冒号**,不是 RFC3339 |
-
-### GitHub:聪明的设计悄悄丢掉了全部价值
-
-第一版想让三样都走仓库级端点、一次分页取全,避免 200 张工单 401 次请求。
-**拿真实数据一跑就发现事件那一路是错的**:`issues/events` 不支持 `since`,
-只能从最新往回翻,而 GitHub 的模型里 PR 也产生 issue 事件——实测本仓库的工单事件
-埋在**第 5 页**,换一个 PR 活跃的仓库就会被推到翻页上限之外。
-
-于是"状态变更史"悄悄变成空的,**而它正是这个来源存在的理由**。改成逐工单取,
-N 只是本轮要写入的工单数。用一次准确换一次省事,这里该换。
-
-### Jira:三个坑都藏在字段形状里
-
-- **时间戳不是 RFC3339**(`2026-08-24T11:11:52.944+0000`,时区偏移没有冒号)。
- chrono 默认解不了,解不出来就是整页工单丢掉。
-- **增量没有 `since` 参数**,只能靠 JQL,时间格式是 Jira 自己的且**要带引号**——
- 两点写错的症状都是 400,不是"查不到"。
-- **`fields` 必须显式列**:不列 `comment` 就不返回评论;默认返回全部字段会把
- 一条响应撑到几百 KB。
-
-## 拿真实响应钉住字段形状
-
-手写的 JSON 只能证明"我以为的形状"解得出来。GitHub 一条 issue 有上百个字段,
-我们只声明十个;哪个其实叫别的名、哪个在某些情况下是 null,只有真数据说得清。
-
-两个连接器的夹具都取自**公开可匿名读的实例**(`deeplethe/utopia`、
-`issues.apache.org`),字段裁到我们声明的那些——裁剪本身顺带证明了未声明的
-字段不会让 serde 失败。
-
-它当场抓到一个手写测试全绿而真实数据报错的 bug:**逐工单事件端点不返回 `issue`
-字段**(上下文已经在 URL 里)。第一版按仓库级响应写成必填,换端点后整片解不出来。
-
-**这条对后来者是硬要求**:接一个没有公开实例、拿不到真实响应的来源,
-交付时必须说明"未经真实实例验证",别跟这两个混为一谈。
-
-## 截断要说出来
-
-Kafka 项目有 **14506** 张工单,一轮翻页上限取 500。不报的话界面上"同步完成"
-是一句误导——所以取回数小于 `total` 时落一条 warn,说明本轮只覆盖了一段。
-
-与 #108「部分抽取报告成完成」、#127「一条坏记录不该毁掉一整块」同一条原则:
-**限了覆盖面就要说出来**。
-
-## 已知取舍:时刻被截成了日期
-
-连接器把时间戳写进正文时是 `created_at.format("%Y-%m-%d")`——**按 UTC 截到天**。
-抽取器从 "Opened by X on 2026-08-18." 这句话里读出的 `valid_from` 因此是
-day 精度,时刻在入库前就没了。
-
-**代价说清楚**:跨 UTC 午夜的事件会差一天。一个 UTC+8 的人在 8 月 19 日
-早上七点开的 issue,GitHub 界面上写着 8-19,我们的文档里写的是 8-18。
-
-**为什么仍然接受**:
-
-- 它没有真的丢。源头原样还在,而两个连接器都是**幂等可重同步**的——
- 真要精确到时刻,重同步一次就能拿回来。这与"不可逆丢失"差一个量级。
-- 精度模型本来就在说实话。`precision = day` 的含义正是"知道哪天、不知哪刻",
- day 精度的日期存成 UTC 午夜、按 UTC 渲染,是自洽的。**真正的错是假装知道**。
-- 这产品目前不问"几点"。它回答"某个时刻世界是什么样",粒度到天。
-
-**什么时候该回头做**:有人要按"当地营业日"统计,或者接了一个事件天然聚在
-午夜附近的源(交接班、开盘收盘)。那时 day 精度不够,才值得加一档 `instant`
-精度——连带 CHECK 约束、抽取提示词、渲染分支一起改。
-
-顺带记一条同源的规矩,它已经落在代码里:**世界时间与记录时间的时区待遇相反**。
-`valid_from`/`valid_to` 来自文档里的陈述,是日历日期不是时刻,一律按 UTC 渲染
-(转本地会让 UTC-5 的读者看到前一天);`recorded_at` 这类"我们何时这么认为"
-是真实时刻,按看的人的时区渲染。这两处**故意不一样,别统一**。
-
-## 为什么没有抽象成 `issues` + provider
-
-接第二个供应商正是为了看清该不该抽象。答案是**暂时不该**:取法根本不同
-(三次拉取 vs 一次调用、`since` vs JQL、事件 vs 字段变更)。共同的只有
-"一张工单一篇文档、正文带变更史"这条判断——而它已经体现在两边一致的**文档形状**上,
-不需要一个共同的 trait 来强制。
-
-硬抽一个 provider 接口,会把这些真实差异挤进一堆 `match`。等第三个来了再看:
-如果它的取法落在已有两种之一,那时抽象才有形状可依。
-
-## 这条线后来延伸到了哪
-
-「说清楚一样东西是哪来的」不止管来源。同一句话在本体侧也成立,
-而且是这篇写完之后才补上的:
-
-- **#141**:类的形状开始承载来历——**方 = 词表声明的(有 IRI),
- 圆 = 语料里长出来的**。从前所有自动建的类都写死 `circle`,
- 一张图上看不出哪些类是本体里定义过的、哪些是从文档里长出来的。
-- **#145**:一个类被词汇表**认领**(`adopt_iri_onto_key`)之后形状要跟着改。
- 漏了这一处的症状很刺眼:类拿到了 IRI 却仍画成圆——**有 IRI 却是圆的,
- 画面就在说谎**。这个缝隙只有真导入一次才撞得到,实测撞上过。
-
-两件都不是这篇的主题,但判据是同一条:**来历要看得见**。
-接新来源时值得一并想:这个来源带进来的东西,读者能不能一眼看出它是从哪来的。
-
-## 相邻的一层:一个源能被谁挂载
-
-本文谈「东西怎么进来」。写完之后加了一层本文没有的东西——**授权**(#142,`data_source_grants`):注册数据源是部署级动作,而它携带的连接串会到达每一个被授权的工作区,所以挂载只能在授权过的集合里挑,守卫在两侧都有(列表按工作区过滤 + 挂载端点复核)。
-判据与本文一致:来历要看得见,去向也要管得住。
-
-## 待做:飞书 / Confluence / Notion
-
-文档协作类是下一个该接的——它是 #122 那份维基历史快照语料的**企业版**:
-同一份文档在不同时刻的版本,天然带版本号,不用采样也不用跟埋在 PR 里的事件较劲。
-四条判据全中。
-
-**飞书优先**(`feishu_docs`):中文用户的实际落点,而且它的 API 直接给文档版本。
-
-三个已知的未知,接的人要先答:
-
-1. **拿不到公开实例。** 飞书/Confluence/Notion 都要租户与凭据,所以做不到
- GitHub/Jira 那样的真实端到端。要么用测试租户,要么明说未经真实验证。
-2. **富文本不是字符串。** 飞书文档是块结构(`docx` 的 block 树),
- Notion 是 block、Confluence Cloud 是 ADF——都需要一个"块树 → 纯文本"的渲染器。
- Jira Cloud 的 v3 也是同一个问题,本轮绕开了(走 v2)。
-3. **"变更史"在这里是什么。** 工单的变更史是事件流;文档的变更史是**版本序列**,
- 更接近 #122 那份语料的做法——可能要按"变了多少"采样,而不是每个版本都取。
-
-### 照着走的骨架
-
-两个已有实现是同一个形状,抄它就行:`github_issues.rs`(三次拉取 + 逐工单事件)、
-`jira_issues.rs`(一次调用取全,`expand=changelog`)。
-
-1. **纯函数 `render()`** 把一条记录排成 Markdown——不联网,于是测得动
-2. **`fetch_all()`** 负责分页与鉴权
-3. `ingest_sources.rs` 里加一个 `sync_*` 分支,调 `ingest_item()`——身份、
- sha256 去重、版本记录都由它负责
-4. `sources::KINDS` 白名单 **加前端三处**(`api.ts` 的 `SourceView["kind"]`、
- `Library.tsx` 的建来源对话框、`SourcesRail.tsx` 的图标与 `SYNCING_KINDS`)
-
-第 4 步最容易漏,症状是**界面上选得到、建的时候报 `kind must be one of…`**——
-单元测试与 tsc 都看不见,只有端到端会撞上(#134 就是这么撞的)。
-
-另外注意凭据只进不出:编辑来源时留空 = 保留库里原值,写法见 `sync_custom`。
-
-### 验收
-
-- 单元测试覆盖 `render()`(含"空评论不留空节"这类边界)
-- 拿得到真实响应就加夹具测试;**拿不到就在 PR 里明说未经真实实例验证**
-- 端到端:建来源 → 同步 → 文档带版本/变更信息 → 二次同步幂等(新增 0)
-- `cargo clippy --workspace --all-targets` 与 `npm run typecheck` 干净
-
-Confluence / Notion 是同一类,上面第 2 条未知三家共通。
+# 0013 · A source hands over its history
+
+- **Status**: implemented for `github_issues` (#134), `jira_issues` (#135) and `notion` (#213, pages keep their own clock); WebDAV shares and object storage (S3 / Azure / GCS) arrived as plain file sources (#200, #207, #209) · Feishu and Confluence not started · the `instant` precision has not been triggered
+- **Written**: 2026-08-31 · condensed into English 2026-09-03
+- **Related**: the bitemporal ground of [0001](0001-ontology-import-and-governance.md); the same judgment on the corpus side in `scripts/bench/fetch-wiki-history.mjs` (#122); [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) is the other end of the line — this record is about how things come in, that one about the rules they land by; the grant layer added afterwards (#142, `data_source_grants`) decides who may mount a source: provenance visible, destination governed
+
+## The problem
+
+The product is a bitemporal ledger, so a source is worth connecting only if it passes four
+tests: real timestamps (the recorded-time axis depends on them); the ability to contradict
+itself (otherwise `supersedes` has nothing to do); a stable identity so a new version of the
+same thing is recognized (`external_key`); and enterprise knowledge actually living there.
+Miss one and it degrades into another web scraper. Issue trackers pass all four.
+
+The valuable part of a ticket is not "it is closed now" but "opened 08-18, closed 08-20,
+assigned to whom in between, priority changed how". Syncing only the current state builds
+that timeline sync by sync, and everything before the first sync is lost — while most systems
+already keep the change history and only need to be asked. #122 made the same call for
+Wikipedia; there revisions have to be sampled, an issue tracker hands the events over.
+
+## Decisions
+
+1. **One ticket is one document, and the body carries the history.** Both connectors render
+ the same shape on purpose: a heading, dated declarative sentences (`Currently Closed.`,
+ `Resolved on 2011-07-19.`), a `## History` list of `date — who changed Field: A → B`, then
+ `## Comments`. Sentences with dates, never key-value pairs: `Opened by X on 2026-08-18`
+ extracts to a fact with `valid_from`; `created_at: 2026-08-18` leaves the model to guess.
+
+2. **GitHub fetches events per ticket.** The first version routed everything through
+ repository-level endpoints to spare 200 tickets 401 requests. Real data showed the events
+ leg was wrong: `issues/events` has no `since`, pages from newest backwards, and pull
+ requests produce issue events too — this repository's issue events sat on page 5, and a
+ PR-heavy repository pushes them past the page cap. The state history came back silently
+ empty, and it is the reason the source exists. Per-ticket fetching costs N requests, N
+ being the tickets written this round; accuracy over economy here.
+
+3. **Jira's traps are all in field shape.** Timestamps are `2026-08-24T11:11:52.944+0000`,
+ no colon in the offset, not RFC3339; an unparsed one drops a whole page. Incremental sync
+ has no `since` and goes through JQL `updated >= "…"` in Jira's own format with quotes, and
+ both mistakes surface as 400, not as an empty result. `fields` must be listed explicitly:
+ omit `comment` and no comments come back; list nothing and one response runs to hundreds
+ of KB. `expand=changelog` returns the field-level history in one call.
+
+4. **Fixtures come from real responses.** Hand-written JSON only proves that the shape I
+ imagined parses. Both fixtures come from publicly readable instances (`deeplethe/utopia`,
+ `issues.apache.org`), trimmed to the declared fields — the trimming itself shows that
+ undeclared fields do not break serde. It caught a bug the hand-written tests passed: the
+ per-ticket events endpoint does not return the `issue` field (the context is in the URL),
+ and the first version had it as required. A source without a public instance must be
+ delivered with "not verified against a real instance" stated.
+
+5. **Truncation is reported.** Kafka has 14506 tickets; a round caps at 500 pages. When the
+ fetched count is below `total`, a warning says this round covered a slice, otherwise "sync
+ complete" misleads. Same principle as #108 (partial extraction reported as complete) and
+ #127 (one bad record must not sink a chunk).
+
+6. **Timestamps are cut to the day, deliberately.** The connectors write
+ `created_at.format("%Y-%m-%d")` in UTC, so `valid_from` extracted from
+ "Opened by X on 2026-08-18." has day precision, and an event across UTC midnight is off by
+ one day for a UTC+8 reader. Accepted because nothing is truly lost (both connectors are
+ idempotent and resyncable); because `precision = day` says exactly "the day is known, the
+ instant is not" — the real error would be pretending to know; and because the product does
+ not yet ask "at what hour". Add an `instant` precision (CHECK constraint, extraction prompt
+ and rendering branch together) only when someone needs local business days or a source
+ whose events cluster around midnight.
+
+ A related rule is already in code: world time and record time get opposite timezone
+ treatment. `valid_from` / `valid_to` are calendar dates from statements in documents and
+ render in UTC (local conversion shows a UTC-5 reader the previous day); `recorded_at` is a
+ real instant and renders in the viewer's timezone. The difference is intentional.
+
+## Dead ends
+
+- **An `issues` + provider abstraction.** The second vendor was connected to find out whether
+ to abstract. Not yet: the fetch strategies differ at the root (three pulls vs one call,
+ `since` vs JQL, event-level vs field-level history). What they share — one ticket, one
+ document, history in the body — already lives in the identical document shape and needs no
+ trait; a forced interface would push the real differences into a pile of `match`.
+ Reconsider when a third source lands in one of the two existing shapes.
+
+## The same judgment elsewhere
+
+Provenance has to be visible, and that reached the ontology after this record: a class's
+shape carries its origin (#141: square = declared by a vocabulary with an IRI, circle = grown
+from the corpus), and a class adopted by a vocabulary (`adopt_iri_onto_key`, #145) changes
+shape — a class with an IRI drawn as a circle is a picture that lies.
+
+## Open questions
+
+- **Feishu / Confluence / Notion** are next: the enterprise version of the #122 Wikipedia
+ history corpus — versions of one document at different times, numbered, no sampling and no
+ events buried in PRs. Feishu first (`feishu_docs`): it is where Chinese users are, and its
+ API hands out document versions. Three unknowns to answer first: no public instance (a test
+ tenant, or "not verified" stated); rich text is a block tree (Feishu `docx` blocks, Notion
+ blocks, Confluence ADF; Jira v3 has the same problem, avoided this round via v2) and needs a
+ block-tree-to-text renderer; and "history" here is a version sequence, closer to #122 —
+ probably sampled by how much changed rather than every version.
+
+ The skeleton is the two existing connectors: a pure `render()` turning one record into
+ Markdown (no network, so testable); `fetch_all()` for paging and auth; a `sync_*` branch in
+ `ingest_sources.rs` calling `ingest_item()`, which owns identity, sha256 dedup and version
+ records; and the `sources::KINDS` whitelist plus three frontend places (`SourceView["kind"]`
+ in `api.ts`, the create dialog in `Library.tsx`, icons and `SYNCING_KINDS` in
+ `SourcesRail.tsx`). The fourth step is the one that gets missed: the kind is selectable and
+ creation fails with `kind must be one of…`, invisible to unit tests and tsc (#134 hit it).
+ Credentials go in and never out — an empty field on edit keeps the stored value, as in
+ `sync_custom`. Acceptance: unit tests on `render()`, fixture tests where a real response is
+ obtainable, create → sync → versions present → second sync adds 0, and clean
+ `cargo clippy --workspace --all-targets` and `npm run typecheck`.
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 14dd5db7..486655dd 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,139 +1,82 @@
-# 0014 · 身份跟着人,范围跟着令牌
-
-- **状态**:已实施(#161 记录、#180 落地)· `personal_tokens` + Streamable HTTP 的 MCP 服务端已上线,暴露五个只读工具;界面在 `feat/tokens-have-a-page`(0016 A2):账户层「Agents & tokens」页,发放时明文与 MCP 客户端配置片段一起只显示一次,列表只剩前缀,撤销留痕(2026-09-02 核,修订见文末)
-- **成文**:2026-09-01(约定见 [README](README.md))
-- **相关**:迁移 `0014_data_source_grants` 刚给数据源补上授权层——本篇是同一个问题
- 换到「机器来敲门」这一侧;[0004](0004-language-and-localization.md) 定下服务端只说英文,
- 错误码这一条对 MCP 同样适用
-
-> 起因是要把 Utopia 的七个工具暴露成 MCP 服务端。**第一个要回答的不是传输层选哪个,
-> 是客户端以什么身份接进来。** 这一篇只答这个。
-
-## 现状:两种凭据,都不合身
-
-| | 跟着谁 | 存法 | 过期 | 能撤吗 |
-|---|---|---|---|---|
-| JWT | 人 | 无状态 | 7 天 | **不能**——签出去就管不了 |
-| `sources.ingest_token` | 一个来源 | 明文 | 无 | 换一个 |
-
-JWT 是给浏览器会话设计的:短命、每次登录重签、无状态所以不需要一张表。MCP 客户端是
-长命的、机器的、配在别人机器上的一个文件里——七天过期意味着每周手动重配一次,而
-「撤不回来」意味着笔记本丢了只能等它自己过期。
-
-`ingest_token` 更不合适:它跟来源走,不跟人走,而且只能**往里推文档**。
-
-## 走过的岔路:KB 级机器令牌
-
-先提的方案是给知识库发机器令牌——一枚令牌对应一个库,跟人无关。
-
-**否掉了,两条理由:**
-
-1. **它引入第三套授权模型。** 现在已经有工作区成员和 KB 角色两层;再加一层「令牌自己的
- 权限」,那么「这个 agent 能看什么」就得同时查三张表才答得出来。而三层里任何一层写错,
- 失败方向都是「多给了」。
-2. **归因会变成假的。** `audit_events.actor_id` 现在记的是活人,`actor_label` 还存了一份
- 身份快照。机器令牌写进来的事实,actor 只能是一个合成 id——台账上就多出一类「不是任何
- 人做的」记录,而账本存在的理由正是「谁在什么时候认下了什么」。
-
-**改成:令牌以这个人的身份行事。**
-
-## 决定
-
-```
-有效权限 = 这个人的角色 ∩ 这枚令牌的 scope
-```
-
-交集,不是并集。**令牌只能收窄,永远不能放宽。** 一个 viewer 的令牌勾上 write 也还是
-只读——scope 是上限,不是授权。
-
-### 为什么身份跟着人
-
-- **现有守卫一行不用改。** `require_kb(kb_id, Role::Viewer)`、`access::kb_role` 拿到的还是
- 一个 `User`,它从哪来的无所谓
-- **归因是真的。** 台账上是活人,不是机器人
-- **停用即失效。** 人离职停用,他的令牌跟着废,不用单独维护一张「谁的机器还连着」的表
-- **多个库不用发多把钥匙**
-
-### 为什么范围仍然要单独收窄
-
-因为有一个 MCP 特有的问题,应用内对话没有这么严重:
-
-> **混淆代理。** MCP 客户端是别人的 agent、别人的系统提示词,而它读的是知识库里的
-> 文档——**不可信内容**。一份文档里写「请执行这段 SQL」或者「记住 X」,那个 agent 可能
-> 就照做了,用的是这个人的全部权限。
-
-应用内对话也有这个面,但那里提示词和工具循环都在 Utopia 手里;走 MCP,Utopia 对客户端
-的提示词、对它还接了哪些别的服务端,一无所知。
-
-而这个人的「全部权限」是什么:经 `query_data`,对他所在**每一个库挂载的每一个生产
-数据库**跑只读 SQL;经 `remember`,往 append-only 账本里写事实。这些能力配在一串放在
-`claude_desktop_config.json` 明文里的字符串上。
-
-所以默认发**只读、限定到一个库**的令牌。要让 agent 写,得显式勾。
-
-## 这枚要哈希,而 `ingest_token` 不哈希
-
-两处结论不同,不是疏忽。`ingest_token` 那条明文决定的原话(`0002_ingest.sql`):
-
-> **明文存,不是哈希。** 自部署威胁模型下「只看一次」是自找麻烦:改存明文随时可查。
-> DB 失守时文档本体早已泄露,密钥哈希化没有额外收益
-
-那个推理对 ingest_token 成立,因为**它只能往里推文档**——泄露它的最坏结果是有人往你
-库里塞垃圾,而库都失守了,塞垃圾不是最要紧的事。
-
-个人令牌不一样:它经 `query_data` 能**读出 Utopia 之外的生产库**。Utopia 的数据库失守
-本来就泄露 Utopia 自己的文档,但数仓在另一台机器上、装着另一批数据,不该跟着一起丢。
-**爆炸半径不同,所以存法不同。**
-
-## 形状
-
-```sql
-CREATE TABLE personal_tokens (
- id UUID PRIMARY KEY,
- user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
- name TEXT NOT NULL, -- 人自己起的,"我的笔记本"
- token_hash TEXT NOT NULL, -- 哈希,理由见上
- scope TEXT NOT NULL DEFAULT 'read'
- CHECK (scope IN ('read', 'write')),
- kb_ids UUID[], -- NULL = 这个人能进的全部
- expires_at TIMESTAMPTZ, -- NULL = 不过期,但 UI 默认给 90 天
- last_used_at TIMESTAMPTZ, -- 「这枚还在用吗」,撤之前要答得出
- revoked_at TIMESTAMPTZ, -- 撤销不删行:撤过这件事本身要留痕
- created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-```
-
-`user_id` 这条有外键且级联,与 `audit_events.actor_id` 的裸外键相反——**台账要活得比
-用户久,令牌不该**。人没了,他的钥匙就该一起没。
-
-## 一条实施纪律
-
-**每个工具入口都要校验 scope,不能只在连接握手时校验一次。**
-
-这是 `0014_data_source_grants` 那轮的教训,原话写在测试里:
-
-> 列表过滤只挡「看得见」,而挂载端点是照着 id 调的——守卫必须在两侧都有
-
-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 的审计怎么记?〔**已答:不进**。实际发的是五个而非四个,多一个 `search_docs`。`remember` 的前提是 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 那道闸,而闸还没接上。〕
-- **传输层**:stdio(本地,配 Claude Desktop 最省事)还是 streamable HTTP(远程,
- 和 Utopia 已经是个服务端相称)。这个选择不影响本篇的结论,两种都要认令牌。〔**已答:Streamable HTTP**,一条路由 `POST /api/v1/kbs/{kb_id}/mcp`,响应用 `application/json` 不用 SSE——工具一问一答,没有服务端主动推的东西。〕
-- **令牌能不能跨工作区。** 现在的 `kb_ids` 是库级白名单;如果将来要按工作区发,
- 和数据源授权那张表会长得很像,届时看要不要合并概念。〔仍未做。〕
-- **(2026-09-02 补)没有界面。** 「UI 默认给 90 天」的 90 天在服务端,而前端根本没有令牌那一页。这是 MCP 今天对用户不可用的直接原因。〔**已做**,同日:`/account/tokens`。三个决定落在界面上——scope 缺省只读、库多选、过期缺省 90 天且「不过期」要显式选;配置片段按库出端点(令牌限定到库,端点也按库分),写法取 Claude Code / Claude Desktop 一族的 Streamable HTTP 键名,别的客户端要自己改键。〕
+# 0014 · Identity from the person, scope from the token
+
+- **Status**: implemented (#161 record, #180 code) · `personal_tokens` and a Streamable HTTP MCP server at `POST /api/v1/kbs/{kb_id}/mcp` with five read-only tools, `application/json` responses rather than SSE · the account-level "Agents & tokens" page at `/account/tokens` (0016 A2): plaintext shown once beside a per-base client config snippet, the list keeps the prefix, revocation leaves a trace · `can_write` is still hard-coded `false`, so a `write` scope changes nothing yet
+- **Written**: 2026-09-01 · condensed into English 2026-09-03
+- **Related**: migration `0014_data_source_grants` gave data sources a grant layer; this is the same question where a machine knocks. [0004](0004-language-and-localization.md) has the server speak English only, MCP error codes included. [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) removes the main objection to opening `remember` over MCP.
+
+## The problem
+
+Exposing Utopia's tools over MCP raises one question before transport: as whom does the
+client connect? Neither existing credential fits. The JWT follows a person but is stateless,
+expires in seven days and cannot be revoked — a client configured in a file on someone else's
+machine would be reconfigured weekly, and a lost laptop waits for expiry.
+`sources.ingest_token` follows a source, is stored in plaintext, never expires and can only
+push documents in.
+
+## Decisions
+
+1. **The token acts as the person.** Effective permission = the person's role ∩ the token's
+ scope. A token can only narrow, never widen: a viewer's token ticked `write` stays
+ read-only. Existing guards (`require_kb(kb_id, Role::Viewer)`, `access::kb_role`) still
+ receive a `User`; the audit trail shows a person; deactivating the person kills their
+ tokens; several bases need no extra keys.
+
+2. **Scope still narrows separately, because of the confused deputy.** An MCP client is
+ someone else's agent under someone else's system prompt, reading untrusted content from the
+ base — a document saying "run this SQL" or "remember X" may be obeyed with the person's
+ full permissions, and Utopia knows nothing about that client's prompt or its other servers.
+ Full permission means read-only SQL against every production database mounted in every base
+ the person can reach (`query_data`) and writes to the ledger (`remember`), all hanging off
+ a string in `claude_desktop_config.json`. So the default token is read-only and limited to
+ one base; writing must be ticked.
+
+3. **This token is hashed while `ingest_token` is not.** `0002_ingest.sql` reasoned that once
+ the database is lost the documents are lost anyway, so hashing buys nothing — true for a
+ token that can only push documents in. A personal token reads production databases outside
+ Utopia through `query_data`, and that warehouse should not fall with Utopia's database.
+ Different blast radius, different storage. SHA-256 rather than argon2: a high-entropy
+ string does not fear brute force, and a per-row salt would defeat the `UNIQUE` index on
+ `token_hash`.
+
+4. **Shape.** `personal_tokens(id, user_id, name, token_prefix, token_hash, scope, kb_ids,
+ expires_at, last_used_at, revoked_at, created_at)`: `scope` defaults to `read`; `kb_ids`
+ NULL means every base the person can reach; `expires_at` NULL means never, but the UI
+ defaults to 90 days and "never" is an explicit choice; `last_used_at` answers "is this
+ still in use" before revoking. The prefix `utp_pat_…` against ingest's `utp_` tells the
+ kinds apart in logs and config files. `user_id` cascades on delete, unlike the bare foreign
+ key on `audit_events.actor_id`: the ledger must outlive the user, the keys must not.
+ Revocation writes `revoked_at` rather than deleting the row: the revocation is a trace.
+
+5. **Every tool call checks scope.** The lesson of `0014_data_source_grants`: list filtering
+ only guards what is visible, the mount endpoint is called by id, so the guard sits on both
+ sides. Rather than a handshake check followed by trust for the connection's lifetime, every
+ POST re-runs authentication (revocation and expiry in the SQL `WHERE`), `covers()` and
+ `require_kb`; a token revoked mid-session fails on its next call. Each call writes an audit
+ row (`mcp.tool_called`, target = the token), so attribution is real.
+
+## Dead ends
+
+- **Base-level machine tokens**, one per base and unrelated to a person. It would be a third
+ authorization model beside workspace membership and base roles — "what can this agent see"
+ needs three tables, and a mistake in any fails towards "gave too much". And attribution
+ becomes fake: `audit_events.actor_id` records living people with an `actor_label` snapshot,
+ while a machine token's facts would belong to a synthetic id.
+
+## Revisions
+
+- 2026-09-02: an unstated precondition — #175 moved the seven tools out of the `match` in
+ `chat.rs` into `tools.rs`, so chat and MCP share one implementation. The JSON schemas stay
+ in `chat.rs`; `search_chunks` still says results can be cited as `[n]`, which MCP clients
+ cannot see.
+- 2026-09-02: the placeholder crate `utopia-mcp` advertised three tools that never existed;
+ the server lives in `utopia-server/src/api/mcp.rs`. Deleted with `utopia-graph` and
+ `utopia-connectors` ([0016](0016-close-the-open-seams-before-cutting-new-ones.md) A2).
+
+## Open questions
+
+- **`query_data` and `remember` over MCP.** The first version ships `search_chunks`,
+ `search_docs`, `find_entities`, `entity_facts` and `changes`. `remember` waits on the gate
+ of 0015; what evidence an external agent's fact carries and how SQL runs are audited are
+ still unanswered.
+- **Tokens across workspaces.** `kb_ids` is a base-level whitelist; a workspace-level grant
+ would look much like `data_source_grants`, and the two concepts may merge then.
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 3c9a3863..1d33c584 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,168 +1,90 @@
-# 0015 · 记下一句话,不等于断言一个事实
-
-- **状态**:已实施 · schema 在迁移 `0018`(#180),运行时随 [0016](0016-close-the-open-seams-before-cutting-new-ones.md) A1 接上:抽取分流进 `pending_facts`、Review 新一档、对话里跟在 remember 后面的确认卡、`remember` 重新打开。**决定 3 的措辞与本文写的不同**,见文末最后一条修订
-- **成文**:2026-09-01(约定见 [README](README.md))
-- **相关**:[0010](0010-no-relation-is-no-relation.md) 删掉兜底关系(本篇那条空谓词正是它的
- 正确行为)、[0011](0011-a-mapping-is-not-a-fact.md) 批过「拿浮点数编码二值状态」——
- 本篇的实现红线;[0014](0014-identity-from-the-person-scope-from-the-token.md) 里
- 「MCP 不开写」的主要顾虑,被本篇的闸消掉
-
-> 起因是一次实测,不是推演。跑通 `remember` 之后回头查库,看到的东西和助手说的
-> 对不上。
-
-## 那一次实测
-
-对话里说:
-
-> Please remember this: Acme moved its headquarters to Shenzhen on 2026-03-15.
-
-助手答:
-
-> I've recorded that **Acme moved its headquarters to Shenzhen** on March 15, 2026.
-
-而图里落下的是:
-
-```
-Acme --(空谓词)-> Shenzhen confidence 0.9 invalidated_at 空
-```
-
-谓词是空的——本体里没有「搬迁到 / 总部位于」这类关系,抽取落不上就留空。**按 0010
-这是正确行为**(不编一个 `related_to` 出来)。但结果是图上多了一条 0.9 置信、没有
-语义的边,而且**说的和进去的不是一回事,人没有任何办法发现**。
-
-## 现状:根本没有确认这道闸
-
-查之前以为 `unconfirmed` 队列就是它。不是,它的定义是:
-
-```sql
--- 待确认 = 有证据、但证据所在的分块全被新版本取代了
-```
-
-那是**证据过期**队列。`lowconf` 是 `confidence < 0.75`。两个都是事后清理:低置信事实
-在队列里躺着的时候,它已经是图上一条活边(`invalidated_at IS NULL`)。
-
-所以:**任何抽取出来的事实,一落库就生效,没有任何一步需要人点头。**
-
-## 这对批量摄入是对的,对 `remember` 不是
-
-灌 500 篇文档抽出一万条事实,让人逐条确认是不可能的。乐观写入 + 事后审阅是那条路上
-唯一可行的设计,本篇不动它。
-
-`remember` 是另一回事,三点都不一样:
-
-| | 文档摄入 | remember |
-|---|---|---|
-| 量 | 一次上万条 | 一次一句 |
-| 人在哪 | 上传完就走了 | **就在对话里** |
-| 素材 | 外部证据 | 人自己特意说的一句话 |
-
-确认成本最低的那一刻,恰好就是他说完那句话的那一刻。
-
-## 真正的病不是「少一道闸」
-
-是**助手宣称的和图里得到的不一致**。
-
-「已记录 Acme 把总部搬到深圳」听起来像是那件事进去了;实际进去的是一条无谓词的边。
-所以二次确认的价值主要不在多点一下,在于**让人看见即将断言的是什么**——看到
-`Acme --?-> Shenzhen`,人会立刻说这不对。
-
-这也决定了确认界面该长什么样:**原句在上,抽出的三元组在下**,两者并排。只列三元组
-等于要人凭空判断它对不对。
-
-## 决定
-
-1. **`remember` 写文档这一步不变。** 那只是记录「你说过这句话」,本身无害,也确实
- 该立刻可检索。
-2. **从记忆抽出的事实,进图前要人确认。** 未确认的不参与检索、不上图、不进推理。
-3. **助手的话照实说**:「已记录,抽出 N 条待你确认」,不宣称完成。
-
-## 修订记录:第一版把状态加在 `facts` 上,错了
-
-**原本的方案**是给 `facts` 加三列(`nod` / `nodded_by` / `nodded_at`),
-`nod = 'pending'` 表示等人点头。迁移写完、`insert_fact` 的参数也穿好了,
-才发现这是**这个仓库半个月前刚踩过的坑**。
-
-`0013_reasoning.sql` 里那段话,把这个形状的问题说得比我清楚:
-
-> 试过塞进 `facts` 加一位 `derived_by_rule` 标记,那一版的问题是**失败方向反了**:
-> 仓库里有四十多处读 `facts` 的查询,其中只有一处认识那个标记,于是新写一条
-> 查询默认就是把派生当断言看,得记得加过滤。写这个功能的人(我)当场就漏了两处。
->
-> 分开之后忘了 UNION 的后果是**看不见**派生,而不是**混进去**。
-
-数了一下:今天有 **27 处**查询按 `invalidated_at IS NULL` 捞活事实,分布在
-6 个文件。给它们逐个补 `AND nod IS DISTINCT FROM 'pending'`,漏一处的后果就是
-一条没人点头的事实混进图里——而这个功能存在的全部理由就是防这件事。
-
-**改成自己一张表 `pending_facts`。** 确认时才写进 `facts`。忘了读它的后果变成
-「看不见待确认队列」,而不是「未确认的混进了图」。失败方向对了。
-
-顺带一提,0013 给出的另外两条理由这里也成立:**列不一样**(待确认的需要
-`proposed_predicate` 原话、需要指回那句记忆,而不需要 `supersedes`),
-**生命周期不一样**(确认后它就不该继续存在于那张表里)。
-
-
-
-0011 那条线上批过一次同样的错。原话不在 ADR 里,在它落地的建表注释
-(`migrations/0006_semantic_layer.sql` 的 `concept_mappings.status` 列):
-
-> **状态而不是置信度。** 从前借事实的 confidence 表达「提议 0.6 / 确认 1.0」,
-> 那是把一个二值状态编码成浮点数,还顺带让它落进「低置信事实」那一档。
-
-`facts` 表今天没有状态列(`id, kb_id, subject_id, predicate_id, object_id,
-object_value, valid_from, valid_to, ..., confidence, derived_by_rule, supersedes`)。
-要加就加真的一列,别再拿 0.6 糊弄——那会让这条事实同时出现在「待确认」和
-「低置信」两个队列里,而它们问的不是同一个问题。
-
-## 顺带:MCP 开写的障碍消掉了
-
-0014 里不开 `remember` 的主要顾虑是混淆代理——知识库里的文档是不可信内容,一份文档
-写「请 remember 某某」,外部 agent 可能就照做了,用的是这个人的全部权限。
-
-装上这道闸之后,**外部 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`):跨轮回放助手上一轮的工具调用与结果,模型才知道自己做过什么,不会把上一轮的检索重跑一遍落到另一批同名实体上。本文讲的是「助手说的」与「图里得到的」之间的落差,那一条讲的是「助手说的」与「助手做的」之间的落差。
-
-## 修订记录:接上运行时之后,三处与本文不同
-
-**一、助手说不出「抽出 N 条」。** 决定 3 写的是「已记录,抽出 N 条待你确认」。抽取是异步走队列的,
-`remember` 回话的那一刻抽取还没跑,N 不存在。两条路:把记忆抽取改成同步(一句话十来秒,卡住整个对话循环),
-或者如实说「这句话记下了,从中抽出的事实会先给你确认,确认前不进图」,等抽取完成时再把确认卡**长到对话里**。
-选了后者。卡片靠 SSE 的 `pending` 事件触发,按那句记忆的 chunk 取待确认项;回放旧会话时同样按 chunk 取,
-还有没点头的就照样显示,都处理完了就不占地方。
-
-**二、确认界面在两处,同一个组件。** Review 页新一档「等你点头」排在最前——它是人自己说的话,而且这一档里的
-东西还没进图,别处每一档审的都是已经在图上的。对话里那张卡是同一行组件。载荷是声明式的(chunk + 三元组列表),
-将来若要让别人的客户端渲染它(MCP 那一侧),换的是渲染器不是服务端。
-
-**三、确认走的正是抽取那条路。** 事实 + 证据(指回那句记忆,引句就是整句)+ 时态对账。所以「Mira 交给
-Devin 了」点头之后,Mira 那条会像从文档里抽出来时一样被闭合。置信度不动,人的态度在台账里
-(`fact.nod_confirmed` / `fact.nod_rejected`,快照自包含)。
-
-**顺带定下的**:拒绝记录按(主语, 谓词, 宾语实体)查,**字面值事实不查**——`rejected_facts` 没有 `object_value`
-列,按(主语, 谓词)挡会把「薪水 28000 被拒」扩大成「薪水这个属性永远不再提」,宁可多问一次。
-实体照常消解并创建,`pending_facts.subject_id` 是外键,这是 0018 定下的取舍;代价是几个暂时孤立的节点。
-「谁说的」从 `remember` 经 `memory_ingest` 与 `extract_document` 的任务载荷一路传到 `proposed_by`。
-
-## 未决
-
-- **闸只拦记忆,还是拦所有「单条、交互式」的写入?** 今天只有 `remember` 这一条路,
- 但将来若有「在图上手工加一条边」的界面,它该走哪边?
-- **确认之后置信度取什么。** 人点了头还留 0.9,还是升到 1.0?0011 的教训说别拿
- confidence 表达人的态度,那大概是「不动它」——但要想清楚。〔**已定:不动**。人的态度在台账里。〕
-- **拒绝之后那条记忆怎么办。** 文档还在(人确实说过那句话),只是没抽出可用的事实。
- 下一轮重抽会不会又提议一遍?`concept_mappings` 那边靠 `status='rejected'` 挡住了
- 重复提议,这里需要对应的东西。〔答了一半:`rejected_facts` 表与查重索引建好了,语义就是「这个三元组在这个库里被拒过」,但没有任何代码写它或查它。〕
+# 0015 · A recorded sentence waits for a nod
+
+- **Status**: implemented · schema in migration `0018` (#180: `pending_facts`, `rejected_facts`) · runtime wired in [0016](0016-close-the-open-seams-before-cutting-new-ones.md) A1: extraction from a memory document goes to `pending_facts`, Review has a "waiting for your nod" queue placed first, a confirmation card grows into the chat after `remember`, `REMEMBER_ENABLED` is `true` again · decision 3 landed with different wording, see Revisions · MCP is still read-only; opening `remember` there is the next cut
+- **Written**: 2026-09-01 · condensed into English 2026-09-03
+- **Related**: [0010](0010-no-relation-is-no-relation.md) removed the fallback relation (the empty predicate below is its correct behavior); [0011](0011-a-mapping-is-not-a-fact.md) rejected encoding a binary state as a float, the red line for this implementation; [0014](0014-identity-from-the-person-scope-from-the-token.md) kept MCP read-only mainly because of the confused deputy, which this gate removes
+
+## The problem
+
+A real run, not a thought experiment. The user said "Please remember this: Acme moved its
+headquarters to Shenzhen on 2026-03-15." The assistant answered "I've recorded that Acme
+moved its headquarters to Shenzhen on March 15, 2026." The graph got
+`Acme --(empty predicate)--> Shenzhen`, confidence 0.9, live. The ontology has no "moved to /
+headquartered in", so the predicate stayed empty — correct by 0010 — but the graph gained a
+meaningless 0.9 edge, and what was said and what went in differed with no way to notice.
+
+There was no confirmation gate at all. `unconfirmed` is the queue for facts whose evidence
+chunks were all superseded; `lowconf` is `confidence < 0.75`; both are after-the-fact cleanup
+on facts that are already live (`invalidated_at IS NULL`). Every extracted fact takes effect
+on insert. That is right for bulk ingest — nobody confirms ten thousand facts from five
+hundred documents one by one. `remember` differs on all three axes: one sentence at a time,
+the person is still in the conversation, and the material is something they said on purpose.
+The cheapest moment to confirm is right after they said it.
+
+The disease is not the missing gate but the gap between what the assistant claims and what
+the graph gets. The value of confirming is mostly that the person sees what is about to be
+asserted — shown `Acme --?-> Shenzhen`, they say "that's wrong" at once. So the card shows the
+original sentence above the extracted triples; triples alone ask for a judgment from nothing.
+
+## Decisions
+
+1. **`remember` still writes the document.** That only records "you said this", is harmless
+ and should be searchable at once.
+2. **Facts extracted from a memory wait for a nod before entering the graph.** Unconfirmed
+ facts take no part in retrieval, the graph or reasoning.
+3. **The assistant says what happened** and does not claim completion.
+4. **Pending facts get their own table, `pending_facts`,** written to `facts` only on
+ confirmation. The columns differ (`chunk_id NOT NULL` pointing back at the memory,
+ `proposed_predicate` with the model's wording, `predicate_id` nullable — the emptiness is
+ exactly what the person must see — and `proposed_by`), and so does the lifecycle: after
+ confirmation the row should not exist there. The failure direction is right: forgetting to
+ read the table hides the queue instead of leaking an unconfirmed fact into the graph.
+5. **Confirmation takes the extraction path**: fact plus evidence (the memory chunk, the
+ whole sentence as the quote) plus temporal reconciliation, so a nod on "Mira handed over to
+ Devin" closes Mira's fact as a document extraction would. Confidence is untouched; the
+ person's stance lives in the audit ledger (`fact.nod_confirmed` / `fact.nod_rejected`).
+ Rejections go to `rejected_facts` and are checked on the next extraction by (subject,
+ predicate, object entity); literal-value facts are not checked, since `rejected_facts` has
+ no `object_value` and blocking on (subject, predicate) would turn "salary 28000 rejected"
+ into "never propose salary again" — better to ask once more. Entities are resolved and
+ created as usual (`pending_facts.subject_id` is a foreign key), at the cost of a few
+ temporarily orphaned nodes. `proposed_by` travels from `remember` through the
+ `memory_ingest` and `extract_document` job payloads.
+6. **The MCP objection is gone.** With the gate an external agent can only propose, never
+ assert; a document saying "please remember X" reaches the person before the graph. This
+ answers the open item in 0014.
+
+## Dead ends
+
+- **Status columns on `facts`** (`nod` / `nodded_by` / `nodded_at`, `pending` = awaiting a
+ nod). The migration was written and `insert_fact` threaded before it turned out to be the
+ trap `0013_reasoning.sql` describes for `derived_by_rule`: the failure direction is
+ reversed. Dozens of queries fetch live facts by `invalidated_at IS NULL` (27 in 6 files when
+ first counted, 56 in 7 files by 2026-09-02); each would need
+ `AND nod IS DISTINCT FROM 'pending'`, and missing one leaks an unconfirmed fact — the one
+ thing the feature exists to prevent.
+- **Confidence 0.6 for "proposed".** Rejected once already for `concept_mappings.status`
+ (0011): a binary state encoded as a float, which also lands the fact in the low-confidence
+ queue, and the two queues ask different questions.
+
+## Revisions
+
+- 2026-09-02: only the schema existed — zero reads and writes, `memory::is_memory_document()`
+ written but uncalled, and the interim gate was `REMEMBER_ENABLED = false` in `chat.rs`
+ ("better no tool than one that silently changes the graph").
+- On wiring the runtime, decision 3 changed. The assistant cannot say "N facts extracted":
+ extraction runs asynchronously and N does not exist when `remember` replies. Making it
+ synchronous would block the chat loop for ten seconds a sentence; instead the reply says the
+ sentence is recorded and its facts will be shown for confirmation first, and the card grows
+ into the conversation on the SSE `pending` event, fetched by the memory's chunk (replayed
+ sessions fetch the same way). The Review queue and the chat card are one component with a
+ declarative payload (chunk + triple list), so an external client would swap the renderer.
+- The same disease from the other side (#173, migration
+ `0015_what_it_did_not_just_what_it_said`): replaying the previous turn's tool calls so the
+ model knows what it did and does not rerun a search onto another set of same-name entities.
+ This record is "said" versus "got"; that one is "said" versus "did".
+
+## Open questions
+
+- Does the gate hold only memories, or every single-item interactive write? Today `remember`
+ is the only such path; a future "add an edge by hand" interface should take the same table.
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
index e695fd25..5463554c 100644
--- 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
@@ -1,123 +1,102 @@
-# 0016 · 先把开着的口子收上,再开新的
+# 0016 · Close the open seams before cutting new ones
-- **状态**:规划中 · 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 的修订记录,本文只排顺序、只讲为什么是这个顺序
+- **Status**: in progress · the first schedule after v0.1.0 · A1, A2, A3 done · B1 done (#227) · B2a done (#238, [0017](0017-a-contradiction-points-upstream.md)), B2b planned · B3: the signature half done (#190 / #196), cross-pack signatures and range-aware direction done (#233), `disjointWith` into resolution still open · D2's blank-base problem worked around with builtin `metric` / `dimension` classes (#231), the pack itself still planned · the lakehouse engines landed ahead of D4 (#239, [0018](0018-the-lakehouse-is-one-protocol-away.md))
+- **Written**: 2026-09-02 · condensed into English 2026-09-03
+- **Related**: written after checking [0001](0001-ontology-import-and-governance.md) through [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) against the code; every item below has its source in those fifteen records, whose 2026-09-02 revision notes are the check's product. This record only orders them and says why this order.
-> 这一篇没有实验数字。它是一次盘点:v0.1.0 发出去了,README 的能力表写了十二行,
-> 十五篇决策记录里有三篇的状态行落后于同一个 PR 里的代码。**在开下一条大线之前,
-> 先把「说的」和「做的」对齐一遍。**
+## The problem
-## 现状,一段话
+v0.1.0 shipped with twelve capability rows in the README while three of fifteen records had
+status lines behind the code in the same PR. Before the next big line, align "said" with
+"done". The half-built pieces still open:
-一个 Rust 二进制加一个 Postgres:摄入(十种格式、URL / RSS / GitHub / Jira 同步、按源令牌推送)→
-混合检索 → 抽取(本体驱动、预算内全铺、超预算按块检索加祖先补齐、写入时按签名掰正方向)→
-三段消解(等值召回、画像相似、包含关系)加攒批裁决 → 双时态账本(证据、supersedes、合并可回滚)→
-本体从语料长出来(计数采纳、可撤销、默认开)→ 推理机 R0 全建、R1 带开关 → 语义层(概念映射另存、口径有历史)→
-问数(Ontology2SQL,源授权到工作区)→ 对话是 agentic 的,七个工具,跨轮回放自己做过什么 → MCP 只读五工具、个人令牌。
-告警五种,审计台账,每库角色矩阵。约 4.7 万行 Rust、2.2 万行前端、18 个连库测试、8 份可重跑语料。
-
-**这些都是真的。** 下面这些也是真的:
-
-| 半成品 | 出处 | 症状 |
+| Half-built | Source | Symptom |
|---|---|---|
-| `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 | 本体声明了不相交,合并候选照样跨过去 |
-| 合并路径没有签名复核〔已做,#196;采纳那条路也没有,#190,一并做了〕 | 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 接上。**〔已做,形态与下文有两处不同,见 0015 末尾的修订:助手说不出 N,确认卡在对话里随抽取完成长出来。〕 抽取遇到记忆文档(`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 · 令牌有界面。**〔已做,`feat/tokens-have-a-page`〕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 · 清死代码与陈旧注释。**〔已做,分两刀:#188 那批清了五处死代码与三个占位 crate;`chore/comments-catch-up` 补了还在描述「兜底谓词」的五处注释和一处指向仓库外 DESIGN.md 的引用〕上表最后一行那五处,加上 `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 证明树。**〔已做,`feat/proof-tree`;实际是链不是树,理由见 0002 R2 的修订〕递归展开到叶子 chunk 的 API + 实体面板里可展开的树。数据结构(`fact_derivations`)已够。
-**B2 · 派生 vs 断言矛盾要有信号。** `axiom_violations` 加一种 kind(`derived_contradiction`),进 Review 同一档——0002 写了没做的那一行。(完整方案见 [0017](0017-a-contradiction-points-upstream.md);B2a 引擎与队列已做,B2b 图与面板上的可见性待做。)
-**B3 · `disjointWith` 进消解,合并路径复核签名。** `classify_type_drift` 改从 `entity_type_disjoint` 读(没声明就退回今天的行为,不硬编码);
-`merge_entities` 搬事实前跑一遍与写入时相同的 domain / range 检查,违反的进 `axiom_violations` 而不是静默搬过去。这是 0009 与 0012 各自待做的同一件事。
-〔**签名那一半已提前做了**(#190 / #196 逼出来的,A 线里插队):`ontology::judge_direction` 一处判断,抽取与采纳共用;合并后对搬动过的事实报 `signature` 违规;R0 多一类。剩下 `disjointWith` 进消解那一半仍在这里。〕
-**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 秒是拍的。
-- **对话内 agent 生成的界面走哪个协议。** A1 的确认卡载荷是声明式的(chunk + 三元组列表),渲染器是我们的 React。
- 讨论过 A2UI(2026-09-02):它解决的是「你不控制的客户端渲染你 agent 的 UI」,而 Chat 页两头都是我们的;
- 卖点成立的地方在 MCP 那一侧,那里对应的是 MCP 自己的 UI 扩展,不是 A2UI。**判据是谁的客户端在看**,
- 等 MCP 放开写工具、有外部客户端要渲染这张卡时再定。
-- **要不要把抽取层拆出 `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 谈横向扩展。现在不谈。
+| `disjointWith` is stored; resolution still uses the hard-coded `CONFUSABLE_TYPE_KEYS` | 0009 / 0001 P5 | merge candidates cross declared disjointness |
+| type resolution runs only by hand | 0001 P3a | refining new entities depends on someone clicking |
+| a Chinese base gets an English ontology; `zh.ts` lags, so the interface defaults to English | 0008 / 0004 | Chinese users get English at both ends |
+| `merge_key` does not fold `_by`; narrative verbs enter the ontology | 0007 | one relation in two directions |
+| the 24,000 budget and 40 / 30 / 30 per-chunk counts are untested; the answer key is hand-filled; mixed packs unmeasured | 0006 / 0008 | no "better" can be told from variance |
+| mappings carry no evidence; with several sources every same-name concept goes to the model | 0011 | the calculation is a black box |
+| the mapping probe depends on the `metric` / `dimension` keys | 0009 | a blank base found nothing until the builtin classes of #231; the pack is D2 |
+| no "new phrasings" reminder once auto-extension is off | 0003 | the index is there, the reminder is not |
+| `document.no_text_layer` unwired, no OCR endpoint | 0005 | scanned documents show all green |
+
+## Criteria
+
+1. **Said and done agree.** README line, status line, code comment: when they disagree, fix
+ that before adding features. 0015 is the assistant to the user; this is us to the reader.
+2. **What writes the graph comes before what reads it.** A half-built thing that silently
+ changes the graph is worse than nothing; a half-built read is a missing feature. So
+ `pending_facts` came before the proof tree.
+3. **Measurable first.** `scripts/bench/` and the corpora exist; the external answer key does
+ not, and without it tuning tightens overfitting ([0006](0006-ontology-scale-and-the-prompt.md)).
+4. **Simulation and execution gates wait for the ground.** The README roadmap's first two
+ items are proposals overlaid on the ledger; `pending_facts` (A1), the proof chain (B1) and
+ the contradiction signal (B2) are what they stack on.
+
+## The lines: A → B ∥ C → D → E
+
+**A · Close the seams**, no new concepts. A1 wire 0015 (done). A2 a tokens page and delete
+the three placeholder crates (done; a placeholder is a promise to the reader, and `cargo new`
+takes minutes). A3 dead code and stale comments (done, #188 and `chore/comments-catch-up`).
+A4 README against code, both languages: promise only what has landed.
+
+**B · Finish the reasoning engine**, after A, parallel with C. B1 the R2 proof chain (done,
+#227; a chain, not a tree — see [0002](0002-reasoning-engine.md)). B2 the derived-vs-asserted
+contradiction signal, `axiom_violations` kind `derived_contradiction` (B2a done; B2b, visibility
+on graph and panel, planned — 0017). B3 `classify_type_drift` reads `entity_type_disjoint`
+instead of the hard-coded list, today's behavior when nothing is declared (class kinship from the
+hierarchy landed first, #226). B4 R3 incremental
+maintenance, deferred until a full re-derivation of `ai-timeline-ends` exceeds a threshold
+(proposal: 10 seconds).
+
+**C · Ontology and extraction quality**: build the ruler, then tune. C1 an external answer
+key, Wikidata `P31` as the type answer for Wikipedia articles, generated by script; only then
+can the 0008 mixed-pack comparison (`run.mjs --packs`) and the 0006 budget curve run. C2 type
+resolution queued after extraction, auto-applying only the "within the original subtree"
+tier; after C1, or it scales noise. C3 with `ontology_lang = zh`, generate Chinese
+`description` rows by LLM (the line the model reads follows the corpus,
+[0004](0004-language-and-localization.md)), IRIs and `label` untouched; catch `zh.ts` up and
+put `navigator.language` back into `detect()`. C4 fold `_by` in `merge_key` and let the
+synonym-merging LLM call review narrative verbs, reversibly. C5 "N new phrasings since last
+time" from `ontology_misses` where `dismissed_at IS NULL`.
+
+**D · Semantic layer and data questions**, after C1. D1 `concept_mappings` gains `evidence`
+(the schema-doc chunk ids read during probing). D2 a "Utopia semantic layer" pack with IRIs,
+optional and replaceable; `mappings.rs` finds types by IRI. D3 one mounted source → only its
+mappings, several → all, in `mappings::confirmed`. D4 the MySQL wire protocol (TiDB /
+OceanBase / Doris / StarRocks, `sqlparser` dialect switch); the lakehouse engines came first.
+
+**E · Enterprise delivery**, the v0.2 bar, can interleave. Credentials encrypted at rest
+(SECURITY.md promises it before 1.0) — small, do it early. OIDC SSO; backup and restore; a
+hundred-thousand-document benchmark (numbers beat design). `document.no_text_layer` together
+with an OCR endpoint (docling-serve sidecar). `instant` precision only when the trigger in
+[0013](0013-a-source-should-hand-over-its-history.md) fires.
+
+**Deferred: simulation engine and execution gate** (criterion 4); a separate record once A
+and B are done.
+
+## A new convention
+
+The PR that implements a record updates its status line. 0011, 0014 and 0015 fell behind the
+code in the same PR by the same author, so the PR template asks which record the change
+implements or overturns and whether the status line moved. Written into the [README](README.md).
+
+## Open questions
+
+- Does the A1 gate hold only memories or every single-item interactive write? Only `remember`
+ today; a hand-added edge should take the same table.
+- Are C3's generated descriptions an exception to "keep the original text"? Leaning towards a
+ projection — rerunnable, disposable — with the IRI and English description kept.
+- B4's 10-second threshold is a guess.
+- Which protocol for agent-generated interfaces in chat. A2UI (discussed 2026-09-02) solves
+ "a client you do not control renders your agent's UI"; on the Chat page both ends are ours,
+ on the MCP side the counterpart is MCP's own UI extension. Decide when an external client
+ needs the A1 card.
+- Whether to split extraction (about 6,500 lines) out of `utopia-server`. Decided not to
+ (2026-09-02): the only real gain is testing pure functions without the server, which their
+ unit tests already do. Split when something cannot be tested without the server; the
+ connector boundary waits for Feishu.
+- After the benchmark: where the single-process worker and embedded Tantivy hit their ceiling
+ decides whether v0.2 discusses horizontal scaling.
diff --git a/docs/decisions/0017-a-contradiction-points-upstream.md b/docs/decisions/0017-a-contradiction-points-upstream.md
index faecada8..f321908d 100644
--- a/docs/decisions/0017-a-contradiction-points-upstream.md
+++ b/docs/decisions/0017-a-contradiction-points-upstream.md
@@ -123,8 +123,8 @@ chain. Here a person sees "the engine could have drawn this edge, and what stopp
**Edges on the graph**:
-- A contested assertion switches to the **alert colour**, edge and all, with no reliance on
- a node ring. The request was explicit: a ring sits on the node while the edge stays grey,
+- A contested assertion switches to the **alert color**, edge and all, with no reliance on
+ a node ring. The request was explicit: a ring sits on the node while the edge stays gray,
and peripheral vision cannot tell them apart.
- A blocked derivation is drawn as a **ghost edge**: the same hue mixed toward `EDGE_DIM`
(under premultiplied blending alpha cannot darken an edge; only the RGB can be mixed — see
@@ -133,14 +133,14 @@ chain. Here a person sees "the engine could have drawn this edge, and what stopp
program is introduced for this.
- The hover label chip gets a "⚠" prefix, and the tooltip states the dispute.
-**Colour**: one new token, `--u-contest`, set to **#ff6a3d** (hot coral orange). It has to
-stand apart from three colours already in use: derived edges are gold
+**Color**: one new token, `--u-contest`, set to **#ff6a3d** (hot coral orange). It has to
+stand apart from three colors already in use: derived edges are gold
(`rgb(231,197,124)`), warning chips are amber (`--u-warn` #f2b66d, too close to gold to
-double as an edge colour), and danger is pink (`--u-danger` #ff9daf, reserved for
+double as an edge color), and danger is pink (`--u-danger` #ff9daf, reserved for
destructive actions). Coral orange is bright enough on the dark ground, its hue is far from
-all three, and it is no common type colour (the type palette leans blue, green and violet).
-Edge colour `rgba(255,106,61,0.55)`; ghost edge `lerp(#ff6a3d, EDGE_DIM, 0.55)`. This is
-the only new colour; chips on the Ontology and Review pages use the same token.
+all three, and it is no common type color (the type palette leans blue, green and violet).
+Edge color `rgba(255,106,61,0.55)`; ghost edge `lerp(#ff6a3d, EDGE_DIM, 0.55)`. This is
+the only new color; chips on the Ontology and Review pages use the same token.
### 4. Data
@@ -196,7 +196,7 @@ B1 (#227) merges first after a rebase; B2a branches from it.
thousand.
- **Granularity of `accepted`**: per pair (one derivation against one assertion). An
assertion hit by several derivations needs several clicks; aggregating the exemption per
- assertion would generalise "this axiom does not apply to this assertion" too far. Per
+ assertion would generalize "this axiom does not apply to this assertion" too far. Per
pair first, measure later.
- **Could ghost edges be too many?** Their number is bounded by the (capped) violation
count, so it should stay manageable; failing that, draw them only when a related node is
diff --git a/docs/decisions/README.md b/docs/decisions/README.md
index d14c9f94..90b28d6e 100644
--- a/docs/decisions/README.md
+++ b/docs/decisions/README.md
@@ -1,59 +1,52 @@
-# 决策记录
+# Decision records
-代码记录了**做成什么样**,git 记录了**什么时候改的**。两者都不记录**为什么这样而不是那样**,以及**哪些路走过发现是死路**。这个目录记那个。
+Code records what was built and git records when it changed. Neither records why it was built this way and which roads turned out to be dead ends. This directory does.
-判断标准:如果半年后有人(包括我们自己)看着某段代码问"当初为什么不直接……",而答案不在代码里,那就该有一篇。
+The test for writing one: if someone (including us) looks at a piece of code in six months and asks "why not simply…", and the answer is not in the code, there should be a record.
-## 约定
+## Conventions
-**文件名** `NNNN-短横线英文标题.md`,四位序号,按创建顺序递增,不留空号。序号只是稳定的引用锚点,不表示优先级。
+**File names** are `NNNN-short-english-title.md`, four digits, increasing in creation order, no gaps. The number is a stable anchor for references and says nothing about priority.
-**目录扁平**。在出现第二种性质不同的文档之前,不建子目录。
+**The directory is flat.** No subdirectories until a second kind of document appears.
-**修订就地留痕,不静默改写**。结论变了——尤其是因为查证推翻了原判断——**在原处保留「修订记录」块**写清:原本是什么、为什么错、依据什么改的。不要把错误的那版删干净。
+**Revisions stay in place.** When a conclusion changes, especially because checking the code overturned it, keep a dated revision note where the original claim stood: what it said, why it was wrong, what changed it. The ledger this product keeps never updates a fact in place; a correction inserts a new row that supersedes the old one, because the change of mind is information. Records follow the same rule: knowing "we assumed a range would take effect immediately, checked, and found it never did" tells the next reader what to check first.
-> 这条不是文档洁癖,是同一条产品原则。我们的账本从不原地 UPDATE 事实,纠正是插入新行 + `supersedes` 旧行,因为**认知变更本身是信息**。决策记录同理:知道"我们曾经以为 range 能立刻生效,查完发现一条都没有",比只看到最终结论有用得多——它告诉你下次该先查什么。
+**When too much has changed**, write a new record and mark the old one `superseded by NNNN` at the top instead of rewriting it.
-**结论变得太多时**,另起一篇并在旧篇顶部标 `已被 NNNN 取代`,而不是把旧篇改成新的。
+**The PR that implements a record updates its status line.** Three status lines once lagged behind the code in the same PR, written by the same person. So the PR description answers one question: which record does this change implement or overturn, and is its status line updated. (Added 2026-09-02, from [0016](0016-close-the-open-seams-before-cutting-new-ones.md).)
-**状态行由实现它的 PR 负责更新。** 0011、0014、0015 三篇的状态行曾落后于同一个 PR 里的代码——写记录的人和写代码的人是同一个人、同一个提交,仍然漏了。所以 PR 描述里要答一句:这个改动实现或推翻了哪篇决策记录,状态行改了没有。(2026-09-02 加,出处见 [0016](0016-close-the-open-seams-before-cutting-new-ones.md)。)
+**Line numbers drift and file names change.** Prefer function, table and constant names over `file.rs:123`. Migrations were consolidated from 53 files into one per domain (#130, #131); older references to migration files are by domain.
-**行号会漂,文件名会换。** 正文里的 `file.rs:123` 是成文时的坐标,不保证仍然准确;迁移在 #130 / #131 从 53 份折成 10 份、一个域一份,所以 2026-08-31 之前写的迁移文件名都要按域重找。引用时优先写函数名、表名、常量名。
+**Language: English.** The first sixteen records were written in Chinese and condensed into English on 2026-09-03; the Chinese originals remain in git history. Code comments are still Chinese; UI, README and records are English.
-**语言**:2026-09-03 起新记录用英文(0017 起),读者已经包括外部贡献者;此前的十六篇仍是中文,与代码注释一致,是否回译等有人需要时再定。
+## Index
-## 索引
-
-| | 文档 | 状态 |
+| | Record | Status |
|---|---|---|
-| 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 证明链到原句(B1)· **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 · 守卫已扩到采纳与合并(#190 / #196),另两条待做仍在 |
-| 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 只读五工具 · 令牌页在账户层(A2)· 误导性的占位 crate 已删 |
-| 0015 | [记下一句话,不等于断言一个事实](0015-recording-a-sentence-is-not-asserting-a-fact.md) | 已实施 · 记忆抽出的事实进 `pending_facts`,Review 新档 + 跟在 remember 步骤后的确认卡 · `remember` 重新打开 · MCP 放开写是下一刀 |
-| 0016 | [先把开着的口子收上,再开新的](0016-close-the-open-seams-before-cutting-new-ones.md) | 规划中 · v0.1.0 之后的排期:A 收口 → B 推理机 ∥ C 尺子与本体 → D 语义层 → E 企业交付;模拟引擎后置 |
-| 0017 | [A contradiction points at an error upstream](0017-a-contradiction-points-upstream.md) | B2a 已实现(引擎与队列:逐条封顶、按规则对聚合、卡片给线索与修法)· B2b 待做:争议在图和面板上原地可见(新警戒色)|
-| 0018 | [The lakehouse is one protocol away](0018-the-lakehouse-is-one-protocol-away.md) | 已实施 · 问数引擎扩到 HTTP 族:Trino(Iceberg / Delta / Hive)、Databricks、Snowflake,scheme 决定引擎,只有回放测试 · MaxCompute 未做 |
-
-## 不是决策记录的那些
-
-**[../pipeline.md](../pipeline.md) —— 一份文档如何变成图谱。** 决策记录讲「为什么这样
-而不是那样」;那一篇讲「东西怎么流的、在哪一步会被丢掉」,带五张 mermaid 图(2026-09-02 加了公理那一张)。
-新来的人先看它,再回来看这里的理由。
-
-这是本目录约定里说的「第二种性质不同的文档」。它没进子目录——放在 `docs/` 根上,
-`.gitignore` 里单独开口,跟 `decisions/` 并列。
-
-## 不放这里的东西
-
-`docs/` 根目录是**本地草稿区**(`.gitignore` 里 `/docs/*` 忽略,只对 `/docs/decisions/` 开口)。随手的调研笔记、临时清单、跑测试的中间产物放那儿,不入库。等某份草稿沉淀出了值得留的判断,再作为一篇决策记录搬进来。
+| 0001 | [Ontology import and governance](0001-ontology-import-and-governance.md) | In progress · P0–P2c built; the P3 budget built, P3a by hand only; P3b built in a different shape; P4b / P4c pending; P5 delivered by 0002; criterion 2 half overturned by 0012 |
+| 0002 | [Reasoning engine](0002-reasoning-engine.md) | R0 checker and R1 materialization (KB switch, default off) built; R2 proof chain (#227); contradiction signals per 0017; R3 incremental maintenance not built |
+| 0003 | [The ontology grows out of the corpus](0003-ontology-growth-loop.md) | Built and running, default on · starting point rewritten by 0010 and the retired seeds · dismissal redone per 0007 · the "new phrasings" reminder pending |
+| 0004 | [Language follows the reader of each text](0004-language-and-localization.md) | Built · UI strings, coded server errors, ontology description language and the locale of generated text · the browser language is not guessed yet |
+| 0005 | [The alert center](0005-alert-center.md) | Built · five alert kinds live, search and paging in the panel · `document.no_text_layer` still unwired |
+| 0006 | [Ontology scale and the extraction prompt](0006-ontology-scale-and-the-prompt.md) | Built · the character budget (24,000) and per-chunk retrieval live, values untested · answer keys still hand-filled |
+| 0007 | [Counting decides what becomes a relation](0007-who-decides-what-becomes-a-relation.md) | Built · adoption decided by counting (`MIN_DOCS = 2`, `MIN_SIGNALS = 3`), proposals persist (#112) · narrative verbs and `_by` folding still open |
+| 0008 | [Ontology packs as the cold start](0008-ontology-packs-as-cold-start.md) | Built · five packs embedded, multi-select at creation, schema.org by default · three open questions stay open; Chinese labels got worse |
+| 0009 | [An undecided type stays empty](0009-no-type-is-a-type.md) | Implemented · `type_id` nullable, builtin classes gone · kin classes go to Review (#226), `disjointWith` still unread by resolution · `metric` / `dimension` builtin on demand (#231) |
+| 0010 | [An unnamed relation stays empty](0010-no-relation-is-no-relation.md) | Implemented · `predicate_id` nullable, `related_to` gone, wording recovered by `fact_surface_predicate` · follow-ups done with 0011 |
+| 0011 | [A mapping is configuration](0011-a-mapping-is-not-a-fact.md) | Implemented (#126 / #140 / #148) · Review flow and revision history rebuilt · the evidence chain not built |
+| 0012 | [The ontology is a contract](0012-the-ontology-is-a-contract-not-a-suggestion.md) | Implemented · violation rate 57% → 4%, reversals 39 → 0 · guard extended to adoption and merge (#190 / #196) · reified-shell filter at pack import open |
+| 0013 | [A source hands over its history](0013-a-source-should-hand-over-its-history.md) | Implemented for GitHub, Jira and Notion (#134 / #135 / #213) · Feishu and Confluence not started · `instant` precision not triggered |
+| 0014 | [Identity from the person, scope from the token](0014-identity-from-the-person-scope-from-the-token.md) | Implemented (#180) · five read-only MCP tools over Streamable HTTP · tokens page at `/account/tokens` · `can_write` still hard-coded false |
+| 0015 | [A recorded sentence waits for a nod](0015-recording-a-sentence-is-not-asserting-a-fact.md) | Implemented · memory facts wait in `pending_facts`, nod queue and chat card, `remember` reopened · MCP write is the next cut |
+| 0016 | [Close the open seams before cutting new ones](0016-close-the-open-seams-before-cutting-new-ones.md) | In progress · A done · B1 and B2a done, B2b and `disjointWith` open · C untouched · D2 worked around (#231); the lakehouse landed ahead of D4 (#239) |
+| 0017 | [A contradiction points at an error upstream](0017-a-contradiction-points-upstream.md) | B2a implemented: engine and queue, per-item cap, aggregation by rule pair, cards with clues and repairs (#238) · B2b planned: disputes visible on the graph and in the panel |
+| 0018 | [The lakehouse is one protocol away](0018-the-lakehouse-is-one-protocol-away.md) | Implemented: Trino (Iceberg / Delta / Hive), Databricks and Snowflake behind the same trait, scheme picks the engine (#239) · replay tests only, real clusters wanted (#240–#242) · MaxCompute waits |
+
+## Not a decision record
+
+**[../pipeline.md](../pipeline.md), how a document becomes a graph.** Records explain why; that page explains how things flow and where they get dropped, with five mermaid diagrams. Newcomers read it first, then come back here for the reasons. It is the "second kind of document" the conventions mention, kept at the `docs/` root beside `decisions/`.
+
+## What does not belong here
+
+The `docs/` root is a local scratch area (`/docs/*` is git-ignored except `/docs/decisions/`). Research notes, temporary checklists and test output live there and stay out of the repository. When a draft settles into a judgment worth keeping, it moves here as a record.
diff --git a/docs/pipeline.md b/docs/pipeline.md
index 355e7878..34cb2b9e 100644
--- a/docs/pipeline.md
+++ b/docs/pipeline.md
@@ -1,34 +1,31 @@
-# 一份文档如何变成图谱
+# How a Document Becomes a Graph
-**这一篇不讲为什么,讲东西怎么流的。** 「为什么这样而不是那样」在 [decisions/](decisions/README.md);
-这里回答另一个问题:**我改的这一行,处在整条链的哪个位置,它上游给我什么、我不给下游什么会断在哪。**
+**This page describes how a document flows through the pipeline.** The reasons behind each choice live in [decisions/](decisions/README.md). This page answers a different question: **where the line you are editing sits in the chain, what upstream hands it, and what breaks downstream if you hand nothing on.**
-> 图上最值钱的不是箭头,是**箭头断掉的地方**。每一段末尾都有一节「这里会丢东西吗」,
-> 列的是代码里真实存在的丢弃点与它们在库里的落点——不是"理论上可能失败",
-> 是**已经在 `extraction_drops` 里数得出来的那几种**。
+> The most valuable thing on the map is **where the arrows break**. Every stage ends with a "Where this stage drops things" section listing the drop points that actually exist in the code and where they land in the database: the kinds you can already count in `extraction_drops`, rather than theoretical failures.
-## 全景
+## Overview
```mermaid
flowchart TB
- U[上传 / 来源同步] --> P[解析<br/>parsers.rs]
- P --> C[分块<br/>1200 字符 · 重叠 150]
- C --> E1[嵌入<br/>chunks.embedding]
- E1 --> RDY[(文档 ready<br/>可搜可问)]
- E1 --> X[抽取<br/>每块一次 LLM]
- X --> ENT[实体消解<br/>这一条是谁]
- X --> FCT[事实落库<br/>双时态账本]
- ENT --> ADJ[裁决<br/>攒批一次 LLM]
- ADJ --> MRG[合并 / 保持分开]
- FCT --> TR[类型消解<br/>这一条是什么]
- FCT --> GROW[本体增长<br/>词表外的说法回流成提案]
- MRG --> G[(图谱)]
+ U[Upload / source sync] --> P[Parse<br/>parsers.rs]
+ P --> C[Chunk<br/>1200 chars · overlap 150]
+ C --> E1[Embed<br/>chunks.embedding]
+ E1 --> RDY[(Document ready<br/>searchable and askable)]
+ E1 --> X[Extract<br/>one LLM call per chunk]
+ X --> ENT[Entity resolution<br/>who this mention is]
+ X --> FCT[Facts to store<br/>bitemporal ledger]
+ ENT --> ADJ[Adjudication<br/>one batched LLM call]
+ ADJ --> MRG[Merge / keep apart]
+ FCT --> TR[Type resolution<br/>what this entity is]
+ FCT --> GROW[Ontology growth<br/>out-of-vocabulary terms become proposals]
+ MRG --> G[(Graph)]
TR --> G
- GROW --> ONT[(本体)]
- ONT -.喂回.-> X
- G --> R0[一致性检查<br/>公理 vs 事实 · 不写库]
+ GROW --> ONT[(Ontology)]
+ ONT -.feeds back.-> X
+ G --> R0[Consistency check<br/>axioms vs facts · writes nothing]
ONT --> R0
- G --> R1[物化推导<br/>开关 · 派生另存]
+ G --> R1[Materialized inference<br/>opt-in · derived facts stored separately]
ONT --> R1
R1 --> G
@@ -37,274 +34,229 @@ flowchart TB
style ONT fill:#2d4a5a,color:#fff
```
-**两段式是有意的**:嵌入完成即 `ready`,搜索与问答立刻可用,抽取在后台排队。
-一篇长文档的图谱要几分钟才长出来,但它在几十秒内就能被搜到。
+**The two-phase split is deliberate.** A document is `ready` as soon as embedding finishes; search and Q&A work immediately while extraction queues in the background. A long document takes minutes to grow its graph but is searchable within seconds.
-**本体那条回流虚线是这套东西的循环**:抽取用本体,抽取遇到本体没有的说法就把原词记下来,
-提案回流补进本体,下一批文档的抽取就用上了。见 [0003](decisions/0003-ontology-growth-loop.md)。
+**The dotted line back into extraction is the loop.** Extraction uses the ontology; when it meets a term the ontology lacks, it records the original wording; proposals flow back into the ontology; the next batch of documents is extracted with it. See [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)。
+**Where the ontology comes from.** A new database seeds nothing. The starting point is an optional prebuilt pack (schema.org checked by default; also W3C Org, PROV-O, FOAF, IOF Core), a user-imported OWL file, or nothing at all. An empty ontology still extracts; an entity without a type simply has no type. See [0008](decisions/0008-ontology-packs-as-cold-start.md) and [0009](decisions/0009-no-type-is-a-type.md).
-**最下面那两个框是本体的公理在干活**:一致性检查不写 `facts`,只把矛盾摆出来(Review 的 violations / defects 两档);
-物化推导默认关,打开后派生事实另存一张表、图上金色,永远不闭合任何断言事实。见第四节。
+**The bottom two boxes are the ontology's axioms at work.** The consistency check never writes `facts`; it only surfaces contradictions (the Review page's two tiers, violations and defects). Materialized inference is off by default; when on, derived facts go to a separate table, show as gold on the graph, and never close any asserted fact. See section 4.
---
-## 一、抽取一个分块
+## 1. Extracting a Chunk
```mermaid
flowchart TB
- subgraph 提示词
- B{本体装得下预算吗?}
- B -->|装得下| FULL[全量铺<br/>小本体的老路]
- B -->|装不下| RET[按这一块的向量检索<br/>约 40 类 / 30 关系 / 30 属性<br/>+ 命中类的祖先一起铺]
+ subgraph prompt [Prompt]
+ B{Does the ontology fit the budget?}
+ B -->|yes| FULL[Lay out the whole ontology<br/>the small-ontology path]
+ B -->|no| RET[Retrieve by the chunk vector<br/>about 40 classes / 30 relations / 30 attributes<br/>+ ancestors of the hit classes]
end
FULL --> LLM[LLM]
RET --> LLM
- CHK[分块正文 + 本文档已认下的实体] --> LLM
- LLM --> J{输出的每一条}
- 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[谓词留空<br/>原词落 proposed_predicate]
+ CHK[Chunk text + entities already accepted in this document] --> LLM
+ LLM --> J{Each item in the output}
+ J -->|entities| EN[Entity<br/>type picked from the list<br/>specific_type free text]
+ J -->|predicate matches an attribute| AT[Attribute fact<br/>value normalized by datatype]
+ J -->|predicate matches a relation| RL[Relation fact]
+ RL --> DIR{Subject and object types<br/>match the signature?}
+ DIR -->|yes| OK[Stored]
+ DIR -->|subject violates, object fits| SWAP[Swap subject and object per the signature<br/>record direction_corrected]
+ DIR -->|swap is also invalid| NOP[Predicate left empty<br/>subject, object, time and evidence kept]
+ J -->|out of vocabulary + literal value| LIT[Value into object_value<br/>original term into proposed_predicate]
+ J -->|out of vocabulary + entity object| FB[Predicate left empty<br/>original term into proposed_predicate]
style LLM fill:#3a3a5a,color:#fff
```
-**`specific_type` 是这一步最容易被忽略的输出**:自由文本、不校验、不入本体,就是模型自己
-对这个实体的说法("vector database software")。类型消解靠它把任务从「读懂这是什么」
-换回「本体里哪个类叫这个名字」。没有它,实测 17 个实体的 `proposed_type` 全是空的——
-因为清单里总有个"差不多"的,模型选了它,心里那个更准的说法就此丢失。
+**`specific_type` is the easiest output to overlook.** Free text, unvalidated, never entered into the ontology: it is the model's own description of the entity ("vector database software"). Type resolution uses it to turn the task from "understand what this is" into "which class in the ontology has this name". Without it, a test run left `proposed_type` empty on all 17 entities: the list always has something close enough, the model picks it, and the more precise description is lost.
-**词表外的两条路都不丢东西**:带字面值的落 `object_value`(而不是凭空造一个叫「2015」的实体),
-带实体宾语的**谓词留空**——不是降级成一个叫「有关联」的关系,那是断言不是含糊([0010](decisions/0010-no-relation-is-no-relation.md))。
-两者的原词都进 `fact_evidence.proposed_predicate`,那是这条事实身上唯一还留着原意的地方,显示时由 `fact_surface_predicate()` 取回。
+**Neither out-of-vocabulary path loses anything.** A literal value goes to `object_value` instead of becoming an entity named "2015". An entity object leaves the **predicate empty** instead of degrading into a relation called "related to", which would be an assertion rather than vagueness ([0010](decisions/0010-no-relation-is-no-relation.md)). In both cases the original term goes to `fact_evidence.proposed_predicate`, the one place on the fact that still carries the original meaning; `fact_surface_predicate()` reads it back for display.
-**命中的关系还要过一道签名**:本体声明了 `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)。
+**A matched relation still passes a signature check.** The ontology declares `employee (organization → person)`, and the model still writes `Musk employee Microsoft`; three rounds of prompt tuning could not suppress it, because English "X is an employee of Y" is too strong. So the write path corrects it: if the subject violates the domain and the object fits, swap them and record `direction_corrected`, never silently. If the swap is also invalid (`OpenAI affectedBy …`, a medical-test predicate in schema.org), drop the predicate and keep subject, object and evidence. Argument order is an encoding convention of the key, not a claim about the world, so here the ontology enforces. See [0012](decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md).
-### 这里会丢东西吗
+### Where this stage drops things
-会。十二种原因码,全部记进 `extraction_drops`,界面上可见(其中一种不是丢弃,是留痕):
+Eleven reason codes, all recorded in `extraction_drops` and visible in the UI (one is a trace, not a drop):
-| 原因 | 什么时候 |
+| Reason | When |
|---|---|
-| `truncated_reply` | 模型的输出被截断,这一块整块作废 |
-| `malformed_item` | 一条事实格式不对——**只丢这一条**,不丢整块(#127) |
-| `not_an_entity_name` | 「实体名」是一整句话(按词数 + 限定动词判,#143) |
-| `low_confidence` | 模型自报置信度低于阈值 |
-| `subject_not_declared` | 主语没在 `entities` 里声明——关系与属性两条路径**都**记 |
-| `attr_domain_mismatch` | 属性挂到了 domain 之外的类上(沿父类 DAG 上溯仍不匹配) |
-| `attr_no_value` / `attr_datatype` | 属性事实没给值,或值换算不出声明的 datatype |
-| `object_missing` | 关系事实没有宾语 |
-| `direction_corrected` | **不是丢弃**:主宾按签名对调了,记下来是为了不静默 |
-| `domain_mismatch` | 对调也不合法,谓词被丢掉(主宾与证据留下) |
-
-**`attr_domain_mismatch` 是最贵的一种**:它在落地当场丢弃,而事后改类救不回来——
-那条事实从没写入过,只能重抽。
-
-从前还有一种 `fallback_relation_missing`(兜底关系被删了就整条消失)——随 `related_to` 一起没了。
+| `truncated_reply` | The model's output was cut off; the whole chunk is discarded |
+| `malformed_item` | One fact is malformed; **only that item** is dropped, not the chunk (#127) |
+| `not_an_entity_name` | The "entity name" is a whole sentence (judged by word count and finite verbs, #143) |
+| `low_confidence` | The model's self-reported confidence is below the threshold |
+| `subject_not_declared` | The subject is not declared in `entities`; recorded on **both** the relation and attribute paths |
+| `attr_domain_mismatch` | The attribute is attached to a class outside its domain, even after walking up the parent DAG |
+| `attr_no_value` / `attr_datatype` | The attribute fact has no value, or the value cannot be converted to the declared datatype |
+| `object_missing` | The relation fact has no object |
+| `direction_corrected` | **Not a drop**: subject and object were swapped per the signature; recorded so it is never silent |
+| `domain_mismatch` | The swap is also invalid; the predicate is dropped (subject, object and evidence stay) |
+
+**`attr_domain_mismatch` is the most expensive.** It drops the fact at write time, and retyping the entity later does not recover it: the fact was never written and can only be re-extracted.
---
-## 二、实体消解:这一条是谁
+## 2. Entity Resolution: Who This Mention Is
```mermaid
flowchart TB
- M[一次 mention<br/>类型 + 名字 + 分块向量] --> EQ[等值召回<br/>canonical_name 或 aliases 相等]
- EQ --> S{画像相似度}
- S -->|0.55 及以上| ATT[并进已有实体<br/>更新画像]
- S -->|0.35 到 0.55| NEW1[新建 + 入审阅队列]
- S -->|低于 0.35| NEW2[新建,不打扰队列]
- EQ -->|一个都没有| NEW3[新建]
+ M[One mention<br/>type + name + chunk vector] --> EQ[Equality recall<br/>canonical_name or aliases equal]
+ EQ --> S{Profile similarity}
+ S -->|0.55 and above| ATT[Attach to the existing entity<br/>update its profile]
+ S -->|0.35 to 0.55| NEW1[Create + enqueue for review]
+ S -->|below 0.35| NEW2[Create, queue untouched]
+ EQ -->|no match| NEW3[Create]
NEW1 --> CT
NEW2 --> CT
- NEW3 --> CT[包含关系召回<br/>只在新建时跑一次]
- CT --> Q[(审阅队列<br/>pending)]
- Q --> AD[裁决<br/>攒批一次 LLM]
- AD -->|同一个| ME[合并<br/>名字进 aliases<br/>事实搬过去]
- AD -->|不是| KP[保持分开]
- ME --> RD[把该 source 上其余 pending<br/>改指到合并目标]
+ NEW3 --> CT[Containment recall<br/>runs once, on creation only]
+ CT --> Q[(Review queue<br/>pending)]
+ Q --> AD[Adjudication<br/>one batched LLM call]
+ AD -->|same| ME[Merge<br/>name into aliases<br/>facts moved over]
+ AD -->|different| KP[Keep apart]
+ ME --> RD[Redirect the other pending pairs on that source<br/>to the merge target]
RD --> Q
style AD fill:#3a3a5a,color:#fff
style Q fill:#2d4a5a,color:#fff
```
-**三个阈值分三档**(`SIM_ATTACH = 0.55`、`SIM_NEW = 0.35`):像得没话说就并,
-像得可疑就新建但入队,不像就新建且不打扰队列。**宁分勿合**——错合的代价是两个实体的
-事实混在一起,比多一个实体贵得多。
+**Two thresholds, three tiers** (`SIM_ATTACH = 0.55`, `SIM_NEW = 0.35`): clearly the same attaches; suspiciously similar creates a new entity and queues it; dissimilar creates one without touching the queue. **Prefer splitting over merging.** A wrong merge mixes two entities' facts together, which costs far more than one extra entity.
-**包含关系召回**(`Holmes` ⊂ `Sherlock Holmes`)补等值召回的盲区:前缀枚举不完,
-简称会静默变成第二个实体。它有三条约束:较短那个名字至少 4 字符(低于此多是通名)、
-单次最多产出 4 对、SQL 侧多扫 16 行(硬互斥类型在 Rust 侧才筛得掉)。
+**Containment recall** (`Holmes` ⊂ `Sherlock Holmes`) covers the blind spot of equality recall: prefixes cannot be enumerated, so a short name would silently become a second entity. Three constraints: the shorter name is at least 4 characters (below that it is usually a generic word), at most 4 pairs per run, and SQL scans 16 extra rows because hard-disjoint types are only filtered on the Rust side.
-**改指那一步**是整张图里最不直觉的一环,也是最容易被误删的:合并之后,涉及被合实体的
-其余待审阅对**不能关掉**,要改指到合并目标。理由见下。
+**The redirect step** is the least intuitive part of the graph and the easiest to delete by mistake. After a merge, the other pending pairs that involve the merged-away entity **must not be closed**; they are redirected to the merge target. The reason follows.
-### 这一段修过三个洞,三个都是同一份语料照出来的
+### Three Holes, One Corpus
-用《福尔摩斯冒险史》前六篇(`scripts/bench/corpora/holmes.json`)连跑四次,每次修一层:
+Four runs over the first six stories of *The Adventures of Sherlock Holmes* (`scripts/bench/corpora/holmes.json`), each fixing one layer:
-| | 原始 | 修同类型 | 加别名召回 | 加改指 |
+| | Baseline | Same-type fix | Alias recall | Redirect |
|---|---|---|---|---|
-| 已合并实体 | 14 | 37 | 47 | **57** |
-| `Holmes` 并入 | ✗ | ✓ | ✓ | ✓ |
-| `Mr. Holmes` 并入 | ✗ | ✗ | ✗ | **✓** |
+| Entities merged | 14 | 37 | 47 | **57** |
+| `Holmes` merged | ✗ | ✓ | ✓ | ✓ |
+| `Mr. Holmes` merged | ✗ | ✗ | ✗ | **✓** |
-**第一层**:`classify_type_drift` 没有「两个类型相同」这一档,`person × person` 落进
-`Disjoint`——"永不可能是同一个"。那个函数生来服务「类型漂移」(同名被抽成两种类型),
-那里两边相同不会发生;后来被包含关系召回借去当相容性判据,**而那里两边相同才是常态**。
-全文最明显的同指关系一对都没进过队列,十二个既有单元测试全在测跨类型。
+**Layer one.** `classify_type_drift` had no tier for "both types equal", so `person × person` fell into `Disjoint`, "can never be the same". The function was written for type drift (one name extracted as two types), where equal sides never occur; containment recall later borrowed it as a compatibility test, where equal sides are the norm. The most obvious coreferences in the text never reached the queue, and all twelve existing unit tests covered cross-type cases.
-**第二层**:召回只看 `canonical_name`。合并把名字搬进 `aliases`,于是**每成功合并一次
-就拆掉一条桥**——`Holmes` 并入之后,后来的 `Mr. Holmes` 跟 `Sherlock Holmes` 谁也不含谁,
-本来正是靠 `Holmes` 桥接。修好第一层反而让第二层的漏显形了。
+**Layer two.** Recall looked only at `canonical_name`. A merge moves the name into `aliases`, so every successful merge removed a bridge: once `Holmes` was merged, the later `Mr. Holmes` and `Sherlock Holmes` contained neither the other, and `Holmes` had been the bridge. Fixing layer one exposed layer two.
-**第三层**:合并会把涉及被合实体的其余 pending 审阅关成 `superseded by merge`,
-代码注释里的理由是"疑点若仍在会由后续 mention 重新提起"。**那句是错的**:包含关系召回
-只在新建实体时跑,而这些实体早就存在、不会再被新建。关掉即永久关闭。现在改指到合并目标,
-只有两类真正过时的才关——重定向后成自环的,和目标对已在队列里的。
+**Layer three.** A merge closed the other pending reviews involving the merged-away entity as `superseded by merge`; the code comment claimed a later mention would raise the doubt again. That was wrong: containment recall runs only when an entity is created, and these entities already exist, so closing was permanent. Now they are redirected to the merge target, and only two genuinely stale kinds are closed: pairs that become self-loops after the redirect, and pairs whose target pair is already queued.
-**这三层是一层套一层的**:不修第一层看不见第二层,不修第二层看不见第三层。
-基准语料的价值不在第一次跑出的数字,在**每修一次就再照出下一层**。
+**Each layer hid the next.** The value of the benchmark corpus is the next layer it exposes after every fix, more than the first number it produces.
-### 这里会丢东西吗
+### Where this stage drops things
-不会丢事实,但会**留下不该分开的实体**。两个已知缺口:
+No facts are lost, but **entities that belong together can stay apart**. Two known gaps:
-- 两个名字既不互相包含、又没有共同别名做桥(`启明 X7 加速卡` vs `启明 X7 推理加速卡`)。
- 要三元组相似度,而 `CREATE EXTENSION pg_trgm` 需要超级权限,本仓库是受限角色连库。
-- 单次包含关系召回上限 4 对:一个通名可能被几十个实体包含,全放进去会淹掉队列。
+- Two names that neither contain each other nor share an alias as a bridge (`启明 X7 加速卡` vs `启明 X7 推理加速卡`). Trigram similarity would cover this, but `CREATE EXTENSION pg_trgm` needs superuser and this repository connects with a restricted role.
+- Containment recall is capped at 4 pairs per run. A generic name may be contained by dozens of entities, and admitting them all would flood the queue.
-合并本身**可撤销**(`entity_merges` 记着改之前的一切,`revert_merge` 放回去)。
+A merge itself is **reversible**: `entity_merges` records everything as it was, and `revert_merge` restores it.
---
-## 三、本体消解:这一条是什么
+## 3. Type Resolution: What This Entity Is
```mermaid
flowchart TB
- subgraph 抽取留下的线索
- PT[proposed_type<br/>词表外的类型名]
- ST[specific_type<br/>模型自己的说法]
- PP[proposed_predicate<br/>词表外的谓词原词]
+ subgraph clues [Clues left by extraction]
+ PT[proposed_type<br/>out-of-vocabulary type name]
+ ST[specific_type<br/>free-text description from the model]
+ PP[proposed_predicate<br/>out-of-vocabulary predicate, original term]
end
PT --> TR
ST --> TR
- PP --> GP[本体提案<br/>检索候选 + 裁决]
- TR[类型消解] --> C1[候选一<br/>画像 → 类的描述]
- TR --> C2[候选二<br/>语境近邻的类当票投]
- C1 --> AD2{裁决}
+ PP --> GP[Ontology proposal<br/>retrieve candidates + adjudicate]
+ TR[Type resolution] --> C1[Candidate one<br/>profile → class descriptions]
+ TR --> C2[Candidate two<br/>classes of context neighbors vote]
+ C1 --> AD2{Adjudication}
C2 --> AD2
- AD2 -->|在原类子树里| AUTO[自动改类<br/>entity_retypes]
- AD2 -->|跨了分类轴| REV[待人工<br/>类对认可一次即免问]
- AD2 -->|都不是| NONE[不动<br/>并记下理由]
- GP -->|已有的| MAP[映射到已有类型<br/>改写等待的事实]
- GP -->|没有的| NEWT[新建类型 + 改写]
+ AD2 -->|within the original class subtree| AUTO[Retype automatically<br/>entity_retypes]
+ AD2 -->|crosses a classification axis| REV[Human review<br/>a class pair approved once is never asked again]
+ AD2 -->|neither| NONE[Leave alone<br/>reason recorded]
+ GP -->|type exists| MAP[Map to the existing type<br/>rewrite the waiting facts]
+ GP -->|type is new| NEWT[Create the type + rewrite]
style AD2 fill:#3a3a5a,color:#fff
```
-**两路候选取并集,不合分数。** 距离在三处都不可比:跨实体不可比
-(`清华大学计算机系→computer_store` 0.46 比 `星云科技→corporation` 0.59 还近,而前者荒谬)、
-两路之间不可比(一个在类空间一个在实体空间)、同一路的两个查询之间也不可比
-(短查询"医药集团"产生的距离系统性小于一整段画像)。**一律交替取。**
+**The two candidate routes are unioned, never scored together.** Distances are incomparable in three places: across entities (`清华大学计算机系→computer_store` at 0.46 is closer than `星云科技→corporation` at 0.59, and the former is absurd), between the two routes (one lives in class space, the other in entity space), and between two queries on the same route (a short query like "医药集团" yields systematically smaller distances than a full profile). Candidates are interleaved instead.
-**分档不看模型自报的 confidence**——实测是双峰的(15 条全 ≥0.85、4 条 null,中间没有),
-自报置信度是语气不是概率。改用「选中的类在不在原类的子树里」:在 = 往下走一格,自动;
-不在 = 换了分类轴,进人工。
+**Tiering ignores the model's self-reported confidence.** In practice it is bimodal (15 items all ≥ 0.85, 4 null, nothing in between): it is tone, not probability. The tier comes from whether the chosen class sits in the original class's subtree. Inside means one step down, applied automatically; outside means a different classification axis, sent to a human.
-**纠正也走人工,而且天然如此**:抽取按块检索候选之后自己就会挑细类,也会挑错
-(`绍兴 → address`);正确答案是错类的**兄弟**不是后代,所以必然判为跨轴。
-推翻抽取的判断比细化它风险大,不该自动发生。
+**Corrections go to a human as well, by construction.** Extraction already picks fine-grained classes after per-chunk retrieval, and sometimes picks wrong ones (`绍兴 → address`). The right answer is a **sibling** of the wrong class, so it always reads as crossing an axis. Overturning extraction's judgment is riskier than refining it and should not happen automatically.
-### 这里会丢东西吗
+### Where this stage drops things
-不丢事实,但**改类不进时间轴**——它是 `entities` 上一次 UPDATE 加一行 `entity_retypes`〔实体历史现在会显示 `retyped` / `retype_reverted` 两种事件,这一条已经补上〕。**可撤销不等于会被撤销**,
-这是先做 preview 再做 apply 的理由。
+No facts are lost. A retype is one UPDATE on `entities` plus a row in `entity_retypes`, and entity history shows it as `retyped` / `retype_reverted` events. **Reversible does not mean it will be reversed**, which is why preview comes before apply.
-**类型消解今天只能手动跑**——本体页 preview → apply,没有任何自动触发。抽取结束只入队本体扩展与实体裁决。
-所以大本体下新实体的细化依赖人记得去点一下,这是个真缺口(0001 P3a)。
+**Type resolution runs only by hand today**: preview → apply on the ontology page, with no automatic trigger. Finishing extraction only enqueues ontology growth and entity adjudication, so refining new entities under a large ontology depends on someone remembering to click. This is a real gap (0001 P3a).
-**人拍过板的不再被引擎重判**:`entities.type_source` 是 `human` 的实体不进取材,包括「人判了,就是没有类型」(0001 P4a)。
+**Human decisions are never re-judged by the engine.** Entities whose `entities.type_source` is `human` are excluded from the candidate pool, including "a human decided it has no type" (0001 P4a).
-**拒绝要给理由。** `left_alone` 曾经只是个数,而这一步的设计押在"选择都不是是个体面答案"上——
-最大的一档不透明。记上理由之后第一次跑就回答了此前答不出的问题:失败**全在检索一侧**
-(`administrative_area`、`periodical` 从没被端上来过),不在裁决。
+**Rejections carry a reason.** The design bets on "none of these" being an honest answer, which made `left_alone` the largest and most opaque tier while it was only a count. With reasons recorded, the first run answered a question that had been unanswerable: the failures were **all on the retrieval side** (`administrative_area` and `periodical` were never offered), none in adjudication.
---
-## 四、公理:检查与推导
+## 4. Axioms: Checking and Inference
```mermaid
flowchart TB
- ONT[(本体的公理<br/>functional · symmetric · asymmetric<br/>transitive · inverseOf · subPropertyOf · disjoint)] --> SELF[本体自检<br/>八类缺陷]
+ ONT[(Ontology axioms<br/>functional · symmetric · asymmetric<br/>transitive · inverseOf · subPropertyOf · disjoint)] --> SELF[Ontology self-check<br/>eight defect kinds]
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/>开关,默认关}
+ ONT --> R0[Fact-level check<br/>self-loop · asymmetry · transitive cycle · cardinality · signature]
+ G[(Graph)] --> R0
+ R0 --> VIO[(axiom_violations<br/>with the full path)]
+ VIO --> DEC{Human decision}
+ DEC -->|retract the fact| RET[Fact retracted]
+ DEC -->|relax the axiom| RLX[Edit the ontology]
+ DEC -->|accept| ACC[Both stay]
+ ONT --> R1{materialize_inferences<br/>switch, off by default}
G --> R1
- R1 -->|开| DER[(derived_facts<br/>另一张表 · rule_id · 前提链)]
- DER --> GV[图上金色边<br/>实体面板「推出来的」]
+ R1 -->|on| DER[(derived_facts<br/>separate table · rule_id · premise chain)]
+ DER --> GV[Gold edges on the graph<br/>entity panel marks them inferred]
style DEC fill:#3a3a5a,color:#fff
```
-**签名在三条写路径上都算数**(#190 / #196):第一节那道「主宾对得上签名吗」的判断住在 store(`ontology::judge_direction`),抽取落新事实、采纳把谓词挂回旧事实都调它——两边都不合的采纳**不挂**,条数随 `facts_left_off` 上报;合并换了主宾之后不掰不改,只对搬动过的事实查一遍,违反的进 `axiom_violations`(`signature`)。检查里的第五类就是它的全量版,本体事后改了 domain 也逃不过。
+**Signatures count on all three write paths** (#190 / #196). The "do subject and object match the signature" check from section 1 lives in the store (`ontology::judge_direction`). Extraction calls it when writing new facts. Adoption calls it when reattaching a predicate to old facts; where both directions fail, the predicate is **not attached** and the count is reported as `facts_left_off`. A merge that changes subject or object neither swaps nor edits; it re-checks only the moved facts, and violations go to `axiom_violations` as `signature`. The `signature` check kind is the full-scan version of the same rule, so a domain changed in the ontology after the fact is caught too.
-**检查不写库,推导写另一张表。** 一致性检查(R0)只指出问题,风险面为零;物化推导(R1)会往图里加东西,所以它的每条约束都是必要的:
-规则**只从本体公理编译**,没有用户 DSL;**断言硬性优先于派生**——已经断言过的三元组不再派生,「这条是谁说的」有唯一答案;
-深度上限加环检测,每谓词封顶两万条且被截掉的**要说出来**;有效时间取前提的交集,空交集不推。
-派生不进 `facts`:四十多处读 `facts` 的查询只有一处认得标记,分开之后忘了 UNION 的后果是**看不见**派生,而不是**混进去**。
+**The check writes nothing; inference writes to a separate table.** The consistency check (R0) only points at problems, with zero risk. Materialized inference (R1) adds to the graph, so each of its constraints is necessary: rules **compile only from ontology axioms**, with no user DSL; **asserted facts strictly override derived ones**, so a triple already asserted is never derived and "who said this" has one answer; a depth limit plus cycle detection, a cap of 20,000 per predicate, and truncation **is reported**; valid time is the intersection of the premises, and an empty intersection derives nothing. Derived facts never enter `facts`: of the forty-odd queries that read `facts`, only one recognizes a marker, so with separate tables a forgotten UNION makes derived facts **invisible** rather than **mixed in**.
-**本体自检排在前面**:自相矛盾的本体(一个关系既 symmetric 又 asymmetric、子类成环、逆没指回来)会让事实层的结论全部可疑。
+**The ontology self-check runs first.** A self-contradictory ontology (a relation both symmetric and asymmetric, a subclass cycle, an inverse that does not point back) makes every fact-level conclusion suspect.
-**没装本体包的库跑出来是零**,那是实情不是故障——没有公理就没有判据,不报矛盾比猜一个公理出来安全。
+**A database without an ontology pack reports zero.** That is the truth, not a fault: without axioms there is no criterion, and reporting no contradiction is safer than guessing an axiom.
-**什么时候跑**:导入本体后自动跑一次检查(公理刚变,最该重算的时刻);Review 页可手动跑;推导按 `inference_interval_minutes`(缺省 60)定时全量重推——增量维护还没做。
+**When it runs.** The check runs automatically after an ontology import (the axioms just changed, the best moment to recompute) and on demand from the Review page. Inference reruns in full on a timer, `inference_interval_minutes` (default 60); incremental maintenance is not built yet.
-### 这里会丢东西吗
+### Where this stage drops things
-不丢,但**有两处沉默**:派生 vs 断言矛盾时派生不落地,今天**不记信号**;同一三元组有多条推导路径只留第一条证明。两者都是 [0002](decisions/0002-reasoning-engine.md) 里写了而没做的。
+Nothing is dropped, but the engine keeps quiet in two places. A derivation that contradicts an assertion (or another derivation) is not written; since #238 it leaves an `axiom_violations` row of kind `derived_contradiction`, capped per predicate, with the overflow counted in the run report and rule-versus-rule disagreements recorded as `ontology_defects` (`rules_disagree`) — see [0017](decisions/0017-a-contradiction-points-upstream.md). When one triple has several derivation paths, only the first proof is kept; that one is still silent ([0002](decisions/0002-reasoning-engine.md)).
-## 想自己跑一遍
+## Running the Benchmarks
-`scripts/bench/` 是可重跑的测量台,**每一组一个新库**——复用一个库省几分钟,
-换来的是一整段无效结论(那是踩过的坑,不是假设)。
+`scripts/bench/` is a rerunnable measurement bench, **one fresh database per run**. Reusing a database saves minutes and costs a whole run of invalid conclusions; that is a lesson learned, not a hypothesis.
```bash
node scripts/bench/run.mjs --corpus pharma --label seeds-only
node scripts/bench/run.mjs --corpus holmes --label holmes
```
-三份语料各测一件事,用途不同、要求也不同:
+Three corpora measure three things, with different requirements:
-| 语料 | 测什么 | 有答案键 |
+| Corpus | Measures | Answer key |
|---|---|---|
-| `tech` / `pharma` | 类型准确性 | 有(弱:自己写的) |
-| `holmes` | 实体消解 · demo 空镜 | **无,故意的** |
+| `tech` / `pharma` | Type accuracy | Yes (weak: hand-written) |
+| `holmes` | Entity resolution · demo footage | **None, by design** |
-福尔摩斯那份**不该有**准确性答案键:模型早就读过它,量类型准确率量到的是记忆,
-不是这条流水线。**编一份假答案比不打分更糟。**
+The Holmes corpus **must not** have an accuracy key: the model has read the book, so measuring type accuracy would measure memory, not the pipeline. A fabricated answer key is worse than no score.
-## 相关决策
+## Related Decisions
-- [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) 为什么「还没判出来」不是类、「说不出」不是关系
+- [0001](decisions/0001-ontology-import-and-governance.md) Ontology import and governance, with the measured revision of P3
+- [0003](decisions/0003-ontology-growth-loop.md) Growing the ontology from the corpus, and where the human stands in the loop
+- [0006](decisions/0006-ontology-scale-and-the-prompt.md) Ontology scale and the extraction prompt, with the curve and one reversal
+- [0002](decisions/0002-reasoning-engine.md) Reasoning engine order and safety boundary; [0012](decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md) direction correction at write time
+- [0017](decisions/0017-a-contradiction-points-upstream.md) A contradiction points at an error upstream: what happens when a derivation disagrees with the ledger
+- [0009](decisions/0009-no-type-is-a-type.md) / [0010](decisions/0010-no-relation-is-no-relation.md) An undecided type and an unnamed relation both stay empty