openchar-core 1.3.17__py3-none-any.whl

inline_core/__init__.py

@@ -0,0 +1,14 @@
+"""Inline Core: the generation engine behind Inline.
+
+Takes a typed node graph and returns immutable takes. See PLAN.md for the architecture and
+docs/contract.md for the Storyline API.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    #: Resolved from the installed package, so pyproject.toml stays the only place a release is
+    #: bumped. An editable install records this at install time; reinstall after bumping.
+    __version__ = version("openchar-core")
+except PackageNotFoundError:  # a source tree that was never installed
+    __version__ = "0.0.0"

inline_core/characters/__init__.py

@@ -0,0 +1,35 @@
+"""Persistent characters: the ``.char`` container, its compiled payloads, and identity scoring."""
+
+from .charfile import (
+    FORMAT_VERSION,
+    MAGIC,
+    SIGNATURE,
+    CharDoc,
+    CharFileError,
+    Manifest,
+    centroid_valid,
+    looks_like_char,
+    member_name,
+    payload_valid,
+    read,
+    refs_fingerprint,
+    sha256_bytes,
+    write,
+)
+
+__all__ = [
+    "FORMAT_VERSION",
+    "MAGIC",
+    "SIGNATURE",
+    "CharDoc",
+    "CharFileError",
+    "Manifest",
+    "centroid_valid",
+    "looks_like_char",
+    "member_name",
+    "payload_valid",
+    "read",
+    "refs_fingerprint",
+    "sha256_bytes",
+    "write",
+]

inline_core/characters/apply.py

@@ -0,0 +1,311 @@
+"""``char_apply``: a character turned into the references and prompt text a run needs.
+
+Payload PNGs are extracted from the zip once, keyed by content hash so an edit lands in a new
+directory rather than mutating one a running graph is reading.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from ..config import data_dir
+from ..takes import AssetRef
+from . import charfile as cf
+from . import encode, library
+
+logger = logging.getLogger("inline_core.characters")
+
+#: Extracted payload bytes to keep. Tiny next to a checkpoint, so this holds many characters.
+_CACHE_LIMIT_BYTES = 2 * 1024**3
+
+
+class AppliedCharacter:
+    """What a runner needs: ordered reference handles, plus the prompt text that names them."""
+
+    def __init__(
+        self,
+        name: str,
+        refs: list[AssetRef],
+        description: str,
+        lora: Path | None = None,
+        lora_strength: float = 1.0,
+        roles: list[str] | None = None,
+    ) -> None:
+        self.name = name
+        self.refs = refs
+        self.description = description
+        #: One role per ref, in the same order. All face when a character predates roles, which is
+        #: what keeps an old character's prompt byte-identical to what it used to produce.
+        self.roles = roles or [cf.ROLE_FACE] * len(refs)
+        #: A trained adapter, which for a model with no reference channel is the only route.
+        self.lora = lora
+        #: What it fuses at. Set on Attach Adapter, because an overfit adapter is only usable
+        #: turned down and the character wire carries no controls of its own.
+        self.lora_strength = lora_strength
+
+    def _role_lines(self, first_position: int, style: str) -> str:
+        """Sentences binding each role to the positions it actually landed on.
+
+        Written from the allocation rather than alongside it, so the numbers cannot drift from the
+        references. Silent when everything is face: an old character keeps its exact prompt.
+        """
+        grouped: dict[str, list[int]] = {}
+        for offset, role in enumerate(self.roles[: len(self.refs)]):
+            grouped.setdefault(role, []).append(first_position + offset)
+        if set(grouped) <= {cf.ROLE_FACE}:
+            return ""
+        out = ""
+        for role in cf.ROLES:
+            numbers = grouped.get(role)
+            if numbers:
+                verb = "shows" if len(numbers) == 1 else "show"
+                out += f" {_positions(style, numbers)} {verb} {self.name}'s {_ROLE_BINDINGS[role]}."
+        return out
+
+    def prompt_prefix(
+        self, first_position: int, style: str = "ordinal", role_lines: bool = False
+    ) -> str:
+        """Text naming the positions the character lands on, so positional prompting resolves.
+
+        ``style`` because a model only resolves the form it was trained on: FLUX.2 reads the ordinal
+        prose below, MiniMax H3 reads ``<Picture N>`` tokens (``models/references.py``), Seedance
+        2.0 reads ``@ImageN``, and handing any of them another names positions it cannot see.
+
+        ``role_lines`` defaults off: the bindings are unvalidated, see docs/characters.md.
+        """
+        if not self.refs:
+            # A LoRA carries the likeness, so the description is all the prompt needs.
+            detail = " ".join(self.description.split())
+            return f"{detail} " if detail else ""
+        positions = [first_position + i for i in range(len(self.refs))]
+        if style == "token":
+            tokens = " ".join(f"<Picture {n}>" for n in positions)
+            plural = "" if len(positions) == 1 else "each"
+            which = f"{tokens} {'shows' if not plural else 'show'}"
+        elif style == "at-image":
+            # Seedance's own addressing syntax, so each position is declared exactly once here.
+            tokens = [f"@Image{n}" for n in positions]
+            if len(tokens) == 1:
+                which = f"{tokens[0]} shows"
+            else:
+                which = f"{', '.join(tokens[:-1])} and {tokens[-1]} show"
+        elif len(positions) == 1:
+            which = f"Image {positions[0]} shows"
+        else:
+            ordinals = [str(n) for n in positions]
+            which = f"Images {', '.join(ordinals[:-1])} and {ordinals[-1]} show"
+        line = f"{which} {self.name}, the same character in every image."
+        if role_lines:
+            line += self._role_lines(first_position, style)
+        detail = " ".join(self.description.split())
+        if not detail:
+            return f"{line} "
+        # Prose, not comma tags: without this it runs into the user's prompt unpunctuated.
+        if detail[-1] not in ".!?":
+            detail += "."
+        return f"{line} {detail} "
+
+
+def _positions(style: str, numbers: list[int]) -> str:
+    """How a role line refers *back* to positions, in prose, never re-declaring them."""
+    # Never `<Picture N>` or `@ImageN`: a reserved label repeated replayed the references on H3, and
+    # nothing has established that Seedance treats a second `@ImageN` as a reference either.
+    noun = "Picture" if style == "token" else "Image"
+    if len(numbers) == 1:
+        return f"{noun} {numbers[0]}"
+    return f"{noun}s {', '.join(str(n) for n in numbers[:-1])} and {numbers[-1]}"
+
+
+#: What each role binds to. Naming only, never describing: "slim build" or "red jacket" would be
+#: text competing with the reference images, which is the caption-overrides-identity failure the
+#: LoRA evals already found.
+_ROLE_BINDINGS = {
+    cf.ROLE_FACE: "face",
+    cf.ROLE_BODY: "full body and build",
+    cf.ROLE_CLOTH: "outfit",
+}
+
+
+def _cache_root() -> Path:
+    return data_dir() / "characters"
+
+
+def char_apply(
+    chosen: str,
+    arch: str = encode.FLUX2_KLEIN_ARCH,
+    prefer: str | None = None,
+    limit: int | None = None,
+    keep_roles: tuple[str, ...] | None = None,
+    select: Sequence[int] | None = None,
+) -> AppliedCharacter | None:
+    """How a character applies on ``arch``, or None when none is picked. An unreadable pick raises
+    rather than silently generating the wrong person.
+
+    ``arch`` matters because a model without a reference channel can only take the adapter, and its
+    payloads are keyed separately. ``keep_roles`` narrows which of them are sent at all, per render,
+    so testing a character face-only does not mean writing a second character. ``select`` names
+    individual references by position, which is what lets a sweep measure one reference's worth."""
+    name = str(chosen or "").strip()
+    if not name:
+        return None
+    path = library.resolve(name)
+    if path is None:
+        raise FileNotFoundError(
+            f"Character {name!r} is not in models/characters/. Pick another in the node's settings."
+        )
+
+    doc = cf.read(path)
+    digest = library.content_hash(path)
+    # Whether this arch reads references at all, which is exactly the archs with a policy for them.
+    references = arch in encode.REFERENCE_POLICIES
+
+    if references and not cf.payload_valid(doc.manifest, arch, encode.PAYLOAD_ENCODER_VERSION):
+        doc = _recompile(doc, path, arch)
+        digest = library.content_hash(path)
+
+    description = _description(doc)
+    lora = _extract_lora(doc, digest, arch)
+    strength = encode.lora_strength(doc.manifest, arch)
+    # A trained adapter wins unless the character says otherwise: the user asked for it explicitly,
+    # and loading both would apply the identity twice. `prefer` overrides both, for a node that can
+    # only run one way: H3's reference partition needs a reference and cannot use an adapter alone.
+    mode = prefer or doc.manifest.apply.get(arch) or ("lora" if lora else "reference")
+    # No reference channel on this arch, so the adapter is the only way it can apply at all.
+    if not references:
+        mode = "lora"
+    refs, roles = ([], []) if mode == "lora" else _extract(doc, digest, arch)
+    # Before the role filter and the cap, so both still divide over what was actually selected.
+    if select is not None:
+        chosen_indices = sorted({i for i in select if 0 <= i < len(refs)})
+        refs, roles = [refs[i] for i in chosen_indices], [roles[i] for i in chosen_indices]
+    if keep_roles is not None:
+        kept = [i for i, role in enumerate(roles) if role in keep_roles]
+        refs, roles = [refs[i] for i in kept], [roles[i] for i in kept]
+    if limit is not None:
+        refs, roles = _fit_roles(refs, roles, limit)
+    return AppliedCharacter(
+        doc.manifest.name or path.stem,
+        refs,
+        description,
+        lora if mode == "lora" else None,
+        strength,
+        roles=roles,
+    )
+
+
+def _fit_roles(
+    refs: list[AssetRef], roles: list[str], limit: int
+) -> tuple[list[AssetRef], list[str]]:
+    """Cut to what a model takes, dividing the slots by role rather than by arrival.
+
+    Trimming the tail instead would drop whichever role happens to be last, so a character with
+    face, body and cloth would silently lose its wardrobe on any model that takes fewer than it
+    holds. Order is preserved, because order is what the prompt numbers.
+    """
+    if limit >= len(refs) or limit <= 0:
+        return refs[: max(0, limit)], roles[: max(0, limit)]
+    counts = {role: roles.count(role) for role in cf.ROLES}
+    share = encode.allocate_roles(counts, limit)
+    keep: list[int] = []
+    taken = dict.fromkeys(cf.ROLES, 0)
+    for index, role in enumerate(roles):
+        if taken[role] < share.get(role, 0):
+            taken[role] += 1
+            keep.append(index)
+    return [refs[i] for i in keep], [roles[i] for i in keep]
+
+
+def _extract_lora(doc: cf.CharDoc, digest: str, arch: str) -> Path | None:
+    """The adapter for ``arch``, or None. A stale one is the wrong face, so it is ignored."""
+    entry = encode.lora_payload(doc.manifest, arch)
+    if not entry:
+        return None
+    key = encode.payload_key(arch, encode.PAYLOAD_LORA)
+    if not cf.payload_valid(doc.manifest, key, encode.LORA_PAYLOAD_VERSION):
+        logger.info("Ignoring a stale %s adapter for %s", arch, doc.manifest.name)
+        return None
+    files = [str(f.get("path")) for f in entry.get("files") or [] if f.get("path")]
+    if not files:
+        return None
+    root = _cache_root() / digest / key
+    target = root / Path(files[0]).name
+    if not target.is_file():
+        root.mkdir(parents=True, exist_ok=True)
+        data = doc.members.get(files[0])
+        if data is None:
+            return None
+        target.write_bytes(data)
+    return target
+
+
+def _description(doc: cf.CharDoc) -> str:
+    raw = doc.members.get(str(doc.manifest.text.get("path") or ""))
+    return raw.decode("utf-8", errors="replace") if raw else ""
+
+
+def _recompile(doc: cf.CharDoc, path: Path, arch: str = encode.FLUX2_KLEIN_ARCH) -> cf.CharDoc:
+    """Rebuild a stale payload from ``refs/``. Payloads are cache, so this always works."""
+    logger.info("Recompiling the %s payload for %s", arch, path.name)
+    import io
+
+    from PIL import Image
+
+    images: list[Any] = []
+    for ref in doc.manifest.refs:
+        raw = doc.members.get(str(ref.get("path")))
+        if raw is None:
+            raise cf.CharFileError(
+                f"{path.name} is missing reference {ref.get('path')}, so it cannot be rebuilt."
+            )
+        images.append(Image.open(io.BytesIO(raw)).convert("RGB"))
+
+    encode.build_payload(doc.manifest, doc.members, images, arch)
+    cf.write(path, doc)
+    return doc
+
+
+def _extract(doc: cf.CharDoc, digest: str, arch: str) -> tuple[list[AssetRef], list[str]]:
+    payload = doc.manifest.payloads.get(arch) or {}
+    entries = list(payload.get("files") or [])
+    files = [str(entry.get("path")) for entry in entries]
+    roles = [cf.role_of(entry) for entry in entries]
+    if not files:
+        return [], []
+
+    root = _cache_root() / digest
+    marker = root / ".complete"
+    if not marker.is_file():
+        staging = root.with_name(f"{digest}.part")
+        shutil.rmtree(staging, ignore_errors=True)
+        staging.mkdir(parents=True, exist_ok=True)
+        for member in files:
+            data = doc.members.get(member)
+            if data is None:
+                raise cf.CharFileError(f"Character payload is missing {member}.")
+            (staging / Path(member).name).write_bytes(data)
+        (staging / ".complete").write_text("ok")
+        shutil.rmtree(root, ignore_errors=True)
+        staging.replace(root)
+        _prune(_cache_root())
+
+    return [AssetRef(ref="path", path=str(root / Path(member).name)) for member in files], roles
+
+
+def _prune(root: Path) -> None:
+    """Oldest-first eviction against a size cap, the same shape as the prompt-embed cache."""
+    if not root.is_dir():
+        return
+    entries = sorted(
+        (p for p in root.iterdir() if p.is_dir()),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    total = 0
+    for entry in entries:
+        total += sum(f.stat().st_size for f in entry.rglob("*") if f.is_file())
+        if total > _CACHE_LIMIT_BYTES:
+            shutil.rmtree(entry, ignore_errors=True)

inline_core/characters/charfile.py

@@ -0,0 +1,270 @@
+"""The ``.char`` container: a persistent character as one portable zip.
+
+::
+
+    Ada.char
+      manifest.json           first member; the signature is at byte 0
+      refs/000.png            user-provided reference images, immutable
+      derived/face_000.png    auto-generated crops
+      text/description.md     the locked character description
+      payloads/<arch>/        compiled per model family, pure cache
+      scoring/                identity centroids, one per scoring encoder
+
+Refs and text are truth; payloads and centroids are cache, and must be regenerable from ``refs/``.
+Torch-free and network-free, so a core install can read a character.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+#: A reader refuses anything above this rather than half-loading the wrong face.
+FORMAT_VERSION = 1
+
+MAGIC = "INLINECHAR"
+
+#: Valid JSON *and* a signature, so a file is identifiable from 32 bytes without parsing.
+SIGNATURE = f'{{"magic":"{MAGIC}","format_version":'.encode()
+
+MANIFEST_NAME = "manifest.json"
+
+#: Fixed so the signature lands at byte 0 and two writes produce identical bytes.
+_KEY_ORDER = (
+    "magic", "format_version", "char_id", "name", "created_at", "modified_at", "app",
+    "app_version", "refs", "derived", "text", "payloads", "scoring", "hints", "apply", "reserved",
+)
+
+
+#: Where a reference came from. Nested inside `refs` rather than a new top-level key on purpose:
+#: `from_json` models only the keys it knows, so a top-level addition is destroyed by any older
+#: build that rewrites the file, and three code paths rewrite one routinely.
+ORIGIN_ORIGINAL = "original"
+ORIGIN_HARVESTED = "harvested"
+
+
+def origin_of(ref: dict[str, Any]) -> str:
+    """Absent means original: every reference written before harvesting existed is one."""
+    return str(ref.get("origin") or ORIGIN_ORIGINAL)
+
+
+#: What a reference is *of*. Sits beside `origin` for the same reason, and absent means face, so
+#: every character written before roles existed keeps behaving exactly as it did.
+ROLE_FACE = "face"
+ROLE_BODY = "body"
+ROLE_CLOTH = "cloth"
+ROLES = (ROLE_FACE, ROLE_BODY, ROLE_CLOTH)
+
+
+def role_of(ref: dict[str, Any]) -> str:
+    """A reference's role, defaulting to face. An unknown value reads as face rather than raising:
+    a manifest is user data, and refusing to open a character over one bad string helps nobody."""
+    role = str(ref.get("role") or ROLE_FACE)
+    return role if role in ROLES else ROLE_FACE
+
+
+def by_role(refs: list[dict[str, Any]], role: str) -> list[dict[str, Any]]:
+    """The references carrying one role, in manifest order."""
+    return [ref for ref in refs if role_of(ref) == role]
+
+
+class CharFileError(Exception):
+    """A ``.char`` that cannot be trusted. The message is shown to the user."""
+
+
+@dataclass
+class Manifest:
+    char_id: str
+    name: str
+    created_at: int
+    modified_at: int
+    app_version: str = ""
+    refs: list[dict[str, Any]] = field(default_factory=list)
+    derived: list[dict[str, Any]] = field(default_factory=list)
+    text: dict[str, Any] = field(default_factory=dict)
+    payloads: dict[str, Any] = field(default_factory=dict)
+    scoring: dict[str, Any] = field(default_factory=dict)
+    hints: list[str] = field(default_factory=list)
+    #: arch -> "reference" | "lora". Absent means "whatever this model does best", resolved at
+    #: apply time, so an older file needs no migration.
+    apply: dict[str, str] = field(default_factory=dict)
+    reserved: dict[str, Any] = field(
+        default_factory=lambda: {"adapters": {}, "video_payloads": {}, "members": []}
+    )
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "magic": MAGIC,
+            "format_version": FORMAT_VERSION,
+            "char_id": self.char_id,
+            "name": self.name,
+            "created_at": self.created_at,
+            "modified_at": self.modified_at,
+            "app": "inline-studio",
+            "app_version": self.app_version,
+            "refs": self.refs,
+            "derived": self.derived,
+            "text": self.text,
+            "payloads": self.payloads,
+            "scoring": self.scoring,
+            "hints": self.hints,
+            "apply": self.apply,
+            "reserved": self.reserved,
+        }
+
+    @classmethod
+    def from_json(cls, raw: dict[str, Any]) -> Manifest:
+        return cls(
+            char_id=str(raw.get("char_id", "")),
+            name=str(raw.get("name", "")),
+            created_at=int(raw.get("created_at", 0)),
+            modified_at=int(raw.get("modified_at", 0)),
+            app_version=str(raw.get("app_version", "")),
+            refs=list(raw.get("refs") or []),
+            derived=list(raw.get("derived") or []),
+            text=dict(raw.get("text") or {}),
+            payloads=dict(raw.get("payloads") or {}),
+            scoring=dict(raw.get("scoring") or {}),
+            hints=list(raw.get("hints") or []),
+            apply={str(k): str(v) for k, v in (raw.get("apply") or {}).items()},
+            reserved=dict(raw.get("reserved") or {}),
+        )
+
+
+@dataclass
+class CharDoc:
+    """A whole character in memory: the manifest plus every member's bytes."""
+
+    manifest: Manifest
+    members: dict[str, bytes] = field(default_factory=dict)
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def member_name(prefix: str, index: int, suffix: str) -> str:
+    """``refs/000.png`` - always ASCII, since a user's filename may not extract on Windows."""
+    return f"{prefix}/{index:03d}{suffix}"
+
+
+def dumps_manifest(manifest: Manifest) -> bytes:
+    """Manifest bytes with the signature at byte 0."""
+    raw = manifest.to_json()
+    ordered = {key: raw[key] for key in _KEY_ORDER if key in raw}
+    data = json.dumps(ordered, ensure_ascii=True, separators=(",", ":")).encode()
+    if not data.startswith(SIGNATURE):
+        raise CharFileError("Character manifest lost its signature; the key order is wrong.")
+    return data
+
+
+def looks_like_char(data: bytes) -> bool:
+    """Whether a manifest blob carries our signature. Cheap enough for an upload gate."""
+    return data.startswith(SIGNATURE)
+
+
+def read(path: Path | str) -> CharDoc:
+    """Load a ``.char``. Raises `CharFileError` with user-facing copy on anything unreadable."""
+    target = Path(path)
+    try:
+        with zipfile.ZipFile(target, "r") as archive:
+            names = archive.namelist()
+            if MANIFEST_NAME not in names:
+                raise CharFileError(f"{target.name} is not a character file (no manifest).")
+            raw = archive.read(MANIFEST_NAME)
+            members = {
+                n: archive.read(n)
+                for n in names
+                if n != MANIFEST_NAME and not n.endswith("/")
+            }
+    except zipfile.BadZipFile as error:
+        raise CharFileError(f"{target.name} is not a readable character file.") from error
+
+    if not looks_like_char(raw):
+        raise CharFileError(f"{target.name} is not a character file (bad signature).")
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise CharFileError(f"{target.name} has a corrupt manifest.") from error
+
+    version = int(parsed.get("format_version", 0))
+    if version > FORMAT_VERSION:
+        raise CharFileError(
+            f"{target.name} was written by a newer version of Inline Studio "
+            f"(character format {version}, this build reads {FORMAT_VERSION}). Update to open it."
+        )
+    return CharDoc(manifest=Manifest.from_json(parsed), members=members)
+
+
+def write(path: Path | str, doc: CharDoc) -> Path:
+    """Write atomically. The archive closes before the replace, or Windows refuses it."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    staging = target.with_name(target.name + ".part")
+    try:
+        with zipfile.ZipFile(staging, "w", zipfile.ZIP_DEFLATED) as archive:
+            # Manifest first so a reader can identify the file from the front of the stream.
+            archive.writestr(MANIFEST_NAME, dumps_manifest(doc.manifest))
+            for name in sorted(doc.members):
+                # PNGs are already compressed; deflating them again costs time and saves nothing.
+                compress = zipfile.ZIP_STORED if name.endswith(".png") else zipfile.ZIP_DEFLATED
+                archive.writestr(name, doc.members[name], compress_type=compress)
+        os.replace(staging, target)
+    except Exception:
+        staging.unlink(missing_ok=True)
+        raise
+    return target
+
+
+def refs_fingerprint(manifest: Manifest, policy: dict[str, Any]) -> str:
+    """Ordered ref hashes plus policy, so a reorder or a resize-budget change both invalidate.
+
+    Originals only. A harvested reference in here would mark the trained adapter stale the moment
+    one was taken, and `_extract_lora` drops a stale adapter with an INFO log - so the loop whose
+    whole point is a better adapter would silently switch off the adapter the user already has.
+    """
+    kept = [ref for ref in manifest.refs if origin_of(ref) == ORIGIN_ORIGINAL]
+    parts = [str(ref.get("sha256", "")) for ref in kept]
+    parts.append(json.dumps(policy, sort_keys=True, separators=(",", ":")))
+    return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
+
+
+def refs_identity(manifest: Manifest) -> str:
+    """Which reference set this is, order included and policy excluded.
+
+    Separate from `refs_fingerprint`, which answers "is this payload still valid" and so covers
+    only the originals and the policy. This answers "were two nodes handed the same character",
+    which a payload node needs because it compiles from a doc it is not the one holding.
+    """
+    parts = [f"{ref.get('sha256', '')}:{origin_of(ref)}" for ref in manifest.refs]
+    return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
+
+
+def payload_valid(manifest: Manifest, arch: str, encoder_version: str) -> bool:
+    """Whether ``payloads/<arch>/`` can be used as-is, or must be recompiled from ``refs/``."""
+    payload = manifest.payloads.get(arch)
+    if not isinstance(payload, dict):
+        return False
+    encoder = payload.get("encoder")
+    if not isinstance(encoder, dict) or str(encoder.get("version", "")) != encoder_version:
+        return False
+    policy = payload.get("policy")
+    if not isinstance(policy, dict):
+        return False
+    return str(payload.get("source_sha256", "")) == refs_fingerprint(manifest, policy)
+
+
+def centroid_valid(manifest: Manifest, encoder_id: str, encoder_version: str) -> bool:
+    """Cosine similarity across two encoder builds is meaningless, so the version must match."""
+    encoders = manifest.scoring.get("encoders")
+    if not isinstance(encoders, list):
+        return False
+    for entry in encoders:
+        if isinstance(entry, dict) and str(entry.get("id")) == encoder_id:
+            return str(entry.get("version", "")) == encoder_version
+    return False