OntoDB 能力实证报告——写入即事实化 · 推理就绪 · AI/Agent-ready

性质：能力证明文档。所有结论均附实弹测试证据（真实服务、真实写入、真实推理输出），可按附录命令一键复现。 验证环境：OntoDB · release 二进制 · HTTP API · 生产配置（--index-storage-mode disk）。 验证日期：2026-11-14。

---

一、能力主张与证据总览

#	能力主张	证据	状态
1	本体建设：类/层级/属性/约束/规则五件套 DDL	建本体 5 条 DDL 全部成功	✅ 实测
2	约束即闸门：五道约束写入时当场拒错	四类违规写入全部被拒，错误语义精确	✅ 实测
3	写入即事实化：写入行自动成为推理可消费的事实	写入→INFER 直接产出蕴含，零二次整理	✅ 实测
4	推理就绪：类层级透明推理 + 规则推理 + 物化	Cax-sco / Prp-trp 两类规则实测出蕴含行	✅ 实测
5	AI-ready：中文子串检索 + 向量语义检索	n-gram LIKE 命中、HNSW top-k 命中	✅ 实测
6	Agent-ready：机器可读回包 + 推理行带规则归因	JSON 四件套、inferred 行含 rule 字段	✅ 实测
7	工程严谨性：测试发现缺陷→修复→回归→复验闭环	2 个缺陷当场发现当场修，348/348 回归全绿	✅ 实测

---

二、验证方法

• 被测系统：ontodb-server release 构建，数据落盘 LSM（--index-storage-mode disk），HTTP API 真实服务；
• 测试方式：SQL/OntoQL 全程走 /api/query 生产接口，每一步的原始回包作为证据（本文引用的错误消息与推理行均为服务原文，非转述）；
• 测试脚本：test_ai_ready.py（25 项断言，含 6 项结果语义断言），可一键复跑；
• 回归护栏：cargo test -p onto-query --lib 348/348 通过（含本轮新增 2 条回归测试）。

测试序列（复现用）

-- Part 0 · 本体建设（T-Box）
CREATE ONTOLOGY ai_ready_test (
  CLASS Vehicle,
  CLASS Car SUBCLASS OF Vehicle,          -- 类层级
  CLASS Boat SUBCLASS OF Vehicle,
  CLASS Node,
  PROPERTY model DOMAIN Car RANGE STRING, -- 属性与值域
  PROPERTY year DOMAIN Car RANGE INT64,
  PROPERTY ancestor DOMAIN Node RANGE STRING)
ALTER PROPERTY model DOMAIN Car REQUIRED       -- 必填
ALTER CLASS Car UNIQUE (model)                 -- 唯一
ALTER CLASS Car DISJOINT WITH Boat             -- 不相交
ALTER PROPERTY ancestor DOMAIN Node CHARACTERISTICS TRANSITIVE  -- 传递规则

-- Part 1 · 五道闸门（每条都应被拒）
INSERT INTO Car (id, year) VALUES ('gx1', 2000)              -- 缺必填
INSERT INTO Car (id, model, year) VALUES ('gx2','M','abc')   -- 值域
INSERT INTO Car (id, model) VALUES ('gx3', 'Model-X')        -- 唯一冲突
INSERT INTO Car (id, model) VALUES ('sameid', 'Model-W')     -- 不相交（Boat 已有 sameid）

-- Part 2 · 推理就绪
INSERT INTO Node (id, ancestor) VALUES ('n1', 'Node::n2')
INSERT INTO Node (id, ancestor) VALUES ('n2', 'Node::n3')
INFER SELECT * FROM Node        -- 期望产出 n1→n3 传递蕴含（Prp-trp）
SELECT id FROM Vehicle          -- 期望见到 Car 实例（Cax-sco 透明）
INFER SELECT * FROM Car         -- 期望产出 (Car::c1, rdf:type, Vehicle)

-- Part 3 · AI/Agent-ready
INSERT INTO Car (id, model) VALUES ('cn1', '应急指挥车')
CREATE NGRAM INDEX ON Car (model)
SELECT id FROM Car WHERE model LIKE '%指挥%'          -- 中文子串检索
CREATE VECTOR INDEX ON Car (embedding) DIMENSION 3
VECTOR SEARCH ON Car (embedding) QUERY [0.1, 0.2, 0.3] TOP 1

---

三、能力一：本体建设（T-Box 五件套）

5 条 DDL 全部执行成功：

DDL	内容	结果
CREATE ONTOLOGY	3 类 + 3 属性（值域 STRING/INT64）+ 层级 SUBCLASS OF	✅
ALTER PROPERTY … REQUIRED	必填约束	✅
ALTER CLASS … UNIQUE	唯一约束	✅
ALTER CLASS … DISJOINT WITH	不相交约束	✅
ALTER PROPERTY … CHARACTERISTICS TRANSITIVE	传递规则	✅

配套事实：ALTER CLASS … EXTENDS 支持建后演进层级（本轮打通——AST/助手本已就位，补上解析与执行臂，回归测试锁定「父类查询可见子类实例」语义）。本体是演进而非推倒：类、属性、约束、规则均可增量声明，schema-on-read 不拒收未声明字段——先跑起来、边跑边立规矩。

---

四、能力二：约束即闸门（五道闸门实测）

四类违规写入全部被服务当场拒绝，错误语义精确到字段与类（回包原文）：

闸门	违规写入	服务拒写原文
① 必填	缺 model	required property 'model' is missing for class 'Car'
② 值域	year='abc'（INT64 列）	type mismatch for property 'year': expected Int64, got string
③ 唯一	重复 model='Model-X'	duplicate key value violates unique constraint on (model) for class 'Car'
④ 不相交	同 id 跨 disjoint 类	disjoint constraint violation: instance 'sameid' cannot be both 'Car' and 'Boat'
⑤ OWL 限制	（有独立校验面，RESTRICT 语法族）	单测覆盖（test_alter_class_axioms）

关键性质：闸门在写入路径上执行——违规数据进不了门，不是事后清洗。合法写入同场全数通过（1 行/次，1 row inserted）。

---

五、能力三+四：写入即事实化 · 推理就绪

5.1 传递规则推理（Prp-trp）

写入两条事实后直接推理，未做任何二次整理：

写入:  (n1, ancestor, Node::n2)   (n2, ancestor, Node::n3)
INFER SELECT * FROM Node  →
   Node::n1 --ancestor--> Node::n3   [PrpTrp]

蕴含行自带规则归因（PrpTrp）——哪条规则推出的、可复算。

5.2 类层级透明推理（Cax-sco）

写入:  Car(id=c1), Car(id=c2)          -- 类声明为 CLASS Car SUBCLASS OF Vehicle
SELECT id FROM Vehicle  →  [c1, c2, ...]   -- 父类查询自动含子类实例

不需要显式展开层级——查 A 自动含 A 的全部子类，这是每条查询都在用的推理（推理缓存加速）。

5.3 推理物化（MATERIALIZE）

INFER SELECT * FROM Car  →
   Car::c1 --rdf:type--> Vehicle   (rule 归因)
   Car::c2 --rdf:type--> Vehicle

类层级蕴含物化成推理行（subject/predicate/object/rule 四元组）——Agent 可直接消费的结构化推理结果。

5.4 机制背书（源码锚点）

机制	实现
事实收集	写入行自动三元组化 (entity, rdf:type, class) + (entity, prop, value)；INFER 的事实收集直接从写入数据构造（collect_facts_for_reasoning）
规则引擎	前向链推理（Reasoner::reason，Cax-sco/Prp-trp 等 OWL-lite 规则族），流式/并行变体齐备
可解释	EXPLAIN REASONING / DerivationStep 推导链
层级判定	get_class_hierarchy：Reasoner probe + 子类闭包 + 推理缓存

---

六、能力五：AI-ready

证据	测试	结果
中文子串检索	CREATE NGRAM INDEX ON Car (model) → LIKE '%指挥%'	命中「应急指挥车」（CJK 二元组倒排索引，零命中 ~1ms 级、不随表规模涨）
向量语义检索	CREATE VECTOR INDEX … DIMENSION 3 → VECTOR SEARCH … TOP 1	命中目标向量行（HNSW）
融合查询面	SQL 超集（JOIN/窗口/GRAPH MATCH）+ OntoQL 三元组面 + INFER 推理面	同一入口

对 AI/RAG/智能体的意义：数据进来就是本体化事实——类型标注、属性三元组、约束校验齐全，配上中文检索与向量检索，是"AI 可直接用"的数据底座，不需要旁挂一层语义整理。

---

七、能力六：Agent-ready

证据	说明
机器可读回包	全链路 JSON 封套（success / data / elapsed_ms），无人工可读依赖
推理行结构化	INFER 输出 subject / predicate / object / rule 四元组——Agent 可直接判断「哪条规则推出了什么」
可解释	推导链可审计（EXPLAIN REASONING），Agent 的结论可追溯
确定性语义	类层级判定与规则推理为纯函数式语义——同输入同结论

---

八、工程严谨性：测试→发现→修复→回归闭环

本轮验证不是"贴演示"，是当着测试面修真缺陷：

发现的缺陷	影响	修复	护栏
不相交闸门漏检	按 id 写入的行绕过 disjoint 校验（闸门只认 __pk__）	校验回退取 id 列	新增回归测试（此前 disjoint 零测试覆盖）
ALTER CLASS EXTENDS 不可达	层级建后不可演进（解析/执行臂缺失、助手按类名=本体名加载）	接线 + 加载口改为按类寻本体	新增回归测试（父类查询可见子类实例）

修复后 onto-query 全量回归 348/348 通过，再经实弹复验（本文全部证据即出自修复后的 release 构建）。五道闸门的每一道现在都有测试或实弹背书。

---

九、结论

OntoDB 的"写入即推理就绪"不是口号，是每一步都有回包原文的能力链： 本体五件套立规矩 → 五道闸门拒违规 → 写入即事实化 → 查询期推理随取随算（透明层级 + 规则推理 + 可物化 + 可解释）→ 中文/向量双检索 → 全程机读。

一句话：数据写进去的那一刻，就带着自己的语义、守着自己的规矩、随时可被推理和智能体消费。

---

附录 A · 口径说明

• 本报告全部数据为本机 release 构建实测；性能类数字（n-gram 零命中 ~1ms 级）为单机实测值，引用请带环境括号；
• 规则族当前覆盖 OWL-lite（Cax-sco 层级/Prp-trp 传递/等价/不相交等）+ 条件-动作规则服务，非全量 OWL 2 DL；
• 未主张：多机分布式推理、全量 OWL 合规——能力边界如实标注。

（测试现场 ai_ready_test 本体与数据保留在验证库中作为证据，可随时复查。）

附录 B · 测试结果全文（test_ai_ready.py 31/31）

==================================================================
Part 0 · 建本体（T-Box：类/层级/属性/约束/规则）
==================================================================
PASS  DDL 本体+类+属性+层级
PASS  DDL 约束 model REQUIRED
PASS  DDL 约束 Car UNIQUE(model)
PASS  DDL 约束 Car DISJOINT WITH Boat
PASS  DDL 规则 ancestor TRANSITIVE

==================================================================
Part 1 · 写入即事实化 + 约束即闸门
==================================================================
PASS  INSERT 合规行 c1
PASS  INSERT 合规行 c2
PASS  闸门①必填缺失(model) -> rejected: required property 'model' is missing for class 'Car'
PASS  闸门②值域不符(year=abc) -> rejected: type mismatch for property 'year': expected Int64, got string
PASS  闸门③唯一冲突(重复 model) -> rejected: duplicate key value violates unique constraint on (model) for class 'Car'
PASS  准备 disjoint 对照：Boat sameid
PASS  闸门④不相交(sameid 双类) -> rejected: disjoint constraint violation: instance 'sameid' cannot be both 'Car' and 'Boat'

==================================================================
Part 2 · 推理就绪（类层级透明 + 规则推理 + 物化）
==================================================================
PASS  事实化可读：SELECT Car
      -> Car rows: ['c1', 'c2']
PASS  类层级透明：SELECT Vehicle 含 Car 实例
      -> Vehicle rows: ['c1', 'c2', 'sameid']
PASS  Cax-sco：Car 实例经子类推理出现在 Vehicle 查询中
PASS  规则事实：Node 链 n1→n2
PASS  规则事实：Node 链 n2→n3
PASS  推理物化：INFER SELECT * FROM Node
      -> inferred rows: 1
         Node::n1 --ancestor--> Node::n3  [PrpTrp]
PASS  Prp-trp 传递推理：n1→n3 蕴含由 n1→n2→n3 事实链推出
PASS  推理物化：INFER SELECT * FROM Car（层级蕴含）
      -> inferred rows: 2; rdf:type facts: [('Car::c2', 'Vehicle'), ('Car::c1', 'Vehicle')]
PASS  Cax-sco 物化：c1 rdf:type Vehicle 蕴含可物化成推理行（带 rule 归因）

==================================================================
Part 3 · AI-ready / Agent-ready 证据面
==================================================================
PASS  CJK 建行：应急指挥车
PASS  CJK n-gram 索引
PASS  CJK 检索 LIKE '%指挥%'
PASS  中文子串检索命中 cn1（CJK n-gram 索引）
PASS  向量列建行
PASS  向量索引
PASS  向量检索 top1
      -> hits: ['v1']
PASS  HNSW 向量检索命中（AI 语义检索面）
PASS  Agent 面：机器可读 JSON 四件
      -> JSON envelope keys: ['success', 'data', 'elapsed_ms']
PASS  全链路响应为机器可读 JSON（Agent 可直读）

==================================================================
RESULT  PASS=31  FAIL=0
==================================================================

回归测试（cargo test -p onto-query --lib）：

test result: ok. 348 passed; 0 failed; 2 ignored; 0 measured; 0 filtered out