Initial Commit

openspec/changes/api-conformance-suites/proposal.md

@@ -0,0 +1,62 @@
+# api-conformance-suites — `./testing` subpath conformance functions for every abstract capability
+
+**Package**: multi-package — adds `./testing` subpaths to every Stage-1 abstract package
+**Status**: PROPOSED
+**Type**: feature (cross-package)
+**Stage**: 5 (Testing kit + conformance suites) — see umbrella `openspec/changes/api-plugin-foundation/`
+
+## Why
+
+Per design doc §13.4, every abstract capability ships a conformance suite under its `./testing` subpath. The pattern mirrors `@suaveplan/i18n-shared/testing`'s `runBackendConformance`: a single function that exhaustively pins the contract; every adapter (Stage 4 production AND Stage 5 in-memory) runs the suite; new adapters that pass the suite are automatically known good; new invariants added to the suite are automatically enforced across every existing adapter.
+
+This change adds those `./testing` subpaths. It's a multi-package change because each function lives in its respective abstract package — co-location matters (the contract owner owns the conformance gate). The companion in-memory adapters (Stage 5) provide the canonical "in-memory passes the suite" self-test, proving the suite isn't trivially empty.
+
+## What changes
+
+Adds a `./testing` export to each of the following abstract packages (created in Stage 1 — `api-router`, `api-auth`, `api-tenant-resolver` (currently inside `api-auth` umbrella), `api-tenant-provider`, `api-secrets`, `api-events`, `api-jobs`, `api-graphql`, `api-ws`, `api-sse`, `api-saga`, `api-2pc`, `api-db`). Each `./testing` subpath exports one conformance function:
+
+- ADDED: `@suaveplan/api-router/testing` → `runRouterConformance(label, factory)` — pins route registration, dispatch, blue-green slot semantics, streaming bypass.
+- ADDED: `@suaveplan/api-auth/testing` → `runAuthSessionConformance(label, factory)` — pins `resolveSession` contract, null-principal handling, securityScheme contribution.
+- ADDED: `@suaveplan/api-tenant-resolver/testing` (or `@suaveplan/api-auth/testing` namespace) → `runTenantResolverConformance(label, factory)` — pins chain-advance sentinel, principal-derived resolution.
+- ADDED: `@suaveplan/api-tenant-provider/testing` → `runTenantProviderConformance(label, factory)` — pins `list`, `listAsync`, mutation semantics.
+- ADDED: `@suaveplan/api-secrets/testing` → `runSecretsConformance(label, factory)` — pins `get`, manifest validation, redaction.
+- ADDED: `@suaveplan/api-events/testing` → `runEventsBusConformance(label, factory)` — pins publish/subscribe, ordering, idempotency, bounded-queue backpressure.
+- ADDED: `@suaveplan/api-jobs/testing` → `runJobsConformance(label, factory)` — pins schedule, runScheduled, perTenant fan-out.
+- ADDED: `@suaveplan/api-graphql/testing` → `runGraphqlEngineConformance(label, factory)` — pins schema merge, resolver execution, subscription delivery.
+- ADDED: `@suaveplan/api-ws/testing` → `runWsEngineConformance(label, factory)` AND `runWsBrokerConformance(label, factory)` — pins connection lifecycle (engine) and subscription fan-out (broker).
+- ADDED: `@suaveplan/api-sse/testing` → `runSseEngineConformance(label, factory)` — pins SSE stream lifecycle, reconnect-id handling.
+- ADDED: `@suaveplan/api-saga/testing` → `runSagaParticipantConformance(label, factory)` — pins step idempotency, compensation, replay safety.
+- ADDED: `@suaveplan/api-2pc/testing` → `run2pcParticipantConformance(label, factory)` — pins prepare/commit/rollback, in-doubt recovery.
+- ADDED: `@suaveplan/api-db/testing` → `runDbAdapterConformance(label, factory)` — pins admin vs scoped surfaces, tenant injection, migration runner, unsafe-queries gating.
+
+Self-tests:
+
+- ADDED: For each `runXConformance`, a self-test file (`src/testing/<name>.self-test.test.ts`) that runs the function against the Stage-5 in-memory adapter (or, for `api-router-hono`'s case, the direct surface) AND asserts that the run reports at least one passing invariant per category (sanity check: a conformance function that runs zero invariants is broken).
+
+## Out of scope
+
+- The abstract package interfaces themselves — those are Stage-1 changes (already proposed).
+- Adapter packages that consume these suites — those are separate changes (Stage 4 + Stage 5).
+- Runtime-only test helpers unrelated to capability conformance — those live in `@suaveplan/testing`.
+
+## Source mapping
+
+Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
+
+| Requirement | Design doc section |
+|---|---|
+| `./testing` subpath pattern (mirrors `i18n-shared/testing`) | §13.4 (intro) |
+| One conformance fn per capability | §13.4 (final paragraph) |
+| Same suite runs against every adapter | §13.4 (middle paragraph) |
+| New invariants automatically enforce across adapters | §13.4 (middle paragraph) |
+
+## Verification approach
+
+- Each conformance function lives at `packages/api/<abstract>/src/testing/<run-name>.ts` with a sibling `.md` documenting which invariants it pins (one bullet per `it(...)` title).
+- Each function's self-test (`<run-name>.self-test.test.ts`) calls it with the Stage-5 in-memory adapter as the factory and asserts non-empty pass count.
+- Each Stage-4 production adapter (in its own change) and each Stage-5 in-memory adapter (in its own change) runs the function against its own factory; those tests live in the adapter package, not here.
+- A dep-graph guard (`tests/dep-graph/conformance-subpath-shape.test.ts`) iterates every abstract package and asserts the `./testing` subpath export exists AND exports the expected `runXConformance` symbol.
+
+## Migration impact
+
+None — additive only. Existing abstract packages get a new subpath export; no existing import surface is touched.

openspec/changes/api-conformance-suites/specs/api-conformance-suites/spec.md

@@ -0,0 +1,182 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-conformance-suites (api-conformance-suites)
+
+**Package**: multi-package — `./testing` subpath additions on every abstract API package
+**Status**: PROPOSED
+
+> Each conformance function lives in its respective abstract package. This delta describes the invariants every function pins. The function itself is the executable enforcement; this spec is the human-readable contract.
+
+## ADDED Requirements
+
+### Requirement: runRouterConformance pins the Router contract
+
+`@suaveplan/api-router/testing` SHALL export `runRouterConformance(label, factory)` which executes a `describe` block of invariants covering: static route match, param route match wins, method routing, 404 on no match, duplicate-route rejection, middleware ordering, streaming bypass, blue-green slot atomic swap, in-flight completion on old slot, abort propagation, telemetry instruments emitted, error-envelope on throw, request-id propagation.
+
+#### Scenario: function runs at least one `it` per category
+
+- **WHEN** `runRouterConformance("self-test", createInMemoryRouter)` runs
+- **THEN** the test report contains at least one passing `it` titled per category (`"matches static routes"`, `"matches param routes"`, `"swaps blue-green atomically"`, ...)
+
+**Verified by:** `packages/api/api-router/src/testing/run-router-conformance.self-test.test.ts::"self-test reports passes across every documented category"`
+
+---
+
+### Requirement: runAuthSessionConformance pins the AuthSession contract
+
+`@suaveplan/api-auth/testing` SHALL export `runAuthSessionConformance(label, factory)` covering: resolves Principal from valid input, returns null on invalid/absent, never throws on malformed input (returns null + emits failure counter), `securitySchemeContribution()` returns a valid OpenAPI fragment.
+
+#### Scenario: self-test passes against api-auth-static-principal
+
+- **WHEN** `runAuthSessionConformance("self-test", () => createStaticPrincipalResolver({ principal: P }))` runs
+- **THEN** every invariant passes AND at least 4 distinct `it` titles report pass
+
+**Verified by:** `packages/api/api-auth/src/testing/run-auth-session-conformance.self-test.test.ts::"self-test against static-principal adapter passes every invariant"`
+
+---
+
+### Requirement: runTenantResolverConformance pins the TenantResolver chain contract
+
+The function SHALL cover: principal-with-tenantId returns it, principal-without advances chain (undefined sentinel), null-principal advances chain by default, `requirePrincipal` throws.
+
+#### Scenario: self-test passes against jwt-tenant-resolver
+
+- **WHEN** `runTenantResolverConformance("self-test", () => createJwtTenantResolver(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-tenant-resolver/src/testing/run-tenant-resolver-conformance.self-test.test.ts::"self-test against jwt resolver passes every invariant"` (or co-located inside `api-auth` if tenant-resolver lives there)
+
+---
+
+### Requirement: runTenantProviderConformance pins the TenantProvider contract
+
+The function SHALL cover: `list()` snapshot, `listAsync()` complete iteration, `get(id)` hit/miss, mutation semantics (`add`/`remove`/`update`) when mutable, immutability throws when not.
+
+#### Scenario: self-test passes against memory provider
+
+- **WHEN** `runTenantProviderConformance("self-test", () => createMemoryTenantProvider(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-tenant-provider/src/testing/run-tenant-provider-conformance.self-test.test.ts::"self-test against memory provider passes every invariant"`
+
+---
+
+### Requirement: runSecretsConformance pins the SecretsLike contract
+
+The function SHALL cover: `get(name)` returns string-or-undefined, manifest fail-fast on required missing, optional missing is silent, value redaction in errors and metric labels.
+
+#### Scenario: self-test passes against env adapter
+
+- **WHEN** `runSecretsConformance("self-test", () => createEnvSecrets(...))` runs with a controlled env fixture
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-secrets/src/testing/run-secrets-conformance.self-test.test.ts::"self-test against env adapter passes every invariant"`
+
+---
+
+### Requirement: runEventsBusConformance pins the EventBus contract
+
+The function SHALL cover: publish-then-subscribe ordering (FIFO), subscriber-idempotency by payload id, bounded-queue backpressure (when configured), interceptor chain, history of published payloads (where adapter supports it).
+
+#### Scenario: self-test passes against in-memory events bus
+
+- **WHEN** `runEventsBusConformance("self-test", () => createInMemoryEventsBus(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-events/src/testing/run-events-bus-conformance.self-test.test.ts::"self-test against in-memory bus passes every invariant"`
+
+---
+
+### Requirement: runJobsConformance pins the JobsRegistry contract
+
+The function SHALL cover: schedule registration, FakeClock-driven `runScheduled`, `perTenant: true` fan-out via TenantProvider, idempotent re-registration on hot reload, abort propagation on stop.
+
+#### Scenario: self-test passes against in-memory jobs registry
+
+- **WHEN** `runJobsConformance("self-test", () => createInMemoryJobsRegistry(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-jobs/src/testing/run-jobs-conformance.self-test.test.ts::"self-test against in-memory jobs registry passes every invariant"`
+
+---
+
+### Requirement: runWsEngineConformance and runWsBrokerConformance pin WS contracts
+
+`@suaveplan/api-ws/testing` SHALL export both:
+
+- `runWsEngineConformance(label, factory)` covering connection lifecycle, heartbeat, backpressure, reconnect-token semantics.
+- `runWsBrokerConformance(label, factory)` covering fan-out, subscribe/unsubscribe/cleanup, delivery mode semantics.
+
+#### Scenario: broker self-test passes against in-memory broker
+
+- **WHEN** `runWsBrokerConformance("self-test", () => createInMemoryWsBroker(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-ws/src/testing/run-ws-broker-conformance.self-test.test.ts::"self-test against in-memory broker passes every invariant"`
+
+---
+
+### Requirement: runSseEngineConformance pins the SSE contract
+
+The function SHALL cover: stream lifecycle, `id:` field for resume, retry hint, abort propagation.
+
+#### Scenario: self-test passes against a reference SSE engine
+
+- **WHEN** `runSseEngineConformance("self-test", referenceSseEngineFactory)` runs (the reference factory is provided in this change for the express purpose of the self-test; Stage 7 ships the production `api-sse-bun`)
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-sse/src/testing/run-sse-engine-conformance.self-test.test.ts::"self-test against reference engine passes every invariant"`
+
+---
+
+### Requirement: runSagaParticipantConformance pins the SagaParticipant contract
+
+The function SHALL cover: step idempotency, compensation execution on failure, replay safety on host restart, persisted state shape.
+
+#### Scenario: self-test passes against a reference saga participant
+
+- **WHEN** `runSagaParticipantConformance("self-test", referenceParticipantFactory)` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-saga/src/testing/run-saga-participant-conformance.self-test.test.ts::"self-test against reference participant passes every invariant"`
+
+---
+
+### Requirement: run2pcParticipantConformance pins the 2PC contract
+
+The function SHALL cover: prepare returns vote, commit/rollback after vote, in-doubt recovery on restart, prepared-transaction cap honoured.
+
+#### Scenario: self-test passes against a reference 2PC participant
+
+- **WHEN** `run2pcParticipantConformance("self-test", reference2pcParticipantFactory)` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-2pc/src/testing/run-2pc-participant-conformance.self-test.test.ts::"self-test against reference 2pc participant passes every invariant"`
+
+---
+
+### Requirement: runDbAdapterConformance pins the Db contract
+
+The function SHALL cover: admin surface SELECT/INSERT, scoped surface tenant injection, cross-tenant rejection, migration runner forward+idempotent+failure, unsafe-queries capability gating + counter emission.
+
+#### Scenario: self-test passes against in-memory SQLite
+
+- **WHEN** `runDbAdapterConformance("self-test", () => createSqliteMemoryDb(...))` runs
+- **THEN** every invariant passes
+
+**Verified by:** `packages/api/api-db/src/testing/run-db-adapter-conformance.self-test.test.ts::"self-test against in-memory sqlite passes every invariant"`
+
+---
+
+### Requirement: Every `./testing` subpath is reachable and exports the expected symbol
+
+A dep-graph guard SHALL iterate every abstract API package, resolve `./testing`, and assert the documented `runXConformance` symbol is present and is a callable.
+
+#### Scenario: every abstract package exposes its conformance function
+
+- **WHEN** the dep-graph guard runs
+- **THEN** each abstract package's `./testing` subpath exports the documented symbol AND the symbol is a function with at least two parameters (label, factory)
+
+**Verified by:** `tests/dep-graph/conformance-subpath-shape.test.ts::"every abstract API package exposes its conformance function under ./testing"`
+
+<!-- markdownlint-enable MD024 -->

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

@@ -0,0 +1,75 @@
+# 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`