# 架构范式与接口约定

<a href="../../development/architecture-paradigm.html">English</a> · **简体中文**

本文档是 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 都必须显式说明它支持下列三种变化中的哪一种，并按对应规则处理。

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

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

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

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

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

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

## 与审稿意见的对应关系

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