Module spi 

The Provider SPI (spine §4.2 runtime interface; 04 §1–§7 contract clauses).

The authoritative SPI form is this Rust trait pair (in-process, R12); a stdio JSON-RPC sidecar adapter form is reserved for v0.2. Method names are the snake_case renderings of the spine A.5 exhaustive list (openSession → open_session, etc.); wire-facing DTO fields stay camelCase.

Cancellation: the TS signatures pass an optional AbortSignal to execute / observe. The Rust counterpart is an optional CancellationToken with the same contract (04 §7.1): on cancellation the provider must forward the cancel intent to the substrate rather than merely abandoning the wait; cancellation is a request, not a guarantee — the provider returns whatever terminal actually materializes; a token that is already cancelled at call time makes the method fail immediately with an action_cancelled-class ProviderError without dispatching.

Structs

BoundActionCall

A bound, ready-to-dispatch action call (spine §4.2 BoundActionCall).

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

ObserveRequest

Request for ProviderSession::observe. wants is an intent declaration, not a wire parameter (DeviceRail device.observe takes no params): it tells the provider whether to chase a ui.snapshot.get follow-up and to fill in truthful omission reasons when a wanted part is missing (04 §4.1).

OpenSessionOptions

Options for Provider::open_session (spine §4.2 OpenSessionOptions).

SessionHealth

Session health probe result (spine §4.2 health()).

VerdictWrite

Verdict write payload for ProviderSession::record_verdict (spine §4.2 — { status, summary, evidence }; the daemon only validates and persists, it runs no assertions).

Enums

ObserveWant

What an explicit observation should include (spine §4.2 observe(req) — wants: ("screenshot" | "uiSnapshot")[]).

SessionOutcome

Terminal outcome of a session (DeviceRail SessionOutcome, spine A.8).

UiSnapshotOutcome

Result of dereferencing an observation’s normalized UI tree (spine §4.2 uiSnapshot; TS: { ok: true, snapshot } | { ok: false, reason }).

Constants

VERDICT_EVIDENCE_MAX_ENTRIES

Wire hard cap on recordVerdict evidence entries (spine §4.2).

VERDICT_SUMMARY_MAX_CHARS

Wire hard cap on recordVerdict summaries, in characters (spine §4.2). Providers fail closed on oversize input; compaction is the runner’s report-assembly job (04 §5).

Traits

Provider

A provider: a static capability declaration plus a session factory (spine §4.2 Provider). Providers declare and faithfully execute; they never fold, translate, improvise, retry, or degrade (04 §1).

ProviderSession

An open provider session (spine §4.2 ProviderSession). One session owns one underlying client connection exclusively. In the broken state every method except health (which reports { ok: false }) fails with a transport_lost-class error (04 §2.1).

Functions

now_ms

Wall clock in milliseconds since the epoch.

observation_projection

The output projection of an observation action (04 §9.4.3): the observation’s identity plus the parts that were captured, each with its truthful omission reason when a wanted part is legitimately absent. Omission is data, never an error (04 §4.1).

synthetic_observation_wants

The parts a provider-synthetic observation action asks for, or None when the call is not one of them (04 §9.4.3).

Type Aliases

EvidenceStream

Byte stream returned by ProviderSession::fetch_evidence (the Rust counterpart of the TS AsyncIterable<Uint8Array>).