freesolo-flash-dev 1.2.87__tar.gz → 1.2.89__tar.gz

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.2.87
+Version: 1.2.89
 Summary: Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/flash/adapters/artifacts.py

@@ -5,15 +5,13 @@ by it, and the two never share a call stack to check. Spelling one on each side
 coincidence, so they are defined once, here.
 """
 
-# The PEFT adapter weights file a deployable adapter must carry. Modern saves use safetensors,
-# but older PEFT/default settings may emit adapter_model.bin.
-ADAPTER_WEIGHT_FILES = ("adapter_model.safetensors", "adapter_model.bin")
+# the peft adapter weights file a deployable adapter must carry.
+ADAPTER_WEIGHT_FILES = ("adapter_model.safetensors",)
 
-# A PEFT save past its shard size splits the weights across `adapter_model-0000N-of-0000M.<ext>`
+# a peft save past its shard size splits the weights across `adapter_model-0000N-of-0000M.<ext>`
 # beside an `adapter_model.<ext>.index.json` mapping every tensor key to the shard holding it.
 ADAPTER_SHARD_PREFIX = "adapter_model-"
-ADAPTER_WEIGHT_SUFFIXES = (".safetensors", ".bin")
-ADAPTER_WEIGHT_INDEX_FILES = tuple(f"{name}.index.json" for name in ADAPTER_WEIGHT_FILES)
+ADAPTER_WEIGHT_SUFFIXES = (".safetensors",)
 
 
 def is_adapter_weight_filename(filename: str) -> bool:

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/flash/adapters/fused_experts.py

@@ -9,8 +9,8 @@ from typing import Any
 
 from flash.adapters.lora_rank import (
     _rank_for_module,
-    declared_lora_ranks,
     lora_tensor_rank_disagrees,
+    strict_declared_lora_ranks,
 )
 from flash.core.catalog import get_model
 
@@ -31,10 +31,23 @@ _QWEN36_FUSED_TARGET_RUNGS = {
 }
 _FUSED_EXPERT_SYNTHETIC_MODULES = frozenset({"experts", "base_layer"})
 _FUSED_EXPERT_WRAPPER_MODULES = ("mlp.experts", "mlp.experts.base_layer")
+_NON_LANGUAGE_LORA_SEGMENTS = frozenset(
+    {
+        "mtp",
+        "multi_modal_projector",
+        "patch_embed",
+        "visual",
+        "vision",
+        "vision_encoder",
+        "vision_model",
+        "vision_tower",
+    }
+)
 _INVALID_FUSED_LOCATION = object()
 
 _LoraTensor = tuple[str, str, str, tuple[int, ...]]
 _LoraPair = tuple[tuple[int, ...], tuple[int, ...]]
+_LoraPairKeys = tuple[str, str]
 
 
 def lora_target_parameters(model_id: str | None) -> list[str] | None:
@@ -67,9 +80,7 @@ def validate_fused_expert_adapter_config(config: Mapping[str, Any], model_id: st
             f"adapter for {model_id} must declare exactly the fused expert targets {required}"
         )
 
-    rank_pattern = config.get("rank_pattern")
-    _validate_rank_pattern(rank_pattern, model_id)
-    declared = declared_lora_ranks(config)
+    declared = strict_declared_lora_ranks(config, source=f"adapter for {model_id}")
     unresolved = [target for target in required if _rank_for_module(target, declared) is None]
     if unresolved:
         raise ValueError(
@@ -109,31 +120,6 @@ def validate_fused_expert_adapter_config(config: Mapping[str, Any], model_id: st
         )
 
 
-def _validate_rank_pattern(rank_pattern: Any, model_id: str) -> None:
-    """Validate positive ranks and PEFT's anchored regex pattern syntax."""
-    message = (
-        f"adapter for {model_id} rank_pattern must map valid non-empty string patterns "
-        "to positive integer ranks"
-    )
-    if rank_pattern is None:
-        return
-    if not isinstance(rank_pattern, Mapping):
-        raise ValueError(message)
-    for pattern, rank in rank_pattern.items():
-        if (
-            not isinstance(pattern, str)
-            or not pattern.strip()
-            or not isinstance(rank, int)
-            or isinstance(rank, bool)
-            or rank <= 0
-        ):
-            raise ValueError(message)
-        try:
-            re.compile(rf"(.*\.)?({pattern})$")
-        except re.error as exc:
-            raise ValueError(message) from exc
-
-
 def _targets_fused_expert_wrapper(module: str) -> bool:
     """Return whether PEFT suffix matching binds this target to an expert wrapper."""
     return any(
@@ -161,6 +147,33 @@ def normalize_verl_fused_expert_export(config: dict[str, Any], model_id: str) ->
         ]
 
 
+def is_non_language_lora_key(key: str) -> bool:
+    """whether a LoRA tensor key names a non-language (vision, projector, mtp) module."""
+    return bool(set(key.lower().split(".")) & _NON_LANGUAGE_LORA_SEGMENTS)
+
+
+def fused_expert_lora_tensor_pairs(
+    tensors: Mapping[str, tuple[int, ...]], config: Mapping[str, Any], model_id: str
+) -> dict[str, _LoraPairKeys] | None:
+    """Return complete canonical pair keys when fused and ordinary topology is exact."""
+    expected = _expected_fused_expert_rungs(config, model_id)
+    if expected is None:
+        return None
+    lora_keys = {key: shape for key, shape in tensors.items() if _LORA_FACTOR_PATTERN.search(key)}
+    parsed = [
+        tensor
+        for key, shape in lora_keys.items()
+        if (tensor := _parse_lora_tensor(key, shape)) is not None
+    ]
+    if not parsed or len(parsed) != len(lora_keys):
+        return None
+    if not _has_complete_fused_rungs(parsed, expected, model_id) or not _has_ordinary_evidence(
+        parsed, config, expected
+    ):
+        return None
+    return _complete_lora_pair_keys(parsed)
+
+
 def has_complete_fused_expert_tensors(
     tensors: Mapping[str, tuple[int, ...]], config: Mapping[str, Any], model_id: str
 ) -> bool:
@@ -225,7 +238,7 @@ def _expected_fused_expert_rungs(
     if catalog_dimensions != Counter(_QWEN36_FUSED_TARGET_DIMENSIONS.values()):
         return None
 
-    declared = declared_lora_ranks(config)
+    declared = strict_declared_lora_ranks(config)
     expected: dict[str, dict[str, _LoraPair]] = {}
     for target in targets:
         rank = _rank_for_module(target, declared)
@@ -315,15 +328,17 @@ def _has_ordinary_evidence(
     for module_path, factor, key, shape in tensors:
         if _is_fused_rung(module_path, fused_rungs):
             continue
+        if not module_path.startswith("base_model.model."):
+            return False
         matched = tuple(target for target in targets if _anchored_suffix_match(module_path, target))
         if not all_linear and not matched:
-            continue
+            return False
         evidence.update(matched)
         groups.setdefault(module_path, {})[factor] = (key, shape)
     if not groups or (not all_linear and evidence != set(targets)):
         return False
 
-    declared = declared_lora_ranks(config)
+    declared = strict_declared_lora_ranks(config)
     for module_path, factors in groups.items():
         if _rank_for_module(module_path, declared) is None:
             return False
@@ -335,6 +350,21 @@ def _has_ordinary_evidence(
     return True
 
 
+def _complete_lora_pair_keys(
+    tensors: list[_LoraTensor],
+) -> dict[str, _LoraPairKeys] | None:
+    """Return every canonical module pair without orphan factors."""
+    groups: dict[str, dict[str, str]] = {}
+    for module_path, factor, key, _shape in tensors:
+        factors = groups.setdefault(module_path, {})
+        if factor in factors:
+            return None
+        factors[factor] = key
+    if not groups or any(set(factors) != {"A", "B"} for factors in groups.values()):
+        return None
+    return {module_path: (factors["A"], factors["B"]) for module_path, factors in groups.items()}
+
+
 def _is_fused_rung(module_path: str, fused_rungs: Mapping[str, Mapping[str, _LoraPair]]) -> bool:
     """Return whether a module path is one of the exact fused wrapper rungs."""
     return any(

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/flash/adapters/lora_rank.py

@@ -105,13 +105,16 @@ def _positive_int(value: Any, *, source: str, field: str) -> int:
 
 
 def _file_identity(file_info: Any) -> str:
+    # the producer is `HfApi.list_repo_tree`, which yields `RepoFile` -- whose `__init__` always
+    # sets `path`/`size`/`blob_id` and builds `lfs` as a `BlobLfsInfo` (field `sha256`, no `oid`).
+    # verified at the declared floor `huggingface-hub>=1.2.0` and at the installed 1.27.0, so the
+    # mapping-shaped `lfs` and the `lfs.oid` spelling have no producer in the supported range.
+    # `getattr` stays only on `lfs` itself, which is legitimately optional (non-LFS files), and on
+    # the entry object, because a listing also yields `RepoFolder` -- no size, no blob_id -- which
+    # must fail closed rather than hash to a folder's tree id.
     lfs = getattr(file_info, "lfs", None)
-    if isinstance(lfs, Mapping):
-        oid = lfs.get("sha256") or lfs.get("oid")
-        size = lfs.get("size")
-    else:
-        oid = getattr(lfs, "sha256", None) or getattr(lfs, "oid", None)
-        size = getattr(lfs, "size", None)
+    oid = getattr(lfs, "sha256", None)
+    size = getattr(lfs, "size", None)
     blob_id = getattr(file_info, "blob_id", None)
     size = size if size is not None else getattr(file_info, "size", None)
     immutable = oid or blob_id
@@ -281,6 +284,8 @@ def rank_from_adapter_config(config: Mapping[str, Any], *, source: str) -> int:
 
 _LORA_A_INFIX = ".lora_A."
 _LORA_B_INFIX = ".lora_B."
+# PEFT appends this rung for every parameter wrapper nested inside another one.
+_NESTED_WRAPPER_RUNG = ".base_layer"
 
 
 @dataclass(frozen=True)
@@ -296,26 +301,9 @@ class DeclaredLoraRanks:
         return self.default is not None or bool(self.by_module)
 
 
-def declared_lora_ranks(config: Mapping[str, Any]) -> DeclaredLoraRanks:
-    """Read the per-module LoRA rank structure out of ``adapter_config.json``."""
-    if not isinstance(config, Mapping):
-        return DeclaredLoraRanks()
-    try:
-        default = _positive_int(config["r"], source="adapter_config.json", field="r")
-    except (KeyError, ValueError):
-        default = None
-
-    by_module: dict[str, int] = {}
-    pattern = config.get("rank_pattern")
-    if isinstance(pattern, Mapping):
-        for module, value in pattern.items():
-            try:
-                by_module[str(module)] = _positive_int(
-                    value, source="adapter_config.json", field="rank_pattern"
-                )
-            except ValueError:
-                continue
-
+def _declared_lora_rank_context(
+    config: Mapping[str, Any], *, default: int | None, by_module: Mapping[str, int]
+) -> DeclaredLoraRanks:
     stacked_rank_modules: list[str] = []
     targets = config.get("target_parameters")
     if isinstance(targets, list):
@@ -335,6 +323,41 @@ def declared_lora_ranks(config: Mapping[str, Any]) -> DeclaredLoraRanks:
     )
 
 
+def strict_declared_lora_ranks(
+    config: Mapping[str, Any], *, source: str = "adapter_config.json"
+) -> DeclaredLoraRanks:
+    """validate and preserve PEFT rank declarations for an authoritative load boundary."""
+    if not isinstance(config, Mapping):
+        raise ValueError(f"{source} must be an object")
+
+    default = None
+    if "r" in config:
+        value = config["r"]
+        if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+            raise ValueError(f"{source} r must be a positive integer")
+        default = value
+
+    by_module: dict[str, int] = {}
+    if "rank_pattern" in config:
+        pattern = config["rank_pattern"]
+        if not isinstance(pattern, Mapping):
+            raise ValueError(f"{source} rank_pattern must be an object")
+        for module, value in pattern.items():
+            if not isinstance(module, str) or not module.strip():
+                raise ValueError(f"{source} rank_pattern keys must be non-empty strings")
+            if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+                raise ValueError(f"{source} rank_pattern values must be positive integers")
+            try:
+                re.compile(rf"(.*\.)?({module})$")
+            except re.error as exc:
+                raise ValueError(
+                    f"{source} rank_pattern contains invalid regex {module!r}"
+                ) from exc
+            by_module[module] = value
+
+    return _declared_lora_rank_context(config, default=default, by_module=by_module)
+
+
 def _rank_for_module(module_path: str, declared: DeclaredLoraRanks) -> int | None:
     """Resolve a module's rank with PEFT's ordered, anchored ``rank_pattern`` matching."""
     for module, rank in declared.by_module.items():
@@ -350,9 +373,27 @@ def _rank_for_module(module_path: str, declared: DeclaredLoraRanks) -> int | Non
 
 
 def _module_uses_target_parameters(module_path: str, declared: DeclaredLoraRanks) -> bool:
-    """Whether this serialized module came from one of PEFT's targeted parameters."""
+    """Whether this serialized module came from one of PEFT's targeted parameters.
+
+    PEFT wraps the module that *owns* a targeted parameter, keeping the parameter name off the
+    serialized path. When several targeted parameters share one owner, the wrappers nest and every
+    wrapper after the first appends a ``base_layer`` rung, so a single owner produces keys like::
+
+        mlp.experts                          (the outermost wrapper)
+        mlp.experts.base_layer               (the one nested inside it)
+
+    Those inner rungs carry the same stacked axis as the outer one, so peeling the ``base_layer``
+    rungs off before matching is what keeps a valid adapter from being measured against the scalar
+    rank.
+    """
+    candidates = [module_path]
+    trimmed = module_path
+    while trimmed.endswith(_NESTED_WRAPPER_RUNG):
+        trimmed = trimmed[: -len(_NESTED_WRAPPER_RUNG)]
+        candidates.append(trimmed)
     return any(
-        module_path == module or module_path.endswith(f".{module}")
+        candidate == module or candidate.endswith(f".{module}")
+        for candidate in candidates
         for module in declared.stacked_rank_modules
     )
 
@@ -409,11 +450,22 @@ def inspect_adapter_config(
         raise ValueError(f"could not verify adapter metadata: {source} is not a JSON object")
     if str(config.get("peft_type") or "").strip().upper() != "LORA":
         raise ValueError(f"could not verify adapter metadata: {source} peft_type must be LORA")
+    # both fields are REQUIRED, not "checked when present": every warm-start source is a
+    # flash-owned adapter resolved from a run or checkpoint reference, and the one exporter every
+    # publish path funnels through stamps `base_model_name_or_path = model_id` unconditionally
+    # (engine/worker/verl/checkpoints.py) while the builder always sets `task_type = CAUSAL_LM`
+    # (engine/worker/model/adapter.py). treating a blank value as "no opinion" made the base-model
+    # match SKIP itself, so an adapter trained on a different base passed preflight and was
+    # inherited into the run -- the check failing open is worse than an old artifact failing loudly.
     task_type = str(config.get("task_type") or "").strip().upper()
-    if task_type and task_type != "CAUSAL_LM":
+    if task_type != "CAUSAL_LM":
         raise ValueError(f"could not verify adapter metadata: {source} task_type must be CAUSAL_LM")
     base_model = _normalized_model(config.get("base_model_name_or_path"))
-    if base_model and base_model != _normalized_model(target_model):
+    if not base_model:
+        raise ValueError(
+            f"could not verify adapter metadata: {source} does not name its base model"
+        )
+    if base_model != _normalized_model(target_model):
         raise ValueError(
             f"train.init_from_adapter base model {base_model!r} does not match target model "
             f"{target_model!r}"

freesolo_flash_dev-1.2.89/flash/adapters/targets.py

@@ -0,0 +1,61 @@
+"""Resolve the exact LoRA module surface for one training job."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from flash.adapters.fused_experts import lora_target_parameters
+from flash.core.catalog import validate_model_for_algorithm
+
+
+@dataclass(frozen=True)
+class LoraTargeting:
+    target_modules: str
+    target_parameters: list[str] | None
+    exclude_modules: str | None
+
+
+def require_modality_marker(config: Mapping[str, Any], *, source: str) -> None:
+    """Reject an adapter config that carries no ``exclude_modules`` modality marker.
+
+    Homed here, beside the resolver that WRITES the marker, so the control plane and the worker
+    decide this identically -- and called from both. The control plane already downloads this exact
+    config during warm-start preparation, so rejecting there costs a submit-time error, while the
+    worker-only check that used to be the sole gate could not fire until a GPU had been allocated
+    and the adapter re-downloaded. Same rejection, no paid allocation.
+
+    The worker keeps its own call because it validates the config it actually loads: the two
+    processes never share a call stack, so a marker present at preparation is not proof of one in
+    the bytes the trainer opens.
+
+    Every supported install writes the key -- ``peft>=0.19`` serializes ``exclude_modules`` on every
+    ``LoraConfig``, as null for a multimodal run -- so an absent key means the artifact predates the
+    marker entirely and its modality is unknowable. Guessing it is what this rejects: a text-only
+    adapter continued as multimodal (or the reverse) trains the wrong module surface and silently
+    produces an adapter that serves as a no-op.
+    """
+    if "exclude_modules" not in config:
+        raise ValueError(
+            f"{source} is missing the required exclude_modules modality marker; "
+            "unmarked artifacts are unsupported"
+        )
+
+
+def resolve_lora_targeting(model_id: str, *, algorithm: str, multimodal: bool) -> LoraTargeting:
+    """Resolve fresh-training targets without changing an authored warm-start adapter."""
+    model = validate_model_for_algorithm(model_id, algorithm)
+    exclude_modules = None
+    if not multimodal:
+        prefix = model.lora_language_prefix.strip(".")
+        if not prefix:
+            raise ValueError(f"{model_id} has no cataloged text-only LoRA language module prefix")
+        escaped = re.escape(prefix)
+        exclude_modules = rf"^(?!{escaped}(?:\.|$)).*$"
+    return LoraTargeting(
+        target_modules="all-linear",
+        target_parameters=lora_target_parameters(model_id),
+        exclude_modules=exclude_modules,
+    )

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/flash/cli/commands/__init__.py

@@ -15,12 +15,12 @@ from flash.cli.ui import render
 from flash.cli.ui.tty import TtyStatusLine
 from flash.client import (
     ApiClient,
-    ApiError,
     ClientError,
     client_from_config,
     save_credentials,
     verify_freesolo_key,
 )
+from flash.client import ApiError as ApiError
 
 # `shadowed_login_warning` has no call site left here since the cost quote moved to
 # `.train_cost`, but the estimate tests patch it on THIS module and that quote reads it back
@@ -380,18 +380,12 @@ def cmd_train(args) -> int:
         # dry-run runs submit-time server preflights without allocating a training gpu or charging
         # for training. a rejection surfaces as the server's error with exit status 1. for sft the
         # server reads the packaged dataset file and builds the quote without executing environment.py.
-        try:
-            status = client.create_run(
-                payload,
-                runtime_secrets=runtime_secrets,
-                dry_run=True,
-                client_train_schema=client_train_schema,
-            )
-        except ApiError as exc:
-            detail = _legacy_train_key_rejection_detail(exc, authored_train_keys)
-            if detail is None:
-                raise
-            raise ApiError(exc.status, detail, detail=detail) from exc
+        status = client.create_run(
+            payload,
+            runtime_secrets=runtime_secrets,
+            dry_run=True,
+            client_train_schema=client_train_schema,
+        )
         compatibility = status.pop("train_schema_compatibility", None)
         _print_train_schema_compatibility(compatibility)
         # the server fails open on a billing-infra problem, so "cost" is only in the validated list
@@ -979,7 +973,6 @@ from flash.cli.commands.train_cost import (  # noqa: E402,F401
     _cmd_train_cost,
     _cmd_train_cost_offline,
     _cmd_train_cost_sft,
-    _legacy_train_key_rejection_detail,
     _print_reasoning_loss_warning,
     _print_sft_cost,
     _print_train_schema_compatibility,

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/flash/cli/commands/env/push.py

@@ -18,6 +18,7 @@ from typing import TYPE_CHECKING, Literal, TypeAlias
 from flash._internal.channel import CLI_NAME
 from flash.cli.ui import render
 from flash.cli.ui.tty import TtyStatusLine
+from flash.envs.package.limits import ARCHIVE_MEMBER_LIMIT as _ENV_PUSH_MAX_FILES
 
 if TYPE_CHECKING:
     from flash.client.http import ProgressCallback
@@ -336,11 +337,6 @@ _ENV_PUSH_SECRET_PATTERNS = (
 _ENV_PUSH_CODE_SUFFIXES = frozenset({".py", ".pyi"})
 _ENV_PUSH_MAX_TOTAL_BYTES = 256 * 1024 * 1024
 
-try:
-    from flash.envs.package.limits import ARCHIVE_MEMBER_LIMIT as _ENV_PUSH_MAX_FILES
-except ImportError:
-    _ENV_PUSH_MAX_FILES = 5000
-
 
 def _normalize_env_name(raw: str) -> str | None:
     """Normalize only the NAME segment; a ``<namespace>/<project>`` prefix passes through verbatim.
@@ -634,30 +630,18 @@ def _resolve_local_env_entrypoint(path: str | Path) -> tuple[Path, Path, Path, b
     include_full_tree = src.is_dir()
     if include_full_tree:
         canonical_entrypoint = src / _ENV_ENTRYPOINT
-        if canonical_entrypoint.is_file():
-            entrypoint = canonical_entrypoint
-            env_root = src
-        elif (src / "pyproject.toml").is_file():
-            raise ValueError(f"{src} has a pyproject.toml but no environment.py entrypoint")
-        else:
-            # evaluations.py is a known sidecar, never an entrypoint. counting it here would
-            # make adding one break a legacy single-module package that resolved fine before:
-            # the directory would suddenly hold "multiple top-level .py modules" and be rejected
-            # before either file is read.
-            modules = [
-                p
-                for p in sorted(src.glob("*.py"))
-                if not p.name.startswith("__") and p.name != _ENV_EVALUATIONS_SIDECAR
-            ]
-            if len(modules) != 1:
-                raise ValueError(
-                    f"{src} has no environment.py and "
-                    f"{'no' if not modules else 'multiple'} top-level .py module(s); "
-                    "add an environment.py entrypoint or pass the exact .py file "
-                    "for a single-file smoke test."
-                )
-            env_root = src
-            entrypoint = modules[0]
+        if not canonical_entrypoint.is_file():
+            # a directory package names its entrypoint `environment.py`. that is what `flash env
+            # setup` scaffolds and the only layout the docs describe, so a directory without one is
+            # rejected rather than guessed at: inferring the entrypoint from "the sole top-level
+            # module" made the resolution depend on which OTHER files happened to be present, so
+            # adding a second module turned a working push into a rejection.
+            raise ValueError(
+                f"{src} has no {_ENV_ENTRYPOINT} entrypoint; add one, "
+                "or pass the exact .py file for a single-file smoke test."
+            )
+        entrypoint = canonical_entrypoint
+        env_root = src
     elif src.is_file() and src.suffix == ".py":
         env_root = src.parent
         entrypoint = src

{freesolo_flash_dev-1.2.87 → freesolo_flash_dev-1.2.89}/flash/cli/commands/env/test.py

@@ -270,7 +270,11 @@ def _drive_single_turn(env, example: dict, record: dict, *, force_echo: bool = F
 
 def _new_multi_turn_replay_state(env, example: dict, record: dict) -> dict:
     state = env.new_rollout_state(example)
-    record["prompt"] = _check_messages(state.get("prompt") or state.get("messages"), "prompt")
+    # `prompt` only, never `messages`: the two are not spellings of one field. `new_rollout_state`
+    # seeds `messages` with a COPY of `prompt` and appends each turn onto it, so falling back to it
+    # records the growing transcript where the frozen initial prefix belongs. every producer sets
+    # both, so an absent `prompt` is a corrupt state and `_check_messages` rejects it by name.
+    record["prompt"] = _check_messages(state.get("prompt"), "prompt")
     _normalize_prompt_images(env, example, record["prompt"])
     return state