forward/sync don't carry shared assets referenced by lectures — quant-econ.bib and _admonition/* dangle and fail strict builds

[mmcky]

A distinct forward-resync gap surfaced during the intermediate lecture-python.zh-cn resync wave (2026-07-19). It is the mirror image of #107: where #107 is about the resync dropping a target-side adaptation, this is about the resync not carrying across an upstream-side addition to a shared file.

Mechanism

forward resyncs each lecture's .md body — including any new {cite}`Key` directives that upstream added — but does not sync the shared bibliography lectures/_static/quant-econ.bib. When an upstream lecture begins citing a reference that upstream also newly added to its own .bib, the resync brings the {cite} into the target lecture while the key stays absent from the target repo's stale .bib. Under the strict build (-n -W) Sphinx emits WARNING: could not find bibtex key "<Key>", which -W promotes to a hard build failure.

Evidence (4 of 36 lectures in one Tier of the wave)

PR	Lecture	Missing key(s)
QuantEcon/lecture-python.zh-cn#123	likelihood_ratio_process	Blume_Easley2006
QuantEcon/lecture-python.zh-cn#124	likelihood_ratio_process_2	Blume_Easley2006
QuantEcon/lecture-python.zh-cn#164	rational_expectations	Lucas_Prescott_1971 (3 uses)
QuantEcon/lecture-python.zh-cn#171	mccall_persist_trans	MaCurdy1982, Meghir2004

All four keys were present verbatim in the upstream lecture-python.myst quant-econ.bib and absent from the zh-cn copy, confirming the target bibliography is a stale snapshot the resync never updates. Fixed manually this wave by copying the specific entries across.

Why it is easy to miss

A per-lecture content review cannot catch it: a {cite} lives in prose and the key it needs lives in a separate file. There is no execution error either — it is a build-time cross-reference check, so only a cold strict build surfaces it (a cached build can pass and hide it).

Suggested fix, cheapest first

1. Lint (minimum): after resyncing a lecture, extract every {cite}`Key` in the translated file and assert each Key resolves in the target repo's .bib; if not, pull the missing entry from the upstream .bib (or flag it on the PR). Deterministic and would have caught all four pre-merge.
2. Sync shared assets (better): treat _static/quant-econ.bib as part of the resync surface and diff-and-merge new upstream entries when a resynced lecture references them.
3. Generalise (best): a shared-asset drift check — any file a resynced lecture references by name (bib keys, _static/… paths, data URLs) should resolve in the target repo after the resync. This subsumes the bib case and would also catch missing data/image assets.

[mmcky]

A second instance of this class, found today: lectures/_admonition/ shared includes.

This issue is scoped to quant-econ.bib, but the underlying rule — sync moves lecture files, so an asset living outside that set is never carried across — has at least one more surface, and it fails harder than a dangling citation does.

lecture-python-programming.fr was missing lectures/_admonition/gpu.md entirely, while three of its lectures include it:

lectures/autodiff.md:36               CRITICAL: Directive "include": file not found: lectures/_admonition/gpu.md
lectures/jax_intro.md:50              CRITICAL: Directive "include": file not found: lectures/_admonition/gpu.md
lectures/numpy_vs_numba_vs_jax.md:67  CRITICAL: Directive "include": file not found: lectures/_admonition/gpu.md

Those three lectures had been publishing without the admonition, silently, because that repo built without -W. Fixed in .fr#14.

Two observations that may affect how this issue is fixed:

1. The failure is asymmetric across editions, which suggests seeding rather than sync is where the gap opened. .fa and .zh-cn both have the file; only .fr lacked it. A sync-time asset check would not have helped an edition whose initial seed omitted the asset — so whatever check lands here probably wants to run on the full target tree, not only on the files a given sync touched.

2. Presence is not sufficiency. .fa's copy exists but is still entirely in English (fa#138). A strict build cannot catch that — the include resolves, so there is no warning. If the fix here is "assert referenced assets exist", it closes the .fr case and leaves the .fa case open. Worth deciding explicitly whether shared assets should also enter the translation and review path, rather than only the existence check.

Suggested widening: treat this issue as shared assets referenced by lectures are not synced, with quant-econ.bib and _admonition/*.md as the two known members, and glob {include}/{cite} targets that resolve outside the synced file set as the discovery mechanism.

[mmcky]

Data point from the zh-cn full gap-fill (QuantEcon/lecture-python.zh-cn#196): init has the same gap as resync — 37 seeded lectures cite 144 keys, none guaranteed present in the target bib (the target was missing 113 of them before a manual source-bib sync). Also note the source bib itself can be incomplete: three of the 144 were dangling upstream too (QuantEcon/lecture-python.myst#990), so the fix ladder's first rung (lint unresolved keys) would pay off in the source repos as well as the editions.

[mmcky]

First production instance on the sync path — and the first one to break a live build.

The two data points above are from forward (the 2026-07-19 resync wave) and init (the zh-cn gap-fill). QuantEcon/lecture-python.zh-cn#202, the first organic sync on v0.23.0, hits the same gap through the Actions sync path, at a scale that makes the build unrecoverable rather than merely warning-noisy.

Upstream QuantEcon/lecture-python.myst#992 changed thirteen files. The sync workflow watches lectures/**/*.md and lectures/_toc.yml, so two of them were never candidates to cross:

Upstream file	Consequence in the target
lectures/_static/quant-econ.bib	57 distinct could not find bibtex key warnings, fatal under -W
lectures/_static/lecture_specific/phillips_drifts_volatilities/NEWQDATA.csv	the lecture raises FileNotFoundError by design when the file is absent

The data-file surface is worth naming separately

The CSV case is a third surface alongside quant-econ.bib and _admonition/*, and it fails differently from both: not a dangling cross-reference but an execution failure, which then cascades into a reference failure. phillips_drifts_volatilities.md resolves the asset directory and raises explicitly if the file is missing:

    relative = Path('_static/lecture_specific/phillips_drifts_volatilities')
    ...
    raise FileNotFoundError(f'NEWQDATA.csv was not found; searched {searched}')

The cell that would have produced fig-csdv-inflation-persistence therefore never runs, and the build separately reports undefined label: 'fig-csdv-inflation-persistence' from the {numref} 1300 lines later. Both the definition and the reference are present and correctly translated in the target file — the label is undefined only because the data it depends on never arrived. Rung 3 of the fix ladder ("any file a resynced lecture references by name … should resolve in the target repo") covers this; rungs 1 and 2 do not.

The bib drift is chronic, not incidental to this PR

Comparing the two bibliographies as they stand today:

	keys
lecture-python.myst	472
lecture-python.zh-cn	405
upstream keys absent from the target	70

So the target bibliography is not slightly behind, it is 70 entries behind, and it only ever fails when a newly-synced lecture happens to cite one of the missing keys. Every future upstream PR that adds a citation is a build-broken sync PR until this is fixed; #202 is simply the first one to add enough of them at once to be impossible to miss.

[mmcky]

Cross-link: #157's proposed reachability check is also this issue's detector.

#157 proposes a deterministic diffCheck — every _toc.yml entry and every {doc}/{cite} introduced by the diff must resolve against target-repo ∪ PR. A {cite} whose key is absent from the target's stale .bib is precisely that check failing, so the two issues are complementary rather than overlapping: #157 is detection at review time (the PR gets flagged instead of merging into a red build), this issue is repair (carry the referenced assets so the situation does not arise).

Worth building in that order if they are scheduled apart — the detector is cheap and stops the silent case, which is the worse half here given three lectures published without their admonition and nobody noticed.

[mmcky]

Field instance three, 2026-08-07 — exactly the predicted mechanism, eleven days after the last adoption. Upstream's citation-adding PRs (Tom's edits) produced sync PRs citing keys the edition bib lacked: 17 distinct keys on lecture-python.zh-cn#230, ~10 more on #231, both previews fatal under -W. Repaired both times by wholesale adoption of the source bib after a strict-subset check (501 ⊂ 537, zero target-only keys). The 2026-07-27 adoption closed the gap, not the mechanism, and it re-fired on schedule: until sync carries bibliography deltas (or editions track the source bib automatically), every citation-adding source PR is a guaranteed red preview on every zh edition.