[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 the executable technical task owned by api-contracts under EPIC-05.

Problem

The current repository state does not yet provide verified, release-ready evidence to add runtime parity, examples, linting, and breaking-change conformance gates.

Goal

Add runtime parity, examples, linting, and breaking-change conformance gates with observable acceptance evidence and no divergence from the product-level contract.

Parent

• Primary Product Epic: EPIC-05
• Backlog ID: API-05

Scope

• Deliver the outcome stated in the title within the api-contracts implementation boundary.
• Reconcile affected contracts, tests, documentation, security, tenancy, observability, migration and release behavior.
• Retain acceptance evidence suitable for the Developer Platform product gate.

Out of Scope

• Creating a separate repository roadmap.
• Expanding into adjacent product domains without an accepted Product Epic or decision record.
• Claiming completion based only on code merge when operational or customer validation is required.

Acceptance Criteria

• The stated outcome is implemented or documented at the correct repository boundary.
• Expected, failure and recovery paths are covered by repeatable checks or retained evidence.
• Tenant isolation, authorization and sensitive-data behavior are reviewed where applicable.
• Public/internal contract and compatibility impacts are reconciled.
• Documentation, observability, migration/rollback and release notes are updated where applicable.
• Evidence is attached or linked and the parent Epic exit criteria are measurably advanced.

Technical Notes

Preserve canonical identifiers, provider-neutral public behavior, idempotency and backward compatibility. Prefer the existing modular-monolith boundary unless measured scale, security isolation or ownership requires extraction.

Dependencies

• Blocked by: API-01 through API-04
• Blocks: To be resolved during refinement.
• Cross-repository work: Link concrete Issues during refinement; do not duplicate their implementation here.

Planning Metadata

• Type: Technical Task
• Priority: P0
• Product milestone: Developer Platform
• Domains: api, devex
• Area: contract
• Complexity: M
• Initial status: Triage
• DRI: Unassigned
• Intended labels: type:technical-task, priority:p0, domain:api, domain:devex, area:contract

Definition of Done

• Acceptance criteria demonstrated.
• Required tests and evidence pass.
• Contracts are updated or confirmed unaffected.
• Security and tenant boundaries are reviewed.
• Migration and rollback paths are verified where applicable.
• Observability and runbooks are updated where applicable.
• Documentation and release notes are updated.
• Pull request(s) are merged and 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.