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

# Draft States

> Placeholder primitives for intentionally incomplete content.

Draft states provide first-class support for intentionally incomplete content during iterative composition.

See: [`/MRS-Specification-RFC#11-data-model`](/MRS-Specification-RFC#11-data-model)

## The Problem

Early-stage composition is inherently incomplete:

* You know the harmony before the orchestration
* You have a melody before the accompaniment
* You have rhythm sketches before final pitches

Without draft states:

1. **Forced completeness** leads to hallucinated filler
2. **Empty measures** are ambiguous (rest or TBD?)
3. **Intent is lost** — an empty measure might mean "rest" or "to be filled"

## Placeholder Primitives

### Placeholder Region

Mark a region as intentionally incomplete:

```clojure theme={null}
(placeholder
  :id #uuid "..."
  :measures #uuid "..." #uuid "..."
  :instruments [violin-1 violin-2 viola cello]
  :intent accompaniment
  :description "Strings accompany flute melody")
```

| Field          | Description                     |
| -------------- | ------------------------------- |
| `:measures`    | UUID range                      |
| `:instruments` | Affected instruments            |
| `:intent`      | What kind of content is planned |
| `:description` | Human-readable description      |

### Intent Types

| Intent           | Description               |
| ---------------- | ------------------------- |
| `:melody`        | Melodic content TBD       |
| `:accompaniment` | Accompaniment pattern TBD |
| `:countermelody` | Counter-line TBD          |
| `:harmony`       | Harmonic content TBD      |
| `:orchestration` | Orchestration TBD         |
| `:texture`       | General texture/pad TBD   |
| `:rhythm`        | Rhythmic pattern TBD      |

### Sketch Rhythm

Provide rhythm without final pitches:

```clojure theme={null}
(sketch-rhythm
  :id #uuid "..."
  :measure #uuid "..."
  :instrument flute-1
  :voice v1
  :rhythm [q e e h]
  :description "Main theme rhythm, pitches TBD")
```

### Harmonic Sketch

Provide harmony without voicing:

```clojure theme={null}
(harmony-plan
  (region :measures #uuid "..." #uuid "..."
    (chord :beat 0 :symbol Cm)
    (chord :beat 2 :symbol Fm)
    (chord :beat 0 :symbol G7)))
```

## Validation Levels

MRS supports validation levels to accommodate draft states:

| Level        | Allows                                      |
| ------------ | ------------------------------------------- |
| `strict`     | No placeholders; all content complete       |
| `permissive` | Placeholders allowed; validates what exists |
| `sketch`     | Minimal validation; for early drafts        |

### Strict Validation

```clojure theme={null}
(meta
  :validation-level strict
  ...)
```

All measures must have complete content. Placeholders are errors.

### Permissive Validation

```clojure theme={null}
(meta
  :validation-level permissive
  ...)
```

Placeholders are valid. Validates:

* Existing content is well-formed
* References are valid
* Placeholder intents are recognized

### Sketch Validation

```clojure theme={null}
(meta
  :validation-level sketch
  ...)
```

Minimal validation for early drafts:

* Basic syntax
* UUID validity
* No content requirements

## Example: From Sketch to Complete

### Stage 1: Harmony Plan Only

```clojure theme={null}
(mrs-s 1.0
  (meta :title "New Piece" :validation-level sketch)
  (players ...)
  (instruments ...)
  (measures
    (measure :id #uuid "..." :number 1 :beat-start 0 :time 4/4
      (placeholder :instruments [flute-1 clarinet-bb violin-1]
                   :intent orchestration
                   :description "Full orchestration TBD")))
  (spans)
  (harmony-plan
    (region :measures #uuid "..." #uuid "..."
      (chord :beat 0 :symbol Cm)
      (chord :beat 2 :symbol Fm))))
```

### Stage 2: Melody Added

```clojure theme={null}
(measure :id #uuid "..." :number 1 :beat-start 0 :time 4/4
  (flute-1
    (v1
      (: 0 Eb5.q :id #uuid "...")
      (: 1 D5.q :id #uuid "...")
      (: 2 Eb5.e :id #uuid "...")
      (: 2+1/2 F5.e :id #uuid "...")
      (: 3 G5.q :id #uuid "...")))
  (placeholder :instruments [clarinet-bb violin-1]
               :intent accompaniment
               :description "Accompaniment to flute melody"))
```

### Stage 3: Complete

```clojure theme={null}
(measure :id #uuid "..." :number 1 :beat-start 0 :time 4/4
  (flute-1
    (v1 (: 0 Eb5.q :id #uuid "...") ...))
  (clarinet-bb
    (v1 (: 0 G4.h :id #uuid "...") ...))
  (violin-1
    (v1 (: 0 C4.q :id #uuid "...") ...)))
```

## Operations on Placeholders

### Resolve Placeholder

Replace placeholder with actual content:

```clojure theme={null}
(resolve-placeholder
  :placeholder-id #uuid "..."
  :content
    ((create-event :tmp-id "e1" :measure #uuid "..." 
                   :instrument clarinet-bb :voice v1
                   :beat 0 :pitch G4 :duration h)
     ...))
```

### Refine Placeholder

Add detail without fully resolving:

```clojure theme={null}
(refine-placeholder
  :placeholder-id #uuid "..."
  :add-sketch-rhythm
    (sketch-rhythm :instrument clarinet-bb :voice v1
                   :rhythm [h h]))
```

## Checkpoints and Placeholders

Checkpoints can require placeholder resolution:

```clojure theme={null}
(checkpoint
  :id "orchestration-complete"
  :requires
    ((no-placeholders :scope :all)))
```

After this checkpoint, placeholders are validation errors.