frutebox-node 0.1.0__py3-none-any.whl

frutebox/mediaserving.py

@@ -0,0 +1,603 @@
+"""FILE 23-B1 — the MEDIA serving resolver: which commercial-safe model serves a media request.
+
+`serving.py` answers this for TEXT models. Nothing answered it for media, and the three
+generator modules (`imagegen`, `videogen`, `audiogen`) each carried their own hardcoded
+Hugging Face default instead. That gap was not cosmetic — it put a NON-COMMERCIAL model in
+production as a live default:
+
+  * `audiogen._MUSIC_MODEL` defaulted to `facebook/musicgen-small`. MusicGen is CC-BY-NC 4.0.
+    Plan 23 §A names it as one of the five exclusions and §D4 says the file-09 licence CI is
+    the backstop that makes shipping one impossible. The backstop could not see it, because
+    `registry.landmines_referenced()` matches REGISTRY IDS (`musicgen`) and the serving
+    surface speaks WEIGHTS REFS (`facebook/musicgen-small`). Two vocabularies, one gate, and
+    the gate was reading the wrong one. `landmines_referenced(['facebook/musicgen-small'])`
+    returned `[]` on a clean tree.
+  * `audiogen._SPEECH_MODEL` defaulted to `suno/bark-small` and `videogen._MODEL` to
+    `THUDM/CogVideoX-2b` — neither model is DECLARED in `registry/models.yaml` at all, so
+    neither passed through any licence, territory or tier gate on its way to a GPU.
+  * `audiogen._CLONE_MODEL` defaulted to `resemble-ai/chatterbox`, which does not exist
+    (HTTP 401). The real repo is `ResembleAI/chatterbox`. The voice-cloning path could never
+    have fetched its model.
+
+So the rule this module enforces, from §B1 ("Declared per model in `models.yaml` — file 09
+`runtime`, `vram_gb`, `modality`"):
+
+  **A media job may only ever run weights that belong to a registry-DECLARED model which
+  `registry.serving_allowed()` passes.** An undeclared ref is refused for being undeclared,
+  which catches a landmine without needing to have predicted that particular landmine.
+
+WHERE THE REPOS AND REVISIONS COME FROM — not guessed, MEASURED.
+Plan 28 §B3, quoted in `scripts/resolve_weights.py`, is explicit: *"If a model's exact
+repo/revision cannot be resolved and license-verified, set `status: verify` and raise it as
+DECISION REQUIRED, never guess."* Every entry in `WEIGHTS` below was read from the live
+Hugging Face API on **2026-09-28**, with its commit SHA pinned and its card licence compared
+against the registry's declared one. A model whose repo could not be resolved that way has NO
+entry, and `resolve_media_model` then refuses it by name rather than inventing a path — see
+`UNRESOLVED` for the three that are in that position and why.
+
+`models.yaml` carries no `weights:` blocks yet (that is plan 28 §B2/B3, another lane), so the
+pins live here, next to the code that loads them, until that block exists to move them into.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .envvars import env as envvar
+from .registry import serving_allowed, territory_allows
+from .registry_gen import BY_ID, REGISTRY
+
+#: The registry tiers that describe a media modality (`models.yaml` field notes: "sound-effects
+#: models ride the music tier"). `voice` is the realtime duplex tier and belongs to file 07, not
+#: to a generate-an-artifact request, so it is deliberately not here.
+MEDIA_TIERS: tuple[str, ...] = ("image", "video", "music", "tts", "stt")
+
+#: A request kind (the API's vocabulary) -> the registry tier that serves it. `/v1/audio/generations`
+#: takes kind=music|song|sfx; all three are music-tier models.
+#: An API `modality` -> the media KIND that serves it.
+#:
+#: Two vocabularies meet here and neither is wrong: the API speaks in modalities (what the
+#: caller asked for) and this module speaks in kinds (what gets generated). `audio` is the one
+#: that is genuinely ambiguous — a request for audio is a request for SPEECH unless it says
+#: otherwise — and deciding it once here is better than each caller guessing.
+KIND_FOR_MODALITY: dict[str, str] = {
+    "image": "image",
+    "video": "video",
+    "audio": "speech",
+}
+
+KIND_TIER: dict[str, str] = {
+    "image": "image",
+    "video": "video",
+    "music": "music",
+    "song": "music",
+    "sfx": "music",
+    "speech": "tts",
+    "clone": "tts",
+    "transcription": "stt",
+}
+
+#: Per-kind preference order, transcribed from plan 23 §A's table (primary first, then its named
+#: backups). The resolver walks this list and takes the first model that passes every gate, so a
+#: licence env that is not signed, or a geo-fence, demotes to the next PLAN-SANCTIONED model rather
+#: than to whatever else happens to share the tier.
+KIND_PREFERENCE: dict[str, tuple[str, ...]] = {
+    # §A: primary Qwen-Image; backups Chroma / FLUX.2 [klein] (neither is in the registry yet),
+    # so SDXL — declared, open-commercial, status default — is the standing second choice.
+    "image": ("qwen-image-20b", "sdxl-1.0"),
+    # §A: primary Wan 2.2; backups Mochi-1, CogVideoX-2B; LTX-2 only under its revenue cap.
+    "video": ("wan-2.2", "mochi-1", "ltx-2.3"),
+    # §A: short instrumental -> ACE-Step.
+    "music": ("ace-step-1.5",),
+    # §A: full song with vocals -> YuE 7B, and the backup column is literally "—".
+    # ACE-Step is NOT a fallback here, for the same reason it is not one for sfx: it is an
+    # INSTRUMENTAL model, and answering "a song with vocals" with a vocal-less track is the
+    # quality-for-availability trade §B3 forbids. Listing it looked harmless while nothing
+    # constrained VRAM; once `max_vram_gb` was honoured it meant every card below YuE's 16 GB
+    # silently got an instrumental instead of a song.
+    "song": ("yue-7b",),
+    # §A: SFX/ambience -> Stable Audio Open, with MOSS-SoundEffect as the Apache alternative for
+    # when the Stability revenue-threshold licence is not signed. ACE-Step is deliberately NOT in
+    # this chain: it is a MUSIC model, and answering "a door creaking" with a short instrumental is
+    # trading quality for availability, which §B3 forbids outright. An sfx request with no sfx
+    # model refuses and says so.
+    "sfx": ("stable-audio-open-1.5", "moss-soundeffect"),
+    # §A: local-first TTS primary Kokoro-82M; backups Piper (CPU, not a GPU-node model), Chatterbox
+    # (cloning), Orpheus.
+    "speech": ("kokoro-82m", "chatterbox", "orpheus"),
+    # Cloning is a capability, not a tier: only Chatterbox does zero-shot voice cloning on a
+    # commercial licence. XTTS-v2 clones better and is CC-BY-NC — excluded on purpose.
+    "clone": ("chatterbox",),
+    "transcription": ("whisper-large-v3-turbo",),
+}
+
+#: Tier B is the 8-16 GB consumer/contributor band, Tier A the 16 GB+ datacentre band. §B2: "The
+#: router never offers a video/music job to a Tier-C/edge node — Tier B/A GPUs only (8-16 GB+)."
+#: Tier C therefore never appears as a value here, and `PLACEMENT_TIERS` is what a caller checks a
+#: node against.
+PLACEMENT_TIERS: frozenset = frozenset({"A", "B"})
+_TIER_B_MAX_VRAM_GB = 16.0
+#: §B2 puts the media floor at "Tier B/A GPUs only (8-16 GB+)" — below this a node is edge/Tier C.
+_TIER_B_MIN_VRAM_GB = 8.0
+
+
+@dataclass(frozen=True)
+class Weights:
+    """A pinned download source. `revision` is a commit SHA, never a branch — a moving
+    reference would let the weights under a shipped model change with no change to this repo."""
+    repo: str
+    revision: str
+    source: str            # how this repo was established, so the next reader need not re-derive it
+    stage2_repo: str = ""  # YuE is a two-stage model; stage 2 is required for a complete song
+    stage2_revision: str = ""
+
+
+#: registry id -> pinned weights. Read from the Hugging Face API 2026-09-28; `source` records how
+#: the repo was picked where the org held more than one candidate.
+WEIGHTS: dict[str, Weights] = {
+    "qwen-image-20b": Weights(
+        "Qwen/Qwen-Image", "75e0b4be04f60ec59a75f475837eced720f823b6",
+        "Qwen/ holds Qwen-Image plus -Edit/-Layered/-PE-* variants; those are different TASKS "
+        "(editing, layering, prompt-expansion), and -2.1/-2512 are later generations than the "
+        "registry's `qwen-image-20b`. The base text-to-image 20B model is Qwen-Image. "
+        "Card licence apache-2.0 == registry declaration.",
+    ),
+    "flux2-klein-4b": Weights(
+        "black-forest-labs/FLUX.2-klein-4B", "e7b7dc27f91deacad38e78976d1f2b499d76a294",
+        "RESOLVED AND LICENCE-VERIFIED 2026-10-12, and it is the only EU-published image model "
+        "that can be. black-forest-labs/ holds 38 repos: the owner's instruction is \"FLUX.2 "
+        "[klein] 4B only — the 9B is non-commercial — exclude it explicitly\", and the live cards "
+        "say exactly that. klein-4B: `license: apache-2.0`, `gated: false`, and its LICENSE.md is "
+        "the verbatim Apache 2.0 text with no non-commercial clause (checked, not inferred from "
+        "the tag). klein-9B: `license: other`, `license_name: flux-non-commercial-license`, "
+        "`gated: auto` — excluded, and it is the registry's `flux2-klein-9b` at status `verify`. "
+        "The -fp8/-nvfp4/-base/-kv variants are quantisations and base (non-instruct) builds of "
+        "the same two; `flux1-schnell` stays UNRESOLVED because its repo is gated. "
+        "STILL `emerging` IN THE REGISTRY, DELIBERATELY: a pin and a licence are not a measured "
+        "load. `AutoPipelineForText2Image` picks `Flux2KleinPipeline` from the repo's "
+        "`model_index.json` and the node installs diffusers unpinned, so it SHOULD load — and "
+        "'should' is not what `status: default` claims. Promoting it needs one GPU load on a "
+        "frutebox-backend-* pod, which is owner-authorised spend.",
+    ),
+    "sdxl-1.0": Weights(
+        "stabilityai/stable-diffusion-xl-base-1.0", "462165984030d82259a11f4367a4eed129e94a7b",
+        "The ref `imagegen.py` has always shipped, now pinned. Card licence openrail++ == the "
+        "registry's `openrail++-m` / open_commercial.",
+    ),
+    "wan-2.2": Weights(
+        "Wan-AI/Wan2.2-T2V-A14B-Diffusers", "5be7df9619b54f4e2667b2755bc6a756675b5cd7",
+        "Wan-AI/ holds T2V / I2V / TI2V / S2V / Animate builds. `/v1/videos` is TEXT-to-video, so "
+        "T2V — the others need an input image or audio and would reject the request. The "
+        "-Diffusers build is the one §B1's named serving library can load. Card apache-2.0 == "
+        "registry declaration.",
+    ),
+    "mochi-1": Weights(
+        "genmo/mochi-1-preview", "14be5fcea23095ed330cb214647916a451e38b6e",
+        "genmo/ publishes exactly one model — unambiguous. Card apache-2.0 == registry.",
+    ),
+    "ace-step-1.5": Weights(
+        "ACE-Step/Ace-Step1.5", "19671f406d603126926c1b7e2adc169acbcade22",
+        "Resolved by scripts/resolve_weights.py against the §B3 org table (ace-step -> ACE-Step). "
+        "NOTE: the card says `mit` where the registry declares `apache-2.0`. Both are the "
+        "apache_mit licence CLASS, so the gate's verdict is unaffected, but the declared string "
+        "is wrong — reported for file 09.",
+    ),
+    "yue-7b": Weights(
+        "m-a-p/YuE-s1-7B-anneal-en-cot", "454c20e1748888800f8e4b3da45125f55482d967",
+        "m-a-p/ holds YuE s1 in 0.5B and 7B, the 7B in en/jp-kr/zh x cot/icl. The variant is not "
+        "this lane's choice: `web/src/lib/audio/music-models.ts` already committed the label "
+        "'YuE 7B (anneal-en-cot)'. Card apache-2.0 == registry.",
+        stage2_repo="m-a-p/YuE-s2-1B-general",
+        stage2_revision="9dfa90b7013f6b5e7eb5eb2991620dca33058a0e",
+    ),
+    "kokoro-82m": Weights(
+        "hexgrad/Kokoro-82M", "f3ff3571791e39611d31c381e3a41a3af07b4987",
+        "Resolved by scripts/resolve_weights.py against the §B3 org table (kokoro -> hexgrad). "
+        "Card apache-2.0 == registry.",
+    ),
+    "chatterbox": Weights(
+        "ResembleAI/chatterbox", "5bb1f6ee58e50c3b8d408bc82a6d3740c2db6e18",
+        "CORRECTS the ref `audiogen.py` shipped. `resemble-ai/chatterbox` returns HTTP 401 — the "
+        "org is `ResembleAI`. The cloning path could never have fetched its model. Card mit == "
+        "registry.",
+    ),
+    "whisper-large-v3-turbo": Weights(
+        "openai/whisper-large-v3-turbo", "41f01f3fe87f28c78e2fbf8b568835947dd65ed9",
+        "Resolved by scripts/resolve_weights.py (§B3 org table: whisper -> openai); the repo name "
+        "is the model id. Card mit == registry.",
+    ),
+}
+
+#: Declared media models with NO resolvable pinned source, and the reason. §B3's rule is to raise
+#: these rather than guess, so `resolve_media_model` skips them and says why. Each is build work
+#: for file 09/28 (a `weights:` block or a corrected id), not an owner action.
+UNRESOLVED: dict[str, str] = {
+    "stable-audio-open-1.5": (
+        "stabilityai/ publishes stable-audio-open-1.0 and -open-small, and stable-audio-3-*. "
+        "There is NO stable-audio-open-1.5. The registry id names a version that does not exist, "
+        "so the sfx primary cannot be fetched. (1.0 is also gated=auto, license `other` — the "
+        "Stability Community revenue threshold plan 23 §A flags 'verify at build'.)"
+    ),
+    "flux1-schnell": (
+        "black-forest-labs/FLUX.1-schnell resolves but is GATED — it needs an accepted licence on "
+        "a Hugging Face account before the weights can be fetched. Registry status is `emerging` "
+        "so it is not offered anyway."
+    ),
+    "orpheus": "No publisher org in the §B3 table and no unambiguous repo; registry status `emerging`.",
+    "moss-soundeffect": "No publisher org in the §B3 table; registry status `emerging`, runtime [].",
+    "auraflow": "No publisher org in the §B3 table; registry status `emerging`.",
+    "lumina-image-2": "No publisher org in the §B3 table; registry status `emerging`.",
+    "hidream-i1": "No publisher org in the §B3 table; registry status `emerging`.",
+    "hunyuan-image": "No publisher org in the §B3 table; geo-fenced backup.",
+    "hunyuan-video-1.5": "No publisher org in the §B3 table; geo-fenced backup.",
+    "ltx-2.3": "No publisher org in the §B3 table; paid_commercial backup behind LIGHTRICKS env.",
+    "stable-video": "No publisher org in the §B3 table; paid_commercial backup behind STABILITY env.",
+    "sd-3.5-large": "No publisher org in the §B3 table; paid_commercial backup behind STABILITY env.",
+    "open-sora": "No publisher org in the §B3 table; registry status `emerging`.",
+    "xtts-v2": "NEVER resolved on purpose — CC-BY-NC (coqui-cpml). Declared so the gate can assert it.",
+}
+
+#: weights repo (lowercased) -> registry id, so the gate can speak the serving surface's own
+#: vocabulary. A multi-stage model maps BOTH its repos to the one id it is: YuE's stage-2
+#: upsampler is not a second model to declare, it is part of yue-7b's serving recipe the same way
+#: a quant file is part of a GGUF model's, and the licence that governs stage 1 governs it.
+_REF_TO_ID: dict[str, str] = {}
+for _mid, _w in WEIGHTS.items():
+    _REF_TO_ID[_w.repo.lower()] = _mid
+    if _w.stage2_repo:
+        _REF_TO_ID[_w.stage2_repo.lower()] = _mid
+del _mid, _w
+
+#: Refs that a previous default put on the serving path and that must never come back. Each maps to
+#: the reason, because "undeclared" understates a CC-BY-NC model.
+RETIRED_REFS: dict[str, str] = {
+    "facebook/musicgen-small": "MusicGen is CC-BY-NC 4.0 — plan 23 §A excludes it by name. Use ace-step-1.5.",
+    "facebook/musicgen-medium": "MusicGen is CC-BY-NC 4.0 — plan 23 §A excludes it by name. Use ace-step-1.5.",
+    "facebook/musicgen-large": "MusicGen is CC-BY-NC 4.0 — plan 23 §A excludes it by name. Use ace-step-1.5.",
+    "coqui/xtts-v2": "XTTS-v2 is CPML, non-commercial — plan 23 §A excludes it by name. Use chatterbox.",
+    "suno/bark-small": "Bark is not declared in models.yaml, so it passes no licence, territory or tier gate. Use kokoro-82m.",
+    "suno/bark": "Bark is not declared in models.yaml, so it passes no licence, territory or tier gate. Use kokoro-82m.",
+    "thudm/cogvideox-2b": "Not declared in models.yaml. Plan 23 §A's video primary is wan-2.2.",
+    "thudm/cogvideox-5b": "CogVideoX-5B carries a conditional licence plan 23 §A flags; it is not declared. Use wan-2.2.",
+    "resemble-ai/chatterbox": "Wrong org — this repo does not exist (HTTP 401). The real one is ResembleAI/chatterbox.",
+    "black-forest-labs/flux.1-dev": "FLUX.1 [dev] is non-commercial — plan 23 §A excludes it by name.",
+    "black-forest-labs/flux.2-dev": "FLUX.2 [dev] is non-commercial — plan 23 §A excludes it by name.",
+}
+
+
+class MediaUnavailable(RuntimeError):
+    """No commercial-safe, declared, fetchable model serves this request here.
+
+    Raised with the reason PER CANDIDATE, because "image generation is unavailable" and "the
+    licence env for the only model that fits is not signed" need different fixes, and a node
+    operator reading a log cannot tell them apart from a single sentence.
+    """
+
+
+@dataclass(frozen=True)
+class MediaSpec:
+    """The resolved answer: which model, from where, at what size, on which placement tier."""
+    kind: str
+    model_id: str
+    tier: str                 # the registry tier (image|video|music|tts|stt)
+    repo: str
+    revision: str
+    vram_gb: float
+    runtime: tuple
+    placement_tier: str       # "A" | "B" — never "C" (§B2)
+    local_ok: bool            # may run free on a capable device (§B3 local-first)
+    stage2_repo: str = ""
+    stage2_revision: str = ""
+
+    @property
+    def ref(self) -> str:
+        """`repo@revision` — what a node fetches, pinned."""
+        return f"{self.repo}@{self.revision}"
+
+
+@dataclass(frozen=True)
+class Placement:
+    """§B3 — where this generation runs, and who pays for it.
+
+    `metered` and `reward` are SEPARATE fields and they always move together. That is the
+    invariant worth having a type for: you cannot charge the user for work no node did, and you
+    cannot pay a node for work it did not do. Two booleans that must agree are easier to get
+    wrong than one, which is exactly why the test asserts they never disagree rather than
+    trusting the two lines below to stay in step.
+    """
+    where: str                # "device" | "node"
+    metered: bool             # charged against the user's §8A budget
+    reward: bool              # a node earned something for it
+    tier: str                 # the placement tier a node would need — "A" | "B", never "C"
+    reason: str = ""
+
+    @property
+    def free(self) -> bool:
+        return not self.metered
+
+
+def media_placement(spec: "MediaSpec", device_vram_gb: float = 0.0) -> Placement:
+    """§B3 — "a capable device generates on-device for free; an incapable one routes to a
+    Tier-A/B node, meters on the user's budget, and settles a node reward."
+
+    CAPABLE IS TWO CONDITIONS, not one. The card has to be big enough AND the model has to be
+    one we may run on a contributor's machine at all: `local_ok` is false for models whose
+    licence or tier bars them from a device however large its GPU is, and treating VRAM alone
+    as capability would put those on the one machine we do not control.
+
+    A device that can do the work is not metered, and no node is paid, because no node did
+    anything. That is the whole of §B3's economics and it is one branch.
+    """
+    need = float(spec.vram_gb or 0.0)
+    have = float(device_vram_gb or 0.0)
+
+    if spec.local_ok and have and have >= need:
+        return Placement(
+            "device", metered=False, reward=False, tier=spec.placement_tier,
+            reason=(f"the device has {have:g} GB and {spec.model_id} needs {need:g} — "
+                    f"it runs here, free, and no node is involved"))
+
+    why = ("this model may not run on a contributor device"
+           if not spec.local_ok
+           else f"the device has {have:g} GB and {spec.model_id} needs {need:g}")
+    return Placement(
+        "node", metered=True, reward=True, tier=spec.placement_tier,
+        reason=f"{why}; a tier-{spec.placement_tier} node runs it, metered on your budget")
+
+
+def model_placement_tier(vram_gb: float) -> str:
+    """Which tier of node can host this MODEL: "B" for the 8-16 GB consumer band, "A" above it.
+
+    Never "C". This is a requirement, not a measurement — §B2 keeps media jobs off edge nodes
+    entirely, so no model weight yields one, not even the 1 GB TTS model.
+    """
+    return "B" if float(vram_gb) <= _TIER_B_MAX_VRAM_GB else "A"
+
+
+def node_tier_for_vram(vram_gb: float) -> str:
+    """Which tier THIS NODE is, measured from the card in it.
+
+    The counterpart to `model_placement_tier`, and deliberately a separate function: one is
+    "what does this model need", the other "what is this machine". Collapsing them is how a
+    4 GB laptop GPU would read as Tier B — the model side never returns "C", so the same
+    mapping cannot answer both questions.
+
+    §B2 puts the media floor at 8-16 GB+, so below 8 GB is Tier C / edge.
+    """
+    v = float(vram_gb)
+    if v > _TIER_B_MAX_VRAM_GB:
+        return "A"
+    if v >= _TIER_B_MIN_VRAM_GB:
+        return "B"
+    return "C"
+
+
+def tier_accepts(node_tier: str) -> bool:
+    """May a node of this tier be offered a media job at all? (§B2 / the done-criterion
+    "refused on a Tier-C/edge node".) Unknown tiers fail closed."""
+    return (node_tier or "").strip().upper() in PLACEMENT_TIERS
+
+
+#: The modalities §B2 keeps off edge nodes — and ONLY these two.
+#:
+#: §B2's sentence is narrow and deliberate: "video and music/SFX are async/batch, NOT in the
+#: token loop … The router never offers a VIDEO/MUSIC job to a Tier-C/edge node." It does not
+#: say image, and it does not say speech. Applying the floor to all four would contradict the
+#: rest of the plan in the same breath: §A calls Kokoro-82M "Apache, local-first", lists Piper as
+#: the CPU backup, and §B3 says "on a capable device … Kokoro, ACE-Step, small image models run
+#: locally" and that this is the FREE path. A 1 GB TTS model barred from a 4 GB laptop by a rule
+#: written for 24 GB video diffusion would delete the plan's own local-first story.
+#:
+#: Image and speech are instead constrained by fit, which the resolver already does properly:
+#: `max_vram_gb` skips any model the card cannot hold, so a small device gets the small model
+#: or an honest refusal — never a job it cannot run.
+EDGE_BARRED_MODALITIES: tuple[str, ...] = ("video",)
+
+#: The advertisement vocabulary a node uses (`GEN_MODALITIES`, `output_modalities`). "audio"
+#: covers speech AND music there, and a node advertising it may still serve speech on a small
+#: card, so the floor cannot be applied to the whole label — only `video` is barred outright.
+MEDIA_MODALITIES: tuple[str, ...] = ("image", "audio", "video")
+
+
+def media_modalities_for_node(advertised, vram_gb: float) -> list:
+    """Filter a node's advertised modalities to what §B2 permits on a card this size.
+
+    A node that advertises a modality it must then refuse is capacity that does not exist: the
+    dispatch is wasted and the router has no way to know. So the floor is applied where the
+    claim is MADE, not only where the job lands, and an operator's `GEN_MODALITIES` cannot opt
+    an edge machine back into VIDEO — the rule is about the hardware, not the configuration.
+
+    Only `video` is stripped below the floor. See `EDGE_BARRED_MODALITIES`: §B2 names video and
+    music, and "audio" in the advertisement vocabulary also covers speech, which §A and §B3
+    explicitly want running locally on small hardware. Stripping the whole `audio` label
+    would take Kokoro off exactly the laptops the plan puts it on. Image and speech are
+    constrained by FIT instead — `resolve_media_model(..., max_vram_gb=...)` already refuses a
+    model the card cannot hold — and a music request on a small card is refused by that same
+    fit check, since the smallest music model needs 8 GB.
+
+    Always returns at least ["text"]: every node serves text.
+    """
+    keep = list(advertised or [])
+    if not tier_accepts(node_tier_for_vram(vram_gb)):
+        # Driven by the constant, not by a literal beside it. A constant that documents the
+        # rule without driving it drifts from it, and editing it would change nothing.
+        keep = [m for m in keep if m not in EDGE_BARRED_MODALITIES]
+    if "text" not in keep:
+        keep.insert(0, "text")
+    return keep
+
+
+def weights_allowed(ref: str, env: dict | None = None) -> tuple[bool, str]:
+    """The §D4 LICENCE gate, speaking WEIGHTS REFS instead of registry ids.
+
+    Returns (allowed, reason). A ref is allowed only when it belongs to a registry-declared
+    model that `serving_allowed()` passes — so an undeclared ref is refused for being
+    undeclared, and no landmine has to have been predicted individually for the gate to stop it.
+
+    SCOPE, because the name invites a wrong assumption: this is the licence gate and nothing
+    else. It does NOT apply the geo-fence — `territory_allows` needs a node region and a user
+    region, which a bare weights ref does not carry. `resolve_media_model` applies the fence
+    separately, and anything else adopting this as "the gate" must do the same or it will admit
+    a geo-fenced model inside its fence.
+    """
+    r = (ref or "").strip()
+    if not r:
+        return False, "empty weights ref"
+    bare = r.split("@", 1)[0].lower()
+    retired = RETIRED_REFS.get(bare)
+    if retired:
+        return False, retired
+    # Callers speak both vocabularies: the serving surface hands over a weights repo, the resolver
+    # hands over a registry id. Accept either, or the refusal reason libels a declared model as
+    # "not declared" — which sends the reader to fix the registry instead of the actual cause.
+    mid = _REF_TO_ID.get(bare) or (r if r in BY_ID else None)
+    if mid is None:
+        return False, (
+            f"{r} is not declared in registry/models.yaml, so it passes no licence or tier gate. "
+            f"Plan 23 §B1 requires every media model to be declared there."
+        )
+    if not serving_allowed(mid, env):
+        m = BY_ID[mid]
+        if m["license_class"] == "non_commercial" or m["status"] == "verify":
+            return False, f"{mid} is {m['license_class']}/{m['status']} — never served (§D4)."
+        if m["status"] == "emerging":
+            return False, f"{mid} is status `emerging` — declared, not yet servable."
+        if m["license_class"] == "paid_commercial":
+            return False, (
+                f"{mid} is paid_commercial: it serves only with "
+                f"FRUTEBOX_LICENSE_{m['vendor']}_AGREED=true."
+            )
+        return False, f"{mid} is refused by the licence gate."
+    return True, ""
+
+
+def resolve_media_model(kind: str, *, node_region: str = "", user_region: str = "",
+                        env: dict | None = None, override: str = "",
+                        max_vram_gb: float = 0.0) -> MediaSpec:
+    """The one answer to "which model serves this media request here".
+
+    `override` is an operator's env choice (`FRUTEBOX_IMAGE_MODEL` and friends). It is
+    VALIDATED, not trusted: an override naming an undeclared or non-commercial model is
+    refused outright rather than honoured, which is the whole reason MusicGen could previously
+    reach a GPU. It may name either a registry id or a weights repo.
+
+    `max_vram_gb` is the VRAM actually available where this will run, and it is what makes
+    §B3's local-first path real rather than aspirational: on a 12 GB contributor card the 24 GB
+    image primary is skipped and the 10 GB one is taken, so the job runs on the device FOR FREE
+    instead of going to a metered Tier-A node. 0 means "don't constrain" (a datacentre caller
+    that will size the pod from the spec it gets back). Note this only reorders WHICH sanctioned
+    model runs — it never lowers the licence, territory or tier bar.
+
+    Raises `MediaUnavailable`, listing what was tried and why each was rejected. It never
+    substitutes a different modality's model or a different artist's voice — a request whose
+    model cannot serve gets an error, because the point of the request was which model.
+    """
+    k = (kind or "").strip().lower()
+    tier = KIND_TIER.get(k)
+    if tier is None:
+        raise MediaUnavailable(
+            f"unknown media kind {kind!r} — expected one of {', '.join(sorted(KIND_TIER))}")
+
+    tried: list[str] = []
+    if override:
+        # An override may only pick FROM THE KIND'S OWN CHAIN, never merely from its tier.
+        # `KIND_TIER` maps music, song and sfx all to the music tier, so a tier-level check
+        # would let `FRUTEBOX_MUSIC_MODEL=ace-step-1.5` — a reasonable thing for an operator to
+        # set — silently redirect every SFX request to a music model. That is the exact trade
+        # the no-fallthrough rule below exists to prevent, and an env var must not be a way
+        # round it. An override outside the chain is refused and told which ids are open to it.
+        picked = _id_for_override(override)
+        sanctioned = KIND_PREFERENCE.get(k, ())
+        if picked not in sanctioned:
+            # A retired ref gets its own reason first. "Not in the chain" is true of
+            # `facebook/musicgen-small` but badly understates it — an operator who reads only
+            # that will try it again for the kind it IS a model of. The licence is why it will
+            # never be re-enabled anywhere, and that is the sentence worth showing.
+            retired = RETIRED_REFS.get(str(override).split("@", 1)[0].strip().lower())
+            raise MediaUnavailable(
+                f"{override!r} cannot serve a {k!r} request: "
+                + (retired or
+                   f"it is not in plan 23 §A's list for {k!r} ({', '.join(sanctioned) or 'none'}). "
+                   f"An override may choose among those, not beyond them.")
+            )
+        candidates: tuple[str, ...] = (picked,)
+    else:
+        # §A's table IS the routing table, and it is exhaustive per kind. There is deliberately no
+        # fallthrough to "any other model in this tier": the music tier holds an instrumental
+        # model, a song model and a sound-effect model, so falling through would answer "a door
+        # creaking" with a short instrumental and call it served. §B3 — "quality is never traded
+        # for locality" — rules that out. A kind whose sanctioned models cannot serve REFUSES.
+        candidates = KIND_PREFERENCE.get(k, ())
+
+    for mid in candidates:
+        m = BY_ID.get(mid)
+        if m is None:
+            # Not a declared model. `weights_allowed` knows the retired refs by name, so an
+            # override of `facebook/musicgen-small` is told it is CC-BY-NC rather than merely
+            # "undeclared" — the operator needs to know WHY it will never be re-enabled.
+            tried.append(f"{mid}: {weights_allowed(mid, env)[1]}")
+            continue
+        if m["tier"] != tier:
+            tried.append(f"{mid}: is a {m['tier']}-tier model, not {tier}")
+            continue
+        if not serving_allowed(mid, env):
+            ok, why = weights_allowed(WEIGHTS[mid].repo if mid in WEIGHTS else mid, env)
+            tried.append(f"{mid}: {why or 'refused by the licence gate'}")
+            continue
+        if not territory_allows(mid, node_region, user_region):
+            tried.append(
+                f"{mid}: geo-fenced — territory {m.get('territory')} bars node "
+                f"{node_region or '?'} / user {user_region or '?'}")
+            continue
+        w = WEIGHTS.get(mid)
+        if w is None:
+            tried.append(f"{mid}: no pinned source — {UNRESOLVED.get(mid, 'no weights block (plan 28 §B2/B3)')}")
+            continue
+        vram = float(m["vram_gb"])
+        if max_vram_gb and vram > float(max_vram_gb):
+            tried.append(f"{mid}: needs {vram:g} GB VRAM, this device has {float(max_vram_gb):g} GB")
+            continue
+        return MediaSpec(
+            kind=k, model_id=mid, tier=tier, repo=w.repo, revision=w.revision,
+            vram_gb=vram, runtime=tuple(m.get("runtime") or ()),
+            placement_tier=model_placement_tier(vram),
+            local_ok=m.get("local_class") in ("L", "W"),
+            stage2_repo=w.stage2_repo, stage2_revision=w.stage2_revision,
+        )
+
+    detail = "\n  ".join(tried) or "no declared model in this tier"
+    raise MediaUnavailable(
+        f"no commercial-safe model can serve a {k!r} request here:\n  {detail}")
+
+
+def _id_for_override(override: str) -> str:
+    """An operator override may name a registry id or a weights repo; normalise to the id so the
+    same gates apply either way. An unrecognised value is returned unchanged and then fails the
+    declared-model check by name, which is the honest outcome."""
+    o = (override or "").strip()
+    return _REF_TO_ID.get(o.split("@", 1)[0].lower(), o)
+
+
+#: The operator's per-area model overrides. Each read is written out LITERALLY rather than
+#: composed from `area`, because `tests/test_provider_credential_env_bypass_guard.py` fails any
+#: env read through a computed name — it cannot see what a variable resolves to, so it cannot
+#: rule out a credential, and it is default-deny by design. These are model names, not secrets,
+#: but the right answer to that guard is to make the read readable, not to file an exemption.
+_OVERRIDE_READS = {
+    "IMAGE_MODEL": lambda: envvar("IMAGE_MODEL", ""),
+    "VIDEO_MODEL": lambda: envvar("VIDEO_MODEL", ""),
+    "SPEECH_MODEL": lambda: envvar("SPEECH_MODEL", ""),
+    "VOICE_CLONE_MODEL": lambda: envvar("VOICE_CLONE_MODEL", ""),
+    "MUSIC_MODEL": lambda: envvar("MUSIC_MODEL", ""),
+}
+
+
+def model_override(area: str) -> str:
+    """The operator's env override for one area, e.g. `IMAGE_MODEL` -> $FRUTEBOX_IMAGE_MODEL.
+
+    Returns "" when unset, so `resolve_media_model` takes the plan's preference order. Read at
+    CALL time rather than at module import: a test and an operator can both change it without
+    reloading the process. An unknown area returns "" rather than raising — a missing override
+    is the same as no override.
+    """
+    read = _OVERRIDE_READS.get(area)
+    return ((read() if read else "") or "").strip()