[API-05] Add runtime parity, examples, linting, and breaking-change conformance gates

[jaavid]

Background

CoreLink is managed as one product across multiple implementation repositories. This work is owned by api-contracts under EPIC-05.

Problem

The previous dependency model made API-05 wait for API-02, API-03 and API-04 as one all-or-nothing block. That creates a release-train deadlock: the already-reviewed Device/Command contract and the next API-02 slice cannot gain reproducible parity/conformance evidence until unrelated future partner/event surfaces are also complete.

Goal

Build incremental contract parity/conformance gates that can accept each version-identifiable public slice independently while preserving one compatibility policy.

Execution model

Phase A — existing public baseline

Validate v1.0.0-draft Device + Command:

• OpenAPI/schema lint and reference integrity;
• representative positive/auth/tenant/error/idempotency examples;
• runtime route/schema parity for the supported baseline;
• breaking-change comparison against the previous immutable contract input;
• immutable provenance output usable by generated SDKs.

Phase B — API-02

When API-02 publishes an accepted/version-identifiable Asset/binding/telemetry/location/alert subset, run the same parity/conformance pipeline for that subset without waiting for API-03/API-04.

Phase C — API-03/API-04

Add partner/commercial/event/webhook slices as they become version-identifiable and acceptance-ready.

Acceptance criteria

• Device/Command baseline can pass/fail parity independently of unfinished API-02/03/04 work.
• Every accepted contract slice identifies exact contract SHA/tag and runtime revision used for parity.
• Lint/reference/example checks are deterministic and fail closed.
• Breaking-change detection compares immutable inputs and produces reviewable evidence.
• Runtime parity distinguishes missing runtime behavior, intentional draft behavior and supported behavior.
• Tenant/auth/error/idempotency examples are covered for each supported slice.
• Provider-specific runtime fields cannot silently enter the public contract through parity generation.
• Machine-readable provenance is consumable by TS-01/PY-01/JAVA-01 generation workflows.
• API-02, API-03 and API-04 can join the gate incrementally rather than becoming mutual blockers.

Dependencies

• Prerequisite completed: API-01.
• Phase A: no API-02/API-03/API-04 blocker; execute against the existing immutable Device/Command baseline now.
• Phase B input: API-02.
• Phase C inputs: API-03 and API-04.
• Blocks: TS-01, PY-01, JAVA-01 reproducible generation; MOCK-01 contract-driven baseline; Developer Platform compatibility evidence.

Definition of Done

• Phase A parity/conformance is implemented and retained against immutable inputs.
• The gate accepts additional contract slices without redesigning the pipeline.
• SDK generation can consume exact provenance output.
• Compatibility/runtime-parity docs are reconciled.
• Pull request(s), CI evidence and exact contract/runtime revisions are linked.

[jaavid]

Progress evidence

PR #11 merged as 7cc2132. Added scripts/lint_contracts.rb, which validates operation IDs, stability metadata, responses, and Postman collection/environment JSON. The GitHub compatibility workflow now runs this structural gate.

Local validation passed: contract lint, OpenAPI YAML parse, public compatibility checker, and git diff --check. API-05 remains open until API-02 through API-04 and runtime parity/generated-client evidence are complete.