suaveplan/openspec/archive/2026-04-29-testing-spec-conformance/proposal.md

OpenSpec Change: testing-spec-conformance

• Change ID: testing-spec-conformance
• Package: @suaveplan/testing
• Status: PROPOSED
• Date: 2026-04-26

Summary

Close five drift items uncovered by bun scripts/openspec-conformance.ts @suaveplan/testing:

1. **Verified by:** lines on every requirement in openspec/specs/testing/spec.md (15 reqs, all owned by this package).
2. Thread a <TBody = unknown> generic through RequestBuilder, ResponseBuilder, TestRequest, TestResponse, and the corresponding *BuilderState types so consumers can pin the body type at the call site instead of the public d.ts leaking five : unknown positions.
3. Add a tests/spec-conformance.spec-conformance.test.ts pinning the new generic threading via expectTypeOf, the dual-runner / sideEffects / subpath-export package-shape assertions, the schemas-leaf-isolation check, and the module-scope determinism scan (Math.random / Date.now / performance.now allow-list).
4. Replace the wall-clock fallback in measureTime and withObservability with the existing injectable Clock substrate (defaultClock by default, FakeClock when injected). Removes the last two non-deterministic call sites in src/ outside the allow list.
5. Tighten scripts/openspec-conformance.ts: stop matching change folders by token-substring on the folder name (which over-matched 226 reqs across enterprise-testing-dom, enterprise-testing-e2e, enterprise-ab-testing, enterprise-network-testing, etc.). Match only via **Package**: @suaveplan/<pkg> in proposal.md frontmatter, and only pull active-change specs/<cap>/spec.md deltas from changes whose proposal explicitly names this package.

After this change, bun scripts/openspec-conformance.ts @suaveplan/testing exits 0.

Current state

@suaveplan/testing is structurally solid (Layer 0, zero @suaveplan/* workspace deps, 295 passing tests, structured TestingError hierarchy with stable TESTING.<DOMAIN>.<REASON> codes, dual-runner subpath exports, sideEffects: false, fast-check property tests, mitata bench harness). Conformance gaps are documentary plus two real drift items:

• 35/35 requirements lacked **Verified by:** lines (down from 226 once the conformance script's over-matching was fixed).
• 5 public d.ts positions resolved to : unknown (request-builder.types.d.ts, response-builder.types.d.ts, http.types.d.ts x2, fixture-manager-internals.d.ts).
• 2 wall-clock fallback sites (measureTime, withObservability) bypassed the Clock substrate documented by the spec's "Module-scope non-determinism absent" scenario.
• The conformance script over-matched on folder-name tokens, pulling in unrelated testing-* change folders.

What changes

1. Add **Verified by:** lines under every ### Requirement: block in openspec/specs/testing/spec.md. Citations name real it(...) test titles in src/**/*.test.ts and tests/*.test.ts.
2. Thread <TBody = unknown> through RequestBuilder, ResponseBuilder, RequestBuilderState, ResponseBuilderState, TestRequest, and TestResponse. Default generic preserves the existing unknown surface for zero-config callers.
3. Add tests/spec-conformance.spec-conformance.test.ts:
   • expectTypeOf assertions over RequestBuilder<UserPayload> / ResponseBuilder<UserPayload> so the generic threading regresses loudly.
   • package.json shape: sideEffects === false, every public surface has a subpath export.
   • Module-scope determinism: scan src/ for Math.random( / Date.now( / performance.now( outside the allow list (context, fake-clock, memory-store).
   • Schema-bundle isolation: *.schemas.ts files do not import their sibling implementation file.
4. measureTime(fn, { clock }) and withObservability({ ..., clock }) now route every wall-clock read through defaultClock (default) or a caller-supplied Clock. Behaviour identical for zero-config callers.
5. scripts/openspec-conformance.ts swaps the folder-name token regex for a frontmatter check and only pulls active-change specs/<cap>/spec.md deltas from changes explicitly tagged **Package**: @suaveplan/<pkg>.

Impact

• Public API: additive — RequestBuilder, ResponseBuilder, TestRequest, TestResponse gain an optional <TBody> generic with unknown default. measureTime and withObservability gain an optional clock option.
• Tests: 7 new it blocks under tests/spec-conformance.spec-conformance.test.ts. Existing 295 tests unchanged.
• Spec: 15 **Verified by:** lines folded into openspec/specs/testing/spec.md. Two stale packages/universal/testing/ path references corrected to packages/dev/testing/.
• Tooling: scripts/openspec-conformance.ts matching tightened. Affects every package's audit but downward-only (fewer false-positive folders).