Preserve device evidence in an AI integration

ALYT treats device evidence as separate facts: a requested value, an accepted command, a transport acknowledgement, and an observed device result are not the same thing. In an AI integration, read device state through the installed context and report state only through the approved connector path. Preserve producer evidence exactly, keep authorization and execution distinct, and treat missing or partial history as incomplete rather than proof that nothing happened. Opening a state view does not probe a device or establish execution permission. Event IDs, source epochs, and sequence values remain part of the original retained record, and ordinary state reporting cannot replace live evidence or introduce a transient press.

Use the installed reporting contract

Report observations only through the reporting interface approved for your installed connector. Do not create your own reporting or execution endpoint, and do not treat an application credential as an internal service credential.

ALYT resolves tenant, home, endpoint ownership, source identity, and receipt time itself. Your payload cannot assign those. current ownership is pinned and rechecked through commit, and the admitted capture stays locked through the state transaction.

That matters when inventory changes during reporting:

• A home, room, owner, or integration change does not relabel admitted evidence.
• A disabled or deleted reporting path does not change already admitted evidence.
• A deleted endpoint still fails like a missing device.
• Read permission and physical execution authority remain separate checks.

If inventory lock contention occurs, ALYT may omit shadow evidence while ordinary state reporting continues. Treat that as incomplete coverage, not complete history.

Preserve producer facts exactly

The observation envelope is alyt.observation/draft-0.1.0. Preserve these fields exactly as produced: eventId, sourceEpoch, sequence, occurredAt, clockQuality, retained, and replay.

Field	Requirement
eventId	Stable UUID for the producer event. Keep it unchanged on retry.
sourceEpoch	Producer boot or session UUID, or null.
sequence	Nonnegative decimal string in signed 64-bit range, or null.
occurredAt	Original observation timestamp with UTC offset, or null.
clockQuality	SYNCHRONIZED, UNCERTAIN, or UNKNOWN.
retained	Whether the observation is retained evidence.
replay	Whether the observation replays an earlier report.

Rules:

• Supply sourceEpoch and sequence together, or set both to null.
• SYNCHRONIZED requires occurredAt.
• Do not invent a sequence or timestamp to fill gaps.
• On resend, preserve the original eventId, sourceEpoch, sequence, and occurredAt.
• broker retention is carried independently by ALYT. A payload saying retained: false does not override that.

Legacy reports without the envelope remain accepted, but they carry UNKNOWN provenance and clock quality rather than fabricated timing.

Keep age, causality, and freshness separate

Evidence keeps original time and receipt time separately for each field. Field freshness is not shared across capabilities.

Examples:

• A battery report does not refresh a contact sensor reading.
• A later contact observation can update contact evidence even if some other field arrived more recently.
• Correlation to a command identifies the command, but it does not prove a physical result.

Future occurredAt values are rejected. Older or duplicate sequence values cannot rewind a field. A new sourceEpoch needs admissible time evidence; if epoch change timing is uncertain, evidence is withheld and history is marked incomplete. A closed epoch cannot return later and replace the current one.

Known expiry uses the field’s original time and capability lifetime, not resend time. Unknown clocks, unknown values, and capabilities without a defined lifetime keep unknown age.

Respect retained and replay restrictions

Retained and replayed reports are useful evidence, but they have hard limits.

A retained report cannot replace live evidence. Separately, it cannot introduce a transient press. Both rules apply independently.

In practice:

• Retained evidence cannot displace a newer live field value.
• Retained evidence cannot create a button press or similar momentary event even without a live baseline.
• Replay and retained evidence cannot claim command causality.

Consume the context view safely

For normalized observations, the installed context view uses alyt.context-view/draft-0.2.0. In draft-0.2.0, sequence is a nullable decimal string, not a JavaScript Number. Branch on schemaVersion and never pass that sequence through Number.

The older draft-0.1.0 view may still use a safe-integer-or-null representation. Your integration should handle both.

Other rules when consuming context:

• Filter against exact current Device and Endpoint inventory.
• Historical snapshots do not restore moved, disabled, or deleted items.
• Native identifiers are private bindings; model-facing evidence uses opaque identities.
• Missing or invalid evidence is omitted or marked UNKNOWN, not fabricated.
• context expires before any included fresh field expires.

Generic telemetry and connectivity data do not refresh physical observations. Only admissible readable device fields do.

Observe limits and admitted data shape

Only descriptor-backed readable fields with supported value types and ranges enter normalized evidence. Unsupported fields stay outside AI context.

Important bounds:

Limit	Value
Readable fields per report	64
Readable fields per endpoint	128
Stored normalized observation record	32,768 bytes
Latest field evidence plus source metadata	65,536 bytes

These are normalized record limits, not a transport payload limit.

Handle history and recovery conservatively

History is bounded. Gaps, unsupported fields, field caps, and retention trimming all make history explicitly incomplete. Missing records are not proof that no event occurred.

During recovery:

• Treat duplicate delivery idempotently.
• Preserve unknown and partial outcomes.
• Reconcile uncertain physical effects before repeating consequential operations.
• Keep current home authorization and manual changes authoritative.

Also note that ordering is tracked per-endpoint, so one device’s sequence gap does not become another device’s gap.

Integration checklist

Concern	What to do
Producer facts	Preserve eventId, sourceEpoch, sequence, occurredAt, clockQuality, retained, and replay exactly.
Numeric handling	Treat sequence in draft-0.2.0 as a signed 64-bit decimal string; do not coerce through Number.
Freshness	Calculate expiry from original time, not resend time.
Causality	Do not equate command correlation with a physical result.
Inventory	Read only against current Device and Endpoint inventory and expect current ownership to be rechecked.
Privacy	Use model-facing opaque identities; do not embed credentials or permission fields in metadata.
Retained evidence	A retained report cannot replace live evidence and cannot introduce a transient press.
Telemetry	Generic telemetry cannot refresh physical state.
Clocks	synchronization qualifies only the supplied fields; absent proof stays UNKNOWN.

If you keep those invariants, your AI integration can reason over device evidence without overstating certainty or inventing facts ALYT did not admit.

Preserve a switch used for lighting

Physical report ingestion keeps the reported capability as the durable fact, while household light/switch aliases are only applied when presenting context, replay, or history. The same source evidence remains tied to its original timestamps, decimal sequence order, and expiry handling, and corrections still restore per-field evidence without adding authority, confirmation, or control changes. Grouping and controls stay unchanged: only the reader-facing name mapping differs, so a switch can still be preserved as the lighting device users expect.