timebase

Timebase

Use this skill when changing core/timebase, tempo conversion, or the transport quantizer's beat/frame arithmetic.

Contracts

• kTicksPerQuarter is 705,600. Musical positions are stored and accumulated as integer TickPosition; samples use integer SamplePosition. Tick-position, duration, and MonotonicBeat arithmetic saturates at the signed 64-bit endpoints; it must not invoke signed-overflow UB.
• TempoMap and MeterMap are editable document values built through nonthrowing factories. Their first point is tick zero and points are strictly ordered. Meter changes must compile on exact preceding bar boundaries.
• CompiledTempoMap is immutable and sample-rate-specific. Construct it only through CompiledTempoMap::compile() and handle TempoMapError; public throwing construction is forbidden. Its first tempo point is tick zero, points are strictly ordered, and BPM is finite in [1, 1000].
• Tempo ramps are BPM-linear in tick position. Integrate them analytically; do not approximate ramps block-by-block or accumulate floating-point deltas.
• Every segment begins at an integer sample anchor. samples_to_ticks() returns the first canonical tick mapping to that sample when one exists. Exact sample -> tick -> sample requires a tick grid at least as dense as samples. On a sparser grid, use resolve_sample() and inspect represented_sample, absolute_error_samples, and exact; the nearest tick is returned.
• Arbitrary tick -> sample -> tick cannot be identity because many ticks share an integer sample. Test monotonicity and canonical-sample preservation instead.
• Render-time phase mapping may use fractional_ticks_to_samples() and its analytic inverse fractional_samples_to_ticks(). Both retain the compiled integer segment anchors but avoid rounding their input/output domains; keep ramp round-trip coverage at fractional interior positions.
• TempoCursor is the allocation-free playback path. Monotonic sample advances consume segment transitions once (amortized O(1)); seeks and loop wraps reset it explicitly. Differential tests must match cold-map canonical results.
• CompiledMeterMap uses zero-based bars and exact integer bar/tick conversion. Tempo changes never affect bar conversion and meter changes never affect tick/sample conversion. Conversion is total across INT64_MIN..INT64_MAX: exact results are returned when representable and out-of-range results saturate without signed-overflow UB.
• Keep TransportQuantizer's public behavior stable. Generic beat/frame/grid arithmetic belongs in <pulp/timebase/quantize.hpp> and the format wrapper delegates to it.
• BeatDivision is an append-only persisted ordinal vocabulary. Append new values immediately before Count, assign every ordinal explicitly, and keep beat_fraction() reduced. division_ticks() must fail if a future fraction is not exactly representable on the 705,600-tick quarter-note lattice.
• BeatDivision owns the canonical fraction table. The older signal::units::Division vocabulary is a compatibility adapter: preserve its lowercase public spellings and persisted ordinals, map it to BeatDivision, and derive its beat values from beat_fraction_or(). Append both enums in the same change and keep exhaustive compile-time and runtime parity coverage in test_signal_units.cpp; never add a second division formula in signal.
• Grid projection consumes explicit document and monotonic anchors in GridProjectionRange; it does not infer transport state from an unwrapped sample clock. This matches playback::MasterTransport: pre-loop material uses its ordinary document interval, loop passes repeat the loop's document sample interval and tempo image, and seeks change the document anchor without resetting MonotonicBeat. Ranges and callbacks are half-open, so splitting a callback cannot duplicate a boundary. Keep capacity and signed-domain failure explicit and leave caller output untouched on insufficient capacity. Bound candidate opportunities before entering either timeline- or bar-grid loops; counting only emitted points leaves incoherent remote-sample ranges able to burn unbounded callback time.
• For document-clock projection, enumerate the rounded end tick as a candidate and let [timeline_sample_start, timeline_sample_start + frame_count) decide ownership. Sparse maps can give a valid one-frame transport range equal rounded tick endpoints (at 1 BPM/48 kHz, tick 0 maps to sample 0 and tick 1 to sample 4). Returning early drops tick 0 from a 1 + 3 split even though a four-frame block emits it; excluding the end candidate merely moves the bug. The next range's sample filter prevents duplication.
• A host-beat-mapped transport range carries fractional host tick endpoints and maps an exact document tick proportionally into output frames. Preserve that metadata in the dependency-lower grid range and match playback's half-open, floor-to-frame rule. Range-local proportions are not callback invariant when a loop boundary's output count was rounded. Retain one HostGridAnchor (normalized source tick, absolute frame, ticks per frame) across the continuous session interval, give each range its absolute first frame and loop-pass document-to-source offset, and floor on that stable clock before clamping to the owning half-open range. Initialize the source tick from the first resolved range in a normalization epoch, not from an absolute host beat that the transport has already wrapped into document coordinates; reset the anchor on an epoch or slope discontinuity. Never feed such a range through CompiledTempoMap::ticks_to_samples(): session tempo is independent of the document tempo, including on split loop ranges.
• project_ratchet_interval() treats the hit count as including the onset and excludes the later clock boundary. It distributes integer-tick remainders from the original interval coordinates on every projection; do not advance a floating-point phase or carry remainder state between callbacks. Half-open windows must concatenate to the same schedule as one whole-window call. Reject a hit count greater than the integer-tick span rather than emitting duplicate positions.
• LoopRegion (<pulp/timebase/loop_region.hpp>) is two document positions plus whether they are in force, and it lives here rather than beside a consumer because that is the whole of it. playback::LoopRegion is an alias of it and timeline_editor::UiPlayhead::loop names it directly, so the rung that runs the transport and the rung that draws the ruler cannot drift apart. enabled gates wrapping, not existence: a disabled loop keeps its bounds so a view goes on drawing the region and re-enabling returns the user to it.
• A value type both the transport rung and the editor rung need belongs here, and this module is the only place it can go. playback's floor and timeline_editor's floor exclude each other; timebase is in both, so it is their entire intersection apart from platform/runtime. Reaching for a shared home anywhere else means widening a floor row, which is the thing the ladder exists to prevent. Before adding one, confirm the intersection still holds in MODULE_FLOORS (timeline_engine_dependency_floor_check.py) rather than assuming it.