[faresobeid]

Adds by-handle payload segments to v1 traces. An inference server can write per-token side arrays (router-replay ids, sampling masks) to a shared file and return payload segments instead of inline routed_experts / sampling_mask; verifiers then moves only the handles.

• PayloadSegment(field, file, offset, pos, rows, dtype, shape): rows fixed-width rows of one per-token array at byte offset of file; pos is the first row's token position. clip() cuts a segment to a position range and moves offset.
• TurnTokens.payload: the request's segments (request-absolute positions), filled by the train client from the generate result's payload.
• Trace.payload: list[NodeSegment], append-only: each turn's commit clips the request segments to the nodes created this turn (node-local positions). The prefix's final token goes to the prefix's last node when that node was sampled (the previous turn never forwarded it). Rows of other re-forwarded prefix positions are dropped, as on the inline path. No row is ever rewritten.
• Branch.payload: the trace's segments on that path, rebased to branch positions, in append order.
• payload streams as an append-only delta list field and is excluded from to_record (handles are short-lived).

Inline fields are unchanged; a turn carries one form or the other, depending on the server.

Validation

• tests/unit/test_graph.py::test_payload_segments_attributed_per_node_and_rebased_per_branch: bridged turn (prior sampled node gets request row path_len-1), fork off a non-sampled prefix node (re-forwarded rows dropped), Branch.payload rebasing on both branches.
• Merged with current main: uv run pytest tests/unit 232 passed, 19 skipped (Docker/Prime/harbor); ruff check, ruff format --check, ty check verifiers clean.

Dependencies / before merge

• feat(client): pass through sampling-mask logprobs and by-handle payload segments renderers#170 passes payload through renderers.client.generate(); land together.
• feat(pd): stitch by-handle routed_experts payload segments router#60 stitches segments under disaggregated P/D.
• The prime-rl reader (prime-rl#3902) was closed unmerged; prime-rl#4196 keeps the arrays on the env servers instead. Confirm a consumer still exists before merging.

---

Note

Medium Risk
Touches turn commit attribution and branch construction for training data; payload handles are wire-only and omitted from persisted traces, so consumers must read shared files before they expire.

Overview
Adds by-handle per-token side arrays to v1 traces so inference can return file offsets instead of inlining large tensors (e.g. routed_experts, sampling_mask).

Introduces PayloadSegment / NodeSegment with clipping and rebasing. The train client maps generate payload into transient TurnTokens.payload. Turn commit appends node-attributed segments on Trace.payload (including the bridged “previous turn final token” row without rewriting earlier rows, and dropping re-forwarded prefix rows). Branch.payload exposes branch-aligned handles for training.

payload streams as an append-only delta field but is excluded from disk records (EXCLUDE_FIELDS). Inline routed_experts / sampling_mask paths are unchanged.

A new graph unit test covers bridged attribution, prefix reuse, and per-branch rebasing.

^{Reviewed by Cursor Bugbot for commit bacf577. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add by-handle payload segments to traces

Introduces a PayloadSegment type that describes a payload range (field, byte offset, row position/count, dtype, shape) with a clip operation for shifting ranges. Turn commits now attribute payload ranges to graph nodes and store them as NodeSegment entries on Trace.payload in graph.py.

• TurnTokens gains a transient payload field populated by response_from_generate in train.py and excluded from serialization
• Each Branch built in trace.py keeps only payload entries on its path, rebased to branch-global token positions
• Worker deltas now append newly sent payload entries via LIST_FIELDS in delta.py
• Behavioral Change: trace record serialization excludes the payload field entirely (added to EXCLUDE_FIELDS in trace.py); PayloadSegment and NodeSegment are newly exported from verifiers.v1

^{Macroscope summarized e88c744.}

[macroscopeapp]

Approvability

Verdict: Needs Human Approval

Macroscope's review found this PR requires human approval — Adds a new by-handle payload contract spanning response parsing, node/branch attribution, and trace delta streaming, with handles pointing to short-lived shared files. Although legacy inline payload paths remain unchanged and focused tests are included, the new runtime and cross-component data path is broader than a small isolated additive change.

No code changes detected at e88c744. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}