W1 — v0.27.0: make partial delivery loud (declared-vs-delivered, TOC merge) [P0]

[mmcky]

Sub-issue of the 2026-08-10 work-plan tracker. The detection layer for the silent-delivery-loss class — five production instances to date, latest on v0.25.0 (2026-08-10). All deterministic engine work.

• Declared-vs-delivered assertion (Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90.3, sync opens a PR whose _toc.yml references a lecture the same run failed to translate #156-B, sync silently first-translates lectures missing from the target — unreachable when it succeeds, invisible when it fails #222-B, Six defects observed syncing a six-PR batch to lecture-intro.zh-cn (declared files silently dropped, toc clobbered, .bib never synced) #256.1): every translation-sync-metadata.files entry ends the run either changed or recorded "no change required + reason"; unexplained empty ⇒ run fails. The assertion must compare metadata against the delivered set independently of the error plumbing: the four index.ts fetch sites are already fail-closed as of v0.25.0 (:525 collects into fetchErrors and :533–535 throws before any branch reset; :1097/:1158/:1190 feed result.errors via :881, which fails the run and opens a failure issue) — yet the 2026-08-10 fr#29 drop reported success, so the live drop path records no error at all. Trace and close that path as part of this item. The reconciliation runs both directions: files[] also under-declares today — the 2026-08-11 scenario-27 run delivered the bib entry and the state file with neither declared (W0 carry-forward) — so everything delivered must be declared, and everything declared must be accounted for.
• Partial PRs still ship on failure: when result.errors is non-empty the run is marked failed and a failure issue opens, but PR creation still proceeds (src/index.ts:902). Decide and implement: annotate the PR as partial (with the "Files failed" section below) or suppress creation.
• _toc.yml structured merge (Sync overwrites localised _toc.yml part captions with English, and nothing detects it #254, sync opens a PR whose _toc.yml references a lecture the same run failed to translate #156.1, Six defects observed syncing a six-PR batch to lecture-intro.zh-cn (declared files silently dropped, toc clobbered, .bib never synced) #256.2): add/remove - file: entries only; never write captions from source; skip entries whose target document is absent from target ∪ PR. Plus Sync overwrites localised _toc.yml part captions with English, and nothing detects it #254's deterministic caption-script assertion. Also dissolves the concurrent full-mirror coupling (sync opens a PR whose _toc.yml references a lecture the same run failed to translate #156 thread).
• PR body from the computed set (Six defects observed syncing a six-PR batch to lecture-intro.zh-cn (declared files silently dropped, toc clobbered, .bib never synced) #256.5) and a "Files failed" section linking the failure issue (sync opens a PR whose _toc.yml references a lecture the same run failed to translate #156.2); thread the run's error set into review input (Review verdict says PASS with diff 10/10 on a sync PR that cannot build — no cross-file reachability check, and the reviewer never learns the run errored #157 gap 2).
• State-not-response checks: PR-create adopt-on-timeout via unique head branch (PR creation reports failure when the GitHub API times out after succeeding (false negative; naive retry would duplicate) #92); rebase refuses to force-push a branch to/behind base — closes deliberately with a comment instead (Six defects observed syncing a six-PR batch to lecture-intro.zh-cn (declared files silently dropped, toc clobbered, .bib never synced) #256.4).
• Stalled-run detection (Sync silently does not run when a merged source PR has an agent-authored head branch #234): examples/detect-stalled-sync.yml + translate status --stalled + FAQ fingerprint for action_required runs.
• Stale-resync guard (resync regenerates from the source PR's merge-time snapshot — stale content reverts newer target edits #276, added 2026-08-19): a regenerated section's code cells must match current source main, so a mismatch is stale-snapshot content by construction; on mismatch the run fails instead of shipping the PR. Not a naive byte-match: fa and zh-cn localize docstrings and comments inside code cells (verified on numpy.md 2026-08-19) while fr keeps them English — compare code cells with comment/docstring lines stripped, or gate per-language on the code-comments rule. Detection only: making resync regenerate from current main (the repair) stays with resync regenerates from the source PR's merge-time snapshot — stale content reverts newer target edits #276, which remains open past this phase. Second lesson from the same incident, for the declared-vs-delivered box: a regeneration must account for every file of the PR it replaces — the 2026-08-18 fr regeneration silently omitted numpy.md, whose #595 edits remain undelivered (verified in content 2026-08-19).

Gate: land #169 (importable entry point) first or alongside — this phase edits index.ts, which has 0% test coverage. Validate with the e2e harness; watch the first organic sync after the tag moves.

Member issues: #90 #92 #156 #222 #234 #256 (defects 1/4/5) #276 (guard only) · supports #157

---

Generated by Claude Code

[mmcky]

Both rulings this phase was waiting on were taken 2026-08-10 (decision files on the #265 branch):

D2 = no first-translation. A metadata files entry whose target is missing is recorded as an explained gap ("target missing — seeding required") — it does not fail the run, and it renders in the PR body. The declared-vs-delivered assertion therefore has three terminal states per file: changed, no-change-with-reason, or explained-gap; anything else fails the run. The silent NEW-mode escalation (sync-orchestrator.ts:545/:650 at v0.25.0) is removed, not disclosed. D-2026-08-10-sync-does-not-first-translate.md

Partial PRs ship annotated. On a non-empty error set the PR still ships with a "Files failed" section linking the failure issue (#156.2); "Files Updated" renders from the computed delivered set (#256.5); state files for undelivered files stay unadvanced so the next run diffs from the correct base. The annotation and the assertion share the same computed delivered/failed/explained sets — build them once. D-2026-08-10-partial-sync-pr-ships-annotated.md

W1 is now fully unblocked: the remaining gate is landing #169 first or alongside.

[mmcky]

Retitled v0.26.0 → v0.27.0: verified 2026-08-19 that no W1 item landed in v0.26.0 (that release was the ml v0.3 rules + #250 judge fix + engineRef; every box here is untouched since 2026-08-10). W1 is the next engine build item per the current work plan (project-translation#36, item 4).

New adjacent failure mode worth folding into this work: during the 2026-08-19 backlog drain on lecture-python.zh-cn, the Rebase Translation PRs automation's force-pushes auto-closed two open sync PRs (#240 at 23:22:43Z, #247 at 23:27:11Z — closed and head_ref_force_pushed share a timestamp in each event log; GitHub momentarily evaluated the branch as empty against main). The PRs vanished from the open set with their content intact but undelivered, and the closed PRs report an empty diff — a silent-loss shape W1's declared-vs-delivered assertion wouldn't currently catch because it lives in the rebase workflow, not the sync run. Recovery was manual (recovery PRs zh-cn#255/#256). Consider either serialising the rebase automation's force-pushes with a guard, or adding a post-rebase assertion that every previously-open sync PR is still open.

[mmcky]

Follow-up to my 2026-08-19 comment above: the rebase force-push auto-close race is now filed as its own issue, #280, with the event-log evidence and a suggested guard. A second rebase-mode defect from the same night — the regeneration producing an internally incoherent file, reverting a merged refactor at one call site while keeping it at another — is recorded on #276, which already tracked the same root cause via the \translate-resync trigger path.

Both are silent-loss shapes that sit outside the sync run, so the declared-vs-delivered assertion in this issue would not catch either. Worth deciding whether W1's scope covers the rebase workflow or whether that becomes a separate W-track item.