跳转到内容
Aira 3D

RFC-0008：Phase 1 SemanticRef Survival Query

字段 值
状态 Accepted — 本地、持久化与 Google Chrome 产品 Gate 已关闭
文档版本 0.2.0
日期 2026-08-31
决策范围 ExactSolid face 引用、跨 Revision 生存、持久证据与 model.read 查询投影
上位路线 Aira 长期架构计划 Phase 1
依赖协议 RFC-0004、RFC-0006、SemanticRef v0.1

1. 决议

Section titled “1. 决议”

Phase 1 在扩大工业 feature catalog 前，先把 ExactSolid face 的 SemanticRef 从 contract oracle 推进为产品级 跨 Revision 查询。首个纵向切片必须证明：rectangle/extrude 的 width、height 或 distance 参数改变后，六个 extrude face role 均能从旧 Revision 确定性解析到新 Revision；缺失、重复、fan-out、版本或证据绑定异常必须 显式 missing、ambiguous 或 fail closed，silent wrong rebind 恒为 0。

该能力继续使用九元 Aira Interface：顶层 operation 仍是 model.read，不增加 model.query 或第十个 meta-operation。实现采用独立、可发现的 additive read profile：

aira.read.semantic-ref/0.1.0

它有自己的公开 schema、strict validator、canonical hash 与 capability contract，不修改已经冻结的 Core/Interface 0.2 或 0.3 接受集，也不改变 AMIR、ModelHash、RevisionId 或 authoringLockHash 的算法。

2. 三层身份

Section titled “2. 三层身份”

2.1 Authoring definition：进入模型语义

Section titled “2.1 Authoring definition：进入模型语义”

“想持续引用什么”属于 authoring。AMIR 0.2 的 semanticRefs 集合仍被 compatibility line 固定为空，因此 首个切片把 Exact face 定义放在 exact.linearExtrude Node 的 semantic extension 中：

extensions["aira.semantic-refs.exact-linear-extrude/0.1"] {
  semantic: true
  version: "0.1.0"
  definitions: { semanticRefId -> definition }
}

definition 固定 Node/output scope、Face、authoring role、lineage origin、exactly-one cardinality、演化策略和 ordering。semantic: true 使完整 envelope 进入既有 AMIR semantic projection，因此定义变化会改变 ModelHash/RevisionId；它不是 UI metadata。未来 AMIR compatibility line 可把同一定义迁入原生 semanticRefs collection，但不能重新解释旧 Revision。

首个 profile 的六个稳定 role 为：

  • cap.start、cap.end；
  • side.uMin、side.uMax、side.vMin、side.vMax。

role 由 NodeId + operation version + role 定义；resolver 使用的 lineage origin 来自真实 OCCT history，禁止 face index、遍历顺序、WASM pointer、Three.js object 或 tessellation index。

2.2 Authoring witness：绑定引用创建时观察

Section titled “2.2 Authoring witness：绑定引用创建时观察”

每个定义在 source Revision 的 committed replay 后生成 SemanticRefAuthoringWitness。Witness 绑定 source Revision/Evaluation/ArtifactGraph/ExecutionManifest、定义 hash、当时完整候选集合与 fan-out。Witness 是证据， 不进入 Revision，也不能被目标 Revision 的结果覆盖。

2.3 Resolution evidence：随 Evaluation 持久化

Section titled “2.3 Resolution evidence：随 Evaluation 持久化”

Exact worker 从真实 ArtifactGraph 生成紧凑 ExactSemanticRefSnapshot。Snapshot 只保存 resolver 所需的 kernel-neutral 事实：完整 context、artifact 内容身份、每个 face 的 artifact-local 内容 ID、全部 lineage origins、geometry signature、面积、质心、bounds、source role 与 confidence，并对自身生成 canonical hash。

Snapshot 是 committed replay evidence 的新版本字段，不复制 B-Rep，不进入 RevisionId。旧 replay evidence 版本保持可读且不被改写；缺少 snapshot 的历史 Revision 对本 profile 返回明确 evidence-missing，不进行猜测。

3. model.read profile wire

Section titled “3. model.read profile wire”

公开 contract 固定四个 wire object，并把 AI 输入与权威审计请求分层：

  1. SemanticRefReadCapabilityContract：由 additive catalog.search/describe 投影发现，绑定 capability ID、 read.profile、schema ID/hash、输入/输出类型与 effectClass=read；
  2. SemanticRefReadIntent：AI-facing 最小输入，只含 request ID、source/target Revision 与 SemanticRef ID 集合；
  3. SemanticRefReadRequest：runtime 从 durable store 权威扩展出的审计对象，含 operation=model.read、 readProfile、完整 AmirQueryRequest，以及按 queryId 绑定的 definition、witness 和 SemanticRefResolutionRequest；
  4. SemanticRefReadResult：canonical Query Plan、每个 root 的 set-valued resolution、Execution Receipt、 source/target snapshot hash 与总 result hash。

AI 不负责提交 definition、witness、Evaluation/ArtifactGraph/manifest hash 或 certificate identity；这些字段必须 由 runtime 从两个 committed Revision 及其唯一 committed replay evidence 补齐。这样既减少模型调用负担， 又不把证据或权限交给模型自证。完整 SemanticRefReadRequest 仍是可重放、可审计的权威对象。

请求约束：

  1. AMIR Query 只能包含 semantic-ref.resolve 或 semantic-ref.resolve-across；
  2. query.selector.semanticRefId 与 definition/witness/request 必须相同；
  3. resolutionRequestHash 必须等于该 resolution request 的 canonical hash；
  4. source/target Revision、modelHash、authoringLockHash、Evaluation、ArtifactGraph 与 manifest 必须同时匹配 durable store；
  5. resolveAcross 必须绑定两个不同的完整 context；
  6. limits 同时受 Query Request、Interface manifest 和 capability contract 约束；
  7. response 中每个 root 都必须有结果；unknown/notApplicable/failed 不得携带伪造值。

read profile 是 capability-scoped contract，不是把全部 query schema重新塞入全局 system prompt。AI 通过 additive catalog.search/describe 投影获得本 profile 的完整 schema/hash，随后仍以 model.read 调用。 该投影不修改冻结的 Exact 0.2 authoring capability schema，也不增加第十个 meta-operation。

4. Resolver 归约

Section titled “4. Resolver 归约”

对每个 definition，runtime 从 source/target snapshot 构造 SemanticRefResolverEvidence：

  1. scope：artifact 与 owning Node/output binding 一致；
  2. entity kind：必须为 Face；
  3. lineage：target face 的 lineage origins 包含 definition origin；
  4. topology：ArtifactGraph 的 exact face record、content identity 与 context hash 已验证；
  5. predicate：v0.1 使用 role/origin 与 exact metric evidence，任何未计算项为 null；
  6. cardinality：保留全集，永不 take-first；
  7. ordering：使用已有 SemanticRef canonical code-unit ordering。

同一 role 的一对一 source→target 产生 modified 或可证明的 no-effect event；一个 source 对多个 target 为 split；多个 source 对一个 target 为 merge；无 target 为 delete。证据事件仅允许 exact 或 deterministic 进入 publishable 结果。Query receipt 的 root contentHash 必须等于对应 resolution hash。 observedFanout.descendantCount 在候选数为 0 或 1 时固定为 0，仅在候选数大于 1 时记录真实 N；因此普通 一对一修改不会被误判为 split，而真实 fan-out 保留全集并进入 ambiguous/不可发布路径。

5. 版本与兼容边界

Section titled “5. 版本与兼容边界”
  • 新公开 schema line：https://schemas.aira.dev/interface/read/semantic-ref/0.1/...；
  • read profile：aira.read.semantic-ref/0.1.0；
  • Exact snapshot：aira.phase-1.exact-semantic-ref-snapshot/0.1；
  • committed replay evidence 使用 0.3（snapshot + authoring witnesses），并保留旧 0.1/0.2 union；
  • Exact feature evidence 使用新版本并保留 0.1/0.2 union；
  • naming algorithm 继续是 aira.semantic-ref/0.1.0。

新增 schema 必须登记到 AIRA_SCHEMA_REGISTRY → 已取消（2026-09-08）：该注册表没有任何读者， 因此双向漂移——审计时既登记着七个已删除的文件，又漏登记了六个磁盘上的 schema，其中包括当前主节点的 exact-program-node-v4.schema.json。要求人工同步而无消费者的清单必然失真，登记它不产生任何检查。 schema 的权威身份是文件自身的 $id；需要它的模块直接声明自己的 id，跨 schema 引用由 bundled-exact-schema-resources 按 $ref 闭包解析。仍然有效：禁止覆盖既有历史治理报告或修改冻结的 Core/AMIR/Operation Catalog/Exact Interface schema bytes。

6. 明确拒绝

Section titled “6. 明确拒绝”
  • 不修改 Core ModelReadCollection enum 来伪装兼容；
  • 不新增顶层 operation；
  • 不把完整 ArtifactGraph、B-Rep bytes、cache 或 kernel handle写入 AMIR；
  • 不从 target geometry 反向猜测 authoring intent；
  • 不以几何接近、数组位置或“通常是这个面”代替 lineage evidence；
  • 不把 contract corpus 通过误称为产品级 resolver 已启用；
  • 不在本切片顺带加入 fillet、chamfer、shell、revolve、sweep、loft 或 STEP direct edit；
  • 不启动真实 provider 或 backend。

7. Accepted Gate（已关闭）

Section titled “7. Accepted Gate（已关闭）”

以下证据已经全部存在：

  1. 新 schema、registry、generated types、validator 与 canonical hash Gate 通过，旧冻结合同哈希不变；
  2. 真实 OCCT committed replay 持久化可重算的 snapshot，tamper/replay conflict fail closed；
  3. 至少两次真实 Exact transaction 形成 source/target Revision；
  4. width、height、distance 参数扰动下六个 face role 全部 resolved，每个 cardinality 恰为 1；
  5. missing、duplicate/split、fan-out、naming-version、context/hash tamper corpus 不发生 silent wrong rebind；
  6. Query Plan/Receipt 可独立重建，root content hash 与 SemanticRef resolution hash 一致；
  7. IndexedDB reopen 后可按两个 Revision 重放同一查询并得到相同 result hash；
  8. Google Chrome 通过原生 Aira Interface discovery + model.read profile 完成查询，Three.js 模型可见， console warn/error 为 0；
  9. provider 调用为 0、backend 未启动、Lane F/Lane R 未被修改。

机器收据：

8. 实施顺序

Section titled “8. 实施顺序”
  1. 冻结 read-profile schema、snapshot schema、版本登记和 contract tests；
  2. 从 Exact ArtifactGraph 生成并持久化 snapshot；
  3. 实现 definition/witness 构造与跨 Revision evidence reducer；
  4. 把 reducer 接入 AMIR Query plan/receipt，并投影到 Exact native model.read；
  5. 完成本地 corpus、IndexedDB reopen 与真实 OCCT/Google Chrome Gate；
  6. 本 RFC 现已 Accepted。其后主线已按长期计划进入 Phase 1 工业 feature catalog 扩展，并由 RFC-0009 关闭首个 exact.revolve Operation Module；当前下一 Gate 为 Exact edge read/selector survival。每个新 authoring operation 仍须独立 capability/RFC、SemanticRef survival corpus、证据与 Chrome Gate。