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

# Architecture Overview

> How MRS components work together for AI-assisted composition.

MRS enables safe, context-aware agent operations on full scores through a separation of concerns: a semantic score model, typed mutation operations, orchestrator authority, and task-adaptive context.

See: [`/MRS-Specification-RFC#3-architecture-overview`](/MRS-Specification-RFC#3-architecture-overview)

## 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)                     │  │
│  └────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
```

## Core Components

### MRS-S (Human/Audit Representation)

A complete, archival-quality representation of score semantics:

* Human-readable S-expression syntax
* Stable UUIDv7 identifiers for all objects
* Complete semantic fidelity
* Useful for interchange, debugging, review, and as agent input

**Implementation note**: An orchestrator does not have to store canonical state as a single MRS-S text document. A database/graph-backed canonical model with indexes and caches can materially improve extraction speed and real-time feedback, as long as it preserves MRS semantics and can export equivalent MRS-S.

### MRS-Ops (Mutation Protocol)

Typed operations for reliable agent output:

* Explicit create/update/delete operations
* Temporary IDs (orchestrator assigns UUIDs)
* Orchestrator computes derived fields
* Eliminates accidental deletions and calculation errors

### Orchestrator

Central coordinator that makes AI composition safe:

* Sole authority for UUID minting
* Computes derived fields (`:at`, `:beat-start`)
* Progressive validation before application
* Generates task-adaptive context views
* Maintains audit trail

### Working Set Envelope

Bounded extraction with context for agent tasks:

* Scoped MRS-S content (what agent can read/modify)
* Task-adaptive context views
* Lane bundle permissions
* Structural index reference for global awareness

### Structural Index

Compressed global view of the score:

* Form/structure overview
* Key areas and tempo map
* Player/instrument activity
* Rehearsal mark locations

### Analytical Overlays

Typed metadata attached to score regions:

* Harmonic analysis (chord symbols, functions)
* Thematic analysis (motifs, themes)
* Form analysis (phrases, periods, sections)

## 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 (well-formed?)
   - Reference validation (IDs exist?)
   - Permission validation (within lanes/scope?)
   - Musical rule validation (constraints satisfied?)

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 id-mapping and revision
   - Or rejection with specific errors
```

## The Scale Problem

| Score Type        | Parts | Measures | Events    | Tokens |
| ----------------- | ----- | -------- | --------- | ------ |
| Lead sheet        | 1     | 32       | \~200     | \~2K   |
| Piano sonata      | 2     | 300      | \~5,000   | \~40K  |
| String quartet    | 4     | 400      | \~8,000   | \~65K  |
| Chamber orchestra | 25    | 500      | \~50,000  | \~400K |
| Full orchestra    | 90    | 1000     | \~200,000 | \~1.5M |

MRS solves this through bounded extraction with task-adaptive context—agents work on focused regions while understanding their musical surroundings.

## Multi-Agent Coordination

```
         ORCHESTRATOR (owns canonical state)
                │
    ┌───────────┼───────────┬───────────┐
    ▼           ▼           ▼           ▼
 Harmony    Melody      Orch.      Expression
  Agent      Agent      Agent        Agent
    │           │           │           │
    └───────────┴───────────┴───────────┘
                │
    (read MRS-S, write MRS-Ops, disjoint lanes)
```

Multiple agents can work in parallel with disjoint lane bundles. The orchestrator validates and applies operations, detecting conflicts via source-hash comparison.

## Related Documentation

* [Orchestrator Contract](/orchestrator-contract) — Validation, transactions, conflict detection
* [Working Set Envelope](/working-set-envelope) — Scoped extraction with context
* [MRS-Ops Protocol](/agentic-operations) — Typed operations for agent mutations