resync regenerates from the source PR's merge-time snapshot — stale content reverts newer target edits

[mmcky]

Observed 2026-08-18 on lecture-python-programming: commenting \translate-resync on PR #595 (merged 2026-08-12) regenerated sync PRs whose translated sections were built from #595's merge-time snapshot of the source, not from current source main. Anything the source changed in those sections after #595 — in this case the test_pwt.csv repoint from lecture-python-programming#612 (merged earlier the same day) — gets reverted in the regenerated target content.

Concrete evidence, from the regenerated PRs before any merge: lecture-python-programming.zh-cn#93's only lecture-content change was reverting two already-repointed polars.md reads back to the old own-repo raw URL (a URL scheduled for deletion), and lecture-python-programming.fa#154 carries the same two reversions plus a rewrite of three pandas_panel.md data reads from the github.com/QuantEcon/data-lectures/raw/main/… form to the raw.githubusercontent.com/… form — i.e. whatever URL form the snapshot happened to hold. The French regeneration (fr#34) was clean only because that target had not yet received the newer edits, so its sections still matched the snapshot.

The trap is sharpest exactly when resync is most needed: a queued sync PR conflicts because later source changes touched the same lectures, someone resyncs to regenerate it, and the regeneration quietly re-applies the pre-conflict content the rebase refused to. The failure is silent — the PR looks like a normal retranslation and merges cleanly.

Suggested direction: in resync mode, rebase the source diff onto current source main before translating (or diff old-source-at-PR against current main rather than against the PR's own head), so a regenerated section can never carry source content older than what main serves. A cheaper guard: after generating, diff the code cells (not prose) of the regenerated sections against current source main and fail the run if any code cell differs — code cells are language-invariant, so any mismatch is stale-snapshot content by construction.

The state files regenerated in these PRs share the problem: they record hashes against the stale snapshot, so merging one also corrupts the baseline the next sync diffs against.

---

Fallout ledger (2026-08-19, measured)

Triage: labeled bug + high-priority; W1 (#259) carries a deterministic detection box for this; the regeneration repair stays here. Operating rule until it lands: do not use \translate-resync. Superseded 2026-08-20 — see the ruling comment below. The blanket moratorium is replaced by a measured precondition: \translate-resync is permitted only when git rev-list --count <mergeSha>..origin/main -- <path> is 0 for every file in the source PR (not just the file named in a failure issue). The documented recovery route also moves off resync onto the CLI (translate forward -f / init -f), which reads source off the local filesystem and cannot exhibit this defect.

Method: for all 21 state files across the three targets (7 lectures × 3), the recorded source-sha was compared against the source repo's true last-touch commit for that lecture, plus content probes for each #595/#612 edit (the PyTorch casing fix, the DiscreteRV seed docstring, qe.Timer mentions, and the data-read URL forms). Reference commits on source main: d35eb831 = the #595 batch (last touch for about_py, autodiff, numpy, pandas_panel, python_by_example), 55c87c9f = the #612 repoint (last touch for pandas, polars).

target	state vs source	content	verdict
zh-cn	all 7 match	seed docstring localized ✓ · pandas_panel raw.githubusercontent form ✓ · polars/pandas URLs ✓	Fully consistent, nothing outstanding. The original batch PR (#89 there) merged at 03:11 before the repoint; the stale regeneration (#93) was correctly closed unmerged.
fr	6 of 7 match; numpy records a2b929f1 (2026-05-13) vs actual d35eb831	numpy is missing both #595 edits: docstring still the pre-#595 text, 2 of 3 qe.Timer mentions	numpy.md never received #595. The original batch PR (#30) was closed unmerged and the regeneration (#34) silently omitted the file. State is honest — it flags numpy as pending.
fa	pandas and polars record d35eb831 vs actual 55c87c9f — the regeneration overwrote the repoint sync's correct state; about_py records 3213613a (2026-05-09, pre-dates this incident)	lectures current except pandas_panel: three data reads carry github.com/QuantEcon/data-lectures/raw/main/… while source at its own last touch uses raw.githubusercontent.com/QuantEcon/data-lectures/main/…	Two stale state files (effect: isSourceChanged over-reports — the fail-safe direction) plus a three-line pandas_panel divergence introduced by the #155 restore, which restored a URL form the source itself had moved off. fa about_py is effectively current in content (PyTorch ×3 already correct); its ordinary pending-state heals on the next organic touch.

Corrections to this issue's original account, from the measurement: (1) the pandas_panel rewrite in fa#154 was correct sync content, not snapshot damage — the #595 batch itself moved the source's URL form to raw.githubusercontent, and the hand-restore then overcorrected it; (2) state files record a per-file source-sha (a commit id), not content hashes, and the stale values sit on the fail-safe side — tools over-report staleness rather than mask it; (3) the incident has a second mechanism, distinct from the stale snapshot: a regeneration can silently drop a file of the PR it replaces (fr numpy), which feeds W1's declared-vs-delivered assertion directly.

Repairs — merged and verified 2026-08-19 (both deterministic, no re-translation). The fallout is fully remediated; what stays open here is the bug itself.

• fa: restored .translate/state/pandas.md.yml and .translate/state/polars.md.yml to the repoint sync's versions (source-sha: 55c87c9f…), and reverted the pandas_panel half of the Decide whether positionCorrect should be deterministic — #148's deliberate residual, now measurable #155 restore (three URL lines back to the source's raw.githubusercontent form). Landed via Repair the #154 regeneration residue: repoint state for pandas/polars, pandas_panel URL form lecture-python-programming.fa#158 (merge 905bab7f, 03:33Z). Post-merge byte-check on main: both state files record 55c87c9f, pandas_panel raw.githubusercontent ×3.
• fr: ported #595's two numpy edits by hand — the docstring addition verbatim (fr keeps docstrings in English) and the one prose sentence (tic/toc → qe.Timer()), advancing numpy's state to d35eb831. forward was not used, deliberately: numpy.md is one of the two natively-reviewed fr lectures (fr#24) and whole-file regeneration would discard the review. Landed via Port the numpy.md edits the resync regeneration dropped (seed docstring, qe.Timer) lecture-python-programming.fr#38 (merge 4eb56d6e, 03:33Z). Post-merge byte-check on main: seed docstring present, qe.Timer ×3 (matching fa/zh-cn), state records d35eb831.

Post-merge, the recorded-vs-actual mismatch set across all 21 state files is zero, modulo fa about_py's benign pre-incident pending-state, which self-heals on the next organic touch. Still open on this issue: the regeneration repair. Re-specified 2026-08-20: compare the source snapshot against current source main — English against English, one repos.compareCommits call over the PR's file set — and fail closed on drift, rather than comparing the regenerated target's code cells against source (which is dominated by legitimate localisation divergence). Note a naive move to current main re-opens the inverse defect that #44 repaired; a correct fix splits the pair, base at merge_commit^ and head at main.

Design note for the W1 guard, measured on numpy.md: code cells are not wholly language-invariant — fa and zh-cn localize docstrings and comments inside code cells; fr keeps them English. The invariance check must strip comment/docstring lines or key off the per-language code-comments rule.

[mmcky]

Second trigger path for this defect, and a worse symptom: automatic mode: rebase, not just \translate-resync. Observed 2026-08-19 on lecture-python.zh-cn at engine @v0 = v0.26.0.

The setup matches this issue's description exactly. lecture-python.zh-cn#255 carries the style-guide regeneration of likelihood_bayes.md, built from source snapshot 07975d5 (a source commit dated 2026-08-05). Separately, lecture-python.zh-cn#248 merged the Generator API refactor for the same lecture, from source 06c784f (2026-08-12) — a descendant of 07975d5. When #248 merged, rebase-translations.yml fired and force-pushed #255's branch, regenerating from the older snapshot.

The difference from the lecture-python-programming case in the report above is the outcome. There the regenerated content was stale but valid. Here the rebase reverted the refactor partially, leaving a file that cannot execute at all:

Site	Rebase output	Consequence
line 80	@jit def set_seed(): np.random.seed(142857) restored, deleting rng = np.random.default_rng(142857)	rng is first used at line 185 but now only defined at line 493 — NameError
line 784 / 902	def create_table(π0s, rng, ...) kept, call reverted to create_table(list(...), N=10000, T=500)	required positional argument missing — TypeError
line 944	compute_cond_var(π, rng) correctly threaded	the same refactor is applied at one call site and reverted at another, in one file

So the regeneration is not a clean revert to the snapshot, which would at least be internally consistent — it interleaves snapshot content with post-snapshot content and produces a file that is coherent at neither state. It also un-translated a code comment back to the source English (# 生成蒙特卡洛抽样 became # Create Monte Carlo draws) and dropped the CJK spacing before two {doc} and {eq} roles.

Two further notes for whoever picks this up:

The force-push overwrote a correct hand resolution of the same conflict that had been pushed to the branch minutes earlier, so the failure mode is not only "stale content wins over newer target edits" but also "regenerated content wins over a human's conflict resolution". Recovery was to merge the automation's head and keep the hand resolution, adopting the three genuine prose improvements the regeneration did produce.

The .translate/state synced-at field is actively misleading when reconciling this by hand: #255's state read synced-at: "2026-08-18" against source 07975d5 (2026-08-05), while main's read synced-at: "2026-08-12" against 06c784f (2026-08-12) — so the state that looked newer pointed at the older source commit. git merge-base --is-ancestor on the two source SHAs is the only reliable ordering, and taking the wrong side would tell future syncs to re-deliver work already applied.

Filed alongside this: #280 covers a separate rebase-mode defect from the same night, where the force-push auto-closed two open sync PRs outright.

[mmcky]

The moratorium is blocking every documented recovery in the estate — 15 issues plus one lost lecture

Recording an operational consequence found while re-verifying project-translation#37, because it raises this issue's urgency beyond the content-revert damage it was filed for.

The engine files a translation-sync-failure issue on the source repo whenever a sync run errors. Fifteen are open right now, every one with zero comments, oldest 2026-07-23:

Source repo	Open failure issues
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

Every single one ends with the same instruction: "Once the issue is resolved, comment \translate-resync on PR #N to retry." That is the route this issue's moratorium forbids.

So the estate is in a state where its only documented recovery path for a failed sync is unavailable, and has been since the moratorium was added to this issue's body on 2026-08-19 (the issue itself was filed 2026-08-18). Nothing surfaces that: the failure issues sit quietly, and the "sync backlog = 0" figure the programme tracks counts open sync PRs, which structurally cannot see a run that failed before a PR existed. Three of the fifteen (lecture-python-programming 613, 614, 615) were filed 2026-08-18, inside the drain that produced the zero.

There is now a sixteenth case with no route at all. On 2026-08-19, lecture-python-intro#839 merged lectures/mobility.md and no pull_request sync run was created for that merge — not failed, not skipped, not parked: absent, with every trigger condition satisfied and the analogous #837 having fired 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 it — so it reads as an Actions dispatch gap rather than a defect in this engine. No failure issue exists for it because nothing ran, so the lecture is undelivered with no artefact anywhere. Its recovery is also \translate-resync.

None of this argues the moratorium was wrong — the fa/fr damage was real and the stale-snapshot mechanism is unfixed. It argues that the moratorium has a cost that is now larger than it looks, and that lifting it, narrowing it, or providing a substitute route (a resync that regenerates from current main rather than the merge-time snapshot) has become the load-bearing decision rather than a nice-to-have. Being raised as the lead item on the programme's current work plan.

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

[mmcky]

Ruling: the moratorium is replaced by a measured precondition, and \translate-resync stops being the documented recovery

Two things in one comment — a correction to my 2026-08-19 comment above, which overstated the cost of holding, and the ruling that follows from re-measuring it.

Correction: "15 blocked recoveries" was about 4× the real number

My earlier comment said this moratorium blocks "every documented recovery in the estate — 15 issues plus one lost lecture". Re-measured against live state, that is wrong in two ways.

The 15 issues collapse to 8 distinct (lecture, target) units, and only 4 are outstanding. Comparing each target's .translate/state/<file>.md.yml source-sha against the source repo's true last-touch commit:

Unit	State	Issues
phillips_lost_conquest → lecture-python.zh-cn	current (3fc4e2ab)	myst 993 — stale
fitting_distributions → lecture-intro.zh-cn	current (1a4e5efc)	intro 817 — stale
numpy → …programming.fr	current (d35eb831, via the fr#38 hand port)	prog 606, 609, 613 — stale
pandas/polars → …programming.fa	current (55c87c9f, via fa#158)	prog 615 — stale
learning_approximation → lecture-python.zh-cn	file absent	myst 1004, 1007
hoist_failure → lecture-python.zh-cn	behind (dd9fd019 vs a7aafd5b)	myst 1028
prob_dist → lecture-intro.zh-cn	behind (6c607ded vs ebff90fd)	intro 812, 818, 820, 822
about_py → …programming.fa	behind (3213613a vs d35eb831)	prog 610, 614

Six of the fifteen are stale bookkeeping, closeable today with no engine change and no resync.

And for 13 of the 15, resync would not have worked anyway. They are all structural-parity failures, and the retry reproduces them exactly. Issue prog#609 was filed by the original pull_request run at engine v0.25.0; prog#613 was filed by the \translate-resync retry at v0.26.0 — and their bodies are byte-identical: same directive count (145 vs 144), same 35 violations, same line numbers. The parity guard shipped in v0.20.0, before all fifteen issues, and nothing in v0.24/25/26 touches section-splice generation. For those cases the engine is the blocker; the moratorium is not.

So the honest cost of holding is four lectures, not sixteen. That is the number the ruling is made against.

Why the moratorium is still the wrong instrument

It does not close the exposure. mode: rebase carries the identical defect — rebaseSinglePR reads metadata.sourceCommitSha from the PR body and fetches source content at that SHA and ${sourceCommitSha}^, the same frozen snapshot — and rebase-translations.yml is installed and active on all five target repos, firing automatically on every merged sync branch with nobody typing anything. It produced 44 non-skipped runs on 2026-08-18/19 and the worse symptom recorded in the comment above: a likelihood_bayes.md that raises NameError then TypeError. It is dormant today only because there are zero open translation PRs anywhere, and it re-arms the moment two sync PRs are open at once. gh run rerun is a third door onto the same frozen SHA.

So the moratorium restrains the deliberate, supervised path while leaving the unsupervised one armed.

And "wait for the W1 guard" does not deliver what it promises. #259's box is prevention, which is right, but it is code-cell-only and the box itself says the repair "stays with #276, which remains open past this phase". Worse, as specified it compares the regenerated target against source main — a comparison dominated by legitimate divergence. Measured across six lectures and three editions, comment-stripping is not enough: zh-cn pandas_panel shows 21 differing code lines from injected i18n font config, localised figure labels and #107 target-local reads. A guard that fires on every mpl.rcParams['font.family'] line gets switched off within a week. It also misses prose-only staleness entirely, which is 14–38% of source lecture edits.

The ruling

1. The blanket moratorium is lifted and replaced by a precondition (@mmcky, 2026-08-20). \translate-resync may be used only when the source has not advanced on any file in the PR since it merged:

gh pr view <n> --repo QuantEcon/<source> --json files --jq '.files[].path'
git rev-list --count <mergeSha>..origin/main -- <each path>

All zero ⇒ permitted. Any non-zero ⇒ refused. Note the risk surface is the PR's entire changed-file set, not the file named in the failure issue: myst#993 names one lecture but would regenerate ten; myst#1004 names one but would regenerate eighteen.

Validated against the known-bad case: for prog#595 the check returns non-zero on pandas.md and polars.md (advanced by lecture-python-programming#612) and zero on the other five — flagging exactly the file that was damaged, and correctly not flagging pandas_panel.md, which this issue's own ledger later established was legitimate sync content rather than damage.

Current tally across the backlog: 7 of 16 items pass, 9 fail. Nine of the twelve distinct source PRs have drift.

2. \translate-resync stops being the documented recovery. The failure-issue template's Recovery block should point at the CLI instead. translate forward and translate init are structurally incapable of this defect — neither consults a source PR or a merge SHA at all; both read the source document off the local filesystem (forward.ts and init.ts resolve path.join(sourceRepoPath, docsFolder, file) and fs.readFileSync), so whatever the clone is checked out to is what gets translated, and their parity check is anchored to current main rather than to the snapshot. Two constraints on the substitute:

• init -f only for an absent lecture. It ends with a bare fs.writeFileSync and no existence check, so on a lecture that already has a translation it discards every human edit and native review in it.
• Never regenerate a natively-reviewed lecture. numpy.md and python_by_example.md on fr are Emile's only reviewed lectures; whole-file regeneration would destroy the one thing project-translation#3 is waiting on. That is why fr#38 was hand-ported rather than forwarded.

3. The repair is re-specified: compare source against source, not target against source. Instead of comparing the regenerated target's code cells against source main, compare the source snapshot against current source main — English against English — over the PR's file set, and fail closed on any drift. One repos.compareCommits call, no language sensitivity, no localisation false positives, and it catches prose staleness that a code-cell comparison cannot. This dominates both this issue's own suggestion (b) and #259's box as written; I will raise the box rewrite on #259.

Note for whoever implements it: the merge-time snapshot was introduced deliberately by #44 (commit 330b8d6, 2026-03-24), which repaired the inverse defect — its message records that github.context.sha points at HEAD of the default branch, so oldContent and newContent could both reference the current main tip and the diff detector would miss the PR's own changes. A naive revert to current main re-opens that. A correct fix splits the pair — base stays at merge_commit^, head moves to main — and must account for the blast radius being wider than changed sections: file-processor.ts:115-122 copies config and preTitle from the snapshot unconditionally, and the state file records the snapshot SHA as provenance.

Also worth knowing: the resync path has zero test coverage, unit and E2E alike, which is why this class survived from March to August. A stale-resync scenario (merge PR A, merge PR B touching the same section, resync A) needs to exist before any fix ships.

One reframing of this issue's scope

The "second mechanism" recorded in the ledger above — a regeneration silently dropping a file of the PR it replaces (fr numpy.md) — is not resync-specific and is not silent. Issue prog#613 records the parity failure loudly; what is silent is that index.ts:794 gates PR creation on translatedFiles.length alone with no hasErrors guard, so fr#34 shipped and merged with 6 of 7 lectures and no indication anything was missing. That is #259 box 2 ("Partial PRs still ship on failure") and it fires on ordinary merge syncs too. It should not be counted as a second reason the resync repair must land.

Immediate consequence

The four outstanding units get routed off resync entirely; I will comment the specific route on each. The six stale issues get closed. And mobility.md (lecture-python-intro#839), which had no route at all, turns out never to have needed one: git diff d7670896..origin/main is empty, so snapshot and main are the same tree, and the target has no counterpart to overwrite — it is a first translation, so this defect cannot fire on it.