member_spans: where each episode member is heard on its mix

[thorwhalen]

What

braidio.transforms.member_spans(project, episode): each member of an episode-render/v1, in play order, with where it is heard on the mix (MemberSpan(member_id, position, start_s, end_s, concurrent)).

• Pairing: ordered_member_ids[i] ↔ the timeline span whose index is i, the rule episode_script + captions.cues_for and the picture track already rely on.
• The sequential lane comes back exclusive: the weave tucks each part ~0.12 s (crossfade) or 0.5 s (clip edge) under its predecessor, so each placement starts where the previous one finished (the cues_for clamp).
• A member laid under what follows, or shorter than its tuck, keeps its true span and is marked concurrent.
• Bounded by the mix's duration_s. Unknown placement (None) when there is no span, the timeline is malformed or cannot be rebuilt, or its indices are not member positions; never rebuilt from durations.
• BeatSpan.placement (additive): build_timeline records layout_placed's sequential/under, to_dict writes it only when recorded (older breakdowns round-trip to the same bytes), from_dict accepts only those two values. Older breakdowns are read off the layout's own signature, property-tested against layout_placed (exact agreement on 3000 random realistic layouts).
• Importer: refuses a manifest timeline whose indices are not distinct member positions (a shifted index would hand every member its neighbour's interval).

First customer: reeleehq/reelee#546 (a spend-free read of commentary takes with text and place on the mix, for reelee-web#356). Follow-up filed: #98.

Checked

• tests/test_importing.py: negative control for the clamp, under/tucked/tie cases, bounds, unpairable and malformed timelines, the importer refusal, the property test. 93 pass; timeline, video-transforms and doctests pass.
• Read-only copies of two real imported productions: 14 and 57 takes, all placed, ordered, inside the mix.
• Local full suite: 640 passed; only py2mcp-dependent files fail locally (module absent from the local venv).

Adversarial review

Three rounds by a fresh Opus reviewer.

• Round 1 (fix first): the clamp squeezed under-laid members to zero; spans could pass the mix end; a non-positional timeline paired members with neighbours' spans; malformed timelines raised. All fixed.
• Round 2 (fix first): inferring under from start order missed ties (cold-open under clip, zero crossfade) and flagged short members. Fixed by recording placement and reading older timelines off layout_placed's signature.
• Round 3 (fix first): a 1 ms rounding tolerance missed ~3.5% of real-valued layouts; a null duration raised; arbitrary placement values were trusted. Fixed (2.5 ms tolerance, property test, validated values, tucked members advance the lane). Confirmed placement in to_dict touches no plan identity, cache key or fingerprint. Remaining by design: older timelines made of parts shorter than the clip edge are ambiguous without a recorded placement (documented).

🤖 Generated with Claude Code