接入力标定 schema 3 与多点空间增益模型

保留旧格式和 cal_path，校验 SN、特征身份及坐标附件，按帧返回逐轴状态。相关测试 263 项通过，已核对存量预测并实测 180 帧录像。

docs/calibration-model-contract.zh.md

@@ -1,6 +1,7 @@
-# 统一力标定模型契约（草案）
+# 统一力标定模型契约
 
-Purpose: plan. Scope: SDK 标定文件选择、SN 绑定和推断接口。状态：2026-10-18 提案，未实现。
+Purpose: reference. Scope: SDK 标定文件选择、SN 绑定和推断接口。
+状态：2026-10-18 已实现 schema 3 的空间/全局增益；ML 后端仅保留契约，尚未实现。
 保持 `cal_path` 与现有单点文件；新增空间模型和机器学习模型使用同一入口。
 
 ## 现状与边界
@@ -38,12 +39,14 @@ profile 创建处理器统一复用内部选择器；现有入口参数只映射
 保留 `device_id` 单独传入时的参数错误；目录本身不存在也报错，不能当成 SN 文件缺失。
 
 ```python
-# 沿用现有调用参数；schema 3 需未来实现支持后使用。
+# 沿用现有调用参数；cal_path 可以选择 schema 1/2/3 文件。
 runtime = FingerRuntime.open(
     config="finger", video="test.mp4",
     device_id="DD02-GL-001",
     cal_path="calibrations/finger/DD02-GL-001.json",
 )
+# 归零值来自本次无载窗口，不是模型内固定常量。
+runtime.set_calibration_reference({"fn": measured_zero_raw}, reference_id="unloaded-1")
 # 自动按 SN 选择仍使用 calibration_dir="calibrations"，不同时传 cal_path。
 ```
 
@@ -107,12 +110,14 @@ runtime = FingerRuntime.open(
 修改输入或算法语义必须升级相应 `/1` 标识。
 
 `geometry_sha256` 是所用计算 mesh 文件字节的 SHA-256；`map_sha256` 是 SDK 坐标映射定义的
-内容摘要，包含坐标变换及其版本，不能只比较图幅。pipeline 的必需键由输入 profile 固定，
+附件字节摘要，包含坐标转换结果，不能只比较图幅。pipeline 的必需键由输入 profile 固定，
 覆盖该 backend 所有影响测量的设置；只检查示例中的部分配置不算兼容校验。
+
 新增 profile 必须定义闭合的签名字段表。首个 profile 的 `feature_signature_sha256` 摘要
 对象包含 `feature_version`、`processing_backend`、有效的图像预处理/光流/HHD 配置和计算资产哈希；
 不含文件绝对路径、SN、显示资源或力读数滤波。以 UTF-8、键排序、无多余空格的 JSON 计算 SHA-256。
 特征定义或单位改变须升级 `feature_version`，配置覆盖后重新计算，不能用配置文件名代替。
+实现由 `calibration_context.build_context` 统一生成，特征版本为 `orisys_hhd_raw/1`。
 
 ## 空间增益模型
 
@@ -132,6 +137,11 @@ runtime = FingerRuntime.open(
   未覆盖、位置失败、归零无效均返回无效，不能偷偷改用 M0。
 - `valid_force_range_N` 必填。估计超范围时保留数值并标记 `out_of_range`，不截断。
 
+FingerRuntime 使用 `artifacts` 中 `role="coordinate_map"` 的只读 NPZ：
+`uv_by_output_px` 为 H×W×2 有符号 UV，`valid_mask` 为 H×W bool；可附 `origin_xy` 与
+`flat_mapping_sha256`。`pipeline.output_domain_sha256` 绑定实际展开的 remap、mask 和 world_xyz；
+形状、几何或特征身份不同则在打开视频前拒绝。离线直接提供 UV 的模型可以没有映射附件。
+
 单点/两点数据不自动切换算法；可导出独立的 `global_gain/1`，参数为各输出轴的增益和有效范围，
 输入 profile 为 `force_delta/1`，由 SDK 按同一归零语义准备对应 raw 增量。
 这不同于旧曲线的绝对 raw 输入；兼容适配器不得替旧文件额外扣零。
@@ -179,7 +189,7 @@ runtime = FingerRuntime.open(
 
 ## 每帧推断与有效性
 
-内部统一生命周期如下；是拟议接口，不是现有 API。
+内部统一生命周期如下，`calibration.load` 分流到旧曲线或新模型：
 
 ```text
 load(selected_file, device_identity, pipeline) -> CalibrationModel
@@ -192,7 +202,8 @@ CalibrationResult:
                 coordinate_unmapped | outside_coverage | out_of_range}
 ```
 
-FN 空间模型输入仅允许单一接触；无法确认单接触时不能宣称已标定总力。
+FN 空间模型输入仅允许单一接触；当前定位器只返回一个中心，无法证明不存在多接触，
+不能宣称已标定总力。全局 `force_delta/1` 不要求定位，未提供接触状态不等同于无接触。
 无接触、失败帧的校准输出为空，raw 另行保留；缺失值不是 0 N。
 `out_of_range` 有数值但不在验证范围，其余失败状态无数值；未声明轴不可用、单位仍为 raw。
 不把某轴 raw 填进 `values_N`，也不只靠全局 `force_unit` 判断三轴单位。
@@ -206,6 +217,10 @@ schema 1/2 仍保留旧滤波/转换顺序。状态模型不能塞入会调用
 
 加载诊断至少包含路径、来源、SN 校验状态、模型/输入 profile、轴集合、内容指纹和失败原因。
 加载不匹配失败与逐帧暂时无效分开；替换时先完成加载校验，失败不得破坏原活动模型。
+Sensor 提供 `bind_calibration_context`、`set_calibration_reference`、`apply_calibration_frame`；
+FingerRuntime 自动绑定真实上下文，并转发归零。`FrameSnapshot.force_units` 和
+`calibration_status` 随帧保存，不能用稍后读取的 Sensor 状态解释旧帧。
+归零与换模型须在计算线程或暂停处理时调用，不承诺并发修改安全。
 
 ## 兼容、实现位置与验收
 
@@ -219,9 +234,14 @@ schema 3 按声明轴校验，允许 FN-only；旧 SDK 遇 schema 3 必须拒绝
 | `sensors/calibration.py` | 统一选择器与指纹；支持 SN 请求 |
 | 新 `calibration_models.py` | 受控类型表、空间增益与模型生命周期；ML 后端另行实现 |
 | `sensor.py`、`finger/runtime.py`、处理器适配层 | 提供同帧位置/零点，缓存逐轴结果和状态 |
-| `force_readout.py` | 保留旧路径，为 schema 3 分离推断与读数滤波 |
+| Sensor 与 `ForceReadout` | 复用读数滤波器；schema 3 在推断后逐轴滤波，旧路径不变 |
 | 离线导出器 | 实验模型到 schema 3；SDK 不依赖实验目录 |
 
+当前导出入口为 workspace 的 `scripts/finger_multical/export_sdk.py`，输出已有文件时拒绝覆盖。
+`data/dd02-gl/force_calibration.v3.json` 与同名 `.coordinates.npz` 是本次实验交付，
+`identity.sn="dd02-gl"` 为实验标识，未从硬件读取；原三边缘点与非单调点警告保留于 provenance。
+它不是生产包默认文件，需显式 `cal_path` 选择。
+
 实现验收必须覆盖：旧结果与单位不变；显式路径/SN/默认/关闭选择；错误 SN 不串用；
 3/14/更多点、退化网格与凸包外；节点和插值预测；零点不重复扣除；缺坐标/无接触；
 FN-only 的 FX/FY 不冒充 N；未知模型、附件损坏和依赖缺失；状态模型每帧只调用一次及 reset。