suaveplan/openspec/archive/2026-04-27-testing-integration-spec-and-generics-hardening/tasks.md

Tasks — testing-integration spec authoring + generics hardening

1. Spec authoring

• 1.1 Read openspec/AGENTS.md Sections 13 and 14
• 1.2 Draft proposal.md (genesis-original; no source mapping section)
• 1.3 Draft specs/testing-integration/spec.md — every requirement carries **Verified by:**
• 1.4 Draft six variant spec files — every requirement carries **Verified by:**

2. Plumbing

• 2.1 Move vitest to peerDependencies on @suaveplan/testing-integration
• 2.2 Move @suaveplan/testing-integration and testcontainers from dependencies to peerDependencies on all six variants; add to devDependencies
• 2.3 Move _fixtureRegistry, _createIntegrationSetupWithInject, _createSkipIfUnavailableWithInject to src/internal/ (not exported in package.json)
• 2.4 Public barrel re-exports only the supported surface
• 2.5 mailpit adds zod to dependencies (catalog:forms)

3. Generics

• 3.1 TestEnvironment<TFixtures extends DefaultFixtureMap = DefaultFixtureMap> — setup() returns precise configs shape
• 3.2 HealthPoller.poll<TConfig> — accepts Pick<ServiceFixture<TConfig>, "name" | "healthCheck">
• 3.3 skipIfUnavailable<TName extends string = string> — typed-registry friendly
• 3.4 expectTypeOf pins in test-environment.spec-conformance.test.ts
• 3.5 assertMail Zod-validated, throws TestEnvironmentError
• 3.6 GarageS3Fixture.waitForHealth delegates to HealthPoller.poll(this)

4. Documentation

• 4.1 New sibling .md for every new internal/*.ts
• 4.2 Updated create-integration-setup.md, assert-mail.md, garage-s3-fixture.md to reflect API changes

5. Pre-archive verification (5-gate triple, all 7 packages)

• 5.1 bun run check — Biome 0/0/0 across the monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/testing-integration{,-*} green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/testing-integration{,-*} 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/testing-integration{,-*} exit 0
• 5.5 bunx turbo build --filter=@suaveplan/testing-integration{,-*} green

6. Pre-archive 7-row checklist

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at the assertMail boundary
• 6.3 TestEnvironmentError thrown by every documented error path (HealthPoller, assertMail non-2xx / timeout / shape mismatch)
• 6.4 Strict-mode behaviors covered (passthrough mode tests + container mode tests)
• 6.5 OTel — N/A; testing-infrastructure packages do not register OTel
• 6.6 Lifecycle dedup — setup() re-clears started so double-teardown is safe; tested
• 6.7 No retroactive tick — every box reflects work done in this change

7. Archive

• 7.1 Fold spec deltas into openspec/specs/testing-integration{,-*}/spec.md
• 7.2 Move change folder → openspec/archive/2026-04-27-testing-integration-spec-and-generics-hardening/