Agent Operations

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

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

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)

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, e.g., `0`, `2+1/2`)
`:pitch`	YES	Pitch or chord or `r` for rest
`:duration`	YES	Duration code (`q`, `h`, `e`, etc.)
Other properties	NO	`:dyn`, `:art`, `:orn`, `:tech`, etc.

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

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

Tmp-ids MUST be strings starting with a letter: "e1", "span-a", "m1"
Tmp-ids are scoped to a single MRS-Ops envelope
Operations MAY reference each other’s tmp-ids within same envelope
Orchestrator maps all tmp-ids to UUIDs before application
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 Type	Typical Context Views
Compose	phrase-structure, harmonic-context, thematic-references
Countermelody	melodic-reference, harmonic-context
Orchestrate	orchestration-map, dynamics-profile
Harmonize	melodic-reference, phrase-structure
Dynamics	phrase-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:

Bundle	Lanes	Use Case
`orchestrate`	notes, expression, technique	Full orchestration
`dynamics-pass`	expression	Dynamics only
`notation-cleanup`	notes, technique	Fix notation
`full-compose`	all creative lanes	Full 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))

Constraint	Description
`range`	Notes within instrument range
`avoid`	Prevent voice-leading errors
`prefer`	Style preferences
`max-interval`	Maximum melodic leap
`note-density`	Notes per measure

Constraint violations are caught in progressive validation.

Overview

MRS-S Format

Agent Workflows

Model & Validation

Why Typed Operations?

MRS-Ops Envelope

Operation Types

Create Event

Update Event

Delete Event

Create Span

Update Span

Delete Span

Create Measure

Delete Measure

Instrument Change

Temporary ID Rules

Task-Adaptive Context Views

Melodic Reference

Harmonic Context

Orchestration Map

Phrase Structure

View Selection by Task Type

Example: Add Countermelody

Lane Bundles

Constraint Language

​Why Typed Operations?

​MRS-Ops Envelope

​Operation Types

​Create Event

​Update Event

​Delete Event

​Create Span

​Update Span

​Delete Span

​Create Measure

​Delete Measure

​Instrument Change

​Temporary ID Rules

​Task-Adaptive Context Views

​Melodic Reference

​Harmonic Context

​Orchestration Map

​Phrase Structure

​View Selection by Task Type

​Example: Add Countermelody

​Lane Bundles

​Constraint Language

Why Typed Operations?

MRS-Ops Envelope

Operation Types

Create Event

Update Event

Delete Event

Create Span

Update Span

Delete Span

Create Measure

Delete Measure

Instrument Change

Temporary ID Rules

Task-Adaptive Context Views

Melodic Reference

Harmonic Context

Orchestration Map

Phrase Structure

View Selection by Task Type

Example: Add Countermelody

Lane Bundles

Constraint Language