docs: 固化 pyi C 模块绑定规格

2026-07-21 19:54:39 +02:00
parent 4c4ded5ee8
commit cd0004b929
3 changed files with 198 additions and 18 deletions
@@ -6,10 +6,11 @@
 | --- | --- | --- | --- |
 | v0.1 | `205e3a70` | 2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 |
 | v0.2 | `d72a1f52` | 2026-07-21 | 已批准：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 |
+| v0.3 | `待追溯` | 2026-07-21 | 已批准：统一 Python 3 `.pyi` C 模块声明方式、跨路线 binding 边界和资源报告口径。 |

 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。

-v0.2 及其引用的 PIKA-CAP v0.1 已批准生效，作为当前实现合同。
+v0.3 及其引用的 PJ2026-0501 v0.4、PIKA-CAP v0.3 已批准生效，作为当前实现合同。

 ## 正文

@@ -23,8 +24,8 @@ v0.2 及其引用的 PIKA-CAP v0.1 已批准生效，作为当前实现合同。
 | 短名 | PikaPython |
 | 层级 | L0 总项目 |
 | 规格状态 | 已生效 |
-| 当前生效版本 | v0.2 |
-| 实现引用版本 | v0.2 |
+| 当前生效版本 | v0.3 |
+| 实现引用版本 | v0.3 |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |

 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。
@@ -75,6 +76,7 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族：
 - Python 子集的解析、编译、字节码或其他执行表示。
 - VM、对象模型、调用约定、内存管理、异常和模块系统。
 - C 模块绑定、平台移植和微控制器资源裁剪。
+- Python 3 `.pyi` C 模块声明、主机侧归一化和目标侧 callback 运行边界。
 - capability 依赖、命名 profile 和跨实现能力等价比较。
 - Linux 功能、性能与资源基线，以及目标架构功能和资源验证。
 - V1、V2、MicroPython 和适用静态实现的版本化比较。
@@ -101,13 +103,14 @@ PikaPython 应形成一个可持续演进的嵌入式 Python 产品族：
 | profile | 有稳定名称和产品意图的 capability 根集合，不表示线性兼容等级。 |
 | 能力等价配置 | 所需 capability 闭包和被测语义一致，并只启用 workload 必需平台模块的配置。 |
 | 代表性 suite | 覆盖产品 profile 真实使用路径的版本化 benchmark 集合；不等同于单一内核上限测试。 |
+| `.pyi` 声明 | 使用 Python 3 stub 语法描述 C 模块 Python 可见接口的主机侧声明输入。 |

 ## 4. 系统边界和接口

 | 边界项 | 内容 |
 | --- | --- |
 | 外部使用者 | 嵌入式应用开发者、模块开发者、移植维护者和自动化构建系统。 |
-| 外部输入 | Python 源码或预编译产物、C 模块、构建裁剪配置、平台端口和资源预算。 |
+| 外部输入 | Python 源码或预编译产物、`.pyi` 声明、C 模块、构建裁剪配置、平台端口和资源预算。 |
 | 受控资源 | 解析器、编译器、执行内核、对象与堆、模块注册表、平台抽象和生成产物。 |
 | 外部输出 | 可执行固件或库、字节码、运行结果、异常、资源报告和 benchmark 报告。 |
 | 用户接口 | Python 子集、C API、模块绑定、构建配置和 workspace CLI。 |
@@ -212,6 +215,21 @@ V2 和静态加速必须保持以下隔离：
 - profile 名称不能替代能力清单，也不能暗示未声明的兼容性；
 - 能力差异、模块差异和资源预算差异必须在报告中分别披露。

+### 6.6 PIKA-L0-REQ-006 Python 3 `.pyi` C 模块接口
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| PIKA-L0-REQ-006 | C 模块接口 | [V2内核](PJ2026-0501-v2-kernel.md) | [PIKA-CAP](pikapython-capability-profiles.md)、[静态加速](PJ2026-0502-static-acceleration.md) |
+
+所有承诺 C 模块 binding 的路线必须遵循
+[PIKA-CAP `.pyi` C 模块声明合同](pikapython-capability-profiles.md)：
+
+- `.pyi` 采用 Python 3 stub 声明方式，不以具体 V1 文件或 V1 C ABI 为兼容目标；
+- 主机工具把声明归一化为模块、成员、签名和能力清单，目标 runtime 只执行生成的 descriptor 和 callback glue；
+- 用户必须能够从 Python 导入 C 模块并调用模块函数；
+  - 支持原生实例能力时，还必须能够构造 C 类并调用实例方法；
+- 绑定参数、返回值、生命周期和错误语义必须可测试、可裁剪并与路线内部对象布局解耦。
+
 ## 7. 全局验收合同

 - 路线验收：
@@ -226,12 +244,19 @@ V2 和静态加速必须保持以下隔离：
  - 每项结果必须绑定实现版本、提交、编译器、优化级别和可比较配置。
 - 资源验收：
  - Flash、静态 RAM、峰值动态 RAM、VM 栈、宿主栈和单次 workload 动态分配必须分别披露；
+  - Flash 和 RAM 必须同时披露绝对值、相对 profile 预算占比和相对比较对象的变化百分比；
  - 资源补偿可以发生在同一发布范围的其他模块，但总配置不得通过隐藏功能差异制造优势。
+- C binding 验收：
+  - `.pyi` 最小 Python 3 stub 子集必须有正向、归一化和范围外拒绝测试；
+  - 目标运行时必须分别通过模块函数、原生实例构造和实例方法的语义回归；
+  - 目标产物不得包含 `.pyi` parser、主机生成器或 V1 binding SDK；
+  - CPython 侧使用同名纯 Python 语义参考模块，目标和参考的退出状态及 stdout 原始字节必须一致；
+  - 模块函数和实例方法的 benchmark 及资源报告必须包含 Flash、RAM 绝对值、预算占比和变化百分比。

 ## 8. 过程控制

- V2 内核实现引用 `PJ2026-0501 V2内核 v0.2`。
- V2 的 capability 和 profile 实现引用 `PIKA-CAP v0.1`。
+- V2 内核实现引用 `PJ2026-0501 V2内核 v0.4`。
+- V2 的 capability 和 profile 实现引用 `PIKA-CAP v0.3`。
 - 静态加速实现引用 `PJ2026-0502 静态加速 v0.1`。
 - 稳定需求变化先修改 SPEC，再进入代码或执行 issue。
 - 当前状态、阶段 benchmark、PR 和阻塞统一进入 TaskTree、阶段报告或 GitHub issue。
@@ -7,10 +7,11 @@
 | v0.1 | `205e3a70` | 2026-07-21 | 定义 V2 动态子集重写内核的架构原则、能力边界和量化验收合同。 |
 | v0.2 | `d72a1f52` | 2026-07-21 | 已批准：明确阶段性 V1 parser 适配器、原子 capability、职责化实现命名、候选内核比较和 cold/warm benchmark 生命周期。 |
 | v0.3 | `5c133ed2` | 2026-07-21 | 已批准：增加语法能力组 TDD、CPython 逐字节脚本回归、严格 ISO C99 硬门禁和扁平 C 源目录合同。 |
+| v0.4 | `待追溯` | 2026-07-21 | 已批准：固定 Python 3 `.pyi` C 模块声明、C callback 边界、原生实例生命周期和 binding 回归合同。 |

 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。

-v0.3 及其引用的 PIKA-CAP v0.2 已批准生效，作为当前实现合同。
+v0.4 及其引用的 PIKA-CAP v0.3 已批准生效，作为当前实现合同。

 ## 正文

@@ -24,8 +25,8 @@ v0.3 及其引用的 PIKA-CAP v0.2 已批准生效，作为当前实现合同。
 | 短名 | V2内核 |
 | 层级 | L1 方向 |
 | 规格状态 | 已生效 |
-| 当前生效版本 | v0.3 |
-| 实现引用版本 | v0.3 |
+| 当前生效版本 | v0.4 |
+| 实现引用版本 | v0.4 |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) |

@@ -66,6 +67,7 @@ V2 的目标是：
 - VM dispatch、调用帧、对象表示、名称访问、容器、异常和内存管理。
 - 编译期和构建期的语法、opcode、对象、模块与平台裁剪。
 - C 模块绑定、平台抽象和可预测错误合同。
+- Python 3 `.pyi` C 模块声明、主机侧归一化和目标侧 C callback 边界。
 - 实现文件和代码标识符的职责化命名合同。
 - 项目自有 C 源码的严格 ISO C99 编译合同。
 - 项目自有 C 源码和头文件在单一 `src/` 目录中的扁平集成合同。
@@ -78,6 +80,7 @@ V2 的目标是：
 - LLVM IR、LLVM 后端、JIT 和目标相关 native emitter 作为 V2 内核依赖。
 - 完整 CPython 或 MicroPython 语法兼容。
 - V1 字节码、对象布局、调用栈、ABI 或 runtime 源码目录结构的内部兼容。
+- V1 C binding SDK、生成器、`PikaObj*` ABI、具体 `.pyi` 文件和 C 符号命名的内部兼容。
 - 将 V1 parser、V1 runtime 或 MicroPython fork 设为 V2 目标运行时的长期依赖。
 - 由本规格预先固定宽度寄存器 VM、紧凑栈 VM 或字节码编码形态。
 - 为提升 parser 性能牺牲 runtime 性能或内核资源；parser 可在 PC 端一次性运行。
@@ -100,16 +103,20 @@ V2 的目标是：
 | 职责化命名 | 文件名和代码标识符表达内核职责、数据语义或生命周期，不携带路线代际缩写。 |
 | 语法能力组 | 一次 TDD 迭代选择的 capability 根集合、依赖闭包、正负测试和资源比较单元。 |
 | 逐字节脚本回归 | 对相同受支持源码比较目标运行时与 CPython 的退出状态和 stdout 原始字节，不做空白或换行归一化。 |
+| `.pyi` 声明 | 使用 Python 3 stub 语法描述 C 模块 Python 可见名称、签名和原生类的主机侧输入；不表示目标设备上的源文件。 |
+| binding descriptor | 从 `.pyi` 归一化得到的模块、成员、签名、类型转换和 callback 元数据。 |
+| C callback | 由 C 模块实现提供、在目标 runtime 调用边界内执行并通过 tagged value 传递参数和结果的函数。 |
+| 原生实例 | 由 C 模块创建、由 runtime 持有不透明载荷并可绑定 C 方法的 Python 可见对象。 |

 ## 4. 系统边界和接口

 | 边界项 | 内容 |
 | --- | --- |
 | 外部使用者 | 嵌入式应用开发者、V1 迁移者、模块开发者和平台移植者。 |
-| 外部输入 | 受支持 Python 源码或 V2 字节码、C 模块、裁剪配置和平台端口。 |
-| 受控资源 | 编译器、字节码、VM 状态、调用帧、对象、堆、模块表和错误状态。 |
+| 外部输入 | 受支持 Python 源码或 V2 字节码、`.pyi` 声明、C callback 模块、裁剪配置和平台端口。 |
+| 受控资源 | 编译器、字节码、VM 状态、调用帧、对象、堆、binding descriptor、模块表和错误状态。 |
 | 外部输出 | 执行结果、异常、停机诊断、静态库或固件、字节码和资源指标。 |
-| 用户接口 | V2 Python 子集、字节码格式、C API、模块绑定和 workspace CLI。 |
+| 用户接口 | V2 Python 子集、字节码格式、Python 3 `.pyi` 声明、C API、模块绑定和 workspace CLI。 |
 | 系统边界 | V2 定义动态子集内核，不定义静态加速路线、板级驱动或应用业务逻辑。 |

 ## 5. 目标架构
@@ -249,6 +256,53 @@ sequenceDiagram
  V-->>A: 结果、异常或致命停机诊断
 ```

+### 5.7 C 模块声明与调用数据流
+
+`.pyi` 绑定必须采用主机生成、目标执行的两段式数据流：
+
+```mermaid
+flowchart LR
+  PYI[Python 3 .pyi 声明] --> N[主机解析与归一化]
+  N --> D[版本化 binding descriptor]
+  D --> G[描述符校验与 C99 glue 生成]
+  G --> R[目标模块注册表]
+  C[C callback 实现] --> R
+  APP[Python import 与调用] --> R
+  R --> OUT[返回值或明确错误]
+```
+
+该数据流必须满足以下稳定边界：
+
+- `.pyi` 只在主机侧参与解析、归一化、校验和 glue 生成；
+- 目标产物只包含已选 capability 所需的 descriptor、注册表和 callback glue；
+- descriptor 必须独立于 V1 对象布局、调用栈、生成头文件和符号命名；
+- descriptor 必须携带可校验的 schema 版本和记录尺寸，未知版本或非法尺寸必须在注册前拒绝；
+- C 模块只能通过公开 C99 binding API 使用不透明上下文和值，不得直接读取 VM、调用帧或对象内部结构；
+- 模块可以通过静态注册或显式初始化加入 registry，但 Python 可见的查找、重复注册和调用错误语义必须一致；
+- 模块名、类名和成员名在 registry 生命周期内保持稳定，并拒绝重复定义；
+- tagged value 的语义标签至少包括：
+  - `none`、`bool`、`int`、`float`、`str`、`bytes` 和 `opaque`；
+  - 具体 C 结构布局不属于本合同；
+- callback 边界必须满足：
+  - 位置参数的数量和类型转换在进入 callback 前完成；
+  - callback 失败通过稳定错误结果返回，不得以未定义跳转或隐式全局状态传递异常；
+  - 语义接口包含调用上下文、只读参数序列、结果输出和错误输出；
+  - 不得通过 C `longjmp` 或未定义异常跨越边界；
+- callback 接收的 `str`、`bytes` 和其他输入视为调用期间借用值，除非 descriptor 明确声明更长生命周期；
+- callback 产生的字符串或字节结果必须在 runtime 接管前完成复制，或使用 descriptor 明确声明的静态只读存储；
+- 原生实例的载荷是不透明的：
+  - 构造失败不得产生可见实例；
+  - 已成功构造的实例在销毁时最多执行一次清理 callback；
+- 目标 runtime 不得因为支持 `.pyi` 绑定而链接 `.pyi` parser、主机工具或 V1 binding SDK。
+
+Python 可见调用路径必须覆盖：
+
+- `import module` 后调用模块级 C 函数；
+- `module.Type(...)` 创建 C-backed 原生实例；
+- `instance.method(...)` 调用 C 实例方法；
+- 标量参数和返回值在 Python 值与 tagged value 之间进行确定转换；
+- 缺模块、缺成员、参数数量、参数类型、callback 和资源错误分别产生可测试诊断。
+
 ## 6. 原子需求

 ### 6.1 V2-L1-REQ-001 重写优先架构
@@ -526,6 +580,27 @@ V2 作为路线和规格称谓，不得进入实现仓库的文件名或项目
 - 明确隔离的第三方 vendored 文件；
 - 构建目录内生成且不进入版本控制的 C 中间产物。

+### 6.14 V2-L1-REQ-014 Python 3 `.pyi` C 模块绑定
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| V2-L1-REQ-014 | C 模块绑定 | PJ2026-050104 裁剪移植 | PJ2026-050101 语言编译、PJ2026-050102 VM执行、PJ2026-050103 对象内存、PJ2026-050105 验证基准 |
+
+V2 必须提供面向用户的 C 模块接口，并遵循
+[PIKA-CAP `.pyi` C 模块声明合同](pikapython-capability-profiles.md)。
+该接口必须满足以下稳定要求：
+
+- `.pyi` 是主机侧 Python 3 stub 声明输入，不是目标 runtime 的解释脚本；
+- 声明必须归一化为版本化 binding descriptor，再生成目标侧注册表和 C99 callback glue；
+- Python 用户必须能够导入 C 模块、调用模块函数、构造 C-backed 原生实例并调用实例方法；
+- 目标侧 C API 必须使用不透明模块、类和实例描述，以及带类型标签的参数和返回值边界；
+- 公开 binding header 必须能被模块以严格 ISO C99 独立包含，不得要求 C++、GNU 扩展或内部 runtime header；
+- callback 生命周期、字符串和字节的借用/复制规则、原生实例清理规则必须是确定的；
+- 缺模块、缺成员、重复注册、参数数量错误、参数类型错误、callback 失败和资源耗尽必须分别可观察和可测试；
+- V1 的 `PikaObj*`、内部 SDK、生成头文件、符号命名和对象 ABI 不属于 V2 兼容合同；
+- `.pyi` 的兼容目标是声明方式和 Python 可见调用语义，不是某个具体 `XXX.pyi` 文件或 V1 生成结果；
+- 未启用 `binding.c` 或 `binding.c-object` 时，相关声明必须在主机生成阶段被拒绝，不能依赖目标运行时临时失败。
+
 ## 7. 验收合同

 ### 7.1 语义验收
@@ -600,6 +675,10 @@ V2 作为路线和规格称谓，不得进入实现仓库的文件名或项目
  - Flash 不高于 V1 同能力配置；
  - 峰值 RAM 不高于 V1 同能力配置；
  - 相对 MicroPython 的性能、Flash 和峰值 RAM 按 7.2 的预算约束做 Pareto 分析。
+- 每份资源对比表必须同时披露 Flash 和 RAM 的：
+  - 绝对值；
+  - 相对于对应 profile 预算的占比；
+  - 相对于比较对象的变化百分比或节省百分比。
 - 高频整数算术、局部控制流和已优化函数调用路径应保持零堆分配：
  - 该结论必须由分配器计数或等价 trace 证明；
  - 不得使用手工源码计数代替。
@@ -646,12 +725,29 @@ V2 作为路线和规格称谓，不得进入实现仓库的文件名或项目
 - 构建和打包清单必须从 `src/` 显式选择源码与公开头文件；
 - 使用者只增加 `src/` 头文件搜索路径即可构建受支持的内核配置。

+### 7.9 C 模块绑定验收
+
+- `.pyi` 主机工具必须对最小 Python 3 stub 子集执行 lexer、parser、归一化和签名校验；
+- 范围外语法、V1 专用宏和 V1 私有类型必须产生稳定诊断，不得生成部分绑定；
+- binding descriptor 必须能确定性表达模块函数、C 类、构造函数、实例方法、参数类型和返回类型；
+- C 模块 fixture 必须只包含公开 binding header，并在 `-std=c99 -pedantic-errors` 条件下独立编译；
+- registry 必须覆盖注册、查找、重复定义、缺模块和缺成员路径；
+- VM 必须分别覆盖模块函数、C 类构造和实例方法的参数绑定、callback 返回和错误传播；
+- 回归 fixture 必须使用目标 C 模块和 CPython 侧同名纯 Python 语义参考模块，比较退出状态和 stdout 原始字节；
+- 目标固件或静态库不得包含 `.pyi` parser、主机生成器或 V1 binding SDK；
+- 冷启动必须单独报告注册和首次调用成本，warm benchmark 只计入已完成注册和加载后的调用；
+- 模块函数和实例方法的调用开销必须分别测量，并同时披露：
+  - Flash、RAM；
+  - profile 预算占比；
+  - 相对比较对象的变化百分比。
+- callback 失败、输入借用值失效、结果复制失败和实例清理必须各有负向或生命周期测试。
+
 ## 8. 过程控制

- V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.3` 和文件职责。
+- V2 新增或修改的手写内核源码应标注 `SPEC: PJ2026-0501 V2内核 v0.4` 和文件职责。
 - 自动生成、vendored、配置和二进制产物可不加源码头，但生成器或配置入口必须能追溯本规格。
 - 架构选择必须记录候选方案、适用前提、benchmark 热点和资源影响；当前结果进入 TaskTree 或 issue，不进入 SPEC。
 - 任何实现若让 V1 内部结构越过中性类型化 V2 IR 边界，必须先更新本规格或作为偏离停止合并。
- capability 和 profile 实现引用 `PIKA-CAP v0.2`。
+- capability 和 profile 实现引用 `PIKA-CAP v0.3`。
 - 语法能力组的红测例、通过证据和 benchmark 数值进入 TaskTree 或 issue，不进入 SPEC。
 - 若后续决定引入 strict type、LLVM、JIT 或 native emitter，应归入独立静态加速规格，不得直接修改 V2 默认路线。
@@ -6,6 +6,7 @@
 | --- | --- | --- | --- |
 | v0.1 | `d72a1f52` | 2026-07-21 | 已批准：建立原子 capability、显式依赖图和命名 profile 合同。 |
 | v0.2 | `7d4a0b0a` | 2026-07-21 | 已批准：增加最小 stdout `print` 能力及其逐字节回归合同。 |
+| v0.3 | `待追溯` | 2026-07-21 | 已批准：固定 Python 3 `.pyi` C 模块声明合同，并拆分模块函数与 C 实例绑定能力。 |

 修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。

@@ -21,8 +22,8 @@
 | 短名 | 能力配置档 |
 | 层级 | L0 共享规范 |
 | 规格状态 | 已生效 |
-| 当前生效版本 | v0.2 |
-| 实现引用版本 | v0.2 |
+| 当前生效版本 | v0.3 |
+| 实现引用版本 | v0.3 |
 | 上级规格 | [PJ2026-05 PikaPython 总规格](PJ2026-05-pikapython.md) |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |

@@ -99,7 +100,8 @@ capability 描述对外语义和可裁剪单元，不规定 parser、IR、字节
 | `container.list` | list、索引、迭代和基础变更。 | `exec.module` |
 | `container.dict` | dict、键查找、迭代和基础变更。 | `exec.module` |
 | `module.import` | 模块命名空间和 `import`。 | `name.global` |
-| `binding.c` | Python 到 C 模块的基础调用。 | `module.import`、`call.positional` |
+| `binding.c` | C 模块注册、模块级函数调用及位置参数和返回值转换。 | `module.import`、`call.positional` |
+| `binding.c-object` | C 类构造、原生实例生命周期和实例方法调用。 | `binding.c`、`object.attribute` |
 | `object.attribute` | 属性读取、写入和绑定方法。 | `name.global`、`call.positional` |
 | `object.class` | `class`、实例构造、实例字段和基础继承。 | `object.attribute` |
 | `exception.basic` | `raise`、`try` 和 `except`。 | `exec.module` |
@@ -113,6 +115,56 @@ capability 描述对外语义和可裁剪单元，不规定 parser、IR、字节

 新增 capability 必须使用新的语义 ID。既有 ID 不得被复用为不兼容语义；删除能力时保留 ID 并标记废弃。

+### 4.1 `.pyi` C 模块声明合同
+
+`.pyi` 是 C 模块 Python 可见接口的主机侧声明输入。
+该合同兼容 PikaPython V1 的声明式绑定方式，但不承诺具体文件、生成产物或 C ABI 兼容：
+
+- 模块作者使用 Python 3 stub 语法声明模块函数、类、构造函数和实例方法；
+- 同一声明经主机工具归一化为与具体内核无关的模块、类、成员和类型签名；
+- 各运行路线可以重写生成器、注册表、callback SDK、对象布局和符号命名；
+- 目标 runtime 不解析 `.pyi`，也不链接 `.pyi` parser、诊断文本或主机生成器；
+- 兼容性按 Python 可见名称、调用形态和已支持类型语义判断，不按 V1 的某个 `XXX.pyi` 文件逐项判断。
+
+最小声明子集必须是合法 UTF-8 Python 3 stub，并支持：
+
+- 顶层模块函数 `def`；
+- 无继承基类的 `class`；
+- `__init__` 和实例方法；
+- 位置参数，其中实例方法的首个参数为 `self`；
+- `...` 函数体；
+- `int`、`bool`、`float`、`str`、`bytes`、`None` 和 `typing.Any` 类型注解；
+- `from typing import Any` 与 `import typing` 两种标准导入形式。
+
+除 `self` 外，函数和方法的参数及返回值必须有受支持的类型注解。
+`__init__` 的返回注解必须是 `None`。
+`Any` 表示 callback 接收或返回带类型标签的动态值，不表示跳过 runtime 类型合法性检查。
+
+以下内容不属于该最小合同：
+
+- V1 专用的 `PikaObj`、小写 `any` 和 `from PikaObj import *`；
+- `PIKA_C_MACRO_IF`、`PIKA_C_MACRO_IFDEF` 或其他非 Python 3 stub 装饰器；
+- V1 生成头文件布局、C 函数命名、对象结构和注册 ABI；
+- 默认参数、关键字参数、可变参数、泛型、重载、联合类型和类继承；
+- 在目标设备运行时读取或解释 `.pyi` 文件。
+
+不在最小子集内的声明必须返回确定的声明诊断，不得静默忽略、降级类型或生成部分绑定。
+后续扩展必须继续采用 Python 3 stub 语法，并通过规格修订增加对应 capability 和验收合同。
+
+### 4.2 C binding 能力映射
+
+`.pyi` 声明工具是主机构建接口，不是目标 runtime capability，也不得写入字节码的所需能力清单。
+声明产生的 Python 可见行为按以下规则映射能力：
+
+- 仅声明模块级 C 函数时，根能力包含 `binding.c`；
+- 声明 C 类、构造函数或实例方法时，根能力包含 `binding.c-object`；
+- 每个参数和返回值的标量注解增加对应的 `value.*` capability；
+- `Any` 不隐式启用全部值类型，允许通过它传递的值类型必须由产品配置显式列出；
+- C 类声明只承诺原生实例语义，不隐式启用 Python `class` 语句、继承或实例字段，因此不自动依赖 `object.class`。
+
+主机工具必须从归一化声明确定性地产生所需能力集合。
+声明使用的能力不属于选定闭包时，必须在生成目标产物前拒绝。
+
 ## 5. 依赖与 profile 合同

 ### 5.1 依赖解析
@@ -162,7 +214,7 @@ profile 根集合如下：
  - `container.dict`；
  - `iter.range`；
  - `module.import`；
-  - `binding.c`；
+  - `binding.c-object`；
  - `exception.basic`。
 - `dynamic-full`：
  - `embedded-app` 的全部根 capability；
@@ -236,6 +288,13 @@ profile 合同如下：
 - `builtin.print` 的正向测试：
  - 必须把目标 stdout 与 CPython 对相同受支持值的输出逐字节比较；
  - 输出通道失败必须返回明确错误。
+- `.pyi` C binding 验收：
+  - 最小 Python 3 stub 子集中的每类声明必须有接受和归一化测试；
+  - 每类范围外声明必须有确定拒绝测试；
+  - `binding.c` 和 `binding.c-object` 必须分别具有启用、禁用和依赖缺失测试；
+  - 生成的目标产物不得包含 `.pyi` parser 或主机生成器；
+  - 模块函数与实例方法必须分别覆盖正常返回、参数数量错误、类型错误和 callback 错误；
+  - C binding 资源报告必须同时披露 Flash、RAM 的绝对值、profile 预算占比和相对比较对象的变化百分比。

 ## 8. 过程控制