feat: add the client contract, fixtures and contract scenarios

CONTEXT.md

@@ -122,9 +122,21 @@ _Avoid_: using this word for a Gatepost component
 ### Gatepost
 
 **Spec**:
-The `spec` repo. It holds the grammar, the data, the vectors and the standards. The API fixtures and the completed OpenAPI file come later.
+The `spec` repo. It holds the grammar, the client contract, the data, the vectors, the fixtures, the completed OpenAPI file and the standards.
 _Avoid_: schema, contract (for the repo)
 
+**Contract scenario**:
+One shared test case in `spec/contract/`. It names the calls, the mock server's responses and the outcome that every client must reach.
+_Avoid_: contract test (for the file), vector, fixture
+
+**Attempt**:
+One request that a client sends for one call. A retry is the second or third attempt.
+_Avoid_: try, request (when you count them)
+
+**Evidence**:
+How Gatepost knows the shape of a gateway response: `observed` in its own calls, `documented` by NIPOST only, or `assumed` by the mock server.
+_Avoid_: source, confidence, proof
+
 **Vector**:
 One shared test case in `spec/vectors/` that every SDK must pass.
 _Avoid_: fixture, example, golden file

Makefile

@@ -1,6 +1,6 @@
 # SPDX-FileCopyrightText: 2026 The Gatepost authors
 # SPDX-License-Identifier: Apache-2.0
-.PHONY: check test vectors tells lint types licences actions
+.PHONY: check test vectors contract tells lint types licences actions
 
 # Each tool has an exact version. A new release can add rules and turn CI red on a change that
 # has nothing to do with it. Renovate opens the pull requests that move these versions.
@@ -14,18 +14,37 @@ REUSE_VERSION := 6.2.0
 CHARSET_NORMALIZER_VERSION := 3.5.2
 # renovate: datasource=pypi depName=zizmor
 ZIZMOR_VERSION := 1.30.1
+# renovate: datasource=pypi depName=pyyaml
+PYYAML_VERSION := 6.0.3
+# renovate: datasource=pypi depName=jsonschema
+JSONSCHEMA_VERSION := 4.26.0
+# renovate: datasource=pypi depName=types-pyyaml
+TYPES_PYYAML_VERSION := 6.0.12.20260906
+# renovate: datasource=pypi depName=types-jsonschema
+TYPES_JSONSCHEMA_VERSION := 4.26.0.20260518
+# renovate: datasource=pypi depName=openapi-spec-validator
+OPENAPI_SPEC_VALIDATOR_VERSION := 0.9.0
 
 # scripts/check-tells has no .py suffix, so the tools need its name.
 SCRIPTS := scripts scripts/check-tells
 
-check: test vectors tells lint types licences actions
+# The checks of the OpenAPI file read YAML and JSON Schema. uv adds the two packages to the
+# Python on PATH, so each Python of the CI matrix runs the tests.
+PYTHON := uv run --no-project --python-preference only-system \
+	--with pyyaml==$(PYYAML_VERSION) --with jsonschema==$(JSONSCHEMA_VERSION) python3
+
+check: test vectors contract tells lint types licences actions
 
 test:
-	python3 -m unittest discover -s scripts/tests -t scripts
+	$(PYTHON) -m unittest discover -s scripts/tests -t scripts
 
 vectors:
 	python3 scripts/build_vectors.py --check
 
+contract:
+	uvx openapi-spec-validator@$(OPENAPI_SPEC_VALIDATOR_VERSION) openapi/gateway.completed.yaml
+	$(PYTHON) scripts/contract_files.py
+
 tells:
 	python3 scripts/check-tells
 
@@ -34,7 +53,8 @@ lint:
 	uvx ruff@$(RUFF_VERSION) format --check $(SCRIPTS)
 
 types:
-	uvx mypy@$(MYPY_VERSION)
+	uvx --with types-pyyaml==$(TYPES_PYYAML_VERSION) \
+		--with types-jsonschema==$(TYPES_JSONSCHEMA_VERSION) mypy@$(MYPY_VERSION)
 
 # reuse needs an encoding detector, and uvx installs reuse without one.
 licences:

README.md

@@ -9,12 +9,16 @@ The shared contract for every Gatepost SDK: the postcode grammar, the data files
 | Path | Holds |
 |---|---|
 | `grammar.md` | how every SDK reads and writes postcodes, and the public interface |
+| `client.md` | how every client calls NIPOST's gateway: results, errors, retries and the queue |
+| `openapi/` | NIPOST's gateway, completed with the responses that its own file leaves out |
+| `fixtures/` | synthetic gateway responses and keys for the mock server |
+| `contract/` | shared client test cases that every client must pass against the mock server |
 | `data/` | state codes, GPS accuracy limits and the postcode format |
 | `vectors/` | shared test cases that every SDK must pass |
 | `standards/` | the coding standards and one file for each language |
 | `CONTEXT.md` | the glossary |
 | `templates/` | files for new repos |
-| `scripts/` | `check-tells`, the vector builder, and a plain reading of the grammar that checks each vector |
+| `scripts/` | `check-tells`, the vector builder, a plain reading of the grammar that checks each vector, and the checks of the OpenAPI file, the fixtures and the scenarios |
 
 ## Check
 

VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0