feat!: Reference by modality with audio/video metadata; one name for sources

[MyPrototypeWhat]

This is a breaking release covering items 10 and 11 of the architecture review. Reference becomes a union keyed by modality and gains audio and video metadata. The catalog a search queries now has one name, "source". It also fixes the defects that turned up in the same files.

Design spec: docs/superpowers/specs/2026-10-12-modality-union-and-source-naming-design.md. Plan: docs/superpowers/plans/2026-10-12-modality-union-and-source-naming.md. The changeset has the full migration guide.

This branch contains #33's commit, rebased. Merge #33 first or not: the content is identical, so either order is clean. Please hold #33's Version Packages PR until this one is in, so core goes 0.9.0 → 0.10.0 once.

What changes

• Reference by modality.

  • Image, video, audio and text variants each declare only their own fields. The other variants' fields are typed ?: never, so a provider that writes the wrong field fails to compile, while readers keep compiling.
  • Runtime: a z.discriminatedUnion, plus a per-variant preview.mediaType prefix check. Cross-modality keys are stripped, and the testkit fails a provider that loses keys.
  • New types:
    • AudioMeta: durationSec, bitrateKbps, sampleRateHz, channels, format.
    • VideoMeta: durationSec, fps.
  • thumbnail is always an image a UI can show. visual means the original's size.

• One word: "source". A provider is adapter code; each provider instance serves one source. These are renamed:

  • meta.providers → meta.sources;
  • ProviderSearchStatus.providerId → SourceStatus.sourceId;
  • providerOptions → sourceOptions;
  • onProviderError → onSourceError;
  • ref.source.providerId → ref.source.id;
  • the skip vocabulary, the controls maps and the messages.

  The sources input, the MCP sources param and every adapter-side name stay as they are.

• Metadata from existing responses, with no new requests.

  • durationSec for openverse-audio, freesound, jamendo, pexels-video and pixabay-video.
  • Bitrate, sample rate and format for openverse-audio.
  • Non-positive or non-finite values stay unset.

• Fixes.

  • openverse-audio's thumbnail was a JSON waveform endpoint; it is now the album art. Its media types follow one table: ogx, mid and webm are labelled correctly, and an unknown filetype gets no preview.
  • Internet Archive no longer returns films for a text search. Core now rejects any emitted item outside the requested modalities.
  • Duplicate source ids throw. HDRIs get their own polyhaven-hdri id.
  • A typed SourceSelectionError, plus a structural isSourceSelectionError guard, so hosts and the dsh plugin stop matching message text.
  • Missing kinds are filled in: pixabay-video film/animation, openverse-audio music.
  • Unknown sourceOptions ids now produce a warning.
  • Flickr and pixabay-video no longer report a rendition's size as visual.

• @refkit/mcp. The sourceOptions input, the agent ref source, and new durationSec/width/height fields. The find-references skill from feat: refkit agent plugin for Claude Code and Codex #34 now names the source field.

• Release. One changeset bumps @refkit/core, @refkit/mcp and all 19 providers to minor; that is how 0.x signals a breaking change. Providers pin core exactly, so hosts upgrade everything together.

How it was built

There were four tasks, each implemented test-first and reviewed independently. A design review and a whole-branch final review came on top. Every finding was fixed or ruled on, and the reasons are recorded.

Testing

• Full gate. pnpm typecheck, pnpm lint, pnpm build, pnpm test:run and pnpm smoke:artifact all pass on top of current main, which includes feat: refkit agent plugin for Claude Code and Codex #34: 653 tests passed, 25 skipped.
• Live checks.
  • Openverse audio: durations, Jamendo items, album art served as image/jpeg, and categories.
  • Internet Archive, text only: 60 of 60 results were texts.
  • REFKIT_LIVE=1 pnpm test:live: 634 passed. The only failure was a gutendex upstream 403.
• Mutation checks. Reviewers broke the type tests, the prefix check, the lost-keys check, the duration units and the waveform thumbnail, and confirmed each change fails the tests.

Follow-up

@refkit/dsh-plugin 0.3.0 adapts to this release once it is on npm (spec D8). The final review lists its 25 concrete changes.