qeld Q1: build_audit.py must learn the qeld.url() call form before any lecture adopts it #88

Activity

1. mmcky

   changed the title [-]classify_url does not recognize the final data.quantecon.org host — the audit breaks at the Phase 4 cutover[/-] [+]qeld Q1: build_audit.py must learn the qeld.url() call form before any lecture adopts it[/+] on Sep 29, 2026
2. mmcky commented on Sep 29, 2026

   

   mmcky

   on Sep 29, 2026

   ContributorAuthor

   More actions

   Re-scoped on 2026-09-29 to qeld phase Q1, and kept open. Decided in the close-out of the datasets migration.

   What this issue asked. Filed on 2026-08-14: classify_url in scripts/build_audit.py knows only the six GitHub URL forms, so a read from data.quantecon.org/lectures/<file> or quantecon.github.io/data-lectures/lectures/<file> classifies as external-web, and a final record would fail the strict audit. It proposed counting both hosts as data-lectures before the first consumer moved to the final URL in the #15 cutover.

   D11 had already retired that cutover. D11 (PLAN-QELD-PACKAGE.md §2.2, recorded in #76 on 2026-08-12) deferred data.quantecon.org indefinitely and made the qeld package the stable interface instead. #15 closed as not planned the same day, two days before this issue was filed. The audit should learn neither host. The domain is deferred, and quantecon.github.io is not a consumer form: AGENTS.md allows only the two raw forms for code reads, and D11 rules it out as qeld's base because attaching a custom domain to the Pages site would start redirecting it. Counting it as migrated would let a lecture adopt it with the audit green. If #37 is ever revived, the change is one minor qeld release, not an edit to the lecture code this audit scans.

   What still holds, measured 2026-09-29. This issue's structural point survives D11 in a new form: the audit has to learn the terminal form before any consumer adopts it (PLAN-QELD-PACKAGE.md §7). The terminal form is now a call, not a host, and the audit does not know it. I ran a copy of scripts/build_audit.py from ab9d24d (main on 2026-09-29) over the real long_run_growth.md from QuantEcon/lecture-python-intro@2a15be2 and QuantEcon/lecture-wasm@669c65f, against this repo's manifests and migration.yml, where mpd2020.xlsx is repointed. The qeld variants change one line per lecture, in place as §4.1 prescribes, to data_url = qeld.url('mpd2020.xlsx'). It ran offline on copies; no lecture repo changed.

   long_run_growth.md reads mpd2020.xlsx via	Pattern recorded	Strict audit on mpd2020.xlsx
   the URLs on main (control)	data-lectures in both repos	no problem
   qeld.url('mpd2020.xlsx') in intro only	local-path in intro, data-lectures in wasm	"mpd2020.xlsx: marked repointed but consumers still read via ['local-path']"
   qeld.url('mpd2020.xlsx') in both repos	local-path in both repos	the same problem

   The call never reaches classify_url: scan_repo picks up the quoted filename as a candidate and records any candidate that is not an http(s) URL as local-path (build_audit.py:250-286). A dataset is fully migrated only when every read is data-lectures (:401-403), so the first lecture to adopt qeld would take its dataset out of the migrated count and turn the strict audit-dashboard build red (:441-448): the Pages deploy is skipped and the workflow opens its audit-drift issue.

   Scope now: qeld Q1, as PLAN-QELD-PACKAGE.md §7 has worded it since D11:

   • build_audit.py learns qeld.url('X') as pattern qeld, counted as migrated and terminal. Since the call never reaches classify_url, the change goes into scan_repo's candidate handling.
   • For pattern qeld, the audit asserts that the key exists in lectures/ and is not deprecated. The assertions Audit: fail strict on wasm reads via the github.com/*/raw/ URL form #48 and Audit: assert on the media host, and on data-lectures URL resolvability #55 added (:465-522) all work on a parsed URL, which a qeld call does not have.
   • In migration.yml, final comes to mean that every code read goes through qeld, with the §4.1 carve-outs terminal on the direct form. At ab9d24d, final and repointed share one check (:441), so final asserts nothing beyond repointed.
   • Gate: on the lecture repos as they stand, audit.json stats and problems come out unchanged.

   Why it stays open, and where it belongs. It is the prerequisite that stops qeld adoption from turning the strict audit red, so it has to land before the first lecture adopts qeld. It is not a datasets-migration item: the static migration finished on 2026-08-18 with all 40 datasets repointed, and PLAN-QELD-PACKAGE.md says the migration completes with or without qeld. It belongs to qeld, which was also ruled on 2026-09-29 to become its own proposed project, qeld-package, in QuantEcon's project registry, shown on the projects dashboard, beside #66 (qeld's open decisions) and #37 (the deferred domain). Nothing is scheduled yet: the project has no tracker, and at 05:42 UTC on 2026-09-29 there was no qeld repository, packages/ directory or PyPI release.

   The body is kept as written, as the record of the original proposal, with a one-line note at the top pointing here.