freesolo-flash-dev 1.2.12__tar.gz → 1.2.14__tar.gz

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/.gitignore

@@ -1,6 +1,9 @@
 __pycache__/
 *.pyc
-.venv/
+# no trailing slash: a checkout may point `.venv` at a venv stored elsewhere, and a `.venv/` rule
+# matches only a directory, so the symlink itself stays trackable and `git add -A` commits it.
+# committing it breaks CI on the next run, where `uv sync` aborts on an existing `.venv` path.
+.venv
 venv/
 *.egg-info/
 dist/

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.2.12
+Version: 1.2.14
 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.12 → freesolo_flash_dev-1.2.14}/flash/adapters/lora_rank.py

@@ -7,11 +7,11 @@ import json
 import math
 import re
 from collections.abc import Callable, Mapping
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from decimal import Decimal, InvalidOperation
 from typing import TYPE_CHECKING, Any
 
-from flash.core.catalog import serving_context_cap, serving_lora_rank_cap
+from flash.core.catalog import lora_expert_count, serving_context_cap, serving_lora_rank_cap
 
 
 class ServingPreflightError(ValueError):
@@ -279,6 +279,117 @@ def rank_from_adapter_config(config: Mapping[str, Any], *, source: str) -> int:
     )
 
 
+_LORA_A_INFIX = ".lora_A."
+_LORA_B_INFIX = ".lora_B."
+
+
+@dataclass(frozen=True)
+class DeclaredLoraRanks:
+    """The default rank, per-module overrides, and parameter-target module paths in a config."""
+
+    default: int | None = None
+    by_module: Mapping[str, int] = field(default_factory=dict)
+    stacked_rank_modules: tuple[str, ...] = ()
+    stacked_rank_multiplier: int | None = None
+
+    def __bool__(self) -> bool:
+        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
+
+    stacked_rank_modules: list[str] = []
+    targets = config.get("target_parameters")
+    if isinstance(targets, list):
+        for target in targets:
+            if not isinstance(target, str):
+                continue
+            module, separator, _ = target.rpartition(".")
+            if separator and module:
+                stacked_rank_modules.append(module)
+
+    base_model = str(config.get("base_model_name_or_path") or "").strip()
+    return DeclaredLoraRanks(
+        default=default,
+        by_module=by_module,
+        stacked_rank_modules=tuple(stacked_rank_modules),
+        stacked_rank_multiplier=lora_expert_count(base_model),
+    )
+
+
+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():
+        if not module:
+            continue
+        try:
+            # entries are regexes in PEFT, deliberately not escaped here either
+            if re.match(rf"(.*\.)?({module})$", module_path):
+                return rank
+        except re.error:
+            continue
+    return declared.default
+
+
+def _module_uses_target_parameters(module_path: str, declared: DeclaredLoraRanks) -> bool:
+    """Whether this serialized module came from one of PEFT's targeted parameters."""
+    return any(
+        module_path == module or module_path.endswith(f".{module}")
+        for module in declared.stacked_rank_modules
+    )
+
+
+def lora_tensor_rank_disagrees(key: str, shape: Any, declared: DeclaredLoraRanks) -> bool:
+    """Return whether a 2-D LoRA weight provably contradicts its configured rank.
+
+    Ordinary module weights carry exactly ``r`` on the LoRA axis. A 3-D parameter targeted through
+    PEFT's ``target_parameters`` serializes under its parent module and stacks every model expert on
+    that axis, so only that module may carry exactly ``r * num_experts``. The distinction must be per
+    module because one config may contain ordinary ``target_modules`` and fused parameters together.
+    """
+    if not declared:
+        return False
+    is_a = _LORA_A_INFIX in key
+    is_b = _LORA_B_INFIX in key
+    if is_a == is_b:  # neither, or a key somehow claiming both
+        return False
+    if not isinstance(shape, (list, tuple)) or len(shape) != 2:
+        return False
+    dims = [d for d in shape if isinstance(d, int) and not isinstance(d, bool) and d > 0]
+    if len(dims) != 2:
+        return False
+
+    infix = _LORA_A_INFIX if is_a else _LORA_B_INFIX
+    module_path = key.partition(infix)[0]
+    rank = _rank_for_module(module_path, declared)
+    if rank is None:
+        return False
+    axis = dims[0] if is_a else dims[1]
+    if _module_uses_target_parameters(module_path, declared):
+        multiplier = declared.stacked_rank_multiplier
+        expected = rank * multiplier if multiplier is not None else rank
+        return axis != expected
+    return axis != rank
+
+
 def alpha_from_adapter_config(config: Mapping[str, Any], *, source: str) -> int:
     """Return the maximum LoRA alpha across default and per-module metadata."""
     return _max_adapter_value(

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/flash/cli/commands/__init__.py

@@ -430,6 +430,7 @@ def cmd_train(args) -> int:
         else:
             print(json.dumps(status, indent=2))
         _print_unpacked_batch_warning(status, spec)  # after the payload, so stdout stays parseable
+        _print_reasoning_loss_warning(status)
         return 0
     status = client.create_run(
         payload,
@@ -438,6 +439,7 @@ def cmd_train(args) -> int:
     )
     run_id = status["run_id"]
     _print_unpacked_batch_warning(status, spec)  # a real submit overrides batch_size the same way
+    _print_reasoning_loss_warning(status)  # and trains on whatever reasoning the template kept
     logger.info(
         "submitted run %s: model=%s algorithm=%s gpu=%s",
         run_id,
@@ -970,6 +972,7 @@ from flash.cli.commands.train_cost import (  # noqa: E402,F401
     _cmd_train_cost_offline,
     _cmd_train_cost_sft,
     _legacy_train_key_rejection_detail,
+    _print_reasoning_loss_warning,
     _print_sft_cost,
     _print_train_schema_compatibility,
     _print_unpacked_batch_warning,

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/flash/cli/commands/train_cost.py

@@ -17,7 +17,11 @@ from flash.client import ApiError, ClientError
 from flash.client.runtime_secrets import runtime_secrets_from_local_env
 from flash.client.specs import spec_payload
 from flash.cost.spec import runconfig_from_spec
-from flash.engine.profiling.workload_profile import unpacked_batch_warning
+from flash.engine.profiling.workload_profile import (
+    reasoning_warning_rows,
+    rendered_reasoning_loss_warning,
+    unpacked_batch_warning,
+)
 from flash.schema import spec_and_train_keys_from_file, train_schema_metadata
 
 
@@ -190,6 +194,41 @@ def _print_unpacked_batch_warning(status: object, spec) -> None:
     print(render.warn(message) if render.styled() else f"warning: {message}", file=sys.stderr)
 
 
+def _print_reasoning_loss_warning(status: object) -> None:
+    """Warn that the chat template drops authored reasoning before a training GPU is allocated.
+
+    Control-plane profiling runs inside the server, so the measurement's own stderr never reaches
+    the submitting client. The counts travel on the quote's profile and the line is rendered here,
+    which is the only place the user can act on it while restructuring is still free.
+    """
+    profile = status.get("workload_profile") if isinstance(status, dict) else None
+    if not isinstance(profile, dict):
+        return
+    authored = profile.get("authored_reasoning_turns")
+    rendered = profile.get("rendered_reasoning_spans")
+    if isinstance(authored, bool) or not isinstance(authored, int):
+        return
+    if isinstance(rendered, bool) or not isinstance(rendered, int):
+        return
+    truncated = profile.get("truncated_reasoning_spans")
+    message = rendered_reasoning_loss_warning(
+        authored_turns=authored,
+        rendered_spans=rendered,
+        # absent on a profile from an older producer, where the two causes were not yet separated.
+        # zero reads as "none were truncated", which is the pre-split behaviour.
+        truncated_spans=truncated
+        if isinstance(truncated, int) and not isinstance(truncated, bool)
+        else 0,
+        # the counts above cover the rows the update horizon reaches, so the denominator has to
+        # cover the same rows. `retained_examples` is the whole retained dataset -- it sizes the
+        # allocation -- and pairing it with bounded counts would understate the survival rate.
+        rows=reasoning_warning_rows(profile),
+    )
+    if not message:
+        return
+    print(render.warn(message) if render.styled() else f"warning: {message}", file=sys.stderr)
+
+
 def _print_sft_cost(status: dict, spec) -> None:
     total = status.get("estimated_cost_usd") if isinstance(status, dict) else None
     if not isinstance(total, (int, float)) or isinstance(total, bool):
@@ -215,6 +254,7 @@ def _print_sft_cost(status: dict, spec) -> None:
         file=sys.stderr,
     )
     _print_unpacked_batch_warning(status, spec)
+    _print_reasoning_loss_warning(status)
 
 
 def _legacy_train_key_rejection_detail(

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/flash/cli/scaffold/TRAINING.md

@@ -669,6 +669,7 @@ spending another GPU run:
 | Local-only env path in config                                | Config validation says there is no local path mode                                                                                                                                       | Publish first, then use the returned slug in `[environment] id`. `flash train` only runs published env ids, not local paths.                                                                                                                                                                                                                                                                                                    |
 | Config knobs are in the wrong table                          | Validation rejects `[grpo]`, `[sft]`, or unknown `[train]` keys                                                                                                                          | Put `epochs`, `group_size`, `max_completion_tokens`, `temperature`, `max_context_tokens`, LoRA, and other training knobs under `[train]`.                                                                                                                                                                                                                                                                                       |
 | GPU selection is not what you expected                       | Leaving `[gpu] type` unset may select a different fitting class as prices or capacity change                                                                                             | Set `[gpu] type` to an active validated class to hard-pin it, or leave it unset for managed cheapest-fit allocation. `train.hf_repo` remains platform-managed.                                                                                                                                                                                                                                                                  |
+| A pinned run stops after two capacity refusals               | The pinned class had no capacity, and no other class was allowed, so there was nowhere to fail over                                                                                      | Widen the search: drop the `[gpu] type` pin for managed allocation, or drop `[gpu] provider`. Flash stops once the class a retry would land on has refused capacity twice, rather than re-queueing on a class the provider keeps refusing. One refusal always earns a retry, since a momentary shortage is not a sold-out class.                                                                                                |
 | Secrets are not available on the worker                      | Reward code works locally but remote logs show missing API keys or auth failures                                                                                                         | List secret names under `[environment] secrets = [...]`, export those env vars locally before submit, or put them in local `.env` / `.env.local`. Never hard-code secret values in the config.                                                                                                                                                                                                                                  |
 | Scorer dependency is missing on the worker                   | Reward code works locally but every reward is `0.0` remotely; the import your scorer needs is installed in your venv, not the worker's                                                   | List the packages your scorer imports under `[environment] pip = ["pymongo>=4.6"]`. They are installed alongside Flash's own worker requirement. `flash env test` names the failing import locally before you spend a GPU on it. Entries name packages only: pip options and URLs with inline credentials are rejected, because the spec is stored and uploaded in plaintext (put the credential in `[environment] secrets`).   |
 | Wrong model / thinking setting                               | Config validation fails, or chat behavior does not match the run                                                                                                                         | Config validation is authoritative for model and thinking compatibility. Thinking is a run-level choice, and `flash models chat` does not expose an override flag.                                                                                                                                                                                                                                                              |

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/flash/core/catalog.py

@@ -148,6 +148,9 @@ class ModelInfo:
     mamba_block_size: int = 0
     # grouped (in_features, out_features, count) for peft all-linear on the full loaded model.
     lora_target_shapes: tuple[tuple[int, int, int], ...] = ()
+    # fused routed experts stacked on the lora rank axis for target_parameters. zero means no
+    # catalog-backed stacked allowance; ordinary and unknown target parameters carry exactly r.
+    lora_expert_count: int = 0
 
     @property
     def is_moe(self) -> bool:
@@ -174,6 +177,7 @@ class ModelInfo:
             "linear_value_head_dim",
             "linear_conv_kernel_dim",
             "lora_target_shapes",
+            "lora_expert_count",
         ):
             data.pop(key, None)
         serving = data["serving"]
@@ -500,6 +504,7 @@ MODELS: dict[str, ModelInfo] = {
             (4608, 2048, 1),
             (4608, 4608, 1),
         ),
+        lora_expert_count=256,
         vocab_size=248_320,
         algos=ALGORITHMS,
         min_vram_gb=141,
@@ -569,6 +574,14 @@ def serving_lora_rank_cap(model: str | ModelInfo | None) -> int | None:
     return int(info.serving.max_lora_rank)
 
 
+def lora_expert_count(model: str | ModelInfo | None) -> int | None:
+    """Return the exact fused-expert stack size for LoRA target parameters, when cataloged."""
+    info = _model_info_for_serving(model)
+    if info is None or info.lora_expert_count <= 0:
+        return None
+    return int(info.lora_expert_count)
+
+
 def serving_context_cap(model: str | ModelInfo | None) -> int | None:
     """Return the model's served ``max_model_len``, or None without a local serving entry.
 

{freesolo_flash_dev-1.2.12 → freesolo_flash_dev-1.2.14}/flash/core/spec.py

@@ -364,6 +364,12 @@ class TrainSpec:
         save_at_steps = parse_positive_int_tuple(self.save_at_steps, name="train.save_at_steps")
         object.__setattr__(self, "max_steps", max_steps)
         object.__setattr__(self, "save_at_steps", save_at_steps)
+        # a nonpositive interval is not a cadence. the public schema already rejects one, but a
+        # persisted or internally built spec reaches this dataclass directly, so canonicalize it to
+        # the unset sentinel every save_freq site already resolves to its algorithm default. leaving
+        # it signed would make the horizon clamp read it as an interval of one and checkpoint every
+        # single step.
+        object.__setattr__(self, "save_every", parse_max_steps(self.save_every))
         effective_max_steps = max_steps or 0
         if save_at_steps and effective_max_steps <= 0:
             raise ValueError("train.save_at_steps requires positive train.max_steps")

freesolo_flash_dev-1.2.14/flash/engine/profiling/reasoning_render.py

@@ -0,0 +1,299 @@
+"""How much of a transcript's authored reasoning survives the chat template into the loss.
+
+Qwen3.5's template keeps ``<think>`` only on assistant turns after the last user message and strips
+it from earlier history, so a K-turn gold transcript delivers roughly 1/K of its reasoning to the
+loss. The stored messages are never wrong -- only the render is -- so a correct-looking dataset and
+a green ``flash env test`` both survive it.
+
+Survival is answered by IDENTITY: the row is rendered again with each reasoning-authoring turn's
+reasoning marked, and a turn survives exactly when its marker reaches the render. Counting
+``<think>`` tags cannot answer it -- the template opens an EMPTY block on every trailing assistant
+turn, so a transcript stripped of all its reasoning still renders one and scores as a survivor,
+the exact case this exists to catch. A marker also rides inside the reasoning itself, so a
+``<think>`` an answer merely quotes carries none and can never be credited.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_THINK_OPEN = "<think>"
+_THINK_CLOSE = "</think>"
+
+
+def _message_text(content: object) -> str:
+    """The text of a message's ``content`` in either the string or content-block shape."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "".join(
+            block["text"]
+            for block in content
+            if isinstance(block, dict)
+            and block.get("type") == "text"
+            and isinstance(block.get("text"), str)
+        )
+    return ""
+
+
+def _reasoning_body_end(text: str) -> int | None:
+    """Where this turn's reasoning BODY ends, or ``None`` when the turn authored no reasoning.
+
+    The template's own rule: the text after the LAST ``<think>`` preceding the FIRST ``</think>``.
+    An opener-less ``reasoned</think>answer`` counts, being the shape a completion sampled against a
+    prompt-supplied opening tag carries.
+
+    Emptiness is judged on the body: the template stamps an empty ``<think>\\n\\n</think>`` onto
+    qualifying trailing turns, and counting that as authored puts a turn in the denominator that
+    never had reasoning to lose.
+
+    The end excludes trailing whitespace because the template renders reasoning through ``|trim``. A
+    marker placed after that whitespace shields it from the trim, so the marked render keeps bytes
+    the real one drops and tokenizes one token longer -- a cap at the block's real end then reports
+    a block that fits as cut.
+    """
+    close = text.find(_THINK_CLOSE)
+    if close < 0:
+        return None
+    open_at = text.rfind(_THINK_OPEN, 0, close)
+    body = 0 if open_at < 0 else open_at + len(_THINK_OPEN)
+    return len(text[:close].rstrip()) if text[body:close].strip() else None
+
+
+def reasoned_assistant_turns(messages: list[dict[str, Any]]) -> int:
+    """Assistant turns that author reasoning, counted from the SOURCE messages.
+
+    Every accepted shape counts -- inline span, content blocks, ``reasoning_content``, opener-less --
+    because a shape missed here reads as "authored no reasoning" and silences the warning for a row
+    losing all of it.
+
+    A ``reasoning_content`` STRING is authoritative even when EMPTY: the template renders that field
+    and leaves ``content`` whole, so an empty field means the turn authored nothing however the
+    answer is written, and falling back to inline detection would read a ``<think>`` the ANSWER
+    quotes as reasoning. Absent and ``None`` differ -- both parse the inline span.
+    """
+    turns = 0
+    for message in messages:
+        if message.get("role") != "assistant":
+            continue
+        reasoning = message.get("reasoning_content")
+        if isinstance(reasoning, str):
+            turns += 1 if reasoning.strip() else 0
+        elif _reasoning_body_end(_message_text(message.get("content"))) is not None:
+            turns += 1
+    return turns
+
+
+def reasoning_marker_prefix(text: str) -> str:
+    """A marker stem guaranteed absent from ``text``, so a marker cannot match user content.
+
+    Extended rather than assumed unique: a dataset containing the stem would otherwise let its own
+    text answer "did this turn's reasoning survive?".
+
+    Doubling then bisecting, not growing one character at a time: text holding the stem followed by
+    N filler characters keeps every one-character extension a substring, so each of N scans walks
+    the whole row (1.4s on a 50k row, before tokenization).
+    """
+    stem = "flashreasoningmark"
+    if stem not in text:
+        return stem
+    low, high = 0, 1
+    while stem + "x" * high in text:
+        low, high = high, high * 2
+    while low + 1 < high:
+        mid = (low + high) // 2
+        low, high = (mid, high) if stem + "x" * mid in text else (low, mid)
+    return stem + "x" * high
+
+
+def _turn_marker(prefix: str, index: int) -> str:
+    """The marker naming ONE turn's reasoning.
+
+    The trailing ``e`` terminates the index: without it ``{prefix}1`` is a substring of
+    ``{prefix}10``, so a dropped turn 1 reads as surviving whenever turn 10 does.
+    """
+    return f"{prefix}{index}e"
+
+
+def _marks_reasoning(message: dict) -> bool:
+    """Whether this turn gets a marker stamped into it.
+
+    One predicate for both stamping and listing: a turn listed but not stamped reads as a template
+    drop, and a turn stamped but not listed cannot be checked at all.
+    """
+    return message.get("role") == "assistant" and bool(reasoned_assistant_turns([message]))
+
+
+def reasoning_markers(messages: list[dict], prefix: str) -> list[str]:
+    """The marker for each reasoning-authoring turn, in order.
+
+    Separate markers because survival is asked per turn: searching for the shared prefix answers
+    only "did ANY reasoning survive", so one surviving turn would cover a stripped neighbour.
+    """
+    return [
+        _turn_marker(prefix, index)
+        for index, message in enumerate(messages)
+        if _marks_reasoning(message)
+    ]
+
+
+def _marked_inline_reasoning(content: object, marker: str) -> object:
+    """``content`` with ``marker`` stamped at the end of the reasoning the template will keep."""
+    if isinstance(content, str):
+        at = _reasoning_body_end(content)
+        return content if at is None else content[:at] + marker + content[at:]
+    if not isinstance(content, list):
+        return content
+    # the template concatenates the text blocks before splitting, so the offset is resolved on the
+    # joined text and then mapped back into whichever block contains it.
+    texts = [
+        block["text"]
+        if isinstance(block, dict)
+        and block.get("type") == "text"
+        and isinstance(block.get("text"), str)
+        else None
+        for block in content
+    ]
+    at = _reasoning_body_end("".join(text or "" for text in texts))
+    if at is None:
+        return content
+    marked: list = []
+    consumed = 0
+    placed = False
+    for block, text in zip(content, texts, strict=True):
+        if text is None:
+            marked.append(block)
+            continue
+        local = at - consumed
+        consumed += len(text)
+        # an offset on a block boundary matches the end of one block and the start of the next, so
+        # the guard keeps it stamped exactly once.
+        if placed or not 0 <= local <= len(text):
+            marked.append(block)
+            continue
+        placed = True
+        marked.append({**block, "text": text[:local] + marker + text[local:]})
+    return marked
+
+
+def with_marked_reasoning(messages: list[dict], prefix: str) -> list[dict]:
+    """The same messages with each reasoning-authoring assistant turn's reasoning marked.
+
+    Only reasoning TEXT changes, so the template's ``last_query_index`` rule sees identical roles in
+    identical positions and keeps exactly the blocks it would have anyway.
+
+    Both shapes mark the ``|trim``-ed reasoning; marking after trailing whitespace would shield it
+    from the template's trim (see ``_reasoning_body_end``).
+    """
+    marked: list[dict] = []
+    for index, message in enumerate(messages):
+        copied = dict(message)
+        if _marks_reasoning(message):
+            marker = _turn_marker(prefix, index)
+            reasoning = copied.get("reasoning_content")
+            if isinstance(reasoning, str) and reasoning.strip():
+                # the template reads this field in preference to an inline span, so it is the
+                # reasoning and the marker belongs in it
+                copied["reasoning_content"] = reasoning.rstrip() + marker
+            else:
+                copied["content"] = _marked_inline_reasoning(copied.get("content"), marker)
+        marked.append(copied)
+    return marked
+
+
+def strip_reasoning_markers(text: str, prefix: str) -> str:
+    """``text`` with every marker removed, so a marked render can be measured against the cap."""
+    return re.sub(rf"{re.escape(prefix)}\d+e", "", text)
+
+
+def marked_reasoning_end(marked_text: str, marker: str) -> int | None:
+    """Where this turn's rendered reasoning ENDS in the marked render, or ``None`` if it was dropped.
+
+    ``None`` IS the survival answer: a marker rides only inside text the template kept as this
+    turn's reasoning, so its absence is exactly a stripped turn.
+
+    The offset runs through the closing tag -- so the caller asks whether the WHOLE block fit -- and
+    stops there rather than at the blank line before the answer, which costs a real token and would
+    call a fully retained block truncated.
+    """
+    at = marked_text.find(marker)
+    if at < 0:
+        return None
+    close = marked_text.find(_THINK_CLOSE, at)
+    return at + len(marker) if close < 0 else close + len(_THINK_CLOSE)
+
+
+def horizon_row_count(row_count: int, *, examples_per_update: int, updates: int) -> int:
+    """How many retained rows an update horizon reaches, in retained order.
+
+    Updates wrap at the end of an epoch, so a horizon past one full pass saturates at ``row_count``
+    rather than counting a row twice. Shared with the CLI so the denominator matches: a bounded
+    count over a whole-dataset denominator would understate the survival rate.
+    """
+    per_update = max(int(examples_per_update), 1)
+    return min(int(row_count), max(int(updates) * per_update, 0))
+
+
+def reasoning_warning_rows(profile: object) -> int:
+    """The row denominator the reasoning counts were totalled over, from a profile OBJECT or dict.
+
+    Both shapes render the same line: the worker holds the profile, the CLI only sees the dict that
+    travelled on the quote. It is serialized rather than re-derived because a horizon-bounded count
+    is indistinguishable from a whole-dataset one by inspection -- both carry ``examples_per_update``
+    and ``authoritative_steps`` -- so deriving it would pair a binding horizon with unbounded counts.
+    """
+
+    def _int(key: str) -> int | None:
+        value = profile.get(key) if isinstance(profile, dict) else getattr(profile, key, None)
+        return None if isinstance(value, bool) or not isinstance(value, int) else value
+
+    rows = _int("reasoning_rows")
+    if rows is not None:
+        return rows
+    retained = _int("retained_examples")
+    return 0 if retained is None else retained
+
+
+def rendered_reasoning_loss_warning(
+    *,
+    authored_turns: int,
+    rendered_spans: int,
+    rows: int,
+    truncated_spans: int = 0,
+) -> str | None:
+    """One user-facing line when authored reasoning does not reach the loss.
+
+    Reasoning is lost two ways with OPPOSITE remedies -- the template strips earlier history, or
+    ``max_context_tokens`` cuts a block the template KEPT off the end of the row -- so the causes are
+    counted separately and each names its own fix. Silent when nothing was authored (the thinking-
+    mode check owns that) or when everything survived; any drop is reported, since the count is
+    exact rather than sampled and any loss is real lost supervision.
+    """
+    if authored_turns <= 0:
+        return None
+    stripped = authored_turns - rendered_spans
+    if stripped <= 0 and truncated_spans <= 0:
+        return None
+    reaching = rendered_spans - truncated_spans
+    causes = []
+    if stripped > 0:
+        causes.append(
+            f"the chat template dropped {stripped} of {authored_turns} authored reasoning blocks "
+            "-- it keeps <think> only on assistant turns after the last user message and strips it "
+            "from earlier history, so a multi-turn transcript trains on a fraction of its reasoning "
+            "and on a tag layout inference never produces. split each K-turn transcript into K "
+            "single-turn rows, so every turn's reasoning sits in the final assistant target where "
+            "the template keeps it"
+        )
+    if truncated_spans > 0:
+        causes.append(
+            f"max_context_tokens cut {truncated_spans} rendered reasoning "
+            f"{'block' if truncated_spans == 1 else 'blocks'} off the end of the row -- the "
+            "template kept these, so raise max_context_tokens or shorten the rows rather than "
+            "restructuring the transcript"
+        )
+    return (
+        f"{'; '.join(causes)}. across {rows} SFT rows, {reaching} of {authored_turns} authored "
+        f"reasoning blocks reach the loss ({reaching / authored_turns:.0%})."
+    )