# ISIS v2 WS10-001: Canonical OpenAPI Generation

## Scope

Implemented a canonical Isis OpenAPI artifact and generation gate so the
published spec is generated from source route declarations.

## Implemented Artifacts

- OpenAPI generator/check script:
  - `scripts/isis/generate_generation_api_openapi.mjs`
- Canonical generated OpenAPI artifacts:
  - `apps/isis/generation-api/openapi.yaml`
  - `openapi/isis/openapi.yaml`
- Generation API contract and script wiring:
  - `apps/isis/generation-api/src/openapi.contract.spec.ts`
  - `apps/isis/generation-api/package.json`
  - `package.json`

## Generation Model

- Source-of-truth route extraction includes:
  - `jobs` routes (`/api/v1/jobs/*`)
  - `models` routes (`/api/v1/models/*`)
  - provider callback routes (`/webhooks/*`)
  - core health/queue aliases (`/health`, `/ready`, `/api/v1/queue/stats`)
- Generator behavior:
  - preserves existing operation objects where available
  - inserts fallback operation objects for newly discovered routes
  - marks all operations with `x-generated-from-source-route: true`
  - emits identical YAML into service-local and canonical OpenAPI locations

## Verification

```bash
node scripts/isis/generate_generation_api_openapi.mjs --check
pnpm --filter @isis/generation-api run openapi:check
pnpm --filter @isis/generation-api exec vitest run src/openapi.contract.spec.ts --reporter=dot
```

## Outcome

WS10-001 is now closed with deterministic, route-derived OpenAPI generation and
a check gate that fails when published specs drift from source routes.
