Music Library

2026.08.05.2

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

wanted: the missing-browse-cache throw named a nonexistent method

wanted's missing-MusicBrainz-browse-cache error told the operator to run swamp model method run <mbInstance> browse — there is no browse method (browse-release-groups / browse-releases / browse-recordings exist; browse is a resource spec name, not a method), so an operator who skipped the discography sync got unknown_method instead of an actionable fix. The throw now names the real runnable command — swamp model method run <mbInstance> sync-artist-discographies --input 'artistMbids:json=[...]' — plus the swamp data query extraction command (with its envelope shape, {"results": [[...]], "total": 1}) to build that artist list from this instance's own artistMap, and the repo-local music-wanted workflow line. No schema or resource shape change.

2026.08.05.1

Fixes musicbrainz-ratelimit-runmodel-fanout, measured live: swamp model method run <instance> resolve-artists completed in 581s having fired ~1483 MusicBrainz searches over a library of 2258 artists — ~2.5 req/sec against MusicBrainz's documented 1 req/sec limit. The root cause: mbFetch's rate limiter (in @magistr/musicbrainz) is correct WITHIN one method invocation, but resolve-artists reached MusicBrainz through ~1483 SEPARATE context.runModel invocations of search-artist, each starting with no rate-limit memory. model.version and manifest.yaml move 2026.08.04.1 -> 2026.08.05.1.

resolve-artists: at most ONE runModel call per run, persisted as a reusable cache

searchMusicBrainzArtists and its isLatest selector are DELETED outright — no dual path. resolve-artists now collects every DISTINCT name needing a MusicBrainz verdict (seed-unresolved, and either uncached or past its TTL), builds one Lucene query per name via the existing escapeLuceneQuery, and issues EXACTLY ONE call to @magistr/musicbrainz's new search-artists-batch method — deterministically selecting its own result row by a generated batchId correlation identity (never isLatest/array order, which nothing in this codebase ever set). Zero names needing a search means zero runModel calls. That call passes limit: 25 explicitly — the candidate window is the SAME 25 the deleted per-artist search-artist path implicitly got from MusicBrainz's own /ws/2 default, not search-artists-batch's own narrower default of 10 (a deliberate choice for that method's other callers, left unchanged). Without the explicit override, a duplicate MBID ranked 11-25 would fall outside the window and matchArtist would auto-pick a single resolved MBID instead of correctly parking the artist as ambiguous.

resolve-artists also now LOADS its own prior output (context.readResource, a NEW capability requirement for this method, optional-chained so an absent prior — including the very first post-merge run — degrades to empty rather than throwing) and treats it as a persistent, load-modify-write aggregate: a seed-unresolved artist whose last search verdict (checkedAt) is younger than ttlMs (new arg, default 30 days) is reused VERBATIM (mbid/status/source/ candidates/checkedAt) without a fresh search — except the LIBRARY's current name always wins, so a renamed artist is never stuck with a stale display name. A converged re-run therefore costs ZERO MusicBrainz requests. Two new method arguments force a re-check: refresh (everything) and refreshKeys (specific artists, ordered FIRST in the batch so an explicit re-check can never be silently discarded by the maxQueries ceiling). An artist present in the library with no prior entry is written; an entry in the prior map whose artist is no longer in the library is dropped — only artists actually in the library are ever written.

checkedAt means exactly "the timestamp of the last MusicBrainz SEARCH that produced a verdict" — it is NEVER set on a seed match (seed coverage is free and re-derived every run, not a search verdict) and NEVER set when a query's fetch errored, was deferred, or was never reached this run (the prior value, still stale, is preserved so the next run retries). A genuine no-match (MusicBrainz returned zero candidates, no error) still gets a fresh checkedAt — it got a real verdict this run, just a negative one.

Completeness: pendingSearch / truncated / stopReason

search-artists-batch bounds one run by maxQueries (default 400, passed through) and a derived maxDurationMs backstop; a run that hits either ceiling — or an aborted signal, or a Retry-After backoff — defers the remainder rather than searching it. Without visibility into that, unresolved: 1083 on a first post-merge run would be indistinguishable from "MusicBrainz doesn't know 1083 artists". Three new OPTIONAL top-level fields on the written artistMap — pendingSearch (distinct artists that needed a verdict this run and didn't get one), truncated, stopReason — make that distinction observable: re-run resolve-artists until pendingSearch is 0 to confirm convergence (about 4 runs for a cold ~1459-1483-artist library at the default maxQueries). All three are optional in the schema (the live 2258-entry map predates them) and always set on write.

Schema: five mirrors move together

ArtistMapEntrySchema gains optional checkedAt; ArtistMapSchema gains optional pendingSearch/truncated/stopReason; wanted.ts's report-side ArtistMapEntry/ArtistMapContent interfaces mirror both; and — the mirror missed once already in an earlier draft of this fix — the LOCAL TypeScript type ArtistMapEntry that resolve-artists actually constructs against also gains checkedAt, or the object literal it builds trips a TS2353

2026.08.02.1

Real-fixes all 6 latent bugs characterized by the test-only backfill below (tracked locally as music-library-latent-bugs, never filed to the Lab). music_library.ts is no longer byte-frozen; the model version and manifest.yaml both bump to 2026.08.02.1, with an identity upgrades[] entry (upgradeAttributes: (old) => old — no stored resource is reshaped, since every change is either a defaulted global/method argument or an additive BpmSchema field).

• LB1 (MEDIUM) fixed — verify's remote ffmpeg decode loop now wraps every file in the shell timeout command (sized from the new defaulted ffmpegDecodeTimeoutSec global arg, default 600s; 0 = no timeout), detected once per worker via command -v timeout so it degrades gracefully if the container lacks it — mirrors bpm's ANALYZE_PY signal.alarm(timeout). sshRun also gained an optional client-side AbortController transport ceiling (timer always cleared in finally, never AbortSignal.timeout()) as a belt-and-suspenders guard sized generously per worker so it only fires if the remote timeout itself failed or ssh/network wedged.
• LB2 (MEDIUM) fixed — verify/bpm/probe's single-path argument now resolves through two new shared, exported helpers — normalizeSegments (split on //\, drop ./empty, pop on .., throw when .. would escape the root — ported in spirit from obsidian-vault's segment guard) and confineContainerPath — instead of the old replace(/^\/+/, "") that stripped only leading slashes. A ../ traversal now throws Error("Path escapes music root: …") instead of resolving outside containerMusicRoot; a clean relative/absolute path still resolves identically to before.
• LB3 (LOW) fixed — probe now guards JSON.parse on the ffprobe output: empty stdout throws a clean Error naming the file instead of a raw JSON.parse("") SyntaxError, and unparseable non-empty stdout is caught and rethrown as a typed Error too (mirrors juick's JSON.parse → typed-error pattern).
• LB4 (LOW) fixed — verify's US(0x1f)/RS(0x1e) record framing is now RS-safe: before splitting on \x1f, any \x1e-delimited fragment whose leading field is not a KNOWN cpath is treated as the tail of the previous record's ffmpeg output (which happened to contain a stray RS byte) and re-folded back onto it, rather than being parsed as an unmatchable orphan record. A corrupt file whose ffmpeg output embeds an RS byte is now correctly classified as errors instead of silently passing as ok.
• LB5 (LOW) fixed — bpmMedian now uses a proper median (new exported median() helper): an even-length bpm array averages the two middle sorted values instead of returning the upper one (bpms[Math.floor(n / 2)]).
• LB6 (LOW) fixed — bpm gained a maxTracks method arg (default 50000, deliberately far higher than verify's 2000 — see below) plus tracksTruncated/failuresTruncated on BpmSchema. All stats (bpmMedian, confidenceBands, bpmHistogram) are computed over the FULL carried-over + newly-analyzed set BEFORE any truncation; only the STORED tracks/failures arrays are capped, mirroring verify's problems: problemsTruncated ? problems.slice(0, 2000) : problems. The default is high (not verify's 2000) because capping the stored array degrades bpm's resume carry-over (a library bigger than the cap would re-analyze the overflow every run) and the running method's input; pass maxTracks: 0 for full resume fidelity on a very large library.
• Pin flips in music_library_adversarial_test.ts: all 6 pin: KNOWN BUG tests are now fixed (music-library-latent-bugs LBn) assertions of the corrected behavior (LB1 also gained a quick-mode variant, an AbortSignal-transport-ceiling check, and a ffmpegDecodeTimeoutSec=0 disable check; LB2 gained a clean-relative-path anti-over-rejection positive; LB6 gained a default-does-not-truncate companion test). The 2 regression-pinned positives (P1 static-SQL, P2 shQuote + control-byte filename filtering), the hostile host/sshUser safety test, and both fixtures-secret-scan tests are UNCHANGED (byte-identical). New direct unit tests for normalizeSegments/confineContainerPath/median were added to music_library_coverage_test.ts.

Merge pull request #58 from umag/feat/music-library-bpm-running

feat(music-library): bpm analysis + cadence-matched running playlists (2026.07.17.1)

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.