Crate pointlock_provider_kit 

pointlock-provider-kit

The Provider SPI of Pointlock (spine §4; 04 §1–§8): the authoritative in-process Rust trait form of Provider / ProviderSession (a stdio JSON-RPC sidecar adapter form is reserved for v0.2), the static capability declaration types (ProviderManifest, CapabilityLockfile, CapabilityAttestation), the unified ProviderError carrier, the deterministic programmable FakeProvider, and the provider conformance suite every implementation must pass before the CLI assembles it.

Authoritative design documents:

• docs/design/00-architecture-spine.md §4 (SPI TS signatures, the canonical notation this crate renders into Rust), §5 (error taxonomy)
• docs/design/04-provider-interface-and-devicerail.md §1–§8 (contract clauses, error normalization, timeout/cancellation, conformance)

Shared runtime DTOs (ActionOutcome, ActionResult, ReconcileResult, ErrorInfo, Observation, AssetRef, …) are defined in pointlock-ir (type truth source, R12) and re-exported here for one-stop SPI imports.

Serde discipline

Wire shape is camelCase (rename_all) with closed objects (deny_unknown_fields); type, field and enum-literal spellings follow spine Appendix A verbatim (error classes stay snake_case by decree). M0 iron law: the public contract shapes here are final; contents may still be narrow (each narrowing carries a pending-incorporation note).

Re-exports

pub use conformance::CheckResult;

pub use conformance::CheckStatus;

pub use conformance::ConformanceOptions;

pub use conformance::ConformanceReport;

pub use conformance::run_conformance;

pub use error::ProviderError;

pub use error::RetryableSource;

pub use fake::FakeHandle;

pub use fake::FakeProvider;

pub use fake::FakeProviderSession;

pub use fake::ScriptedOutcome;

pub use lockfile::CapabilityAttestation;

pub use lockfile::CapabilityLockfile;

pub use lockfile::LOCKFILE_DIGEST_DOMAIN_TAG;

pub use lockfile::LockfileDevice;

pub use lockfile::LockfileHello;

pub use lockfile::LockfileProvider;

pub use lockfile::PeerInfo;

pub use lockfile::ProtocolVersion;

pub use lockfile::lockfile_digest;

pub use manifest::ActionDefinitionStatic;

pub use manifest::ActionProtection;

pub use manifest::ChannelRole;

pub use manifest::ChannelSupport;

pub use manifest::ConditionalFeature;

pub use manifest::FeatureDeclarations;

pub use manifest::PlatformKind;

pub use manifest::ProtocolRange;

pub use manifest::ProviderManifest;

pub use manifest::VerbBinding;

pub use spi::BoundActionCall;

pub use spi::EvidenceStream;

pub use spi::ObserveRequest;

pub use spi::ObserveWant;

pub use spi::OpenSessionOptions;

pub use spi::Provider;

pub use spi::ProviderSession;

pub use spi::SessionHealth;

pub use spi::SessionOutcome;

pub use spi::UiSnapshotOutcome;

pub use spi::VERDICT_EVIDENCE_MAX_ENTRIES;

pub use spi::VERDICT_SUMMARY_MAX_CHARS;

pub use spi::VerdictWrite;

pub use spi::now_ms;

pub use spi::observation_projection;

pub use spi::synthetic_observation_wants;

Modules

conformance

Provider conformance suite (04 §8).

error

The unified error carrier thrown by provider methods (04 §1, pending spine incorporation).

fake

FakeProvider — the deterministic, programmable reference implementation of the SPI (04 §8): an in-memory world model with scripted outcomes and fault injection. It is both the conformance suite’s reference subject and the runner’s E2E test double.

lockfile

Capability lockfile and runtime attestation (spine §4.1).

manifest

Static provider capability declaration (spine §4.1 ProviderManifest).

spi

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

Structs

ActionResult

Result of a succeeded action (spine §4.2). Every action returns state deltas: before/after observations plus evidence references.

AssetRef

Content-addressed evidence reference (DeviceRail AssetRef, spine A.8). Never inline bytes; sha256 is the bare hex digest when present.

CancellationToken

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

ErrorInfo

Structured, stable-coded error (DeviceRail ErrorInfo, spine A.8). retryable is advisory metadata for the runner — providers never retry.

EventCursor

Event-log cursor of the bound provider session (spine §6.6; advanced ack-after-persist, never across session generations).

Observation

A judgement-free point-in-time world snapshot (spine §2 concept 9, DeviceRail Observation shape). Omissions are typed data, not errors.

UiContextRef

Full identity of one UI context (DeviceRail UiContextRef, spine A.8). documentEpoch changes on navigation/reconnect and invalidates prior node references.

UiNodeRef

Reference to one node of a captured UI snapshot (DeviceRail UiNodeRef).

UiSnapshotRef

Reference to the UI-tree evidence of an observation. Minimal shape (the evidence asset); exact DeviceRail UiSnapshotRef field alignment is re-verified in M1 — pending incorporation.

Verdict

A folded step verdict (spine §2 concept 12). Append-only history: re-judgement produces a new verdict with supersedes set.

Viewport

Viewport of an observation (DeviceRail Viewport).

Enums

ActionExecution

The execution mode the provider actually used (spine §4.2) — the key input for unauthorized-degradation auditing (§6.4 R-degrade).

ActionOutcome

Four-way terminal outcome of an action (spine §4.2; never folded, never translated — cancelled and timedOut are recorded terminals).

ErrorClass

Pointlock-layer closed error taxonomy (spine §5). DeviceRail ErrorInfo.code is an open string set mapped onto this enum.

ReconcileResult

Fate of a hanging action intent after a crash (spine §4.2/§6.7-B).