Exact observation contracts

An observation contract is more than an event name. Compatibility requires the complete tuple:

observation type
+ positive contract version
+ RFC 8785 canonical payload schema
+ SHA-256 digest of canonical schema bytes plus newline

The package owns the semantic payload schema because the package owns meaning. The connector declares that exact reviewed contract because it promises to emit matching evidence.

Example

{
  "type": "darts.autodarts.throw",
  "contractVersion": 1,
  "payloadSchemaSha256": "…",
  "payload": {
    "segment": 20,
    "multiplier": 3
  }
}

bull and outer_bull are domain observations, not invalid segment numbers. The active mode decides whether they score, advance a target, or count as a miss. That interpretation cannot live in the AutoDarts connector.

Stable source-event identity

The connector derives an event key from stable source facts whenever possible: source ID, upstream sequence, round/visit key, and event index. Reconnect and replay of the same upstream event must produce the same identity.

Do not use local arrival time or a random UUID when the source provides stable identity. The host deduplicates before authoritative transition application.

Canonical schema

Packing canonicalizes JSON Schema with RFC 8785, appends one newline, and hashes those bytes. This removes whitespace and object-key-order ambiguity while making any meaningful schema change explicit.

Structurally similar payloads with different schema digests are intentionally incompatible. Publish a new contract version and coordinate package/connector support rather than guessing across versions.

Bound the payload

Use the narrowest semantic facts the Practice Mode needs. Avoid raw video, screenshots, unbounded logs, arbitrary nested metadata, provider credentials, or entire upstream responses. High-frequency telemetry should remain local; emit bounded domain observations.