freesolo-flash-dev 1.0.43__tar.gz → 1.0.45__tar.gz

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 1.0.43
+Version: 1.0.45
 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.0.43 → freesolo_flash_dev-1.0.45}/flash/cli/training_doc.py

@@ -697,6 +697,39 @@ on a beyond-noise improvement.
 
 ---
 
+## Multi-GPU training (`gpu.count > 1`)
+
+Flash trains on one card by default. The default `trl` backend is single-process and never
+reads `gpu.count`, so raising the count alone would rent n cards and train on one — submit
+rejects that rather than billing for idle hardware.
+
+To shard one job across several cards, select the `verl` backend for the phase you are running:
+
+```toml
+[gpu]
+type = "B200"
+count = 4
+# provider must also be pinned: not every provider puts all n cards on ONE machine, and
+# submit names the ones that qualify when it rejects an unpinned multi-gpu spec.
+
+[worker_env]
+FLASH_SFT_BACKEND = "verl"   # SFT
+# FLASH_RL_BACKEND  = "verl"   # GRPO  (the key is RL, not GRPO)
+# FLASH_OPD_BACKEND = "verl"   # OPD
+```
+
+One key per phase, and GRPO's is `FLASH_RL_BACKEND`. The verl worker launches one rank per
+card with Ulysses sequence parallelism.
+
+The verl GRPO backend covers single-turn, non-tool, non-multimodal runs; multi-turn, tool, and
+image-prompt environments stay on `trl` (which is single-GPU). Warm-starting with
+`init_from_adapter` while `kl_penalty_coef > 0` is also `trl`-only: verl computes its KL
+reference with adapters disabled, so the reference would be the bare base model instead of your
+SFT adapter, pulling the policy back toward base. Every one of these raises at startup rather
+than quietly training on a different contract.
+
+---
+
 ## Command reference
 
 ```bash

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/flash/engine/worker/opd_verl.py

@@ -86,6 +86,20 @@ _TEXT_TEACHER_SHUTDOWN_WAIT_S = 5.0
 _TEXT_TEACHER_REQUEST_BACKLOG = 64
 
 
+def _align_granularity(groups, student_tokens) -> float:
+    """mean student-tokens-per-group: the alignment-health signal coverage cannot provide.
+
+    a degenerate alignment that collapses every student token onto a single group still scores
+    coverage ~1.0, so coverage alone never flags it. this is the trl opd formula verbatim
+    (``opd.py``): non-empty student spans over surviving groups, counted after fully-forced groups
+    are dropped so the ratio describes the signal that actually reaches the loss.
+    """
+    if not groups:
+        return 0.0
+    n_align = sum(1 for st in student_tokens if st.end > st.start)
+    return n_align / len(groups)
+
+
 class _TeacherBridgeHTTPServer(ThreadingHTTPServer):
     request_queue_size = _TEXT_TEACHER_REQUEST_BACKLOG
 
@@ -518,6 +532,12 @@ class _TeacherAlignmentBridge:
         self.forced_tokens = int(state.get("forced_tokens", 0))
         self.dropped_forced_groups = int(state.get("dropped_forced_groups", 0))
         self.coverage_sum = float(state.get("coverage_sum", state.get("granularity_sum", 0.0)))
+        # alignment GRANULARITY (mean aligned-groups-per-sequence), distinct from coverage: a
+        # collapsed alignment that maps every student token onto one group still scores coverage
+        # ~1.0, so coverage alone cannot flag that failure mode. no legacy alias here -- the old
+        # granularity_* state keys held coverage, so reading them would restore the wrong quantity.
+        self.align_group_sum = float(state.get("align_group_sum", 0.0))
+        self.align_group_n = int(state.get("align_group_n", 0))
         # resume: baseline the per-step delta counters at the restored cumulative mass, so the
         # first resumed step reports its own coverage instead of the whole prior run's.
         self._prev_aligned = self.aligned_sequences
@@ -648,6 +668,8 @@ class _TeacherAlignmentBridge:
                 "aligned_sequences": self.aligned_sequences,
                 "empty_alignments": self.empty_alignments,
                 "coverage_sum": self.coverage_sum,
+                "align_group_sum": self.align_group_sum,
+                "align_group_n": self.align_group_n,
             }
 
     def _empty(self, prompt_length: int, response_length: int) -> dict:
@@ -756,12 +778,15 @@ class _TeacherAlignmentBridge:
         aligned_group_count = len(groups)
         groups = _drop_fully_forced_groups(groups, kept_forced)
         coverage = groupwise_coverage(groups, student_tokens)
+        granularity = _align_granularity(groups, student_tokens)
         with self._stats_lock:
             self.teacher_input_tokens += teacher_input_tokens
             self.dropped_forced_groups += aligned_group_count - len(groups)
             self.coverage_sum += coverage
             if groups:
                 self.aligned_sequences += 1
+                self.align_group_sum += granularity
+                self.align_group_n += 1
             else:
                 self.empty_alignments += 1
         teacher_ids, teacher_logprobs = encode_shifted_group_metadata(
@@ -1084,11 +1109,14 @@ class _TeacherAlignmentBridge:
                     groups = groupwise_alignment(student_tokens, teacher_tokens)
                     groups = [(indices, logsum) for indices, logsum in groups if indices]
                     coverage = groupwise_coverage(groups, student_tokens)
+                    granularity = _align_granularity(groups, student_tokens)
                     with self._stats_lock:
                         self.teacher_input_tokens += len(turn["prompt_ids"]) + len(student_ids)
                         self.coverage_sum += coverage
                         if groups:
                             self.aligned_sequences += 1
+                            self.align_group_sum += granularity
+                            self.align_group_n += 1
                         else:
                             self.empty_alignments += 1
                     teacher_ids, teacher_logprobs = encode_shifted_group_metadata(
@@ -2515,6 +2543,17 @@ def run_opd_verl(spec=None) -> None:
                 "verl OPD produced no distillation-loss metrics for the whole run — the "
                 "distillation path never engaged; refusing to publish"
             )
+        if len(final_accounting["loss_curve"]) != final_step:
+            # record_step only checks that each metric line FOLLOWS the last one, so a missing
+            # trailing metric (on_line skips any step-tagged line whose loss it cannot parse) leaves
+            # a curve shorter than the checkpoint verl actually wrote, and nothing later arrives to
+            # catch it. opt_steps is published from this curve, so a short curve would understate the
+            # updates applied. fail loud instead of reporting a number the curve cannot support.
+            raise RuntimeError(
+                f"verl OPD recorded {len(final_accounting['loss_curve'])} distillation-loss metrics "
+                f"for {final_step} optimizer updates; refusing to publish an accounting that does "
+                "not cover every update"
+            )
         if int(final_accounting.get("aligned_sequences", 0) or 0) <= 0:
             # zeroed-mask pass-through batches still emit a (zero) loss metric, so the loss-curve
             # check alone cannot distinguish real distillation from a run where the teacher never
@@ -2553,6 +2592,10 @@ def run_opd_verl(spec=None) -> None:
             generated_tokens=int(final_accounting["generated_tokens"]),
             notes={
                 "steps": update_horizon,
+                # optimizer updates that actually produced a distillation loss. record_step enforces
+                # loss_curve length == the metric step, and the guard above rejects a curve shorter
+                # than final_step, so this is measured, not assumed.
+                "opt_steps": len(final_accounting["loss_curve"]),
                 "epochs": knobs.epochs,
                 "retained_prompts": len(prompts),
                 "dropped_long_prompts": dropped_long,
@@ -2568,6 +2611,15 @@ def run_opd_verl(spec=None) -> None:
                     if final_accounting["aligned_sequences"]
                     else 0.0
                 ),
+                # the real alignment-health signal. mean_coverage reads ~1.0 even when the alignment
+                # has collapsed every student token onto one group, so it cannot flag that failure
+                # mode on its own; this ratio can.
+                "mean_align_granularity": (
+                    float(final_accounting["align_group_sum"])
+                    / int(final_accounting["align_group_n"])
+                    if final_accounting["align_group_n"]
+                    else 0.0
+                ),
                 "truncated_rollouts": int(final_accounting["truncated_rollouts"]),
                 "forced_tokens": int(final_accounting["forced_tokens"]),
                 "dropped_forced_groups": int(
@@ -2591,6 +2643,23 @@ def run_opd_verl(spec=None) -> None:
                     if multi_turn and final_accounting["episodes_seen"]
                     else None
                 ),
+                # the engine length actually handed to vllm (prompt + completion), already clamped to
+                # the model's own limit. the prompt filter is carved out of this same number.
+                "vllm_max_model_len": max_model_len,
+                # teacher call shape. only the single-turn TEXT path goes through the batcher, which
+                # holds a fixed cap and one serial scoring thread. the multimodal path scores one
+                # item per call and the multi-turn path batches a whole episode, and both run on the
+                # bridge's own request threads -- neither has a constant, so None records "not
+                # batched by flash" instead of asserting a number nothing enforces.
+                # the cap is bounded by the samples one step can actually produce (trl does the same
+                # in _opd_teacher_batch_size): a step of 1 rollout can never fill a batch of 8, and
+                # reporting the global cap there would describe a shape the run cannot reach.
+                "opd_teacher_batch_size": (
+                    min(_TEXT_TEACHER_BATCH_SIZE, max(1, prompts_per_step * knobs.group_size))
+                    if not multimodal and not multi_turn
+                    else None
+                ),
+                "opd_teacher_workers": 1 if not multimodal and not multi_turn else None,
                 "rollout_backend": "verl_vllm",
                 "verl_version": "0.8.0",
                 "verl_backend": "fsdp",

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/flash/opd_retry_contract.py

@@ -17,7 +17,12 @@ OPD_OPTIMIZER_START_PHASE = "opd"
 OPD_RETRY_ARTIFACT_PREFIX = "_opd_retry"
 OPD_OPTIMIZER_START_FILENAME = "optimizer-start.v1.json"
 OPD_RESUME_REVISION_ENV = "FLASH_OPD_RESUME_REVISION"
-OPD_RESUME_STATE_VERSION = 2
+# bumped to 3 when the verl worker began accumulating align_group_sum/align_group_n. a version-2
+# state carries neither, so resuming one would restart the accumulator at zero and publish a
+# post-resume-only mean_align_granularity as though it described the whole run. the version check
+# below already rejects mismatches fail-closed, so the bump refuses those states outright instead of
+# threading a completeness flag through the accounting.
+OPD_RESUME_STATE_VERSION = 3
 MAX_BOUNDED_NONNEGATIVE_INTEGER = (1 << 63) - 1
 
 # a full-state opd resume checkpoint (the custom loop's counterpart to the hf trainer's checkpoint-n)
@@ -55,6 +60,13 @@ _OPD_RESUME_ACCOUNTING_SCHEMA = {
     "opd_phase_seconds": "dict",
     "opd_phase_counts": "dict",
 }
+# alignment granularity, accumulated only by the verl worker. the trl worker's granularity lives in
+# the granularity_* slots above; in verl those same slots hold COVERAGE, so verl carries its own pair
+# and both must be validated when present rather than coerced past the fail-closed contract.
+_OPD_RESUME_OPTIONAL_ACCOUNTING_SCHEMA = {
+    "align_group_sum": "nonneg_number",
+    "align_group_n": "nonneg_int",
+}
 
 
 def bounded_nonnegative_integer(value: object, *, field: str) -> int:
@@ -136,6 +148,14 @@ def validate_opd_resume_state_metadata(
         elif field_type == "dict" and not isinstance(value, dict):
             raise ValueError(f"opd resume state {field} must be an object")
 
+    for field, field_type in _OPD_RESUME_OPTIONAL_ACCOUNTING_SCHEMA.items():
+        if field not in state:
+            continue
+        if field_type == "nonneg_int":
+            _nonnegative_integer(state[field], field=field)
+        else:
+            _finite_number(state[field], field=field, nonnegative=True)
+
     for field in ("loss_curve", "coverage_curve"):
         curve = state[field]
         if len(curve) != opt_steps:

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/flash/runner/__init__.py

@@ -1187,6 +1187,15 @@ _MULTI_GPU_BACKENDS: frozenset[str] = frozenset({"verl"})
 _MULTI_GPU_PROVIDERS: frozenset[str] = frozenset({"runpod"})
 
 
+def _backend_env_key(spec: JobSpec) -> str:
+    """the [worker_env] key that selects this spec's training backend.
+
+    one definition so the gate's remedy cannot name a different key than the resolver reads: the
+    phase mapping is not derivable from the algorithm (grpo -> FLASH_RL_BACKEND).
+    """
+    return f"FLASH_{spec.phase.upper()}_BACKEND"
+
+
 def _effective_backend(spec: JobSpec) -> str:
     """the training backend this spec will actually run, as the worker resolves it.
 
@@ -1195,7 +1204,7 @@ def _effective_backend(spec: JobSpec) -> str:
     empty dict and forwards a fixed credential allowlist, never the ambient control-plane env. so the
     backend is a property of the SPEC and the gate can read it here rather than guessing.
     """
-    key = f"FLASH_{spec.phase.upper()}_BACKEND"
+    key = _backend_env_key(spec)
     worker_env = getattr(spec, "worker_env", None) or {}
     for name, value in worker_env.items():
         if str(name).upper() == key:
@@ -1215,10 +1224,16 @@ def _require_supported_gpu_count(spec: JobSpec) -> None:
         return
     backend = _effective_backend(spec)
     if backend not in _MULTI_GPU_BACKENDS:
+        # name the key that actually enables sharding. the backend is selected only through
+        # [worker_env], which no other error or doc mentions, so a message that offers just
+        # "set gpu.count to 1" leaves multi-gpu undiscoverable.
+        key = _backend_env_key(spec)
+        sharding = ", ".join(sorted(_MULTI_GPU_BACKENDS))
         raise ValueError(
             f"multi-gpu training (gpu.count={count}) is not supported by the {backend!r} backend "
             f"for algorithm {spec.algorithm!r}; it trains in a single process and would leave "
-            f"{count - 1} rented card(s) idle. set gpu.count to 1"
+            f"{count - 1} rented card(s) idle. set gpu.count to 1, or select a sharding backend "
+            f'with [worker_env] {key} = "{sharding}"'
         )
     provider = (getattr(spec.gpu, "provider", "") or "").strip().lower()
     if provider not in _MULTI_GPU_PROVIDERS:

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "freesolo-flash-dev"
-version = "1.0.43"
+version = "1.0.45"
 description = "Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI"
 readme = "README.md"
 # RunPod Flash supports Python 3.11-3.12 (not 3.13 yet).
@@ -116,7 +116,7 @@ artifacts = ["flash/py.typed"]
 # auto-published by .github/workflows/publish-dev.yml: a push to `dev` whose version isn't yet on
 # PyPI publishes it; pushes that don't change it find it already published and no-op. So cutting a
 # dev-channel release = bump this (and [project].version) and merge to `dev`.
-version = "1.0.43"
+version = "1.0.45"
 
 [tool.pytest.ini_options]
 pythonpath = ["."]

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/tests/test_multi_gpu_gate.py

@@ -110,3 +110,24 @@ def test_run_training_gates_effective_spec_on_recovery():
     # before any provisioning (the gate precedes the first get_status/allocation touch).
     with pytest.raises(ValueError, match="multi-gpu training"):
         _run_training(_spec(2), io.StringIO(), prior_cost=0.0)
+
+
+@pytest.mark.parametrize(
+    ("algorithm", "key"),
+    [("sft", "FLASH_SFT_BACKEND"), ("grpo", "FLASH_RL_BACKEND"), ("opd", "FLASH_OPD_BACKEND")],
+)
+def test_gate_message_names_the_key_that_enables_sharding(algorithm, key):
+    from flash import runner
+
+    # [worker_env] is the ONLY route to a sharding backend, and the phase key is not guessable from
+    # the algorithm (grpo -> FLASH_RL_BACKEND). a message offering only "set gpu.count to 1" leaves
+    # multi-gpu undiscoverable, so assert the remedy travels with the rejection.
+    # match the backend rejection specifically: the gate also raises for gpu.provider, and that
+    # path carries no backend key, so a bare raises() would pass while checking nothing.
+    with pytest.raises(ValueError, match="multi-gpu training") as excinfo:
+        runner._require_supported_gpu_count(_spec(4, algorithm))
+
+    message = str(excinfo.value)
+    assert key in message
+    assert "verl" in message
+    assert "worker_env" in message

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/tests/test_opd_resume_safety.py

@@ -1123,6 +1123,62 @@ def test_gate_blocks_pinned_checkpoint_metadata_download_failure(monkeypatch, tm
         _run_gate()
 
 
+@pytest.mark.parametrize(
+    "overrides",
+    [
+        {"align_group_sum": float("nan")},
+        {"align_group_sum": float("inf")},
+        {"align_group_sum": -1.0},
+        {"align_group_n": -1},
+        {"align_group_n": 1.5},
+        {"align_group_n": True},
+    ],
+)
+def test_resume_validator_rejects_corrupt_alignment_granularity(overrides):
+    # the verl worker resumes its granularity accumulators from these fields and publishes their
+    # ratio into train_meta. a tampered or corrupt checkpoint must fail the fail-closed contract
+    # here, not coerce past it and propagate a non-finite or negative mean into every later
+    # checkpoint and the run's reported alignment health.
+    state = _valid_resume_state(2, **overrides)
+    # match on the corrupt field itself: a validator that rejected for some unrelated reason would
+    # pass a bare raises() while leaving this pair entirely unchecked.
+    (field,) = overrides
+
+    with pytest.raises(ValueError, match=field):
+        validate_opd_resume_state_metadata(state, expected_seed=42, checkpoint_step=2)
+
+
+def test_resume_state_version_rejects_states_predating_alignment_granularity():
+    # the verl worker resumes align_group_sum/align_group_n and publishes their ratio as
+    # mean_align_granularity. a state written before those accumulators existed carries neither, so
+    # resuming one restarts the accumulator at zero and the ratio would describe only the
+    # post-resume samples while being reported as the whole run's alignment health. the contract
+    # version is the enforcement point: it must have moved past 2 so the existing fail-closed check
+    # refuses those states outright.
+    assert OPD_RESUME_STATE_VERSION > 2
+
+    stale = _valid_resume_state(2)
+    stale["contract_version"] = 2
+
+    with pytest.raises(ValueError, match="contract_version"):
+        validate_opd_resume_state_metadata(stale, expected_seed=42, checkpoint_step=2)
+
+
+def test_resume_validator_accepts_alignment_granularity_and_states_without_it():
+    # verl writes the pair; trl does not. both must validate, so the fields are checked when present
+    # rather than required -- otherwise adding them would reject every trl checkpoint.
+    with_granularity = _valid_resume_state(2, align_group_sum=3.0, align_group_n=2)
+    validated = validate_opd_resume_state_metadata(
+        with_granularity, expected_seed=42, checkpoint_step=2
+    )
+    assert validated["align_group_sum"] == 3.0
+    assert validated["align_group_n"] == 2
+
+    without = _valid_resume_state(2)
+    assert "align_group_sum" not in without
+    validate_opd_resume_state_metadata(without, expected_seed=42, checkpoint_step=2)
+
+
 def test_shared_resume_metadata_validator_returns_a_copy():
     state = _valid_resume_state(3)
 

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/tests/test_opd_verl.py

@@ -64,6 +64,7 @@ from flash.engine.worker.opd_verl_structured import (
     canonical_structured_spec,
 )
 from flash.engine.worker.tokenizer_align import TeacherToken
+from flash.opd_retry_contract import OPD_RESUME_STATE_VERSION
 from flash.opd_verl_validation import validate_opd_verl_structured_outputs
 
 
@@ -719,7 +720,7 @@ class _BridgeTokenizer:
 
 def _resume_accounting(step=2):
     return {
-        "contract_version": 2,
+        "contract_version": OPD_RESUME_STATE_VERSION,
         "seed": 42,
         "opt_steps": step,
         "step": step,
@@ -841,7 +842,14 @@ def test_write_train_meta_integrates_canonical_failure_accounting_metadata():
     assert "**_failure_accounting_metadata(final_accounting)" in write_train_meta_source
     assert '"teacher_transient":' not in write_train_meta_source
     assert '"teacher_error":' not in write_train_meta_source
-    assert '"mean_align_granularity":' not in write_train_meta_source
+    # granularity IS reported, but only from its own accumulator. the snapshot's granularity_sum /
+    # granularity_n are legacy aliases holding COVERAGE, so deriving the ratio from them would
+    # publish coverage a second time under the name of the one signal coverage cannot provide.
+    assert '"mean_align_granularity":' in write_train_meta_source
+    assert 'final_accounting["align_group_sum"]' in write_train_meta_source
+    assert 'final_accounting["align_group_n"]' in write_train_meta_source
+    assert "granularity_sum" not in write_train_meta_source
+    assert "granularity_n" not in write_train_meta_source
 
 
 class _BridgeTeacher:
@@ -1051,6 +1059,87 @@ def test_bridge_verifies_prompt_and_serializes_aligned_native_fields():
         bridge.score(0, 2, [10, 12, 65, 99])
 
 
+def test_bridge_granularity_separates_a_collapsed_alignment_from_a_healthy_one():
+    # both teachers cover every student token, so coverage is 1.0 for BOTH and cannot tell them
+    # apart. the merged teacher returns one span where the healthy one returns two, which is the
+    # degenerate collapse mean_coverage is blind to -- granularity is the signal that sees it.
+    healthy = _text_bridge(_BridgeTeacher())
+    healthy.score(0, 2, [10, 11, 65, 66, 99])
+    collapsed = _text_bridge(_MergedBridgeTeacher())
+    collapsed.score(0, 2, [10, 11, 65, 66, 99])
+
+    assert healthy.coverage_sum == collapsed.coverage_sum == 1.0
+    assert healthy.aligned_sequences == collapsed.aligned_sequences == 1
+    # two student tokens over two groups vs two student tokens over one merged group.
+    assert healthy.align_group_sum == 1.0
+    assert collapsed.align_group_sum == 2.0
+    assert healthy.align_group_n == collapsed.align_group_n == 1
+
+
+def test_bridge_granularity_counts_only_sequences_that_reached_the_loss():
+    # a teacher that returns no tokens still reaches the accounting, but its sequence carries no
+    # groups and contributes nothing to the loss. folding its 0.0 into the mean would report a
+    # collapse that never happened -- it belongs in empty_alignments only.
+    class _EmptyAlignmentTeacher:
+        def score(self, _prompt_text, _completion_text):
+            return []
+
+    bridge = _text_bridge(_BridgeTeacher())
+    bridge.score(0, 2, [10, 11, 65, 66, 99])
+    assert bridge.align_group_n == 1
+    assert bridge.align_group_sum == 1.0
+
+    bridge.teacher = _ScoreManyTeacherAdapter(_EmptyAlignmentTeacher())
+    bridge._text_teacher_batcher = None
+    bridge.score(0, 2, [10, 11, 65, 66, 99])
+
+    assert bridge.empty_alignments == 1
+    # the empty sequence moved empty_alignments, and left the granularity mean untouched.
+    assert bridge.align_group_n == 1
+    assert bridge.align_group_sum == 1.0
+
+
+def test_bridge_granularity_survives_resume_without_reading_the_coverage_aliases():
+    # granularity_sum / granularity_n are LEGACY ALIASES for coverage. resuming granularity from
+    # them would silently restore coverage under the granularity name, so an old-format state must
+    # restart the accumulator at zero rather than inherit the wrong quantity.
+    resumed = _text_bridge(_BridgeTeacher())
+    state = dict(_resume_accounting())
+    state.update({"align_group_sum": 6.0, "align_group_n": 3})
+    carried = _TeacherAlignmentBridge(
+        prompts=list(resumed.prompts),
+        tokenizer=_BridgeTokenizer(),
+        teacher=_ScoreManyTeacherAdapter(_BridgeTeacher()),
+        thinking_prefill="",
+        eos_token_ids=frozenset({99}),
+        stop_sequences=(),
+        mutation_callback=lambda: None,
+        initial_state=state,
+    )
+    assert carried.align_group_sum == 6.0
+    assert carried.align_group_n == 3
+    snapshot = carried.accounting_snapshot()
+    assert snapshot["align_group_sum"] == 6.0
+    assert snapshot["align_group_n"] == 3
+
+    legacy_only = _TeacherAlignmentBridge(
+        prompts=list(resumed.prompts),
+        tokenizer=_BridgeTokenizer(),
+        teacher=_ScoreManyTeacherAdapter(_BridgeTeacher()),
+        thinking_prefill="",
+        eos_token_ids=frozenset({99}),
+        stop_sequences=(),
+        mutation_callback=lambda: None,
+        initial_state=_resume_accounting(),
+    )
+    # granularity_sum is 3.5 and granularity_n is 5 in that state; both must be ignored here.
+    assert legacy_only.align_group_sum == 0.0
+    assert legacy_only.align_group_n == 0
+    # the coverage accumulators, whose aliases those really are, DO still resume from them.
+    assert legacy_only.coverage_sum == 3.5
+    assert legacy_only.aligned_sequences == 5
+
+
 def test_text_teacher_batcher_enforces_max_batch_size_across_concurrent_requests():
     prompt_texts = [f"question-{index}" for index in range(17)]
     teacher = _BatchingTeacher(prompt_texts)
@@ -4919,6 +5008,109 @@ def test_deterministic_seed_uses_every_rollout_identity_component():
 
 
 
+def test_train_meta_records_the_optimizer_steps_that_actually_produced_a_loss():
+    import inspect
+
+    from flash.engine.worker.opd_verl import run_opd_verl
+
+    notes = inspect.getsource(run_opd_verl)
+    notes = notes[notes.index("_w.write_train_meta(") :]
+    # `steps` is the REQUESTED horizon. a step whose batch carried no teacher signal never applies
+    # an update, so reporting the horizon as the work done would overstate a partly-starved run.
+    assert '"steps": update_horizon,' in notes
+    assert '"opt_steps": len(final_accounting["loss_curve"]),' in notes
+
+
+def test_worker_refuses_to_publish_a_loss_curve_shorter_than_the_final_checkpoint():
+    import inspect
+
+    from flash.engine.worker.opd_verl import run_opd_verl
+
+    source = inspect.getsource(run_opd_verl)
+    # record_step only checks that each metric line FOLLOWS the previous one, so it cannot notice a
+    # MISSING TRAILING metric: on_line silently skips any step-tagged line whose loss it cannot
+    # parse, and no later step ever arrives to trip the sequence check. that leaves a curve of
+    # length N-1 for a run verl actually checkpointed at step N, and opt_steps is published straight
+    # from that curve. the guard must compare against final_step, not merely require non-emptiness.
+    assert 'if len(final_accounting["loss_curve"]) != final_step:' in source
+    guard = source[source.index('if len(final_accounting["loss_curve"]) != final_step:') :]
+    assert "raise RuntimeError(" in guard[:600]
+    # and it must sit BEFORE the publish, not after it.
+    assert source.index('if len(final_accounting["loss_curve"]) != final_step:') < source.index(
+        "_w.write_train_meta("
+    )
+
+
+def test_train_meta_reports_the_teacher_call_shape_only_where_one_is_enforced():
+    import inspect
+
+    from flash.engine.worker.opd_verl import run_opd_verl
+
+    notes = inspect.getsource(run_opd_verl)
+    notes = notes[notes.index("_w.write_train_meta(") :]
+    # only the single-turn text path runs through the batcher, and it holds one serial scoring
+    # thread. multimodal scores one item per call and multi-turn batches an episode, both on the
+    # bridge's own request threads -- neither has a constant to report.
+    # the reported cap is bounded by the samples one step can actually produce, matching trl's
+    # _opd_teacher_batch_size: a 1-rollout step can never fill a batch of 8, so publishing the
+    # global cap there would describe a shape the run is structurally unable to reach.
+    assert (
+        '"opd_teacher_batch_size": (\n'
+        "                    min(_TEXT_TEACHER_BATCH_SIZE, max(1, prompts_per_step * knobs.group_size))\n"
+        "                    if not multimodal and not multi_turn\n"
+        "                    else None\n"
+        "                ),"
+    ) in notes
+    assert (
+        '"opd_teacher_workers": 1 if not multimodal and not multi_turn else None,'
+    ) in notes
+    # the engine length handed to vllm, not a hardcoded default: prompt filtering is carved out of
+    # this same number, so a fabricated one would disagree with the budget the run actually used.
+    assert '"vllm_max_model_len": max_model_len,' in notes
+
+
+def test_text_teacher_batcher_scores_one_batch_at_a_time():
+    # opd_teacher_workers reports 1 for the text path. that is only honest while the batcher scores
+    # serially, so assert the observable property rather than the thread count: no two score_many
+    # calls may ever overlap, however the batcher is wired internally.
+    from flash.engine.worker.opd_verl import _TextTeacherBatcher
+
+    class _OverlapDetectingTeacher:
+        def __init__(self):
+            self.lock = threading.Lock()
+            self.in_flight = 0
+            self.max_in_flight = 0
+
+        def score_many(self, items):
+            with self.lock:
+                self.in_flight += 1
+                self.max_in_flight = max(self.max_in_flight, self.in_flight)
+            # hold the call open long enough that a second scoring thread would land inside it.
+            time.sleep(0.05)
+            with self.lock:
+                self.in_flight -= 1
+            return [
+                [TeacherToken(text=completion, logprob=-1.0, start=0, end=len(completion))]
+                for _prompt, completion in items
+            ]
+
+    teacher = _OverlapDetectingTeacher()
+    batcher = _TextTeacherBatcher(teacher, max_batch_size=1, flush_wait_s=0.01)
+    batcher.start()
+    try:
+        with ThreadPoolExecutor(max_workers=8) as executor:
+            futures = [
+                executor.submit(batcher.score, f"prompt-{index}", f"completion-{index}")
+                for index in range(8)
+            ]
+            for future in futures:
+                future.result(timeout=10.0)
+    finally:
+        batcher.close()
+
+    assert teacher.max_in_flight == 1
+
+
 def test_worker_structured_validator_runs_before_model_download():
     import inspect
 

{freesolo_flash_dev-1.0.43 → freesolo_flash_dev-1.0.45}/uv.lock

@@ -1025,7 +1025,7 @@ wheels = [
 
 [[package]]
 name = "freesolo-flash"
-version = "1.0.43"
+version = "1.0.45"
 source = { editable = "." }
 
 [package.optional-dependencies]