feat(timeline): sample-accurate clip-launch foundation

[shipyard-local]

Header-only, real-time clip-launch engine and its authored launch model — the Phase-3 clip-launch foundation. Deliberately not wired into Project identity/serialization yet (that is the explicit follow-up slice).

What lands

• core/timeline/include/pulp/timeline/clip_launch.hpp — LaunchQuantize (monotonic-domain grid + phase), Slot, and Scene value types describing what is launchable and how it quantizes. launch_immediate / launch_every_quarters / launch_every_bars helpers.
• core/playback/include/pulp/playback/clip_launch.hpp — the RT engine:
  • next_launch_boundary resolves the next monotonic boundary (ceil onto the {phase + k*grid} set), saturating over a 128-bit intermediate.
  • resolve_launch_sample maps a target through the transport's half-open [monotonic_start, monotonic_end) ranges to a block-relative sample offset — the boundary on a loop wrap belongs to the post-wrap range, keeping resolution sample-accurate across the wrap. Includes a block-end rounding guard so an offset never equals frame_count.
  • LaunchHandle drives the Stopped → Armed → Playing → Stopping → Stopped state machine. Allocation-free, audio-callback safe.

Quantizing on the transport's monotonic clock (never wraps) is what keeps "launch at the next bar" well-defined when a rendered block straddles a loop wrap.

Tests (test/test_playback_clip_launch.cpp, 13 cases / 588 assertions)

• Boundary math (on/just-past/just-before a grid point; phase offset; immediate).
• resolve_launch_sample: mid-block exact offset, beyond-block nullopt, block-end deferral sweep, already-behind fire-now.
• Sample-accuracy across a loop wrap (DoD): synthetic split snapshot — exactly-at-wrap (→ post-wrap range, half-open), strictly-inside-wrapped-base (→ 800 proves the wrapped base was used), and a one-sample-past-wrap off-by-one check (→ 501).
• LaunchHandle end-to-end across a real loop wrap: a frame-granular run is ground truth (fire @ 500), and 1024/333/500/250-frame blocks (including a split-block boundary landing exactly on the wrap) all resolve to the identical absolute sample.
• Immediate launch, armed-while-stopped, quantized stop, and an RT no-alloc probe on process().

Scope

Header-only foundation only. Follow-ups (not in this PR): Project/serialize integration, scene-launch arbitration, follow-actions, examples. Skill guidance for playback/timeline follows the integration slice (skip trailers on the commit record why).

🤖 Generated with Claude Code

---

🔎 Provenance

Agent	claude
Machine	m3
Tab	Timeline v3
Directory	/Volumes/Workshop/Code/pulp-cliplaunch
Session	c66f4a64-25ea-42e5-b184-d48611a066a2

Resume

claude --resume c66f4a64-25ea-42e5-b184-d48611a066a2

Jump to this tab

cmux surface focus C0B3DA54-39AF-4DAA-8089-AA08DAB71968

Relaunch (any agent)

cmux surface resume get --surface C0B3DA54-39AF-4DAA-8089-AA08DAB71968

Restore URL — https://claude.ai/code/session_01TVQHcnbg3t6TvXsdv6gXhS

_{stamped 2026-07-22 07:57 UTC}