Orchestrator Contract

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

Responsibility	Description
UUID minting	Maps tmp-ids to UUIDs; sole authority for ID creation
Derived fields	Computes `:beat-start`, `:at`, reconciles inherited state
Progressive validation	Validates operations in stages before application
Canonical state management	Maintains canonical score semantics; applies validated changes
Context generation	Creates task-adaptive context views
Conflict detection	Uses source-hash to detect concurrent modifications
Audit trail	Records 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.

Lane	Owns
`structure`	Measure list, sections, movements
`temporal`	Tempo map, time signatures
`harmonyPlan`	Chord symbols, harmonic analysis
`notes`	Pitches, durations, rests
`expression`	Dynamics, hairpins, slurs
`technique`	Articulations, playing techniques
`lyrics`	Lyrics, syllables

What Each Lane Controls

Lane	Can Create/Modify	Cannot Touch
`structure`	Measures, sections, movements, repeats	Event content
`temporal`	Tempo, time signatures, metric modulations	Notes, spans
`harmonyPlan`	Chord symbols, key areas, harmonic rhythm	Note pitches
`notes`	Pitches, durations, rests, voice assignment	Dynamics, slurs
`expression`	Dynamics, hairpins, slurs, phrasing	Pitches, technique
`technique`	Articulations, playing techniques, ornaments	Pitches, dynamics
`lyrics`	Lyric text, syllabification, alignment	Pitches

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 Type	Recommended Bundle
Compose melody	`notes` or `full-compose`
Add countermelody	`orchestrate`
Orchestrate sketch	`orchestrate`
Add dynamics	`dynamics-pass`
Shape phrases (slurs)	`expression`
Add articulations	`technique`
Write lyrics	`lyrics-pass`
Fix notation	`notation-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:

Working Set created with source-hash H1
Agent produces operations (takes time)
Meanwhile, another agent modifies the score
Before applying, orchestrator checks current hash
Current hash ≠ H1 → conflict detected

Conflict Resolution Options

Option	When to Use
Reject	Default safe behavior; agent must retry with fresh envelope
Rebase	If operations can be transformed to apply on new state
Merge	If 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

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

Operation Application

When validation passes, the orchestrator applies operations:

Map tmp-ids to UUIDs in deterministic order
Compute derived fields (:at, :beat-start)
Update canonical score state (and export MRS-S if needed)
Update structural index if needed
Record transaction in audit trail
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:

Trigger	Reason
Structure changes	Form is foundational
Temporal changes	Affects timing across the score
Locked lane touched	Checkpoint protection
Conflict detected	Cannot 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")

Overview

MRS-S Format

Agent Workflows

Model & Validation

Orchestrator Contract

Orchestrator Architecture

Orchestrator Responsibilities

Edit Lanes

What Each Lane Controls

Lane Bundles

Bundle Selection by Task Type

Progressive Validation

Stage 1: Syntax Validation

Stage 2: Reference Validation

Stage 3: Permission Validation

Stage 4: Musical Rule Validation

Conflict Detection

Conflict Resolution Options

Transaction Model

Checkpoints and Locks

Typical Checkpoint Flow

Operation Application

Application Order

Partial Application

Human Review Gates

​Orchestrator Architecture

​Orchestrator Responsibilities

​Edit Lanes

​What Each Lane Controls

​Lane Bundles

​Bundle Selection by Task Type

​Progressive Validation

​Stage 1: Syntax Validation

​Stage 2: Reference Validation

​Stage 3: Permission Validation

​Stage 4: Musical Rule Validation

​Conflict Detection

​Conflict Resolution Options

​Transaction Model

​Checkpoints and Locks

​Typical Checkpoint Flow

​Operation Application

​Application Order

​Partial Application

​Human Review Gates

Orchestrator Architecture

Orchestrator Responsibilities

Edit Lanes

What Each Lane Controls

Lane Bundles

Bundle Selection by Task Type

Progressive Validation

Stage 1: Syntax Validation

Stage 2: Reference Validation

Stage 3: Permission Validation

Stage 4: Musical Rule Validation

Conflict Detection

Conflict Resolution Options

Transaction Model

Checkpoints and Locks

Typical Checkpoint Flow

Operation Application

Application Order

Partial Application

Human Review Gates