# ISIS v2 WS08-009: Audio API/SDK Contracts and Retrieval

## Scope

`WS08-009` formalizes a first-class audio contract surface in Isis generation
API and SDK so external systems can read normalized audio parameter contracts
and artifact retrieval links without parsing generic job payloads.

## Research and Existing Implementation Alignment

Before implementation, existing audio contract coverage was audited:

- API/SDK type contracts already included rich audio request/output payloads:
  - `apps/isis/generation-api/src/types.ts`
  - `libs/isis/client/src/types.ts`
- Existing retrieval paths were generic-only:
  - `GET /api/v1/jobs/:id`
  - `GET /api/v1/jobs/:id/output`
- RunPod audio endpoint classes were already implemented in `WS08-008`, so this
  task focused on retrieval contracts rather than provider routing.

This gap analysis confirmed the missing piece was a dedicated API + SDK contract
for audio retrieval snapshots.

## Deliverables

1. Audio contract snapshot schema and types

- Added API and SDK interfaces for:
  - `JobAudioContractParameters`
  - `JobAudioContractRetrievalLinks`
  - `JobAudioContractSnapshot`
- Added Zod schemas:
  - `JobAudioContractParametersSchema`
  - `JobAudioContractRetrievalLinksSchema`
  - `JobAudioContractSnapshotSchema`

2. Dedicated API retrieval endpoint

- Added `GET /api/v1/jobs/:id/audio` route in generation API.
- Endpoint behavior:
  - returns normalized audio parameter contracts (`audioConditioning`,
    `voiceConsistency`, including snake_case aliases)
  - returns audio artifact retrieval links derived from `output.audioPackage`
  - returns `400 JOB_AUDIO_UNAVAILABLE` when job has no audio context
  - returns `404 JOB_NOT_FOUND` for missing jobs

3. SDK method coverage for audio retrieval

- Added `GenerationResource` methods:
  - `getJobAudioContracts(jobId)`
  - `getJobAudioParameters(jobId)`
  - `getJobAudioPackage(jobId)`

4. API contract publication updates

- Added `/api/v1/jobs/{id}/audio` to route inventory and OpenAPI spec with
  explicit `JobAudioContractSnapshot` schema reference.
- Updated Isis API documentation and architecture/endpoint tables to include the
  new audio contract endpoint.

5. Web parity exposure for new SDK methods

- Updated `GenerationParityPage` method matrix and inspection console to expose:
  - `getJobAudioContracts`
  - `getJobAudioParameters`
  - `getJobAudioPackage`
- Added parity tests to exercise these interactions in the UI.

## Verification Commands

```bash
pnpm --filter @isis/generation-api exec vitest run src/routes/jobs.spec.ts src/schemas/job.schema.spec.ts --reporter=dot
pnpm --filter @isis/web exec vitest run src/pages/GenerationParityPage.spec.tsx --reporter=dot
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs
```

## Result

`WS08-009` is implemented with explicit API/SDK contracts for audio parameters
and retrieval, plus web parity exposure for all new SDK methods.
