# PSP 数据契约

所有 SHA 使用 64 位小写 SHA-256；Git commit 使用仓库返回的完整 SHA。状态必须引用实际证据，不允许人工填写 `passed` 掩盖未执行步骤。

## `metadata/bsp.lock.json`

PSP 仓库内保存 BSP handoff 的稳定摘要，不保存自身 commit：

```json
{
  "schema_version": 1,
  "handoff_path": "/absolute/BSP/doc/bsp_adaptation/handoff/psp_handoff.json",
  "handoff_sha256": "<sha256>",
  "bsp_project": "CV1841CP-LY-SM-YT70_dualos",
  "bsp_commit": "<完整Git SHA或旧交接中的null>",
  "bsp_source_dirty": false,
  "chip": "CV1841CP",
  "build_id": "20260901_1",
  "imgs_version_path": "/epbuild/EMX2.0/EmxRes/.../imgs/20260901_1",
  "image_partition_margin": {
    "partition_table": "/absolute/BSP/configs/.../partition_spinand.xml",
    "required_margin_bytes": 524288,
    "checks": [
      {
        "image": "kernel.bin",
        "image_size_bytes": 2621440,
        "effective_partition_size_bytes": 3670016,
        "actual_margin_bytes": 1048576,
        "passed": true
      },
      {
        "image": "rootfs.bin",
        "image_size_bytes": 3145728,
        "effective_partition_size_bytes": 4194304,
        "actual_margin_bytes": 1048576,
        "passed": true
      }
    ]
  },
  "artifacts": [
    {
      "relative_path": "boot.bin",
      "absolute_path": "/epbuild/.../boot.bin",
      "size": 123,
      "sha256": "<sha256>"
    }
  ],
  "mixed_build": null,
  "warnings": []
}
```

混用构建时 `mixed_build` 记录每个文件来源、build ID、commit、hash、原因、风险、确认人和时间；默认值为 `null`。

## `metadata/allowed-overrides.json`

为保持 `psp.json` 兼容，应用同名覆盖的精确白名单放在 sidecar：

```json
{
  "schema_version": 1,
  "overrides": [
    {
      "psp_path": "configs/sdcard.json",
      "application_path": "orgConfigs/sdcard.json",
      "winner": "psp",
      "reason": "板级存储配置由 PSP 提供",
      "confirmed_by": "<负责人角色或姓名>",
      "confirmed_at": "<ISO-8601>"
    }
  ]
}
```

路径必须是仓库内精确相对路径，不允许绝对路径、`..` 或通配符。

## 应用侧 `psp.lock.json`

由应用层创建，不放进 PSP 仓库：

```json
{
  "schema_version": 1,
  "project_id": "LY-SM-YT70",
  "psp_path": "psp",
  "psp_repository": "<团队共享Git地址>",
  "psp_commit": "<完整Git SHA>",
  "expected_state": "candidate",
  "bsp_build_id": "20260901_1",
  "etunel_work_id": "<WORK_ID>",
  "etunel_handoff_subtask": "<SUBTASK_ID>"
}
```

submodule gitlink 是实际锁定依据；lock 用于人和工具核对。两者不一致时停止构建。

## CV18 Sensor 静态证据

`validate_psp.py` 的 `checks.sensor_baseline` 记录 `sensor_cfg.ini` 的绝对路径/hash、枚举头文件绝对路径/hash/enum tag/`source`、芯片系列和每个 Sensor section 的规格枚举名称、期望配置值、实际值及匹配结果。默认 `source=bundled`，由芯片系列自动选择 skill 内置枚举表；只有明确传入替代头文件时为 `source=override`。CV181X 的 `expected_config_value` 是枚举名称；CV184X 是从 `_SNS_TYPE_E` 解析出的规范十六进制值。

## 本地固定打包契约和 `packaging-result.json`

用户提供应用工程路径和芯片后，`record_packaging_result.py contract` 按 EMX2.1 固定目录与命令生成打包契约。契约不放进 PSP 仓库，机器 schema 为：

```json
{
  "schema_version": 2,
  "contract_type": "emx21-project-packaging",
  "contract_id": "<稳定且唯一的契约ID>",
  "chips": ["CV1841CP"],
  "project_root": "/absolute/application-project",
  "psp_path": "/absolute/application-project/psp",
  "working_directory": "/absolute/application-project/scripts",
  "output_root": "/absolute/application-project/output",
  "product_command": "./product.py",
  "release_commands": ["./release.py 0", "./release.py 1"],
  "success_exit_codes": [0]
}
```

四个路径必须严格满足上述父子关系，命令必须逐字匹配；应用工程路径、`psp` 子仓库或脚本无法验证时不得创建占位值或形成 `packaged`。`release.py 1` 还需要本轮用户确认 clean rebuild，不能只依赖契约中的允许列表。

`record_packaging_result.py preflight` 生成不可覆盖的 `schema_version: 1` 检查结果。候选提交前可以用 `--psp-source <staging>` 检查待导入内容；正式组包前必须使用应用工程内 `psp`、完整 commit 和 `--formal`。结果至少记录 PSP/脚本路径、资源来源映射、分区、BSP 分区比对、错误和警告。

`record_packaging_result.py snapshot` 生成不可覆盖的 `schema_version: 3` 快照，至少锁定契约路径/hash/id、打包前 PSP Git 状态、应用工程 Git 状态和既有 `output` 直接版本目录及目录树 hash。

`record_packaging_result.py record` 生成 `schema_version: 2` 的 `packaging-result.json`，至少包含 `passed`、契约路径/hash/id、芯片、PSP 仓库/commit/dirty、BSP build ID、应用工程路径/commit/dirty、执行目录、两阶段精确命令/退出码/日志证据、clean rebuild 确认状态、本轮新增版本目录绝对路径和完整文件清单，以及用户/项目指定烧录包的绝对路径、大小、mtime 和 SHA-256。日志证据只保存外部日志路径/hash/大小以及失败或警告的行号和行 hash，不复制日志正文。

本轮必须恰好新增一个 `output/<版本>/` 直接子目录，且既有版本目录未被修改或删除。handoff 生成时再次核对契约文件和烧录包 hash。

## 外部 `device-validation.json`

```json
{
  "schema_version": 1,
  "result": "PASS",
  "evidence_source": "USER_REPORTED",
  "psp_commit": "<完整Git SHA>",
  "image_path": "/absolute/path/to/flash-package.img",
  "image_sha256": "<sha256>",
  "board": "LY-SM-YT70",
  "hardware_revision": "<revision>",
  "checks": [
    {"name": "boot", "result": "PASS", "evidence": "<用户反馈摘要>"}
  ],
  "unexecuted": [],
  "issues": [],
  "confirmed_by": "<用户或负责人>",
  "confirmed_at": "<ISO-8601>"
}
```

适用检查未执行时总体结果不能为 PASS。

## 外部 `application-integration.json`

至少包含 schema、结果、PSP commit、应用仓库/commit、应用构建和打包命令/退出码、产物证据、覆盖检查、未执行项、应用负责人和确认时间。

## 外部 `psp-handoff.json`

由 `render_psp_handoff.py` 汇总，不复制 PSP 配置。至少包含项目/芯片、PSP 仓库/完整 commit/Git 状态、参考 PSP、BSP lock、Media/AIPlugin 基线、验证状态、烧录包、应用集成、Etunel 标识、自检、负责人确认、未执行项、警告、例外和风险。没有有效 Etunel 上下文时必须标记 `etunel.sent=false`。供 Etunel 使用时只允许 `packaged` 或 `accepted`，并记录 `git ls-remote` 对当前共享 URL/commit 的可达性结果；生成文件本身仍保持 `sent=false`。