The source is the actual DRF serializers and view annotations. build.mjs converts Swagger 2 to OpenAPI 3, adds the source-record discriminated variants and the named ordering enum with comma-separated ordering, then validates the resulting document. Do not edit src/core/openapi.json or generated TypeScript by hand.

From the backend root (Python dependencies installed with uv):

PYTHONPATH=src uv run python src/manage.py generate_swagger tools/openapi/swagger.json --overwrite --format=json --settings=settings.test
cd tools/openapi
bun install --frozen-lockfile --ignore-scripts
bun build.mjs
bun run apigen
bun run type-check

The runtime gate also validates rendered responses from the real DRF list/detail views against Orval's generated Zod schemas, including every documented HTTP status. Generate its synthetic fixtures in the isolated test database, then run:

# From the backend root. The parent directory of this explicit path must exist.
OPENAPI_RUNTIME_FIXTURES=/tmp/mostovik-openapi-runtime.json PYTHONPATH=src uv run pytest tests/apps/organizations/test_openapi_runtime_fixtures.py -q
cd tools/openapi
bun run apigen
bun run contract-check /tmp/mostovik-openapi-runtime.json

Zod is pinned to 4.3.6. The gate covers a full Budget payload with unknown raw fields, all five SME size units, nullable SRO admission dates, mixed/filtered lists, empty arrays and zero counts, and 400/404 errors. Parsed responses must equal the original JSON so that an apparently successful parser cannot silently discard raw keys. Ordinary pytest runs write no fixture file; writing is enabled only by OPENAPI_RUNTIME_FIXTURES. No live upstream requests or business databases are used. The generated validators are disposable build output, never handwritten.

Bun is pinned to 1.3.9 in CI; the tool dependencies are locked in bun.lock. CI regenerates the source Swagger document, runs bun build.mjs --check, generates a client and compiles a strict TypeScript fixture. It fails if the bundled contract is stale, invalid, loses discrimination, or removes the named ordering enum.

For the frontend, copy the bundled document to its openapi.json, then run its own bun run apigen and bun run type-check. Keep source-group checks before reading source-specific payloads. Multipart upload operations now have one accurately documented content type, so Orval generates ...Mutation rather than the former multi-content-type ...MutationWithFormData name. The generated function still constructs FormData and sends multipart data.

Before accepting an upgraded live dataset:

python src/manage.py migrate --noinput
python src/manage.py normalize_published_registry_payloads
python src/manage.py normalize_published_registry_payloads --apply
python src/manage.py build_source_record_exports

The first normalization command is a dry run. Applying it preserves record UIDs, publication timestamps and artifact IDs, but atomically increments the affected artifact content revisions. New export tickets return 503 until a matching export generation is built; already issued tickets keep their pinned generation. SRO access remains gated as described in docs/sro-membership-source.md.