[API-01] Define draft, beta, stable, deprecation, and support semantics consistently

[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 define draft, beta, stable, deprecation, and support semantics consistently.

Goal

Define draft, beta, stable, deprecation, and support semantics consistently with observable acceptance evidence and no divergence from the product-level contract.

Parent

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

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 Foundation 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: None
• 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: Foundation
• Domains: api
• Area: contract
• Complexity: M
• Initial status: Triage
• DRI: Unassigned
• Intended labels: type:technical-task, priority:p0, domain:api, 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]

Contract progress: populated openapi/corelink-public-v1.yaml with a draft contract for the locally verified slice: tenant-scoped Device registration, Provisioning start/replay, Command queueing, and Tenant creation. It defines Bearer JWT, Idempotency-Key, canonical IDs, maturity=draft, schemas and 401/403/409 responses. YAML syntax and diff checks pass. Admin, internal and AsyncAPI documents remain incomplete; no stable SDK or full compatibility claim is made.

[jaavid]

AsyncAPI progress: populated asyncapi/corelink-events-v1.yaml with a draft v1 command-event channel (corelink.device.command.v1) and canonical event envelope. It is limited to runtime-registered command events and remains draft; telemetry/location and other events are not claimed as public until evidence exists. YAML and diff checks pass.

[jaavid]

Merged in PR #9 (merge commit 714d1fe). The compatible public contract baseline and compatibility workflow are now on the default branch; the attempted breaking replacement was removed after CI correctly rejected it.

[jaavid]

Closing API-01. The compatible 1.0.0-draft public contract baseline and canonical event envelope are merged in PR #9; compatibility policy documents draft/stable/deprecation/support semantics; public-openapi compatibility workflow passes for the merged baseline. Admin/internal contracts and stable SDK release remain separate follow-up work.