[Tracker] 2026-06-02 issue triage — 7 open

[jakebromberg]

End-of-day triage of all 7 open issues in this repo. Intended as the entry point for any contributor or agent picking up after 2026-06-02: where to start, what blocks what, which issues are obsolete, and which proposals overlap.

This repo is the API-contract source of truth for the org: api.yaml drives TS codegen (consumed by Backend-Service + dj-site via @wxyc/shared on GitHub Packages), Python codegen (consumed by request-o-matic + library-metadata-lookup), and Swift/Kotlin codegen (locally scripted; consumer migrations pending). It also publishes the reusable check-charset-corpus-drift.yml workflow on the moving gha/v1 tag.

P0 sequencing — recommended order

1. Close setup-dev-environment.sh assigns same port to backend and auth #66. Already fixed in commit e6ac42a (2026-05-19); PR fix: setup-dev-environment.sh assigns same port to backend + auth when defaults are taken (subshell loses RESOLVED_PORTS) #136 closed but setup-dev-environment.sh assigns same port to backend and auth #66 stayed open. No work needed beyond the close.
2. One nullability sweep PR covering AlbumSearchResult declares label (and others) as required but the wire emits nulls #140 + Mark AlbumSearchResult.on_streaming (and peers) as nullable to match documented behavior #127. Add nullable: true to every AlbumSearchResult / LibraryAlbumResponse field whose description says "Null if unknown" or whose backing column is nullable. oasdiff will flag breaking; coordinate a major-version bump and fan out to consumers (Backend-Service AlbumSearchResultRow type fix in apps/backend/services/library-search.service.ts, dj-site selectors, Python decoders in rom + LML, iOS already lenient via decodeIfPresent).
3. Enforce release tag PR for every api.yaml schema change #105 re-scope, then implement. Drop the publish-tag complaints (already implemented via publish.yml + recent inline version-bump commits) and re-scope to the three real gaps: (a) CI gate failing api.yaml change without package.json bump, (b) CI gate enforcing the dist/ + generated-artifact policy (decide whether dist/ is committed or generated-on-tag), (c) tag automation on merge.
4. Add Python codegen script alongside TS / Swift / Kotlin #107 finish + downstream migration. generate:python already exists in package.json; commit the output, pin datamodel-code-generator in this repo's tooling, then file the two consumer PRs against LML and rom to delete their local scripts.
5. Add Swift and Kotlin codegen for mobile consumers #106 re-scope. Title misleads — generate:swift + generate:kotlin already exist in package.json. The real gaps are CI parity (currently only generate:typescript runs in CI), consumer migration of wxyc-ios-64 / library-scanner / WXYC-Android off hand-rolled DTOs, and a real publish channel (Swift package / Maven artifact) since the codegen targets local-only paths like ../wxyc-ios-64-copy/.
6. Audit and fix naming inconsistencies in api.yaml #27 — long tail. Big naming-audit refactor with no traction in 2.5 months. Pick up only when bandwidth allows; could be a good first-issue split if scoped per-naming-class.

Critical / high severity

• HIGH: AlbumSearchResult declares label (and others) as required but the wire emits nulls #140, Mark AlbumSearchResult.on_streaming (and peers) as nullable to match documented behavior #127 (production decoder-drift risk; iOS already papered over once)
• HIGH-was, MED-now: Enforce release tag PR for every api.yaml schema change #105 (re-scoped — most of the safety net is in place; the open work is belt-and-suspenders CI gates)
• MED: Add Swift and Kotlin codegen for mobile consumers #106, Add Python codegen script alongside TS / Swift / Kotlin #107 (codegen distribution / CI parity)
• LOW: Audit and fix naming inconsistencies in api.yaml #27 (naming audit)
• Recommend close: setup-dev-environment.sh assigns same port to backend and auth #66 (fix shipped)

Cross-cluster conflicts (decide once before starting)

dist/ in-repo vs publish-on-tag

#105 calls for committing regenerated dist/ artifacts in every api.yaml PR. Current practice is: dist/ is committed (last touched 2026-05-28) but the source of truth for downstream consumers is the GitHub-Packages publish triggered by v* tag (publish.yml). Decide once whether dist/ stays committed (and gets a CI gate that diffs it against fresh codegen) or is gitignored and produced only by publish.yml. Either is defensible; the duplication today is the smell.

Major-version bump policy

#140 + #127 widen TS types from non-null to nullable. oasdiff will flag breaking. The repo is currently on 1.x. Two options: (a) cut v2.0.0 and coordinate consumer migrations, or (b) treat the spec as the truth and the prior non-null types as the bug, ship as v1.x with a Notes section documenting the consumer-side fix. (b) is faster but trains consumers to expect silent widening on patch versions. Pick once before opening the PR.

Obsolete / needs-revision (recommend close)

• setup-dev-environment.sh assigns same port to backend and auth #66 — fix shipped in e6ac42a (2026-05-19) matching the proposed approach line-for-line. See per-issue comment #66 (2026-06-02).

Cross-repo dependencies

Issue	Blocked by	Method
#127	#140	native (addBlockedBy) + body ## Blocked by section

Issue	Downstream work (filed in this repo, lands in others)
#107	LML — delete scripts/generate_api_models.sh, invoke this repo's codegen; rom — same
#106	wxyc-ios-64 / library-scanner / WXYC-Android — adopt generated DTOs, retire hand-rolled
#140 / #127	Backend-Service — fix AlbumSearchResultRow in apps/backend/services/library-search.service.ts to match wire (`label?: string
#105	Org-wide — every consumer relies on tag-based publish working; this issue's CI gates reduce the chance of a silent contract regression

Cross-repo runtime risks

• The 2026-04-30 iOS semantic-index decoder drift incident (Decode semantic-index search and neighbors response wrappers wxyc-ios-64#229) is the named precedent for the failure mode AlbumSearchResult declares label (and others) as required but the wire emits nulls #140 / Mark AlbumSearchResult.on_streaming (and peers) as nullable to match documented behavior #127 / Add Swift and Kotlin codegen for mobile consumers #106 are guarding against — hand-maintained decoders silently diverge from the wire.
• check-charset-corpus-drift.yml is consumed by every downstream npm-packing repo via @gha/v1. Any change to it (or to its caller-permissions contract) is high-blast-radius. See CLAUDE.md "Tag Stability Policy" — applies to anything in .github/workflows/.

Cluster map (7 open)

• api.yaml nullability drift: AlbumSearchResult declares label (and others) as required but the wire emits nulls #140, Mark AlbumSearchResult.on_streaming (and peers) as nullable to match documented behavior #127
• Codegen scope / CI parity: Add Swift and Kotlin codegen for mobile consumers #106, Add Python codegen script alongside TS / Swift / Kotlin #107
• Publish-policy hardening: Enforce release tag PR for every api.yaml schema change #105
• Dev-env scripts: setup-dev-environment.sh assigns same port to backend and auth #66 (recommend close)
• Naming consistency long tail: Audit and fix naming inconsistencies in api.yaml #27

Active org projects this repo touches

• wxyc-fastapi rollout (#29) — Add Python codegen script alongside TS / Swift / Kotlin #107 is on this board (Todo). The fastapi rollout is the immediate consumer of a consolidated Python codegen.
• Catalog Track Search (#30) — recently closed series (PRs [Epic] E7 — wxyc-shared api.yaml v1.3.0 (catalog-track-search contract) #110/E6-1: api.yaml additions — write-side + V2 track_position field #111/E7-1: api.yaml v1.3.0 PR — matched_via, TrackMatchHint #112/E7-2: Publish v1.3.0 release tag #113) landed v1.3.0; no open work here.
• Cross-cache-identity (#25) — recently closed series ([E2 step 0a] api.yaml v0.5.0 → v0.6.0: identity block + include_identity flag (BLOCKS E2-BS, E2-LML) #87/[E2 step 0c] LML confidence-threshold review (BLOCKS E2-BS step 1) #88/api.yaml v0.7 — POST /api/v1/identity/bulk-resolve-libraries schema #103) landed v0.6.0 + the bulk-resolve-libraries DTO; no open work here.
• GitHub Actions Supply-Chain Hardening (#31) — none of the current open issues are on this board, but Enforce release tag PR for every api.yaml schema change #105 and the Tag Stability Policy work in .github/workflows/ are adjacent.
• Post-launch service hardening (#32) — none of the open issues are on this board; if a consumer-side AlbumSearchResult nullability fix lands during the hardening project, it'll be a sub-issue of the BS epic, not this repo.

How to find work

• All blocked issues carry a ## Blocked by body section. Only Mark AlbumSearchResult.on_streaming (and peers) as nullable to match documented behavior #127 is currently blocked (by AlbumSearchResult declares label (and others) as required but the wire emits nulls #140).
• Native blocked-by relationships render under the "Relationships" pill in the GitHub UI.
• Per-issue triage commentary is on each issue's page (look for "Triage finding" / "Status update" / "Sequencing concern" comments dated 2026-06-02).
• Open PRs in flight: all four are dependabot (oasdiff-action bump chore(deps): bump oasdiff/oasdiff-action from 0.0.47 to 0.0.51 #154, date-fns chore(deps): bump date-fns from 4.1.0 to 4.4.0 in the production-dependencies group across 1 directory #135, better-auth chore(deps-dev): bump better-auth from 1.6.9 to 1.6.14 in the better-auth group across 1 directory #109, dev-dependencies group chore(deps-dev): bump the dev-dependencies group across 1 directory with 6 updates #95). No human-authored work in flight.

Notes for the next session

• Issue Enforce release tag PR for every api.yaml schema change #105 mentions "api.yaml: add identity block + include_identity flag (E2 step 0a, schema half) #99" — that PR landed and the predecessor tracking work ([E2 step 0a] api.yaml v0.5.0 → v0.6.0: identity block + include_identity flag (BLOCKS E2-BS, E2-LML) #87 → v0.11.0 missing tag) is past. Don't re-litigate that history; treat Enforce release tag PR for every api.yaml schema change #105 as the forward-looking CI-gates ticket only.
• The triage skill found no existing tracker; this is the first. Append to this issue rather than starting a new one when re-running triage.

[jakebromberg]

Superseded by #164 (2026-06-03 triage). The cluster shape is materially unchanged in 24 hours — three issues closed (#157, #160, #162, all shipped as v1.10.0/v1.11.0 during the 2026-06-02 Apple Music Track 1 + Aubrey Hearst on-air recovery), one new issue opened (#156, Discogs-unavailable Album fields under BS#1280 epic). See #164 for current sequencing.