From da31343d1ae2aa1737166f728d034b1ef42b105a Mon Sep 17 00:00:00 2001 From: "fts-forge[bot]" <345159799+fts-forge[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:25:42 -0800 Subject: [PATCH 1/2] feat(session): read the song's structure through the service, ramps included `Request::ReadStructure` answers the tempo map, markers and regions, a `read` every extension may make: a follower (Ignition's cue list, a chart) resolves musical time with it, so it must see the session's own tempo map, not a copy. `TempoChange` gains the ramp's `shape` and `tension`, so seconds resolve exactly as the session's map does; `TempoMapData::of` and `to_tempo_map` convert. `SessionDoc` gains `markers()` and `regions()`. Test: a linear ramp set with the structure grant reads back unchanged by an extension with none, and resolves seconds to the same quarter notes as the session's map. Co-Authored-By: Claude Opus 5.5 --- crates/session/src/doc.rs | 12 +++++ crates/session/src/service.rs | 62 ++++++++++++++++++++- crates/session/tests/session/service.rs | 71 +++++++++++++++++++++++++ 3 files changed, 143 insertions(+), 2 deletions(-) diff --git a/crates/session/src/doc.rs b/crates/session/src/doc.rs index f510d420..45171709 100644 --- a/crates/session/src/doc.rs +++ b/crates/session/src/doc.rs @@ -227,6 +227,18 @@ impl SessionDoc { read_records(&self.doc.get_map(LANES), read_lane) } + /// Every marker. + #[must_use] + pub fn markers(&self) -> BTreeMap { + read_records(&self.doc.get_map(MARKERS), read_marker) + } + + /// Every region. + #[must_use] + pub fn regions(&self) -> BTreeMap { + read_records(&self.doc.get_map(REGIONS), read_region) + } + /// Every item. #[must_use] pub fn items(&self) -> BTreeMap { diff --git a/crates/session/src/service.rs b/crates/session/src/service.rs index 9b4ec18f..84e1a9e7 100644 --- a/crates/session/src/service.rs +++ b/crates/session/src/service.rs @@ -75,6 +75,9 @@ pub enum Request { Remove { name: String }, /// Every lane, and every item with other extensions' payloads nulled. ReadTimeline, + /// The song's structure: the tempo map, markers and regions, which + /// every extension reads (a follower resolves musical time with it). + ReadStructure, /// Puts a lane it owns. PutLane { id: LaneId, lane: Lane }, /// Removes a lane it owns, and the items on it it owns. Another @@ -121,6 +124,47 @@ pub struct TempoChange { pub bpm: f64, /// The new meter, when it changes here. pub meter: Option, + /// How the tempo moves from here to the next change: REAPER's shape + /// (`None` or 1 holds, 0 is linear, 5 bezier); see `time::TempoShape`. + pub shape: Option, + /// A bezier shape's tension. + pub tension: Option, +} + +impl TempoMapData { + /// `tempo` as plain data, ramps included. + #[must_use] + pub fn of(tempo: &TempoMap) -> Self { + let meter = tempo.default_meter(); + Self { + default_bpm: tempo.default_bpm(), + numerator: meter.numerator, + denominator: meter.denominator, + points: tempo + .points() + .iter() + .map(|p| TempoChange { + seconds: p.position_seconds(), + bpm: p.bpm, + meter: p.time_signature.map(|t| Meter { + numerator: t.numerator, + denominator: t.denominator, + }), + shape: p.shape, + tension: p.bezier_tension, + }) + .collect(), + } + } + + /// The tempo map this describes. + /// + /// # Errors + /// + /// A tempo that is not a positive number, or a meter with a zero. + pub fn to_tempo_map(&self) -> Result { + tempo_map(self) + } } /// The answer. @@ -133,6 +177,11 @@ pub enum Response { lanes: BTreeMap, items: BTreeMap, }, + Structure { + tempo: TempoMapData, + markers: BTreeMap, + regions: BTreeMap, + }, } /// Why a request was not done. @@ -177,7 +226,7 @@ impl From for ServiceError { #[must_use] pub const fn action_for(request: &Request) -> &'static str { match request { - Request::ReadData | Request::ReadTimeline => READ, + Request::ReadData | Request::ReadTimeline | Request::ReadStructure => READ, Request::SetTempo { .. } | Request::PutMarker { .. } | Request::PutRegion { .. } @@ -265,6 +314,12 @@ pub fn handle( request: Request, ) -> Result { match request { + // Everyone reads the structure; no grant needed. + Request::ReadStructure => Ok(Response::Structure { + tempo: TempoMapData::of(&doc.tempo()), + markers: doc.markers(), + regions: doc.regions(), + }), Request::ReadTimeline | Request::PutLane { .. } | Request::RemoveLane { .. } @@ -483,7 +538,10 @@ fn tempo_map(data: &TempoMapData) -> Result { Some(m) => Some(meter(m.numerator, m.denominator)?), None => None, }; - points.push(TempoMap::point(change.seconds, change.bpm, meter)); + let mut point = TempoMap::point(change.seconds, change.bpm, meter); + point.shape = change.shape; + point.bezier_tension = change.tension; + points.push(point); } Ok(TempoMap::new( data.default_bpm, diff --git a/crates/session/tests/session/service.rs b/crates/session/tests/session/service.rs index 877d3808..0f446b29 100644 --- a/crates/session/tests/session/service.rs +++ b/crates/session/tests/session/service.rs @@ -244,6 +244,8 @@ fn the_song_structure_needs_a_grant() { numerator: 6, denominator: 8, }), + shape: None, + tension: None, }], }, }; @@ -268,3 +270,72 @@ fn the_song_structure_needs_a_grant() { }; assert!(refused(handle(&doc, &ext("keyflow"), granted, bad))); } + +#[test] +fn everyone_reads_the_structure_with_its_ramps() { + let doc = studio(); + let granted = Grants { structure: true }; + // A ramp from 60 to 120 BPM over 10 s (shape 0: linear), then held. + let tempo = TempoMapData { + default_bpm: 60.0, + numerator: 4, + denominator: 4, + points: vec![ + TempoChange { + seconds: 0.0, + bpm: 60.0, + meter: None, + shape: Some(0), + tension: None, + }, + TempoChange { + seconds: 10.0, + bpm: 120.0, + meter: None, + shape: None, + tension: None, + }, + ], + }; + handle( + &doc, + &ext("keyflow"), + granted, + Request::SetTempo { + tempo: tempo.clone(), + }, + ) + .unwrap(); + handle( + &doc, + &ext("keyflow"), + granted, + Request::PutMarker { + id: MarkId::from("drop"), + marker: session::Marker { + at: Time::QuarterNotes(32.0), + name: "Drop".into(), + color: None, + ruler: None, + }, + }, + ) + .unwrap(); + // Ignition, granted nothing, reads it. + let Response::Structure { + tempo: read, + markers, + regions, + } = ask(&doc, "ignition", Request::ReadStructure).unwrap() + else { + panic!("not the structure") + }; + assert_eq!(read, tempo); + assert_eq!(markers[&MarkId::from("drop")].name, "Drop"); + assert!(regions.is_empty()); + // The ramp is kept: seconds resolve as the session's own map does. + let map = read.to_tempo_map().unwrap(); + let qn = Time::Seconds(7.25).quarter_notes(&map); + assert!((qn - Time::Seconds(7.25).quarter_notes(&doc.tempo())).abs() < 1e-12); + assert!((map.bpm_at(11.0) - 120.0).abs() < 1e-12); +} From 8e6ba128b6b0442f932e5f8e9a18a38917939ea6 Mon Sep 17 00:00:00 2001 From: "fts-forge[bot]" <345159799+fts-forge[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:40:47 -0800 Subject: [PATCH 2/2] docs(session): what is built toward a shared session, and what is next MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §9 now records steps 1-5 as built (the vox service, the extension face, Keyflow's host, the shared clock with its measured results, the structure read and Ignition's cues), what each found, and what is still missing in order. Co-Authored-By: Claude Opus 5.5 --- docs/design/session.md | 82 +++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 28 deletions(-) diff --git a/docs/design/session.md b/docs/design/session.md index 8df10c46..fabb64aa 100644 --- a/docs/design/session.md +++ b/docs/design/session.md @@ -686,34 +686,60 @@ session as an Architect document, kept in step through Architect's sync. ## 9. Before Studio, Keyflow or Ignition can share a session -In order: - -1. **The `fts.session` service wrapper**, built: `session::host` (feature - `vox`), `SessionService::ask(doc, request)` over `service::handle`. - - The caller is the call's principal. An extension's call - (`Principal::Extension`) names its namespace; any other principal is - refused. - - The action is the permission engine's answer on `doc/`: `read`, - `write`, or `structure` for tempo, markers and regions. - - The gate checks `read` before decoding (`doc/**`); the handler - checks the exact document. - - The host and its gate ask the same engine, the org's one, which - answers a share link's guest by what the link grants. A read-only - link reads and every edit is refused, with no guest code path. -2. **A host that holds the document**, for the first consumer, which - should be Keyflow, the smallest: a chart with a tempo map and no - engine. Its app opens a `.session` as a `DocFile` of `kind()`, syncs it - with `OrgSyncs` (or a share link), and serves `fts.session` to its - chart view. Keyflow's chart moves into `keyflow`'s `chart` text, - bound with `TextBinding`. -3. **The shared clock** (§7.5), so a follower on another machine follows - for real. Until then playheads across machines are as good as the - process clocks' agreement (unrelated). -4. **Ignition** on the same session: its cue lists as lanes and items, - following the transport with `Tracker`, through the service. -5. **Studio**: rename its `session` crate to `session-app`, then the - migration of §5.3, which is the long pole (the DAW's data as extension - data, the live document's 4 → 5 migration, the file). +Built (2026-11-18), in order: + +1. **`fts.session` over vox** (`session::host`, session#181). The caller + is the call's principal; what it may do is the permission engine's + answer on `doc/` (`read`, `write`, `structure`). The host and its + gate ask the org's one engine, so a read-only share link's guest reads + and is refused writes, with no guest code path. +2. **`fts.session` as an Architect extension service** + (`session::extension`, session#182). The provider's actions answer for + `cx.caller` (Architect's newer code: the `runtime-compositor-keyflow` + pin), one method per action, so Architect's effect check holds a guest + to `read`. Ids are transparent on the wire, so a timeline crosses JSON. +3. **Keyflow as the first host** (keyflow#85: `keyflow-session`): + - a chart is Keyflow's `chart` text entry in a `.session` `DocFile`, + synced through Architect's sync and bound to an editor with + `TextBinding`; + - `Provider` serves `fts.session`; + - `ChartSource` is the chart pane's state, a document (the chart + alone) or a session. + + Found: Architect's `SyncedDoc` does not persist what it receives + (`apply_remote`, not `apply_remote_durable`); `ChartSession::save` + writes it. +4. **The shared clock** (`session::clock`, session#183): the host + serves `now()`, a peer's `SharedClock` estimates it, `play_state` + stamps `PlayState::at_ms` in it. + - **Two processes on one machine:** playhead error max 168 µs + (exact truth). + - **Two machines on a LAN:** the estimate is within ±0.92 ms (half + the round trip); wall clocks cannot judge it tighter. +5. **Reading the structure** (`ReadStructure`, ramps included, + session#184), and **Ignition on the session** (ignition#16: + `ignition-session`): + - cue lists as lanes and timed items at their bars, untimed cues and + list settings as Ignition's data; + - read back in GO order for `CuePlayer`; + - followed from the transport by `CueFollower`. + +Still missing, in the order to do them: + +1. **The chart view on the session**: `feat/runtime-chart` reads its chart + through `ChartSource` (four lines, keyflow#85 lists them) and the app + hosting Keyflow registers the provider's actions. Needs that branch's + Architect pin. +2. **Architect**: + - `SyncedDoc` applying remote updates durably; + - the shared clock moved into the presence driver; + - a tag the fleet can pin with `cx.caller`. +3. **Network sync** in a real host: the org driver (`OrgSyncs`) or a share + link's iroh dial, which the tests stand in for with the in-process + transport. +4. **Ignition's extension** asking through its host, and DMX output taken + from `CueFollower`. +5. **Studio**: rename its `session` crate to `session-app`, then §5.3. ## 10. Not sure of