feat(v1): training run metadata on episode

[mikasenghaas]

Summary

Enough on the episode that a consumer stops keeping its own copy of where it came from and what it
is to the run. Everything is optional or defaulted, so existing records and readers are unaffected.

class EnvInfo:    id: str = ""             # what the env IS      — reverse-text-v1
                  name: str | None = None  # what a run CALLS it  — reverse-text

class GroupInfo:  id, size                 # the episodes planned together from one task

class Episode:    env, group, run

A group is what a consumer compares against each other — pass@k over it, a GRPO baseline within it.
utils/platform.py reconstructs that ad hoc today. The id is per group, not per task: planning
the same task again is a new group, so two rounds never merge into one comparison.

The run, and what an episode is to it

A training run's evals are its own — same id, same policy as the rollouts they are measured against
— so one run record, with the per-episode part nested under it:

class Metadata:        policy: PolicySpan | None       # the versions generation spanned
class TrainMetadata:   step: int | None                # the batch window it landed in
class EvalMetadata:    step: int                       # the epoch it was dispatched for

class TrainRunInfo:    id, metadata: TrainMetadata | EvalMetadata
class EvalRunInfo:     id                              # a standalone eval

Splitting the metadata is what lets each say something true. step means two different things and
only the eval's is knowable upfront, so under a single kind flag it had to be optional for both.
And off_policy_steps differs the same way:

PolicySpan.drift              -> end - start                  # what moved mid-generation
TrainMetadata.off_policy_steps -> (step - 1) - policy.start   # behind what is training
EvalMetadata.off_policy_steps  -> policy.drift                # what moved under it

Nothing trains on an eval, so there is no policy for it to be behind; what makes it off-policy is
the policy moving under it. Its step cannot say that — fixed at dispatch, it reports an eval that
outlived three updates as on-policy, and one that measured a single version cleanly as one behind.

Both readings derive from the span, so nothing stored can contradict it. policy is None when the
episode did not come from the live policy at all (a frozen sampler), so staleness reads None
rather than a 0 that looks fresh.

The run types also move from trace.py to episode.py — they were written when the run was a field
on Trace, and #2244 moved the field without them.

Verification

• uv run pytest tests — full suite passes; round-trips through
  WireEpisode.model_validate(episode.model_dump(mode="json")).

• The eval cases that motivated the split:

  	before	now
  dispatched at step 6 under v5, ran to v8	0	3
  measured one version cleanly	1	0

• Live in prime-rl (feat(orchestrator)!: align multi-agent types prime-rl#3183), 6-step runs with eval throughout.

Consumer

prime-rl carried all of this on Episode and Trace subclasses and now extends neither. Its two
staleness mechanisms — an in-flight counter, then a recompute at ship — collapse into the derived
property.

Not included

An earlier revision had Env.slots mint a group so -r k was a group of k. Dropped: nothing here
reads a group, and it broke resume — slots() sized the group by what it was asked to plan, but a
resume asks only for what it still owes, so one -r k split in two. Worth doing when something here
consumes a group, with the resume threading it needs.

🤖 Generated with Claude Code