Initial Commit

openspec/changes/enterprise-testing-contract/specs/api-schemas/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Consumer-side pact recording over envelope shapes
+
+The `@suaveplan/api-schemas` package SHALL ship an `api-schemas.contract.test.ts` that uses `recordPactInteraction` from `@suaveplan/testing-contract` to record interactions exercising every envelope shape defined in the package: `common` (pagination, sort, filter, id-param, error-envelope), `auth` (login, register, refresh, logout, context), `admin` (ping, health, status), and `events` (domain-event, envelope, metadata). The resulting pact file MUST be committed to `pacts/api-schemas__enterprise-api.json`.
+
+#### Scenario: Every envelope shape is exercised
+
+- **WHEN** the consumer-side test suite runs
+- **THEN** `pacts/api-schemas__enterprise-api.json` contains at least one interaction whose request or response body matches each of `common`, `auth`, `admin`, and `events`
+
+#### Scenario: Schema drift produces reviewable diff
+
+- **WHEN** an `api-schemas` change renames a field on the `auth.login` request envelope
+- **THEN** the diff against `pacts/api-schemas__enterprise-api.json` is non-empty AND surfaces in PR review before the corresponding API plugin is updated
+
+### Requirement: Pact-recorded shapes parse cleanly under the package's Zod schemas
+
+Every recorded request and response body in the committed pact file MUST parse successfully under the matching Zod schema exported from `@suaveplan/api-schemas`. A validation step in the consumer-side test SHALL enforce this contract.
+
+#### Scenario: Recorded body conforms to its Zod schema
+
+- **WHEN** the test parses each `interactions[].request.body` and `interactions[].response.body` under the matching exported Zod schema
+- **THEN** every parse succeeds AND no `ZodError` is thrown