Aira SemanticRef v0.1 契约

状态：Draft / Contract Implemented
版本：0.1.0
命名算法版本：aira.semantic-ref/0.1.0
Canonical Schema：semantic-ref.schema.json
语言中立 corpus：survival-corpus.json

1. 目的

SemanticRef 用模型语义重新寻找几何子实体，而不是保存一个“看起来稳定”的 kernel face/edge index。本契约固定 authoring witness、当前 context 解析、跨 Revision/表示 context 翻译、集合型结果、演化证据、cardinality 和确定性 hash，使任何 AI、GUI、operation 或 merge 流程都不能偷偷选择第一个候选继续执行。

本契约不声称已经解决全部 topological naming。它定义的是：

内核/表示 adapter 必须交付什么证据；
resolver 如何返回有限集合和显式失败；
哪些结果可以进入 authoritative validation；
resolver 版本变化如何被 ExecutionManifest 和 validation token 绑定。

2. 不变量

所有解析结果都是集合；即使 cardinality 声明 exactly one，也返回 candidates[]。
ArtifactSubEntityId 只在一个 artifact 内有效，wire 形态为内容身份 subentity:sha256:<digest>；禁止裸 pointer、数组下标或 face:7。
resolve 绑定同一个 source/target context；resolveAcross 必须绑定两个不同的完整 context。两个 context 可以属于同一 Revision，例如同一 authoring Revision 的 ExactSolid→MeshSolid 显式转换；但它们的 Revision/Evaluation/ArtifactGraph/ExecutionManifest/representation 组合不得完全相同。
每个 context 同时固定 RevisionId、EvaluationId、ArtifactGraph hash、ExecutionManifest hash、 representation 与 namingAlgorithmVersion。
candidates、声明/实际 cardinality、过滤阶段、evolution、diagnostics 和 publishable 都是结果必填字段。
missing、ambiguous、changed-kind、unknown 都不得发布；禁止“取第一个”。
heuristic 或 unknown evolution evidence 在 v0.1 均只能得到 unknown，不能进入 authoritative validation。
cache、kernel handle、当前内存地址和 resolver 实现对象不进入 AMIR/RevisionId。

3. 四类 canonical message

Canonical Schema 的根类型 SemanticRefContractMessage 是以下四种消息的闭合 union。

3.1 `SemanticRefAuthoringWitness`

引用创建时保存：

semanticRefId 与定义 hash；
authoring Revision/Evaluation/ArtifactGraph/ExecutionManifest；
声明 cardinality；
当时观察到的完整候选集合；
按 lineage origin 记录的预期 fan-out；
canonical witnessHash。

Witness 是解析证据，不是 kernel ID 永久化。请求必须携带它的 hash；resolver 会重算并拒绝被修改的 witness。

3.2 `SemanticRefResolutionRequest`

请求字段包括：

operation: resolve | resolveAcross；
SemanticRef definition/witness binding；
source/target context；
expected entity kind；
declared cardinality；
split/merge/delete/kind-change policy；
ordering policy。

resolveAcross 不是另造一套 AI 工具；它是 Aira Interface model.query 下的类型化 reference query。同一 Revision 跨表示仍必须使用它，因为表示、Evaluation、ArtifactGraph、ExecutionManifest 与转换证据已经改变。

3.3 `SemanticRefResolverEvidence`

adapter 把 kernel 特有 history、topology 和 predicate 归约成：

每个 candidate 的 scopeMatched、lineageMatched、topologyMatched、predicateMatched；
authoring fan-out 的当前观察；
至少一个 evolution event；
complete 和 canonical evidenceHash。

四个匹配值允许 null，但任何仍存活候选上的 null 都使结果为 unknown。这防止“未计算”被解释为 pass。

3.4 `SemanticRefResolutionResult`

结果固定：

SemanticRefResolutionResult {
  sourceContext, targetContext
  candidates[]
  declaredCardinality, actualCardinality
  stages[]
  evolution[]
  status, survival
  diagnostics[]
  publishable
  resolutionHash
}

resolutionHash 对除自身外的规范结果做 NFC + UTF-16 code-unit key ordering + SHA-256。所有数量必须为非负安全整数；字符串、key 和集合顺序经过确定性规范化。

4. Authoring 与 Resolution 分层

Authoring 回答“用户/AI 想持续引用什么”：scope、entity kind、role、lineage、predicates、cardinality、 evolution policy 和 ordering 属于 AMIR 语义。

Resolution 回答“在这个已绑定的执行上下文中找到了什么”：candidate、过滤证据、evolution、实际 cardinality 和 status 属于 Evaluation/ArtifactGraph 证据。Resolution 不得修改 SemanticRef 定义，也不得用当前结果覆盖 authoring witness。

5. 固定解析顺序

v0.1 的七个阶段顺序不可由 adapter 改写：

scope；
entity-kind；
lineage；
topology；
predicate；
cardinality；
ordering。

每个阶段记录 input/output count 和有限 exclusion reason。kernel 可提供原始 history，但不能直接宣布最终 cardinality 或 publishable。

6. Evolution 合同

“没有 event”不合法，因为它无法区分 no-effect 与 evidence 未计算。事件方向始终从 source/前代到 target/后代：

kind	source	target	含义
`creation`	0	≥1	新实体出现
`no-effect`	1	1，同 locator	已证明未受影响
`modified`	1	1	身份可翻译但几何/拓扑事实变化
`split`	1	≥2	一个前代产生多个后代
`merge`	≥2	1	多个前代合并
`delete`	≥1	0	前代消失
`kind-change`	≥1	≥1，kind 不同	实体种类改变
`converted`	≥1	≥1	跨 Exact/Mesh/Field 表示转换

每个事件携带 evidence hash 和 exact | deterministic | heuristic | unknown。v0.1 authoritative 路径只接受 exact 或 deterministic。

7. 状态与发布

状态判定优先级为：

evidence 不完整、过滤值未知或 heuristic/unknown evolution → unknown；
kind-change → changed-kind；
authoring fan-out 不一致 → ambiguous；
policy 拒绝 split/merge → ambiguous；
policy 拒绝 delete 且结果为空 → missing；
actual < min → missing；
actual > max → ambiguous；
其余 → resolved。

只有 resolved 的 publishable=true。cardinality.min=0 且 onDelete=allowMissing 可以解析为空集合；下游 port 是否接受空 EntitySet 仍由类型/前置条件检查。

not-applicable 保留给上游 applicability engine；reference resolver v0.1 不用它掩盖 unknown。

8. 排序

unordered 表示下游不得赋予位置语义，但 wire 仍按 artifact/subentity 内容身份排序以保证 hash 稳定。 byRoleThenCentroidLexicographic 先比较 role，再比较 adapter 提供的 canonical decimal orderingKey，最后以 locator 作为稳定 tie-breaker。实现禁止使用 locale-sensitive comparator。

9. ExecutionManifest 与 token 绑定

namingAlgorithmVersion 是 ExecutionManifest 必填字段。interactive preview 与 authoritative validation 可以使用不同 quality profile，因此两个完整 manifest hash 不要求相等；但最终 validation token 已绑定 authoritative executionManifestHash，从而绑定其中的 naming algorithm version。resolver 升级不会静默重新解释一枚旧 validation token。

namingAlgorithmVersion、adapter/kernel build 与 resolution evidence 不进入 RevisionId。若 AMIR SemanticRef 定义或 authoring witness 的规范语义发生改变，须明确更新当前契约及其 authoring binding，并在当前契约内通过显式 Patch 表达模型修改。旧契约不提供迁移或兼容读取，历史结果不得被重写。

10. v0.1 Survival Corpus

当前语言中立 corpus 固定 16 个场景：current no-effect、跨 Revision modified、split 允许/拒绝、fan-out 变化、merge 允许/拒绝、delete 拒绝/optional、kind-change、unknown evidence、cardinality missing/ambiguous、 Exact→Mesh conversion、creation 和确定性 ordered set。每个场景发布 expected status、candidate order、diagnostic codes 和 canonical resolution hash。

Corpus Gate 的最高级失败是 silent wrong rebind；它必须为 0。missing/ambiguous/unknown 是合法、可解释的结果，不得为提高“成功率”而自动降级。

11. 当前实现边界

semantic-ref.ts 是最小 reference resolver 与 contract oracle，用于冻结 wire、hash、状态优先级和 corpus；它不是生产级几何匹配算法。Core MVP 仍把 AMIR semanticRefs 固定为空 map，Aira Interface 尚未启用产品级 resolve/resolveAcross。

ArtifactGraph v0 与真实 MeshSolid box/boolean history 已接入 GeometryEvaluationBundle：同输入、参数修改、creation/delete、through-slot split/merge 均有实际 Manifold evolution evidence，真实 split 会向本 resolver 返回两个 candidates 并显式 ambiguous。OCCT ExactSolid adapter 也已通过同一失败合同。

Representation Translation v0.1 进一步用真实 OCCT 圆柱证明同一 Revision 的 ExactSolid→MeshSolid converted resolution：3 个 face 一对一映射时为 resolved / publishable=true；split 为 ambiguous / publishable=false，missing fail closed，silent wrong rebind 为 0。这关闭的是 adapter/contract Gate，不代表产品级 resolver 或 production ExactSolid 已启用。继续禁止在同一 survival contract 之外扩张依赖 SemanticRef 的 fillet、constraint 或工业 feature catalog。