跳转到内容
Aira 3D

ADR-CORE-002：可组合的 Authoring Operation Module

状态：Accepted — exact.revolve@1.0.0 首个模块 Gate 已通过

日期：2026-08-31

决策范围：AMIR/Core 0.4、Operation Catalog、Capability discovery、Task Capsule、provider projection

上位路线：Aira 长期架构计划

1. 问题

Section titled “1. 问题”

AMIR 0.1、Exact 0.2 与 Field 0.3 都用封闭 JSON Schema union 枚举 Node。这个设计适合冻结首个 兼容线，却不适合长期工业 feature catalog：每增加 revolve、fillet、shell 或第三方 authoring operation， 如果都复制 AMIR/Core schema、Rust enum、工具 schema和完整接口版本，会产生版本爆炸；如果直接修改旧 union，又会扩大已发布接受集、破坏历史 hash 与重放语义。

Aira 需要同时满足：

  1. AI 能通过 catalog.search/describe 获得一个操作的完整 typed contract；
  2. 未知、未授权或契约 hash 不匹配的操作 fail closed；
  3. 新操作不要求改写稳定九元 meta-operation，也不要求发布另一套建模语言；
  4. Revision 必须锁定操作语义，不能在未来被同名 adapter 重新解释；
  5. operation package 不能携带 shell、eval、网络或任意宿主代码权限；
  6. 旧 0.1/0.2/0.3 文档、schema、catalog 和证据逐字节保持不变。

2. 外部先例的有限采用

Section titled “2. 外部先例的有限采用”
  • JSON Schema 2020-12 的 $dynamicRef/$dynamicAnchor 用于动态作用域引用和可扩展递归 schema；它不提供 package trust、能力授权、实现绑定或 Revision 重放，因此不作为 Aira operation registry。
  • WebAssembly Component Model 的 WIT 把 typed interface 放入带 namespace 与完整 SemVer 的 package，并由 world 显式组合 imports/exports。Aira 采用“版本化接口包 + 显式组合”的原则，但当前不要求把几何 evaluator 编译为 Wasm Component，也不把 WIT 当 authoring wire。
  • OCCT 的 BRepBuilderAPI_MakeShape 提供 Generated/Modified/IsDeleted history，但这些是 evaluator evidence， 不能充当 operation contract、SemanticRef 或 capability identity。

一手资料：

3. 决策

Section titled “3. 决策”

3.1 新增 AMIR/Core 0.4 模块化信封

Section titled “3.1 新增 AMIR/Core 0.4 模块化信封”

amir/0.4 的 Node 只冻结通用信封：

op + opVersion + operationContractHash + inputs + outputs + extensions

结构 schema 只证明信封和基础 Value/PortDefinition 合法。完整合法性必须依次通过：

  1. I-JSON、重复键、Unicode 与 canonical boundary；
  2. AMIR 0.4 结构 schema；
  3. 当前 Revision 锁定的 Catalog Snapshot 查找；
  4. operationRef = op@opVersion 与 operationContractHash 精确匹配；
  5. Operation Module 的 node schema；
  6. Core 静态语义、Task Capsule、Session Grant 与 runtime availability；
  7. evaluator + independent checker + publication state machine。

结构 schema 单独通过不表示 Node 可执行或可提交。

3.2 Operation Module 是数据合同，不是代码插件

Section titled “3.2 Operation Module 是数据合同，不是代码插件”

每个 module 固定：

  • moduleId、moduleVersion、operationRef 与 canonical moduleHash；
  • 完整 node JSON Schema 及其 schemaHash；
  • input/output type、binding、单位、范围和 applicability；
  • authoring roles、SemanticRef policy 与 naming algorithm version；
  • postconditions、required assurance、稳定 Diagnostic code 集合；
  • evaluator profile 与所需 representation，但不携带 kernel 名、函数名或 raw handle；
  • 对应 capability ID 与 provider projection 约束。

module JSON 禁止网络 $ref、可执行代码、脚本、callback、文件路径、kernel symbol 和任意宿主权限。实现由 runtime 自有 allowlist 将 evaluator profile 映射到 adapter；module 无权自注册实现。

3.3 Catalog Snapshot 显式组合 modules

Section titled “3.3 Catalog Snapshot 显式组合 modules”

Catalog Snapshot 是 immutable、canonical、可内容寻址的 module 集合。它记录精确 module/schema hash， 并拥有独立 catalogId。同一 AMIR 0.4 compatibility line 可发布新的 catalog patch snapshot；新增操作只 新增 module 和 catalog snapshot，不修改 Core schema。

Revision 的 operationCatalog、authoring lock、Task Capsule 与 ExecutionManifest 必须共同绑定 catalog identity/hash。重放缺少任一 module 或出现 hash 不一致时返回结构化不可执行状态，不回退到“当前最新版”。

3.4 Capability discovery 是投影，不是第二份真相

Section titled “3.4 Capability discovery 是投影，不是第二份真相”

catalog.search/describe 从 Operation Module 机械生成 Capability Contract。下列规则对 Capability Contract 仍然有效；其中 provider projection 一支已随 RFC-0002 §13.2 于 2026-09-08 废弃，没有代码实现过它：

  • capability 可以比 canonical module 收窄接受集，不能扩大；
  • examples、摘要和检索 embedding 不进入 authoring identity；
  • capability、module、schema、catalog 四个 hash 必须互相可追溯；
  • AI 只提交 module schema 允许的 typed Patch，不提交 evaluator/checker 自证字段。

3.5 当前契约与历史记录

Section titled “3.5 当前契约与历史记录”

项目未发布，仅维护当前 AMIR 0.4 信封、模块及目录内容绑定；旧 0.1/0.2/0.3 和旧 0.4 内容不是兼容读取目标。早期 migration fixture 与兼容线方案已退役，不再作为实施要求。替换同批清理旧入口，不隐式启用休眠 Field 能力；当前 Revision 的事务和历史恢复继续受既有检查约束。公共信封与模块各自更新内容绑定，是否需要版本号变化依具体语义说明，不以兼容层延续旧实现。

4. 首个证明模块

Section titled “4. 首个证明模块”

RFC-0009 的 exact.revolve@1.0.0 是首个 Operation Module Gate。 它复用现有 Profile2D/ExactSolid 管线，并验证 axis/angle applicability、OCCT history、条件性 cap roles、 SemanticRef survival、独立证书、原生九元接口和 Google Chrome 产品闭环。

RFC-0009 现已 Accepted，因此 0.4 模块化信封、Operation Module 与 Catalog Snapshot 作为架构边界成立。 产品激活仍与合同验收分离：

  • 当前默认 Runtime Snapshot 仍不自动切换到 0.4；
  • exact.revolve 在独立 activation 变更前不出现在 production capability search；
  • 旧 Exact 0.2 仍是默认产品 authoring line；
  • provider 保持停止。

5. Gate

Section titled “5. Gate”
  1. module schema、catalog snapshot 与 AMIR/Core 0.4 均有独立 schema/hash/registry identity；
  2. 旧 0.1/0.2/0.3 schema/catalog/fixture 字节锁不变；
  3. 未知 module、hash mismatch、schema mismatch、未授权 module、catalog/module 缺失全部 fail closed；
  4. TypeScript/Ajv 与 Rust validator 对同一合法/非法 corpus 一致；
  5. provider projection 不扩大 canonical 接受集；
  6. migration fixture 证明几何语义保持、Revision identity 显式变化；
  7. fresh checkout 可重放 contract、runtime 与 browser evidence；
  8. 至少一个真实工业 operation 通过完整产品 Gate，证明该抽象不是空框架。

八项 Gate 已由 RFC-0009 的 Exact Revolve 产品切片关闭：双语言模块验证、真实 OCCT/Manifold、 SemanticRef、九元接口、Google Chrome 与 sealed-runtime fresh-checkout 证据均通过。模块抽象不再是预设框架， 而是由首个独立 operation 实证的稳定扩展边界。

6. 后果

Section titled “6. 后果”
  • 新工业 operation 的规范单位变成独立 module/RFC/capability/evidence，而不是复制 Core；
  • Core validator 需要两阶段 schema + module semantic validation；
  • catalog snapshot 数量会增长，但每个 Revision 的解释边界更精确；
  • module registry、签名和第三方分发仍属于 Phase 3，本 ADR 只固定本地/内建模块合同；
  • 动态扩展不意味着动态执行权限，Aira runtime 始终保留最终实现和 effect authority。

7. 验收证据

Section titled “7. 验收证据”

本 ADR 的 Accepted 不注册第三方代码插件、不开放 raw OCCT API，也不自动启用任何新 production capability。