# control-surface-schema spec delta

## ADDED Requirements

### Requirement: ControlSurface root document

`@suaveplan/control-surface-schema` SHALL export a `ControlSurface` type with: `id` (uuid v7), `name`, `version` (semver matching `CURRENT_SCHEMA_VERSION`), `createdAt`, `updatedAt`, `skin`, `root: ControlNode`. Every field is validated by the Zod schema.

#### Scenario: Empty surface validates

- **WHEN** `validateSurface({ id, name: "x", version: CURRENT_SCHEMA_VERSION, createdAt: 0, updatedAt: 0, skin: { id: "default" }, root: { type: "group", id: "root", layout: { kind: "absolute" }, transform: { position: { x:0, y:0 } }, children: [] } })` is called
- **THEN** it returns `{ surface }` with no error

#### Scenario: Missing fields rejected

- **WHEN** `validateSurface({})` is called
- **THEN** it returns `{ error }` with code `CONTROL_SURFACE_SCHEMA.INVALID_DOCUMENT` and Zod issues attached

**Verified by:** `src/validate/validate.test.ts`

### Requirement: ControlNode discriminated union

`ControlNode = Group | Control`. Validators distinguish by `type` field; cross-validation rejects controls inside controls or groups with mixed-type children that don't match the layout kind.

#### Scenario: Nested groups validate

- **WHEN** a surface contains a Group containing two Groups each containing three Controls
- **THEN** validation succeeds and `walkSurface(surface, visitor)` visits 9 nodes in DFS order

**Verified by:** `src/walk/walk.test.ts`

### Requirement: 18 ControlKind variants

`ControlKind` SHALL be a closed union of 18 values: `knob`, `slider-v`, `slider-h`, `button-momentary`, `button-latching`, `switch-2`, `switch-3`, `led`, `digital-display`, `meter-vu`, `meter-peak`, `meter-spectral`, `xy-pad`, `jog-wheel`, `piano-key`, `drum-pad`, `text-label`, `image`. The validator rejects unknown kinds.

#### Scenario: Unknown kind rejected

- **WHEN** a Control has `kind: "not-a-thing"`
- **THEN** `validateSurface` rejects with `INVALID_DOCUMENT`

**Verified by:** `src/validate/validate.test.ts::"unknown ControlKind"`

### Requirement: Six Binding variants

`Binding` SHALL cover `pluginParam`, `transport`, `midiOut`, `midiIn`, `dmx`, `compound`. The `compound` variant wraps an array of other bindings (no nested compounds — flat-only) so one knob can drive a plugin parameter, a MIDI CC, and a DMX channel simultaneously.

#### Scenario: pluginParam binding round-trips through validate + JSON

- **WHEN** a Control has `binding: { kind: "pluginParam", pluginId: "p1", paramPath: "channels/0/volume", curve: "log" }`
- **THEN** `JSON.parse(JSON.stringify(validateSurface(surface).surface))` deep-equals the original

#### Scenario: Nested compound rejected

- **WHEN** a `compound` binding contains another `compound` in its `bindings` array
- **THEN** validation rejects with `INVALID_DOCUMENT`

**Verified by:** `src/validate/validate.test.ts::"binding variants"`

### Requirement: GroupLayout — 4 variants

`GroupLayout` SHALL cover `grid`, `absolute`, `stack`, `free3d`. `free3d` is the only layout that admits z-axis transforms; the validator rejects nonzero `transform.position.z` under any other layout.

#### Scenario: 2D layout rejects z-transform

- **WHEN** a Group has `layout: { kind: "grid", columns: 4, rows: 4, gap: 8 }` and a child with `transform: { position: { x:0, y:0, z:1 } }`
- **THEN** validation rejects with `INVALID_DOCUMENT`

**Verified by:** `src/validate/validate.test.ts::"layout z-axis discipline"`

### Requirement: Schema versioning + forward migration

`upgradeSurface(unknown)` SHALL accept any prior version registered in the migration chain and migrate forward to `CURRENT_SCHEMA_VERSION`. Unknown versions reject with `UNSUPPORTED_VERSION`.

#### Scenario: Upgrade 0.1.0 → 0.2.0 (illustrative)

- **WHEN** a v0.1.0 document is passed to `upgradeSurface` and a registered `0.1.0 → 0.2.0` migration exists
- **THEN** the returned document validates against the current schema

#### Scenario: Unknown version rejects

- **WHEN** `upgradeSurface({ version: "99.0.0", ... })` is called
- **THEN** it throws `SchemaError("CONTROL_SURFACE_SCHEMA.UNSUPPORTED_VERSION")`

**Verified by:** `src/upgrade/upgrade.test.ts`

### Requirement: Duplicate-id detection

`validateSurface` SHALL detect duplicate `id` values across the entire node tree and reject with `DUPLICATE_ID` carrying the offending ids on `context.ids`.

#### Scenario: Two controls with the same id rejected

- **WHEN** a surface has two `Control` nodes with `id: "x"`
- **THEN** validation rejects with `DUPLICATE_ID` listing `["x"]`

**Verified by:** `src/identity/identity.test.ts`

### Requirement: Binding-reference cross-check

When a binding references a `pluginId` that is not present in the surface's optional `pluginCatalog` (passed alongside), validation SHALL reject with `BINDING_REFERENCE_MISSING` carrying the missing reference on context.

#### Scenario: Reference missing plugin

- **WHEN** `validateSurface(surface, { pluginCatalog: new Set(["p1"]) })` is called and a control references `pluginId: "p99"`
- **THEN** validation rejects with `BINDING_REFERENCE_MISSING` carrying `{ missing: "p99" }`

**Verified by:** `src/identity/identity.test.ts::"binding ref"`

### Requirement: walkSurface DFS traversal

`walkSurface(surface, visitor)` SHALL visit every node depth-first, passing the node + its parent stack (root-first). Mutation during traversal is undefined behaviour (visitor is read-only by contract).

#### Scenario: DFS order

- **WHEN** a surface has root → A → [B, C → [D]] → E
- **THEN** visitor is called with node ids in order `["root", "A", "B", "C", "D", "E"]`

**Verified by:** `src/walk/walk.test.ts`