# ISIS v2 WS08-006: Audio Compliance Checks (Loudness, Clipping, Format Normalization)

## Scope

`WS08-006` implements first-class audio compliance checks for ISIS audio output
packages so downstream systems can deterministically evaluate release readiness
for loudness targets, clipping risk, and format normalization.

## Research and Existing Implementation Alignment

Before implementation, existing ISIS audio contract and runtime layers were
reviewed to align compliance checks with already-shipped output package
infrastructure:

- Workflow schema and output-package linting:
  - `libs/isis/workflows/src/schemas/workflow.schema.ts`
  - `libs/isis/workflows/src/utils/output-contract-lint.ts`
- Generation runtime output parsing and package 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 compliance reporting extends existing package contracts without
introducing schema/runtime drift.

## Deliverables

1. Workflow schema + lint contract expansion

- Added optional `audio_package.compliance` workflow contract.
- Added compliance artifact inclusion to output package lint bundle derivation.
- Added compliance artifact id coverage to required artifact consistency checks.

2. Runtime output-config parsing

- Extended output spec parser to normalize
  `output_spec.audio_package.compliance` into runtime `WorkflowOutputConfig`.
- Added normalized compliance settings:
  - `loudnessToleranceLufs`
  - `truePeakToleranceDbtp`
  - `maxClippingPercent`
  - `enforceFormatNormalization`
  - optional `artifactId` and `pathTemplate`

3. Runtime compliance report emission

- Extended `buildAudioPackageOutput` to emit `audioPackage.compliance` with:
  - loudness check (target vs measured vs tolerance)
  - clipping check (true peak tolerance + estimated clipping percent)
  - format-normalization checks for mixdown, stems, and multi-track artifacts
  - overall compliance status aggregation (`pass`/`warn`/`fail`)
- Added deterministic compliance artifact output path + metadata.

4. API/SDK/schema contract updates

- Added typed compliance report structures to:
  - `apps/isis/generation-api/src/types.ts`
  - `libs/isis/client/src/types.ts`
- Added validation schemas for compliance report payloads in
  `apps/isis/generation-api/src/schemas/job.schema.ts`.

5. Workflow coverage

- Added `audio_package.compliance` contracts to:
  - `music-cue-composer`
  - `sfx-sound-designer`
  - `voice-performance-synthesis`

6. Regression coverage

- Extended workflow schema tests to include compliance contract acceptance.
- Extended job output schema tests for compliance payload acceptance and
  rejection behavior.
- Extended executor simulation tests to verify compliance report emission and
  required check structure.

## 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
node scripts/isis/generate-v2-workflow-taxonomy-registry.mjs
node scripts/isis/validate-v2-workflow-taxonomy-registry.mjs
node scripts/isis/validate-v2-compliance-gate.mjs
```

## Result

`WS08-006` is now implemented as a typed, validated, and runtime-emitted audio
compliance report contract covering loudness, clipping, and format normalization
across audio workflow families and API/SDK surfaces.
