Endpoint Comparison APIs

Endpoint Comparison APIs create continuous endpoint comparisons, control indefinite runs, retrieve aggregate and request-level evidence, and select one final endpoint behind an existing interlay.

Arenas

An arena accepts 2 to 16 unique same-organization direct endpoints matching the source interlay's endpoint kind. The compiled runtime must register an endpoint-comparison adapter for that kind. The caller needs shared endpoint READ and WRITE permission for the serving endpoint and every contender. Sample ratio is greater than zero and at most one, queue and concurrency limits must be positive, and retention is between 1 and 365 days.

Arena and immutable run responses expose source_endpoint_kind, per-contender endpoint_kind, protocol_family, comparison_scope, comparison_semantics, adapter ID/version, probe capabilities, and identity dispatch-plan kind/version. Current arenas are homogeneous.

Runs

Only one active run may use an interlay. Running and paused runs are restored after Eden restarts. Interrupted completion either finalizes an already-applied selection, restores the untouched run to its prior state, or fails an ambiguous state for review. Normal interlay patches cannot replace the endpoint while a run is active.

Evidence

The request list accepts limit from 1 to 500 and an optional run-scoped before comparison ID. The cursor can continue through the retained run window rather than only the latest summary page. Each observation includes queue_delay_us, the compatibility field latency_us, explicit dispatch_latency_us, and total_latency_us. Canonical digests appear only for canonical adapters; LLM observations may include time-to-first-token, token-unit, and estimated-cost fields.

Completion

{
  "selected_endpoint_uuid": "endpoint-uuid",
  "expected_interlay_revision": "revision-from-interlay-response",
  "acknowledge_warnings": true,
  "data_readiness_evidence_ref": "change/CHG-1842"
}

Preflight validates adapter compatibility, endpoint health, direct routing, retained permissions, recent successful evidence, migration state, and the optimistic interlay revision. It always warns that write delivery is best effort. Known write gaps or evidence-sink loss block completion unless data_readiness_evidence_ref contains a printable external evidence reference of at most 512 characters and warnings are acknowledged.

Completion is idempotent for the same endpoint. It drains accepted comparisons for up to 30 seconds, restores the prior endpoint and run state on failure, and preserves the interlay address and governance settings. It does not synchronize endpoint data.

Protocol Semantics

Eligible writes are dispatched best effort and surfaced through attempt, success, drop, and gap counts. Read attempts, successes, and comparison gaps are reported separately. Endpoint comparison is not a replication API.