sync opens a PR whose _toc.yml references a lecture the same run failed to translate

[mmcky]

The first organic production sync on v0.23.0 (QuantEcon/lecture-python.myst#992 → QuantEcon/lecture-python.zh-cn#202) shipped a PR that cannot build, because the run committed a _toc.yml entry for the one file it had just refused to write.

What happened

The source PR added ten new lectures. Nine translated cleanly. lectures/phillips_lost_conquest.md failed the structural parity check — correctly; the translation came back with its directive sequence scrambled and the MyST target anchor dropped:

##[error]Error processing lectures/phillips_lost_conquest.md: Error: structural parity check failed:
  - directive count differs: source has 28, output has 27
  - directive #1 name changed: source line 15 has {raw}, output line 40 has {contents}
  - directive #4 name changed: source line 68 has {code-cell}, output line 115 has {math}
  ...
  - target anchors diverge — missing from output: (phillips_lost_conquest)=

That guard did exactly its job, and the failure issue (QuantEcon/lecture-python.myst#993) was filed with a correct \translate-resync recovery recipe. The problem is what happened next:

Processing TOC file lectures/_toc.yml...
Successfully processed lectures/_toc.yml
##[error]Translation completed with 1 errors
Creating PR in target repository...
Created PR: https://github.com/QuantEcon/lecture-python.zh-cn/pull/202

The committed lectures/_toc.yml carries - file: phillips_lost_conquest at line 131. The target build fails under -n -W: toctree contains reference to nonexisting document 'phillips_lost_conquest'.

Why this is worse than one absent file

The dangling reference is not confined to the TOC. The dropped lecture is cross-referenced from four of the nine siblings that did ship, so a partial run does not degrade gracefully to "nine good lectures and one to follow" — it degrades to nine lectures that each carry a broken cross-reference:

Location	Warning
lectures/intro.md	toctree contains reference to nonexisting document phillips_lost_conquest
lectures/phillips_drifts_volatilities.md:67	unknown document: phillips_lost_conquest
lectures/phillips_drifts_volatilities.md:2990	unknown document: phillips_lost_conquest
lectures/phillips_priors.md:523	unknown document: phillips_lost_conquest
lectures/phillips_two_stories.md:90	unknown document: phillips_lost_conquest
lectures/phillips_two_stories.md:539	unknown document: phillips_lost_conquest

When an upstream PR adds a coherent set of lectures that cite each other — which is the normal shape of a new lecture series — dropping any one member breaks the rest.

Mechanism

TOC processing runs unconditionally after the per-file loop and does not consult the run's error set; the TOC is then committed like any other output, and PR creation proceeds after Translation completed with N errors is already logged. The three stages each behave sensibly in isolation and there is no point at which the partial state is reconciled.

Suggested fix, cheapest first

1. Filter the TOC (minimum). When assembling _toc.yml, drop entries naming files the run failed to produce that are also absent from the target repo. Deterministic, no new inputs required, and would have made E2E harness: a full run should test a single release, not sync-at-ref plus review-at-@v0 #202 buildable on its own.
2. Declare the partial state on the PR. The body lists "Files Added" with a ✅ per file and says nothing about the file that failed. A "Files failed" section carrying the parity error and a link to the failure issue would stop a reviewer reading the red build as unexplained — at present the failure issue is filed in the source repo and nothing in the target PR points to it.
3. Consider whether a partially-translated new-file set should open a PR at all. Nine good translations are worth keeping rather than discarding, so 1 + 2 is probably the right balance, but the choice should be deliberate rather than incidental.

Related

• Distinct from Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90 — those five are silent loss while the run reports success. This is the inverse: the run reports failure, and ships anyway.
• forward/sync don't carry shared assets referenced by lectures — quant-econ.bib and _admonition/* dangle and fail strict builds #117 is the other reason E2E harness: a full run should test a single release, not sync-at-ref plus review-at-@v0 #202 cannot build (shared assets not carried across); the two are independent and both need fixing before that PR is green.

[mmcky]

Fourth field instance — and this one is completely silent

QuantEcon/lecture-python.zh-cn#208 (v0.24.0, source PR lecture-python.myst#1006, 2026-07-26) dropped lectures/learning_approximation.md — the same file, from the same cause, as #207 the same weekend. Its translation-sync-metadata block lists nine files; the PR delivers eight.

The important part is what it did not do. QuantEcon/lecture-python.zh-cn#208 writes no _toc.yml entry, so the drop produced no dangling reference, no build failure, and no visible symptom of any kind. The preview build is green and the verdict scored PASS. The only trace anywhere is the nine-entry metadata array against an eight-file PR — which nothing compares.

This changes how the incidence of this defect should be read. QuantEcon/lecture-python.zh-cn#207 broke loudly only because that run was also adding _toc.yml entries; the dangling reference is what made it visible, not the drop itself. So the three recorded instances (myst#993, myst#1004, myst#1007) are not the rate — they are the subset that happened to coincide with ToC writes. Every partial run on a sync that adds no ToC entries has been failing silently, and there is no signal in the estate that would have told us.

Both weekend PRs hit it: four instances, not three.

One cheap mitigation independent of the atomicity fix: compare the metadata files array against the files actually in the PR, and surface any difference in the PR body and to the reviewer. That comparison is free, it needs no run-state plumbing, and it converts the silent case into a visible one. Filed as part of the broader escalation problem in #222, which is what put learning_approximation on this path in the first place — it was never in the target, so the run attempted a full first-time translation of it rather than a sync.

[mmcky]

New field instance class (2026-08-07), adjacent to this defect: concurrent full-ToC mirrors couple sync PRs to each other. Three lecture-adding syncs open simultaneously on lecture-python.zh-cn (#230, #231, #242) each regenerated _toc.yml as a full mirror of the source ToC — so each references lectures that are delivered in the other open PRs, and every one of them fails the strict preview with toctree contains reference to nonexisting document until the others merge and it rebases. Each also re-introduced the undelivered learning_approximation entry (zh-cn#210 has that trail), and the citation side re-broke per action-translation#117 (17 missing keys on #230, ~10 on #231 — all present in the source bib, adopted wholesale on the #230 branch after a strict-subset check). Not filing separately since the root is the same partial/concurrent atomicity question this issue owns; recording so the class has a name when it's designed away.

[mmcky]

PR #289 status 2026-09-01: reviewed in full and upgraded on the contributor's branch (head 4d1f02d, CI green, mergeable, awaiting @kp992's look). The mechanism was right; the upgrades are a byte-preserving removal (the original yaml.dump round-trip turned the one-line removal into a 401-line rewrite of the real lecture-python TOC), coverage of the second way a new file fails to arrive (source fetch failure — the file never reached the filter), and a PR-body notice that says exactly what happened to the TOC entry, including the silent zh-cn#208 shape where no TOC was in the changeset. Details in the review comment on #289. Still W1's: the declared-vs-delivered assertion that makes the drop visible when no TOC is involved (#259 box 1). Merge order with #291 is #289 first.