Skip to main content
The orchestrator is the central coordinator that makes AI-assisted composition and orchestration safe and reliable at scale. It maintains the canonical score state and mediates all agent operations through progressive validation and typed operations. Core principle: Agents read MRS-S; agents write MRS-Ops. Only the orchestrator applies changes to canonical state. See: /MRS-Specification-RFC#12-orchestrator-contract

​
Orchestrator Architecture

         ORCHESTRATOR (owns canonical score state)
                │
    ┌───────────┼───────────┬───────────┐
    ▼           ▼           ▼           ▼
 Harmony    Melody      Orch.      Expression
  Agent      Agent      Agent        Agent
    │           │           │           │
    └───────────┴───────────┴───────────┘
                │
         Working Set Envelopes
         (scoped MRS-S + context views + lane bundles)

​
Orchestrator Responsibilities

ResponsibilityDescription
UUID mintingMaps tmp-ids to UUIDs; sole authority for ID creation
Derived fieldsComputes :beat-start, :at, reconciles inherited state
Progressive validationValidates operations in stages before application
Canonical state managementMaintains canonical score semantics; applies validated changes
Context generationCreates task-adaptive context views
Conflict detectionUses source-hash to detect concurrent modifications
Audit trailRecords all changes with attribution
Implementation note: “Canonical state” is a semantic concept. An orchestrator may store it as an MRS-S document, an event log plus snapshots, or a database/graph model with indexes. The contract is about behavior: deterministic application, validation, and exportable/auditable semantics.

​
Edit Lanes

Lanes are permission boundaries that determine what an agent may modify.
LaneOwns
structureMeasure list, sections, movements
temporalTempo map, time signatures
harmonyPlanChord symbols, harmonic analysis
notesPitches, durations, rests
expressionDynamics, hairpins, slurs
techniqueArticulations, playing techniques
lyricsLyrics, syllables

​
What Each Lane Controls

LaneCan Create/ModifyCannot Touch
structureMeasures, sections, movements, repeatsEvent content
temporalTempo, time signatures, metric modulationsNotes, spans
harmonyPlanChord symbols, key areas, harmonic rhythmNote pitches
notesPitches, durations, rests, voice assignmentDynamics, slurs
expressionDynamics, hairpins, slurs, phrasingPitches, technique
techniqueArticulations, playing techniques, ornamentsPitches, dynamics
lyricsLyric text, syllabification, alignmentPitches

​
Lane Bundles

Common workflows grant multiple related lanes: 
(define-bundle orchestrate
  :lanes [notes expression technique]
  :description "Full orchestration pass")

(define-bundle dynamics-pass
  :lanes [expression]
  :description "Dynamics and phrasing")

(define-bundle notation-cleanup
  :lanes [notes technique]
  :description "Fix notation issues")

(define-bundle full-compose
  :lanes [structure temporal harmonyPlan notes expression technique]
  :description "Full compositional control")

(define-bundle lyrics-pass
  :lanes [lyrics]
  :description "Lyric writing and alignment")

​
Bundle Selection by Task Type

Task TypeRecommended Bundle
Compose melodynotes or full-compose
Add countermelodyorchestrate
Orchestrate sketchorchestrate
Add dynamicsdynamics-pass
Shape phrases (slurs)expression
Add articulationstechnique
Write lyricslyrics-pass
Fix notationnotation-cleanup

​
Progressive Validation

Operations are validated in stages before application: 
┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Syntax    │ → │ References  │ → │ Permissions │ → │  Musical    │
│ Validation  │   │ Validation  │   │ Validation  │   │  Rules      │
└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘
                                                              │
                                                              ▼
                                                      ┌─────────────┐
                                                      │ Application │
                                                      └─────────────┘

​
Stage 1: Syntax Validation

  • Operation is well-formed
  • Required fields present
  • Types correct

​
Stage 2: Reference Validation

  • All referenced UUIDs exist in source
  • All tmp-ids are unique within envelope
  • Cross-references between ops are valid

​
Stage 3: Permission Validation

  • Operation within granted lanes
  • Operation within granted scope
  • Operation type is allowed

​
Stage 4: Musical Rule Validation

  • Constraints satisfied (range, avoid parallel fifths)
  • Duration sums correct
  • Ties connect same pitches
See: /MRS-Specification-RFC#13-progressive-validation

​
Conflict Detection

The orchestrator uses source-hash to detect concurrent modifications: 
1. Working Set created with source-hash H1
2. Agent produces operations (takes time)
3. Meanwhile, another agent modifies the score
4. Before applying, orchestrator checks current hash
5. Current hash ≠ H1 → conflict detected

​
Conflict Resolution Options

OptionWhen to Use
RejectDefault safe behavior; agent must retry with fresh envelope
RebaseIf operations can be transformed to apply on new state
MergeIf changes are in disjoint regions/lanes

​
Transaction Model

Every change is recorded: 
(transaction
  :id #uuid "..."
  :timestamp "2026-01-17T10:30:00Z"
  :agent "countermelody-agent"
  :source-hash "sha256:..."
  :result-hash "sha256:..."
  :ops-applied 6
  :scope (:measures #uuid "..." #uuid "..." :instruments [clarinet-bb])
  :bundle orchestrate)
Transactions enable:
  • Audit trail: Who changed what, when
  • Rollback: Revert to previous state
  • Replay: Reconstruct state from transactions

​
Checkpoints and Locks

Lock approved decisions to prevent regression: 
(checkpoint
  :id "harmony-approved"
  :created "2026-01-17T10:30:00Z"
  :approved-by "composer"
  :locks
    ((structure :scope :all)
     (harmonyPlan :scope :all)))
After checkpoint:
  • Agents cannot modify locked lanes
  • Validation rejects operations that touch locked content
  • Human approval required to unlock

​
Typical Checkpoint Flow

1. Form sketched → checkpoint structure
2. Harmony planned → checkpoint harmonyPlan
3. Orchestration approved → checkpoint notes
4. Final polish → no locks (expression, technique)

​
Operation Application

When validation passes, the orchestrator applies operations:
  1. Map tmp-ids to UUIDs in deterministic order
  2. Compute derived fields (:at, :beat-start)
  3. Update canonical score state (and export MRS-S if needed)
  4. Update structural index if needed
  5. Record transaction in audit trail
  6. Return result with id-mapping

​
Application Order

Operations are applied in the order received. Dependencies must be satisfied:
  • Create measure before creating events in it
  • Create events before creating spans that reference them
The orchestrator MAY reorder to satisfy dependencies if unambiguous.

​
Partial Application

When some operations fail validation: 
(mrs-ops-result
  :status partial
  :applied 4
  :rejected 2
  :id-mapping (...)
  :errors
    ((error :op 5 :code MUSIC-001 :message "Tie connects different pitches")
     (error :op 6 :code REF-001 :message "Span references non-existent tmp-id")))
Policy options:
  • All-or-nothing: Reject entire batch if any operation fails
  • Partial: Apply valid operations, return errors for invalid
  • Interactive: Pause for human decision on errors

​
Human Review Gates

Certain operations should trigger human review by default:
TriggerReason
Structure changesForm is foundational
Temporal changesAffects timing across the score
Locked lane touchedCheckpoint protection
Conflict detectedCannot auto-resolve safely
In practice, a “review” is not just textual—musicians also need to audition. Implementations can pair semantic diffs with:
  • a rendered excerpt of the affected region, and/or
  • a playback preview (e.g., MIDI/rendered audio)
Human approval is recorded: 
(human-review
  :transaction-id #uuid "..."
  :status approved
  :reviewer "arranger"
  :notes "Approved with minor adjustment")