# ISIS v2 WS08-002: Audio Output Package Contract

## Scope

`WS08-002` introduces a first-class audio output package contract covering:

- mixdown/master delivery
- optional stem delivery and stem archive bundles
- loudness analysis metadata
- cue-sheet timeline metadata

The contract is now available across workflow schema, lint/contract derivation,
runtime execution output, API schemas, and SDK types.

## Research and Existing Implementation Alignment

Before implementation, existing contract patterns and audio metadata structures
were reviewed and reused:

- Structured package pattern from `three_d_package` and `editorial_package`.
- Output package lint derivation/validation pattern from workflow output
  contract utilities.
- Existing audio metadata models from provider integrations for sample
  rate/bit-depth/loudness conventions.

## Deliverables

1. Workflow schema extension (`output_spec.audio_package`)

- Added typed audio package blocks:
  - `mixdown`
  - `stems` (+ optional `archive`)
  - `loudness`
  - `cue_sheet`
- Added new audio enums/constraints:
  - stem types
  - mixdown formats (`wav`, `flac`, `aiff`)
  - bit depth (`16`, `24`, `32`)
  - loudness standards
  - cue sheet formats (`csv`, `json`, `cue`)
- Added validation gates:
  - audio outputs require `audio_package`
  - `audio_package` only allowed for audio outputs

2. Workflow contract lint derivation

- Added auto-derivation of required/optional artifacts from
  `output_spec.audio_package`.
- Added lint checks verifying expected audio package artifact IDs are emitted in
  resolved output contracts.

3. Audio workflow definitions updated

- `sfx-sound-designer`
- `voice-performance-synthesis`
- `music-cue-composer`

Each now declares explicit `audio_package` contracts for mixdown, stems,
loudness report, and cue sheet artifacts.

4. Runtime/API/SDK contract propagation

- Added `audioPackage` to runtime workflow output config parsing.
- Added `JobOutput.audioPackage` in generation API types and zod schemas.
- Added mirrored `audioPackage` types in client SDK contracts.
- Implemented runtime assembly of `audioPackage` outputs in both real and
  simulated execution paths.

5. Test coverage

- Workflow schema tests for valid/invalid audio package contracts.
- Job output schema tests for audio package acceptance/rejection.
- Executor simulation test confirming audio package emission for music workflow
  runs.

## Verification Commands

```bash
pnpm --filter @isis/workflows exec vitest run src/workflows.spec.ts --reporter=dot
pnpm --filter @isis/generation-api exec vitest run src/schemas/job.schema.spec.ts src/workflows/executor.spec.ts --reporter=dot
```

## Result

`WS08-002` is now implemented as a first-class, validated audio package contract
with end-to-end runtime/API/SDK exposure.
