MRS: Music Representation

RFC 0001 — Version 1.0

Status: Draft
Created: 2025-12-12
Updated: 2026-01-17
Authors: MRS Working Group
License: CC BY 4.0

Abstract

This document specifies MRS (Music Representation), a model and protocol suite for encoding and safely editing musical scores in AI-assisted composition and orchestration workflows at professional scale. MRS is built on three core architectural principles:

Separation of storage and mutation formats: MRS-S is the canonical storage format; MRS-Ops is the typed operation protocol for agent mutations
Player-Instrument-Staff model: Professional orchestration semantics with instrument doubling and switching
Task-adaptive context: Dynamic context views tailored to specific editing tasks, not fixed reduction rings

The key insight is that reliable AI-assisted composition requires different optimizations for reading scores (complete, archival MRS-S) versus writing changes (typed, validated operations). Agents read MRS-S fragments with task-appropriate context views; agents write typed operations that the orchestrator validates progressively and applies deterministically. Every musical object carries a stable UUID identifier. The orchestrator is the sole authority for UUID minting, derived field computation, and canonical state management. This eliminates entire classes of agent errors (hallucinated references, calculation mismatches, accidental deletions) while maintaining full semantic fidelity.

Introduction
Design Principles
Architecture Overview
MRS-S: The Canonical Storage Format
MRS-Ops: The Mutation Protocol
Players, Instruments, and Staves
Working Set Envelope
Task-Adaptive Context Views
Structural Index
Analytical Overlays
Data Model
Orchestrator Contract
Progressive Validation
Query Resolution
Extension Mechanisms
MIME Types and File Extensions
Security Considerations
Appendix A: Complete Grammar
Appendix B: Quick Reference
Appendix C: Glossary

1. Introduction

1.1 Motivation

AI cannot currently compose or edit full orchestral scores reliably. Three fundamental challenges block progress: Scale: A full orchestral score (~1.5M tokens) exceeds any context window. Editing measure 847 should not require loading measures 1-846. Context: Musical decisions require understanding surrounding material. An agent writing a countermelody needs phrase boundaries, harmonic rhythm, and thematic relationships—not just the target measures. Reliability: Existing approaches ask AI to emit complete, structurally-valid score fragments. This creates high failure rates from:

Accidental omissions (agent returns less than given)
Calculation errors (duration sums, absolute positions)
Hallucinated references (IDs that don’t exist)
Format violations (malformed syntax)

MRS solves these through architectural separation:

MRS-S (storage): Complete, archival-quality encoding with stable UUIDs
MRS-Ops (mutation): Typed operation protocol with orchestrator-derived fields
Task-adaptive context: Dynamic views tailored to specific editing tasks
Progressive validation: Operations validated before application
Orchestrator authority: Single source of truth for UUIDs, derived fields, and state

1.2 Goals

Semantic completeness: Encode everything a professional engraver needs (Dorico-level granularity)
Reliable agent output: Typed operations with progressive validation minimize repair loops
Structural stability: UUIDs survive insertions, deletions, and reorderings
Professional orchestration: Player/instrument model supports doubling, switching, condensing
Task-appropriate context: Agents receive information relevant to their specific task
Deterministic reconciliation: Operations produce predictable, auditable results
Human-auditable: Operations are semantic diffs; humans review intent, not syntax

1.3 Non-Goals

Encoding visual layout (page breaks, staff spacing, collision avoidance)
Providing a programming language (no loops, conditionals, macros)
Defining audio synthesis or playback behavior
Replacing domain-specific formats (MIDI, audio, engraving source)

1.4 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Term	Definition
Score	A complete musical work in MRS-S format
Player	A performer who may play multiple instruments
Instrument	A specific sound source with fixed transposition and range
Staff	A visual grouping of five lines; instruments may have multiple staves
Voice	An independent melodic/rhythmic stream within a staff
Measure	A metrical unit bounded by barlines, identified by UUID
Event	An atomic musical occurrence (note, rest, chord), identified by UUID
Span	A relation connecting multiple events (slur, beam, hairpin)
MRS-S	The canonical storage format (S-expression based)
MRS-Ops	The typed operation protocol for agent mutations
Working Set	A bounded MRS-S fragment with task-adaptive context
Orchestrator	System that owns canonical state and applies validated operations

2. Design Principles

2.1 Separation of Concerns: Storage vs Mutation

MRS uses different representations optimized for different purposes:

Concern	Format	Optimized For
Storage, interchange, archival	MRS-S	Completeness, human readability, validation
Agent output, mutations	MRS-Ops	Reliability, minimal surface, explicit intent

Rationale: Asking agents to emit complete, valid score fragments creates high failure rates. Typed operations with orchestrator-derived fields eliminate entire error classes.

2.2 Orchestrator Authority

The orchestrator is the sole authority for:

UUID minting (agents use temporary IDs)
Derived field computation (:at, :beat-start, :sec-start)
Canonical state management
Validation and application of changes

Rationale: Centralized authority eliminates coordination failures. Agents cannot create invalid references or miscalculate derived fields.

2.3 Stable Identity Over Positional Reference

Every measure, event, and span carries a stable UUIDv7 identifier. Measure numbers are display properties for human navigation, not structural identity. Rationale: Positional references break when content is inserted or deleted. UUID references survive structural changes.

2.4 Progressive Validation

Operations are validated in stages before application:

Syntax: Operation is well-formed
References: All referenced IDs exist (or are valid tmp-ids)
Permissions: Operation is within granted lanes/scope
Musical rules: Content satisfies constraints
Application: State mutation (guaranteed to succeed after validation)

Rationale: Errors caught before state mutation enable specific feedback and partial acceptance.

2.5 Task-Adaptive Context

Agents receive context views tailored to their specific task, not fixed “near/far” rings. Context is information needed to make correct decisions, not just nearby measures. Rationale: Fixed rings may include irrelevant content and omit critical content. Task-adaptive views provide what’s actually needed.

2.6 Professional Orchestration Semantics

The Player → Instrument → Staff model supports:

Instrument doubling (Flute 2 / Piccolo)
Mid-score instrument changes
Transposition handling across changes
Percussion kits
Condensing and divisi

Rationale: Arrangers and orchestrators work with players and instrument changes constantly. This is not an edge case.

3. Architecture Overview

3.1 System Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         MRS ARCHITECTURE                                 │
│                                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                      SEMANTIC MODEL                                │  │
│  │   Players → Instruments → Staves                                   │  │
│  │   Measures → Events (notes, rests, chords)                         │  │
│  │   Spans (slurs, ties, beams, hairpins)                             │  │
│  │   Analytical Overlays                                              │  │
│  │   Structural Index                                                 │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                      │                         │                         │
│             ┌────────┴────────┐       ┌────────┴────────┐               │
│             │     MRS-S       │       │    MRS-Ops      │               │
│             │   (storage,     │       │   (mutation,    │               │
│             │    reading)     │       │    writing)     │               │
│             └─────────────────┘       └─────────────────┘               │
│                                               │                          │
│  ┌────────────────────────────────────────────┴─────────────────────┐   │
│  │                       ORCHESTRATOR                                │   │
│  │                                                                   │   │
│  │   • UUID minting (tmp-id → UUID mapping)                         │   │
│  │   • Derived field computation (:at, :beat-start)                 │   │
│  │   • Progressive validation pipeline                              │   │
│  │   • Task-adaptive context generation                             │   │
│  │   • Lane bundle management                                       │   │
│  │   • Changeset audit trail                                        │   │
│  └───────────────────────────────────────────────────────────────────┘   │
│                      │                                                   │
│  ┌───────────────────┴───────────────────────────────────────────────┐  │
│  │                  WORKING SET ENVELOPE                              │  │
│  │                                                                    │  │
│  │   :content (MRS-S fragment — agent reads this)                    │  │
│  │   :context-views (task-adaptive, queryable)                       │  │
│  │   :structural-index-ref (global awareness)                        │  │
│  │   :bundle (lane permissions for task type)                        │  │
│  │   :available-queries (what agent can request)                     │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

3.2 Data Flow

1. EXTRACTION
   Orchestrator creates Working Set Envelope:
   - Extracts MRS-S fragment for scope
   - Generates task-adaptive context views
   - Grants lane bundle permissions
   - Includes structural index reference

2. AGENT PROCESSING
   Agent receives Working Set Envelope:
   - Reads MRS-S content + context views
   - Produces MRS-Ops (typed operations)
   - Uses tmp-ids for new objects

3. VALIDATION (Progressive)
   Orchestrator validates operations:
   - Syntax validation
   - Reference validation (tmp-ids and UUIDs)
   - Permission validation (lanes, scope)
   - Musical rule validation

4. APPLICATION
   Orchestrator applies validated operations:
   - Maps tmp-ids to UUIDs
   - Computes derived fields
   - Updates canonical score state (and can export MRS-S)
   - Records audit trail

5. RESPONSE
   Orchestrator returns result:
   - Success with applied changes
   - Or rejection with specific errors

3.3 The Scale Problem

Score Type	Parts	Measures	Events	MRS-S Size	Tokens
Lead sheet	1	32	~200	~8 KB	~2K
Piano sonata	2	300	~5,000	~150 KB	~40K
String quartet	4	400	~8,000	~250 KB	~65K
Chamber orchestra	25	500	~50,000	~1.5 MB	~400K
Full orchestra	90	1000	~200,000	~6 MB	~1.5M

No context window can hold a full orchestral score. MRS solves this through bounded extraction with task-adaptive context.

4. MRS-S: The Canonical Storage Format

MRS-S is an S-expression format optimized for complete semantic fidelity, human readability, and archival quality.

4.1 Document Structure

(mrs-s 1.0
  (meta <metadata>)
  (players <player-definitions>)
  (instruments <instrument-definitions>)
  (measures <measure-content>)           ; OR (movements <movement-content>)
  (spans <span-definitions>)
  (overlays <overlay-content>)           ; OPTIONAL
  (structural-index <index-content>)     ; OPTIONAL (can be computed)
  (alternatives <alt-content>)           ; OPTIONAL
  (layout <layout-hints>))               ; OPTIONAL

All top-level sections except overlays, alternatives, and layout are REQUIRED. Sections MUST appear in the order shown.

4.2 Version Declaration

(mrs-s 1.0
  ...)

The version number follows semantic versioning (MAJOR.MINOR). Parsers MUST reject documents with unsupported major versions.

4.3 Metadata Section

(meta
  :title "Symphony No. 5 in C Minor"
  :subtitle "Fate Knocking at the Door"
  :composers ["Ludwig van Beethoven"]
  :arrangers []
  :copyright "Public Domain"
  :created "1808"
  :modified "2026-01-17T10:30:00Z"
  
  ; Score-wide defaults
  :key C :mode minor
  :time 2/4
  :tempo 108
  :tempo-text "Allegro con brio")

Required Metadata Fields

Field	Type	Description
`:title`	string	Primary title of the work

Optional Metadata Fields

Field	Type	Description
`:subtitle`	string	Secondary title
`:composers`	[string]	List of composer names
`:arrangers`	[string]	List of arranger names
`:copyright`	string	Copyright notice
`:key`	pitch-class	Default key (A-G with optional #/b)
`:mode`	keyword	`major`, `minor`, `dorian`, etc.
`:time`	fraction	Default time signature
`:tempo`	integer	Default tempo in BPM
`:tempo-text`	string	Tempo marking text

4.4 Measures Section

(measures
  (measure 
    :id #uuid "018c3f40-0001-7890-abcd-ef1234567890"
    :number 1
    :beat-start 0
    :time 4/4
    :key C :mode minor
    :tempo 120
    
    (flute-1
      (v1
        (: 0 C5.q :id #uuid "018c3f2a-0001-...")
        (: 1 D5.q :id #uuid "018c3f2a-0002-...")
        (: 2 E5.h :id #uuid "018c3f2a-0003-...")))
    
    (clarinet-bb
      (v1
        (: 0 r.w :id #uuid "018c3f2a-0010-...")))))

Measure Attributes

Attribute	Required	Type	Description
`:id`	YES	UUIDv7	Stable identifier
`:number`	YES	integer	Display number (can have gaps)
`:beat-start`	YES	rational	Absolute beat position (orchestrator-computed)
`:time`	NO	fraction	Time signature (inherits if omitted)
`:key`	NO	pitch-class	Key signature (inherits if omitted)
`:tempo`	NO	integer	Tempo in BPM (inherits if omitted)

4.5 Event Syntax

(: <beat> <pitch-expr> :id <uuid> <properties>*)

Component	Description
`:`	Event marker
`<beat>`	Beat position within measure (0-indexed, exact rational)
`<pitch-expr>`	Pitch with duration, chord, or rest
`:id`	Stable UUIDv7 identifier (REQUIRED)
`<properties>`	Optional `:keyword value` pairs

Note: The :at field (absolute position) is NOT required in storage. It is computed by the orchestrator when needed:

event.:at = measure.:beat-start + event.beat

This eliminates a class of calculation errors and reduces storage size.

Pitch Expression

C4.q        ; C4 quarter note
Eb5.h       ; E-flat 5 half note
F#3.e       ; F-sharp 3 eighth note
[C4 E4 G4].q  ; C major triad, quarter note
r.q         ; Quarter rest

Duration Codes

Code	Name	Beats
`w`	Whole	4
`h`	Half	2
`q`	Quarter	1
`e`	Eighth	1/2
`s`	Sixteenth	1/4
`t`	Thirty-second	1/8

Dotted: append . (e.g., q. = 3/2 beats) Double-dotted: append .. (e.g., q.. = 7/4 beats)

Rational Beat Positions

Beat positions MUST be exact rationals. The canonical form is:

0           ; Integer
1           ; Integer  
2+1/2       ; Mixed number (two and a half)
0+1/3       ; Fraction (one third)
3+3/4       ; Mixed number (three and three quarters)

Decimal literals (e.g., 2.5) are NOT permitted.

Event Properties

(: 0 G4.q 
  :id #uuid "018c3f2a-..."
  :dyn ff
  :art staccato
  :orn trill
  :tech pizz
  :lyrics [{:text "Hal-" :syllabic begin}])

Property	Type	Description
`:dyn`	keyword	Dynamic marking
`:art`	keyword	Articulation
`:orn`	keyword	Ornament
`:tech`	keyword	Playing technique
`:lyrics`	list	Lyric syllables
`:grace`	boolean	Grace note flag
`:cue`	boolean	Cue note flag
`:cue-source`	instrument-id	Source instrument for cue

4.6 Spans Section

Spans define relationships between events across time.

(spans
  (slur
    :id #uuid "018c3f2c-0001-..."
    :from #uuid "018c3f2a-0001-..."
    :to #uuid "018c3f2a-0004-...")
  
  (hairpin
    :id #uuid "018c3f2c-0002-..."
    :type crescendo
    :from #uuid "018c3f2a-0001-..."
    :to #uuid "018c3f2a-0008-...")
  
  (beam
    :id #uuid "018c3f2c-0003-..."
    :events [#uuid "018c3f2a-0005-..." 
             #uuid "018c3f2a-0006-..."
             #uuid "018c3f2a-0007-..."]))

Span Types

Type	Endpoint Style	Description
`slur`	from/to	Phrasing slur
`tie`	from/to	Tie between same pitches
`hairpin`	from/to	Crescendo/diminuendo
`beam`	events list	Beam grouping
`ottava`	from/to	Octave transposition
`pedal`	from/to	Piano pedal
`trill-span`	from/to	Extended trill
`gliss`	from/to	Glissando line
`volta`	from/to	Ending bracket

4.7 Tuplet Syntax

(tuplet 3:2 q
  (: 0 C4.e :id #uuid "...")
  (: 0+1/3 D4.e :id #uuid "...")
  (: 0+2/3 E4.e :id #uuid "..."))

4.8 Grace Notes

(grace :type acciaccatura
  (: 0 D5.s :id #uuid "..."))

; Main note that grace attaches to
(: 0 C5.q :id #uuid "...")

4.9 Directions

(measure :id #uuid "..." :number 45
  (dir :type tempo :beat 0 :text "Più mosso" :tempo 132)
  (dir :type dynamic :beat 0 :text "ff" :scope all)
  (dir :type rehearsal :beat 0 :text "B")
  (dir :type text :beat 2 :text "poco rit." :placement above)
  (dir :type segno :beat 0)
  (dir :type coda :beat 0)
  
  (flute-1 ...))

4.10 Movements

(movements
  (movement 1 :title "Allegro" :key C :mode major :time 4/4
    (measures ...))
  (movement 2 :title "Adagio" :key F :mode major :time 3/4
    (measures ...)))

4.11 Alternatives (Ossia, Variants)

(alternatives
  (ossia
    :measures [#uuid "..." #uuid "..."]
    :instrument flute-1
    :label "easier version"
    :content (measures ...))
  (variant
    :measures [#uuid "..."]
    :label "manuscript variant"
    :content ...))

4.12 Layout Hints (Optional)

Layout hints are NON-NORMATIVE suggestions for rendering engines.

(layout
  :bar-numbers (every 5)
  
  (break :type system :after #uuid "018c3f40-0008-...")
  (break :type page :after #uuid "018c3f40-0020-...")
  
  (hide-empty-staves true)
  
  (condense 
    :instruments [flute-1 flute-2]
    :measures [#uuid "..." #uuid "..."]
    :label "Fl. 1, 2"))

5. MRS-Ops: The Mutation Protocol

MRS-Ops is the typed operation protocol for agent mutations. Agents read MRS-S but write MRS-Ops.

5.1 Design Rationale

Asking agents to emit complete MRS-S fragments creates failure modes:

Accidental omission: Agent returns less content than given → content 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:

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

5.2 Operation Envelope

(mrs-ops
  :version 1.0
  :scope-hash "sha256:a3f2c1b9e4d7..."
  :base-revision "rev:abc123"
  
  :ops
    (<operation>
     <operation>
     ...))

Field	Required	Description
`:version`	YES	Protocol version
`:scope-hash`	YES	Hash of source Working Set (conflict detection)
`:base-revision`	NO	Revision ID of source state
`:ops`	YES	List of operations

5.3 Operation Types

5.3.1 Create Event

(create-event
  :tmp-id "e1"
  :measure #uuid "018c3f40-002d-..."
  :instrument flute-1
  :voice v1
  :beat 0
  :pitch C5
  :duration q
  :dyn mp
  :art staccato)

Field	Required	Description
`:tmp-id`	YES	Temporary ID (orchestrator maps to UUID)
`:measure`	YES	Target measure UUID
`:instrument`	YES	Target instrument ID
`:voice`	YES	Target voice
`:beat`	YES	Beat position (rational)
`:pitch`	YES	Pitch or chord or `r` for rest
`:duration`	YES	Duration code
Other properties	NO	`:dyn`, `:art`, `:orn`, etc.

5.3.2 Update Event

(update-event
  :id #uuid "018c3f2a-0001-..."
  :set
    ((:pitch D5)
     (:dyn f)))

Field	Required	Description
`:id`	YES	Existing event UUID
`:set`	YES	List of (field value) pairs to update

5.3.3 Delete Event

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

5.3.4 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"

5.3.5 Update Span

(update-span
  :id #uuid "018c3f2c-0001-..."
  :set
    ((:style legato)))

Note: Span endpoints (:from, :to, :events) are immutable after creation. To change endpoints, delete and recreate the span.

5.3.6 Delete Span

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

5.3.7 Create Measure

(create-measure
  :tmp-id "m1"
  :after #uuid "018c3f40-0030-..."   ; Insert after this measure
  :time 4/4
  :key C :mode minor)

The orchestrator:

Assigns UUID and :number
Computes :beat-start based on position
Updates subsequent measures if needed

5.3.8 Delete Measure

(delete-measure
  :id #uuid "018c3f40-0030-...")

Warning: Deleting a measure deletes all events within it. Spans with endpoints in the deleted measure become invalid.

5.3.9 Instrument Change

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

5.4 Temporary ID Rules

Temporary IDs MUST be strings starting with a letter: "e1", "span-a", "m1"
Temporary IDs are scoped to a single MRS-Ops envelope
Operations within the same envelope MAY reference each other’s tmp-ids
The orchestrator maps all tmp-ids to UUIDs before application
Responses include the tmp-id → UUID mapping

5.5 Operation Ordering

Operations are applied in order. Dependencies must be respected:

Create measure before creating events in it
Create events before creating spans that reference them

The orchestrator MAY reorder operations to satisfy dependencies if unambiguous.

5.6 Example: Add Countermelody

Agent receives Working Set with clarinet part (empty) and violin melody (in context). Agent returns:

(mrs-ops
  :version 1.0
  :scope-hash "sha256:a3f2c1b9e4d7..."
  
  :ops
    ((create-event :tmp-id "e1" :measure #uuid "018c3f40-002d-..." 
                   :instrument clarinet-bb :voice v1
                   :beat 0 :pitch Eb4 :duration q :dyn mp)
     (create-event :tmp-id "e2" :measure #uuid "018c3f40-002d-..."
                   :instrument clarinet-bb :voice v1
                   :beat 1 :pitch D4 :duration q)
     (create-event :tmp-id "e3" :measure #uuid "018c3f40-002d-..."
                   :instrument clarinet-bb :voice v1
                   :beat 2 :pitch Eb4 :duration e)
     (create-event :tmp-id "e4" :measure #uuid "018c3f40-002d-..."
                   :instrument clarinet-bb :voice v1
                   :beat 2+1/2 :pitch F4 :duration e)
     (create-event :tmp-id "e5" :measure #uuid "018c3f40-002d-..."
                   :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")

6. Players, Instruments, and Staves

MRS uses a three-level model for professional orchestration semantics.

6.1 The Model

Player (performer)
  └── Instruments (what they can play)
        └── Staves (visual representation)

Player: A human performer. May play multiple instruments (doubling). Instrument: A specific sound source with fixed transposition, range, and technique set. Staff: Visual representation. An instrument may use multiple staves (piano) or share a staff (condensed scores).

6.2 Players Section

(players
  (player woodwind-2
    :name "Flute 2 / Piccolo"
    :instruments [flute-2 piccolo]
    :default flute-2)
  
  (player clarinet-1
    :name "Clarinet 1"
    :instruments [clarinet-bb clarinet-a]
    :default clarinet-bb)
  
  (player percussion-1
    :name "Percussion 1"
    :instruments [snare timpani triangle]
    :default snare))

Attribute	Required	Description
`:name`	YES	Display name
`:instruments`	YES	List of instrument IDs this player uses
`:default`	YES	Default/starting instrument

6.3 Instruments Section

(instruments
  (instrument flute-1
    :name "Flute"
    :abbr "Fl. 1"
    :family woodwinds
    :staves [treble]
    :transposition none
    :range [C4 D7])
  
  (instrument piccolo
    :name "Piccolo"
    :abbr "Picc."
    :family woodwinds
    :staves [treble]
    :transposition (up P8)
    :range [D5 C8])
  
  (instrument clarinet-bb
    :name "Clarinet in Bb"
    :abbr "Cl."
    :family woodwinds
    :staves [treble]
    :transposition (down M2)
    :range [E3 C7])
  
  (instrument clarinet-a
    :name "Clarinet in A"
    :abbr "Cl."
    :family woodwinds
    :staves [treble]
    :transposition (down m3)
    :range [Eb3 B6])
  
  (instrument piano
    :name "Piano"
    :abbr "Pno."
    :family keyboards
    :staves [treble bass]
    :transposition none
    :range [A0 C8]
    :staff-connect brace))

Attribute	Required	Description
`:name`	YES	Full display name
`:abbr`	YES	Abbreviated name
`:family`	YES	Instrument family
`:staves`	YES	List of staff clefs
`:transposition`	YES	Transposition interval or `none`
`:range`	NO	Playable range [low high]
`:staff-connect`	NO	`brace`, `bracket`, `line`

6.4 Transposition Specification

none                  ; Concert pitch
(up P8)               ; Sounds octave higher (piccolo)
(down M2)             ; Sounds major 2nd lower (Bb clarinet)
(down m3)             ; Sounds minor 3rd lower (A clarinet)
(down P5)             ; Sounds perfect 5th lower (English horn)

6.5 Instrument Changes

When a player switches instruments mid-score:

(measure :id #uuid "..." :number 45
  (woodwind-2
    (instrument-change :to piccolo :beat 0)
    (v1
      (: 0 D6.q :id #uuid "...")
      ...)))

The orchestrator:

Validates the player owns the target instrument
Handles transposition changes automatically
Updates display (instrument name in score)

6.6 Percussion Kits

(instrument snare-kit
  :name "Snare Drum Kit"
  :abbr "S.D."
  :family percussion
  :staves [percussion]
  :transposition none
  :kit
    ((snare :line 0 :notehead normal)
     (rim :line 0 :notehead x)
     (stick :line 2 :notehead x)))

(instrument drum-kit
  :name "Drum Kit"
  :abbr "Dr."
  :family percussion
  :staves [percussion]
  :transposition none
  :kit
    ((kick :line -2 :notehead normal)
     (snare :line 0 :notehead normal)
     (hi-hat :line 2 :notehead x)
     (crash :line 4 :notehead x-circle)))

6.7 Referencing in Measures

In measure content, use instrument ID (not player ID):

(measure :id #uuid "..." :number 1
  (flute-1
    (v1 (: 0 C5.q :id #uuid "...")))
  
  (piccolo    ; After instrument change
    (v1 (: 0 D6.q :id #uuid "...")))
  
  (piano
    (:rh (v1 (: 0 [C4 E4 G4].q :id #uuid "...")))
    (:lh (v1 (: 0 C3.q :id #uuid "...")))))

7. Working Set Envelope

The Working Set Envelope provides agents with bounded MRS-S content plus task-appropriate context.

7.1 Envelope Structure

(working-set
  :version 1.0
  :source-hash "sha256:a3f2c1b9e4d7..."
  
  :scope
    (:measures #uuid "018c3f40-002d-..." #uuid "018c3f40-0034-...")
    (:instruments [clarinet-bb])
    (:voices [v1])
  :display-hint (:measures 45 52)
  
  :bundle orchestrate
  :allowed-ops [create-event update-event delete-event create-span delete-span]
  
  :task "Add clarinet countermelody responding to violin theme"
  
  :constraints
    ((range clarinet-bb E3 C7)
     (avoid parallel-fifths violin-1))
  
  :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-002d-..."
        :number 45
        :beat-start 487
        (clarinet-bb
          (v1))))  ; Empty — target for agent
    
    (spans)
  
  :context-views
    <task-adaptive-context>
  
  :structural-index-ref "sha256:abc123..."
  
  :available-queries
    [:melodic-content :harmonic-analysis :orchestration-density])

7.2 Envelope Fields

Required Fields

Field	Type	Description
`:version`	decimal	Envelope version (1.0)
`:source-hash`	string	SHA-256 hash of source state
`:scope`	scope-spec	What the agent may modify
`:content`	MRS-S	The score fragment (readable, target of ops)

Scope Specification

:scope
  (:measures #uuid "..." #uuid "...")   ; UUID range (inclusive)
  (:instruments [clarinet-bb flute-1])  ; Instruments included
  (:voices [v1 v2])                     ; Optional: specific voices
:display-hint (:measures 45 52)         ; Human-readable, informational

Scope uses UUIDs for structural stability. Display hints are for human orientation only.

Permission Fields

Field	Description
`:bundle`	Lane bundle granting permissions
`:allowed-ops`	Explicit list of permitted operation types

Optional Fields

Field	Type	Description
`:task`	string	Natural language task description
`:constraints`	list	Validation rules agent must satisfy
`:context-views`	list	Task-adaptive context (see §8)
`:structural-index-ref`	string	Hash reference to structural index
`:available-queries`	list	Queries agent may request

7.3 Content Self-Containment

The :content of a Working Set Envelope MUST be parseable as standalone MRS-S:

Instrument definitions MUST be included
Time/key/tempo state at extraction start MUST be declared
Spans MUST have both endpoints within scope OR be marked with boundary markers

7.4 Boundary-Crossing Spans

When a span crosses the envelope boundary:

(slur
  :id #uuid "018c3f2c-..."
  :from #uuid "018c3f2a-..."    ; Inside scope
  :to #uuid "018c3f2b-..."      ; Outside scope
  :boundary-exit true)          ; Marks endpoint outside

Boundary-marked spans are read-only at their boundary endpoints. Agents MAY NOT modify :from, :to, or :events of boundary-marked spans.

8. Task-Adaptive Context Views

Context views provide task-relevant information beyond the edit scope. Unlike fixed “near/far” rings, views are selected and shaped for the specific task.

8.1 Design Rationale

Different tasks need different context:

Countermelody: The melody being responded to, harmonic rhythm
Orchestration: What other instruments are playing, texture density
Dynamics: Phrase structure, existing dynamics, climax points
Slur shaping: Articulation context, phrase groupings

Fixed rings waste tokens on irrelevant content and may omit critical content. Task-adaptive views provide what’s actually needed.

8.2 Context View Types

8.2.1 Melodic Reference

Provides the melody line(s) the agent should respond to:

(context-view melodic-reference
  :instruments [violin-1]
  :measures #uuid "018c3f40-002d-..." #uuid "018c3f40-0034-..."
  :reduction melody-only
  :content
    (measures
      (measure :id #uuid "..." :number 45
        (violin-1
          (v1
            (: 0 G5.q :id #uuid "...")
            (: 1 A5.e :id #uuid "...")
            ...)))))

8.2.2 Harmonic Context

Provides harmonic information (chord symbols, key areas):

(context-view harmonic-context
  :measures #uuid "018c3f40-002d-..." #uuid "018c3f40-0034-..."
  :content
    (harmony-events
      (chord :measure #uuid "..." :beat 0 :symbol Cm :function i)
      (chord :measure #uuid "..." :beat 2 :symbol Fm :function iv)
      (chord :measure #uuid "..." :beat 0 :symbol G7 :function V7)))

8.2.3 Orchestration Map

Shows what instruments are active and their texture:

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

8.2.4 Phrase Structure

Provides phrase boundaries and form:

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

8.2.5 Dynamics Profile

Provides dynamics trajectory:

(context-view dynamics-profile
  :measures #uuid "..." #uuid "..."
  :content
    (dynamics-arc
      (point :measure #uuid "..." :beat 0 :level p)
      (point :measure #uuid "..." :beat 0 :level f)
      (point :measure #uuid "..." :beat 0 :level pp)))

8.2.6 Thematic References

Provides motif/theme information:

(context-view thematic-references
  :content
    (themes
      (theme :id theme-a :label "Main theme"
             :exemplar #uuid "018c3f40-0001-..."
             :occurrences [#uuid "..." #uuid "..." #uuid "..."])
      (theme :id theme-b :label "Second theme"
             :exemplar #uuid "018c3f40-0020-...")))

8.3 View Selection by Task Type

The orchestrator selects context views based on task type:

Task Type	Typical Context Views
`compose`	phrase-structure, harmonic-context, thematic-references
`countermelody`	melodic-reference, harmonic-context, phrase-structure
`orchestrate`	orchestration-map, dynamics-profile, melodic-reference
`harmonize`	melodic-reference, phrase-structure
`dynamics`	phrase-structure, dynamics-profile, orchestration-map
`articulate`	phrase-structure, melodic-reference

8.4 Available Queries

Agents may request additional context via queries:

:available-queries
  [:melodic-content    ; Request melody from specific instruments
   :harmonic-analysis  ; Request harmony analysis
   :orchestration-density ; Request texture information
   :phrase-boundaries  ; Request phrase structure
   :thematic-occurrences] ; Request theme locations

Query request (in agent response):

(query-request
  :type melodic-content
  :instruments [oboe-1]
  :measures #uuid "..." #uuid "..."
  :reason "Need oboe line to avoid doubling")

The orchestrator may grant or deny queries based on scope and permissions.

9. Structural Index

The Structural Index provides global awareness without loading the full score.

9.1 Index Structure

(structural-index
  :hash "sha256:abc123..."
  :source-hash "sha256:def456..."
  
  :form
    (sections
      (section :type exposition :measures #uuid "..." #uuid "..." :display [1 64])
      (section :type development :measures #uuid "..." #uuid "..." :display [65 120])
      (section :type recapitulation :measures #uuid "..." #uuid "..." :display [121 180]))
  
  :key-areas
    ((region :key C :mode minor :measures #uuid "..." #uuid "...")
     (region :key Eb :mode major :measures #uuid "..." #uuid "...")
     (region :key G :mode minor :measures #uuid "..." #uuid "..."))
  
  :tempo-map
    ((tempo :bpm 120 :measures #uuid "..." #uuid "...")
     (tempo :bpm 80 :text "Adagio" :measures #uuid "..." #uuid "..."))
  
  :players-summary
    ((player woodwind-2 :instruments [flute-2 piccolo] :active-measures [...])
     (player clarinet-1 :instruments [clarinet-bb] :active-measures [...]))
  
  :rehearsal-marks
    ((mark "A" :measure #uuid "..." :number 16)
     (mark "B" :measure #uuid "..." :number 32))
  
  :total-measures 180
  :total-duration "12:34")

9.2 Index Fields

Field	Description
`:form`	Structural sections (exposition, development, etc.)
`:key-areas`	Key signature regions
`:tempo-map`	Tempo changes
`:players-summary`	Players and their activity
`:rehearsal-marks`	Rehearsal mark locations
`:total-measures`	Total measure count
`:total-duration`	Approximate duration

9.3 Index Derivation

The structural index can be:

Derived automatically from the score (partial)
Enhanced by overlays (harmonic analysis, thematic analysis)
Manually annotated (form labels, section names)

10. Analytical Overlays

Overlays attach analytical metadata to score regions without modifying the score itself.

10.1 Overlay Structure

(overlays
  (overlay :id harmonic-analysis
    :type harmonic
    :author "harmony-agent"
    :created "2026-01-17T10:30:00Z"
    
    :regions
      ((region :measures #uuid "..." #uuid "..."
               :content
                 (chord :beat 0 :symbol Cm :function i)
                 (chord :beat 2 :symbol Fm :function iv))))
  
  (overlay :id motivic-analysis
    :type thematic
    :author "analysis-agent"
    
    :themes
      ((theme :id theme-a :label "Main theme"
              :first-occurrence #uuid "..."
              :characteristics "descending fourth, dotted rhythm"))))

10.2 Overlay Types

Type	Purpose
`harmonic`	Chord symbols, Roman numerals, functions
`thematic`	Motifs, themes, their occurrences
`form`	Structural analysis (phrase, period, section)
`voice-leading`	Part writing analysis
`performance`	Performance annotations

10.3 Overlay Lifecycle

Overlays may be:

Persistent: Stored with the score
Session: Valid only for current editing session
Derived: Recomputed after score changes

11. Data Model

11.1 Core Types

Score
├── meta: Metadata
├── players: List<Player>
├── instruments: List<Instrument>
├── measures: List<Measure>
├── spans: List<Span>
├── overlays: List<Overlay>?
├── structural-index: StructuralIndex?
└── alternatives: List<Alternative>?

Player
├── id: Identifier
├── name: String
├── instruments: List<InstrumentId>
└── default: InstrumentId

Instrument
├── id: Identifier
├── name: String
├── abbr: String
├── family: InstrumentFamily
├── staves: List<Clef>
├── transposition: Interval | none
├── range: [Pitch, Pitch]?
└── kit: List<KitItem>?  (percussion only)

Measure
├── id: UUIDv7
├── number: Integer
├── beat-start: Rational  (orchestrator-computed)
├── time: TimeSignature?
├── key: PitchClass?
├── mode: Mode?
├── tempo: Integer?
├── tempo-text: String?
├── rehearsal: String?
├── barline-left: BarlineType?
├── barline-right: BarlineType?
├── directions: List<Direction>
└── content: Map<InstrumentId, InstrumentContent>

Event
├── beat: Rational
├── pitch: PitchExpr
├── id: UUIDv7
├── dyn: Dynamic?
├── art: Articulation?
├── orn: Ornament?
├── tech: Technique?
├── lyrics: List<LyricSyllable>?
└── ...other properties

Span
├── id: UUIDv7
├── type: SpanType
├── from: UUIDv7?
├── to: UUIDv7?
├── events: List<UUIDv7>?
├── boundary-entry: Boolean?
├── boundary-exit: Boolean?
└── ...type-specific attributes

11.2 Identifier Rules

UUIDs: All measures, events, and spans carry UUIDv7 identifiers under :id
Instrument IDs: Match regex [a-z][a-z0-9-]* (e.g., flute-1, clarinet-bb)
Player IDs: Match regex [a-z][a-z0-9-]* (e.g., woodwind-2, percussion-1)
Voice IDs: v1 through v4, or :rh/:lh for keyboard
Temporary IDs: Strings starting with letter, scoped to operation envelope

11.3 Immutability Rules

Once assigned:

:id is immutable for the lifetime of the object
Span endpoints (:from, :to, :events) are immutable
Measure :beat-start is orchestrator-managed (not directly editable)

11.4 Rational Number Representation

All temporal positions use exact rationals:

Canonical forms:
  0, 1, 2, ...       (integers)
  2+1/2              (two and a half)
  0+1/3              (one third)
  3+3/4              (three and three quarters)

NOT permitted:
  2.5                (decimal)
  0.333              (decimal)

Implementations MUST treat rationals as exact; no floating-point approximation.

12. Orchestrator Contract

The orchestrator is the central coordinator that makes AI-assisted composition and orchestration safe and reliable.

12.1 Orchestrator Responsibilities

Responsibility	Description
UUID minting	Maps tmp-ids to UUIDs; sole authority for ID creation
Derived fields	Computes `:beat-start`, reconciles inherited state
Validation	Progressive validation of all operations
State management	Maintains canonical score state; 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

12.2 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

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

12.4 Conflict Detection

The orchestrator uses source-hash to detect conflicts:

Working Set created with source-hash H1
Agent produces operations
Before applying, orchestrator checks current hash
If current hash ≠ H1, conflict detected
Options: reject, rebase, merge (policy-dependent)

12.5 Transaction Model

(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)

All changes are recorded in an append-only transaction log.

12.6 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.

13. Progressive Validation

Operations are validated in stages before application.

13.1 Validation Pipeline

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Syntax    │ → │ References  │ → │ Permissions │ → │  Musical    │
│ Validation  │   │ Validation  │   │ Validation  │   │  Rules      │
└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘
                                                              │
                                                              ▼
                                                      ┌─────────────┐
                                                      │ Application │
                                                      └─────────────┘

13.2 Validation Stages

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, etc.)
Duration sums correct
Ties connect same pitches

13.3 Validation Results

(validation-result
  :status rejected
  :stage permissions
  :errors
    ((error :op 3 :code PERM-001 
            :message "Operation modifies 'structure' lane, not granted"
            :detail (:op-type create-measure :granted-lanes [notes expression]))))

13.4 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 'e99'")))

The orchestrator MAY apply valid operations and reject invalid ones, or reject the entire batch (configurable policy).

13.5 Validation Rules

Structural Rules

Rule	Severity	Description
STRUCT-001	ERROR	Duplicate UUIDs
STRUCT-002	ERROR	Invalid measure numbers
STRUCT-003	ERROR	Beat position out of bounds
STRUCT-004	ERROR	Reference to non-existent UUID
STRUCT-005	WARNING	Gap in measure numbering

Musical Rules

Rule	Severity	Description
MUSIC-001	ERROR	Tie connects different pitches
MUSIC-002	ERROR	Duration overflow (exceeds measure)
MUSIC-003	WARNING	Pitch out of instrument range
MUSIC-004	WARNING	Parallel fifths/octaves
MUSIC-005	WARNING	Voice crossing

Permission Rules

Rule	Severity	Description
PERM-001	ERROR	Operation outside granted lanes
PERM-002	ERROR	Operation outside granted scope
PERM-003	ERROR	Operation type not allowed
PERM-004	ERROR	Modifying locked lane

14. Query Resolution

The orchestrator translates human-friendly references to UUIDs.

14.1 Query Types

Measure number resolution:

(query :type resolve :human-ref (:measure-number 45)
       :response (:id #uuid "018c3f40-002d-..." :number 45))

Rehearsal mark resolution:

(query :type resolve :human-ref (:rehearsal "B")
       :response (:id #uuid "018c3f40-0020-..." :number 32))

Rehearsal mark with offset:

(query :type resolve :human-ref (:rehearsal "B" :offset 4)
       :response (:id #uuid "018c3f40-0024-..." :number 36))

Range resolution:

(query :type resolve-range :human-ref (:measures 45 52)
       :response (:from #uuid "018c3f40-002d-..." :to #uuid "018c3f40-0034-..."))

14.2 Reverse Resolution

UUID to display information:

(query :type display-info :id #uuid "018c3f40-002d-..."
       :response (:number 45 :rehearsal "C" :beat-start 487))

15. Extension Mechanisms

15.1 Custom Properties

Events, spans, and directions support custom properties with x- prefix:

(: 0 C4.q 
  :id #uuid "..."
  :dyn f
  :x-source "manuscript-page-47"
  :x-confidence 0.85)

15.2 Namespace Extensions

(: 0 C4.q
  :id #uuid "..."
  :analysis:roman-numeral "I"
  :analysis:function "tonic"
  :mei:xml-id "note-001")

Namespace	Purpose
`x-*`	Unregistered extensions
`analysis:*`	Music theory analysis
`mei:*`	MEI compatibility
`midi:*`	MIDI-specific data
`render:*`	Rendering hints
`edit:*`	Editorial metadata

16. MIME Types and File Extensions

16.1 MIME Types

Format	MIME Type
MRS-S	`application/vnd.mrs+sexpr`
MRS-Ops	`application/vnd.mrs-ops+sexpr`
Working Set Envelope	`application/vnd.mrs-workset+sexpr`

16.2 File Extensions

Format	Extension
MRS-S	`.mrs` or `.mrs-s`
MRS-Ops	`.mrs-ops` (typically ephemeral)
Working Set	`.mrs-workset` (typically ephemeral)

16.3 Encoding

MRS documents MUST be encoded in UTF-8. BOM SHOULD NOT be used.

17. Security Considerations

17.1 Input Validation

Parsers MUST validate:

Maximum document size
Maximum nesting depth
Maximum event count per measure
Valid Unicode in strings

17.2 Denial of Service Protection

Implementations SHOULD protect against:

Deeply nested structures
Very large measure numbers
Excessive span counts
Malformed UTF-8

17.3 Information Disclosure

Working Set Envelopes may expose:

Source document structure
Source document hash
Creator/modifier identity

Implementations SHOULD allow redaction of sensitive metadata.

Appendix A: Complete Grammar

A.1 MRS-S Key Productions

document     <- '(' 'mrs-s' version meta players instruments measures spans 
                overlays? structural-index? alternatives? layout? ')'

meta         <- '(' 'meta' metadata-fields ')'
players      <- '(' 'players' player* ')'
instruments  <- '(' 'instruments' instrument* ')'
measures     <- '(' 'measures' measure* ')' | '(' 'movements' movement* ')'
spans        <- '(' 'spans' span* ')'

player       <- '(' 'player' identifier ':name' STRING ':instruments' '[' identifier* ']' 
                ':default' identifier ')'
instrument   <- '(' 'instrument' identifier instrument-attrs ')'

measure      <- '(' 'measure' ':id' uuid ':number' INT measure-attrs* 
                direction* instrument-content* ')'
event        <- '(' ':' beat pitch-expr ':id' uuid properties* ')'

pitch        <- STEP ACCIDENTAL? OCTAVE '.' DURATION DOTS?
chord        <- '[' pitch+ ']' '.' DURATION DOTS?
rest         <- 'r' '.' DURATION DOTS?

span         <- '(' span-type ':id' uuid span-endpoints attributes* ')'

uuid         <- '#uuid' '"' UUID-STRING '"'
rational     <- INT (('+' INT '/' INT) | ('/' INT))?
beat         <- rational

A.2 MRS-Ops Key Productions

ops-envelope <- '(' 'mrs-ops' ':version' DECIMAL ':scope-hash' STRING 
                ':ops' '(' operation* ')' ')'

operation    <- create-event | update-event | delete-event |
                create-span | update-span | delete-span |
                create-measure | delete-measure |
                instrument-change

create-event <- '(' 'create-event' ':tmp-id' STRING 
                ':measure' uuid ':instrument' identifier ':voice' voice-id
                ':beat' rational ':pitch' pitch-expr ':duration' duration
                properties* ')'

update-event <- '(' 'update-event' ':id' uuid ':set' '(' set-pair* ')' ')'
delete-event <- '(' 'delete-event' ':id' uuid ')'

create-span  <- '(' 'create-span' ':tmp-id' STRING ':type' span-type 
                ':from' ref ':to' ref attributes* ')'

ref          <- uuid | STRING  ; UUID or tmp-id

Appendix B: Quick Reference

B.1 Duration Codes

Code	Name	Beats
`w`	Whole	4
`h`	Half	2
`q`	Quarter	1
`e`	Eighth	1/2
`s`	Sixteenth	1/4
`t`	32nd	1/8
`x`	64th	1/16

B.2 Dynamics

pppp ppp pp p mp mf f ff fff ffff
sfz sfp sffz fz rf rfz fp sf sff

B.3 Articulations

staccato staccatissimo tenuto accent marcato
portato stress fermata breath caesura

B.4 Ornaments

trill mordent mordent-inverted
turn turn-inverted tremolo
arpeggio glissando

B.5 Lane Bundles

Bundle	Lanes
`orchestrate`	notes, expression, technique
`dynamics-pass`	expression
`notation-cleanup`	notes, technique
`full-compose`	structure, temporal, harmonyPlan, notes, expression, technique

B.6 Context View Types

View	Purpose
`melodic-reference`	Melody to respond to
`harmonic-context`	Chord progression
`orchestration-map`	Active instruments, texture
`phrase-structure`	Phrase boundaries
`dynamics-profile`	Dynamics trajectory
`thematic-references`	Themes and motifs

Appendix C: Glossary

Term	Definition
Agent	An AI system that operates on MRS documents
Context View	Task-adaptive information beyond the edit scope
Event	An atomic musical occurrence with UUID identity
Instrument	A specific sound source with fixed transposition/range
Lane	A permission boundary for a category of content
Lane Bundle	A predefined set of lanes for common workflows
Measure	A metrical unit with UUID identity
MRS-Ops	Typed operation protocol for agent mutations
MRS-S	Canonical storage format (S-expression based)
Orchestrator	System that owns canonical state and applies changes
Overlay	Analytical metadata attached to score regions
Player	A performer who may play multiple instruments
Progressive Validation	Multi-stage validation before state mutation
Scope	UUID-based boundaries of a Working Set
Span	A relation connecting multiple events
Structural Index	Compressed global view of the score
Temporary ID	Agent-assigned ID mapped to UUID by orchestrator
Working Set	Bounded MRS-S fragment with task-adaptive context

End of Specification

Spec RFC

​RFC 0001 — Version 1.0

​Abstract

​Table of Contents

​1. Introduction

​1.1 Motivation

​1.2 Goals

​1.3 Non-Goals

​1.4 Terminology

​2. Design Principles

​2.1 Separation of Concerns: Storage vs Mutation

​2.2 Orchestrator Authority

​2.3 Stable Identity Over Positional Reference

​2.4 Progressive Validation

​2.5 Task-Adaptive Context

​2.6 Professional Orchestration Semantics

​3. Architecture Overview

​3.1 System Architecture

​3.2 Data Flow

​3.3 The Scale Problem

​4. MRS-S: The Canonical Storage Format

​4.1 Document Structure

​4.2 Version Declaration

​4.3 Metadata Section

​Required Metadata Fields

​Optional Metadata Fields

​4.4 Measures Section

​Measure Attributes

​4.5 Event Syntax

​Pitch Expression

​Duration Codes

​Rational Beat Positions

​Event Properties

​4.6 Spans Section

​Span Types

​4.7 Tuplet Syntax

​4.8 Grace Notes

​4.9 Directions

​4.10 Movements

​4.11 Alternatives (Ossia, Variants)

​4.12 Layout Hints (Optional)

​5. MRS-Ops: The Mutation Protocol

​5.1 Design Rationale

​5.2 Operation Envelope

​5.3 Operation Types

​5.3.1 Create Event

​5.3.2 Update Event

​5.3.3 Delete Event

​5.3.4 Create Span

​5.3.5 Update Span

​5.3.6 Delete Span

​5.3.7 Create Measure

​5.3.8 Delete Measure

​5.3.9 Instrument Change

​5.4 Temporary ID Rules

​5.5 Operation Ordering

​5.6 Example: Add Countermelody

​6. Players, Instruments, and Staves

​6.1 The Model

​6.2 Players Section

​6.3 Instruments Section

​6.4 Transposition Specification

​6.5 Instrument Changes

​6.6 Percussion Kits

​6.7 Referencing in Measures

​7. Working Set Envelope

​7.1 Envelope Structure

​7.2 Envelope Fields

​Required Fields

​Scope Specification

​Permission Fields

​Optional Fields

​7.3 Content Self-Containment

​7.4 Boundary-Crossing Spans

​8. Task-Adaptive Context Views

​8.1 Design Rationale

​8.2 Context View Types

​8.2.1 Melodic Reference

​8.2.2 Harmonic Context

​8.2.3 Orchestration Map