# ISIS v2 Cross-Service Compatibility Contract Tests (WS10-010)

Date: 2026-02-24  
Owner: @oshun/isis-team  
Checklist: `WS10-010`  
Ticket: `ISIS2-00118`

## Objective

Add contract tests that validate cross-service compatibility across Isis APIs on
all merge paths.

## Existing Implementations Reviewed

Before implementation, these in-repo implementations were analyzed:

- `.github/workflows/ci.yml`
  - existing `isis-api-route-contracts` job executing per-service OpenAPI route
    parity tests.
- `apps/isis/*/src/openapi.contract.spec.ts`
  - existing per-service route-vs-spec contract assertions.
- `libs/isis/client/src/resources/*.route-parity.spec.ts`
  - SDK-to-backend route parity pattern and OpenAPI parsing utilities.

Design decisions from this analysis:

- keep per-service OpenAPI parity tests in place,
- add a dedicated SDK-level cross-service compatibility spec that validates
  required route chains spanning generation, workflow-registry, and
  output-registry,
- enforce this cross-service suite in CI on every merge path.

## Delivered Validation Surface

Added cross-service contract test:

- `libs/isis/client/src/resources/isis.cross-service-contract.spec.ts`

Cross-service scenarios covered:

- workflow-pack exchange and workflow triggering compatibility
- preset-bundle import/export and execution-history compatibility
- job-to-output provenance/lineage traceability compatibility

Updated CI merge gate:

- `.github/workflows/ci.yml`
  - added step:
    - `pnpm --filter @isis/client exec vitest run src/resources/isis.cross-service-contract.spec.ts`
  - step executes within `isis-api-route-contracts` job.

## Verification Commands

```bash
pnpm --filter @isis/generation-api exec vitest run src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/workflow-registry exec vitest run src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/output-registry exec vitest run src/openapi.contract.spec.ts --reporter=dot
pnpm --filter @isis/client exec vitest run src/resources/isis.cross-service-contract.spec.ts --reporter=dot
node scripts/isis/generate-remediation-backlog-v2.mjs
node scripts/isis/validate-v2-compliance-gate.mjs
```
