[API-02] Expand public v1 contracts for Assets, bindings, telemetry, location, and alerts

[jaavid]

Background

CoreLink is managed as one product across multiple implementation repositories. This work is owned by api-contracts under EPIC-04 and is now the primary contract-expansion step after the hosted v0.2.0-alpha.8 runtime proved real asset/device/position/telemetry behavior.

Goal

Publish the next version-identifiable public v1 slice for Assets, bindings, telemetry, location and alerts without exposing provider-specific identifiers, protocol names or raw provider payloads.

Immediate execution slice

Use the accepted hosted-alpha runtime behavior as implementation input, but keep the contract narrower than runtime where acceptance is incomplete.

Prioritize:

1. Asset collection/detail read models required by Console.
2. Device↔Asset binding/association semantics using canonical CoreLink IDs.
3. Latest canonical telemetry/state read model.
4. Latest position + bounded position/history read model.
5. Alert read/acknowledgement only where runtime behavior is already acceptance-ready.

Explicitly keep provider-local fields such as provider IDs, adapter names and protocol names outside the public contract.

Acceptance criteria

• Asset collection/detail is versioned with tenant-safe pagination/error semantics.
• Binding semantics use canonical CoreLink resource IDs and define lifecycle/conflict behavior.
• Latest telemetry/state exposes canonical fields and an extensibility model without provider payload leakage.
• Position/history contract defines timestamps, ordering, pagination/limits and tenant isolation.
• Alert operations included in this slice map to accepted runtime behavior; unsupported alert operations remain explicitly draft/deferred.
• Cross-tenant/insufficient-scope behavior fails closed and is represented in examples/tests.
• Contract examples are representative of the alpha.8 canonical runtime, not provider wire payloads.
• Compatibility impact and migration notes are documented.
• API-05 can run parity/conformance against this slice independently of API-03/API-04 completion.

Dependencies

• Prerequisite completed: API-01.
• Runtime input: PLAT-04 remains the full Product Acceptance gate, but alpha.8 implementation evidence is sufficient to draft/version the supported subset with explicit maturity.
• Blocks: API-05 incremental parity/conformance, CONSOLE-01 canonical read-model reconciliation, TS/PY regeneration for the expanded surface, DOCS-03 and downstream mock/conformance work.

Definition of Done

• Accepted/draft maturity is explicit per operation.
• OpenAPI/schema validation and examples pass.
• Provider-neutrality, tenant isolation and authorization boundaries are reviewed.
• API-05 parity can target the exact resulting revision.
• Affected Console/SDK/docs compatibility records are updated.
• Pull request(s), exact contract SHA/tag and runtime evidence links are retained.

[jaavid]

Dependency clarification

Platform PR #167 (e9996b8) published the closure checklist. API-02 remains blocked on PLAT-04 canonical telemetry/position/latest-state/history behavior; once that contract is frozen, API-02 can add the public asset/binding/telemetry/location/alert surfaces and runtime parity evidence.

[jaavid]

Release-train priority update: this issue now carries the Hosted Alpha Console contract cutover required by product-planning#20. The first additive slice should cover the currently accepted Console journeys in dependency order: canonical Asset collection/get + Asset↔Device binding, provisioning execute, telemetry latest/position/history, then alerts/connectors/entitlements/geofence only where runtime semantics are accepted. The goal is to make api-contracts the normative source consumed by @corelink/sdk, not to mirror every internal Platform route. Provider-local Traccar/OpenRemote identifiers remain internal.

[jaavid]

Runtime expansion evidence — operational intelligence P0

Platform PR CoreLinkPlatform/platform#245 adds new runtime-alpha CoreLink-owned operational surfaces that should be evaluated as follow-on API-02 slices only after their runtime acceptance gates pass:

• canonical operational state: online/motion/ignition/operational_status;
• Trips and Stops;
• polygon/corridor geofences;
• alert notification channels/rules/delivery history;
• provider-neutral command capabilities/templates;
• basic daily activity reports.

These runtime endpoints must not automatically become accepted public v1 contracts merely because they are present in runtime OpenAPI. API-02/API-05 should admit them incrementally after tenant-isolation, error/pagination, request/response schema and maturity evidence is retained. Provider/adapter/protocol/raw-command fields remain excluded.