freesolo-flash-dev 1.2.59__tar.gz → 1.2.61__tar.gz

{freesolo_flash_dev-1.2.59 → freesolo_flash_dev-1.2.61}/CHANGELOG.md

@@ -21,6 +21,10 @@ This file starts at 1.1.35. Earlier releases are not reconstructed here; use
 
 ### Changed
 
+- Multi-turn GRPO now clones each sibling rollout from the task state that produced its prepared
+  prompt. Environments that record randomized episode choices on the task during `start_episode`
+  are stepped and scored against the same episode the model saw, without sharing mutable state
+  between sibling rollouts.
 - A RunPod attempt's stall window is now measured from evidence timestamps rather than from when
   the control plane happened to look at it. The window was seeded from the moment polling started
   and was reset again by the first status read, and a heartbeat was credited at the time it was

{freesolo_flash_dev-1.2.59 → freesolo_flash_dev-1.2.61}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.2.59
+Version: 1.2.61
 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.59 → freesolo_flash_dev-1.2.61}/flash/content/multimodal.py

@@ -250,13 +250,22 @@ def record_has_images(record: dict, messages: list[dict] | None = None) -> bool:
         return True
     for message in messages or []:
         content = message.get("content") if isinstance(message, dict) else None
-        if isinstance(content, list) and any(
-            isinstance(block, dict) and block.get("type") in _IMAGE_BLOCK_TYPES for block in content
-        ):
+        if content_has_images(content):
             return True
     return False
 
 
+def content_has_images(content: object) -> bool:
+    """Whether one message's ``content`` carries an image block.
+
+    The single definition of "this message shows the model an image", so a path that cannot carry
+    media (the multi-turn GRPO bridge) recognises exactly what the paths that can do.
+    """
+    return isinstance(content, list) and any(
+        isinstance(block, dict) and block.get("type") in _IMAGE_BLOCK_TYPES for block in content
+    )
+
+
 def text_only_prompt_messages(messages: list[dict]) -> list[dict]:
     """Drop image content blocks while preserving the teacher's message order and text."""
     stripped: list[dict] = []

{freesolo_flash_dev-1.2.59 → freesolo_flash_dev-1.2.61}/flash/core/spec.py

@@ -28,6 +28,10 @@ from uuid import UUID
 from flash._internal.diagnostics import SECRET_ENV_KEYS_ENV
 from flash.core.catalog import DEFAULT_MODEL, normalize_algorithm
 from flash.core.spec_persistence import (
+    DROPPED_TOP_LEVEL_KEYS,
+    REMOVED_PERSISTED_TRAIN_KEYS,
+    announce_dropped_keys,
+    migrated_optimizer_batch,
     opt_float,
     opt_int,
     str_tuple,
@@ -453,6 +457,58 @@ MANAGED_GPU_KEYS = frozenset(
     {"disk_gb", "network_volume", "network_volume_gb", "max_retries", "max_wall_seconds"}
 )
 
+# the other two halves of the same boundary. together with the managed gpu registry they name every field
+# that separates the worker contract from the public one -- which is the whole difference between
+# them, and is why `to_dict` can be a projection of `to_internal_dict` rather than a second
+# serializer. they were bare `data.pop(...)` calls, so the boundary existed only as a sequence of
+# statements: nothing could enumerate it, and a field added to one serializer but not the other was
+# invisible until a submit round trip or a recovery digest failed.
+#
+# order is irrelevant (the payload is canonicalized with sort_keys), but presence is a recovery
+# contract: `_preparation_digest` hashes the public payload, so moving a name in or out of this set
+# invalidates the stored digest of every warm-start and workload-profile run in flight.
+#
+# not reused by `_validate_effective_spec`, which keeps its own near-identical list. the difference
+# is one name -- `model_revision` -- and it is deliberate there: the validator excludes it only
+# conditionally, so a historical authored pin stays structurally compared between the two halves.
+# substituting this set would widen that exclusion to every run and drop a real integrity check.
+MANAGED_TOP_LEVEL_KEYS = frozenset(
+    {
+        # server-assigned identity -- never authored in a config.
+        "run_id",
+        # runner-managed, and no longer part of the public config or status spec. internal round
+        # trips keep the value and marker through to_internal_dict(). historical public specs that
+        # emitted these are replayed only while verifying a stored preparation digest, from the
+        # exact persisted bytes.
+        "model_revision",
+        "model_revision_auto",
+        # the provenance marker only. gpu.count=1 stays in the public [gpu] object for digest
+        # stability; internal round trips carry the marker verbatim.
+        "gpu_count_auto",
+        "workload_profile",
+        "workload_profile_input_digest",
+        "workload_profile_producer_version",
+    }
+)
+
+# platform-managed [train] fields: the control-plane-assigned artifact repo and the resolve-once
+# revision pin of a warm-start source.
+MANAGED_TRAIN_KEYS = frozenset({"hf_repo", "init_from_adapter_revision"})
+
+# platform-managed [environment] field: the env ref is resolved once and pinned by the control plane.
+# `pip` deliberately stays public -- it is the author's own scorer dependencies, which only they can
+# declare.
+MANAGED_ENVIRONMENT_KEYS = frozenset({"resolved_sha"})
+
+# every managed section, so the public/worker boundary can be walked rather than restated. the two
+# things not here are the ones that are not removals: `train.lora_rank`/`lora_alpha` are stripped
+# only for a warm start, and `gpu.type_fallbacks` is respelled into `gpu.type` rather than dropped.
+MANAGED_SECTION_KEYS = (
+    ("train", MANAGED_TRAIN_KEYS),
+    ("gpu", MANAGED_GPU_KEYS),
+    ("environment", MANAGED_ENVIRONMENT_KEYS),
+)
+
 
 @dataclass(frozen=True)
 class WandbSpec:
@@ -555,52 +611,44 @@ class JobSpec:
         parser would reject, so the result re-validates through ``flash.schema.spec_from_dict``. Do
         not hand its output to a worker or provider path -- those need ``to_internal_dict()``.
 
+        Built as a PROJECTION of the worker payload, because that is the actual relationship: the
+        public contract is the worker contract minus the platform-managed fields, which
+        MANAGED_TOP_LEVEL_KEYS and MANAGED_SECTION_KEYS name. This is still a blacklist -- a newly
+        added field is public until something strips it, exactly as before -- but the strips are now
+        enumerable rather than a run of statements, so a test can assert the boundary instead of
+        trusting that two independent `asdict(self)` bodies were kept in sync by hand. What the
+        registries deliberately do NOT cover is the two adjustments below that are not removals.
+
         Its bytes are a recovery contract. ``_preparation_digest`` hashes this output as canonical
         JSON, so key PRESENCE is load-bearing even though key order is not: adding or dropping one
         key here invalidates the stored digest of every warm-start and workload-profile run in
         flight, which fails integrity validation on recovery.
         """
-        data = asdict(self)
-        # server-assigned identity — never authored in a config.
-        data.pop("run_id", None)
-        # model_revision is runner-managed and no longer part of the public config or status spec.
-        # Internal round trips keep the value and marker through to_internal_dict(). Historical public
-        # specs that emitted this key are replayed only while verifying their stored preparation
-        # digest, using the exact value from the persisted bytes.
-        data.pop("model_revision", None)
-        data.pop("model_revision_auto", None)
-        # keep gpu.count=1 in the public gpu object for preparation-digest stability. only the
-        # platform-managed provenance marker is stripped; internal round trips carry it verbatim.
-        data.pop("gpu_count_auto", None)
-        data.pop("workload_profile_input_digest", None)
-        data.pop("workload_profile_producer_version", None)
-        data.pop("workload_profile", None)
+        data = self.to_internal_dict()
+        for managed in MANAGED_TOP_LEVEL_KEYS:
+            data.pop(managed, None)
+        for section, managed_keys in MANAGED_SECTION_KEYS:
+            for managed in managed_keys:
+                data[section].pop(managed, None)
         train = data["train"]
-        train.pop("init_from_adapter_revision", None)
-        train.pop("hf_repo", None)  # control-plane-assigned artifact repo
         if train.get("init_from_adapter"):
             # the source adapter's topology is authoritative for a warm start, so the parser rejects
             # both keys alongside init_from_adapter. the runner writes the inherited rank/alpha onto
             # the public spec, so they must be stripped here or the submit round trip re-validates
-            # a combination the parser refuses.
+            # a combination the parser refuses. conditional, so it cannot be a registry entry.
             train.pop("lora_rank", None)
             train.pop("lora_alpha", None)
-        # runner-assigned disk sizing, shared weight-cache volume, and retry/wall-clock lifecycle.
+        # restore the public list spelling for an ordered pin -- a reshape rather than a removal,
+        # which is the other thing no registry can express. the default stands in for the key the
+        # worker payload omits when there are no fallbacks: unlike `providers`, this one is read
+        # back, so it cannot rely on the omission alone.
         gpu = data["gpu"]
-        for managed in MANAGED_GPU_KEYS:
-            gpu.pop(managed, None)
-        # restore the public list spelling for an ordered pin.
         fallbacks = gpu.pop("type_fallbacks", ())
         if fallbacks:
             gpu["type"] = [gpu["type"], *fallbacks]
-        # omit the unset preference so an internal default does not become an authored empty list on
-        # the public round trip, where an explicit empty list is rejected as a likely configuration bug.
-        if not gpu.get("providers"):
-            gpu.pop("providers", None)
-        data["environment"].pop("resolved_sha", None)  # resolve-once env ref pin
-        # [environment] pip stays in the payload: it is the author's own scorer dependencies, which
-        # only they can declare. The submit paths append it to worker_pip_for_env, so what travels
-        # here is the extra requirements, not the worker's own.
+        # an empty `providers` needs no strip: the worker payload this projects from already omits
+        # it, for the same reason the public contract wants it gone -- an internal default must not
+        # read back as an authored empty list, which the parser rejects as a likely config bug.
         return data
 
     def to_internal_dict(self) -> dict[str, Any]:
@@ -642,9 +690,10 @@ class JobSpec:
         if not isinstance(data, dict):
             raise TypeError("job spec must be an object")
         allowed_top_level = {item.name for item in fields(cls)}
-        unknown_top_level = sorted(set(data) - allowed_top_level)
+        unknown_top_level = sorted(set(data) - allowed_top_level - DROPPED_TOP_LEVEL_KEYS)
         if unknown_top_level:
             raise ValueError(f"job spec has unknown key(s): {', '.join(unknown_top_level)}")
+        announce_dropped_keys(data)
         env = data.get("environment") or {}
         # Reject stale payloads carrying a local `path`; worker only runs published env ids.
         if isinstance(env, dict) and env.get("path"):
@@ -652,7 +701,12 @@ class JobSpec:
                 "local environment paths are no longer supported; the worker only runs "
                 "published Freesolo environment ids"
             )
-        train = validated_section(data, "train", {item.name for item in fields(TrainSpec)})
+        train = validated_section(
+            data,
+            "train",
+            {item.name for item in fields(TrainSpec)},
+            removed=REMOVED_PERSISTED_TRAIN_KEYS,
+        )
         gpu = validated_section(data, "gpu", {item.name for item in fields(GpuSpec)})
         gpu_type, gpu_type_fallbacks = _parse_persisted_gpu_types(gpu)
         provider, providers = validated_persisted_providers(gpu, gpu_type, gpu_type_fallbacks)
@@ -661,8 +715,9 @@ class JobSpec:
             raise TypeError("project must be a string")
         project = require_project_id(project_raw) if project_raw.strip() else ""
         algorithm = normalize_algorithm(data.get("algorithm", cls.algorithm))
-        batch_size = opt_int(train.get("batch_size"))
-        prompts_per_step = opt_int(train.get("prompts_per_step"))
+        # one reading of the optimizer batch for both keys: the rollout spelling changed in 1.1.43
+        # and a persisted spec can still carry the old one.
+        batch_size, prompts_per_step = migrated_optimizer_batch(train, algorithm)
         return cls(
             model=data.get("model", cls.model),
             model_revision=_model_revision(data.get("model_revision", cls.model_revision)),

freesolo_flash_dev-1.2.61/flash/core/spec_persistence.py

@@ -0,0 +1,414 @@
+"""Decoding rules for PERSISTED job-spec records, as distinct from authored configuration.
+
+`JobSpec` serves four different contracts, and this module owns exactly one of them: reading back
+bytes that were already written to `~/.flash/runs/<run_id>.json`. That is not the same job as
+validating a config a user just wrote, and the two must not be confused:
+
+- authored configuration is parsed by `flash.schema.spec_from_dict`, which is STRICT. an unknown key
+  is a typo in a file the author can still fix, so it fails loudly.
+- a persisted record is parsed by `JobSpec.from_dict`, which is TOLERANT by necessity. the record is
+  immutable history: it was written by an older Flash, it is never rewritten, and a run that is
+  still training depends on it decoding. rejecting it strands the run.
+
+So the coercions here are deliberately looser than anything the authored parser would accept, and
+the migrations exist to keep specific historical spellings readable. Neither belongs on the
+submission path.
+
+Serialized-byte warning: `flash/runner/preparation.py::_preparation_digest` sha256-hashes the
+canonical JSON of `to_dict()` and `to_internal_dict()` output. Key ORDER is safe there
+(`sort_keys=True`), but key PRESENCE is not -- adding, dropping, or renaming a key in a decode path
+changes the digest and fails integrity validation for every warm-start and workload-profile run in
+flight. Change decoding here only with the corpus gate green.
+
+These functions take plain dicts and return plain dicts and scalars. That is the rule that keeps the
+module importable by `spec.py` rather than the other way round, and it is why `validated_section`
+takes its allowed-key set as an argument instead of reading `fields(TrainSpec)` itself.
+
+What is deliberately NOT here: `_coerce_wandb` and `_parse_persisted_gpu_types` are also called only
+from `JobSpec.from_dict`, so they belong to this contract by usage -- but they construct `WandbSpec`
+and reach `_validated_gpu_type`, which `__post_init__` needs too. Moving them would make this module
+import the dataclasses that import it. The boundary is therefore "persisted-record logic that does
+not depend on the spec types themselves"; `VersionedPersistedSpecEnvelope` follows that rule too.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from flash.core.catalog import normalize_algorithm, samples_on_policy
+
+# removed public top-level fields that a persisted record can still carry. stored run records are
+# never rewritten, and effective_preparation.worker_spec is written with to_internal_dict() (asdict),
+# which emitted every field including the defaulted ones -- so every record written before a field
+# was dropped still names it. this registry also drives historical public-digest replay for
+# model_revision, which remains an internal field. without it a still-running job can lose its
+# recovery, deploy, and serving paths after the upgrade.
+#
+# ignored on read only. most keys here no longer exist as jobspec fields; model_revision remains an
+# internal runner field, but the public schema rejects it and to_dict omits it. keeping it in this set
+# lets digest recovery identify the historical public key without weakening jobspec.from_dict.
+DROPPED_TOP_LEVEL_KEYS = frozenset(
+    {"model_policy", "model_revision", "worker_env", "workload_profile_kind"}
+)
+
+# tolerating a dropped key keeps a pre-upgrade run's recovery path, but the values behind it stop
+# being applied -- so a run that authored them now trains on managed defaults instead of what was
+# submitted. that is announced rather than silent. only user-authorable keys qualify: model_policy
+# was platform-managed (to_dict popped it), so its loss cannot change what a submitted config asked
+# for. the values are deliberately not forwarded -- doing so would reinstate the override table this
+# removal exists to close, and would deliver it without the validation the deleted parser performed.
+_ANNOUNCED_DROPPED_KEYS = frozenset({"worker_env"})
+
+# removed [train] keys a persisted record can still carry. deliberately narrow: a key is listed only
+# once its behavior is gone, so an unlisted unknown key stays fatal rather than silently ignored.
+REMOVED_PERSISTED_TRAIN_KEYS = frozenset({"advantage_clip"})
+
+
+def announce_dropped_keys(data: dict[str, Any]) -> None:
+    """Log the removed user-authored keys a persisted record still carries and no longer applies.
+
+    Only announced when the payload names the run. A public spec is ``to_dict()`` output, which pops
+    the server-assigned run_id, and the same stored run is read through both shapes -- so warning
+    without an id would emit an unactionable "run <unknown>" line and duplicate the identified one
+    the worker-spec read already produced. Every provisioned run records an internal worker spec
+    (asdict, run_id included), and that is the read this fires on.
+    """
+    run_id = str(data.get("run_id") or "").strip()
+    if not run_id:
+        return
+    for key in sorted(_ANNOUNCED_DROPPED_KEYS):
+        value = data.get(key)
+        if not value:
+            continue
+        names = ", ".join(sorted(str(k) for k in value)) if isinstance(value, dict) else str(value)
+        logging.getLogger("flash.spec").warning(
+            "run %s was submitted with [%s] (%s); that table was removed and its values are NOT "
+            "applied -- this run uses managed defaults instead. resubmit without it if the run "
+            "depends on those values.",
+            run_id,
+            key,
+            names,
+        )
+
+
+def validated_section(
+    data: dict[str, Any],
+    name: str,
+    allowed: set[str],
+    *,
+    removed: frozenset[str] = frozenset(),
+) -> dict[str, Any]:
+    """Read one nested block (``[train]``, ``[gpu]``) of a persisted record, rejecting unknown keys.
+
+    A missing block and an explicit null are the same state -- both mean "authored nothing" -- so both
+    normalize to empty rather than one of them raising. ``removed`` names keys whose behavior is gone:
+    they are dropped silently, because the record is immutable history and cannot be rewritten. An
+    unlisted unknown key stays fatal, which is what keeps the tolerance narrow instead of turning
+    every typo in a stored record into a silent default.
+    """
+    section = data.get(name)
+    if section is None:
+        section = {}
+    if not isinstance(section, dict):
+        raise TypeError(f"{name} must be an object")
+    section = {key: value for key, value in section.items() if key not in removed}
+    unknown = sorted(set(section) - allowed)
+    if unknown:
+        raise ValueError(f"{name} has unknown key(s): {', '.join(unknown)}")
+    return section
+
+
+def validated_persisted_providers(
+    gpu: dict[str, Any], gpu_type: str, gpu_type_fallbacks: tuple[str, ...]
+) -> tuple[str, tuple[str, ...]]:
+    """``(provider, providers)`` from a persisted ``[gpu]`` block, cross-checked against its classes.
+
+    ``GpuSpec.__post_init__`` runs the same both-set check but cannot replace this one: ``allow_empty``
+    here keys off whether the record CARRIED a ``providers`` key, and that presence is exactly what the
+    dataclass has already lost by the time it validates. An explicitly empty preference and an absent
+    one are different states in a stored record.
+    """
+    from flash.providers import PROVIDER_NAMES, validated_provider_preferences
+
+    provider = gpu.get("provider", "")
+    if not isinstance(provider, str):
+        raise TypeError("gpu.provider must be a string")
+    provider = provider.strip().lower()
+    providers = validated_provider_preferences(
+        gpu.get("providers", ()), allow_empty="providers" not in gpu
+    )
+    if provider and providers:
+        raise ValueError("gpu.provider and gpu.providers cannot both be set")
+    if provider or providers or gpu_type:
+        from flash.providers.base import providers_for
+
+        if provider and provider not in PROVIDER_NAMES:
+            raise ValueError(f"unknown gpu.provider {provider!r}")
+        # a hard provider pin must carry every acceptable class. provider preferences stay soft: an
+        # ineligible named provider contributes no candidate, while eligible named or unnamed
+        # configured providers remain available for failover.
+        for candidate in (gpu_type, *gpu_type_fallbacks):
+            if candidate and provider and provider not in providers_for(candidate):
+                raise ValueError(
+                    f"gpu.provider {provider!r} cannot provision gpu.type {candidate!r}"
+                )
+    return provider, providers
+
+
+def str_tuple(value: Any) -> tuple[str, ...]:
+    """Normalize a string-or-list knob to a tuple of strings; a bare string is one element, not iterated."""
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value,) if value else ()
+    return tuple(s for s in (str(x) for x in value) if s)
+
+
+def volume_gb(value: Any, default: int = 100) -> int:
+    """Parse volume size in GB; non-positive / non-numeric / missing values return default."""
+    if isinstance(value, bool):
+        # bool is an int subclass; reject to avoid int(True)==1 becoming a 1 GB volume.
+        return default
+    try:
+        gb = int(value)
+    except (TypeError, ValueError):
+        return default
+    return gb if gb > 0 else default
+
+
+def opt_int(value: Any) -> int | None:
+    """Parse optional int; rejects bools (bool is int subclass — int(True)==1 is a footgun)."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise TypeError(f"expected a number, got bool {value!r}")
+    return int(value)
+
+
+def opt_float(value: Any) -> float | None:
+    """Parse optional float; rejects bools (mirrors ``opt_int``)."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise TypeError(f"expected a number, got bool {value!r}")
+    return float(value)
+
+
+def migrated_optimizer_batch(train: dict, algorithm: str) -> tuple[int | None, int | None]:
+    """``(batch_size, prompts_per_step)`` with the pre-1.1.43 rollout spelling migrated.
+
+    grpo/opd authored the optimizer batch as ``batch_size`` until it was split into
+    ``prompts_per_step``. The schema rejects the old name on SUBMISSION, but `from_dict` also
+    reparses PERSISTED specs, and the deployed release (1.1.40) has no ``prompts_per_step`` at all
+    -- so every rollout run in flight across this upgrade carries only the old key. The workers read
+    ``prompts_per_step`` alone, so without this a recovered run silently resumes on the recipe
+    default: 64 instead of an authored 32 on grpo, which OOMs a card rented for 32, and 8 on opd.
+
+    The old key is MOVED, not copied, and is dropped whenever the new one is present. Leaving it
+    populated would re-emit both names from ``to_dict()``, and a spec carrying both is rejected by
+    the schema -- breaking the resubmit that recovery and ``flash runs get`` perform, and leaving
+    `vram.py::_optimizer_batch_value` (which takes the larger of the two) free to size a card off
+    the stale value that ranking ignores. That applies to a payload written mid-upgrade carrying
+    BOTH spellings too: ``prompts_per_step`` wins, so the superseded key has to go with it.
+
+    A non-positive legacy value is discarded rather than migrated: ``minimum=1`` would have
+    rejected it at submission, and carrying it forward only fails later on a rented GPU. It is
+    discarded from BOTH names for the same round-trip reason -- retaining it under the old one
+    would re-emit a key the schema rejects for this algorithm.
+    """
+    batch_size = opt_int(train.get("batch_size"))
+    prompts_per_step = opt_int(train.get("prompts_per_step"))
+    if not samples_on_policy(algorithm):
+        return batch_size, prompts_per_step
+    if prompts_per_step is not None:
+        return None, prompts_per_step
+    return None, batch_size if batch_size is not None and batch_size >= 1 else None
+
+
+_PREPARATION_ENVELOPE_VERSION = 1
+
+
+def _prepared_before_public_alpha(raw_public: object) -> bool:
+    """True when this run's PERSISTED public spec predates ``lora_alpha`` becoming authorable.
+
+    The discriminator is the stored bytes, not this build's serialization: a snapshot prepared
+    before the change hashed a public spec with no alpha key, and its digest can only be reproduced
+    the same way. status.spec is never rewritten, so this answer is stable for the run's life.
+
+    A warm-start spec is excluded even though it also omits alpha -- to_dict() strips rank and alpha
+    for those in every version, so absence there says nothing about when the run was prepared, and
+    treating it as legacy would drop a binding that costs nothing to keep.
+    """
+    if not isinstance(raw_public, dict):
+        return False
+    train = raw_public.get("train")
+    if not isinstance(train, dict) or "lora_alpha" in train:
+        return False
+    return not train.get("init_from_adapter")
+
+
+_ROLLOUT_BATCH_KEYS = ("batch_size", "prompts_per_step")
+
+
+def _stored_rollout_batch_spelling(raw_spec: object) -> dict[str, Any] | None:
+    """How a PERSISTED rollout spec spelled its optimizer batch, or None if it is not one.
+
+    Same discriminator style as ``_prepared_before_public_alpha``: the answer comes from the stored
+    bytes, which are never rewritten, so it is stable for the run's life.
+
+    ``JobSpec.from_dict`` MOVES the pre-1.1.43 ``batch_size`` onto ``prompts_per_step`` when
+    reparsing, so rehashing a persisted spec with today's parse can produce different bytes than
+    were hashed at persist time -- failing integrity validation for exactly the warm-start grpo/opd
+    runs this migration exists to rescue.
+
+    Both keys are reported, rather than just the value there is to migrate. Reporting only the
+    latter conflates snapshots that have nothing to move but still change shape: a mixed-version
+    payload storing both names (the migration drops the old one, so the stored ``batch_size`` still
+    has to be rehashed), one whose legacy value is non-positive (discarded by the parser), and a
+    modern payload (nothing to do). Replaying the stored spelling covers all of them uniformly.
+
+    A key merely holding null reports None; a key genuinely OMITTED is omitted from the reading too,
+    because the two hash differently. Every digest is taken over a serialized ``JobSpec``, which
+    emits both names, so a null was really hashed as null -- while 1.1.40 predates
+    ``prompts_per_step`` entirely and hashed no such key. Each half's reading therefore carries its
+    OWN absence rather than sharing one flag: after a re-persist the worker half is rewritten in the
+    modern shape while ``status.spec`` keeps the legacy one, so the halves genuinely disagree about
+    which keys exist and a single flag would misdescribe one of them.
+
+    This is not a way to forge a batch: the replayed values are the STORED ones, and the digest they
+    are compared against was computed over the ORIGINAL ones, so any tampering still mismatches.
+
+    Only a rollout algorithm is eligible: for sft ``batch_size`` is the current, un-migrated name,
+    which ``from_dict`` leaves alone.
+    """
+    if not isinstance(raw_spec, dict):
+        return None
+    if not samples_on_policy(normalize_algorithm(str(raw_spec.get("algorithm") or ""))):
+        return None
+    train = raw_spec.get("train")
+    if not isinstance(train, dict):
+        return None
+    stored = {key: train.get(key) for key in _ROLLOUT_BATCH_KEYS}
+    # the 1.1.40 shape, read off the bytes themselves: it carried the old name and no new one.
+    # a payload omitting both says nothing about when it was written, and the serializer always
+    # emits both -- so treating that as absence would drop a key that was hashed.
+    if "batch_size" in train and "prompts_per_step" not in train:
+        del stored["prompts_per_step"]
+    return stored
+
+
+def _restore_rollout_batch_spelling(payload: dict, stored: dict | None) -> None:
+    """Put the optimizer-batch keys back exactly as the stored payload hashed them.
+
+    A key absent from ``stored`` was absent from the hashed bytes, so it is removed rather than
+    written -- that is the 1.1.40 shape, which predates ``prompts_per_step``.
+    """
+    if stored is None:
+        return
+    train = payload.get("train")
+    if not isinstance(train, dict):
+        return
+    for key in _ROLLOUT_BATCH_KEYS:
+        if key in stored:
+            train[key] = stored[key]
+        else:
+            train.pop(key, None)
+
+
+@dataclass(frozen=True)
+class VersionedPersistedSpecEnvelope:
+    """How a persisted snapshot's bytes were spelled when its digest was taken.
+
+    Every field here answers one question -- what did the STORED payload look like, not what does
+    this build serialize -- and each is read off bytes that are never rewritten, so the answers are
+    stable for the run's life. They were previously five keyword arguments threaded through three
+    call sites in lockstep; nothing ever passed a meaningful subset, because they are one reading.
+
+    Empty is the correct default for a snapshot written by this build: there is nothing to rewind,
+    so ``rewind()`` is a no-op and the digest is taken over today's serialization directly.
+    """
+
+    CURRENT_VERSION: ClassVar[int] = _PREPARATION_ENVELOPE_VERSION
+
+    version: int = CURRENT_VERSION
+    worker_dropped_keys: Mapping[str, Any] = field(default_factory=dict)
+    public_dropped_keys: Mapping[str, Any] = field(default_factory=dict)
+    public_omits_lora_alpha: bool = False
+    worker_rollout_batch: dict[str, Any] | None = None
+    public_rollout_batch: dict[str, Any] | None = None
+
+    @classmethod
+    def read(
+        cls,
+        snapshot: object,
+        raw_public: object,
+        *,
+        include_worker: bool = True,
+    ) -> VersionedPersistedSpecEnvelope:
+        """Read one persisted preparation envelope and its public half.
+
+        Historical snapshots predate the explicit version key and are version 1 by definition. A
+        newer version is rejected rather than guessed: the digest cannot reveal which serialization
+        produced it, so an older build has no safe replay strategy for bytes it does not understand.
+
+        The public and worker halves keep independent spelling. After re-persistence the worker half
+        is rewritten in the modern shape while ``status.spec`` stays historical; ``include_worker``
+        is false on that write path so old worker spelling is not replayed onto newly serialized bytes.
+        """
+        snapshot = snapshot if isinstance(snapshot, Mapping) else {}
+        version = snapshot.get("version", cls.CURRENT_VERSION)
+        if isinstance(version, bool) or not isinstance(version, int) or version < 1:
+            raise ValueError("persisted preparation envelope version must be a positive integer")
+        if version != cls.CURRENT_VERSION:
+            raise ValueError(f"unsupported persisted preparation envelope version {version}")
+        raw_worker = snapshot.get("worker_spec") if include_worker else None
+        return cls(
+            version=version,
+            worker_dropped_keys=_dropped_key_subset(raw_worker),
+            public_dropped_keys=_dropped_key_subset(raw_public),
+            public_omits_lora_alpha=_prepared_before_public_alpha(raw_public),
+            worker_rollout_batch=_stored_rollout_batch_spelling(raw_worker),
+            public_rollout_batch=_stored_rollout_batch_spelling(raw_public),
+        )
+
+    def rewind(self, public_payload: dict, worker_payload: dict) -> None:
+        """Rewind today's serialization to the bytes this snapshot actually hashed.
+
+        None of this can forge a value: every replayed key comes from the STORED payload, and the
+        digest it is compared against was computed over the ORIGINAL one, so tampering still
+        mismatches. Only keys registered as historical removals are honoured -- filtered HERE and
+        not just at ``read()``, because an instance can be built directly -- so a field the
+        dataclass still defines always comes from the spec itself.
+        """
+        # the rollout optimizer batch was renamed `batch_size` -> `prompts_per_step`, and from_dict
+        # moves it when reparsing -- so a spec written before or across the rename only reproduces
+        # its digest under the spelling it actually stored, including a key it did not have.
+        _restore_rollout_batch_spelling(worker_payload, self.worker_rollout_batch)
+        _restore_rollout_batch_spelling(public_payload, self.public_rollout_batch)
+        # a pre-upgrade snapshot hashed `model_policy` in (to_internal_dict was asdict, so it emitted
+        # the defaulted value) and the field no longer exists, so rehashing without it fails a
+        # still-valid run's integrity check on recovery.
+        worker_payload.update(_dropped_key_subset(self.worker_dropped_keys))
+        # a dropped key that was user-authorable was hashed on the public side too. model_policy
+        # never was, so the worker half sufficed for it; model_revision and worker_env were.
+        public_payload.update(_dropped_key_subset(self.public_dropped_keys))
+        # ``lora_alpha`` became user-authorable, so to_dict() now emits it for non-warm-start runs.
+        # scoped to legacy snapshots only: a digest created from here on binds the public alpha, and
+        # without that binding the two halves can disagree silently -- `_validate_effective_spec`
+        # excludes lora_alpha from its structural comparison, leaving the digest as the only cover.
+        if self.public_omits_lora_alpha:
+            public_payload["train"].pop("lora_alpha", None)
+
+
+def _dropped_key_subset(raw_spec: object) -> dict[str, Any]:
+    """The since-removed top-level keys a mapping carries, and nothing else.
+
+    Applied on the way in AND on the way out: a key the dataclass still defines must come from the
+    spec, never from a replayed reading, so the filter has to sit at the apply site too.
+    """
+    if not isinstance(raw_spec, Mapping):
+        return {}
+    return {key: raw_spec[key] for key in DROPPED_TOP_LEVEL_KEYS if key in raw_spec}

{freesolo_flash_dev-1.2.59 → freesolo_flash_dev-1.2.61}/flash/engine/worker/backend_common.py

@@ -935,6 +935,7 @@ from flash.engine.worker.verl.capabilities import (  # noqa: E402,F401
     resolve_rollout_enforce_eager,
     resolve_verl_loggers,
     resolve_verl_python,
+    rollout_mm_processor_cache_overrides,
     rollout_resident_overrides,
     rollout_sleep_unsupported,
     strict_gdn_probe_module,