跳转到内容
Aira 3D

Aira ArtifactGraph v0.x 契约

状态：Draft / MeshSolid + ExactSolid + Field3D Adapters + Translation Gates Implemented
图版本：0.1.0（Mesh/Exact 既有证据）/ 0.2.0（Field3D）
Geometry bundle：0.2.0
Canonical Schema：artifact-graph.schema.json
SemanticRef 依赖：SEMANTIC-REF-v0.1.md
跨表示转换：REPRESENTATION-TRANSLATION-v0.1.md

1. 目的

Section titled “1. 目的”

ArtifactGraph 是 AMIR operation DAG 求值后的、绑定一次 Evaluation 的几何证据图。它回答：哪些 artifact 由哪些 operation 输入生成、最终 body 来自哪个 authority artifact、每个 artifact 当前有哪些可引用子实体， 以及这些子实体来自哪些稳定语义 origin。

它不替代 AMIR：AMIR 是 authoring truth，ArtifactGraph 可删除重建。它也不把 kernel pointer、数组下标、 originalID 或 faceID 提升为持久身份。

2. 身份与绑定

Section titled “2. 身份与绑定”

每个图必须绑定：

  • evaluationId；
  • executionManifestHash；
  • namingAlgorithmVersion；
  • representation；
  • canonical artifactGraphHash。

图 hash 对除自身外的完整规范图计算。它进入 SemanticRef resolution context，但不进入 AMIR RevisionId。 同一 Revision 可因 adapter/kernel/quality profile 不同产生不同 ArtifactGraph；validation token 绑定最终 authoritative ExecutionManifest 和 Evaluation。

3. Artifact 与 derivation

Section titled “3. Artifact 与 derivation”

当前有两类 producer：

  1. operation：artifact:node:<nodeId>:solid，绑定 nodeId、输出 port 和完整 operationRef；
  2. body-materialization：绑定 body 与 authority artifact；artifact 命名由表示 adapter 负责。

Field v0.2 的 operation artifact 命名为 artifact:field:<FieldNodeId>:field，每个 Field node 都形成独立、 可内容寻址的 ScalarField artifact；它不是 Solid，也不能被 Face resolver 当作 Solid。

每条 derivation 保存完整 source/target artifact locator、输入名和 ordinal，并以 evidence hash 寻址。 Manifold boolean 的 base/tool 是 sub-entity sourceRole，不是新的 AMIR operation 类型。

4. Face 子实体

Section titled “4. Face 子实体”

v0.1 的 MeshSolid 和 ExactSolid adapter 都只发布 Face 子实体。共同字段为：

  • artifactSubEntityId=subentity:sha256:<digest>；
  • 一个或多个稳定 lineageOrigins；
  • 表示内 canonical bytes 的 geometrySignatureHash；
  • surface area、centroid 和 bounds；
  • direct | base | tool | materialized 来源角色。

表示专属证据必须互斥，不能混装：

representation 专属字段 confidence
MeshSolid triangleCount，签名来自 canonical triangle soup deterministic
ExactSolid edgeCount、brepSizeBytes、serializationFormat=occt-brep-ascii-v3-no-triangulation exact

这里的 exact 只表示 OCCT B-Rep/history 证据没有经过网格近似，不表示形式化精确实数计算。Schema 以 additive union 接纳两种表示；现有 MeshSolid bundle 仍被 GeometryEvaluationBundle 的局部约束锁为 representation=MeshSolid，不会意外接收 ExactSolid 图。

子实体 ID 是 artifact-local 内容身份；跨 Revision 稳定性由 lineage/evolution 证明，不由 ID 字面相等假设。 几何量以固定到 1e-9 mm 的 canonical decimal string 发布，远小于当前 0.001 mm modeling tolerance。

4.1 Field3D Region 子实体

Section titled “4.1 Field3D Region 子实体”

连续标量场没有可枚举的 B-Rep/Mesh Face。Field graph 0.2.0 因此为每个 Field node 发布且只发布一个 entityKind=Region / regionKind=zero-set 子实体，记录：

  • 对应 Field contract 的 hash、kind 与 fieldId；
  • 零面的 proven upper-bound bounds，而不是虚构 surface area、centroid、triangle 或 edge 数；
  • 当前 node 自身及传递依赖的稳定 lineageOrigins；
  • canonical geometrySignatureHash 与 artifact-local Region ID；
  • confidence=deterministic。

Boolean Field 的输入通过 representation-local derivation 连接；derivation source 必须存在于同一个 Field 图， 且 locator content hash 必须匹配。跨表示 Field→Mesh 关系绝不写入任一图，只存在于独立 translation evidence。 攻击者即使篡改 lineage 后重算 graph hash，validateFieldArtifactGraph 仍会用 Typed Field IR 重建完整 canonical 图并以 FIELD_ARTIFACT_GRAPH_MISMATCH 拒绝。

5. Manifold adapter 归约

Section titled “5. Manifold adapter 归约”

锁定的 Manifold 3.5.1 提供 runOriginalID、triangle faceID 和 boolean backside/run 信息。adapter 只在 一次求值进程内读取这些值，然后：

  1. 在 primitive 创建时把 face 归约为稳定 origin：box 的 ±X/±Y/±Z；cylinder 的 ±Z cap 与按角度排序的 侧面 ordinal；
  2. boolean/transform 后按 origin 分组；
  3. 用共享几何边构造 connected components，使一个 origin 的多个不连通后代成为显式 split；
  4. 对每个 component 计算 canonical triangle soup、几何签名和 artifact-local ID；
  5. 丢弃所有瞬时 Manifold ID，不序列化到 ArtifactGraph。

该规则是 aira.semantic-ref/0.1.0 的 MeshSolid 命名算法部分；改变分类、连通性或量化规则必须升级版本。

6. OCCT ExactSolid adapter 归约

Section titled “6. OCCT ExactSolid adapter 归约”

当前 capability-minimal runtime 从 P0B-S3 的 17 bindings 增至 22 bindings。原包虽然在 TypeScript 声明中 出现 Modified/Generated/IsDeleted，真实调用会因 NCollection_BaseList 未绑定而失败；因此它不足以支撑 history adapter。新增的五项为 NCollection_BaseList、TopTools_FormatVersion、Bnd_Box、 BRepBndLib 与 BRepTools，另显式导出 MEMFS 的 FS/FS_readFile/FS_unlink。

adapter 的规则是：

  1. 用 BRepTools.Write 写入 MEMFS，固定 ASCII BRep V3，禁用 triangles/normals；shape bytes 直接形成 content/signature hash；
  2. 用 BRepGProp 与 BRepBndLib.AddOptimal 读取面积、质心和 bounds，用 TopExp_Explorer 计数 edge；
  3. primitive face 在求值进程内归类为稳定 origin；boolean 对每个输入 face 读取 IsDeleted、Modified 和 Generated，将所有结果 face 归约到 lineage origin 集；
  4. 任一输出 face 没有 history 映射即 fail closed；OCCT shape wrapper、指针、枚举序号与 MEMFS 路径均不 进入 ArtifactGraph；
  5. face ID 由 artifact、lineage origin 集和规范 BRep face hash 派生。

曾尝试用 additionalCppCode 包装序列化；它令构建系统退化为约 5,348 bindings 的全量重编译，运行 4,908 秒后终止，因此被否决。采用上游生成的 BRepTools.Write 后维持 22-binding 边界，最终 WASM 为 8,276,727 raw / 3,218,986 gzip-9 bytes。

7. 跨图 evolution

Section titled “7. 跨图 evolution”

同一 artifact ID 的两个图按 lineageOrigin 对齐：

source 数量 target 数量 evolution
0 ≥1 creation
≥1 0 delete
1 1，完整 locator 相同 no-effect
1 1，其余 modified
1 ≥2 split
≥2 1 merge

v0.1 MeshSolid/ExactSolid adapter 不产生 kind-change 或 converted；二者分别由实体种类变化和 representation conversion adapter 负责。多对多暂归为 modified，不得据此自动发布 exactly-one SemanticRef。

Manifold 与 OCCT 各自的真实 through-slot fixture 都已证明 1→2 split 与反向 2→1 merge。两种表示均实际 覆盖 creation/delete/merge/modified/no-effect/split 六类 evolution。OCCT fixture 的正向计数为 2 creation + 2 modified + 4 split，反向为 2 delete + 4 merge + 2 modified；12 个输出 face 全部有 history 映射。split 后 resolver 返回完整两个 candidates，fan-out/cardinality 使结果为 ambiguous、 publishable=false，禁止取第一个。

这证明的是合同同构，不是跨表示 identity translation。Mesh face 与 Exact face 即使拥有相同 evolution kind，也不能据此自动视为同一实体。

8. ExactSolid→MeshSolid 跨表示 translation

Section titled “8. ExactSolid→MeshSolid 跨表示 translation”

跨表示转换不修改 source ArtifactGraph，也不把两个表示的 artifact/subentity ID 合并。独立的 Representation Translation record 以 convertedFrom 连接 source/target artifact，以 tessellatedFrom 连接 face，并同时绑定两个图、转换参数、loss certificate 与 mapping evidence。ArtifactGraph 内部 derivation 继续保持 representation-local；converted evolution 只由该独立转换证据产生。

真实 Gate 使用 36-binding OCCT runtime 对半径 10 mm、高 20 mm 的圆柱 tessellate。3 个 Exact face 均产生 一个 Mesh face mapping；粗预算得到 52 vertices / 100 triangles，细预算得到 252 vertices / 500 triangles， Manifold 3.5.1 对两份结果均报告 NoError。细预算重复执行的 target graph、translation ID、顶点与三角缓冲 完全一致。same-Revision 的两个 representation context 可通过 resolveAcross 得到 converted；人工构造的 split 返回两个 candidates 并变为 ambiguous，missing 与 false-pass 均被拒绝。

OCCT face deflection 加量化焊接位移只发布为 measuredEstimate，不是 proven bound；angular 参数只发布为 requestedOnly。因此 requireBoundedError=true 会 fail closed 为 ERROR_BOUND_UNAVAILABLE。Manifold 的独立 检查只证明 MeshSolid 拓扑/solid 后置条件，不证明 source surface 的几何偏差。完整规则与证据见 Representation Translation v0.1。

9. Field3D→MeshSolid 图绑定

Section titled “9. Field3D→MeshSolid 图绑定”

Field translation 合同已从 0.1.0 升至 0.2.0，统一使用 evaluation:sha256:*。source 和 target endpoint 都显式绑定 Revision、Evaluation、ExecutionManifest、ArtifactGraph hash、artifact ID 与 content hash。真实 球体 bake 生成相互独立的 Field3D source graph 和 MeshSolid target graph；target graph 因 face survival 仍为 unknown 而发布零个 Face，禁止凭三角缓冲编造源 Face identity。交换两个图会失败为 FIELD_TRANSLATION_GRAPH_REPRESENTATION，悬空局部 derivation 会失败为 ARTIFACT_GRAPH_DANGLING_LOCATOR。

机器证据见 Field ArtifactGraph v0.2。

10. 当前边界

Section titled “10. 当前边界”
  • GeometryEvaluationBundle 0.2.0 已强制携带 artifactGraphHash 和完整图；
  • box、cylinder、transform、union、difference 的现有 Manifold evaluator 会为实际执行到的 node 生成 artifact；
  • 当前产品 AMIR semanticRefs 仍为空，Aira Interface 尚未暴露产品级 resolve/resolveAcross；
  • OCCT ExactSolid ArtifactGraph/history adapter 已实现，但 production ExactSolid 尚未启用；
  • ExactSolid→MeshSolid conversion contract/adapter Gate 已实现，但尚未接入 production evaluator；
  • typed Field IR、representation-local Field ArtifactGraph 与 TrueSDF→MeshSolid graph-bound conversion Gate 已 实现；Field Region 尚未接入产品查询，meshed face survival 仍为 unknown；GeneralImplicit bake、 Edge/Wire/Vertex naming 和持久 cache 均未实现；
  • Chrome 插件存在；此前自动化传输链未完成的 browser smoke 与 Edge 兼容性均是非阻塞发布矩阵项，不得反向 阻塞已由真实 Chromium worker、源码复现和离线 runtime fixture 关闭的内核 Gate。

下一 Gate 是 GeneralImplicit root 语义与真正 bounded-error/isotopy mesher 的算法裁决，随后才把 Field Region resolution 接到现有 query path。通过前不选择 GPU authoritative 路径，也不扩张依赖持久命名的 fillet、constraint 或工业 feature catalog。