AMIR：Aira Modeling Intermediate Representation 规范：扩展、示例与实现符合性

主文档与完整目录。本分篇与主文档共同构成同一规范，版本、状态与权威以主文档为准；仅拆分阅读结构，条款编号和正文语义不变。

15. 当前版本与扩展

amirVersion 和 opVersion 遵循 SemVer：

• 不认识的 AMIR major version 必须拒绝执行；
• 同 major 的新 minor 可以增加 optional 字段或 Operation，但不得重解释已有字段；
• 改变单位、默认值、端口类型、Field kind、转换误差语义或拓扑角色必须提升相应 major version。

扩展字段只能置于 extensions 下，并使用反向域名或组织命名空间。每项必须采用固定 envelope：

{
  "com.aira.experimental.material": {
    "version": "1.0.0",
    "semantic": true,
    "payload": { "name": "Aluminum" }
  }
}

除 version、semantic、payload 外不得出现未知 envelope 字段。读取器必须原样保留未知 extension。未知 extension 若声明 semantic: true，不理解它的执行器必须拒绝 authoritative evaluation；非语义 extension 可以忽略执行但必须 round-trip。

【当前实现】 项目尚未正式发布，只接受 amirVersion: 0.4.0 的当前契约。旧版读取线、RevisionMigrationRecord、迁移 actor 和修订 hash 槽位均已删除；不保留升级、迁移或兼容别名。当前撤销/重做通过普通 Patch 和新 Revision 完成，重新验证后原子提交，不改写历史。

16. 当前最小 Document

当前空白 Document 的唯一构造入口为 createBlankOperationModuleDocumentV04，结构由 AMIR 当前 schema 定义。构造结果是 draft，进入 Rust Core 后才生成并校验 committed RevisionId；调用方不得自造该身份。

本文不再复制旧版完整 JSON 示例。程序、约束草图、拉伸等节点的当前输入以 Operation Module 及其 node schema 为准，发现和执行都读取同一目录。

17. 失败示例

以下示例是规范要求的结构化失败，而不是唯一文案。

17.1 单位维度不匹配

将 Angle 连接到 exact.extrude.distance: Length 时，必须在静态阶段失败：

{
  "id": "diag:unit-mismatch-example",
  "code": "UNIT_DIMENSION_MISMATCH",
  "severity": "error",
  "phase": "static",
  "at": {
    "nodeId": "n.extrude",
    "port": "distance"
  },
  "details": {
    "expectedType": "Length",
    "actualType": "Angle",
    "source": "p.draftAngle"
  },
  "messageKey": "type.unit.dimensionMismatch",
  "fixes": []
}

禁止把数值 5 deg 去掉单位后当作 5 mm。

17.2 Feature DAG 循环

n.a#solid 依赖 n.b#solid，而 n.b#solid 又依赖 n.a#solid 时：

{
  "id": "diag:feature-cycle-example",
  "code": "DEPENDENCY_CYCLE",
  "severity": "error",
  "phase": "static",
  "at": {
    "nodeId": "n.a"
  },
  "details": {
    "cycle": [
      "n.a#solid",
      "n.b#solid",
      "n.a#solid"
    ]
  },
  "messageKey": "graph.featureCycle",
  "fixes": [
    {
      "kind": "manual",
      "action": "breakDependency"
    }
  ]
}

循环中的 Node 及其后继必须为 blocked，不得执行内核。

17.3 SemanticRef 基数歧义

要求 exactly one face，但解析到四个候选时：

{
  "id": "diag:semantic-ref-example",
  "code": "SEMANTIC_REF_AMBIGUOUS",
  "severity": "error",
  "phase": "resolve",
  "at": {
    "semanticRefId": "s.mountFace"
  },
  "details": {
    "expected": { "min": 1, "max": 1 },
    "actualCount": 4,
    "candidates": [
      { "artifactSubEntityId": "face:a", "role": "side" },
      { "artifactSubEntityId": "face:b", "role": "side" },
      { "artifactSubEntityId": "face:c", "role": "side" },
      { "artifactSubEntityId": "face:d", "role": "side" }
    ]
  },
  "messageKey": "selection.semanticRef.ambiguous",
  "fixes": [
    {
      "kind": "patchTemplate",
      "action": "addPredicate",
      "suggestedPredicate": "face.normalParallelTo"
    }
  ]
}

执行器禁止偷偷采用 face:a。

17.4 有损转换无法满足误差预算

Field mesher 只能估计误差，而 Node 要求可证明上界时：

{
  "id": "diag:error-bound-example",
  "code": "ERROR_BOUND_UNAVAILABLE",
  "severity": "error",
  "phase": "conversion",
  "at": {
    "nodeId": "n.fieldBake",
    "port": "errorBudget"
  },
  "details": {
    "conversion": "Field3D<GeneralImplicit> -> MeshSolid",
    "requireBoundedError": true,
    "availableEvidence": "measuredEstimate",
    "requestedEvidence": "provenUpperBound"
  },
  "messageKey": "conversion.errorBound.unavailable",
  "fixes": [
    {
      "kind": "patchTemplate",
      "action": "allowEstimatedError"
    },
    {
      "kind": "manual",
      "action": "chooseCertifiedMesher"
    }
  ]
}

18. MVP Operation Catalog

本节保留 v0.1 的能力建议表作为目标清单，并按 0.4 运行时标注状态。live 目录是 exact-phase1-v0.4.12.catalog.json， 共 11 个模块，与 exact-feature-graph.ts 的执行分支逐一对应：

状态	Operation
【已实现】	exact.program@4.0.0、exact.importedBRep@2.0.0、exact.linearExtrude、exact.revolve、exact.boolean.difference、exact.shell、exact.fillet、exact.chamfer、exact.holeArray、sketch.rectangle、sketch.constrainedProfile
【契约】	field.gyroid、field.beamLattice、field.smoothUnion、convert.fieldToMesh（Lane F，无执行器）；convert.exactToMesh 以表示转换实现
【未实现】	下表其余全部，含下表 assembly.* 操作（不代表文档级 product 未实现）

能力发现现在只有一个权威：exact-phase1-v0.4.x。曾与它并列的 amir.ops-v0.3.0 目录 （连同 operation-catalog-v0.3.schema.json 与其 lock）已于 2026-09-08 删除——没有任何代码读取过它， 0.4 线也从未续写这套清单机制。随它一起消失的是只登记在那里的 mesh.* 五个 op：它们从来没有产品执行器， “已登记但不可执行”本身就是这份冗余在制造的假象。要重新引入 mesh 表示时，按当时的事实进入 live 目录。 表中类型为规范签名摘要。

18.1 Sketch/Profile

状态：仅 sketch.rectangle 已实现；sketch.constrainedProfile 承担了 sketch.solve + sketch.profile 的职责；其余【未实现】。

Operation	主要输入	输出	关键后置条件
sketch.empty	Plane3D	Sketch2D	稳定空 entity map
sketch.line	Sketch2D, Point2, Point2, entityId	Sketch2D	entityId 唯一，非零长度
sketch.circle	Sketch2D, Point2, Length, entityId	Sketch2D	radius > tolerance
sketch.arc	Sketch2D, Point2, Length, Angle, Angle, entityId	Sketch2D	非退化弧
sketch.rectangle	PrincipalPlane/Plane3D, Point2, Length, Length	Sketch2D, Profile2D	宽高为正、闭合无自交
sketch.solve	Sketch2D, List<Constraint>	Sketch2D	报告 DOF/ConflictSet
sketch.profile	Sketch2D, EntitySet<SketchEntity>	Profile2D	闭合、定向、无自交
profile.boolean	Profile2D, Profile2D, BooleanMode	Profile2D	有效平面区域

18.2 Exact/B-Rep

状态：exact.extrude（实现名 exact.linearExtrude）、revolve、boolean.difference、fillet、chamfer 已实现，另有 shell；box、cylinder、boolean.union、boolean.intersection、transform【未实现】。

Operation	主要输入	输出	默认能力路由
exact.box	Length x3, anchor, Transform3D	ExactSolid	exact.primitive.box
exact.cylinder	Length radius, Length height, Axis3D	ExactSolid	exact.primitive.cylinder
exact.extrude	Profile2D, Length, Direction3, Bool symmetric	ExactSolid	exact.brep.extrude
exact.revolve	Profile2D, Axis3D, Angle	ExactSolid	exact.brep.revolve
exact.boolean.union	List<ExactSolid>	ExactSolid	exact.boolean
exact.boolean.intersection	ExactSolid, ExactSolid	ExactSolid	exact.boolean
exact.boolean.difference	ExactBRep base, ExactBRep tool	ExactSolid	两个输入均须为有效单实体，结果实际去料且仍为非空单实体
exact.transform	ExactSolid, Transform3D	ExactSolid	保持 B-Rep 表示
exact.fillet	ExactBRep, EntitySet<Edge>, Length	ExactSolid	有效单实体；所有指定边成功或原子失败
exact.chamfer	ExactBRep, EntitySet<Edge>, Length	ExactSolid	有效单实体；所有指定边成功或原子失败
exact.shell	ExactBRep, EntitySet<Face>, Length, side	ExactSolid	有效单实体及唯一来源开口；计划入口当前选择一个面

Loft、sweep、draft【未实现】；shell 已实现为 exact.shell，STEP 读入已实现为 exact.importedBRep，导出是绑定 Revision 的派生 job 而非 Feature Node。任何新增 operation 都必须有明确失败模型和稳定 descriptor。

18.3 Mesh、Field、转换与 Assembly

状态：Mesh【休眠】；Field 与 convert.fieldToMesh【契约】；convert.exactToMesh【已实现】；convert.meshToField 与下表 assembly.* 操作【未实现】；文档级 product 的共享定义、实例和空间关系已接入，当前工程消费者范围见 M2 方案。

Operation	主要输入	输出	契约
mesh.box	Length x3, anchor, Transform3D	MeshSolid	三个长度为正；输出必须是闭合 2-manifold
mesh.cylinder	Length radius, Length height, Count circularSegments, Axis3D	MeshSolid	radius/height 为正，circularSegments >= 3；分段数进入模型语义与 hash
mesh.import	BytesHash contentHash, MeshFormat format	RawMesh	从预注册的内容寻址 Asset Store 读取；不声称 manifold
mesh.validateSolid	RawMesh/MeshSurface	MeshSolid	不修复；所有 MeshSolid invariant 必须 pass
mesh.boolean.union	List<MeshSolid>	MeshSolid	输出必须重新验证 2-manifold/watertight
mesh.boolean.intersection	MeshSolid, MeshSolid	MeshSolid	同上
mesh.boolean.difference	MeshSolid, List<MeshSolid>	MeshSolid	同上
mesh.transform	MeshSolid, Transform3D	MeshSolid	负 determinant 时必须修复绕序并记录
field.sphere	Point3, Length	Field3D<TrueSDF>	负内正外
field.box	Point3, Vec3<Length>, Transform3D	Field3D<TrueSDF>	Transform 必须为刚体；非刚体用单独 op
field.union	List<Field3D<K>>	Field3D<GeneralImplicit>	MVP 保守降级，不冒充 TrueSDF
field.intersection	List<Field3D<K>>	Field3D<GeneralImplicit>	同上
field.difference	Field3D<K>, List<Field3D<K>>	Field3D<GeneralImplicit>	同上
field.smoothUnion	Field3D<K>, Field3D<K>, Length	Field3D<GeneralImplicit>	smoothing radius > 0
field.gyroid	Transform3D, Length period, Real iso	Field3D<GeneralImplicit>	可声明 mathematicalDomain=allSpace；每次预览/烘焙必须给有限 clip/bounds
field.rigidTransform	Field3D<K>, Transform3D	Field3D<K>	Transform 必须刚体，保持 kind
convert.exactToMesh	ExactSolid, ExactMeshErrorBudget	MeshSolid	显式近似和证书
convert.fieldToMesh	Field3D<K>, Box3D, FieldMeshErrorBudget	MeshSolid	结果必须验证，记录 mesher
convert.meshToField	MeshSolid, MeshFieldSampling	Field3D<GeneralImplicit>	显式体素/距离误差
assembly.compose	List<AssemblyItem>	Assembly	instance ID 唯一、无环
assembly.transformInstance	Assembly, InstanceRef, Transform3D	Assembly	不修改 part definition

18.4 MVP Constraint 与 Assertion

状态：约束 14 种中 9 种【节点内实现】（缺 equalLength、equalRadius、distanceX、distanceY、diameter、midpoint、fix）；断言 9 种中 3 种【已实现】。

下表是 v0.1 的目标清单，不是当前能力清单。运行时只有 assert.validSolid、assert.bounds、 assert.holeArray 有求值器；其余任一断言出现在文档里都会让整次求值以 EXACT_GRAPH_ASSERTION_UNKNOWN 硬失败（apps/web/src/feature-graph/amir-v0.4-exact-feature-graph.ts）， 而不是降级为 unknown 后继续。因此“在清单里”只表示保留了这个名字，不表示可以写进模型。

Constraint kind：

• sketch.coincident、horizontal、vertical；
• parallel、perpendicular、tangent；
• equalLength、equalRadius；
• distance、distanceX、distanceY；
• angle、radius、diameter；
• midpoint、fix。

Assertion Operation：

• assert.validSolid；
• assert.watertight；
• assert.manifold；
• assert.noSelfIntersection；
• assert.fullyConstrainedSketch；
• assert.semanticRefCardinality；
• assert.boundingBoxWithin；
• assert.volumeBetween；
• assert.minThickness。

耗时较高或无法在当前后端证明的 Assertion 必须返回 unknown，并遵守其 onUnknown，不得伪造 pass。

19. JSON Schema 拆分建议

应采用 JSON Schema Draft 2020-12 并拆分为多个 $id。实际拆分以 packages/aira-contracts/schema/ 为准：amir-core-vX（文档核心）、operation-catalog-vX 与 operation-module（目录与模块）、每个 operation 一个 *-node-vN.schema.json、semantic-ref 与选择器、artifact-graph / geometry-evidence（运行时证据）、field-ir 与 smooth-implicit-*（Lane F / Lane R 契约）。v0.1 原建议的目录树已被这一实际结构取代，不再单列。

实施规则：

• 使用 $defs 和 $ref，避免复制 Value、ID、Diagnostic 定义。
• Tagged union 使用 oneOf 加固定 discriminator，并对 object 设置 unevaluatedProperties: false。
• 每个 Operation input schema 应从 Operation Catalog descriptor 生成；TypeScript、Rust 类型和 AI tool schema 应来自同一来源。
• schema release 必须附带正例、负例和跨语言 conformance fixtures。
• Schema 只负责结构，无法完整证明 Document Dependency Graph/Feature DAG 无环、Port assignability、单位代数、SemanticRef runtime cardinality、revision hash 或几何后置条件；这些必须由单独的 semantic validator 和 executor 实现。
• schema URI 和 Operation Catalog 必须内容寻址或版本锁定，禁止 production evaluator 动态读取不受信任的 latest schema。

20. 实现符合性级别

实现可以声明以下逐级能力：

1. AMIR Reader：解析 canonical JSON，保留未知非语义 extensions。
2. Structural Validator：通过 Draft 2020-12 Schema。
3. Semantic Validator：实现 ID、类型、单位、完整 Document Dependency Graph、Feature DAG、Port 与 conversion 规则。
4. Transaction Store：实现 Patch、preview token、validation token、CAS commit、idempotency 和 Revision hash。
5. Representation Executor：明确列出支持的 Operation，并为每次执行产生锁定的 ExecutionManifest。
6. Observatory Runtime：生成 ArtifactGraph、Source Map、Diagnostics 与 Geometry Certificate。

任何实现只有同时达到 1–3 才能声称“读取并验证 AMIR”；只有达到 1–6 并通过官方 conformance fixtures，才能声称“完整 AMIR runtime”。

当前运行时的声明：级别 1–4 由 crates/aira-core（Rust，无几何）承担；级别 5 仅覆盖 Exact 与 Sketch，由维护版 Replicad 的 exact-feature-graph.ts 在浏览器 OCCT 上执行，Mesh / Field 与下表 Assembly 操作端口不在此声明范围；文档级 product 的产品执行与工程消费者另由同一 Exact 执行路径承担；级别 6 产出 ArtifactGraph、Diagnostics 与部分 Certificate，Source Map 与确定性等级缺失。因此当前实现不能声称完整 runtime。

---

AMIR 的核心不变量可以压缩成一句话：程序承载意图，AMIR 保证意图可识别、可编辑、可回退、可验证——身份由 hash 确定，编辑由声明与实测守恒约束，任何几何结果都必须能沿 Node、Port、Artifact 与 Certificate 回到其来源和保证。