docs(api): daily audit 2026-08-25 — align stale envelope schemas (safari + consolidated)

[flashduty]

Summary

Daily api-review audit (2026-08-25). The full generate pipeline was not run this round: the knowledge pack is missing runbooks/api-review-apply-patches.py and runbooks/api-review-daily.md (confirmed by the pack sentinel: 20 files, no api-review runbook; established since 2026-08-24), so per iron rule 6 the generator stays blocked. Per the documented fallback, a deterministic audit on HEAD was performed instead (fixed content below), then surgical fixes applied.

Audit results (HEAD, all deterministic)

• Registry fc-pgy/logic/api/api_test.go @ 08c824a4: 920 rows, 337 auth: all; public set (auth=all, path not /event/push/) = 337 unique paths.
• Specs (per-module split files @ eba0b02): on-call 191, platform 27, monitors 42, rum 35, safari 42 = 337 — registry ↔ spec comparison is a perfect match in both directions (0 registry-only, 0 spec-only).
• Consolidated openapi.en/zh.json: 337 paths, identical to split union; en/zh parity: 0 path / operationId / schema-name diffs (all 5 modules).
• docs.json pages allow-list covers 191/27/42/35/42 ops (pages-only = 0, spec-only = 0); en/openapi/api-catalog.mdx: 337 rows, stated 337, module counts 191/42/35/42/27; zh same 337 rows.
• Lint: all 12 spec files load as JSON, $refs resolve, no duplicate operationIds, OpenAPI 3.1.0 → no endpoint added or removed → no docs.json / api-catalog.mdx changes needed.

Drift found and fixed (1 finding)

Stale lean envelope schemas in safari.openapi.{en,zh}.json + consolidated openapi.{en,zh}.json — committed internal drift:

• ErrorCode: missing x-enumDescriptions (per-value descriptions for all 20 wire codes), missing example, and a plain description instead of the canonical code/HTTP/meaning table.
• DutyError: missing properties.message.example; zh files carried English descriptions.
• ErrorResponse: zh files carried English description.

Canonical truth = the on-call split, which is byte-identical to platform/monitors/rum (verified). Fix: replaced the three schema definitions in the 4 stale files with the canonical objects (+112/−16 lines across 4 files):

File	Change
api-reference/safari.openapi.en.json	ErrorCode + DutyError → enriched
api-reference/safari.openapi.zh.json	ErrorCode + DutyError + ErrorResponse → enriched (zh text)
api-reference/openapi.en.json	ErrorCode + DutyError → enriched
api-reference/openapi.zh.json	ErrorCode + DutyError + ErrorResponse → enriched (zh text)

Verification: sort-key deep compare vs HEAD yields exactly 22 differences, every one in the three envelope schemas (no order churn); after the fix all 12 spec files carry an identical canonical envelope (explicit cross-file check); path counts unchanged (337); re-run JSON validation passes.

Notes

• The template/update partial-update semantics are already correct at HEAD (landed via docs(api): document /template/update as a partial update #303, merged) — no further action.
• This envelope alignment is the same content as the unmerged portion of PR docs(api): daily audit 2026-08-24 — align stale envelope schemas, fix template update semantics #305 (2026-08-24, closed with no comments); its template/update portion already landed via docs(api): document /template/update as a partial update #303. If the envelope alignment was deliberately closed, please comment here and this PR can be closed the same way; otherwise this is the remaining drift from that audit.
• Diff exceeds the usual <100-line bar only because the enrichment itself is 20 enum rows × 2 languages × 2 files (same magnitude as docs(api): daily audit 2026-08-24 — align stale envelope schemas, fix template update semantics #305's +116/−20); this is content, not churn.
• monit-webapi is not published to GitHub (flashcatcloud org 404) → monitors module unchanged, HEAD content carried over.
• unresolved registry rows: none (all 337 public rows match spec paths; no handler lookups needed since no regeneration).
• Constructed examples: none this run (no new operations, no example edits).