sync silently first-translates lectures missing from the target — unreachable when it succeeds, invisible when it fails

[mmcky]

On QuantEcon/lecture-python.zh-cn#208 — an organic production sync on v0.24.0 from source PR QuantEcon/lecture-python.myst#1006 — the run silently escalated from "apply an eight-line diff" to "translate two entire lectures from scratch". One of the two succeeded and was committed unreachable; the other failed and was dropped without a trace. Neither escalation is disclosed in the PR body, the sync metadata, or the review verdict.

What the source PR asked for

#1006 is a narrow change: add hidden pip install cells to nine lectures. Every file in it is +8/-0 or +1/-1.

Seven of those nine already existed in lecture-python.zh-cn, and the sync handled them correctly — I checked all seven diffs and they carry the pip cell and nothing substantive else.

The other two, olg_adaptive_money.md and learning_approximation.md, did not exist in the target at all. Both are present in the source _toc.yml (lines 124 and 125), so they are simply untranslated lectures — coverage gaps predating this PR. Rather than reporting that, the run translated both from scratch.

Defect A — when the implicit first-translation succeeds, the lecture lands unreachable

olg_adaptive_money.md was translated in full and committed at +1263 lines. Its state file records mode: NEW, so the engine is aware it did something other than a sync. QuantEcon/lecture-python.zh-cn#208 never touches lectures/_toc.yml.

Merged as-is, the target repo gains a 1263-line lecture that is in no toctree: not built, not linked, invisible to readers. Coverage metrics improve and the published site is unchanged. This is the exact mirror of #156 — there, a _toc.yml entry with no file; here, a file with no _toc.yml entry.

To be clear about what is not wrong: the translation itself is good. It is structurally parallel to source (62 fenced directives against 62, 23 headings against 23, 16 display-math blocks against 16), carries a complete 19-entry heading map and a translation.title, and includes the pip cell the source PR added. The output is fine; the delivery is broken.

Defect B — when it fails, the drop is completely silent

learning_approximation.md is listed in QuantEcon/lecture-python.zh-cn#208's translation-sync-metadata block as one of nine files. Only eight were delivered. It failed structural parity — the same file, from the same cause, that broke #207 the same weekend.

The difference is that QuantEcon/lecture-python.zh-cn#207 was adding _toc.yml entries, so its drop produced a dangling reference and a hard build failure. QuantEcon/lecture-python.zh-cn#208 wrote no _toc.yml entry, so the identical drop produced no dangling reference, no build failure, and no visible symptom of any kind. The only evidence is a nine-entry metadata array against an eight-file PR.

The consequence for #156 is that its observed incidence is an undercount. The defect is visible only when the run happens to also be writing ToC entries; when it is not, it fails completely silently. Both weekend PRs hit it — that is four field instances, not three.

Why the escalation is itself the problem

Concern	Detail
No mandate	The source PR changed eight lines. Nothing in it authorises translating a 53 KB lecture from scratch.
Wrong path's guard rails	This is init work performed on the sync path, so it inherits none of init's handling — notably the ToC insertion gap tracked in #142, whose "walk the source TOC order and insert after the nearest preceding entry that exists in the target" algorithm is exactly what is missing here.
Not disclosed	The PR body lists olg_adaptive_money.md under "Files Added" indistinguishably from a state file. Nothing says "this lecture was translated in full because the target lacked it", and nothing says a ninth file was attempted and dropped.
Not coordinated	#207 independently first-translated the same lecture from an older source SHA. Two open PRs each create lectures/olg_adaptive_money.md and its state file; both read mergeable against main, so the collision only surfaces after the first merge.
Not caught in review	The verdict scored scopeCorrect: false — correct outcome, wrong reason. It argued the file "already existed in the source's Before state, so it should have been an update", reasoning from the source when the relevant fact is the target. It never noticed the missing _toc.yml entry, and it scored the dropped ninth file as though it had never been attempted.

Suggested fix

The first question is a policy decision, not an implementation detail: should sync first-translate a file missing from the target at all?

If no — the run applies what it can, reports the gap explicitly (a failure issue or a PR-body section naming the untranslated lectures), and leaves seeding to init, where #142 and #134 are already tracked. This is the conservative option and it makes the coverage gap visible instead of half-closing it.

If yes — then the escalation must be complete rather than partial. It must insert the _toc.yml entry using #142's algorithm, and it must say in the PR body which files were first-translated rather than synced, so a reviewer knows the diff contains a full translation rather than an eight-line edit.

Either way, two things hold regardless of which is chosen:

• Any file present in the sync metadata but absent from the PR must be surfaced — in the PR body and to the reviewer. Defect B is invisible today only because nothing compares those two lists, and that comparison is free.
• 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's reachability check should run in both directions. As specified there it validates _toc.yml entries against the union of (target repo ∪ PR). The inverse — every markdown file the PR adds is reachable from _toc.yml — is the same filesystem-and-regex pass and catches this case. That is three field instances for 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 now, and they are bidirectional.

Evidence

Fact	Verified
olg_adaptive_money.md absent from lecture-python.zh-cn@main	404 via contents API
Present in source at 53,661 bytes, in source _toc.yml line 124	contents API + _toc.yml
QuantEcon/lecture-python.zh-cn#208 adds it at +1263/-0, state mode: NEW, tool-version: 0.24.0	PR files + state file
QuantEcon/lecture-python.zh-cn#208 touches no _toc.yml	PR file list (16 files, none is _toc.yml)
QuantEcon/lecture-python.zh-cn#208 metadata lists 9 files, PR delivers 8	translation-sync-metadata block vs PR file list
learning_approximation.md absent from target and from both PRs; present in source at 31,311 bytes	contents API
QuantEcon/lecture-python.zh-cn#207 also creates lectures/olg_adaptive_money.md (+1255/-0) and its state file	PR file list

Engine version 0.24.0 throughout; both PRs carry engineVersion: 0.24.0 in their verdict blocks.

Refs: #156, #157, #142, #134, #117, #90

[mmcky]

Field confirmation — QuantEcon/lecture-python.zh-cn#208 merged 2026-07-27, and the predicted fallout all landed

Both defects reached main, and the collision turned out to be worse than described: it also breaks the engine's own rebase automation.

Defect A confirmed in production

lectures/olg_adaptive_money.md is now in lecture-python.zh-cn@main at 53,921 bytes, with zero occurrences of olg_adaptive_money in lectures/_toc.yml. A full lecture is in the repository and reachable from nothing.

The collision materialised exactly as predicted

Immediately after the merge, #207 went mergeable: CONFLICTING, mergeStateStatus: DIRTY, on precisely the two files flagged above — lectures/olg_adaptive_money.md and .translate/state/olg_adaptive_money.md.yml, both add/add.

New: the sibling-rebase automation cannot recover from it

The Rebase Translation PRs workflow fired on the merge (run 30238457465) and failed — 0 rebased, 0 skipped, 1 errors — with two distinct errors on #207:

1. olg_adaptive_money.md — Error: Document must have a # title heading. This is a false negative. The document has an H1 at line 47, # 世代交叠货币经济中的适应性主体, in both the #207 branch version and the main version that #208 landed. Verified with git show against each ref. Whatever the rebase path is inspecting, it is not finding a title that is plainly present — and the trigger appears to be the collision itself, since the file changed from "absent in target" to "present in target" when #208 merged.

2. genetic_classifier.md — structural parity failure, and it is the #118 signature again: directive count 36 → 35, directive #1 {raw} at source line 15 against {index} at output line 42, plus target anchors diverge — missing from output: (genetic_classifier)=. Note this is a different file from learning_approximation: genetic_classifier.md was delivered intact in #207, but re-translating it during the rebase corrupts it the same way. So the head-of-document re-fencing is not specific to one lecture.

The practical consequence is that the automation has no path forward: it cannot rebase #207, and each attempt re-runs a full translation that reproduces the corruption. The PR has to be repaired by hand.

What the hand repair required

For the record, since it is the cost side of this defect:

• Resolve both add/add conflicts in favour of main's versions — Resume 2026-07-26: finalise #206, smoke the harness, verify v0.24.0 in the estate, update tracking issues #208's copy is the correct one, being built from the newer source SHA (a4fbd86) and structurally matching source at 62 fenced directives to 62, where Native-speaker review: the ml reference translations seeding the test harness #207's predates #1006 and is one short.
• Drop the learning_approximation _toc.yml entry and remove four {doc} cross-references to it from bounded_rationality.md and genetic_classifier.md.
• Replace quant-econ.bib wholesale from the English source — 21 keys were missing, not the 18 the failing build reported, the other three being latent citations not yet referenced.

After that, all 355 citations resolve, every _toc.yml entry has a file, and every lecture is reachable from _toc.yml.

Implementation note for the bidirectional check

When implementing the reverse direction discussed in #157, the {doc} scan needs to exclude namespaced intersphinx targets. Running it over this repo surfaces 31 references of the form intermediate:ifp_discrete, advanced:additive_functionals, intro:eigen_II — all valid cross-project links to sibling lecture series, none of them dangling. A naive "does this resolve to a local file" check reports every one as a defect.

[mmcky]

Decision D2 taken 2026-08-10: sync does not first-translate target-missing lectures. The contract is to propagate diffs to lectures that already exist in the target; a missing target is a gap to report — "target missing — seeding required" in the delivered-set accounting and the PR body — with seeding left to init (#142's gap-fill, W5 #263). Growing an edition by a lecture is an editorial decision a human takes, not something a sync run discovers post-hoc.

Recorded as .dev/decisions/D-2026-08-10-sync-does-not-first-translate.md (landing via #265). Defect B (the eight-against-nine metadata signature) is now pure detection work under W1's declared-vs-delivered assertion (#259); no escalation path gets built. This issue stays open until the W1 work makes the silent NEW-mode escalation impossible.

[mmcky]

This issue is the right home for a coverage gate — and most of the machinery already exists

Surfaced while re-verifying project-translation#37, whose plan proposed opening a new item for "no stage compares the source lecture set against a target's". That premise was wrong, and this issue is where the remaining work belongs rather than a fresh filing.

Three source-vs-target comparisons already exist, and all three have been correct for weeks.

1. The engine already files a per-run failure record. A translation-sync-failure issue is opened on the source repo whenever a sync errors, carrying the verbatim error and a recovery instruction. Fifteen are open right now, every one with zero comments, oldest 2026-07-23 — QuantEcon/lecture-python.myst 993, 1004, 1007, 1028; QuantEcon/lecture-python-intro 812, 817, 818, 820, 822; QuantEcon/lecture-python-programming 606, 609, 610, 613, 614, 615. Two of them (lecture-python.myst#1004 and #1007) are the primary evidence for the #118 block on learning_approximation, which the estate has been citing second-hand from a downstream issue title.
2. The dashboard collector runs a genuine nightly set diff. collector/collect.py in QuantEcon/status-translations emits per-edition {"slug": …, "state": "missing"} on cron 17 3 * * *. Checked against data/history/: it named mccall_risk on lecture-python.zh-cn in the 2026-08-06 snapshot — the first nightly run after the lecture landed upstream, and the day before its delivery PR was auto-closed — and in all 14 snapshots since, covering the entire twelve days between that auto-close and the gap's discovery on 2026-08-19. It has named the three lecture-intro.zh-cn gaps in every snapshot the history holds, from 2026-07-09.
3. The CLI already implements the comparison. src/cli/commands/status.ts unions source and target file lists via resolveFilePairs and classifies a source file with no target as SOURCE_ONLY. It is simply unreachable from the Action — action.yml's mode accepts only sync, review and rebase — and no edition workflow invokes the CLI.

So the gap is surfacing, not detection, which makes this issue's "Suggested fix" (surface coverage gaps in the PR body; compare the sync metadata file list against the delivered list) the correct and much cheaper shape. Options in ascending cost, for whoever picks it up: alert on the collector's existing missing[]; expose a status mode on action.yml; schedule a bench invocation of the existing CLI.

One failure mode none of the three catches. On 2026-08-19, lecture-python-intro#839 merged with lectures/mobility.md added. The sync workflow is active, its paths filter matched, and its merged == true condition held — and no pull_request run was created for that merge: not skipped, not failed, not parked awaiting approval — absent. (The only sync-workflow run naming that PR is a pre-merge issue_comment run at 04:32Z, skipped by the trust guard.) No failure issue was filed because nothing ran. The analogous lecture-python-intro#837 fired a pull_request run three seconds after its own merge two days earlier. Nothing else fired for that merge commit either — the push-triggered Data URL guard has no run for d7670896 though it ran for #837 — so this looks like an Actions dispatch gap rather than a workflow-condition bug. A declared-vs-delivered assertion inside the sync run cannot see this, because there is no run; only a periodic comparison can. Worth noting when scoping, since it argues for the scheduled route over the in-run one.

Full evidence is recorded in the programme's private planning repo, project-translation, as research/2026-08-20-edition-coverage-audit.md.