Skip to main content

​
One Semantic Model, Multiple Representations

MRS is a semantic score model plus protocols for safe, bounded editing. It is commonly represented in two complementary forms:
RepresentationPurposeWho Uses It
MRS-SComplete score semantics for reading, audit, and interchangeHumans review; agents read; orchestrator can export/store
MRS-OpsTyped mutations (explicit edits)Agents write; orchestrator validates/applies
An implementation may keep canonical state in a database/graph form for performance, then export MRS-S as needed. Agents read MRS-S content in Working Set Envelopes. Agents write MRS-Ops operations. The orchestrator validates and applies operations to canonical state.

​
File Types

  • MRS-S: .mrs or .mrs-s — application/vnd.mrs+sexpr
  • MRS-Ops: .mrs-ops — application/vnd.mrs-ops+sexpr
  • Encoding: UTF-8 (no BOM)
See: /MRS-Specification-RFC#16-mime-types-and-file-extensions

​
Minimal MRS-S Score

(mrs-s 1.0
  (meta
    :title "Untitled")
  
  (players
    (player violin-player
      :name "Violin"
      :instruments [violin-1]
      :default violin-1))
  
  (instruments
    (instrument violin-1
      :name "Violin"
      :abbr "Vln."
      :family strings
      :staves [treble]
      :transposition none
      :range [G3 E7]))
  
  (measures
    (measure 
      :id #uuid "018c3f40-0001-7890-abcd-ef1234567890"
      :number 1
      :beat-start 0
      :time 4/4
      (violin-1
        (v1
          (: 0 C4.q :id #uuid "018c3f2a-0001-...")
          (: 1 D4.q :id #uuid "018c3f2a-0002-...")
          (: 2 E4.q :id #uuid "018c3f2a-0003-...")
          (: 3 F4.q :id #uuid "018c3f2a-0004-...")))))
  
  (spans))
Key points:
  • Every measure has :id (UUID) and :number (display)
  • Every event has :id (UUID) — no :at required in storage (orchestrator computes it)
  • Players own instruments; instruments appear in measure content

​
Working Set Envelope

For agent tasks, the orchestrator extracts a Working Set Envelope: 
(working-set
  :version 1.0
  :source-hash "sha256:..."
  
  :scope
    (:measures #uuid "018c3f40-0001-..." #uuid "018c3f40-0008-...")
    (:instruments [clarinet-bb])
  :display-hint (:measures 1 8)
  
  :bundle orchestrate
  :allowed-ops [create-event update-event delete-event create-span]
  
  :task "Add clarinet countermelody"
  
  :content
    (meta :time 4/4 :key C :mode minor :tempo 132)
    (instruments
      (instrument clarinet-bb :name "Clarinet in Bb" :abbr "Cl." 
                  :staves [treble] :transposition (down M2)))
    (measures
      (measure 
        :id #uuid "018c3f40-0001-..."
        :number 1
        :beat-start 0
        (clarinet-bb (v1))))  ; Empty — target for agent
    (spans)
  
  :context-views
    (context-view melodic-reference
      :instruments [violin-1]
      :content (measures ...))
    (context-view harmonic-context
      :content (harmony-events ...))
  
  :structural-index-ref "sha256:...")
Key features:
  • Scope uses UUIDs — not measure numbers
  • :bundle grants lane permissions
  • :context-views provide task-relevant information
  • :content is valid MRS-S the agent can read

​
Agent Output: MRS-Ops

Agents write typed operations, not complete fragments: 
(mrs-ops
  :version 1.0
  :scope-hash "sha256:..."
  
  :ops
    ((create-event :tmp-id "e1" :measure #uuid "018c3f40-0001-..." 
                   :instrument clarinet-bb :voice v1
                   :beat 0 :pitch Eb4 :duration q :dyn mp)
     (create-event :tmp-id "e2" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 1 :pitch D4 :duration q)
     (create-event :tmp-id "e3" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 2 :pitch Eb4 :duration e)
     (create-event :tmp-id "e4" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 2+1/2 :pitch F4 :duration e)
     (create-event :tmp-id "e5" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 3 :pitch G4 :duration q)
     
     (create-span :tmp-id "s1" :type slur :from "e1" :to "e5")))
Key features:
  • Explicit operations: create-event, not “here’s the whole fragment”
  • Temporary IDs: "e1", "s1" — orchestrator assigns UUIDs
  • No derived fields: No :at required — orchestrator computes it
  • Spans reference tmp-ids: "e1" in same envelope is valid

​
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")

​
The Workflow

1. Orchestrator extracts Working Set Envelope
   (MRS-S fragment + task-adaptive context + permissions)

2. Agent reads MRS-S content and context views
   
3. Agent produces MRS-Ops (typed operations with tmp-ids)

4. Orchestrator validates progressively:
   - Syntax → References → Permissions → Musical Rules

5. Orchestrator applies:
   - Maps tmp-ids to UUIDs
   - Computes derived fields
   - Updates canonical state

6. Orchestrator returns result (success or specific errors)

​
Why This Works

Failure ModeHow MRS-Ops Eliminates It
Accidental deletionExplicit delete-event required
Calculation errorsOrchestrator computes :at
Hallucinated IDsOrchestrator validates all refs
UUID collisionsOrchestrator mints all UUIDs
See: /MRS-Specification-RFC#5-mrs-ops-the-mutation-protocol