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

# Query Resolution

> Translating human-friendly references to UUIDs.

The orchestrator translates human-friendly references (measure numbers, rehearsal marks) to UUIDs for structural operations.

See: [`/MRS-Specification-RFC#14-query-resolution`](/MRS-Specification-RFC#14-query-resolution)

## Why Query Resolution?

UUIDs provide stable identity, but humans think in:

* Measure numbers ("measure 45")
* Rehearsal marks ("4 bars after B")
* Structural positions ("the development section")

Query resolution bridges human intent and structural identity.

## Query Types

### Measure Number Resolution

```clojure theme={null}
(query
  :type resolve
  :human-ref (:measure-number 45)
  :response (:id #uuid "018c3f40-002d-..." :number 45))
```

### Rehearsal Mark Resolution

```clojure theme={null}
(query
  :type resolve
  :human-ref (:rehearsal "B")
  :response (:id #uuid "018c3f40-0020-..." :number 32))
```

### Rehearsal Mark with Offset

```clojure theme={null}
(query
  :type resolve
  :human-ref (:rehearsal "B" :offset 4)
  :response (:id #uuid "018c3f40-0024-..." :number 36))
```

"4 measures after rehearsal B"

### Range Resolution

```clojure theme={null}
(query
  :type resolve-range
  :human-ref (:measures 45 52)
  :response (:from #uuid "018c3f40-002d-..."
             :to #uuid "018c3f40-0034-..."
             :display-range [45 52]))
```

### Section Resolution

```clojure theme={null}
(query
  :type resolve
  :human-ref (:section "development")
  :response (:from #uuid "..." :to #uuid "..." :display-range [65 120]))
```

Requires form analysis overlay.

## Reverse Resolution

UUID to display information:

```clojure theme={null}
(query
  :type display-info
  :id #uuid "018c3f40-002d-..."
  :response (:number 45 :rehearsal "C" :beat-start 487))
```

Useful for:

* Generating human-readable error messages
* Creating display hints in Working Sets
* Logging and debugging

## Resolution in Working Sets

Working Set Envelopes include display hints derived from query resolution:

```clojure theme={null}
(working-set
  :scope
    (:measures #uuid "018c3f40-002d-..." #uuid "018c3f40-0034-...")
    (:instruments [clarinet-bb])
  :display-hint (:measures 45 52)  ; From reverse resolution
  ...)
```

The display hint is informational only—never used for structural reference.

## Resolution Errors

| Error         | Description              |
| ------------- | ------------------------ |
| `RESOLVE-001` | Measure number not found |
| `RESOLVE-002` | Rehearsal mark not found |
| `RESOLVE-003` | Section name not found   |
| `RESOLVE-004` | Offset out of bounds     |

```clojure theme={null}
(query
  :type resolve
  :human-ref (:rehearsal "Z")
  :error (:code RESOLVE-002 :message "Rehearsal mark 'Z' not found"))
```

## Usage in Task Instructions

Human task instructions use friendly references:

> "Add a clarinet countermelody from rehearsal B to 8 bars after B"

The orchestrator resolves:

1. "rehearsal B" → `#uuid "018c3f40-0020-..."`
2. "8 bars after B" → `#uuid "018c3f40-0028-..."`

And creates a Working Set with those UUIDs in scope.

## Query Capabilities

Agents may request resolution:

```clojure theme={null}
:available-queries
  [:resolve-measure
   :resolve-rehearsal
   :resolve-section
   :display-info]
```

Query request from agent:

```clojure theme={null}
(query-request
  :type resolve
  :human-ref (:rehearsal "C")
  :reason "Need to reference theme from section C")
```