Normalize the 14 charset-drift callers: wxyc-shared-ref, @main pins, permissions, corpus pin

[jakebromberg]

Problem

The 14 callers of check-charset-corpus-drift.yml have drifted apart along four independent axes. Every one currently passes, so nothing is broken — but "pinned to gha/v1" is not presently a true statement about what most of them run, and the inconsistency will produce a confusing incident eventually.

Full fleet as of 2026-08-07 (enumerated by walking .github/workflows/ in all 54 WXYC repos via gh api; gh search code returns only 6 of these and is not a valid enumeration method here):

Consumer	uses: ref	wxyc-shared-ref	permissions:	pinned-sha256 / package-version
Backend-Service	@gha/v1	gha/v1	contents+packages read	41a18c5c / 0.12.0
dj-site	@gha/v1	gha/v1	contents+packages read	41a18c5c / 0.12.0
library-metadata-lookup	@gha/v1	gha/v1	contents+packages read	41a18c5c / 0.12.0
semantic-index	@gha/v1	gha/v1	contents+packages read	41a18c5c / 0.12.0
tubafrenzy	@gha/v1	gha/v1	contents+packages read	41a18c5c / 0.12.0
discogs-xml-converter	@gha/v1	gha/v1	contents+packages read	41a18c5c / 0.12.0
wxyc-etl	@gha/v1	gha/v1	contents+packages read	41a18c5c / 1.6.0
musicbrainz-cache	@gha/v1	gha/v1	contents+packages read	75a3395b / 0.10.0
catalog-audits	@gha/v1	gha/v1	contents+packages read	75a3395b / 0.10.0
discogs-etl	@gha/v1	gha/v1	contents+packages read	75a3395b / 0.10.0
request-o-matic	@gha/v1	unset → main	contents+packages read	41a18c5c / 1.6.0
wikidata-cache	@gha/v1	unset → main	contents+packages read	41a18c5c / 1.6.0
archive	@main	unset → main	none declared	75a3395b / 0.10.0
wxyc-archive-search	@main	unset → main	none declared	75a3395b / 0.10.0

The four axes

1. wxyc-shared-ref unset in 4 repos. This input selects which tree the reusable workflow checks out to get scripts/check-corpus-drift.sh, and it defaults to main. So request-o-matic, wikidata-cache, archive and wxyc-archive-search run tagged YAML against main's script. Harmless today only because that script happens to be byte-identical at gha/v1 and main. The moment it isn't, four repos silently run unreleased logic while their config says gha/v1.

2. Two repos pin @main outright. archive and wxyc-archive-search bypass the tag entirely. Note this cuts both ways: archive being on @main is what made it a usable canary for the actions/checkout@v7 bump (see #319), so the fix is not "nobody may track main" — it is that tracking main should be a deliberate, documented choice rather than the result of nobody repointing them.

3. Two repos declare no permissions: block. archive and wxyc-archive-search grant the workflow-default token scope. They pass today, but CLAUDE.md's caller-permissions contract requires contents: read + packages: read, and the documented failure mode when the intersection narrows is an opaque 401 from npm pack with the message suppressed by --silent — the 2026-05-12 → 2026-05-14 org-wide drift outage. These two are one default-permissions change away from that.

4. Corpus-pin and package-version drift. Five repos sit on 75a3395b / 0.10.0 while the rest are on 41a18c5c / 0.12.0+. Whether that matters depends on what the pin is asserting; it should at least be a decision rather than sediment.

One likely-dead workflow

wxyc-archive-search's last charset run was 2026-07-13 04:31 PDT, before the v7 bumps landed. The repo has gone quiet and GitHub auto-disables scheduled workflows in inactive repos. It should be re-enabled or retired, not left as a caller that never fires — an inert caller is indistinguishable from a passing one on a dashboard.

Desired end state

Every caller's configuration is a deliberate statement. Where a repo tracks main, that is written down and intentional; where a repo pins the tag, it pins the tag for both the YAML and the script; every caller declares the permissions the contract requires.

Suggested approach

Per-repo PRs, each tiny. Sequence after the gha/v1 move in #319/#323 lands and is verified, so callers are not repointed at a tag that is about to move under them.

1. Set wxyc-shared-ref: gha/v1 in request-o-matic and wikidata-cache — or drop the input from all 14 if tracking main's script is the intent. Pick one and apply it uniformly; the current split is the actual problem.
2. Repoint archive and wxyc-archive-search to @gha/v1 and add the contents: read + packages: read block. If keeping one on @main as a deliberate canary, leave a comment in the workflow saying so and why.
3. Decide on the corpus pin / package version spread; align or document.
4. Re-enable or retire wxyc-archive-search's schedule.

Constraints

• Verify each repo's next run after changing it. These are scheduled workflows; a broken caller is silent until its cron fires, which for most of the fleet is weekly.
• Do not batch all 14 into one sweep. The value here is low and the blast radius of a wrong uniform edit is 14 repos.
• If Split gha/v1 into per-workflow tags: one tag now covers two independent contracts #326 (per-workflow tags) lands first, repoint to charset/v1 instead of gha/v1 and skip the intermediate step.

Acceptance criteria

• Every caller either sets wxyc-shared-ref explicitly or the input is gone from all callers.
• No caller pins @main unintentionally; any that does carries a written reason.
• Every caller declares contents: read + packages: read.
• wxyc-archive-search's workflow is confirmed running or deliberately retired.
• Corpus pin / package version spread is aligned or its variance is documented.
• Each changed repo has one green post-change run, not just a green PR.

Related

• api.yaml merges silently strand the Python consumers: their codegen check resolves this repo's main at run time #319, Pin the Python codegen spec ref and add a drift-detection workflow (#319) #323 — where the fleet was enumerated
• Deploy workflows blocked by GITHUB_TOKEN permissions mismatch since a66ed7c Backend-Service#857 — the caller-callee permission narrowing trap

[jakebromberg]

Sequencing gate cleared: the gha/v1 move is live-verified

This ticket's constraint was "sequence after the gha/v1 move in #319/#323 lands and is verified, so callers are not repointed at a tag that is about to move under them." That gate is now met, by observation rather than inference.

referenced_workflows on a run records the SHA the tag actually resolved to at dispatch. Two consumers have green post-move runs:

Consumer	Run time (PT)	Resolved gha/v1	Result
Backend-Service	2026-08-07 18:33:52	b23dc58	success
request-o-matic	2026-08-07 18:37:01	b23dc58	success

Backend-Service is the stronger of the two: it already sets wxyc-shared-ref: gha/v1, so it exercised the tagged script as well as the tagged YAML. request-o-matic covers the other half — tagged YAML against main's script, the configuration axis 1 below is about.

The remaining consumers still show 1858cba only because they have not run since the move, not because anything is failing. Rollback (git tag -f gha/v1 1858cba) is no longer on the table.

Verification recipe, for the rest of the fleet as they land:

gh api repos/WXYC/<repo>/actions/runs/<run-id> --jq '.referenced_workflows'

Axis 1 progress: request-o-matic

WXYC/request-o-matic#236 sets wxyc-shared-ref: gha/v1, leaving wikidata-cache, archive, and wxyc-archive-search. Per this ticket's "do not batch all 14 into one sweep," it is one repo and one line.

Two notes from doing it:

The change verifies itself. .github/workflows/charset-corpus-drift.yml is inside its own pull_request paths filter, so the edit triggers the job it edits. The PR run resolved b23dc58 and passed. Any repo whose caller file is similarly self-filtered gets free verification; that satisfies this ticket's "verify each repo's next run after changing it" constraint without waiting a week for a cron.

Expect unrelated red in request-o-matic. Its Codegen Freshness job is gated if: github.event_name == 'pull_request', so it is skipped on every push to main and only fires on PRs — meaning the first PR opened after an upstream api.yaml change wears a drift failure it did not cause. #236 is that PR. It is pre-existing, it is WXYC/request-o-matic#218's scope, and main is not branch-protected so nothing is blocked. Anyone picking up the other three repos should expect the same shape and not try to fix it in a workflow-pin PR.