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

# Design Principles

> Core design philosophy guiding MRS architecture decisions.

MRS is built on principles derived from the real requirements of AI-assisted composition and orchestration at professional scale.

See: [`/MRS-Specification-RFC#2-design-principles`](/MRS-Specification-RFC#2-design-principles)

## Separation of Concerns: Semantic Model vs Representations

MRS is a **semantic model** plus protocols for safe editing. It may be represented in multiple ways depending on the audience and task.

| Concern                      | Representation           | Optimized For                                 |
| ---------------------------- | ------------------------ | --------------------------------------------- |
| Canonical semantics          | (Implementation-defined) | Correctness, indexing, partial extraction     |
| Human/audit/interchange view | MRS-S                    | Completeness, readability, validation         |
| Agent output (mutations)     | MRS-Ops                  | Reliability, minimal surface, explicit intent |

**Rationale**: The architecture should not depend on a single file format. What matters is stable identity, deterministic application, and human-auditable changes.

**Reliability consequence**: Asking agents to emit complete, valid score fragments creates high failure rates from accidental omissions, calculation errors, and hallucinated references. Typed operations with orchestrator-derived fields eliminate entire error classes.

```clojure theme={null}
;; Agent reads MRS-S (complete, human-auditable)
(measure :id #uuid "..." :number 45
  (clarinet-bb
    (v1
      (: 0 C5.q :id #uuid "...")
      (: 1 D5.q :id #uuid "..."))))

;; Agent writes MRS-Ops (typed, minimal)
(create-event :tmp-id "e1" :measure #uuid "..." 
              :instrument clarinet-bb :voice v1
              :beat 2 :pitch E5 :duration q :dyn mf)
```

## Orchestrator Authority

The orchestrator is the sole authority for:

* **UUID minting**: Agents use temporary IDs; orchestrator assigns final UUIDs
* **Derived field computation**: Orchestrator computes `:at`, `:beat-start`, etc.
* **Canonical state management**: Single source of truth
* **Validation and application**: Progressive validation before state mutation

**Rationale**: Centralized authority eliminates coordination failures. Agents cannot create invalid references or miscalculate derived fields because they don't manage those concerns.

## Stable Identity Over Positional Reference

Every measure, event, and span carries a stable UUIDv7 identifier. Measure numbers are display properties for human navigation, not structural identity.

```clojure theme={null}
(measure 
  :id #uuid "018c3f40-1234-7890-abcd-ef1234567890"  ; Stable—survives edits
  :number 45                                         ; Display only—can change
  :beat-start 487
  ...)
```

**Rationale**: Positional references break when content is inserted or deleted. UUID references survive structural changes, enabling fluid compositional workflows where form evolves during the creative process.

## Progressive Validation

Operations are validated in stages before application:

```
Syntax → References → Permissions → Musical Rules → Application
```

**Rationale**: Errors caught before state mutation enable specific feedback, partial acceptance, and no silent corruption. This is fundamentally different from "emit fragment, hope it validates."

## Task-Adaptive Context

Agents receive context views tailored to their specific task, not fixed "near/far" rings.

| Task Type     | Context Views                       |
| ------------- | ----------------------------------- |
| Countermelody | Melodic reference, harmonic context |
| Orchestration | Orchestration map, texture density  |
| Dynamics pass | Phrase structure, dynamics profile  |

**Rationale**: Fixed rings may include irrelevant content and omit critical content. A countermelody task needs the melody it responds to, not "nearby measures at melodic-skeleton reduction."

## Professional Orchestration Semantics

The Player → Instrument → Staff model supports real-world orchestration:

```clojure theme={null}
(player woodwind-2
  :name "Flute 2 / Piccolo"
  :instruments [flute-2 piccolo]
  :default flute-2)
```

**Rationale**: Arrangers and orchestrators work with players and instrument changes constantly. Flute 2 doubling piccolo is not an edge case—it's standard practice. The model must reflect professional reality.

## Explicit Over Implicit

Every musical element has an explicit representation. Position in the measure is stated, not inferred from accumulated durations. Voice assignment is declared, not guessed from stem direction.

**Rationale**: Implicit state creates cascading errors. If an LLM miscounts one duration, all subsequent events are misaligned. Explicit positions are independently verifiable.

## Semantic Over Visual

MRS encodes musical meaning, not page layout. A crescendo is marked with semantic anchors (start/end and type), not with graphical coordinates.

**Rationale**: Layout is context-dependent (page size, staff spacing, font). Semantic encoding remains valid across renderers.

**Practical note**: Real-time feedback still matters for musicians. Implementations can render previews by exporting the relevant region to a notation engine, or by using a lightweight preview renderer, without making engraving geometry part of the canonical model.

## Predictable Over Clever

The format uses regular patterns even when more compact alternatives exist. Every note uses the same syntax regardless of context.

**Rationale**: LLMs generate more reliably when patterns are consistent. A 10% size reduction is not worth a 50% increase in generation errors.

## Canonical Rational Syntax

All temporal positions use exact rationals in a single canonical form:

```
Permitted:   0, 1, 2+1/2, 0+1/3, 3+3/4
Forbidden:   2.5, 0.333, 1.75  (decimal literals)
```

**Rationale**: Decimal literals invite floating-point parsing and normalization ambiguity. One canonical form eliminates entire error classes.