frutebox-node 0.1.0__py3-none-any.whl

frutebox/registry/__init__.py

@@ -0,0 +1,189 @@
+"""FILE 09-B — registry enforcement: licence gates, geo-fencing, representation invariant.
+
+The registry (registry/models.yaml → registry_gen.py) declares; this module ENFORCES:
+
+  serving_allowed()   — licence gate: non-commercial/verify never serve; paid-commercial
+                        serves only under its signed FRUTEBOX_LICENSE_<VENDOR>_AGREED env
+                        (the STEVAI_ spelling is still read, second).
+  territory_allows()  — geo-fence, BOTH directions (executing node's region AND the
+                        requesting user's region), fail-closed on unknowns.
+  check_representation() — the CI invariant: per tier, every big-three bloc the roster
+                        provides must keep ≥1 enabled model, and at least 2-of-3 overall
+                        (scoped to what the roster provides — a tier the roster only
+                        fills from one bloc is a tracked gap, not a permanent red CI).
+"""
+from __future__ import annotations
+
+import os
+
+from frutebox.envvars import NEW_PREFIX, OLD_PREFIX
+from frutebox.registry_gen import BY_ID, REGISTRY
+
+#: 09-B1 — the known landmine list, asserted absent from every serving surface.
+LANDMINES = frozenset({
+    "codestral-22b", "xtts-v2", "flux1-dev", "flux2-dev", "flux-pro", "musicgen",
+    "lg-exaone", "cohere-command-r-plus", "nvidia-sana", "suno", "udio", "ox-alpha",
+})
+
+_BIG3 = ("eu", "us", "cn")
+
+#: 09-B3 — the roster's own per-tier accounting of which big-three blocs provide a quality
+#: model (frutebox-plan1-model-roster-balanced.md v1.3, balance-check lines). Hard-coded so
+#: DELETING a bloc's models from models.yaml cannot silently lower the floor — the
+#: criterion is that removing the only US frontier model FAILS, not that the requirement
+#: vanishes with it. Known gaps (video-EU, music, tts, stt, transparency-CN) are the
+#: roster's flagged gaps, tracked there, not CI failures here.
+TIER_BASELINE: dict[str, frozenset] = {
+    "frontier": frozenset({"eu", "us", "cn"}),
+    "mid": frozenset({"eu", "us", "cn"}),
+    "small": frozenset({"eu", "us", "cn"}),
+    "coding": frozenset({"eu", "us", "cn"}),
+    "reasoning": frozenset({"eu", "us", "cn"}),
+    "multimodal": frozenset({"eu", "us", "cn"}),
+    "transparency": frozenset({"eu", "us"}),
+    "image": frozenset({"eu", "us", "cn"}),
+    "video": frozenset({"us", "cn"}),
+    "music": frozenset({"cn"}),
+    "tts": frozenset({"us"}),
+    "stt": frozenset({"us"}),
+    "voice": frozenset({"eu", "us", "cn"}),
+}
+_ENABLED_STATUSES = {"default", "backup", "emerging"}
+_ENABLED_CLASSES = {"apache_mit", "open_commercial", "geo_fenced"}
+
+
+def serving_allowed(model_id: str, env: dict | None = None) -> bool:
+    """May this model appear in a serving manifest / be offered at routing?
+
+    Unknown ids are ALLOWED here — the registry gates roster models; serving aliases
+    (ollama tags, the stevai-default wildcard) are governed by their catalog entry.
+    """
+    m = BY_ID.get(model_id)
+    if m is None:
+        return True
+    if m["license_class"] == "non_commercial" or m["status"] == "verify":
+        return False
+    if m["status"] == "emerging":
+        return False  # runtimes can't serve it yet — declared, never offered
+    if m["license_class"] == "paid_commercial":
+        e = env if env is not None else os.environ
+        # DUAL-READ, FRUTEBOX_ first — the same precedence as `envvars.env()`, including that an
+        # EMPTY new-name value counts as set and wins rather than falling through to the old one.
+        #
+        # This read ONLY the STEVAI_ name while the TypeScript half of this same gate
+        # (`video-models.ts`, `music-models.ts`) goes through `envVar()`, which is dual-read. So a
+        # deployment that set FRUTEBOX_LICENSE_STABILITY_AGREED — the name F-86 says to move to —
+        # got a TypeScript side that offered the model and a Python side that still refused it.
+        # Fail-closed, so not a licensing hole, but the two halves of one decision disagreeing
+        # about the name of the variable that decides it.
+        suffix = f"LICENSE_{m['vendor']}_AGREED"
+        new_name, old_name = NEW_PREFIX + suffix, OLD_PREFIX + suffix
+        raw = e[new_name] if new_name in e else e.get(old_name, "")
+        return str(raw).lower() == "true"
+    return True
+
+
+def region_bloc(region: str) -> str | None:
+    """Map a gateway region / country claim to a territory bloc tag. None = unknown."""
+    r = (region or "").strip().lower()
+    if not r:
+        return None
+    if r in ("eu", "us", "cn", "ca", "uk", "il", "uae", "jp", "kr", "za"):
+        return r
+    if r.startswith("eu-"):
+        return "eu"
+    if r.startswith("us-"):
+        return "us"
+    if r in ("gb",):
+        return "uk"
+    if r in ("ae",):
+        return "uae"
+    if len(r) == 2:  # bare ISO country code → EU membership decides the bloc
+        eu = {"at", "be", "bg", "hr", "cy", "cz", "dk", "ee", "fi", "fr", "de", "gr", "hu",
+              "ie", "it", "lv", "lt", "lu", "mt", "nl", "pl", "pt", "ro", "sk", "si", "es", "se"}
+        return "eu" if r in eu else r
+    return None
+
+
+def territory_allows(model_id: str, node_region: str, user_region: str) -> bool:
+    """09-B2 — the geo-fence, applied to BOTH the node and the user, fail-closed.
+
+    deny:      blocked when either side is inside a denied bloc — or UNKNOWN (an
+               unattributable region cannot be proven outside the fence).
+    allow_only: served only when BOTH sides are provably inside — unknown is outside.
+    Worldwide ({}): always allowed, regions irrelevant.
+    """
+    m = BY_ID.get(model_id)
+    if m is None:
+        return True
+    t = m.get("territory") or {}
+    if not t:
+        return True
+    sides = (region_bloc(node_region), region_bloc(user_region))
+    if "deny" in t:
+        denied = set(t["deny"])
+        return all(s is not None and s not in denied for s in sides)
+    if "allow_only" in t:
+        allowed = set(t["allow_only"])
+        return all(s is not None and s in allowed for s in sides)
+    return True
+
+
+def _enabled(m: dict) -> bool:
+    return m["status"] in _ENABLED_STATUSES and m["license_class"] in _ENABLED_CLASSES
+
+
+def representation_report(registry: list[dict] | None = None) -> dict[str, dict]:
+    """09-B3 — per tier: which big-three blocs the roster provides, which are enabled,
+    and every other-region bloc counted (the maximize-representation metric)."""
+    reg = registry if registry is not None else REGISTRY
+    tiers: dict[str, dict] = {}
+    for m in reg:
+        if m["tier"] == "utility":
+            continue  # parity-exempt, never licence-exempt
+        t = tiers.setdefault(m["tier"], {"provided": set(), "enabled": set(), "other": {}})
+        # "Provided" counts only entries that COULD serve: a bloc represented solely by a
+        # named exclusion (a landmine like xtts-v2, or an unresolved verify) is not
+        # provided by the roster — it is documented as unusable. Paid/geo-fenced count as
+        # provided (they serve under their gates).
+        could_serve = m["status"] != "verify" and m["license_class"] != "non_commercial"
+        if m["bloc"] in _BIG3:
+            if could_serve:
+                t["provided"].add(m["bloc"])
+            if _enabled(m):
+                t["enabled"].add(m["bloc"])
+        elif _enabled(m):
+            t["other"][m["bloc"]] = t["other"].get(m["bloc"], 0) + 1
+    return tiers
+
+
+def check_representation(registry: list[dict] | None = None) -> list[str]:
+    """The CI gate: failures as human sentences; empty list = invariant holds.
+
+    Judged against TIER_BASELINE (what the roster says the field provides), so neither
+    disabling nor DELETING a bloc's models can pass silently."""
+    failures: list[str] = []
+    report = representation_report(registry)
+    for tier, baseline in sorted(TIER_BASELINE.items()):
+        enabled = report.get(tier, {}).get("enabled", set())
+        for bloc in sorted(baseline - enabled):
+            failures.append(
+                f"tier '{tier}': the roster provides a {bloc.upper()} model but none is enabled")
+        if len(baseline) >= 2 and len(enabled) < 2:
+            failures.append(
+                f"tier '{tier}': below the 2-of-3 floor ({len(enabled)} of "
+                f"{len(baseline)} baseline big-three blocs enabled)")
+    return failures
+
+
+def landmines_referenced(serving_ids: list[str]) -> list[str]:
+    """09-B1 — landmine or non-commercial ids referenced by a serving surface."""
+    bad: list[str] = []
+    for mid in serving_ids:
+        if mid in LANDMINES:
+            bad.append(mid)
+            continue
+        m = BY_ID.get(mid)
+        if m and (m["license_class"] == "non_commercial" or m["status"] == "verify"):
+            bad.append(mid)
+    return bad

frutebox/registry/generate.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""FILE 09-A2 — registry codegen: models.yaml → TS + Python + JSON artifacts.
+
+One source of truth, three consumers, zero drift: the web catalog, the Python serving
+stack, and a canonical JSON the round-trip tests compare both against. Deterministic —
+same input, byte-identical output — so `git diff` after a regen IS the drift check.
+
+Run from the repo root:  python -m frutebox.registry.generate
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+
+import yaml
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+YAML_PATH = ROOT / "frutebox" / "registry" / "models.yaml"
+JSON_PATH = ROOT / "frutebox" / "registry" / "registry.gen.json"
+PY_PATH = ROOT / "frutebox" / "registry_gen.py"
+TS_PATH = ROOT / "web" / "src" / "lib" / "model-registry.gen.ts"
+
+REQUIRED = ("id", "bloc", "tier", "license", "license_class", "territory",
+            "local_class", "status", "runtime", "vram_gb")
+
+#: FILE 11-B2 — `speed`, OPTIONAL and validated when present.
+#:
+#: Plan 11 names this as "Registry field (file 09)", and it was the one field the plan asks for that
+#: the registry did not have: `speed: {spec_decode, draft_model, K}`. Speculative decoding is
+#: quality-lossless and roughly 2-3x on decode, so which method a model can use is a FACT ABOUT THE
+#: MODEL — it belongs beside its runtime and its VRAM, not in a serving module's private table, or
+#: the serving stack and the registry would disagree about the same model.
+#:
+#: Optional rather than required because most of the roster has no head and no suitable draft model,
+#: and a required field would be filled with `none` 90 times to satisfy a validator. Absent means
+#: `none`, which `speed_of()` returns.
+SPEC_DECODE = {
+    # EAGLE-3 with P-EAGLE parallel drafting: a pre-trained head exists for this model.
+    "p-eagle",
+    # EAGLE-3 without parallel drafting (an older vLLM/SGLang, or parallel drafting unavailable).
+    "eagle3",
+    # No head: a small model from the same family drafts for the big one.
+    "draft",
+    # llama.cpp's multi-token prediction, for GGUF targets.
+    "mtp",
+    "none",
+}
+#: 11-B2's measured optimum for P-EAGLE. Carried per model so a model that wants a different K can
+#: say so, rather than the number being a constant three call sites deep.
+DEFAULT_SPEC_K = 7
+#: `in` and `ru` added 2026-10-10. `in` is India, for Maya Research's `maya1` — the roster's claim is
+#: global representation and the set of blocs it can express is part of that claim. `ru` exists only so
+#: `kandinsky-5.0` can be CATALOGUED while it waits on an owner governance decision: a row that cannot
+#: name its own origin cannot record why it is being held.
+BLOCS = {"eu", "us", "cn", "ca", "uk", "il", "uae", "jp", "kr", "za", "in", "ru", "community"}
+TIERS = {"frontier", "mid", "small", "coding", "reasoning", "multimodal", "transparency",
+         "utility", "voice", "image", "video", "music", "tts", "stt"}
+LICENSE_CLASSES = {"apache_mit", "open_commercial", "geo_fenced", "paid_commercial", "non_commercial"}
+STATUSES = {"default", "backup", "emerging", "verify"}
+
+
+def load() -> list[dict]:
+    with open(YAML_PATH, encoding="utf-8") as f:
+        entries = yaml.safe_load(f)
+    if not isinstance(entries, list) or not entries:
+        raise SystemExit("models.yaml: expected a non-empty list")
+    seen: set[str] = set()
+    for e in entries:
+        for k in REQUIRED:
+            if k not in e:
+                raise SystemExit(f"{e.get('id', '?')}: missing field {k}")
+        if e["id"] in seen:
+            raise SystemExit(f"duplicate id {e['id']}")
+        seen.add(e["id"])
+        if e["bloc"] not in BLOCS:
+            raise SystemExit(f"{e['id']}: unknown bloc {e['bloc']}")
+        if e["tier"] not in TIERS:
+            raise SystemExit(f"{e['id']}: unknown tier {e['tier']}")
+        if e["license_class"] not in LICENSE_CLASSES:
+            raise SystemExit(f"{e['id']}: unknown license_class {e['license_class']}")
+        if e["status"] not in STATUSES:
+            raise SystemExit(f"{e['id']}: unknown status {e['status']}")
+        if e["local_class"] not in ("L", "W", "S", None):
+            raise SystemExit(f"{e['id']}: unknown local_class {e['local_class']}")
+        _check_origin_risk(e)
+        if e["license_class"] == "paid_commercial" and not e.get("vendor"):
+            raise SystemExit(f"{e['id']}: paid_commercial requires a vendor (env-gate key)")
+        t = e["territory"] or {}
+        if not isinstance(t, dict) or any(k not in ("deny", "allow_only") for k in t):
+            raise SystemExit(f"{e['id']}: territory must be {{}}, {{deny:[...]}} or {{allow_only:[...]}}")
+        _check_speed(e)
+        _check_source(e)
+    return entries
+
+
+#: What a `source` block may contain. A pinned, RESOLVABLE place to get the weights — nothing about
+#: how to serve them, which is `serving.py`'s business and varies by engine.
+SOURCE_KEYS = {"hf_repo", "revision", "ollama_tag", "ollama_digest", "gated",
+               "gguf_repo", "gguf_revision", "gguf_quant"}
+
+
+def _check_source(e: dict) -> None:
+    """28 §B — an enabled model must have a PINNED source, or say honestly that it has none.
+
+    WHAT THIS CLOSES, measured 2026-10-01: of 29 enabled models, **25 could not be served at all** —
+    `serving.serving_spec()` returned a recipe with an empty command, because the only sources that
+    existed were two hand-maintained dicts in `serving.py` covering four models. Every other enabled
+    model was in the catalog, offered by routing, and unservable. All three enabled EMBEDDING models
+    were among them, which is why `/v1/embeddings` failed fleet-wide with `HTTPStatusError`.
+
+    And the four that did work were pinned to a REPO and not to a REVISION, so what they served was
+    whatever `main` happened to be that day.
+
+    THE RULES, each of which is a failure that actually happened or was one edit away:
+
+    * an enabled model (`default`/`backup`) carries `source` or `source_unavailable` — never neither,
+      because "neither" is how 25 models sat in the catalog looking fine;
+    * a revision is a full 40-character sha. A tag or a branch is not a pin: `revision: main` reads
+      like one and moves under you;
+    * an `ollama_tag` comes with an `ollama_digest`, for the same reason — `qwen3:8b` is republished;
+    * `source` and `source_unavailable` are mutually exclusive. A model cannot both have weights and
+      not have them, and a stale `source_unavailable` beside a working source is worse than either.
+    """
+    import re as _re
+
+    src, gone = e.get("source"), e.get("source_unavailable")
+    if src is not None and gone is not None:
+        raise SystemExit(f"{e['id']}: has BOTH source and source_unavailable — pick one")
+    if e["status"] in ("default", "backup") and src is None and gone is None:
+        raise SystemExit(
+            f"{e['id']}: status {e['status']!r} but no source and no source_unavailable. An enabled "
+            f"model with no pinned source is in the catalog, offered by routing, and unservable — "
+            f"that was true of 25 of 29 enabled models on 2026-10-01. Pin a source, or say in "
+            f"`source_unavailable` why there is none.")
+    if src is None:
+        return
+    if not isinstance(src, dict) or not src:
+        raise SystemExit(f"{e['id']}: source must be a non-empty mapping")
+    unknown = set(src) - SOURCE_KEYS
+    if unknown:
+        raise SystemExit(f"{e['id']}: unknown source key(s) {sorted(unknown)}; "
+                         f"known: {', '.join(sorted(SOURCE_KEYS))}")
+    if not any(src.get(k) for k in ("hf_repo", "ollama_tag", "gguf_repo")):
+        raise SystemExit(f"{e['id']}: source names no place to get the weights "
+                         f"(needs hf_repo, ollama_tag or gguf_repo)")
+    for repo_key, rev_key in (("hf_repo", "revision"), ("gguf_repo", "gguf_revision")):
+        if src.get(repo_key) and not src.get(rev_key):
+            raise SystemExit(f"{e['id']}: {repo_key} without {rev_key} — an unpinned repo serves "
+                             f"whatever `main` is today")
+        rev = src.get(rev_key)
+        if rev and not _re.fullmatch(r"[0-9a-f]{40}", str(rev)):
+            raise SystemExit(f"{e['id']}: {rev_key} {rev!r} is not a full 40-character sha. A tag or "
+                             f"a branch name is not a pin.")
+    if src.get("ollama_tag") and not str(src.get("ollama_digest") or "").startswith("sha256:"):
+        raise SystemExit(f"{e['id']}: ollama_tag without a sha256 ollama_digest — a tag is "
+                         f"republished, so the tag alone does not name what was tested")
+    if "gated" in src and not isinstance(src["gated"], bool):
+        raise SystemExit(f"{e['id']}: source.gated must be true/false")
+
+
+def _check_speed(e: dict) -> None:
+    """Validate 11-B2's `speed` block. Absent is fine; wrong is not.
+
+    The two rules that matter are the ones a typo would otherwise turn into silent slowness: a
+    method this stack cannot spell does nothing at all (the flag is ignored by the engine, and the
+    pod serves at 1x while the registry claims 2-3x), and `spec_decode: draft` without a
+    `draft_model` is a configuration that cannot start.
+    """
+    sp = e.get("speed")
+    if sp is None:
+        return
+    if not isinstance(sp, dict) or any(k not in ("spec_decode", "draft_model", "K") for k in sp):
+        raise SystemExit(f"{e['id']}: speed must be {{spec_decode, draft_model?, K?}}")
+    method = sp.get("spec_decode", "none")
+    if method not in SPEC_DECODE:
+        raise SystemExit(f"{e['id']}: unknown spec_decode {method!r}; "
+                         f"known: {', '.join(sorted(SPEC_DECODE))}")
+    if method == "draft" and not str(sp.get("draft_model") or "").strip():
+        raise SystemExit(f"{e['id']}: spec_decode 'draft' needs a draft_model — a draft method with "
+                         f"nothing to draft with cannot start")
+    if sp.get("draft_model") and method in ("none", "mtp"):
+        # `mtp` predicts from the target's own extra heads and `none` predicts nothing, so neither
+        # has anything to point a draft model at. An ignored field reads as a promise.
+        raise SystemExit(f"{e['id']}: draft_model is meaningless with spec_decode {method!r}")
+    #: THE HEAD PATH FOR EAGLE3 IS NOT IN THIS FILE, ON PURPOSE. SGLang wants
+    #: `--speculative-draft-model-path <head repo>`, and the head is a separate artefact published
+    #: per target model. Guessing a repo name here would produce a pod that fails to start (or worse,
+    #: one that starts with the wrong head), so `serving.py` reads it from configuration and leaves
+    #: speculative decoding OFF, loudly, until it is set. `speed.draft_model` may still name it when
+    #: it is known.
+    k = sp.get("K", DEFAULT_SPEC_K)
+    if not isinstance(k, int) or not 1 <= k <= 16:
+        raise SystemExit(f"{e['id']}: speed.K must be an int in 1..16 (11-B2 measures 7 as optimal)")
+
+
+#: The owner's at-your-own-risk flag (2026-10-13). Three facts, and the SENTENCE is composed here
+#: rather than written per model: the catalog listing, the artifact and the governance record must
+#: all say the same thing, and three surfaces each building their own string is how the music roster
+#: and the licence-gate variable name came apart.
+ORIGIN_RISK_KEYS = {"origin", "name", "reason"}
+
+
+def _check_origin_risk(e: dict) -> None:
+    r = e.get("origin_risk")
+    if r is None:
+        return
+    if not isinstance(r, dict):
+        raise SystemExit(f"{e['id']}: origin_risk must be a mapping")
+    missing = ORIGIN_RISK_KEYS - set(r)
+    if missing:
+        raise SystemExit(f"{e['id']}: origin_risk is missing {sorted(missing)}")
+    extra = set(r) - ORIGIN_RISK_KEYS
+    if extra:
+        # A field nobody composes is a field nobody renders. Refused rather than carried.
+        raise SystemExit(f"{e['id']}: origin_risk has unknown key(s) {sorted(extra)}")
+    if r["origin"] not in BLOCS:
+        raise SystemExit(f"{e['id']}: origin_risk.origin {r['origin']!r} is not a known bloc")
+    for k in ("name", "reason"):
+        if not str(r[k]).strip():
+            raise SystemExit(f"{e['id']}: origin_risk.{k} is empty")
+    # The risk is ABOUT the model's own origin; a flag naming a different bloc from `bloc` would
+    # make the two fields disagree about where the model comes from.
+    if r["origin"] != e["bloc"]:
+        raise SystemExit(
+            f"{e['id']}: origin_risk.origin {r['origin']!r} != bloc {e['bloc']!r}")
+
+
+def origin_disclosure(risk: dict) -> str:
+    """THE one sentence, in the owner's words (2026-10-13).
+
+    Composed from the row's facts so a second flagged model gets the same shape automatically, and
+    so no surface can paraphrase it. The em dash is the owner's.
+    """
+    return f"Generated with {risk['name']} ({risk['reason']}) — use at your own risk"
+
+
+def emit(entries: list[dict]) -> None:
+    canon = [
+        {
+            "id": e["id"], "bloc": e["bloc"], "tier": e["tier"], "license": e["license"],
+            "license_class": e["license_class"], "territory": e["territory"] or {},
+            "local_class": e["local_class"], "status": e["status"],
+            "runtime": list(e["runtime"] or []), "vram_gb": e["vram_gb"],
+            **({"vendor": e["vendor"]} if e.get("vendor") else {}),
+            # Emitted only when present, so the 96 models without a head do not each carry a
+            # `speed: {spec_decode: none}` that says nothing. `speed_of()` supplies the default.
+            **({"speed": {k: e["speed"][k] for k in sorted(e["speed"])}} if e.get("speed") else {}),
+            # 28 §B — the PINNED source travels with the model, so a consumer resolving weights reads
+            # the same fact the catalog was validated against instead of its own table. `serving.py`
+            # kept its own, and 25 of 29 enabled models were missing from it.
+            **({"source": {k: e["source"][k] for k in sorted(e["source"])}} if e.get("source") else {}),
+            **({"source_unavailable": " ".join(str(e["source_unavailable"]).split())}
+               if e.get("source_unavailable") else {}),
+            **({"source_notes": " ".join(str(e["source_notes"]).split())}
+               if e.get("source_notes") else {}),
+            # The flag, WITH the composed sentence. Consumers render `disclosure` verbatim rather
+            # than rebuilding it — the `edit_notice` arrangement: the thing that knows supplies the
+            # words, and the surface that shows them does not get to reword them.
+            **({"origin_risk": {**{k: e["origin_risk"][k] for k in sorted(e["origin_risk"])},
+                                "disclosure": origin_disclosure(e["origin_risk"])}}
+               if e.get("origin_risk") else {}),
+        }
+        for e in entries
+    ]
+    blob = json.dumps(canon, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+    JSON_PATH.write_text(blob, encoding="utf-8")
+
+    PY_PATH.write_text(
+        '"""GENERATED by frutebox/registry/generate.py from registry/models.yaml — DO NOT EDIT."""\n'
+        "REGISTRY: list[dict] = " + repr(canon) + "\n"
+        "BY_ID: dict[str, dict] = {m['id']: m for m in REGISTRY}\n",
+        encoding="utf-8",
+    )
+
+    TS_PATH.write_text(
+        "// GENERATED by frutebox/registry/generate.py from frutebox/registry/models.yaml — DO NOT EDIT.\n"
+        "export type RegistryEntry = {\n"
+        "  id: string; bloc: string; tier: string; license: string; license_class: string;\n"
+        "  territory: { deny?: string[]; allow_only?: string[] };\n"
+        "  local_class: \"L\" | \"W\" | \"S\" | null; status: string; runtime: string[];\n"
+        "  vram_gb: number; vendor?: string;\n"
+        "  speed?: { spec_decode: string; draft_model?: string; K?: number };\n"
+        # 28 §B — the pinned source. All optional: a model may have one, may say why it has none, and
+        # `source_notes` records a problem that is neither (a wrong runtime declaration). Emitting the
+        # DATA without extending this type is what failed the web typecheck — the generator writes both
+        # halves, so they can only drift if one is forgotten.
+        "  source?: {\n"
+        "    hf_repo?: string; revision?: string;\n"
+        "    ollama_tag?: string; ollama_digest?: string;\n"
+        "    gguf_repo?: string; gguf_revision?: string; gguf_quant?: string;\n"
+        "    gated?: boolean;\n"
+        "  };\n"
+        "  source_unavailable?: string;\n"
+        "  source_notes?: string;\n"
+        # The owner's at-your-own-risk flag. `disclosure` is composed by the generator so every
+        # surface renders one string; emitting the DATA without extending this type is what failed
+        # the web typecheck when `source` was added.
+        "  origin_risk?: {\n"
+        "    origin: string; name: string; reason: string; disclosure: string;\n"
+        "  };\n"
+        "};\n"
+        "export const MODEL_REGISTRY: RegistryEntry[] = " + blob.rstrip("\n") + ";\n"
+        "export const REGISTRY_BY_ID: Record<string, RegistryEntry> =\n"
+        "  Object.fromEntries(MODEL_REGISTRY.map((m) => [m.id, m]));\n",
+        encoding="utf-8",
+    )
+    print(f"registry: {len(canon)} models → {JSON_PATH.name}, {PY_PATH.name}, {TS_PATH.name}")
+
+
+if __name__ == "__main__":
+    emit(load())

frutebox/registry/generate_providers.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""28 §A9 — provider registry codegen: providers.yaml → a TS artifact the web app can read.
+
+WHY THIS EXISTS AT ALL
+`Provider` rows in Neon are what `ProviderCredential.providerId` points at. Until 2026-09-22
+**nothing in the codebase had ever written one** — no upsert, no migration, no seed. The rows that
+existed were created by hand, so `providers.yaml` and the table could drift indefinitely, and the
+only symptom was a 500 with an empty body (`P2003`, foreign key violated) when someone tried to
+store a credential for a provider the table had never heard of. That is how `lambda` failed.
+
+WHY CODEGEN RATHER THAN READING THE YAML AT RUNTIME
+The web image is built with `web/` as its Docker context, so `frutebox/registry/providers.yaml` is
+not in the container and cannot be read there. The seeder runs inside the web service because that
+is the only service with `DATABASE_URL`. So the YAML has to travel as generated code — the same
+route `models.yaml` already takes (`generate.py` → `model-registry.gen.ts`).
+
+DELIBERATELY NOT EMITTED
+  * `env` — the credential NAMES. The table has no column for them; they stay in the YAML, which
+    is what `frutebox/providers.py` reads.
+  * `derived` — A TRAP, and the reason this is spelled out. In the YAML `derived` is a list of
+    NAMES TO DISCOVER from a credential (§A5: "the owner provides the credential; the code
+    discovers the rest"). In the database, `Provider.derivedJson` holds the DISCOVERED VALUES.
+    They are not the same thing in either direction, and syncing the first into the second would
+    overwrite real discovered ids with a list of labels.
+
+Run from the repo root:  python -m frutebox.registry.generate_providers
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+
+import yaml
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+YAML_PATH = ROOT / "frutebox" / "registry" / "providers.yaml"
+TS_PATH = ROOT / "web" / "src" / "lib" / "provider-registry.gen.ts"
+
+CLASSES = {"gpu", "compute", "tee", "weights"}
+#: `being_replaced` added 2026-10-16 (owner decision: Verda + Nebius replace RunPod). It describes
+#: a provider's ROLE, which is what this field is for — the same reason vast keeps `status: backup`
+#: while being `enabled: true`. It is deliberately NOT `disabled`: RunPod is still serving the EU
+#: media pods and is still the only funded fallback, so a status that read as "off" would be a
+#: lie on the way to becoming a self-fulfilling one.
+#:
+#: SAFE TO ADD because nothing branches on this value: the column is `String` (no Prisma enum, no
+#: migration), the generated TS types it as `string`, and `provider-seed.ts` — the only consumer of
+#: PROVIDER_REGISTRY — copies it through. Checked 2026-10-16, with the search proven on a
+#: known-present pattern first.
+#:
+#: ⚠️ FLAGGED FOR THE WEB LANE, not changed here: the doc comment on `Provider.status` in
+#: `web/prisma/schema.prisma:2972` still reads "active | backup | emerging | disabled" and is now
+#: one value short. It is a comment, not a constraint, and that file is not this lane's.
+STATUSES = {"active", "backup", "emerging", "disabled", "being_replaced"}
+
+
+def load() -> list[dict]:
+    doc = yaml.safe_load(YAML_PATH.read_text(encoding="utf-8")) or {}
+    rows = doc.get("providers") or []
+    if not isinstance(rows, list) or not rows:
+        raise SystemExit("providers.yaml: expected a non-empty `providers:` list")
+
+    held = set(doc.get("on_hold") or [])
+    seen: set[str] = set()
+    out = []
+    for r in rows:
+        pid = str(r.get("id") or "")
+        if not pid:
+            raise SystemExit("a provider row has no id")
+        if pid in seen:
+            raise SystemExit(f"duplicate provider id {pid}")
+        seen.add(pid)
+        # An on-hold provider must not be a row here either: `test_on_hold_providers_are_not_
+        # rows_at_all` requires their ABSENCE so they cannot be enabled by flipping a flag, and
+        # generating one would smuggle it into the database by the back door.
+        if pid in held:
+            raise SystemExit(f"{pid} is in on_hold AND has a provider row — one of the two is wrong")
+        cls = str(r.get("class", "gpu"))
+        if cls not in CLASSES:
+            raise SystemExit(f"{pid}: unknown class {cls}")
+        status = str(r.get("status", "backup"))
+        if status not in STATUSES:
+            raise SystemExit(f"{pid}: unknown status {status}")
+        out.append({
+            "id": pid,
+            "cls": cls,
+            "status": status,
+            "enabled": bool(r.get("enabled", False)),
+            "phase": int(r.get("phase", 2)),
+            "hqCountry": str(r.get("hq_country", "") or ""),
+            "regions": [str(x) for x in (r.get("regions") or [])],
+            "apiBase": str(r.get("api_base", "") or ""),
+            "capabilities": r.get("capabilities") or {},
+            "notes": str(r.get("notes", "") or "").strip(),
+        })
+    return sorted(out, key=lambda x: x["id"])
+
+
+def emit(rows: list[dict]) -> None:
+    blob = json.dumps(rows, indent=2, sort_keys=True, ensure_ascii=False)
+    TS_PATH.write_text(
+        "// GENERATED by frutebox/registry/generate_providers.py from\n"
+        "// frutebox/registry/providers.yaml — DO NOT EDIT.\n"
+        "//\n"
+        "// The shape the seeder writes into the `Provider` table. `env` and `derived` are\n"
+        "// deliberately absent: the table has no column for credential names, and the YAML's\n"
+        "// `derived` is a list of names to DISCOVER while the column holds DISCOVERED VALUES.\n"
+        "export type ProviderSeedRow = {\n"
+        "  id: string; cls: string; status: string; enabled: boolean; phase: number;\n"
+        "  hqCountry: string; regions: string[]; apiBase: string;\n"
+        "  capabilities: Record<string, unknown>; notes: string;\n"
+        "};\n"
+        "export const PROVIDER_REGISTRY: ProviderSeedRow[] = " + blob + ";\n",
+        encoding="utf-8",
+    )
+    print(f"providers: {len(rows)} → {TS_PATH.relative_to(ROOT)}")
+
+
+if __name__ == "__main__":
+    emit(load())