hyb-oa/.trellis/tasks/08-09-deployment-contract-single-source-harness/prd.md

部署合同单一事实源与失败路径覆盖

Goal

消除正式 deploy.sh 与生产 preflight 对候选构建身份的重复定义，使完整候选提交、12 位公开前缀以及 BUILD_SHA / VITE_BUILD_SHA 映射由同一可执行合同派生；再用完全本地的假 SSH / 假 Docker harness 覆盖历史生产暴露的失败路径，让同类漂移在提交前失败，而不是通过真实 SSH 往返发现。

Confirmed Facts

• 生产部署刚实际暴露过两类工具缺陷：production-preflight.mjs 曾先检查 Prisma marker、覆盖远端真实错误码；preflight 还曾漏注入 Compose 强制要求的 BUILD_SHA / VITE_BUILD_SHA。
• 正式 deploy.sh 从 check-source-provenance.mjs 输出取得 commit 与 shortCommit；production preflight 又独立校验候选 SHA 并执行 slice(0, 12)。候选构建身份的派生逻辑因此存在两个实现点。
• production-preflight-remote.sh 对完整/短 SHA 格式和前缀关系的校验是远端消费端纵深防御，不属于应删除的重复定义。
• server/tests/unit/scripts/deployment-safety-contract.test.js 已有临时目录、假 SSH 和假 Docker 基础，也已有历史缺陷的部分回归断言；缺口是单一合同本身以及更多真实子进程失败分支，而不是再建一套测试框架。
• 项目生产拓扑只有一套承载公网的 legacy trialrun 环境，没有同构预发；因此本任务只运行本地 synthetic harness，不连接生产、不执行部署。

Scope

• 共享合同：check-source-provenance.mjs 中候选完整 SHA、12 位前缀和两个 Compose 构建环境键的可导入派生合同。
• 消费调用点：deploy.sh 与 production-preflight.mjs；远端 helper 只保留消费端 fail-closed 校验。
• 验证范围：provenance focused tests、现有 deployment safety fake SSH/Docker harness、env contract 与 Trellis 本地门禁。
• 环境边界：全部使用本地 synthetic 数据和临时目录，不运行任何真实 SSH、Docker 部署或生产命令。

Requirements

R1 候选构建身份单一事实源

• 在现有 deploy/trialrun/check-source-provenance.mjs 中提供可导入的候选构建身份函数和固定环境键合同。
• 输入只接受 40–64 位十六进制完整提交；一次调用必须返回完整 { BUILD_SHA, VITE_BUILD_SHA } 环境对象，固定派生完整 BUILD_SHA 与其前 12 位 VITE_BUILD_SHA。不得拆成两个可独立调用/修改的 getter，调用方不得自行重新截取、重新定义键名或只注入其中一项。
• collectSourceProvenance 的 CLI 结果保留既有 commit / shortCommit 兼容字段，同时提供由同一函数产生的构建环境对象；不得破坏既有部署调用与审计输出。
• deploy.sh 必须从 provenance 的构建环境对象读取并注入远端 Compose；production-preflight.mjs 必须导入同一函数生成远端命令输入。禁止任一调用方回退到 git rev-parse HEAD 或自行 slice(0, 12)。
• production-preflight-remote.sh 继续在 docker compose config 前校验两值存在、格式正确且前缀一致；这是 fail-closed 消费验证，不得因单一来源而删除。

R2 本地失败路径 harness

• 扩展既有 deployment-safety-contract.test.js，复用临时假 SSH / 假 Docker，不连接网络或真实 Docker daemon。
• production preflight 的真实子进程路径必须覆盖完整四象限：远端非零且有稳定错误码/无 Prisma marker；远端非零且有稳定错误码/有 marker；远端非零且无可解析错误码/无 marker；远端零退出但无 marker。前三种分别传播原码或返回 PRODUCTION_PREFLIGHT_REMOTE_FAILED，最后一种返回 PRISMA_STATUS_OUTPUT_MISSING。
• 失败路径仍须先写稳定脱敏 summary 与相对 report reference，再返回失败；不得为了测试错误码而跳过证据合同。
• 远端 helper 必须覆盖 Compose config 失败、缺失构建值、完整/短 SHA 格式错误和前缀不一致，并断言每种情况均在 Prisma status / 数据库写入前 fail-closed。
• provenance 测试必须覆盖完整/短 SHA 与固定环境键的同源性，以及非法提交输入；受控 SSH 成功 fixture 必须断言远端收到的两值等于共享合同输出。

R3 边界与兼容性

• 不改变 production target gate、migration reconciliation、rollback window、错误码语义、部署顺序或公网 smoke 行为。
• 不把备份、WARCH3 timer、自动备份脚本的全部 build-SHA 校验并入本轮；它们是不同运行合同，后续如需统一另行规划。
• 不执行 SSH、生产 preflight、部署、迁移、配置修改、账号操作或业务写入。
• 不以删除远端防御、降低 Compose 插值、放宽 SHA 格式或只加静态文本断言换取测试通过。

Acceptance Criteria

• AC1：候选完整 SHA、12 位前缀及两个 Compose 环境键由一次函数调用返回的完整 { BUILD_SHA, VITE_BUILD_SHA } 对象产生；没有两个独立 getter。deploy.sh 与 production preflight 均按整对象消费，不再各自派生短 SHA或只选择性注入一个键。
• AC2：既有 provenance CLI 字段保持兼容，部署脚本仍从已验证且已发布的候选提交生成远端构建输入；没有本地 HEAD fallback。
• AC3：远端 helper 保留格式/前缀/Compose fail-closed 校验，且失败发生在 Prisma status、迁移或任何业务写入之前。
• AC4：本地真实子进程 harness 覆盖远端错误码优先级完整四象限、Compose config 失败及构建身份缺失/非法/不一致；回退错误判断次序或任一调用点的完整对象注入时，对应回归用例必须失败。
• AC5：focused Vitest、provenance tests、node --check、bash -n、env contract、task/process/governance/sensitive 与 git diff --check 全部通过。
• AC6：只读 reviewer 核对单一事实源、调用点、fail-closed 顺序与测试有效性；reviewer 不修改代码。
• AC7：任务结论明确仅为本地部署 tooling hardening；未连接或验证生产，不宣称完成任何新部署。

Out of Scope

• 生产发布、预发建设、生产邮件、身份引导拓扑或 secret 持久化方式变更。
• 数据库 schema/migration、产品功能、认证、权限或合同业务状态机修改。
• 统一所有 backup/timer/monitor 的 build identity 合同，或重写全部部署脚本为单一语言。
• 处理 8 条会话夹具失败、员工负向验收、合同 UI 样本、管理员手册附件承诺。

Risks and Deferred Items

• Bash 与 Node 的远端命令格式仍然不同；本轮统一的是候选构建身份的来源、键和派生，不以跨语言模板引擎扩大风险。
• 远端验证与本地派生看似重复，但承担不同责任：前者防传输/调用漂移，后者建立单一来源。测试必须保留两层。
• 现有 deployment-safety-contract 测试文件较大；本轮优先复用 helper，避免继续复制 fake SSH/Docker 搭建逻辑。是否拆分测试文件不作为验收条件。

Test Plan

• node --check deploy/trialrun/check-source-provenance.mjs deploy/trialrun/production-preflight.mjs
• bash -n deploy/trialrun/deploy.sh deploy/trialrun/production-preflight-remote.sh
• cd server && npm test -- tests/unit/scripts/check-source-provenance.test.js tests/unit/scripts/deployment-safety-contract.test.js
• node deploy/trialrun/validate-env-contract.js
• python3 ./.trellis/scripts/task.py validate 08-09-deployment-contract-single-source-harness
• node scripts/qa/check-process-contract.mjs --baseline --json
• node scripts/qa/check-trellis-governance.mjs --json
• node scripts/qa/check-sensitive-content.mjs
• git diff --check

Open Questions

• 无。范围、兼容性和风险边界已由现有代码、生产故障证据及用户确认的实施顺序确定。