Musicbrainz

2026.08.05.2

Fixes music-wanted-sequence-not-wired. model.version and manifest.yaml move 2026.08.05.1 -> 2026.08.05.2.

Breaking change: sync-artist-discographies no longer falls back to a cached search result

Before this change, running sync-artist-discographies with no artistMbids argument silently fell back to the artists cached by this instance's last search-artist run — an implicit dependency on the search resource, whose writer is five different methods with incompatible shapes. Live, that produced a one-artist "successful" sync with no error at all. The method now throws immediately when artistMbids is absent or empty, naming the runnable command: swamp model method run <name> sync-artist-discographies --input 'artistMbids:json=["<mbid>","<mbid>"]', plus the swamp data query extraction command (and its envelope shape — {"results": [[...]], "total": 1}, not a bare array) to build that list from a @magistr/music-library instance's artist-map.

batchSize now defaults to the whole deduped list, not 10

artistMbids is deduped at list-resolution time — requested is the DISTINCT count, requestedRaw the raw input length — and batchSize defaults to requested rather than 10. One run is now a single complete pass by default (~35 minutes / ~775 requests for a cold ~775-artist list at 1 req/sec) instead of a 78-batch cold pass at the old default. The cursor still exists for two cases: a deliberate partial via an explicit smaller batchSize, and an interrupted pass.

The cursor is now keyed to the list it indexes

discographySyncState gains a listFingerprint (length-prefixed FNV-1a over the deduped list) and persists the distinct requested count. A persisted cursor is only resumed from when BOTH match this run's list; otherwise (including every state written before this change, none of which carry a fingerprint) the run restarts at offset 0. This closes the defect this issue was filed about: a cursor left at offset 1 by a one-artist list was silently applied to the real 775-artist list and skipped index 0 forever.

One definition of run coverage: covered and remaining

Eight new optional discographySyncState fields — requested, requestedRaw, listFingerprint, startOffset, covered, remaining, uncovered, uncoveredCount — record one run's coverage against its requested list. covered = processedCount + skippedCount; remaining = requested - covered. remaining is deliberately NOT requested - cursor.offset, which is algebraically identical to a formula that always reports 0 for a run that never reached its full list. uncovered / uncoveredCount record which requested MBIDs have no cached discography at all, computed from stored data rather than any counter.

A crash now leaves a record

The state write moves into a finally covering the whole post-loop accounting block, and execute's return moves out of the try — so a throw partway through a batch still persists an accurate cursor, coverage and uncovered set, and a successful run's returned dataHandles always names the handle it wrote rather than risking {dataHandles: [undefined]}.

New report: @magistr/musicbrainz-discography-sync

A new default model-scope report rendering discographySyncState's coverage, bound to the execution that produced it (never claims a run's numbers unless that run's own write is present in context.dataHandles), with an independent cross-check against the actual cached rg-by-artist-* rows.

2026.08.05.1

Fixes musicbrainz-ratelimit-runmodel-fanout, measured live: swamp model method run music resolve-artists completed in 581s having fired ~1483 MusicBrainz searches — ~2.5 req/sec against the documented 1 req/sec limit. mbFetch's rate limiter is correct WITHIN one method invocation (each await mbFetch(...) call shares module-level spacing state with every other call in the SAME invocation) but has no memory ACROSS separate context.runModel invocations — each one starts with lastRequest = null, so a caller fanning out one runModel call per item loses spacing entirely, even though the limiter itself was never broken. model.version and manifest.yaml move 2026.08.04.1 -> 2026.08.05.1.

New method: search-artists-batch

Collapses the fan-out instead of persisting the limiter: takes MANY Lucene artist queries and loops internally over the existing mbFetch, so the already-correct in-process limiter becomes correct for the WHOLE workload by construction — no persisted cursor, no read/write per request, no change to how spacing is computed. Bounded by maxQueries (default 400 — the designed stop) and a maxDurationMs slow-upstream backstop DERIVED from it (a new pure exported deriveMaxDurationMs(maxQueries, minIntervalMs, explicit?): explicit ?? Math.ceil(maxQueries * minIntervalMs * 1.5) + 30_000, so raising maxQueries also raises the backstop, while an explicit value is honoured verbatim with no floor), an already-aborted context.signal, and a new MusicBrainzBackoffError (see below) — each stop recorded in a stopReason (complete / max-queries / max-duration / aborted / backoff) with the untried remainder pushed to a new deferred[] array. A per-query fetch failure is isolated (recorded with an error, batch continues); a MusicBrainzBackoffError stops the WHOLE batch instead, because that query never got a verdict. The written artistSearchBatch resource (new, garbageCollection: 3 — deliberately below every other spec's 10, since it is one potentially-large document per run) is ALWAYS produced, including on every early stop, so completed work survives. Two new pure helpers back the planning: dedupeQueries (order-preserving, idempotent) and planSearchBatch(queries, maxQueries) -> {batch, deferred, truncated} (first maxQueries entries in input order — this is what makes an explicitly requested re-check placed first in the caller's query list immune to being silently dropped by the ceiling).

Payload budget: a new projection, not the full artist document

search-artist and search-artists-batch now share one extracted body, searchArtistsOnce (module-private), so the artist-search HTTP contract — including offset, still forwarded end-to-end — lives in exactly one place. search-artist is UNCHANGED behaviourally: same arguments, same full MusicBrainz artist objects written to the same artists/search resource. search-artists-batch instead writes a new exported projectArtistCandidates(artists) projection — {id, name, sort-name} per hit, dropping area/begin-area/life-span/aliases/tags/etc — because it writes ONE document per run and the full shape risked the datastore's 16MB per-document limit on a large batch (measured: one unprojected search-artist row at the default limit is ~15.6KB; projected, a hit is ~110-130 bytes).

Breaking change: retryAfterBackoffMs returns a discriminated result

retryAfterBackoffMs(retryAfterHeader, minIntervalMs, maxBackoffMs = 60_000) now returns {kind: "sleep", ms} or {kind: "stop", retryAfterMs} instead of a bare number of milliseconds — the whole Retry-After contract lives in this one pure classifier, and mbFetch only acts on the classification, never re-parsing the header itself. mbFetch behaviour changes for EVERY existing method, not just the new one: a Retry-After within maxBackoffMs still sleeps and retries exactly once, as before; a Retry-After EXCEEDING maxBackoffMs now throws a new exported MusicBrainzBackoffError (carrying retryAfterMs) immediately, without sleeping and without retrying — under the fan-out collapse, a single hostile or misconfigured multi-hour Retry-After would otherwise stall a whole batch invocation for that long while holding both the musicbrainz model lock and the caller's. mbFetch also gains an optional 5th signal?: AbortSignal parameter: checked before the rate-limit reservation, composed into the per-call AbortController via AbortSignal.any (never replacing the existing 30s client-side timeout), and raced against the Retry-After backoff sleep (no longer an uninterruptible setTimeout) — this is the only way a long batch's --timeout can be enforced INSIDE an in-flight request or backoff sleep, not just between queries. All four-argument callers (every existing method) are

2026.07.31.1

Everything below was accumulated as Unreleased until now. This release bundles two pieces of work: the wave-2b test backfill to the STANDARD.md five-suite quality bar (ext-quality-test-backfill), and the musicbrainz-ssrf-and-latent-bugs security fix for the SSRF in the Bandcamp scraper's fetchPage(). model.version and manifest.yaml move 2026.07.16.2 -> 2026.07.31.1 to reflect the actual source change (the test backfill alone was behavior-preserving and had not needed a bump).

Security fix: SSRF via bandcampUrl (HIGH)

Closes the HIGH-severity SSRF in fetchPage(), which previously fetched any caller-supplied or scraped URL with no scheme or host allowlist, allowing an internal/loopback/metadata-service target passed as bandcampUrl (or a second-order albumUrl scraped from a discography page) to be fetched verbatim and its parsed content returned to the caller.

• Added a module-private assertBandcampUrl(raw) guard: requires protocol === "https:" and hostname === "bandcamp.com" or hostname.endsWith(".bandcamp.com") (dot-anchored, so evil.bandcamp.com.attacker.com and notbandcamp.com are both rejected); throws a clear Invalid Bandcamp URL / Refusing to fetch non-Bandcamp host error otherwise, never a raw parser exception.
• fetchPage() now calls the guard before the initial request AND fetches with redirect: "manual", re-validating every Location header against the same guard before following it (bounded to 5 hops) — this closes the redirect-based bypass where a legitimate *.bandcamp.com URL 302s to an internal address, which a default auto-following fetch() would otherwise chase transparently.
• The guard is centralized in fetchPage, so all five existing call sites (seed-from-bandcamp's bandcampUrl; find-missing and seed-all-missing's bcUrl and second-order albumUrl) inherit the fix with no call-site changes. A second-order albumUrl that fails the guard still falls into the existing catch and gets embedded as an inert seed-URL string parameter — no fetch occurs there, so it is not an SSRF vector.
• Behavior tradeoff: custom-domain (CNAME-to-Bandcamp) sites are now rejected by the host allowlist, since only bandcamp.com and *.bandcamp.com are recognized. Accepted given the security priority and the overwhelmingly common *.bandcamp.com case.
• No AbortSignal timeout was added (tracked separately as a deferred MED under musicbrainz-ssrf-and-latent-bugs, along with the other latent bugs noted below) — this change is scoped to the SSRF fix only.
• musicbrainz_adversarial_test.ts: flipped the two SSRF characterization pins from asserting the vulnerable behavior to asserting the fix (assertRejects + zero fetch calls), and added positive coverage: a legit *.bandcamp.com fetch is unaffected; a bandcamp-to-bandcamp redirect is followed; a bandcamp-to-internal-address redirect is rejected on the redirect hop; file:// and http:// (non-https) inputs are rejected on scheme; and the dot-anchored hostname allowlist rejects spoofed hosts while still allowing bare bandcamp.com. All other tests are unchanged — 119 tests total, all green.

Test backfill (wave-2b, ext-quality-test-backfill)

• Added extensions/models/musicbrainz_test.ts (contract-fixture), musicbrainz_methods_test.ts (methods), musicbrainz_adversarial_test.ts (adversarial), musicbrainz_coverage_test.ts (coverage), musicbrainz_property_test.ts (property-invariant-flow) — 0 tests before this backfill, 114 after (119 after the SSRF fix above).
• Added fixtures/ — pure doc-derived, synthetic MusicBrainz WS v2 JSON wire fixtures (artist/release-group/release/recording/label search, artist and release-group lookup, browse-release-groups, browse-releases, generic search, a 404 and a 503 error body) plus five synthetic Bandcamp HTML fixtures under fixtures/bandcamp/ (.ts string-export modules, not .html, to keep the default test task free of --allow-read), plus PROVENANCE.md. No live call was made against any MusicBrainz instance or real Bandcamp page while authoring these fixtures; every value is synthetic (fake MBIDs 00000000-...-00000000000N, invented "Fixture"-prefixed names, synthetic Bandcamp subdomains).
• The extension's built-in 1 req/sec MusicBrainz rate limiter is both neutralized AND explicitly characterized under @std/testing FakeTime (first call incurs no wait; a second call soon after schedules a wait of at least 1100ms; spacing collapses toward zero as elapsed time grows) — see the three dedicated RATE LIMITER: tests in musicbrainz_methods_test.ts.
• Several already-shipped gaps were PINNED by the backfill (characterized as current behavior, not fixed) and tracked separately for follow-up under `music

Release 2026.07.16.2 — align model versions with manifests

Maintenance release across the @magistr extensions. For most packages this carries no functional change: the only edit is the model's version: field, brought back in line with its manifest version so the published model type version and the package version no longer drift.

Functional changes in this release are limited to:

• anime-cron: normalizeTitle now strips a ": subtitle" suffix and a trailing parenthesized year before comparison, fixing dedup false-misses where the torrent title carries a subtitle or year that the AniList romaji does not.

• arckit: first publish. Standalone ArcKit port — a 12-phase architecture governance state machine with 65 bundled templates, driven by a bundled skill.

Also tracks three extensions (kaiten, observability-agent, music-library) that previously existed only as untracked working-tree directories, recovered from stashes.

Merge pull request #5 from umag/extensions/jscad-stl-pair

extensions: add 15 more @magistr extensions + auto-discover CI