[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 created a release-train deadlock: already-reviewed Device/Command and the next API-02 slice could not gain reproducible conformance evidence until unrelated future partner/event surfaces were 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 auth/tenant/error/idempotency contract coverage;
• breaking-change comparison against the immutable baseline;
• immutable provenance usable by generated SDKs;
• exact Platform runtime route parity for the supported baseline.

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.

Current evidence — 2026-08-30

Contract-side Phase A

• Contract compatibility workflow runs on Blacksmith and compares the candidate public contract against immutable v1.0.0-draft.
• Parse/lint/breaking-change checks remain fail-closed.
• The workflow records candidate SHA and OpenAPI blob provenance.
• Blacksmith run 33277044723 passed on contract commit 3fbfa73474de7bb61f9070322d81c35a92ab4919.

Runtime-side Phase A

• Platform now has a dedicated Public Contract Runtime Parity Blacksmith workflow.
• It fetches the immutable v1.0.0-draft contract, extracts every public HTTP path/method and verifies the exact Platform runtime OpenAPI contains those operations.
• It additionally fails if provider/internal routes leak into the public runtime OpenAPI boundary and uploads contract/runtime evidence containing the exact runtime SHA.
• Blacksmith run 33277220867 passed on Platform commit 87b1a01ef75f89c3feb5022e4f209fa575b742f2.

SDK provenance consumers

• TS-01 completed; Blacksmith run 33277002040 passed.
• PY-01 completed; Blacksmith run 33277017639 passed.
• JAVA-01 completed; Blacksmith run 33277037833 passed.

Phase A now has executable immutable contract compatibility plus exact-runtime route parity and SDK provenance. Deeper request/response schema parity and full examples remain active hardening work and API-05 therefore stays open until that evidence is added.

Acceptance criteria

• Device/Command baseline can pass/fail independently of unfinished API-02/03/04 work.
• Current accepted baseline identifies exact contract tag/commit and exact runtime SHA for route parity.
• Lint/reference checks are deterministic and fail closed.
• Breaking-change detection compares immutable inputs and produces reviewable evidence.
• Runtime route/method parity distinguishes a missing supported operation and provider/internal route leakage.
• Runtime request/response schema parity is fully automated for the accepted operation set.
• Tenant/auth/error/idempotency examples are fully covered for each supported slice.
• Provider-specific runtime routes are excluded from the public runtime OpenAPI parity boundary.
• Immutable 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 remaining hardening: request/response schema parity and fuller examples.
• Phase B input: API-02.
• Phase C inputs: API-03 and API-04.
• No longer blocked: TS-01, PY-01 and JAVA-01 generation-provenance baselines are completed.
• Still blocks: full MOCK-01 contract-driven baseline and complete Developer Platform compatibility acceptance.

Definition of Done

• Phase A immutable contract compatibility and exact-runtime route parity are implemented and retained.
• The gate accepts future slices without redesigning the pipeline.
• SDK generation consumes exact immutable provenance.
• Request/response schema parity and required examples are added for the accepted baseline.
• Compatibility/runtime-parity docs are reconciled with the complete evidence set.
• 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.