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

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。

仅按 AOI bbox + scale ladder 过滤仍然不够。Source→PBF expected scope 必须重放 Production 的实际可见范围语义：

• 按每个计划 tile 计算与生产一致的 buffer_tile_pixels expanded bounds；
• 按 zoom 的 scale ladder 顺序计算 coverage；
• finer scale coverage 先占用区域，coarser scale 只允许进入 coverage - occupied 的剩余可见区；
• AOI 边缘允许因 tile buffer 合法带入外侧 Source component；
• 同一 relation group 必须在“该 tile、该 native_scale、该 visible region”实际 selected 的成员集合上重新选择 base 与 LIGHTS；
• 不得先在全局 relation group 上固定一个 base，再套到所有 tile；
• expected tile occurrence set 必须与 PBF actual occurrence set 完全一致。

因此 audit 的 scope truth 是 Production Plan + policy + coverage + tile buffer，而不是裸 AOI bbox。AOI bbox 只用于说明工程范围，不能单独定义 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。