feat: enforce S-52 semantic conservation audits

docs/CM95_S52_语义守恒与运行时能力审计标准_v1.md

@@ -0,0 +1,326 @@
+# CM95 S-52 语义守恒与运行时能力审计标准 v1
+
+日期：2026-09-19
+
+## 1. 目的
+
+本标准用于防止 CM95 Source → S-52 Presentation → Delivery PBF → Runtime Renderer 的任意一层发生“输出看起来结构正确，但语义已经被降维或丢失”的情况。
+
+本标准的核心原则是：
+
+> 审计不能只验证输出自身是否自洽，必须验证输入语义是否完整守恒到输出，并继续验证输出中的每一种 runtime instruction 是否存在真实消费者。
+
+尤其禁止把以下不同概念混为一谈：
+
+- 物理实体数量；
+- presentation 数量；
+- drawing instruction 数量；
+- S-52 resource 数量；
+- runtime renderer capability。
+
+这些维度必须分别审计。
+## 2. 审计层级
+
+### 2.1 Source Entity 层
+
+验证原始数据库中的物理实体、relation、component 关系。
+
+例如一个航标 relation group 可以包含：
+
+- 1 个 TOWERS；
+- 2 个 LIGHTS。
+
+该关系的物理实体 cardinality 可以是 1，但 LIGHTS presentation cardinality 是 2。
+
+### 2.2 S-52 Presentation 层
+
+每一条会产生独立 portrayal 语义的 Source record，必须独立解析出 presentation。
+
+不得因为多个 Source record 最终附着在同一物理实体上，就只保留其中一个 presentation。
+
+### 2.3 Delivery PBF 层
+
+Delivery Feature 可以合并物理实体，但必须完整保存所有需要的 presentation facts。
+
+物理实体去重不得造成 presentation 去重。
+
+### 2.4 Runtime Capability 层
+
+任何没有静态物化、需要 Runtime 执行的 instruction/CSP，必须有明确 target renderer capability。
+
+“标记为 runtime”不等于“已经实现 renderer”。
+
+### 2.5 Visual / Runtime Evidence 层
+
+对需要实际屏幕行为的 instruction，还必须有真实 runtime evidence。HTTP 200、DOM 存在、字段存在均不能单独替代真实绘制验证。
+## 3. 基本守恒不变量
+
+### 3.1 Physical Entity Invariant
+
+若一个 relation group 表示一个物理航标，则允许：
+
+`N source components → 1 navigation_marks Feature`
+
+但必须有明确、可审计的 component trace。
+
+### 3.2 Presentation Cardinality Invariant
+
+若同一 relation group 中存在 N 条独立 LIGHTS，且这些记录均解析为 LIGHTS05，则：
+
+`N source LIGHTS → N LIGHTS presentations`
+
+不得变成：
+
+`N source LIGHTS → 1 selected LIGHTS presentation`
+
+### 3.3 Presentation Signature Invariant
+
+只比较数量不够。
+
+必须为每条 presentation 构造 canonical signature，至少覆盖：
+
+- source_record_index；
+- s52_csp_resolved；
+- display priority/category；
+- light mode；
+- light symbol；
+- arc outline/color/width；
+- arc start/end；
+- arc radius / sector radius；
+- sector start/end/sweep；
+- nominal range；
+- rotation / obscured；
+- light label / text literal。
+
+对于同一个稳定输出 Feature ID：
+
+`expected signature multiset == actual signature multiset`
+
+A+B 变成 A+A 即使 count 都为 2，也必须 FAIL。
+### 3.4 Tile Occurrence Invariant
+
+同一个稳定 Feature ID 出现在不同 XYZ tile 时，其 presentation signature set 必须一致。
+
+若同一个 Feature 在不同 tile 中出现不同的 LIGHTS presentation 集合，视为 tile occurrence drift，必须 FAIL。
+
+### 3.5 Runtime Capability Invariant
+
+对于 release 实际出现的每一种 runtime kind，只要 feature_count > 0，就必须检查目标 renderer capability。
+
+严格 portrayal parity 下：
+
+`required runtime kind → capability status IMPLEMENTED → implementation evidence exists`
+
+以下状态均不得视为 strict PASS：
+
+- PREVIEW_ONLY；
+- NOT_IMPLEMENTED；
+- capability entry missing；
+- implementation evidence 缺失或 marker 不存在。
+
+### 3.6 Resource Invariant
+
+SY/AP/LC 等资源存在性审计与 Runtime instruction capability 审计是两个独立维度。
+
+Resource Contract PASS 不得被解释为 Runtime Portrayal PASS。
+## 4. 审计范围必须绑定 Production Plan
+
+Source→PBF 审计必须绑定具体 Production Plan：
+
+- dataset_id；
+- plan_id；
+- AOI bbox；
+- zoom；
+- scale ladder；
+- FID manifest；
+- lookup IR；
+- PBF directory。
+
+不得把 AOI 内但不属于该 plan scale ladder 的 Source record 计入 expected set。
+
+审计 artifact 必须记录 plan_id 和 PBF directory。Finalize 必须验证 artifact 的 plan_id / PBF directory 与当前 release 一致，禁止拿其他 release 的 PASS 报告复用。
+## 5. Multi-LIGHTS 专项规则
+
+### 5.1 实体模型
+
+一座灯塔/灯标仍只产生一个主 `navigation_marks` Feature。
+
+### 5.2 Presentation 模型
+
+当 relation group 包含两条或以上 LIGHTS 时，主 Feature 必须有：
+
+`s52_light_presentations`
+
+数组中每条记录对应一条 Source LIGHTS，并保存已经完成 S-52 Lookup/CSP 解析的 presentation facts。
+
+### 5.3 向后兼容
+
+主 Feature 原有单组标量 LIGHTS 属性允许继续存在，但只作为主 presentation 的兼容字段。
+
+Runtime 看到 `s52_light_presentations` 后，必须以数组为完整 truth，不得只消费主标量。
+
+### 5.4 CA 特殊规则
+
+`CA(...)` 是 screen-space drawing instruction。
+
+arc radius 与 sector leg radius 使用屏幕毫米语义，不得预烘焙成地理圆。
+
+Renderer 必须执行：
+
+- outline；
+- colored arc；
+- sector start/end；
+- sector legs；
+- bearing / screen coordinate 转换。
+## 6. Runtime Kind 标准
+
+当前至少审计以下 runtime kinds：
+
+- RUNTIME_CA；
+- RUNTIME_DEPARE；
+- RUNTIME_DEPCNT；
+- RUNTIME_SOUNDG；
+- RUNTIME_OBSTRN；
+- RUNTIME_WRECKS。
+
+后续新增任何 runtime CSP/opcode 时，必须同步加入：
+
+1. usage scanner；
+2. capability registry；
+3. capability audit；
+4. 对应 runtime/visual regression。
+
+禁止出现“数据里新增 runtime kind，但 capability audit 不认识，因此被静默忽略”的情况。
+## 7. Release Gate
+
+### 7.1 Data Release Gate
+
+Builder Contract 0.4.11 及以后，finalize 必须要求独立的 Source→PBF presentation conservation audit artifact。
+
+缺少 artifact、schema 不匹配、plan_id 不匹配、PBF directory 不匹配或 audit status != PASS，release finalize 必须 FAIL。
+
+### 7.2 Target Portrayal Gate
+
+当声称某个具体 target 已达到 S-52 runtime portrayal 完整性或视觉 parity 时，必须额外提供该 target 的 runtime capability audit。
+
+只要 release 中实际出现的 runtime kind 有任意一个不是 IMPLEMENTED，则不得声称该 target runtime portrayal 完整。
+
+Data Release PASS 与 Target Portrayal PASS 必须分开表述。
+## 8. 禁止的审计方式
+
+以下方式不能单独作为完整性证明：
+
+- 只比较 input/output Feature count；
+- 只比较 PBF/report/decoded Feature count；
+- 只扫描已经损失后的 PBF；
+- 只确认字段名存在；
+- 只确认 Resource Contract PASS；
+- 只确认 style compiler 认识 RUNTIME_CA；
+- 只确认 HTTP 200；
+- 只确认 DOM / layer / source 已加载；
+- 用截图主观观察代替可重复的 signature/capability gate。
+
+这些检查仍然有价值，但只能作为各自层级的局部审计。
+## 9. 当前代码实现
+
+### 9.1 Presentation Conservation
+
+实现：
+
+- `src/cm95pbf/presentation_audit.py`
+- `tools/cm95_s52_presentation_conservation_audit.py`
+
+该审计器直接读取 NAS Source，不依赖 builder report 生成 expected set；按 Production Plan scale ladder 限定范围；使用 FID manifest 将 Source base entity 映射到稳定 PBF Feature ID；再解码 PBF，比较 multi-LIGHTS canonical signature set。
+
+当前会检查：
+
+- expected/actual multi-light group 数；
+- expected/actual presentation record 数；
+- signature mismatch；
+- missing/unexpected group；
+- tile occurrence drift；
+- Source LIGHTS05 resolution failure；
+- PBF presentation JSON/structure failure。
+
+### 9.2 Runtime Capability
+
+实现：
+
+- `tools/cm95_s52_runtime_capability_audit.py`
+- `config/s52/cm95_s52_runtime_capabilities_web_compare_v1.json`
+
+Style usage audit 已扩展 runtime CSP coverage，覆盖 DEPARE/DEPCNT/SOUNDG/OBSTRN/WRECKS，并继续覆盖 CA。
+
+Capability audit 会验证 capability status 和声明的 implementation evidence marker。
+
+### 9.3 Finalize Gate
+
+`finalize-production` 新增：
+
+- `--presentation-conservation-audit`
+- `--runtime-capability-audit`
+
+Builder Contract 0.4.11+ 的 presentation conservation audit 为硬门槛。
+
+Runtime capability audit 在提供时为硬门槛；没有提供时只能说明该 release 的 target runtime capability 尚未审计，不得据此声称 portrayal parity。
+## 10. 已验证回归
+
+双 sector LIGHTS 正向 regression：
+
+- Source expected multi-light groups：1
+- PBF actual multi-light groups：1
+- Source expected presentations：2
+- PBF actual presentations：2
+- signature mismatch：0
+- occurrence drift：0
+- Presentation Conservation：PASS
+
+同一 AOI 对修复前旧 release 做负向 regression：
+
+- Source expected multi-light groups：1
+- PBF actual multi-light groups：0
+- Source expected presentations：2
+- PBF actual presentations：0
+- missing group：1
+- Presentation Conservation：FAIL（missing_multi_light_groups）
+
+该负向回归证明审计器能直接抓到本次历史“multi-LIGHTS 被 composite 吃掉”的真实缺陷。
+
+CA-only target capability：
+
+- RUNTIME_CA observed：4 tile occurrences
+- capability：IMPLEMENTED
+- implementation evidence：PASS
+- CA capability audit：PASS
+
+完整 Web debug runtime capability：
+
+- RUNTIME_CA：IMPLEMENTED
+- RUNTIME_DEPARE：PREVIEW_ONLY
+- RUNTIME_DEPCNT：PREVIEW_ONLY
+- RUNTIME_SOUNDG：PREVIEW_ONLY（当 release 实际出现时）
+- RUNTIME_OBSTRN：NOT_IMPLEMENTED
+- RUNTIME_WRECKS：NOT_IMPLEMENTED
+- strict full runtime capability audit：FAIL
+
+该 FAIL 是正确结果，用于阻止把“部分 runtime preview”错误描述成“完整 S-52 runtime portrayal”。
+## 11. 后续扩展原则
+
+本标准不只用于 LIGHTS。
+
+任何存在以下结构的转换都必须采用相同方法：
+
+`多个 Source semantic records → 一个 Delivery physical Feature`
+
+例如组合航标、复杂危险物、复合文本、多个关联 portrayal record 等。
+
+必须分别定义：
+
+- physical entity invariant；
+- presentation cardinality；
+- canonical signature；
+- runtime kind；
+- target capability；
+- release gate。
+
+新规则如果没有对应 expected/actual 守恒审计，不应进入正式 Production Contract。