# R1.2 实现报告

## 交付

- Webhook HTTP 路径在验签、规范化字段校验后，仅把 `deliveryId/repo/ref/after/payloadSha` 等最小记录写入持久 inbox；文件 `fsync`、原子 rename 与目录 `fsync` 完成后才返回 `202`。
- 首次投递的 `202` 表示持久接收为 `accepted`，并明确 `refsCommitted=false`。重复投递的 `202` 返回 journal 当前真实状态；相同 delivery 与相同正文幂等，相同 delivery 但正文或规范字段不同返回 `409`。
- ingress 使用 YAML `responseBudgetMs=6500` 控制从请求进入到 body 读取、持久接收完成的绝对时限，与 worker 单次执行时限相互独立。时限耗尽返回 typed `503`，但不取消正在进行的持久写入；迟到的成功或失败会继续记录，重试仍按同一 delivery 幂等关联。
- 重复 delivery 响应返回 journal 的真实状态。`accepted`、`processing` 与 `failed` 都保持 `refsCommitted=false`；只有 `committed` 才携带已持久化的 refs proof。
- 持久 journal 采用严格 schema、不可变 identity、单调 sequence、崩溃恢复和每仓库 committed watermark。PVC 不可用、journal 损坏或容量耗尽时 readiness 失败并返回 `503`。
- record 列举、worker 调度与 status 统一按不可变 `acceptedSequence` 排序；即使多笔接收记录具有相同毫秒时间戳，也不会回退到 delivery ID 或文件名顺序。
- worker 每仓库串行、跨仓库并行；普通与 terminal backoff 都由 YAML 配置。terminal cycle 耗尽后仍自动进入下一 cycle，不要求人工重送。
- executor 抛错以及返回 `undefined`、`null` 或缺少成功证明的 malformed terminal result，都会持久标记为 typed failure 并进入自动重试，不能被误判为成功。
- Git 收敛先验证精确 `after`，再用一次 `git push --atomic` 更新带 lease 的 branch 与不可变 snapshot；乱序祖先只创建 snapshot，分叉 fail-closed，提交 journal 前重新读取远端 refs 证明结果。
- SIGTERM/超时会中止活跃 Git 进程组；未完成 record 保留并在新进程恢复。

## 自动 desired delivery

- [UniDesk #1760](https://github.com/pikasTech/unidesk/issues/1760) 新增独立 `platform-infra-gitea-nc01` PaC PipelineRun。它由既有 `sentinel-nc01-v03` Repository CR 在真实 `master` push 上发现，不依赖 todo-note 镜像构建。
- PipelineRun 使用既有 `default` ServiceAccount，从 immutable source snapshot 执行独立 publisher，不依赖本次 desired 才会创建的 bridge ServiceAccount。
- publisher 以 CAS 向 `unidesk-host-gitops` 写入三项：现有 parent path 下的 child Argo Application、独立 platform-infra desired path、source release state。只 stage 自己的三个路径，保留并发 todo/sentinel 文件。
- source state 只允许同提交幂等或祖先向前；同提交的 stored materialization hash 必须与 exact-source renderer 一致，否则 fail-closed。旧事件标记 superseded，分叉拒绝。push race 重新 clone 最新 head 后重试，成功后再 `ls-remote` 证明目标 ref。

## Ingress retry 边界

- Caddy 请求体安全重放、4xx 不重试、可重试 502/503/504、硬时限与 body cap 的 renderer 和真实 Caddy 测试已经具备。
- PK01 host 尚无 PR-merge 自动 reconciler，因此 owning YAML 明确设置 `ingressRetry.enabled=false`，继续渲染现有无重试转发，不宣称该能力已上线。
- 自动 host reconciliation 独立跟踪在 [UniDesk #1768](https://github.com/pikasTech/unidesk/issues/1768) 与 `docs/MDTODO/pk01-caddy-gitea-webhook-auto-reconciliation.md`；禁止手工 apply 补链。

## 测试证据

- durable bridge：21 个 Node 集成测试通过，覆盖入口绝对时限与迟到写入、重复投递各状态、同毫秒顺序、executor reject 与 malformed result。
- independent publisher：首次发布/幂等、并发文件保留与 CAS fresh retry、乱序/分叉、同提交冲突 state 共 4 个测试通过。
- desired bootstrap contract：既有 Repository、既有 ServiceAccount、child Application 与完整 bridge manifest 共 2 个测试通过。
- Caddy renderer：单元测试通过；Caddy v2.11 真实重放集成测试另行在完整验收组运行。
