> ## Documentation Index
> Fetch the complete documentation index at: https://musicready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Working Set Envelope

> Scoped MRS-S extraction with task-adaptive context for agent operations.

A Working Set Envelope wraps a bounded MRS-S fragment with task-adaptive context for focused agent operations.

See: [`/MRS-Specification-RFC#7-working-set-envelope`](/MRS-Specification-RFC#7-working-set-envelope)

## Design Principles

* **Agents read MRS-S** — complete, human-auditable score fragments
* **Scopes use UUIDs** — not measure numbers — for structural stability
* **Task-adaptive context** — views tailored to the specific task, not fixed rings
* **Permissions via bundles** — lane bundles grant appropriate modification rights

## Envelope Structure

```clojure theme={null}
(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
    (context-view melodic-reference
      :instruments [violin-1]
      :measures #uuid "018c3f40-002d-..." #uuid "018c3f40-0034-..."
      :content
        (measures
          (measure :id #uuid "..." :number 45
            (violin-1
              (v1
                (: 0 G5.q :id #uuid "...")
                (: 1 A5.e :id #uuid "...")
                ...)))))
    
    (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)))
  
  :structural-index-ref "sha256:abc123..."
  
  :available-queries
    [:melodic-content :harmonic-analysis :orchestration-density])
```

## Envelope Fields

### Required Fields

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

### Scope Specification

```clojure theme={null}
: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
```

**Important**: Scope uses UUIDs for structural stability. Display hints are for human orientation only — never used for structural reference.

### Permission Fields

| Field          | Type    | Description                                |
| -------------- | ------- | ------------------------------------------ |
| `:bundle`      | keyword | Lane bundle granting permissions           |
| `:allowed-ops` | list    | 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 views         |
| `:structural-index-ref` | string | Hash reference to structural index  |
| `:available-queries`    | list   | Queries agent may request           |

## 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

This enables validation of the content independent of the full score.

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

See: [Task-Adaptive Context Views](/agentic-operations#task-adaptive-context-views)

### View Types

| View Type             | Purpose                            |
| --------------------- | ---------------------------------- |
| `melodic-reference`   | Melody the agent should respond to |
| `harmonic-context`    | Chord progression and key areas    |
| `orchestration-map`   | Active instruments and texture     |
| `phrase-structure`    | Phrase boundaries and form         |
| `dynamics-profile`    | Dynamics trajectory                |
| `thematic-references` | Themes and motifs                  |

### View Selection by Task

| Task Type     | Typical Views                       |
| ------------- | ----------------------------------- |
| Countermelody | melodic-reference, harmonic-context |
| Orchestration | orchestration-map, dynamics-profile |
| Dynamics pass | phrase-structure, dynamics-profile  |
| Harmonization | melodic-reference, phrase-structure |

## Boundary-Crossing Spans

When a span crosses the envelope boundary:

```clojure theme={null}
(slur
  :id #uuid "018c3f2c-..."
  :from #uuid "018c3f2a-..."    ; Inside scope
  :to #uuid "018c3f2b-..."      ; Outside scope
  :boundary-exit true)          ; Marks endpoint outside
```

### Boundary Rules

* `:boundary-entry true` — span starts outside scope, ends inside
* `:boundary-exit true` — span starts inside scope, ends outside
* Both markers — span crosses through scope

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

## Available Queries

Agents may request additional context:

```clojure theme={null}
: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):

```clojure theme={null}
(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.

## Constraints

Constraints specify rules that generated content must satisfy:

```clojure theme={null}
:constraints
  ((range clarinet-bb E3 C7)           ; Notes within instrument range
   (avoid parallel-fifths violin-1)    ; Voice-leading rule
   (prefer chord-tones downbeats))     ; Style preference
```

### Constraint Types

| Type    | Syntax                              | Description                  |
| ------- | ----------------------------------- | ---------------------------- |
| Range   | `(range <instrument> <low> <high>)` | Notes within range           |
| Avoid   | `(avoid <violation> <ref-part>?)`   | Prevent voice-leading errors |
| Prefer  | `(prefer <feature> <location>)`     | Style preferences            |
| Density | `(note-density <min> <max>)`        | Notes per measure            |

Constraint violations are caught in the musical rules validation stage.