RFC-0004：AMIR Query Compiler

状态：Proposed 文档版本：0.1.0 日期：2026-08-31 上位路线：Aira 长期架构计划 §3.3 机器证据：AMIR Query Contract v0.1

1. 决议

AMIR Query Compiler 是确定性的语义查询编译边界，不是自然语言、供应商 JSON 或矩阵“转义层”。它把 版本化 Query Request 编译为绑定具体 Revision/Evaluation 的执行计划，并由运行时产生内容寻址的 Execution Receipt。编译器不直接执行几何、不拥有 scheduler、不保存 raw kernel handle，也不改变 AMIR Revision 身份。

v0.1 固定三个 wire object：

1. AmirQueryRequest：声明查询 DAG、typed selector、assurance/unknown policy 与资源上限；
2. AmirQueryPlan：锁定 descriptor catalog、执行 binding、稳定 recipe key、拓扑序与输入内容哈希；
3. AmirQueryExecutionReceipt：记录 root result、assurance、Diagnostic set 与 constructive trace。

当前 Aira Interface 仍保持九个顶层元操作。语义查询继续投影在 model.read 下；本 RFC 不新增第十个 operation，也不扩大 capability catalog。

2. 身份分层

身份	回答的问题	包含	排除
requestHash	要计算什么语义请求	query DAG、selector、requirements、limits	request alias、Revision/Evaluation
queryKey	此节点的稳定计算 recipe 是什么	descriptor、stable args、前置 query key	Revision、artifact handle、执行结果
bindingHash	这次计划绑定哪些权威输入	source/target Revision、model、authoring lock、Evaluation/Assurance	query recipe
planId	哪个编译计划应被执行	request、catalog、binding、拓扑节点、limits	runtime result
result contentHash	实际得到什么结果	result contract 下的 canonical bytes	cache slot、内核对象地址
receiptId	哪次执行证据被封存	plan/binding、roots、Diagnostic set、trace	未执行断言

因此同一语义请求换到新 Revision 时，queryKey 保持稳定，bindingHash 与 planId 必须改变。运行时可用 稳定 key 做增量匹配，但只有输入内容绑定和依赖结果均满足时才能命中 cache；不能用稳定 key 本身冒充结果 有效性。

3. v0.1 Query Catalog

Catalog 固定七个版本化 query family：

• model.parameters；
• artifact.metrics、artifact.topology、artifact.lineage；
• semantic-ref.resolve、semantic-ref.resolve-across；
• impact.downstream。

每个 descriptor 锁定 kind、queryVersion、binding requirement 和 result contract hash；整个 catalog 再生成 snapshot hash。artifact 与 SemanticRef 查询必须绑定 source Evaluation；跨 Revision resolve 必须 同时绑定两个完整且不同的 context。目标 binding 在没有跨 context 查询时属于非法冗余输入。

Selector 是闭合 tagged schema。OCCT shape、Manifold object、WASM pointer、Three.js object、GPU buffer 或 其他 raw handle 无法通过 wire schema，也不得出现在 key、lineage 或 receipt 中。

4. 确定性编译

编译器执行以下规范步骤：

1. 严格 schema 校验并拒绝附加字段；
2. 规范化 query、dependency 与 selector 集合顺序；
3. 拒绝重复 ID、缺失依赖、cycle、无 root 和节点预算溢出；
4. 按稳定 code-unit 顺序作确定性拓扑排序；
5. 从 descriptor、selector/requirements 与 prerequisite query keys 生成 queryKey；
6. 从 Revision/Evaluation/Assurance 内容生成 constructive inputBindings；
7. 对完整 canonical plan 生成 planId。

编译产物可从内嵌 request 独立重建；任何字段、hash、节点顺序或 binding 被修改都 fail closed。v0.1 reference compiler 位于 @aira/contracts，是 contract oracle；它不是 production scheduler 的永久归属。

5. 执行收据与取消

Execution Receipt 必须绑定 planId 与 bindingHash。已完成 root 才能携带 contentHash/byteSize，且必须 满足请求的 minimum assurance；unknown/notApplicable/failed 不得携带裸值。onUnknown = fail 时不能 把未知伪装成普通 unknown 结果。

trace event 按 plan 拓扑顺序记录 query key、依赖结果 hash、结果 hash、cache/computed/early-cutoff outcome 与 artifact bytes。正常 settled execution 必须覆盖所有 plan nodes，并以单次 atomic 发布 cache； cancelled/failed 必须 cachePublication = none，不能留下部分可见 cache 状态。root bytes 与 trace bytes 均受请求上限约束。

Receipt 证明“运行时声称执行了什么”，不自动证明几何正确；其 root assurance 仍受 RFC-0003 的 checker registry 与 precondition DAG 约束。

6. 与 P0B-S4 Spike 的关系

P0B-S4 已证明最小 TypeScript scheduler 在真实 Manifold DAG 上可实现 dirty propagation、semantic early cutoff、AbortSignal、事务隔离和 byte-budget LRU。本 RFC 只吸收已验证的协议语义，不把 spike class 复制进 产品，也不裁决 Salsa、comemo 或自研 scheduler。

下一阶段 scheduler 必须消费本 RFC 的 plan/receipt 边界，并另外证明：

• cache 命中同时核对 recipe、input binding 与 dependency result；
• cancellation/exception 对共享 cache 零污染；
• browser WASM 与 native/server 对同一 fixture 产生相同规范 plan/receipt；
• cache eviction 由 bytes 与 rebuild cost 决定。

7. 版本与接受条件

Query contract、compiler、descriptor catalog、result contract 与 scheduler 分别版本化。v0.1 不进入 modelHash、RevisionId 或 authoringLockHash；只有未来会改变 AMIR 解释的 query semantics 才通过正式 版本治理进入 authoring lock。

本 RFC 进入 Accepted 前至少还需：

1. version namespace 治理固定 $id、contract/compiler/catalog 的登记点、当前内容绑定及不支持绑定的拒绝规则；
2. production scheduler 消费 plan，并对 dirty/early-cutoff/cancel/cache budget 完成双环境 Gate；
3. 七个 result contract 的 canonical result schema 全部发布；
4. SemanticRef 与 Certificate assurance 的 production query 通过跨 Revision replay corpus；
5. provider/browser/server 投影保持九元控制面并通过 exact-byte conformance。

当前 v0.1 contract Gate 已 Verified，但 scheduler/product query 未启用，RFC 整体仍为 Proposed。