架构范式与接口约定¶

English · 简体中文

本文档是 oracq 开发范式的公开、可引用约定：分层结构、RIR 的稳定性契约、所有公共 API 必须遵守的三种变化边界，以及科学接口元数据的路线图。它只记录约定，本身不改变代码。文末给出与外部审稿意见的对应关系。

分层结构¶

源码树分三层，依赖方向只能向下。

infrastructure：寄存器级中间表示（RIR）、验证、序列化、linking、资源估计、读出与后端适配。这一层不知道算法是什么。
algorithms：算法库。common 存放共享数值内核与标准变换（QSP/QSVT、傅里叶算术、搜索、估计）；input_model 存放访问模型、块编码代数与数据加载构造；其余包（basics、qlss、qode、qpde、qnlss、qml、optimization、qec）存放各求解器族。
applications：物理模型与应用级组合（QHAM、QFVM、catalog 与 gallery），消费算法协议而不是具体实现。

新算法归入 algorithms 的对应类别文件，绝不进入旧导入兼容层（_compat.py）。每层只能依赖下层：求解器族可以消费 common 与 input_model，应用可以消费求解器协议，反向依赖禁止。

RIR 核心稳定¶

RIR 的稳定核心由寄存器、模块调用、具名资源和结构化操作 Repeat、Control、Adjoint 组成。它们在生成、序列化与恢复过程中保持不变：寄存器名、位宽与视图必须保留到后端 lowering；模块调用与 Repeat 结构在生成与文本序列化期间不得被无条件展开。

凡是表达计划而非线路身份的内容都放在 RIR 之上：PDE 表达式、QHAM 闭包、矩阵函数近似与精度选择都是上层计划对象。它们是生成器的输入，不是 IR 节点，不得加入 IR。

三种变化的边界¶

框架的每个公共 API 都必须显式说明它支持下列三种变化中的哪一种，并按对应规则处理。

算法或近似参数变化 → 触发重新生成。 截断阶数、误差目标、相位序列等选择被固化进生成的程序。由于位宽是具体的，参数扫描是 Python 生成阶段的任务：改参数，重新生成程序。
相同接口的 oracle 实现替换 → 通过 checked binding。 存储的开放程序不重新生成；替换实现在 linking 时按声明的接口与组装约定检查。绑定可以改变内部线路、私有工作区与捕获的资源；不得暗中修改调用方已经使用的块编码尺度、寄存器格式或近似参数。
后端变化 → 通过 lowering 处理。 后端导出与执行同生成分离；核心不依赖量子后端，原生依赖仅在执行入口导入。

qsp_phases 的可替换相位合成器是同一规则应用到数值内核上的实例：合成器是一个有声明契约的组件（输入目标多项式与约束，输出共享反射约定下时间正序的相位序列），内置实现随库提供，而每一条合成出的序列——无论内置还是替换——都必须在进入生成的程序之前通过 qsp_response 往返校验约定。

接口元数据：现状与路线图¶

接口元数据决定 checked binding 可以依赖什么。现状与规划如下：

现状：寄存器接口（名称、位宽、视图）、块编码尺度 α、调用能力（受控与伴随可用性、资源捕获）。
路线图（本阶段不实现）：误差度量及其范数口径、有效域、定点布局的溢出策略、物理布局信息、范数约定。

每项元数据还要携带证据级别，区分三种情形：调用方声明（语言不证明的承诺，例如谱界）、数值验证（生成或验证时在网格上或对照见证检查）、数学证明（由构造本身推出）。本阶段只记录路线图，不附带代码改动。

与审稿意见的对应关系¶

本文档回应审稿意见的框架层面建议：保留当前分层并加强层间约定（前两节）；把三种变化边界确立为公共 API 的统一规则（第三节）；按分阶段路线图扩充科学接口元数据（第四节）。审稿建议的统一证据记录与窄范围互操作适配器在 future-work 计划中单独跟踪，不属于本阶段。