suaveplan/openspec/changes/api-conformance-suites/tasks.md

# Tasks — api-conformance-suites (multi-package)

> Every checkbox MUST reflect work actually done in this change.

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Spec authoring

- [x] 1.1 Read design doc (§13.4, §15 Stage 5)
- [x] 1.2 Read `openspec/changes/api-router/`, `api-auth/`, `api-events/`, `api-secrets/`, `api-ws/`, `api-sse/`, `api-graphql/`, `api-saga/` (pending), `api-2pc/` (pending), `api-db/` (pending), `api-jobs/` (pending), `api-tenant-provider/`, `api-tenant-resolver/` for each abstract surface
- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
- [x] 1.4 Draft `proposal.md`
- [x] 1.5 Draft `specs/api-conformance-suites/spec.md`
- [x] 1.6 Every requirement carries `**Verified by:**`

## 2. Implementation

- [ ] 2.1 `packages/api/api-router/src/testing/run-router-conformance.ts` + `.md`
- [ ] 2.2 `packages/api/api-auth/src/testing/run-auth-session-conformance.ts` + `.md`
- [ ] 2.3 `packages/api/api-auth/src/testing/run-tenant-resolver-conformance.ts` (or `api-tenant-resolver` if separate) + `.md`
- [ ] 2.4 `packages/api/api-tenant-provider/src/testing/run-tenant-provider-conformance.ts` + `.md`
- [ ] 2.5 `packages/api/api-secrets/src/testing/run-secrets-conformance.ts` + `.md`
- [ ] 2.6 `packages/api/api-events/src/testing/run-events-bus-conformance.ts` + `.md`
- [ ] 2.7 `packages/api/api-jobs/src/testing/run-jobs-conformance.ts` + `.md`
- [ ] 2.8 `packages/api/api-graphql/src/testing/run-graphql-engine-conformance.ts` + `.md`
- [ ] 2.9 `packages/api/api-ws/src/testing/run-ws-engine-conformance.ts` + `.md`
- [ ] 2.10 `packages/api/api-ws/src/testing/run-ws-broker-conformance.ts` + `.md`
- [ ] 2.11 `packages/api/api-sse/src/testing/run-sse-engine-conformance.ts` + `.md`
- [ ] 2.12 `packages/api/api-saga/src/testing/run-saga-participant-conformance.ts` + `.md`
- [ ] 2.13 `packages/api/api-2pc/src/testing/run-2pc-participant-conformance.ts` + `.md`
- [ ] 2.14 `packages/api/api-db/src/testing/run-db-adapter-conformance.ts` + `.md`
- [ ] 2.15 Each abstract package's `package.json` adds the `./testing` subpath export
- [ ] 2.16 Each `./testing` subpath imports its companion in-memory adapter (Stage 5) ONLY in the self-test file — runtime conformance code must NOT depend on adapter packages (avoid circular)

## 3. Tests

- [ ] 3.1 `packages/api/api-router/src/testing/run-router-conformance.self-test.test.ts` — invokes the function against `createInMemoryRouter`; asserts at least one pass per category (route-match, blue-green, streaming, error-envelope)
- [ ] 3.2 Same self-test file pattern for every other run-* function (one per capability)
- [ ] 3.3 `tests/dep-graph/conformance-subpath-shape.test.ts` — iterate every abstract package; assert `./testing` subpath exports the expected symbol
- [ ] 3.4 Every `it(...)` carries `{ timeout: 5000 }` (30000 for genuinely async)

## 4. Documentation

- [ ] 4.1 Sibling `.md` per conformance function (≥200 words, lists every invariant with a one-line description, basic + advanced examples of invocation, full signature)
- [ ] 4.2 Each abstract package's README documents the `./testing` subpath usage and links the .md
- [ ] 4.3 Cross-link from umbrella `api-plugin-foundation/proposal.md` to this change

## 5. Pre-archive verification (5-gate triple)

- [ ] 5.1 `bun run check` — clean
- [ ] 5.2 `bunx turbo lint typecheck test --filter='@suaveplan/api-*'` — green
- [ ] 5.3 `bunx turbo test:coverage --filter='@suaveplan/api-*'` — 100/100/100/100
- [ ] 5.4 `bun scripts/openspec-conformance.ts api-conformance-suites` — exit 0
- [ ] 5.5 `bunx turbo build --filter='@suaveplan/api-*'` — green

## 6. Pre-archive 7-row checklist

- [ ] 6.1 Generics threaded through every `runXConformance(label, factory)` signature; `expectTypeOf` asserts factory return type matches capability
- [ ] 6.2 Conformance fixtures (where Zod-validated payloads are needed) wired at boundaries
- [ ] 6.3 No `error-codes.ts` per conformance fn — they delegate to the capability's own codes
- [ ] 6.4 Strict-mode behaviors (where a capability flips strict/lenient) tested both on and off inside the conformance suite itself
- [ ] 6.5 OTel-instrument invariants (every capability's expected instrument set) asserted from within the conformance suite using an in-memory `MeterProvider` supplied by the test host
- [ ] 6.6 Lifecycle dedup invariants (idempotent register/unregister, etc.) included in the suite where applicable
- [ ] 6.7 No retroactive tick — every box reflects work in this change

## 7. Archive

- [ ] 7.1 Fold spec deltas into each abstract package's `openspec/specs/<cap>/spec.md` under a "Testing subpath" section
- [ ] 7.2 Move `openspec/changes/api-conformance-suites/` → `openspec/archive/<yyyy-mm-dd>-api-conformance-suites/`
- [ ] 7.3 Tick Stage 5 conformance-suites box in umbrella `openspec/changes/api-plugin-foundation/tasks.md`
- [ ] 7.4 Refresh `MANIFEST.md`