# ISIS v2 WS08-005: Multi-Track Export Bundles (Dialogue/SFX/Music Separation)

## Scope

`WS08-005` implements first-class multi-track export bundle contracts for ISIS
audio workflows so downstream systems can consume explicit dialogue/SFX/music
separated tracks in addition to mixdown and stem exports.

## Research and Existing Implementation Alignment

Before implementation, existing ISIS output package and runtime layers were
reviewed:

- Workflow schema and output package contracts:
  - `libs/isis/workflows/src/schemas/workflow.schema.ts`
  - `libs/isis/workflows/src/utils/output-contract-lint.ts`
- Generation runtime contract parsing and output assembly:
  - `apps/isis/generation-api/src/workflows/types.ts`
  - `apps/isis/generation-api/src/workflows/executor.ts`
- API/SDK output contracts:
  - `apps/isis/generation-api/src/types.ts`
  - `apps/isis/generation-api/src/schemas/job.schema.ts`
  - `libs/isis/client/src/types.ts`

This ensured the new multi-track bundle sits on existing audio package
infrastructure without introducing contract drift.

## Deliverables

1. Workflow schema + lint expansion

- Added `audio_package.multi_track` schema support with:
  - per-track artifacts (`dialogue`, `sfx`, `music`, `ambience`, `voiceover`,
    `other`)
  - format/sample-rate/bit-depth/channels contract
  - optional archive contract
- Extended output contract lint to include multi-track artifacts in resolved
  required/optional output bundles and missing-artifact checks.

2. Runtime output-config parsing

- Extended generation runtime output parsing to read and normalize
  `audio_package.multi_track` into runtime `WorkflowOutputConfig`.
- Added normalization for multi-track role enums and archive MIME/format
  resolution.

3. Runtime package emission

- Extended `buildAudioPackageOutput` to emit `audioPackage.multiTrack` with:
  - deterministic per-track output entries
  - optional archive output
  - size/metadata population consistent with existing mixdown/stem handling

4. API/SDK/output schema contract updates

- Added `multiTrack` package types to:
  - `apps/isis/generation-api/src/types.ts`
  - `libs/isis/client/src/types.ts`
- Added `multiTrack` validation schema support to
  `apps/isis/generation-api/src/schemas/job.schema.ts`.

5. Workflow coverage

- Added `audio_package.multi_track` contracts to:
  - `music-cue-composer`
  - `sfx-sound-designer`
  - `voice-performance-synthesis`
- Each workflow now declares dialogue/SFX/music separated tracks with required
  flags tuned by workflow role and archive export path.

6. Regression coverage

- Extended workflow schema tests for multi-track validation acceptance.
- Extended generation API output schema tests to validate multi-track payload
  acceptance.
- Extended executor regression tests to verify emitted multi-track bundles and
  archive metadata on simulated audio 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-005` is now implemented with typed, validated, and runtime-emitted
multi-track export bundles for dialogue/SFX/music separation, exposed through
workflow contracts and API/SDK output schemas.
