Skip to main content
The Extract-Replace Protocol defines how orchestrators create Working Set Envelopes from MRS-S documents and how to apply agent responses back. See: /MRS-Specification-RFC#9-extract-replace-protocol

​
Overview

┌─────────────────┐         extract         ┌─────────────────────────┐
│     MRS-S       │ ──────────────────────► │  Working Set Envelope   │
│    (Source)     │                         │  (scoped MRS-S + context)│
│                 │ ◄────────────────────── │                         │
└─────────────────┘         replace         └─────────────────────────┘
The key simplification: replacement is trivial because agents return valid MRS-S fragments that directly substitute for the extracted scope.

​
Extraction

Extraction produces a Working Set Envelope from a source document:
  1. Validate requested scope (measure UUIDs exist, parts exist)
  2. Compute source hash for conflict detection
  3. Resolve inherited state (time/key/tempo at extraction start)
  4. Copy measures in UUID range
  5. Build context rings at reduced detail
  6. Include spans (mark boundary crossings)
  7. Build envelope with metadata and synopsis reference
See: /MRS-Specification-RFC#9-2-extraction-mrs-s--working-set

​
Replacement

Replacement applies agent output back to the source:
  1. Verify source hash (for conflict detection)
  2. Validate response scope (UUID range, parts)
  3. Parse response content as MRS-S
  4. Assign UUIDs to new objects lacking them
  5. Delete all content in scope from source
  6. Insert all content from response
  7. Handle span updates
  8. Full validation
The entire merge logic reduces to: delete the old scope, insert the new scope, validate. See: /MRS-Specification-RFC#9-3-replacement-working-set--mrs-s

​
UUID-Based Operations

All scope specifications use UUIDs: 
:scope
  (:measures #uuid "018c3f40-002d-..." #uuid "018c3f40-0034-...")
  (:parts [clarinet-1])
:display-hint (:measures 45 52)  ; Informational only

​
Insertion Operations

When agents need to insert new measures: 
(working-set-response
  :scope (...)
  
  :insertions
    ((after #uuid "018c3f40-0030-..."
      (measure :id #uuid "018c3f50-new1-..." :number :auto ...)))
  
  :content ...)
The orchestrator assigns :number values and updates absolute positions.

​
Round-Trip Guarantee

For any valid MRS-S document S and extraction parameters P: 
replace(S, identity(extract(S, P))) ≡ S
Extracting and immediately replacing unchanged content produces an identical document. See: /MRS-Specification-RFC#9-4-round-trip-guarantee