model.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/runtime/result.hpp>
#include <pulp/timebase/compiled_meter_map.hpp>
#include <pulp/timebase/compiled_tempo_map.hpp>
#include <pulp/timebase/quantize.hpp>
#include <pulp/timebase/rational_time.hpp>
#include <pulp/timebase/tick.hpp>
#include <pulp/timeline/assets.hpp>
#include <pulp/timeline/automation_lane.hpp>
#include <pulp/timeline/clip.hpp>
#include <pulp/timeline/clip_launch.hpp>
#include <pulp/timeline/device_placement.hpp>
#include <pulp/timeline/item_id.hpp>
#include <pulp/timeline/modulation.hpp>
#include <pulp/timeline/note_modifier.hpp>
#include <pulp/timeline/recording.hpp>
#include <pulp/timeline/tuning.hpp>
 
#include <compare>
#include <cstddef>
#include <cstdint>
#include <iterator>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
 
namespace pulp::timeline {

 
namespace detail {
class ProjectStateAccess;
class LauncherStore;
struct SequenceEditAccess;
} // namespace detail
struct ClipIndexNode;

struct TrackIndexStats {
    std::uint64_t live_nodes = 0;
    std::uint64_t nodes_created = 0;
};

struct LauncherIndexStats {
    std::uint64_t live_nodes = 0;
    std::uint64_t nodes_created = 0;
};

struct TrackInput {
    ItemId id;
    std::string name;
    std::vector<Clip> clips;
    std::vector<DevicePlacement> device_chain;
    std::vector<AutomationLane> automation_lanes;
    std::vector<Modulator> modulators;
    std::vector<MacroControl> macros;
    std::vector<ModulationRoute> modulation_routes;
    std::vector<TakeLane> take_lanes;
    bool record_armed = false;
    // Zero selects the arrangement rather than a take playlist/comp lane.
    ItemId active_take_lane_id;
    std::optional<TrackFreeze> freeze;
    TrackMixer mixer;
    // Absence means the track plays in whatever tuning the project states.
    std::optional<TuningReference> tuning;
};

class Track {
  public:
    class ClipView {
      public:
        class Iterator {
          public:
            using value_type = Clip;
            using difference_type = std::ptrdiff_t;
            using iterator_category = std::forward_iterator_tag;

            const Clip& operator*() const noexcept;
            const Clip* operator->() const noexcept;
            Iterator& operator++() noexcept;
            bool operator==(const Iterator&) const noexcept = default;
 
          private:
            friend class ClipView;
            Iterator(std::shared_ptr<const ClipIndexNode> root, std::size_t index) noexcept
                : root_(std::move(root)), index_(index) {}
            std::shared_ptr<const ClipIndexNode> root_;
            std::size_t index_ = 0;
        };

        std::size_t size() const noexcept {
            return size_;
        }

        bool empty() const noexcept {
            return size_ == 0;
        }

        const Clip& operator[](std::size_t index) const noexcept;
        Iterator begin() const noexcept {
            return Iterator(root_, 0);
        }

        Iterator end() const noexcept {
            return Iterator(root_, size_);
        }
 
      private:
        friend class Track;
        ClipView(std::shared_ptr<const ClipIndexNode> root, std::size_t size) noexcept
            : root_(std::move(root)), size_(size) {}
        std::shared_ptr<const ClipIndexNode> root_;
        std::size_t size_ = 0;
    };

    static runtime::Result<Track, ModelError> create(ItemId id, std::string name,
                                                     std::vector<Clip> clips);
    static runtime::Result<Track, ModelError> create(TrackInput input);
    runtime::Result<Track, ModelError> insert_clip(Clip clip) const;
    runtime::Result<Track, ModelError> erase_clip(ItemId id) const;
    runtime::Result<Track, ModelError> replace_clip(Clip replacement) const;
    runtime::Result<Track, ModelError> insert_automation_lane(AutomationLane lane) const;
    runtime::Result<Track, ModelError> erase_automation_lane(ItemId id) const;
    runtime::Result<Track, ModelError> insert_modulator(Modulator modulator) const;
    runtime::Result<Track, ModelError> erase_modulator(ItemId id) const;
    runtime::Result<Track, ModelError> replace_modulator(Modulator replacement) const;
    runtime::Result<Track, ModelError> insert_macro(MacroControl macro) const;
    runtime::Result<Track, ModelError> erase_macro(ItemId id) const;
    runtime::Result<Track, ModelError> replace_macro(MacroControl replacement) const;
    runtime::Result<Track, ModelError> insert_modulation_route(ModulationRoute route) const;
    runtime::Result<Track, ModelError> erase_modulation_route(ItemId id) const;
    runtime::Result<Track, ModelError> replace_modulation_route(ModulationRoute replacement) const;
    runtime::Result<Track, ModelError>
    insert_device(DevicePlacement placement,
                  std::optional<ItemId> before_device_id = std::nullopt) const;
    runtime::Result<Track, ModelError> erase_device(ItemId id) const;
    runtime::Result<Track, ModelError>
    move_device(ItemId id, std::optional<ItemId> before_device_id) const;
    runtime::Result<Track, ModelError> replace_device(DevicePlacement replacement) const;
    runtime::Result<Track, ModelError> insert_take_lane(TakeLane lane) const;
    runtime::Result<Track, ModelError> erase_take_lane(ItemId id) const;
    runtime::Result<Track, ModelError> insert_take(ItemId lane_id, Take take) const;
    runtime::Result<Track, ModelError> erase_take(ItemId lane_id, ItemId take_id) const;
    runtime::Result<Track, ModelError> with_take_comp(ItemId lane_id,
                                                      std::vector<TakeCompSegment> comp) const;
    Track with_record_armed(bool armed) const;
    runtime::Result<Track, ModelError> with_active_take_lane(ItemId lane_id) const;
    runtime::Result<Track, ModelError> with_freeze(std::optional<TrackFreeze> freeze) const;
    runtime::Result<Track, ModelError> with_mixer(TrackMixer mixer) const;
    runtime::Result<Track, ModelError> with_tuning(std::optional<TuningReference> tuning) const;
    Track with_name(std::string name) const;

    ItemId id() const noexcept;
    const std::string& name() const noexcept;
    ClipView clips() const noexcept;
    const Clip* find_clip(ItemId id) const noexcept;
    std::span<const DevicePlacement> device_chain() const noexcept;
    const DevicePlacement* find_device_placement(ItemId id) const noexcept;
    std::span<const AutomationLane> automation_lanes() const noexcept;
    const AutomationLane* find_automation_lane(ItemId id) const noexcept;
    std::span<const Modulator> modulators() const noexcept;
    const Modulator* find_modulator(ItemId id) const noexcept;
    std::span<const MacroControl> macros() const noexcept;
    const MacroControl* find_macro(ItemId id) const noexcept;
    std::span<const ModulationRoute> modulation_routes() const noexcept;
    const ModulationRoute* find_modulation_route(ItemId id) const noexcept;
    std::vector<ModulationRoute> routes_from_source(ItemId source_id) const;
    std::span<const TakeLane> take_lanes() const noexcept;
    const TakeLane* find_take_lane(ItemId id) const noexcept;
    bool record_armed() const noexcept;
    ItemId active_take_lane_id() const noexcept;
    const std::optional<TrackFreeze>& freeze() const noexcept;
    const TrackMixer& mixer() const noexcept;
    const std::optional<TuningReference>& tuning() const noexcept;
    std::size_t shared_index_nodes_with(const Track& other) const;
    bool shares_clip_membership_with(const Track& other) const noexcept;
    bool shares_storage_with(const Track& other) const noexcept;
    static TrackIndexStats index_stats() noexcept;
 
  private:
    friend class Sequence;
    struct Data;
    bool shares_compile_structure_with(const Track& other) const noexcept;
    runtime::Result<Track, ModelError>
    with_device_chain(std::vector<DevicePlacement> device_chain) const;
    runtime::Result<Track, ModelError> with_modulators(std::vector<Modulator> modulators) const;
    runtime::Result<Track, ModelError> with_macros(std::vector<MacroControl> macros) const;
    runtime::Result<Track, ModelError>
    with_modulation_routes(std::vector<ModulationRoute> routes) const;
    explicit Track(std::shared_ptr<const Data> data) : data_(std::move(data)) {}
    std::shared_ptr<const Data> data_;
};

enum class ChordQuality : std::uint8_t {
    Major = 0,
    Minor = 1,
    Diminished = 2,
    Augmented = 3,
    Dominant7 = 4,
    Major7 = 5,
    Minor7 = 6,
    HalfDiminished7 = 7,
    Suspended2 = 8,
    Suspended4 = 9,
};

enum class ScaleMode : std::uint8_t {
    Major = 0,
    NaturalMinor = 1,
    HarmonicMinor = 2,
    MelodicMinor = 3,
    Dorian = 4,
    Phrygian = 5,
    Lydian = 6,
    Mixolydian = 7,
    Locrian = 8,
    Chromatic = 9,
};

enum ChordExtension : std::uint16_t {
    kChordExtensionNinth = 1u << 0,
    kChordExtensionFlatNinth = 1u << 1,
    kChordExtensionSharpNinth = 1u << 2,
    kChordExtensionEleventh = 1u << 3,
    kChordExtensionSharpEleventh = 1u << 4,
    kChordExtensionThirteenth = 1u << 5,
    kChordExtensionFlatThirteenth = 1u << 6,
};

inline constexpr std::uint16_t kChordExtensionMask =
    kChordExtensionNinth | kChordExtensionFlatNinth | kChordExtensionSharpNinth |
    kChordExtensionEleventh | kChordExtensionSharpEleventh | kChordExtensionThirteenth |
    kChordExtensionFlatThirteenth;

enum class ChordVoicing : std::uint8_t {
    Close,
    Open,
    Drop2,
    Drop3,
    Rootless,
    Shell,
};

struct ChordScaleEvent {
    timebase::TickPosition position;
    ChordQuality chord_quality = ChordQuality::Major;
    std::uint8_t chord_root = 0;
    ScaleMode scale_mode = ScaleMode::Major;
    std::uint8_t scale_root = 0;
    // The pitch class that sounds lowest, when it is not the chord root. This
    // is the general form of an inversion: naming the bass covers both a chord
    // tone in the bass and a bass note outside the chord, and a separate
    // inversion number beside it could only ever contradict it.
    std::optional<std::uint8_t> chord_bass;
    // Bitmask over ChordExtension. Zero states the plain quality.
    std::uint16_t chord_extensions = 0;
    std::optional<ChordVoicing> voicing;
 
    constexpr auto operator<=>(const ChordScaleEvent&) const = default;
};

class ChordScaleLane {
  public:
    static runtime::Result<ChordScaleLane, ModelError> create(std::vector<ChordScaleEvent> events);

    std::span<const ChordScaleEvent> events() const noexcept {
        return *events_;
    }

    bool empty() const noexcept {
        return events_->empty();
    }

    const ChordScaleEvent* at(timebase::TickPosition position) const noexcept;
    bool shares_storage_with(const ChordScaleLane& other) const noexcept {
        return events_.get() == other.events_.get();
    }

    bool operator==(const ChordScaleLane& other) const noexcept;
 
  private:
    explicit ChordScaleLane(std::shared_ptr<const std::vector<ChordScaleEvent>> events) noexcept
        : events_(std::move(events)) {}
 
    std::shared_ptr<const std::vector<ChordScaleEvent>> events_;
};

struct DynamicsEvent {
    timebase::TickPosition position;
    float intensity = 0.0f;
    AutomationInterpolation interpolation = AutomationInterpolation::Continuous;
 
    constexpr bool operator==(const DynamicsEvent&) const = default;
};

class DynamicsLane {
  public:
    static runtime::Result<DynamicsLane, ModelError> create(std::vector<DynamicsEvent> events);

    std::span<const DynamicsEvent> events() const noexcept {
        return *events_;
    }

    bool empty() const noexcept {
        return events_->empty();
    }

    const DynamicsEvent* at(timebase::TickPosition position) const noexcept;
    std::optional<float> value_at(timebase::TickPosition position) const noexcept;
    bool shares_storage_with(const DynamicsLane& other) const noexcept {
        return events_.get() == other.events_.get();
    }

    bool operator==(const DynamicsLane& other) const noexcept;
 
  private:
    explicit DynamicsLane(std::shared_ptr<const std::vector<DynamicsEvent>> events) noexcept
        : events_(std::move(events)) {}
 
    std::shared_ptr<const std::vector<DynamicsEvent>> events_;
};

struct SequenceMarker {
    ItemId id;
    std::string name;
    timebase::TickPosition position;
    std::optional<std::uint32_t> color;
};

enum class SectionRole : std::uint8_t {
    Unspecified,
    Intro,
    Verse,
    PreChorus,
    Chorus,
    Bridge,
    Breakdown,
    Drop,
    Solo,
    Interlude,
    Outro,
};

struct SequenceRegion {
    ItemId id;
    std::string name;
    timebase::TickPosition position;
    timebase::TickDuration duration;
    std::optional<std::uint32_t> color;
    SectionRole role = SectionRole::Unspecified;

    auto operator<=>(const SequenceRegion&) const = default;
};

inline constexpr std::int32_t kGrooveUnitScale = 1000;
inline constexpr std::int32_t kMaxGrooveVelocityScale = 4000;
inline constexpr std::size_t kMaxGrooveSteps = 1024;

struct GrooveStep {
    timebase::TickDuration timing_offset{};
    std::int32_t velocity_scale = kGrooveUnitScale;
 
    constexpr auto operator<=>(const GrooveStep&) const = default;
};

struct GrooveTemplateInput {
    std::string name;
    // Zero means the groove states no swing. A swing grid is a subdivision:
    // the pair it warps spans twice this.
    timebase::TickDuration swing_grid{};
    timebase::SwingRatio swing = timebase::kStraightSwing;
    // The width of one entry in `steps`. Zero exactly when there is no table.
    timebase::TickDuration step{};
    std::vector<GrooveStep> steps;
    std::int32_t timing_strength = kGrooveUnitScale;
    std::int32_t velocity_strength = kGrooveUnitScale;
};
 
// A named feel a sequence plays with: a swing setting and a repeating table of
// per-step timing and accent, each scaled by its own strength.
//
// Groove carries velocity as well as timing deliberately. A feel is as much
// accent as it is placement — the same timing with flat velocities does not
// sound like the groove it was sampled from. Timing and accent share one
// canonical owned array. The two are separately
// attenuated so a project can borrow a groove's placement without its accents,
// which is the common editing request.
//
// Swing and the table are two independent displacements of the same authored
// position: the table is indexed by where a note was written, not by where
// swing moved it, so changing the swing setting never re-assigns notes to
// different steps.
//
// The swing half is order-preserving (see timebase::swing_position). The table
// half is not: adjacent steps may lean in opposite directions, and material at
// the end of one step can be pushed past material at the start of the next.
// That is what a groove template is, so offsets are bounded to less than a
// step rather than constrained into monotonicity.
//
// The template is sequence-owned context, not clip content: it is read by other
// items' compile hooks. Reading it across entities is what the compile-context
// subscription contract governs (see compile_context.hpp).
class GrooveTemplate {
  public:
    static runtime::Result<GrooveTemplate, ModelError> create(GrooveTemplateInput input);

    const std::string& name() const noexcept {
        return data_->name;
    }

    timebase::TickDuration swing_grid() const noexcept {
        return data_->swing_grid;
    }

    timebase::SwingRatio swing() const noexcept {
        return data_->swing;
    }

    timebase::TickDuration step() const noexcept {
        return data_->step;
    }

    std::span<const GrooveStep> steps() const noexcept {
        return data_->steps;
    }

    std::int32_t timing_strength() const noexcept {
        return data_->timing_strength;
    }

    std::int32_t velocity_strength() const noexcept {
        return data_->velocity_strength;
    }

    bool states_no_feel() const noexcept;
    bool is_canonical_default() const noexcept;

    timebase::TickPosition apply_timing(timebase::TickPosition position) const noexcept;
    std::int32_t velocity_scale_at(timebase::TickPosition position) const noexcept;

    bool shares_storage_with(const GrooveTemplate& other) const noexcept {
        return data_.get() == other.data_.get();
    }

    bool operator==(const GrooveTemplate& other) const noexcept;
 
  private:
    // The table entry `position` falls in, or null when the groove has no table.
    const GrooveStep* step_at(timebase::TickPosition position) const noexcept;
 
    struct Data {
        std::string name;
        timebase::TickDuration swing_grid;
        timebase::SwingRatio swing;
        timebase::TickDuration step;
        std::vector<GrooveStep> steps;
        std::int32_t timing_strength;
        std::int32_t velocity_strength;
 
        bool operator==(const Data&) const = default;
    };
    explicit GrooveTemplate(std::shared_ptr<const Data> data) noexcept : data_(std::move(data)) {}
 
    std::shared_ptr<const Data> data_;
};

struct SequenceInput {
    ItemId id;
    std::string name;
    std::optional<timebase::TickDuration> musical_duration;
    std::optional<AbsoluteTimelineDuration> absolute_duration;
    std::vector<Track> tracks;
    std::vector<SequenceMarker> markers;
    std::vector<SequenceRegion> regions;
    std::optional<ChordScaleLane> chord_scale_lane;
    std::optional<DynamicsLane> dynamics_lane;
    std::optional<GrooveTemplate> groove;
    // Authored launch order. A scene owns its slots; every non-empty slot
    // references a clip in this sequence.
    std::vector<Scene> scenes;
    // Authored top-to-bottom track order, naming every track in `tracks`
    // exactly once. An empty vector records no authored order, and the
    // sequence adopts the identity order of `tracks` instead.
    std::vector<ItemId> track_order;
};

class Sequence {
  public:
    class SceneView {
      public:
        class Iterator {
          public:
            using value_type = Scene;
            using difference_type = std::ptrdiff_t;
            using pointer = const Scene*;
            using reference = const Scene&;
            using iterator_category = std::forward_iterator_tag;

            const Scene& operator*() const noexcept;
            const Scene* operator->() const noexcept;
            Iterator& operator++() noexcept;
            Iterator operator++(int) noexcept {
                auto copy = *this;
                ++*this;
                return copy;
            }

            bool operator==(const Iterator&) const noexcept = default;
 
          private:
            friend class SceneView;
            Iterator(std::shared_ptr<const detail::LauncherStore> store, ItemId current) noexcept
                : store_(std::move(store)), current_(current) {}
            std::shared_ptr<const detail::LauncherStore> store_;
            ItemId current_;
        };

        std::size_t size() const noexcept;
        bool empty() const noexcept {
            return size() == 0;
        }

        const Scene& operator[](std::size_t index) const noexcept;
        Iterator begin() const noexcept;
        Iterator end() const noexcept;
 
      private:
        friend class Sequence;
        explicit SceneView(std::shared_ptr<const detail::LauncherStore> store) noexcept
            : store_(std::move(store)) {}
        std::shared_ptr<const detail::LauncherStore> store_;
    };

    static runtime::Result<Sequence, ModelError>
    create(ItemId id, std::string name, std::optional<timebase::TickDuration> duration,
           std::vector<Track> tracks);
    static runtime::Result<Sequence, ModelError>
    create(ItemId id, std::string name, std::optional<timebase::TickDuration> musical_duration,
           std::optional<AbsoluteTimelineDuration> absolute_duration, std::vector<Track> tracks);
    static runtime::Result<Sequence, ModelError>
    create(ItemId id, std::string name, std::optional<timebase::TickDuration> musical_duration,
           std::optional<AbsoluteTimelineDuration> absolute_duration, std::vector<Track> tracks,
           std::vector<SequenceMarker> markers, std::vector<SequenceRegion> regions);
    static runtime::Result<Sequence, ModelError> create(SequenceInput input);
    static runtime::Result<Sequence, ModelError>
    create(ItemId id, std::string name, std::optional<timebase::TickDuration> musical_duration,
           std::optional<AbsoluteTimelineDuration> absolute_duration, std::vector<Track> tracks,
           std::vector<SequenceMarker> markers, std::vector<SequenceRegion> regions,
           ChordScaleLane chord_scale_lane);

    ItemId id() const noexcept;
    const std::string& name() const noexcept;
    std::optional<timebase::TickDuration> duration() const noexcept;
    std::optional<AbsoluteTimelineDuration> absolute_duration() const noexcept;
    std::span<const Track> tracks() const noexcept;
    std::span<const ItemId> track_order() const noexcept;
    std::span<const ItemId> outgoing_sequence_refs() const noexcept;
    const Track* find_track(ItemId id) const noexcept;
    const ChordScaleLane& chord_scale_lane() const noexcept;
    const DynamicsLane& dynamics_lane() const noexcept;
    const GrooveTemplate& groove() const noexcept;
    std::span<const SequenceMarker> markers() const noexcept;
    std::span<const SequenceRegion> regions() const noexcept;
    SceneView scenes() const noexcept;
    const SequenceMarker* find_marker(ItemId id) const noexcept;
    const SequenceRegion* find_region(ItemId id) const noexcept;
    const Scene* find_scene(ItemId id) const noexcept;
    const Slot* find_slot(ItemId id) const noexcept;
    runtime::Result<Sequence, ModelError> replace_track(Track track) const;
    runtime::Result<Sequence, ModelError>
    insert_track(Track track, std::optional<ItemId> before_track_id = std::nullopt) const;
    runtime::Result<Sequence, ModelError>
    move_track(ItemId track_id, std::optional<ItemId> before_track_id = std::nullopt) const;
    runtime::Result<Sequence, ModelError> erase_track(ItemId id) const;
    runtime::Result<Sequence, ModelError> insert_marker(SequenceMarker marker) const;
    runtime::Result<Sequence, ModelError> erase_marker(ItemId id) const;
    runtime::Result<Sequence, ModelError> insert_region(SequenceRegion region) const;
    runtime::Result<Sequence, ModelError> erase_region(ItemId id) const;
    runtime::Result<Sequence, ModelError> replace_region(SequenceRegion replacement) const;
    runtime::Result<Sequence, ModelError>
    insert_scene(Scene scene, std::optional<ItemId> before_scene_id = std::nullopt) const;
    runtime::Result<Sequence, ModelError> erase_scene(ItemId id) const;
    runtime::Result<Sequence, ModelError>
    insert_slot(ItemId scene_id, Slot slot,
                std::optional<ItemId> before_slot_id = std::nullopt) const;
    runtime::Result<Sequence, ModelError> erase_slot(ItemId scene_id, ItemId slot_id) const;
    Sequence with_chord_scale_lane(ChordScaleLane lane) const;
    Sequence with_dynamics_lane(DynamicsLane lane) const;
    Sequence with_groove(GrooveTemplate groove) const;
    std::size_t shared_launcher_nodes_with(const Sequence& other) const;
    bool shares_launcher_storage_with(const Sequence& other) const noexcept;
    bool shares_storage_with(const Sequence& other) const noexcept;
    static LauncherIndexStats launcher_index_stats() noexcept;
 
  private:
    friend class Project;
    friend struct detail::SequenceEditAccess;
    struct Data;
    bool shares_compile_structure_with(const Sequence& other) const noexcept;
    // Annotation edits validate only the annotation lists and share the existing
    // track storage and identity index; they never re-walk the arrangement.
    runtime::Result<Sequence, ModelError>
    with_annotations(std::vector<SequenceMarker> markers,
                     std::vector<SequenceRegion> regions) const;
    explicit Sequence(std::shared_ptr<const Data> data) : data_(std::move(data)) {}
    std::shared_ptr<const Data> data_;
};

inline constexpr std::size_t kMaxSequenceNestingDepth = 8;
 
// Where this session's zero sits on the source/house clock — the document form
// of "this session starts at 01:00:00:00". Stored as an absolute sample offset
// paired with its own rational rate, never as a formatted timecode string:
// frame-rate formatting is a presentation concern and a string would make the
// same instant compare unequal across display rates.
std::optional<ModelError>
validate_sequence_graph(std::span<const Sequence> sequences);
std::optional<ModelError>
validate_sequence_edge(std::span<const Sequence> sequences,
                       ItemId parent_id, ItemId child_id);

struct SessionStart {
    timebase::SamplePosition start;
    timebase::RationalRate sample_rate;

    constexpr bool operator==(const SessionStart& other) const noexcept {
        return start == other.start && sample_rate == other.sample_rate;
    }
};

struct ProjectInput {
    ItemId id;
    std::string name;
    std::uint64_t next_item_id = 1;
    ItemId root_sequence_id;
    std::vector<MediaAsset> assets;
    std::vector<Sequence> sequences;
    timebase::TempoMap tempo_map{};
    timebase::MeterMap meter_map{};
    std::optional<SessionStart> session_start;
    // Absence states no tuning at all, which is not the same claim as stating
    // equal temperament: a document that never chose still follows whatever the
    // host or instrument defaults to.
    std::optional<TuningReference> tuning;
};

enum class ItemKind : std::uint8_t {
    Project,
    Asset,
    Sequence,
    Track,
    Clip,
    Note,
    MidiLane,
    MidiLanePoint,
    DevicePlacement,
    AutomationLane,
    AutomationPoint,
    Modulator,
    MacroControl,
    ModulationRoute,
    TakeLane,
    Take,
    Marker,
    Region,
    Scene,
    Slot,
};

constexpr ItemId immediate_parent_id(ItemKind kind, ItemId project_id, ItemId sequence_id,
                                     ItemId track_id, ItemId clip_id,
                                     ItemId lane_id = {}) noexcept {
    switch (kind) {
    case ItemKind::Project:
        return {};
    case ItemKind::Asset:
    case ItemKind::Sequence:
        return project_id;
    case ItemKind::Track:
    case ItemKind::Marker:
    case ItemKind::Region:
    case ItemKind::Scene:
        return sequence_id;
    case ItemKind::Slot:
        return lane_id;
    case ItemKind::Clip:
    case ItemKind::DevicePlacement:
    case ItemKind::AutomationLane:
    case ItemKind::Modulator:
    case ItemKind::MacroControl:
    // A route is owned by the track, not by the source it reads. Parenting it
    // to its source would make the source's removal an ownership question the
    // document answers twice, and would leave a route whose source is a macro
    // and a route whose source is a modulator with different owners.
    case ItemKind::ModulationRoute:
    case ItemKind::TakeLane:
        return track_id;
    case ItemKind::Note:
    case ItemKind::MidiLane:
        return clip_id;
    case ItemKind::AutomationPoint:
    case ItemKind::Take:
    case ItemKind::MidiLanePoint:
        return lane_id;
    }
    return {};
}

struct ItemLocation {
    ItemKind kind = ItemKind::Project;
    // Immediate ownership is canonical; the remaining IDs cache ancestor navigation.
    ItemId parent_id;
    ItemId sequence_id;
    ItemId track_id;
    ItemId clip_id;
    bool active = false;
 
    constexpr ItemLocation() noexcept = default;
    constexpr ItemLocation(ItemKind item_kind, ItemId parent, ItemId sequence, ItemId track,
                           ItemId clip, bool is_active) noexcept
        : kind(item_kind), parent_id(parent), sequence_id(sequence), track_id(track), clip_id(clip),
          active(is_active) {}

    constexpr bool has_same_owner(const ItemLocation& other) const noexcept {
        return kind == other.kind && parent_id == other.parent_id;
    }
    constexpr auto operator<=>(const ItemLocation&) const = default;
};

enum class IdentityMutationKind : std::uint8_t { Insert, Deactivate, Reactivate };

struct IdentityMutation {
    IdentityMutationKind mutation = IdentityMutationKind::Insert;
    ItemId item;
    ItemLocation location;
};

struct ProjectIdentityStats {
    std::uint64_t live_nodes = 0;
    std::uint64_t nodes_created = 0;
};

class SequenceCompileStructureToken {
  public:
    SequenceCompileStructureToken() noexcept = default;

    bool valid() const noexcept {
        return value_ != 0;
    }
 
    constexpr bool operator==(const SequenceCompileStructureToken&) const noexcept = default;
 
  private:
    friend class Project;
    explicit SequenceCompileStructureToken(std::uint64_t value) noexcept : value_(value) {}
    std::uint64_t value_ = 0;
};

class Project {
  public:
    static runtime::Result<Project, ModelError> create(ProjectInput input);

    ItemId id() const noexcept;
    const std::string& name() const noexcept;
    std::uint64_t next_item_id() const noexcept;
    ItemId root_sequence_id() const noexcept;
    std::span<const MediaAsset> assets() const noexcept;
    std::span<const Sequence> sequences() const noexcept;
    const timebase::TempoMap& tempo_map() const noexcept;
    const timebase::MeterMap& meter_map() const noexcept;
    const std::optional<SessionStart>& session_start() const noexcept;
    const std::optional<TuningReference>& tuning() const noexcept;
    const MediaAsset* find_asset(ItemId id) const noexcept;
    const Sequence* find_sequence(ItemId id) const noexcept;
    std::optional<ItemLocation> locate(ItemId id) const noexcept;
    std::size_t shared_identity_nodes_with(const Project& other) const;
    bool shares_storage_with(const Project& other) const noexcept;
    SequenceCompileStructureToken sequence_compile_structure_token() const noexcept;
    static ProjectIdentityStats identity_stats() noexcept;
    ItemIdAllocator item_id_allocator() const noexcept {
        return ItemIdAllocator(next_item_id());
    }
 
  private:
    friend struct ProjectEditAccess;
    friend class detail::ProjectStateAccess;
    struct Data;
    runtime::Result<Project, ModelError>
    replace_sequence(Sequence sequence, std::span<const IdentityMutation> identities = {},
                     std::optional<std::uint64_t> next_item_id = std::nullopt) const;
    runtime::Result<Project, ModelError>
    append_sequence(Sequence sequence, std::span<const IdentityMutation> identities = {},
                    std::optional<std::uint64_t> next_item_id = std::nullopt) const;
    runtime::Result<Project, ModelError>
    remove_sequence(ItemId sequence_id, std::span<const IdentityMutation> identities = {}) const;
    // Appends a sealed media asset as a pinned project input. The asset carries
    // its own ContentHash identity; identity mutations register (or reactivate)
    // the ItemKind::Asset entry the same way clip inserts do.
    runtime::Result<Project, ModelError>
    append_asset(MediaAsset asset, std::span<const IdentityMutation> identities = {},
                 std::optional<std::uint64_t> next_item_id = std::nullopt) const;
    runtime::Result<Project, ModelError>
    remove_asset(ItemId asset_id, std::span<const IdentityMutation> identities = {}) const;
    Project replace_tempo_map(timebase::TempoMap tempo_map) const;
    Project replace_meter_map(timebase::MeterMap meter_map) const;
    // Unlike the tempo and meter maps this returns a Result: a tuning has a
    // validity rule (valid_tuning_reference) that Project::create already
    // applies, and a replacement path that skipped it could seat a tuning a
    // fresh construction would refuse.
    runtime::Result<Project, ModelError>
    replace_tuning(std::optional<TuningReference> tuning) const;
    explicit Project(std::shared_ptr<const Data> data) : data_(std::move(data)) {}
    std::shared_ptr<const Data> data_;
};

class IdRemapTable {
  public:
    std::span<const std::pair<ItemId, ItemId>> entries() const noexcept {
        return entries_;
    }

    std::optional<ItemId> find(ItemId old_id) const noexcept;
 
  private:
    friend struct IdRemapBuilder;
    std::vector<std::pair<ItemId, ItemId>> entries_;
};

struct ExternalIdFixup {
    void* context = nullptr;
    runtime::Result<ItemId, ModelError> (*map)(void*, ItemId) noexcept = nullptr;

    runtime::Result<ItemId, ModelError> apply(ItemId id) const noexcept;
};

struct RemapIdFixups {
    ExternalIdFixup asset;
    ExternalIdFixup sequence;
};

struct RemappedClip {
    Clip clip;
    IdRemapTable ids;
};

struct RemappedTrack {
    Track track;
    IdRemapTable ids;
};

struct RemappedSequence {
    Sequence sequence;
    IdRemapTable ids;
};

runtime::Result<RemappedClip, ModelError> remap_ids(const Clip& clip, ItemIdAllocator& allocator,
                                                    ExternalIdFixup external = {});
runtime::Result<RemappedClip, ModelError> remap_ids(const Clip& clip, ItemIdAllocator& allocator,
                                                    RemapIdFixups fixups);
runtime::Result<RemappedTrack, ModelError> remap_ids(const Track& track, ItemIdAllocator& allocator,
                                                     ExternalIdFixup external = {});
runtime::Result<RemappedTrack, ModelError> remap_ids(const Track& track, ItemIdAllocator& allocator,
                                                     RemapIdFixups fixups);
runtime::Result<RemappedSequence, ModelError>
remap_ids(const Sequence& sequence, ItemIdAllocator& allocator, ExternalIdFixup external = {});
runtime::Result<RemappedSequence, ModelError>
remap_ids(const Sequence& sequence, ItemIdAllocator& allocator, RemapIdFixups fixups);
runtime::Result<RemappedSequence, ModelError>
remap_ids(const Sequence& sequence, std::span<const std::pair<ItemId, ItemId>> carried_ids,
          RemapIdFixups fixups = {});

struct RemappedProject {
    Project project;
    IdRemapTable ids;
};

runtime::Result<RemappedProject, ModelError> remap_ids(const Project& project,
                                                       std::uint64_t first_id);

 
} // namespace pulp::timeline