yovision/contracts/source-config/v1

Sense → Brain 媒体源与区域规则配置契约 v1

yovision.source-config/v1 是 Sense 发布、Brain 消费的完整配置快照。它只携带稳定逻辑标识、无凭据媒体引用、Profile 规格、归一化规则及完整性摘要，不暴露 Sense 数据库模型或 Brain 内部配置模型。

本版本选择 JSON Schema，而不是 OpenAPI：快照可经文件、消息或后续 connector 传输，工单 #148 不定义 HTTP 端点。后续 connector 若提供 HTTP API，应引用本 Schema，不复制字段定义。

文件

• source-config.schema.json：Draft 2020-12 JSON Schema。
• examples/valid/：可接受的 active 与待重校准快照。
• examples/invalid/：必须安全拒绝的版本、秘密、路径、坐标和绑定错误。
• compatibility.md：版本、兼容周期、迁移和回退规则。
• mapper-fields.md：Sense 生产者与 Brain 消费者字段映射和测试责任。

消费规则

1. 先按 JSON Schema 校验，再执行跨字段语义校验。
2. schema_version 必须精确等于 yovision.source-config/v1；未知主版本不得降级猜测。
3. rule_set.profile_binding 必须与 profile.id/width/height 完全一致。
4. rule_set.state != active 时不得运行任何规则；recalibration_required 表示 Profile 规格变化后需重新标定。
5. areas 与 directional_lines 的 id 在同一快照内必须全局唯一；多边形必须非退化，线段起终点不得相同。
6. effective_at 不得早于 published_at。
7. integrity.value 是移除顶层 integrity 后，对 RFC 8785 JCS 规范化 JSON 字节计算的 SHA-256 小写十六进制摘要。生产消费者应使用合规 JCS 实现；仓库样例只使用 JCS 简单类型子集。

media.ref 是 connector 解析的无凭据不透明引用，固定以 media: 开头。它不能包含 URI authority、用户名、密码、查询参数、fragment、Windows 盘符或文件系统路径。RTSP 凭据交换与机器身份不属于本契约。

可复制验证

从仓库根目录运行：

& contracts\tests\source-config-v1\run.ps1

脚本在系统临时目录创建隔离虚拟环境、安装固定版本的 Schema 校验器并运行测试，不修改产品目录。测试结束后会清理临时环境。