跳转到内容
Aira 3D

RFC-0006：Phase 1 Exact authoring 公开建模合同

字段 值
状态 Accepted（能力仍有效）— 交付载体 0.2 接口线已于 2026-09-08 退役，见 §0
文档版本 0.5.0
日期 2026-08-31
决策范围 Sketch2D、Profile2D、ExactSolid、linear extrude、Revision identity、Capability 与发布边界
上位路线 Aira 长期架构计划 Phase 1
接口协议 RFC-0002
身份协议 SemanticRef v0.1、ArtifactGraph v0
前置证据 Exact box 浏览器产品事务、AMIR 0.2 transaction 浏览器闭环、Exact 0.2 原生接口本地 Gate

2026-09-14 对齐：本文早期版本迁移、兼容 fixture 与历史 Gate 描述仅保留原设计依据，不是当前实现或待办。当前项目仅维护单一契约，按产品宪法 §10及工作进度执行；不恢复迁移器或已删除测试。

0. 实施状态（2026-09-08 修订）

Section titled “0. 实施状态（2026-09-08 修订）”

本 RFC 决定的建模能力仍然有效，其交付载体已被取代。

  • 仍然成立：sketch.rectangle@1.0.0 与 exact.linearExtrude@1.0.0 两个几何 Operation、 它们的 Capability、以及“不暴露 OCCT/PlaneGCS/矩阵脚本/任意代码执行”的边界——这些已迁移到 AMIR 0.4 的 Operation Module 目录并在产品路径上执行。
  • 已退役：本文正文所依据的 amir/0.2 / core/0.2 compatibility line、amir.ops/0.2.0 目录、 exact-interface-context-v0.2 与 exact-interface-results-v0.2，连同 0.1 的 amir-core.schema.json 与 core-contracts.schema.json，已于 2026-09-08 删除：软件未发布， 没有需要按这些契约打开的既有文档，而 0.4 schema 原先由 0.2 派生，不断开就无法退役。
  • 同时退役：RFC-0002 的九元操作接口在产品路径上已被两个 AI SDK 工具取代， 见 RFC-0002 §13.2。

因此下文对 0.2 schema 文件、catalog id 与 hash 的具体引用是历史记录，不再指向仓库中存在的工件； 当前的等价物见 AMIR 规范与 packages/aira-contracts/fixtures/operation-catalogs/exact-phase1-v0.4.12.catalog.json。

1. 决议

Section titled “1. 决议”

Aira 的首个公开 Exact authoring 合同采用新的 AMIR 0.2 compatibility line，不在现有 0.1 Schema 中追加 enum 值。它只公开两个几何 Operation：

  1. sketch.rectangle@1.0.0：从明确平面和参数创建可编辑 Sketch2D 与有效 Profile2D；
  2. exact.linearExtrude@1.0.0：从 Profile2D 创建以 B-Rep 为权威表示的 ExactSolid。

对应 Capability 为：

  • cap:model.sketch.rectangle@1；
  • cap:model.exact.linear-extrude@1；
  • 复用语义不变的 cap:model.parameter.set@1 完成尺寸编辑。

它们继续使用 RFC-0002 的九个元操作，不增加顶层工具，不暴露 OCCT、PlaneGCS、Manifold、矩阵脚本或 任意代码执行。当前 mesh.box@1.0.0 产品路径不被偷偷重新解释为 Exact authoring。

2. 为什么必须新 compatibility line

Section titled “2. 为什么必须新 compatibility line”

当前受 Schema Registry、Rust Core、M3 Gate 和 canonical hash fixture 约束的公开 AMIR 0.1 实现只 接受 MeshSolid port 与六个 mesh Operation。AMIR-v0.1.md 中的 Sketch/Exact 章节仍是 Draft 设计上限， 不是已经发布的 wire contract。

增加 Sketch2D、Profile2D、ExactSolid 和新 Operation 会扩大 JSON Schema 接受集。按 ADR-CORE-001，禁止原地修改 amir/0.1：

  • 现有 amir-core.schema.json、core-contracts.schema.json、M1/M3 catalog 与历史 hash fixture 保持不变；
  • 新建 amir/0.2 与 core/0.2 Schema line，document/protocol version 从 0.2.0 开始；
  • 新 Operation Catalog 为 amir.ops/0.2.0；
  • 一个 Task Capsule 只能锁定一个 interface/AMIR/catalog 组合，禁止跨 line 拼装 Patch。

Patch Envelope 本身不重复携带 amirVersion；Core 必须由已验证 Task Capsule 选择对应 line 的 decoder。 Document decoder 则必须同时核验 $schema、amirVersion 与 revision.operationCatalog，不能假设代码生成类型 会完整执行 JSON Schema 的 const 约束。

2.1 已冻结 Core 0.2 的两个接口缺口

Section titled “2.1 已冻结 Core 0.2 的两个接口缺口”

实现 Exact 原生接口时发现，已经冻结的 core-contracts-v0.2.schema.json 有两个不能原地修正的事实：

  1. InterfaceManifest.protocolVersion 是 0.2.0，但其 TaskCapsule.protocolVersion 字面量仍为 0.1.0；
  2. ModelPreviewOutput 的 evidence 仍指向旧 MeshSolid/Manifold 几何 bundle，不能表达 OCCT provisional Exact evidence。

裁决是增加两个语言中立的绑定合同，而不是重写冻结 schema、伪造类型转换或再建一套建模语言：

  • exact-interface-context-v0.2 明示并哈希绑定 interface/Task Capsule/AMIR/catalog、完整 discovery catalog、 selected capability contracts、Runtime Snapshot、Session Grant、当前 Revision/model/authoring lock；
  • exact-interface-results-v0.2 只替换 Exact model.preview 的模型可见结果投影，携带 Candidate、preview receipt 与 OCCT Exact evidence 的紧凑 hash binding；完整 B-Rep/history/certificate evidence 仍由浏览器持久化。

两者都是 Aira Interface 合同，不进入 AMIR authoring identity，也不改变九元操作。旧 Core/AMIR 0.2 文件 继续逐字节冻结；后续若要统一 Task Capsule 字面量或通用多表示 response union，必须发布新的 compatibility line，不能把本附加合同反向写进 0.2。

3. 三层真相边界

Section titled “3. 三层真相边界”

3.1 Revision authoring truth

Section titled “3.1 Revision authoring truth”

进入 ModelHash、RevisionId 或其 authoring lock 的内容为：

  • Parameter、单位、范围和表达式；
  • NodeId、Operation ref/version、typed inputs、port declarations 与稳定语义角色；
  • sketch plane、局部坐标、extent/direction policy；
  • BodyId、root 与 ExactSolid authority binding；
  • Operation Catalog、tolerance profile、规范化和迁移记录。

3.2 Evaluation truth

Section titled “3.2 Evaluation truth”

下列内容绑定 Revision/Evaluation/ExecutionManifest，但不嵌入 AMIR Document：

  • PlaneGCS 解出的坐标、DOF、residual 和 conflict diagnostics；
  • materialized Profile2D loops；
  • OCCT handle、B-Rep bytes、history、ArtifactGraph 与 face content IDs；
  • Exact→Mesh translation、loss certificate、RenderPacket 与 Three.js buffers；
  • kernel build、WASM hash、worker trace 与性能指标。

ExactSolid authority 表示“这个 typed Operation 的成功结果是 Body 的设计权威”，不表示把 B-Rep bytes 写进 Revision，也不表示数学精确实数证明。

3.3 Publication truth

Section titled “3.3 Publication truth”

发布是 branch pointer 的 CAS 事件。它产生独立 PublicationReceipt，记录 before/after head、Task、 Exact evidence hash、actor、时间与 CAS 结果；Receipt 不改变已验证 Revision 的内容身份。

4. sketch.rectangle@1.0.0

Section titled “4. sketch.rectangle@1.0.0”

4.1 输入与输出

Section titled “4.1 输入与输出”
Port 类型 约束
plane PrincipalPlane `XY
centerU Length plane-local 坐标，可为 ParameterRef
centerV Length plane-local 坐标，可为 ParameterRef
width Length 必须大于 modeling tolerance
height Length 必须大于 modeling tolerance

输出：

Port 类型 语义
sketch Sketch2D 四条有向边、四个顶点和 fully-constrained rectangle 语义
profile Profile2D 由同一边界形成的单外环、无孔、正向、无自交区域

该 Operation 是语义 primitive，不是把当前 ExactProfileExtrudeRequest 复制进 AMIR。实现可以用 PlaneGCS、 解析式或其他 adapter 求值，但 backend、初值、矩阵和浮点坐标不进入 authoring identity。

4.2 稳定角色

Section titled “4.2 稳定角色”

Operation descriptor 固定下列 authoring roles：

  • edges：edge.uMin、edge.uMax、edge.vMin、edge.vMax；
  • vertices：vertex.uMin.vMin、vertex.uMin.vMax、vertex.uMax.vMin、vertex.uMax.vMax；
  • region：profile.outer。

角色由 NodeId + Operation version + role 定位，不由数组顺序或求值坐标定位。ArtifactGraph 的实际 subentity ID 仍是 artifact-local 内容身份；角色只是 SemanticRef authoring witness。

4.3 必需后置条件

Section titled “4.3 必需后置条件”
  • DOF = 0；
  • 四条边非退化、端点闭合；
  • profile simple、正向、面积大于 tolerance；
  • role→artifact mapping 完整且一对一；
  • 失败时不得 materialize Profile2D artifact。

5. exact.linearExtrude@1.0.0

Section titled “5. exact.linearExtrude@1.0.0”

5.1 输入与输出

Section titled “5.1 输入与输出”
Port 类型 约束
profile Profile2D 必须来自成功、同 Evaluation DAG 可达的 profile artifact
distance Length 必须大于 modeling tolerance
extentMode LinearExtrudeExtentMode `positive
directionMode ProfileNormalDirection `profileNormal

输出 solid: ExactSolid。v1 不支持 arbitrary vector、two-distance、to-face、up-to-next、draft 或 thin feature；新增这些语义必须升级 Operation version，不能由 adapter 私自解释。

positive 的 signed interval 为 [0,distance]；symmetric 为 [-distance/2,+distance/2]。directionMode 决定 interval 正轴，禁止用负 distance 暗示方向。

5.2 稳定角色与 history

Section titled “5.2 稳定角色与 history”
  • cap.start、cap.end 由 signed interval 定义；
  • 每个 profile boundary role 必须通过 direct history 产生唯一 side face；
  • side face authoring witness 为 profile role + exact.linearExtrude NodeId；
  • OCCT face index、遍历顺序、裸 handle 和 triangulation index 永远不是 SemanticRef。

5.3 必需发布前检查

Section titled “5.3 必需发布前检查”
  • B-Rep serialization 与 content hash 可重建；
  • kernel 在锁定 tolerance 下报告 valid、closed solid；
  • volume 为正，bounds/orientation 与 Profile/extent 一致；
  • cap 与全部 side face lineage 完整，无 unmapped result face；
  • Exact→Mesh translation 与 Manifold 独立拓扑检查通过；
  • Geometry Certificate、ArtifactGraph、translation evidence 与 task Revision binding 一致。

任何一项为 fail 或 required-unknown，都不得发布用户 head。

6. Capability 与 AI 操作面

Section titled “6. Capability 与 AI 操作面”

新 Capability 只加入 0.2 catalog，绝不修改 M1_CAPABILITIES 或历史 M3_CAPABILITY_CONTRACTS。

Capability Target AI 可见的核心信息
cap:model.sketch.rectangle@1 sketch.rectangle@1.0.0 typed plane/center/width/height、roles、profile 后置条件
cap:model.exact.linear-extrude@1 exact.linearExtrude@1.0.0 Profile2D 前置、extent/direction、ExactSolid/lineage/certificate 后置
cap:model.parameter.set@1 Patch template 修改既有参数，不重建 NodeId/BodyId/role witness

catalog.search/describe 暴露完整锁定合同；small-catalog 可以内联，但仍计入 catalog hash。examples 只提高 成功率，不定义合法性。Core validator、Task Protocol、Session Grant 和 runtime snapshot 始终是 authority。

7. Task Revision 与用户发布

Section titled “7. Task Revision 与用户发布”

公开 Exact authoring 的标准路径为：

user head H0
  → fork task branch at H0
  → typed AMIR 0.2 Patch / Candidate C1
  → provisional Exact evaluation（Candidate source；不得伪造 RevisionId）
  → previewToken
  → authoritative-exact ValidationReceipt(C1, modelHash, authoringLockHash,
      executionManifestHash, evaluationId, geometryCertificateHash)
  → task commit R1（ValidationToken 消费后才产生真实 RevisionId）
  → committed R1 replay（Exact + history + Exact→Mesh + RenderPacket）
  → durable Candidate evidence + durable Revision replay evidence
  → CAS adopt R1 as user head
  → PublicationReceipt(H0 → R1)

关键裁决：用户分支必须直接采用已验证的同一个 R1，不得为了记录 publisher 再生成语义相同的第二个 Revision。 actor、发布时间和审计信息属于 PublicationReceipt/Event Log，不应复制模型快照。

provisional evaluation 与 committed replay 是两个不同作用域的证据事件：前者证明 Candidate 可以被 Exact kernel 接受，是 Core 产生 ValidationToken 的输入；它的 source 只能是 candidateId + baseRevision + patchHash，不得提前声称 RevisionId。后者在 task commit 后重新执行完整 Exact→Mesh 链，把同一 B-Rep 结果、history、translation 与 RenderPacket 绑定到 R1。只有 committed replay evidence 已持久化，且 CAS 时仍能按 evaluation ID、evidence hash、task head 与 parent 复核，用户 head 才能移动。

当前主线已把 Exact box 与 M3 task publication 从“重提交 + modelHash equality”迁到同一 Revision 的 branch pointer adoption；数据库 v3 与 AMIR 0.2 transaction session 已支持：

  • project-global immutable Revision object；
  • branch-local head/reflog；
  • CAS 直接移动 head 到已存在的、父为 H0 的 task Revision；
  • evidence 与多个 branch reachability 解耦；
  • provisional Candidate evidence 与 committed Revision replay evidence 分开持久化；
  • stale head、取消、provisional Exact fail、committed replay fail、binding tamper 均保持用户 head 不变。

8. SemanticRef 生存规则

Section titled “8. SemanticRef 生存规则”
  1. Parameter edit 保留 NodeId、BodyId 与 authoring role，重新求值产生新的 artifact-local subentity ID；
  2. resolveAcross 使用旧/新 ArtifactGraph lineage 决定 resolved、ambiguous 或 missing；
  3. rectangle 宽高变化期望四条 edge role 与六个 extrude face role 全部生存；
  4. Operation version、plane、extent policy 或 profile topology 改变时不得假定生存；
  5. exactly-one 无法证明时禁止静默选择 face；silent wrong rebind 必须为 0。

9. 0.1 → 0.2 迁移

Section titled “9. 0.1 → 0.2 迁移”

AMIR 0.2 必须继续表达现有 mesh Operation，使 0.1 文档可以显式、无几何改写地迁移。迁移会更新 schema/catalog lock、写入 migration record 并产生新的 ModelHash/RevisionId。

禁止的“迁移”：

  • 把 mesh.box 自动替换成 sketch.rectangle + exact.linearExtrude；
  • 把 Manifold mesh、Exact verifier 或视觉相似解释成 B-Rep authoring history；
  • 复用旧 MeshSolid artifact/subentity ID 作为新 ExactSolid identity。

Mesh→Exact 只能是用户或 AI 明确提出、经过 capability discovery、验证和损失披露的新建模事务。

10. 公开启用 Gate

Section titled “10. 公开启用 Gate”

RFC 状态不等于 production enablement。新 capability 只有同时满足以下条件才可加入 runtime manifest：

  1. amir/0.2、core/0.2 与 amir.ops/0.2.0 有独立 schema、canonical hash 和跨 Rust/TS fixture；
  2. 0.1 schema/catalog/hash fixture 逐字节不变；
  3. rectangle create 与 width/height/distance edit 保留稳定 authoring roles；
  4. Exact worker 先对 Candidate 真实执行 provisional B-Rep/history/certificate，commit 后再对同一 Revision 真实重放 B-Rep/history/translation/RenderPacket；不能只检查报告字段；
  5. user publish 直接采用同一个 task RevisionId；
  6. stale CAS、provisional Exact fail、committed replay fail、取消、binding tamper、unmapped face 和 required-unknown 零用户写入；
  7. capability search/describe、Task Capsule、Grant、Snapshot、catalog/contract hash 和 Exact response binding 通过 contracts/browser/gateway 共享 conformance；
  8. 九元操作集合不变，provider 默认停止；
  9. 旧 mesh.box 产品路径仍可读、可重放，不被重新解释；
  10. Google Chrome 通过原生九元 Aira Interface完成创建、参数编辑、重新求值、read-back、历史与恢复， console error 为 0；此前直接调用 session helper 的 Chrome Gate 不替代本项。

11. 明确拒绝

Section titled “11. 明确拒绝”
  • 不把 local spike request、OCCT binding 表或 solver matrix 作为 AMIR；
  • 不把 B-Rep bytes、RenderPacket 或 Three.js Object3D 放进 Revision；
  • 不因类型名为 ExactSolid 就跳过 Certificate；
  • 不以第二个“相同 modelHash” Revision 代替 branch pointer adoption；
  • 不增加 model.publish 第十个元操作；publish 是受信 runtime 对已验证 model.commit 的 CAS effect；
  • 不在本 RFC 中顺带加入 arc/spline、holes、revolve、sweep、loft、fillet、shell 或 STEP direct edit。

12. 实施顺序

Section titled “12. 实施顺序”
  1. 冻结语言中立 0.2 schema、operation descriptors、capability contracts 与 migration fixtures；
  2. 让 Rust Core 同时解码/验证 0.1 与 0.2，保持 hash 算法版本显式；
  3. 把现有 rectangle/profile/exact adapter 接到 0.2 Node evaluation；
  4. 把 IndexedDB 从 branch-owned RevisionRecord 迁为 global Revision + branch reflog，并实现 CAS adoption；
  5. 完成 AMIR 0.2 Candidate→provisional Exact→ValidationToken→task Revision→committed replay→CAS adoption 自动 Gate与真实 Chrome Gate；
  6. 完成 capability search/describe、Task Capsule、Grant、Snapshot、Exact response profile 与 gateway/browser 本地共享 conformance；
  7. 再完成原生接口真实 Chrome Gate，才把 RFC 与 capability 标为 Accepted/Enabled。

13. 当前实施状态

Section titled “13. 当前实施状态”

截至 2026-08-31，实施顺序第 1–7 项已经完成：

  • 独立生成并登记 amir/0.2、core/0.2 与 operation-catalog/0.2 schema；
  • amir.ops/0.2.0 含五个原样保留的 mesh Operation 与两个 Exact Operation，其 JCS hash 为 sha256:9dde85545368e94d72abd1f32756af865e4e092773d50c919bb4a54f83dc0275；
  • TypeScript/Ajv 与 Rust/serde-jcs 对 namespace-only migration、rectangle→extrude fixtures 的 canonical/model hash 独立复算一致；
  • Rust Core 保留 0.1 entrypoint，同时新增独立 0.2 document/patch decoder 与静态 validator；三个 line identity 字段不匹配时 fail closed；
  • 旧 0.1 两个 schema、M1 catalog、model/revision hash manifests 均有 byte lock；M1/M3 仍为六项， Exact capability 只进入独立 0.2 runtime snapshot；
  • Schema Registry 已升至 0.5.0，28/28 schema 登记为 19 public contract + 9 spike-local；v0.1–v0.5 治理收据保持原字节；
  • IndexedDB v3 将 RevisionRecord 改为 project-global immutable object；branch head 以有序 reflog 记录 genesis/fork/commit/adopt，v2 数据按 parent chain 迁移；
  • publishTaskBranch 在 CAS 前验证 task head、Revision parent、持久 evidence 与可恢复 Core，随后直接采用 同一个 task RevisionId，并生成独立 PublicationReceipt；stale CAS 不移动 head、不写 receipt。
  • 浏览器新增独立 Rust/WASM validateAmirV02Json trust boundary：原始 JSON 必须先通过重复键/I-JSON、 生成类型与静态语义验证，Rust 重新序列化后才交给 evaluator；这不是 0.2 transaction engine；
  • 0.2 evaluator 按 root/Body/port 遍历 sketch.rectangle → Profile2D → exact.linearExtrude DAG， 解析 Length/ParameterRef、生成稳定构造角色，并复用既有 PlaneGCS/Profile2D/OCCT/Exact→Mesh worker；
  • AMIR context 与公开 exact.linearExtrude@1.0.0 producer 进入独立 exact-feature-execution/0.2 与 exact-feature-candidate-evidence/0.2；旧 0.1 profiles 保持不变；
  • adapter 当前仅认证 XY + profileNormal；其他 principal plane 与 opposite direction 明确 fail closed。
  • Rust Core 新增编译期隔离的 AMIR 0.2 transaction engine；0.1/0.2 document、patch、ModelHash、RevisionId 与 authoring lock 不交叉解释，0.2 authoritative validation profile 固定为 authoritative-exact；
  • Candidate Exact source 不携带 RevisionId；provisional certificate 完整绑定 Candidate/model/manifest/ evaluation/ArtifactGraph，ValidationToken 消费后才产生 task Revision；
  • 浏览器 session 已实现 task fork、propose、provisional Exact、preview、Core validate、task commit、Candidate evidence 持久化、committed Revision 全量 replay、replay evidence 持久化与 evidence-gated CAS adoption；
  • 自动 Gate 覆盖 blank create、parameter edit、provisional/replay failure 零用户写入、stale CAS refresh 与 IndexedDB reopen；真实 Google Chrome 已完成 24×16×8 create、distance 8→10 edit、三 Revision history、 两份 task evidence、两份 PublicationReceipt、Three.js RenderPacket 与 console 0 warning/error；
  • workspace 构建现在通过 @aira/replicad 的 build:aira 直接编译维护版源码扩展，并按当前 feature-graph 收据恢复和校验密封运行时，避免源码与浏览器实际加载的 package export 漂移。旧 @aira/occt-spike adapter 已退出当前树；历史收据由不可变 Git 快照重放。
  • 已冻结附加 Exact context schema（NFC-JCS hash sha256:e3335ee7241e618e9aa5c287255cf19ffdc6b3cd6fb314d29f519f617d4831d1）与 Exact results schema （NFC-JCS hash sha256:0ca04e49e3ce7a3ea68e51abea5426c6d074f66b615cbfc182e49d38f6e15f50）， 不改写冻结 Core/AMIR 0.2；
  • 完整 small catalog 含 rectangle、linear extrude、parameter set 三份 Capability Contract；Task context 将 catalog/contract、Snapshot、Grant、Task Capsule、Revision/model/authoring lock 与响应 profile 全部 hash 绑定；catalog、contract、runtime、grant、capsule、authority 六类篡改由三端共享 corpus fail closed；
  • gateway 在 adapter/provider 前验证同一 context，Exact 轮机械投影 Core/AMIR 0.2 tool schema，并逐轮记录 projection binding；测试只使用本地 fixture/mocked transport，真实 provider 调用为 0；
  • 浏览器 Phase1ExactSession 已作为真实 native transaction backend：九元操作集成测试覆盖 discovery、read、 propose/preview/validate/commit、read-back 与 revert；前三个写入阶段不移动 user head，commit 经 task Revision replay/evidence/CAS 才发布。

真实 Google Chrome 已从原生接口而非直接 session helper 驱动同一条 create/edit/revert 产品链，并取得 console 0、持久化、重开、committed replay 与 Three.js 可视证据。启用前后两次运行的 Exact B-Rep hash 一致；snapshot:aira-phase1-exact-occt-browser@1、公开 capability 与顶层 evaluator evidence 现统一为 productionEnabled=true。本决议没有增加第十个元操作，也没有认证 §11 明确排除的后续 Phase 1 能力。