Skip to main content
MRS defines a protocol for agent operations centered on typed operations (MRS-Ops), task-adaptive context, and progressive validation. Core Principle: Agents read MRS-S fragments with task-appropriate context. Agents write typed MRS-Ops operations. The orchestrator validates and applies. See: /MRS-Specification-RFC#5-mrs-ops-the-mutation-protocol

​
Why Typed Operations?

Asking agents to emit complete MRS-S fragments creates failure modes:
  • Accidental omission: Agent returns less content → content silently deleted
  • Calculation errors: Miscomputed :at values, duration sums
  • Hallucinated references: IDs that don’t exist
  • UUID management: Agent must generate valid, non-colliding UUIDs
MRS-Ops eliminates these by design:
  • Explicit operations: Create, update, delete are distinct (no omission risk)
  • Orchestrator-derived fields: Agent provides beat; orchestrator computes :at
  • Temporary IDs: Agent uses tmp-ids; orchestrator assigns UUIDs
  • Minimal surface: Only changed content in output

​
MRS-Ops Envelope

(mrs-ops
  :version 1.0
  :scope-hash "sha256:a3f2c1b9e4d7..."
  :base-revision "rev:abc123"
  
  :ops
    (<operation>
     <operation>
     ...))
FieldRequiredDescription
:versionYESProtocol version
:scope-hashYESHash of source Working Set (conflict detection)
:base-revisionNORevision ID of source state
:opsYESList of operations

​
Operation Types

​
Create Event

(create-event
  :tmp-id "e1"
  :measure #uuid "018c3f40-002d-..."
  :instrument clarinet-bb
  :voice v1
  :beat 0
  :pitch Eb4
  :duration q
  :dyn mp
  :art staccato)
FieldRequiredDescription
:tmp-idYESTemporary ID (orchestrator maps to UUID)
:measureYESTarget measure UUID
:instrumentYESTarget instrument ID
:voiceYESTarget voice
:beatYESBeat position (rational, e.g., 0, 2+1/2)
:pitchYESPitch or chord or r for rest
:durationYESDuration code (q, h, e, etc.)
Other propertiesNO:dyn, :art, :orn, :tech, etc.

​
Update Event

(update-event
  :id #uuid "018c3f2a-0001-..."
  :set
    ((:pitch D5)
     (:dyn f)))
FieldRequiredDescription
:idYESExisting event UUID
:setYESList of (field value) pairs to update

​
Delete Event

(delete-event
  :id #uuid "018c3f2a-0001-...")

​
Create Span

(create-span
  :tmp-id "s1"
  :type slur
  :from "e1"        ; Can reference tmp-id or UUID
  :to "e5")
Span endpoints can reference:
  • Existing UUIDs: #uuid "018c3f2a-..."
  • Temporary IDs from same operation set: "e1"

​
Update Span

(update-span
  :id #uuid "018c3f2c-0001-..."
  :set
    ((:style legato)))
Note: Span endpoints (:from, :to, :events) are immutable. To change endpoints, delete and recreate the span.

​
Delete Span

(delete-span
  :id #uuid "018c3f2c-0001-...")

​
Create Measure

(create-measure
  :tmp-id "m1"
  :after #uuid "018c3f40-0030-..."
  :time 4/4
  :key C :mode minor)
The orchestrator assigns UUID, :number, and computes :beat-start.

​
Delete Measure

(delete-measure
  :id #uuid "018c3f40-0030-...")
Warning: Deleting a measure deletes all events within it.

​
Instrument Change

(instrument-change
  :tmp-id "ic1"
  :player woodwind-2
  :measure #uuid "018c3f40-0045-..."
  :beat 0
  :to piccolo)

​
Temporary ID Rules

  1. Tmp-ids MUST be strings starting with a letter: "e1", "span-a", "m1"
  2. Tmp-ids are scoped to a single MRS-Ops envelope
  3. Operations MAY reference each other’s tmp-ids within same envelope
  4. Orchestrator maps all tmp-ids to UUIDs before application
  5. Response includes the tmp-id → UUID mapping

​
Task-Adaptive Context Views

Context views provide task-relevant information beyond the edit scope. Unlike fixed rings, views are selected for the specific task.

​
Melodic Reference

(context-view melodic-reference
  :instruments [violin-1]
  :measures #uuid "..." #uuid "..."
  :content
    (measures
      (measure :id #uuid "..." :number 45
        (violin-1
          (v1
            (: 0 G5.q :id #uuid "...")
            ...)))))

​
Harmonic Context

(context-view harmonic-context
  :content
    (harmony-events
      (chord :measure #uuid "..." :beat 0 :symbol Cm :function i)
      (chord :measure #uuid "..." :beat 2 :symbol Fm :function iv)))

​
Orchestration Map

(context-view orchestration-map
  :content
    (texture-regions
      (region :measures [#uuid "..." #uuid "..."]
              :active [violin-1 violin-2 viola cello]
              :density medium
              :character "lyrical strings")))

​
Phrase Structure

(context-view phrase-structure
  :content
    (phrases
      (phrase :start #uuid "..." :end #uuid "..." :type antecedent)
      (phrase :start #uuid "..." :end #uuid "..." :type consequent)))

​
View Selection by Task Type

Task TypeTypical Context Views
Composephrase-structure, harmonic-context, thematic-references
Countermelodymelodic-reference, harmonic-context
Orchestrateorchestration-map, dynamics-profile
Harmonizemelodic-reference, phrase-structure
Dynamicsphrase-structure, dynamics-profile

​
Example: Add Countermelody

Working Set Envelope (agent receives): 
(working-set
  :version 1.0
  :source-hash "sha256:..."
  :scope (:measures #uuid "..." #uuid "...") (:instruments [clarinet-bb])
  :bundle orchestrate
  :task "Add countermelody responding to violin"
  :content (measures ...)
  :context-views
    (context-view melodic-reference :instruments [violin-1] :content ...)
    (context-view harmonic-context :content ...))
Agent Response (MRS-Ops): 
(mrs-ops
  :version 1.0
  :scope-hash "sha256:..."
  :ops
    ((create-event :tmp-id "e1" :measure #uuid "..." 
                   :instrument clarinet-bb :voice v1
                   :beat 0 :pitch Eb4 :duration q :dyn mp)
     (create-event :tmp-id "e2" :measure #uuid "..."
                   :instrument clarinet-bb :voice v1
                   :beat 1 :pitch D4 :duration q)
     (create-event :tmp-id "e3" :measure #uuid "..."
                   :instrument clarinet-bb :voice v1
                   :beat 2 :pitch Eb4 :duration e)
     (create-event :tmp-id "e4" :measure #uuid "..."
                   :instrument clarinet-bb :voice v1
                   :beat 2+1/2 :pitch F4 :duration e)
     (create-event :tmp-id "e5" :measure #uuid "..."
                   :instrument clarinet-bb :voice v1
                   :beat 3 :pitch G4 :duration q)
     
     (create-span :tmp-id "s1" :type slur :from "e1" :to "e5")))
Orchestrator Response: 
(mrs-ops-result
  :status success
  :id-mapping
    (("e1" #uuid "019b2c3d-0001-...")
     ("e2" #uuid "019b2c3d-0002-...")
     ("e3" #uuid "019b2c3d-0003-...")
     ("e4" #uuid "019b2c3d-0004-...")
     ("e5" #uuid "019b2c3d-0005-...")
     ("s1" #uuid "019b2c3d-0010-..."))
  :applied 6
  :revision "rev:def456")

​
Lane Bundles

Lane bundles grant permissions for common workflows:
BundleLanesUse Case
orchestratenotes, expression, techniqueFull orchestration
dynamics-passexpressionDynamics only
notation-cleanupnotes, techniqueFix notation
full-composeall creative lanesFull control

​
Constraint Language

:constraints
  ((range clarinet-bb E3 C7)
   (avoid parallel-fifths violin-1)
   (prefer chord-tones downbeats)
   (max-interval P8)
   (note-density 2 8))
ConstraintDescription
rangeNotes within instrument range
avoidPrevent voice-leading errors
preferStyle preferences
max-intervalMaximum melodic leap
note-densityNotes per measure
Constraint violations are caught in progressive validation.