suaveplan/openspec/archive/2026-05-26-api-host-testing-kit/proposal.md

api-host-testing-kit — Populate Stage-5 ./testing subpath

Why

@suaveplan/api-host/testing has shipped a STAGE_2_RESERVED sentinel since Stage 2. Stage 5 in-memory adapters (api-router-in-memory, api-auth-static-principal / api-auth-anonymous, api-db-sqlite-memory, api-events-in-memory, api-ws-broker-in-memory, api-tenant-provider-memory, api-secrets-env) have all shipped, but no host-side composition surface drives them together. Plugin authors writing integration tests have to hand-wire every adapter slot at the call site — the same boilerplate observed in e2e/foundation-stack/src/server.ts. The keystone for the Stage-5 testing kit is a createTestHost(config?) factory that composes every default in one line.

What changes

• Replace STAGE_2_RESERVED placeholder with the full createTestHost(config?) factory under src/testing/create-test-host/.
• Surface flips: the sentinel constant changes from true to false (back-compat preserved — consumers that branched on === true still compile; the populated helpers ship alongside).
• New types: TestHostConfig, TestHostSeed, TestHostAdapters, TestHost, FixturePluginInstall, FixtureRouteRegistration.
• TestHost extends Host with installFixturePlugin, fetchAs, waitForEvent, dispose.
• Default adapter resolution per-slot, override-beats-default semantics.
• seed.principal / seed.tenants / seed.secrets populate the default adapter inputs.
• Companion smoke at e2e/foundation-stack-test-host/ boots a Bun.serve over createTestHost(...) and drives every wired slot through real HTTP with Playwright.
• suaveplan.conformanceSkip for api-lifecycle / api-loader / api-manifest / api-secrets retained (api-host is the consumer/driver, not the implementer); the gap is documented in README + this proposal.

Impact

• Affected specs: api-host
• Affected code: packages/api-stack/api/api-host/src/testing/*, packages/api-stack/api/api-host/package.json (peerDependenciesMeta + new devDependencies for the in-memory adapters), e2e/foundation-stack-test-host/* (new workspace).
• Affected downstream: every package previously branching on STAGE_2_RESERVED === true can now opt into the populated helper; no breaking change.