@ateam-ai-mobile/plugin-runtime 0.1.5 → 0.1.8

package/src/sdk/device-state.ts

@@ -0,0 +1,1315 @@
+/**
+ * @adas/device-state — Device Bridge v2, the SEMANTIC layer.
+ *
+ * Intended repo path:
+ *   packages/plugin-runtime/src/sdk/device-state.ts
+ * Intended module specifier for plugin bundles:
+ *   '@adas/device-state'   (NOT '@adas/plugin-sdk')
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHICH LAYER AM I IN?
+ *
+ *   props.device.*        MECHANICAL. "Do this to the hardware, now."
+ *                         VERB names: takePhoto, getCurrent, scanBarcode,
+ *                         readOnce, authenticate, pickImage.
+ *                         Returns a BARE value. THROWS when it cannot.
+ *                         Declared in the manifest as `capabilities: { camera: true }`
+ *                         (the legacy `native: {}` field is still honoured).
+ *                         Lives in '@adas/plugin-sdk'.
+ *
+ *   props.deviceState.*   SEMANTIC. "What is true right now, and how well do
+ *                         we know it?"
+ *                         STATE names: getSnapshot, subscribe, start, stop.
+ *                         Returns a SNAPSHOT carrying freshness + confidence,
+ *                         and able to say `unknown` in every field.
+ *                         A read NEVER throws for absence.
+ *                         Declared in the manifest as `stateDomains: ['visual']`.
+ *                         Lives in '@adas/device-state' (this file).
+ *
+ * The two containers are the discriminator. Every semantic call in a plugin
+ * begins with the eight characters `deviceState.`; every mechanical call
+ * begins with `native.`. There is no line of code where the layer is
+ * ambiguous, and no object on which both appear.
+ *
+ * This is a deliberate departure from
+ * Docs/device-bridge-v2/DEVICE_BRIDGE_V2_IMPLEMENTATION_GROUNDING_2026-08-07.md
+ * §"Migration strategy", which proposed adding `visual`, `spatial`,
+ * `connectivityState`… as fields ON `PluginNative`. See the design note at the
+ * bottom of this file for why that layout is rejected and what it costs.
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * PROVENANCE MARKERS used throughout. They are not decoration — the freeze
+ * really does fix some of this and really does leave the rest open, and an
+ * implementor needs to know which is which before changing a line:
+ *
+ *   FROZEN   — API_FREEZE 2026-08-07 §15 lists it as a frozen candidate.
+ *   V0.1     — "v0.1 freeze candidate; may change only when implementation
+ *              grounding proves a field impossible/non-portable."
+ *   OPEN     — the docs explicitly leave it undecided. Do not quietly close it.
+ *   DECISION — not in the docs at all; decided here, and reversible.
+ */
+
+/* eslint-disable @typescript-eslint/no-empty-interface */
+
+// ═════════════════════════════════════════════════════════════════════════
+// 1. Common metadata model
+// FROZEN (API_FREEZE §1, §15 "Common metadata model: frozen candidate").
+// Shared verbatim by all eight domains. Do not fork a per-domain variant.
+// ═════════════════════════════════════════════════════════════════════════
+
+/** FROZEN (API_FREEZE §1). The eight domain keys. */
+export type DeviceBridgeDomain =
+  | 'spatial'
+  | 'visual'
+  | 'activity'
+  | 'deviceContext'
+  | 'connectivity'
+  | 'capability'
+  | 'environment'
+  | 'interaction';
+
+export type FreshnessState = 'fresh' | 'aging' | 'stale' | 'unknown';
+
+/**
+ * FROZEN. Both fields are nullable on purpose: "we have no observation at all"
+ * has to be expressible without inventing a timestamp.
+ *
+ * `aging` is a real third state, not a rounding of fresh/stale — a consumer
+ * that only branches on fresh-vs-stale is misreading the contract.
+ *
+ * API_FREEZE §1 "Why observedAt + ageMs": the host may compute `ageMs` at read
+ * time, so it can be more accurate than `Date.now() - observedAt` measured on
+ * the JS side after a bridge hop. Read `ageMs` when you have it.
+ */
+export interface Freshness {
+  state: FreshnessState;
+  /** Epoch ms of the observation itself. `null` = never observed. */
+  observedAt: number | null;
+  /** Age at read time. `null` = never observed. */
+  ageMs: number | null;
+}
+
+export type ConfidenceLevel = 'high' | 'medium' | 'low' | 'unknown';
+
+/**
+ * FROZEN. `level` is mandatory and ordinal; `score` is optional and exists
+ * only "when a stable numeric estimate exists" (API_FREEZE §1).
+ *
+ * The asymmetry is the point: native must not manufacture 0.5 to fill a field.
+ * A missing `score` is information — it says the estimator has no calibrated
+ * number, only a bucket.
+ */
+export interface Confidence {
+  level: ConfidenceLevel;
+  /** 0..1. Omitted when no stable numeric estimate exists. */
+  score?: number;
+}
+
+/**
+ * FROZEN. Every snapshot in v2 carries exactly one of these.
+ *
+ * `freshness` required, `confidence` optional — because some domains report
+ * exact OS facts (battery level, audio route) where a confidence is
+ * meaningless, and others report inference (activity, indoor/outdoor) where it
+ * is mandatory. Cross-domain review: "Freshness is mandatory for dynamic
+ * state. Confidence is mandatory for inferred/estimated state; optional for
+ * exact OS facts."
+ *
+ * NOTE (OPEN): freshness is per-SNAPSHOT, never per-field. So a snapshot
+ * cannot today say "lighting is fresh but acoustics is stale". The
+ * architecture doc raised this for Spatial and Environment and never resolved
+ * it. Do not work around it by inventing a second freshness field.
+ */
+export interface StateQuality {
+  freshness: Freshness;
+  confidence?: Confidence;
+}
+
+// ── Support / permission / availability / restriction ──────────────────────
+// FROZEN (API_FREEZE §1). Four INDEPENDENT axes. The capability doc is blunt:
+// "Do not collapse all failure modes into a single boolean." A camera can be
+// supported + granted + busy, and each of those three answers leads the caller
+// somewhere different.
+
+export type SupportState = 'supported' | 'unsupported' | 'unknown';
+
+export type PermissionState =
+  | 'granted'
+  | 'denied'
+  | 'restricted'
+  | 'notDetermined'
+  | 'limited'
+  | 'unavailable'
+  | 'unknown';
+
+export type AvailabilityState =
+  | 'available'
+  | 'busy'
+  | 'temporarilyUnavailable'
+  | 'unavailable'
+  | 'unknown';
+
+export type RestrictionState =
+  | 'none'
+  | 'backgroundRestricted'
+  | 'systemRestricted'
+  | 'policyRestricted'
+  | 'lowPowerRestricted'
+  | 'unknown';
+
+// ── Events ────────────────────────────────────────────────────────────────
+
+/**
+ * FROZEN (API_FREEZE core rule 4): "Events are meaningful semantic changes,
+ * never raw sensor streams." If you find yourself wanting an event per frame
+ * or per GPS fix, you are in the wrong layer.
+ */
+export interface StateEvent<TName extends string = string, TPayload = unknown> {
+  domain: DeviceBridgeDomain;
+  name: TName;
+  /** Epoch ms. */
+  timestamp: number;
+  /**
+   * OPEN: per-event payload schemas are not specified anywhere in the three
+   * design docs. Defaults to `unknown` rather than `any` so a consumer is forced
+   * to narrow it rather than read a field that may not exist. A domain that
+   * decides its schemas (spatial — see `SpatialStateEvent`) passes `TPayload`,
+   * which is the freeze's own second parameter, dropped here until one did.
+   */
+  payload?: TPayload;
+}
+
+export interface Subscription {
+  unsubscribe(): void;
+}
+
+export type StateListener<TName extends string = string> = (
+  event: StateEvent<TName>,
+) => void;
+
+/**
+ * VOCABULARY §"Event Naming Rule", expressed as a type.
+ *
+ * Four domains (visual, activity, spatial, deviceContext) have NO frozen event
+ * vocabulary — the vocabulary doc publishes "Initial … Events" lists for
+ * connectivity, capability, interaction and environment only. Rather than mint
+ * names those docs deliberately did not mint, their events are typed against
+ * the naming RULE. A wrong-shaped name is a compile error; the specific
+ * vocabulary stays open, as the docs left it — except where a DECISION closes
+ * it (spatial, see `SpatialEvent`), and that list is checked against the rule
+ * through `AssertConforming`.
+ */
+export type ConformingEventName =
+  | `${string}Changed`
+  | `${string}Started`
+  | `${string}Stopped`
+  | `${string}Available`
+  | `${string}Unavailable`
+  | `${string}StateStale`;
+
+/**
+ * A closed list of names, checked against the naming rule at compile time.
+ * Wrap a decided vocabulary in this and a name like `turnCompleted` stops
+ * compiling instead of reaching a plugin.
+ */
+export type AssertConforming<T extends ConformingEventName> = T;
+
+// ── Errors ────────────────────────────────────────────────────────────────
+
+/** FROZEN (API_FREEZE §12). */
+export type DeviceBridgeErrorCode =
+  | 'UNSUPPORTED'
+  | 'PERMISSION_DENIED'
+  | 'RESTRICTED'
+  | 'BUSY'
+  | 'TEMPORARILY_UNAVAILABLE'
+  | 'STALE'
+  | 'TIMEOUT'
+  | 'CANCELLED'
+  | 'INTERNAL';
+
+/**
+ * FROZEN shape (API_FREEZE §12).
+ *
+ * READ THE SCOPE LINE CAREFULLY. This is for FAILED OPERATIONS —
+ * `visual.capture()`, `visual.start()`. It is NOT how the surface reports that
+ * a camera is denied or a sensor is missing: "Expected state should still be
+ * exposed in snapshots."
+ *
+ * So: `getSnapshot()` does not throw this. `capture()` and `start()` do.
+ * That split is the whole no-fabrication contract in one sentence — a read
+ * always returns something honest, an action either happens or explains
+ * itself in a typed code.
+ */
+export class DeviceBridgeError extends Error {
+  readonly code: DeviceBridgeErrorCode;
+  readonly domain?: DeviceBridgeDomain;
+  /** Whether retrying could plausibly succeed (BUSY yes, UNSUPPORTED no). */
+  readonly recoverable?: boolean;
+
+  constructor(
+    code: DeviceBridgeErrorCode,
+    message: string,
+    opts?: { domain?: DeviceBridgeDomain; recoverable?: boolean },
+  ) {
+    super(message);
+    this.name = 'DeviceBridgeError';
+    this.code = code;
+    this.domain = opts?.domain;
+    this.recoverable = opts?.recoverable;
+  }
+}
+
+// ── Sessions and the lifecycle pattern ────────────────────────────────────
+
+export interface StateSession {
+  id: string;
+  /** The intent this session was started with. */
+  intent: string;
+  startedAt: number;
+}
+
+export interface StartOptions<TIntent extends string> {
+  /**
+   * MANDATORY, and that is the single most important line in this file.
+   *
+   * You cannot open a v2 session without naming what it is FOR. Native then
+   * owns sampling rate, resolution, buffering, fusion and power — API_FREEZE
+   * core rule 6. `start()` means "maintain state according to this intent",
+   * not "open a particular native API" (§2).
+   *
+   * Contrast the mechanical layer, where `camera.takePhoto()` is a legal,
+   * complete, intent-free call. That difference is visible at every call site.
+   */
+  intent: TIntent;
+  /**
+   * DECISION (not frozen). §13 requires bounded timeout/cancellation for
+   * session starts and says chain STOP must propagate to native, but leaves
+   * the plumbing "implementation-specific". `AbortSignal` is what
+   * `DeviceToolContext.signal` already carries in this SDK, so reuse it rather
+   * than invent a second cancellation idiom.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * FROZEN pattern (API_FREEZE §2), reproduced as documentation. The eight
+ * concrete domains below do NOT extend this — each spells out exactly the
+ * methods it has, because §11 warns "domains should not be forced to implement
+ * meaningless lifecycle methods" and three domains genuinely have no intent
+ * vocabulary at all.
+ *
+ * Two invariants apply to every domain:
+ *  - `getSnapshot()` reads CACHED state. It must not trigger expensive raw
+ *    sensing (no camera open, no network probe, no GPS cold start).
+ *  - "Multiple plugins may eventually share one native engine; session
+ *    ownership must not imply duplicate sensor pipelines." (OPEN: the
+ *    arbitration mechanism is undefined. See DESIGN NOTE 3.)
+ */
+export interface StatefulDomain<
+  TSnapshot,
+  TIntent extends string = never,
+  TEvent extends string = string,
+> {
+  getSnapshot(): Promise<TSnapshot>;
+  start?(options: StartOptions<TIntent>): Promise<StateSession>;
+  stop?(sessionId?: string): Promise<void>;
+  subscribe?(listener: StateListener<TEvent>): Subscription;
+}
+
+/**
+ * Why every read is `Promise<T>` even though it is a cached read.
+ *
+ * Not because it samples — it must not. Because it crosses the RN bridge, and
+ * this SDK has no synchronous JSI module today (verified: everything in
+ * PluginNative except haptics/connectivity.isOnline is Promise-based). The
+ * grounding doc's own target for a warm cached snapshot is p50 < 10 ms /
+ * p95 < 30 ms, which is an async-bridge budget, not a sampling budget.
+ */
+
+// ═════════════════════════════════════════════════════════════════════════
+// 2. Domain 1 — Spatial State
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * FROZEN (API_FREEZE §3). Copied verbatim, not designed here.
+ *
+ * This landed as a placeholder first, on the belief that §3's field schema had
+ * never been written. It had — the placeholder was a gap in what got read, not
+ * a gap in the freeze. Worth recording, because "the docs leave this open" and
+ * "I did not find it" produce identical-looking comments and only one of them
+ * is a reason to invent a shape.
+ */
+export type SpatialIntent =
+  | 'navigation'
+  | 'fitness'
+  | 'geofence'
+  | 'lowPowerTracking'
+  | 'preciseLocate';
+
+/** FROZEN (API_FREEZE §3). */
+export interface SpatialPoint {
+  latitude: number;
+  longitude: number;
+  altitude?: number | null;
+  /** Metres. `null` when the platform gives no estimate — never 0, which
+   *  would read as a perfect fix. */
+  accuracyM?: number | null;
+  timestamp: number;
+}
+
+/** FROZEN (API_FREEZE §3). */
+export interface SpatialSnapshot {
+  /** `null` when there is no usable fix. Not a zero coordinate — (0,0) is a
+   *  real place in the Gulf of Guinea. */
+  position: SpatialPoint | null;
+  movement: {
+    speedMps: number | null;
+    bearingDeg: number | null;
+    distanceRecentM: number | null;
+    state?: 'stationary' | 'moving' | 'unknown';
+  };
+  orientation: {
+    headingDeg: number | null;
+    headingAccuracyDeg?: number | null;
+    pitchDeg?: number | null;
+    rollDeg?: number | null;
+  };
+  /** Newest last. Empty when nothing has been recorded — the ring is a native
+   *  concern, and its window is chosen by intent. */
+  recentPath: SpatialPoint[];
+  changes?: {
+    lastMeaningfulTurnDeg?: number | null;
+    timestamp?: number | null;
+  };
+  quality: StateQuality;
+}
+
+/**
+ * DECISION (not frozen) — the spatial event vocabulary. Six names, all ending
+ * in a suffix the naming rule allows, which `AssertConforming` enforces.
+ *
+ * Drawn from the architecture doc's spatial candidates (meaningful movement,
+ * meaningful turn, location quality degraded/recovered, state became stale)
+ * and named after the SNAPSHOT fields they report, so an event and a read use
+ * one vocabulary: `lastMeaningfulTurnChanged` is `changes.lastMeaningfulTurnDeg`
+ * changing. The names an earlier note floated (`turnCompleted`, `arrived`,
+ * `headingLost`) are rejected — the first two fail the rule, and "arrived" is a
+ * destination, which the vocabulary's Governance puts above Device Bridge.
+ */
+export type SpatialEvent = AssertConforming<
+  | 'movementStarted'
+  | 'movementStopped'
+  | 'lastMeaningfulTurnChanged'
+  | 'positionConfidenceChanged'
+  | 'positionChanged'
+  | 'spatialStateStale'
+>;
+
+/** A spatial event: the frozen envelope, with its payload always present. */
+type SpatialEventOf<TName extends SpatialEvent, TPayload> =
+  StateEvent<TName, TPayload> & { domain: 'spatial'; payload: TPayload };
+
+/**
+ * DECISION — what each spatial event carries. Only the facts of the
+ * transition, in the snapshot's own field names; everything else is one
+ * `getSnapshot()` away, which keeps two shapes of the same fact from drifting.
+ *
+ * `timestamp` on the envelope is when the transition was RECOGNISED. Where a
+ * hold delays that on purpose, `since` carries the true onset.
+ */
+export type SpatialStateEvent =
+  /** `movement.state` became `moving` and held (navigation: 3 s). */
+  | SpatialEventOf<'movementStarted', {
+      previous: 'stationary' | 'unknown';
+      speedMps: number | null;
+      bearingDeg: number | null;
+      since: number;
+    }>
+  /** `moving` → `stationary`, held (navigation: 5 s). Never fired on moving →
+   *  `unknown`: losing the speed is not evidence of stopping. */
+  | SpatialEventOf<'movementStopped', { previous: 'moving'; since: number }>
+  /** A new completed turn. Signed: positive = clockwise = right. */
+  | SpatialEventOf<'lastMeaningfulTurnChanged', { lastMeaningfulTurnDeg: number; timestamp: number }>
+  /** The GPS fix band (high ≤10 m, medium ≤50 m, else low) changed and held.
+   *  The fix alone — a compass calibration change is not a position event. */
+  | SpatialEventOf<'positionConfidenceChanged', {
+      level: ConfidenceLevel;
+      previous: ConfidenceLevel;
+      accuracyM: number | null;
+      direction: 'dropped' | 'recovered';
+    }>
+  /** Moved at least max(profile floor, 2 × accuracyM) from the last reported
+   *  position, so GPS jitter never fires it. The session's first fix fires
+   *  with `previous: null`. */
+  | SpatialEventOf<'positionChanged', {
+      position: SpatialPoint;
+      previous: SpatialPoint | null;
+      distanceM: number | null;
+    }>
+  /** `quality.freshness.state` became `stale`. Once; re-armed by a fresh read. */
+  | SpatialEventOf<'spatialStateStale', { observedAt: number | null; ageMs: number | null }>;
+
+export interface SpatialDomain {
+  getSnapshot(): Promise<SpatialSnapshot>;
+  start(options: StartOptions<SpatialIntent>): Promise<StateSession>;
+  stop(sessionId?: string): Promise<void>;
+  /**
+   * DECISION: the six `SpatialEvent`s, typed per name — narrow on `e.name` and
+   * `e.payload` is that event's shape.
+   *
+   * Events flow only while a spatial session is open; subscribing opens no
+   * sensor. They are derived from the same snapshot `getSnapshot()` returns: a
+   * listener that re-reads inside the callback sees the snapshot its event came
+   * from. A state change must hold, on at least two fixes, before it fires.
+   *
+   * From a device tool's `ctx.deviceState` this refuses (RESTRICTED): a call
+   * has no lifetime to own the listener.
+   */
+  subscribe(listener: (event: SpatialStateEvent) => void): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 3. Domain 2 — Visual State
+//
+// Visual is NOT "the camera API". It is a native-maintained visual timeline
+// plus camera/capture state. Everything interpretive — what is in the scene,
+// what the sign says, which corridor to take — sits ABOVE Device Bridge and is
+// not modelled here.
+// ═════════════════════════════════════════════════════════════════════════
+
+/** FROZEN (API_FREEZE §4) + VOCABULARY §"Visual Intents". Nine values. */
+export type VisualIntent =
+  | 'navigation'
+  | 'document'
+  | 'ocr'
+  | 'shopping'
+  | 'inspection'
+  | 'accessibility'
+  | 'stream'
+  | 'highQuality'
+  | 'lowPower';
+
+/**
+ * Media crosses by REFERENCE, never as inline bytes (core rule 3).
+ *
+ * AN ID AND NOTHING ELSE. The `uri` field is gone (2026-08-16), and its
+ * removal answers the question this comment used to record as OPEN — "how does
+ * a plugin turn a handle into pixels?" It doesn't. Ever.
+ *
+ * Frames now live in a native ring keyed by id and are never written to disk.
+ * `native.vision.readText/describe/assessQuality` take this id and resolve it
+ * INSIDE the trusted layer; the pixels do not cross into plugin code, so a
+ * solution's bundle cannot copy, upload or retain them. That is what makes
+ * "frames never leave the phone" enforceable rather than a promise.
+ *
+ * Do not add `uri` or `bytes` back. A plugin that believes it needs the pixels
+ * needs a new method on `native.vision` instead — one whose implementation
+ * stays on this side of the boundary.
+ */
+export interface MediaHandle {
+  id: string;
+  mimeType?: string;
+  /**
+   * Epoch ms after which this id no longer resolves — the frame's real
+   * eviction time from the native ring, not a guess.
+   *
+   * Past it, `native.vision` throws rather than returning an empty result:
+   * "I cannot look at that frame" and "I looked and found nothing" are
+   * different answers and must never be confused by a caller about to speak.
+   * In practice a caller rarely hits this, because the timeline is clamped to
+   * native retention — see `visualEngine.effectiveWindowMs()`.
+   */
+  expiresAt?: number | null;
+}
+
+/**
+ * V0.1. Per-frame usability is CATEGORICAL, not numeric — 'degraded' rather
+ * than a blur score. Coarse honest classes beat false precision; the same
+ * principle the connectivity doc states outright for connection quality.
+ *
+ * Every member carries `'unknown'` so a platform that cannot assess blur says
+ * so instead of defaulting to 'good'.
+ */
+export interface VisualFrameQuality {
+  blur?: 'good' | 'degraded' | 'unknown';
+  exposure?: 'good' | 'dark' | 'bright' | 'unknown';
+  /** `null` = cannot tell. Distinct from `false` = checked, not obstructed. */
+  obstructed?: boolean | null;
+}
+
+export interface VisualFrameRef {
+  handle: MediaHandle;
+  timestamp: number;
+  orientation?: { headingDeg?: number; pitchDeg?: number; rollDeg?: number };
+  quality?: VisualFrameQuality;
+}
+
+export interface VisualSnapshot {
+  camera: {
+    available: boolean;
+    /**
+     * Independent of `available` on purpose. A camera can be present and
+     * permitted (`available: true`) while no session is running
+     * (`active: false`) — that is a different situation from a camera the app
+     * cannot use at all, and Guide has to say different things about them.
+     *
+     * DRIFT (flagged, not resolved): the architecture doc's conceptual block
+     * also carried `camera.orientation`; the frozen §4 block does not. Not
+     * added here.
+     */
+    active: boolean;
+    facing?: 'front' | 'back' | 'unknown';
+  };
+  /**
+   * `null` when there is no usable current frame.
+   *
+   * This is the anti-fabrication field. The alternative implementation —
+   * returning the last frame you happen to still hold — is precisely how a
+   * guidance loop ends up describing a corridor the user left thirty seconds
+   * ago. If it is not current, it is `null`, and the timeline below is where
+   * you go looking for history, knowingly.
+   */
+  latest: VisualFrameRef | null;
+  /**
+   * TIME-based, not frame-count-based. Default window ~5s; documented bounded
+   * range roughly 1–15s, selected by profile/intent. Native decides how
+   * densely to retain frames inside the window and evicts everything outside
+   * it automatically.
+   *
+   * `windowMs` is exposed; FPS knobs are NOT, and must never be added
+   * (API_FREEZE §4). If a plugin wants "more frames", it declares a different
+   * intent — it does not turn a dial.
+   */
+  recentTimeline: { windowMs: number; frames: VisualFrameRef[] };
+  quality: StateQuality;
+}
+
+export interface VisualCaptureResult {
+  frame: VisualFrameRef;
+}
+
+/**
+ * OPEN, worth knowing before you use it: whether `capture({intent})` may pass
+ * an intent DIFFERENT from the running session's intent is not addressed
+ * anywhere in the three docs.
+ */
+export interface VisualCaptureOptions {
+  intent: VisualIntent;
+  /** §13: capture must support bounded timeout/cancellation. */
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface VisualDomain {
+  /**
+   * Cached read. Does NOT open the camera and does NOT take a picture.
+   *
+   * This is the call a guidance loop makes on every turn. The hot path is:
+   * native camera pipeline → rolling native timeline → cached visual state →
+   * one snapshot read from RN. "Avoid repeatedly starting the camera or
+   * capturing a new image for every plugin-tool call during an interactive
+   * session."
+   */
+  getSnapshot(): Promise<VisualSnapshot>;
+
+  /** Maintain visual state according to this intent. Not "open the camera". */
+  start(options: StartOptions<VisualIntent>): Promise<StateSession>;
+
+  /**
+   * An intentional, one-shot, high-quality-ish acquisition. THROWS
+   * DeviceBridgeError on failure — it is an operation, not a read.
+   *
+   * If you are about to call this once per conversational turn, stop: that is
+   * `getSnapshot()`'s job, and doing it here is the frame-timer pattern this
+   * whole layer exists to replace.
+   */
+  capture(options: VisualCaptureOptions): Promise<VisualCaptureResult>;
+
+  /**
+   * OPEN (doc conflict): the architecture doc shows `visual.subscribe(events)`
+   * — a filter — while API_FREEZE shows `visual.subscribe(listener)`. The
+   * freeze is followed here. Unresolved.
+   *
+   * OPEN: there is no "Initial Visual Events" list anywhere. The candidate set
+   * in prose (camera became available/unavailable, frame quality degraded/
+   * recovered, camera appears obstructed, significant scene change, visual
+   * session suspended/resumed, visual state became stale) is NOT a minted
+   * vocabulary. Typed against the naming rule only.
+   */
+  subscribe(listener: StateListener<ConformingEventName>): Subscription;
+
+  stop(sessionId?: string): Promise<void>;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 4. Domain 3 — Human Activity State
+// ═════════════════════════════════════════════════════════════════════════
+
+/** FROZEN (API_FREEZE §5, VOCABULARY §"Human Activity Values"). */
+export type HumanActivity =
+  | 'stationary'
+  | 'walking'
+  | 'running'
+  | 'cycling'
+  | 'driving'
+  | 'unknown';
+
+/** FROZEN. Independent of HumanActivity — walking+pocket, driving+mounted. */
+export type DevicePlacement =
+  | 'handheld'
+  | 'pocket'
+  | 'table'
+  | 'mounted'
+  | 'unknown';
+
+/**
+ * FROZEN. Note `driving` is BOTH an intent here and a HumanActivity value
+ * above. The docs define no relationship between the two and do not flag the
+ * collision: declaring intent `driving` does not assert the user is driving.
+ */
+export type ActivityIntent =
+  | 'navigation'
+  | 'fitness'
+  | 'driving'
+  | 'safety'
+  | 'accessibility'
+  | 'lowPower';
+
+export interface ActivitySnapshot {
+  human: {
+    state: HumanActivity;
+    /** `null` when the start of the current activity is not known. */
+    since: number | null;
+    /** REQUIRED, unlike StateQuality.confidence — an inferred activity may
+     *  never be handed over without saying how sure the inference is. */
+    confidence: Confidence;
+  };
+  devicePose: {
+    placement: DevicePlacement;
+    /** V0.1. These four values appear only in the freeze TS, not in the
+     *  vocabulary doc — unlike the placement values. Mild drift, flagged. */
+    orientation?: 'portrait' | 'landscape' | 'flat' | 'unknown';
+    confidence: Confidence;
+  };
+  /**
+   * Advisory only. `likelyNext` is a hint and never a fact.
+   * OPEN: transition names are bare `string` — no controlled vocabulary exists
+   * anywhere, which sits awkwardly beside "Intents are not arbitrary strings".
+   */
+  transition?: {
+    current?: string | null;
+    likelyNext?: string | null;
+    confidence?: Confidence;
+  };
+  /** OPEN: no window length or cap is specified for Activity (Spatial gets
+   *  ~10–20s, Visual ~5s). Required array — an empty one is a real answer. */
+  recentTransitions: Array<{ name: string; timestamp: number }>;
+  quality: StateQuality;
+}
+
+export interface ActivityDomain {
+  getSnapshot(): Promise<ActivitySnapshot>;
+  /**
+   * OPEN: §11's naming list shows only `activity.getSnapshot()`, and §2 makes
+   * start/stop optional. Whether Activity is session-based or a passive
+   * always-on domain is genuinely unstated. Included here because the six
+   * frozen ActivityIntent values would otherwise have no seam to arrive
+   * through — but this is a DECISION, not a reading of the freeze.
+   */
+  start(options: StartOptions<ActivityIntent>): Promise<StateSession>;
+  stop(sessionId?: string): Promise<void>;
+  /** OPEN: no "Initial Activity Events" list exists. */
+  subscribe(listener: StateListener<ConformingEventName>): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 5. Domain 4 — Device Context
+//
+// SCOPE WARNING. The early architecture draft put lifecycle, audio route and
+// hardware availability here. The freeze REMOVED all three: app foreground/
+// background and active channels are canonicalized under Interaction; hardware
+// support/permission moved to Capability. Frozen Device Context is power +
+// thermal + resources, and nothing else.
+// ═════════════════════════════════════════════════════════════════════════
+
+export interface DeviceContextSnapshot {
+  power: {
+    /** 0..1 FRACTION, not a percentage. `null` = not known. */
+    batteryLevel: number | null;
+    charging: boolean | null;
+    lowPowerMode: boolean | null;
+  };
+  thermal: {
+    state: 'nominal' | 'fair' | 'serious' | 'critical' | 'unknown';
+  };
+  resources: {
+    memoryPressure?: 'normal' | 'warning' | 'critical' | 'unknown';
+    storagePressure?: 'normal' | 'warning' | 'critical' | 'unknown';
+  };
+  /** Confidence is legitimately omitted here — these are exact OS facts, not
+   *  estimates. Freshness still matters: a populated batteryLevel says nothing
+   *  about whether it was sampled a second or a minute ago. */
+  quality: StateQuality;
+}
+
+/**
+ * NO INTENT TYPE, and that is deliberate — not an oversight, and not a gap to
+ * fill in later. There is no `DeviceContextIntent` in the freeze and no
+ * "Device Context Intents" section in the vocabulary, because
+ * (cross-domain review) "A domain may expose an intent only if it changes
+ * native implementation strategy in a meaningful way." Reading battery and
+ * thermal does not.
+ *
+ * The direction of flow is the other way round: Device Context is an INPUT to
+ * how OTHER domains satisfy their intents. Visual intent `navigation` +
+ * device context `battery 5% + low-power mode` → native picks a lower-power
+ * camera strategy while still honouring the Visual contract. The plugin does
+ * not retune anything, and must not be asked to.
+ *
+ * Do not add `deviceContext.start({intent:'lowPower'})` because five other
+ * domains have a lowPower intent.
+ */
+export interface DeviceContextDomain {
+  getSnapshot(): Promise<DeviceContextSnapshot>;
+  /**
+   * OPEN: `DeviceContextDomain`'s interface body is never written in the
+   * freeze, and no Device Context event names are frozen (the vocabulary has
+   * "Initial … Events" for connectivity/capability/interaction/environment
+   * only). DECISION: expose subscribe, because the candidate events —
+   * low-power mode changed, charging changed, thermal pressure changed — are
+   * exactly what an adaptive session needs and polling for them is wasteful.
+   *
+   * OPEN: "battery crossed significant threshold" and "changed materially"
+   * have no numbers anywhere, and Device Context has no profiles to
+   * parameterize them.
+   */
+  subscribe(listener: StateListener<ConformingEventName>): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 6. Domain 5 — Connectivity State
+// ═════════════════════════════════════════════════════════════════════════
+
+/** FROZEN (API_FREEZE §7, VOCABULARY §"Connectivity Intents"). */
+export type ConnectivityIntent =
+  | 'lowLatencyConversation'
+  | 'interactive'
+  | 'bulkTransfer'
+  | 'backgroundSync'
+  | 'offlineResilient'
+  | 'lowPower';
+
+/**
+ * V0.1, and note it is FLAT — the connectivity design doc sketched a nested
+ * shape (internet{…}, quality{…}, recent_history{…}) and the freeze flattened
+ * it. Two unreconciled deltas, carried here as-is rather than merged:
+ *  - `bandwidthClass` appears in the freeze but in neither the design doc nor
+ *    the vocabulary's Connectivity Values.
+ *  - there is NO recent-history field, although the design doc requires native
+ *    to maintain recent transitions and leaves the default window OPEN.
+ */
+export interface ConnectivitySnapshot {
+  /** NOTE: the design doc says "online / offline / uncertain"; the frozen
+   *  third value is `unknown`. The two words are never reconciled. */
+  reachability: 'online' | 'offline' | 'unknown';
+  transport: 'wifi' | 'cellular' | 'ethernet' | 'other' | 'none' | 'unknown';
+  qualityClass:
+    | 'excellent'
+    | 'good'
+    | 'degraded'
+    | 'poor'
+    | 'unusable'
+    | 'unknown';
+  stability: 'stable' | 'changing' | 'flapping' | 'unknown';
+  /** `null` when no recent measurement exists. Explicitly preferred over
+   *  reporting a stale number: "return unknown rather than stale precision." */
+  latencyMs?: number | null;
+  bandwidthClass?: 'high' | 'medium' | 'low' | 'unknown';
+  metered?: boolean | null;
+  constrained?: boolean | null;
+  quality: StateQuality;
+}
+
+/** FROZEN v0.1 (VOCABULARY §"Initial Connectivity Events"). All ten. */
+export type ConnectivityEvent =
+  | 'connectivityOnline'
+  | 'connectivityOffline'
+  | 'transportChanged'
+  | 'connectivityDegraded'
+  | 'connectivityRecovered'
+  | 'connectivityUnstable'
+  | 'connectivityStable'
+  | 'meteredStateChanged'
+  | 'constrainedStateChanged'
+  | 'connectivityStateStale';
+
+export interface ConnectivityDomain {
+  /**
+   * A fast local cached read. It must NOT ping, and must NOT run a bandwidth
+   * or speed test. Latency is sampled on native's own schedule, chosen by
+   * intent, and cached with a timestamp.
+   */
+  getSnapshot(): Promise<ConnectivitySnapshot>;
+  /**
+   * OPEN: `ConnectivityDomain` is named in §11 but never defined, so whether
+   * connectivity is session-based is unstated. DECISION: yes — six frozen
+   * intents with documented behavioural differences (lowLatencyConversation
+   * "prioritize fresh latency knowledge"; lowPower "rely primarily on passive
+   * OS signals and minimize active probes") only mean something if there is a
+   * way to declare one.
+   */
+  start(options: StartOptions<ConnectivityIntent>): Promise<StateSession>;
+  stop(sessionId?: string): Promise<void>;
+  subscribe(listener: StateListener<ConnectivityEvent>): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 7. Domain 6 — Capability / Permission State
+//
+// The "why" domain. When another snapshot says `unknown`, this is where the
+// reason lives. Descriptive only — it never triggers a permission dialog.
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * FROZEN. Four independent axes, deliberately not collapsed. The canonical
+ * worked example from the capability doc: supported + granted + busy + none —
+ * a camera you own, are allowed to use, and cannot have right now.
+ */
+export interface CapabilityStatus {
+  support: SupportState;
+  permission?: PermissionState;
+  availability: AvailabilityState;
+  restriction?: RestrictionState;
+}
+
+export interface CapabilitySnapshot {
+  camera: CapabilityStatus;
+  microphone: CapabilityStatus;
+  /** The only capability the freeze gives scoped detail to. Health and
+   *  photos/media do NOT get one — see the gap note below. */
+  location: CapabilityStatus & {
+    precision?: 'precise' | 'approximate' | 'unknown';
+    backgroundPermission?: PermissionState;
+  };
+  motion: CapabilityStatus;
+  bluetooth: CapabilityStatus;
+  uwb: CapabilityStatus;
+  nfc: CapabilityStatus;
+  notifications: CapabilityStatus;
+  /**
+   * GAP (flagged): the capability doc notes health "authorization is often
+   * record-type specific rather than a single global permission" and its
+   * candidate shape had a `permission_summary`. The frozen §9 gives health a
+   * plain CapabilityStatus, so scoped health authorization is NOT
+   * representable in v0.1. Its own exit criterion ("scoped permissions are
+   * representable") is therefore only partly met.
+   */
+  health: CapabilityStatus;
+  backgroundExecution: CapabilityStatus;
+  /** GAP (flagged): photos/media appears in the design doc's native inputs and
+   *  its full-vs-limited scope discussion, but there is NO photos key in the
+   *  frozen CapabilitySnapshot. Not added here. */
+  quality: StateQuality;
+}
+
+/** FROZEN v0.1 (VOCABULARY §"Initial Capability Events"). All ten. */
+export type CapabilityEvent =
+  | 'capabilityChanged'
+  | 'permissionChanged'
+  | 'capabilityAvailable'
+  | 'capabilityUnavailable'
+  /** NOTE: this pair does not match the documented naming patterns. The docs
+   *  neither flag nor reconcile it; carried verbatim rather than "fixed". */
+  | 'capabilityBusy'
+  | 'capabilityFree'
+  | 'restrictionChanged'
+  | 'locationPrecisionChanged'
+  | 'backgroundPermissionChanged'
+  | 'capabilityStateStale';
+
+/**
+ * NO INTENT TYPE — the one domain that is intent-less by explicit reasoning
+ * rather than by omission: "Capability State itself should generally be cheap
+ * and mostly event-driven, so it does not need many sensing profiles."
+ * A candidate `interactive/background/minimal` vocabulary is floated in the
+ * design doc and explicitly conditional ("only be kept if implementation
+ * proves they add value"). Nothing frozen. Not added.
+ *
+ * Also NOT here: any `requestPermission()`. Permission-request UX is outside
+ * this state engine by design, and a floated generic primitive is future work.
+ */
+export interface CapabilityDomain {
+  getSnapshot(): Promise<CapabilitySnapshot>;
+  subscribe(listener: StateListener<CapabilityEvent>): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 8. Domain 7 — Environment State
+// ═════════════════════════════════════════════════════════════════════════
+
+/** FROZEN (VOCABULARY §"Environment Intents"). */
+export type EnvironmentIntent =
+  | 'ambient'
+  | 'navigation'
+  | 'accessibility'
+  | 'proximity'
+  | 'safety'
+  | 'lowPower';
+
+export interface EnvironmentSnapshot {
+  /** Privacy is part of the SHAPE, not advice: this says `dim`, never a camera
+   *  frame; `loud`, never microphone audio; a beacon count, never a BLE
+   *  payload. Raw audio/images/BLE payloads are not part of this domain. */
+  lighting: {
+    level: 'dark' | 'dim' | 'normal' | 'bright' | 'veryBright' | 'unknown';
+    lux?: number | null;
+    confidence?: Confidence;
+  };
+  acoustics: {
+    level: 'quiet' | 'moderate' | 'loud' | 'veryLoud' | 'unknown';
+    approximateDb?: number | null;
+    confidence?: Confidence;
+  };
+  /** `uncertain` and `unknown` are different: uncertain = we looked and cannot
+   *  decide; unknown = we have no basis to decide. */
+  enclosure: {
+    state: 'indoor' | 'outdoor' | 'uncertain' | 'unknown';
+    confidence?: Confidence;
+  };
+  proximity?: {
+    distanceClass?: 'immediate' | 'near' | 'far' | 'unknown';
+    confidence?: Confidence;
+  };
+  /** The only sub-block with no confidence — these are presence booleans, not
+   *  estimates. Note they cannot distinguish unsupported / denied / switched
+   *  off; that distinction lives in `capability`. */
+  nearbySignals?: {
+    bleAvailable?: boolean;
+    beaconCount?: number | null;
+    uwbAvailable?: boolean;
+    nfcAvailable?: boolean;
+  };
+  quality: StateQuality;
+}
+
+/** FROZEN v0.1 (VOCABULARY §"Initial Environment Events"). All ten. */
+export type EnvironmentEvent =
+  | 'lightingChanged'
+  | 'environmentBecameDark'
+  | 'environmentBecameBright'
+  | 'noiseLevelChanged'
+  | 'environmentBecameLoud'
+  | 'indoorOutdoorChanged'
+  | 'proximityChanged'
+  | 'nearbySignalAppeared'
+  | 'nearbySignalDisappeared'
+  | 'environmentStateStale';
+
+export interface EnvironmentDomain {
+  getSnapshot(): Promise<EnvironmentSnapshot>;
+  start(options: StartOptions<EnvironmentIntent>): Promise<StateSession>;
+  stop(sessionId?: string): Promise<void>;
+  subscribe(listener: StateListener<EnvironmentEvent>): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 9. Domain 8 — Interaction State
+//
+// Reports interaction FACTS. It never decides "pause the guide" or "speak now"
+// — that is orchestration and belongs to the Plugin Tool / Skill / AI.
+// ═════════════════════════════════════════════════════════════════════════
+
+export interface InteractionSnapshot {
+  lifecycle: {
+    appState: 'foreground' | 'background' | 'inactive' | 'unknown';
+    screenOn: boolean | null;
+    userActive?: boolean | null;
+    idleDurationMs?: number | null;
+  };
+  audio: {
+    captureActive: boolean | null;
+    playbackActive: boolean | null;
+    route:
+      | 'speaker'
+      | 'earpiece'
+      | 'wiredHeadset'
+      | 'bluetooth'
+      | 'carAudio'
+      | 'other'
+      | 'unknown';
+    /** `none` (checked, nothing interrupting) and `unknown` (no knowledge) are
+     *  deliberately different values. */
+    interruption: 'none' | 'temporary' | 'system' | 'unknown';
+  };
+  /** Optional GROUP: a platform that cannot report voice session state omits
+   *  the whole block rather than guessing `false` for each field. */
+  voice?: {
+    sessionActive: boolean | null;
+    userSpeaking?: boolean | null;
+    assistantSpeaking?: boolean | null;
+  };
+  /** May report that a camera session is running; must NOT duplicate frame
+   *  state. Frames belong to `visual`. */
+  visual?: {
+    cameraSessionActive: boolean | null;
+  };
+  quality: StateQuality;
+}
+
+/** FROZEN v0.1 (VOCABULARY §"Initial Interaction Events"). All twelve. */
+export type InteractionEvent =
+  | 'appStateChanged'
+  | 'screenStateChanged'
+  | 'audioRouteChanged'
+  | 'audioInterruptionStarted'
+  | 'audioInterruptionEnded'
+  | 'voiceSessionStarted'
+  | 'voiceSessionStopped'
+  | 'cameraSessionStarted'
+  | 'cameraSessionStopped'
+  | 'userBecameActive'
+  | 'userBecameIdle'
+  | 'interactionStateStale';
+
+/**
+ * NO INTENT TYPE. §10 declares only `InteractionSnapshot`, and the vocabulary
+ * — which does publish intents for spatial, visual, activity, connectivity and
+ * environment — has no "Interaction Intents" section. Five profiles are
+ * floated in the design doc, hedged twice ("Likely profiles, if needed") with
+ * no obligation attached to any of them. Not added.
+ */
+export interface InteractionDomain {
+  getSnapshot(): Promise<InteractionSnapshot>;
+  subscribe(listener: StateListener<InteractionEvent>): Subscription;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 10. Root surface
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * FROZEN name (API_FREEZE §11) and FROZEN member names.
+ *
+ * §11's "Recommended naming rule" says to call it `visual.getSnapshot()`, not
+ * `device.visual.*`. Read here as a rule about the WIRE/tool-name convention
+ * (`device.*` stays a human/backend routing convention for callable plugin
+ * tools) rather than a ban on a plugin-prop container. That reading is a
+ * judgement call and is flagged as such — if it is wrong, the fix is to rename
+ * the PROP, never to merge these eight members into `PluginNative`.
+ */
+export interface DeviceBridgeV2 {
+  readonly spatial: SpatialDomain;
+  readonly visual: VisualDomain;
+  readonly activity: ActivityDomain;
+  readonly deviceContext: DeviceContextDomain;
+  readonly connectivity: ConnectivityDomain;
+  readonly capability: CapabilityDomain;
+  readonly environment: EnvironmentDomain;
+  readonly interaction: InteractionDomain;
+}
+
+/** The name plugin authors see. See DESIGN NOTE 1 for why not `deviceBridge`. */
+export type DeviceState = DeviceBridgeV2;
+
+// ═════════════════════════════════════════════════════════════════════════
+// 11. Manifest gate — a SEPARATE declaration from `native`
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * DECISION (not in the docs). A second, differently-named manifest field, so a
+ * plugin cannot half-declare its way across the boundary:
+ *
+ *   native:       { camera: true }        → props.device.camera.takePhoto()
+ *   stateDomains: ['visual', 'spatial']   → props.deviceState.visual.getSnapshot()
+ *
+ * Declaring `native.camera` grants NOTHING in the semantic layer, and vice
+ * versa. There is no field whose meaning spans both.
+ *
+ * How an UNDECLARED domain must behave — and this is the load-bearing part:
+ * it returns a normal snapshot in which every enum is `unknown`, every
+ * nullable is `null`, and `quality.freshness` is
+ * `{ state:'unknown', observedAt:null, ageMs:null }`. It does NOT throw and it
+ * does NOT return undefined.
+ *
+ * Why that matters here specifically: today's `gatePluginNative` gives an
+ * undeclared capability a proxy whose methods `console.warn` and return
+ * `undefined` (packages/plugin-runtime/src/host.ts:67-76). So
+ * `await native.location.getCurrent()` on an undeclared plugin resolves to
+ * `undefined`, and `pos?.latitude` is `undefined` — which then flows into an
+ * LLM answer as a confident nothing. A silent undefined is a fabrication
+ * vector; a snapshot of explicit unknowns is not.
+ *
+ * The "why" is readable from `capability.getSnapshot()` using an existing
+ * frozen enum member: a manifest-gate denial maps to
+ * `restriction: 'policyRestricted'` — the plugin manifest IS a policy. No new
+ * vocabulary needed. (The docs never consider a manifest gate, so this
+ * mapping is a DECISION, but it uses only frozen values.)
+ */
+export type StateDomainDeclaration = readonly DeviceBridgeDomain[];
+
+// ═════════════════════════════════════════════════════════════════════════
+// 12. Small helpers — the "present does not mean fresh" guard
+// DECISION. Not frozen, not in any doc. Included because the single most
+// likely misuse of this API is reading a value and ignoring `quality`, and a
+// one-line guard is easier to reach for than a correct hand-rolled check.
+// ═════════════════════════════════════════════════════════════════════════
+
+const CONFIDENCE_ORDER: Record<ConfidenceLevel, number> = {
+  unknown: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+};
+
+/**
+ * Is this snapshot good enough to act on?
+ *
+ * Deliberately requires the caller to state a budget: there is no universal
+ * "fresh enough", and the docs give no numeric thresholds for any domain
+ * (native chooses sampling behaviour). A guidance loop wants ~1500 ms; a
+ * battery-aware background job is happy with 60 s.
+ *
+ * `unknown` freshness fails: it means nothing was ever observed, which is not
+ * the same as an old-but-real reading and must not be treated as one.
+ */
+export function isActionable(
+  quality: StateQuality,
+  budget: { maxAgeMs: number; minConfidence?: ConfidenceLevel },
+): boolean {
+  const { freshness, confidence } = quality;
+  if (freshness.state === 'unknown' || freshness.state === 'stale') return false;
+  if (freshness.ageMs === null || freshness.ageMs > budget.maxAgeMs) return false;
+  if (budget.minConfidence) {
+    const have = CONFIDENCE_ORDER[confidence?.level ?? 'unknown'];
+    if (have < CONFIDENCE_ORDER[budget.minConfidence]) return false;
+  }
+  return true;
+}
+
+/** The honest "we have never observed this" value. Use it instead of
+ *  inventing a timestamp when constructing a degraded snapshot. This is the
+ *  canonical source of the `unknown` freshness shape — the engine's
+ *  `qualityUnknown()` derives from it so the two never drift. */
+export function neverObserved(): Freshness {
+  return { state: 'unknown', observedAt: null, ageMs: null };
+}
+
+/**
+ * One human-readable sentence for why a capability cannot answer, built ONLY
+ * from what the four axes actually say. Returns null when the capability is
+ * fine — so a caller cannot accidentally print a reason that does not exist.
+ */
+export function explainCapability(status: CapabilityStatus): string | null {
+  if (status.support === 'unsupported') return 'this device does not have it';
+  if (status.permission === 'denied') return 'permission was denied';
+  if (status.permission === 'restricted') return 'permission is restricted';
+  if (status.permission === 'notDetermined') return 'permission has not been asked for yet';
+  if (status.permission === 'limited') return 'only limited access was granted';
+  if (status.restriction === 'policyRestricted') return 'this plugin did not declare it';
+  if (status.restriction === 'backgroundRestricted') return 'the app is in the background';
+  if (status.restriction === 'lowPowerRestricted') return 'the device is in low-power mode';
+  if (status.availability === 'busy') return 'it is in use by something else';
+  if (status.availability === 'temporarilyUnavailable') return 'it is temporarily unavailable';
+  if (status.availability === 'unavailable') return 'it is unavailable';
+  if (status.support === 'unknown' || status.availability === 'unknown') {
+    return 'its state could not be determined';
+  }
+  return null;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// 13. Integration seams into the existing SDK
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * Additive extension of `PluginProps` (sdk/types.ts:259).
+ *
+ * `deviceState` is OPTIONAL because a host that has not installed a v2
+ * provider must not pretend to have one. `undefined` means "this host has no
+ * semantic layer", which a plugin can check once; it does NOT mean "the
+ * sensors said nothing". Those are different, and collapsing them would
+ * reintroduce exactly the ambiguity this file exists to remove.
+ */
+export interface PluginPropsV2Extension {
+  readonly deviceState?: DeviceState;
+}
+
+/**
+ * Additive extension of `DeviceToolContext` (sdk/types.ts:320-327).
+ *
+ * This is the seam that matters most: device tools are what the AI calls, and
+ * device tools are where a fabricated value reaches a user. The lint rule
+ * proposed alongside this file (`no-mechanical-sensing-in-device-tools`) bans
+ * `ctx.native.camera`, `ctx.native.location` and `ctx.native.connectivity`
+ * inside a `DeviceToolDefinition.run` body — a device tool must reach sensing
+ * through `ctx.deviceState`. UI code is unaffected.
+ */
+export interface DeviceToolContextV2Extension {
+  readonly deviceState?: DeviceState;
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// DESIGN NOTES
+// ═════════════════════════════════════════════════════════════════════════
+
+/**
+ * DESIGN NOTE 1 — why the prop is `deviceState`, not `deviceBridge`.
+ *
+ * "Device Bridge" already names three different things in this codebase:
+ *   - `DeviceBridge`, the telemetry sync class that polls collectors and
+ *     pushes to the relay (packages/expo/src/device-bridge/index.ts:60);
+ *   - `PluginNative`, which sdk/types.ts:323 documents verbatim as
+ *     "Device Bridge — camera, location, sensors, storage";
+ *   - the v2 semantic layer in this file.
+ * A fourth use of the word would be the opposite of unmistakable. `deviceState`
+ * says what the object is (state, not actions) and collides with nothing.
+ *
+ *
+ * DESIGN NOTE 2 — why NOT `PluginNative.visual` / `PluginNative.connectivityState`.
+ *
+ * The implementation-grounding doc proposes adding the eight domains as fields
+ * on `PluginNative`, with `connectivityState` to dodge the collision with the
+ * existing `connectivity`. Rejected, for three reasons:
+ *
+ *   (a) It puts `native.camera.takePhoto()` and `native.visual.getSnapshot()`
+ *       on one object, one keystroke apart in autocomplete. The layer becomes
+ *       invisible at the call site, which is the failure being designed out.
+ *   (b) `native.connectivity` vs `native.connectivityState` is a confusable
+ *       pair by construction — two fields, one object, near-identical names,
+ *       different layers, different return shapes. `deviceState.connectivity`
+ *       vs `native.connectivity` is disambiguated by the first token instead.
+ *   (c) The gate model would have to span both meanings of one manifest field.
+ *
+ * The grounding doc's actual constraint is §14's "Do not create a second
+ * plugin runtime" — and this design does not. Same runtime, same registration,
+ * same bundle pipeline, same props object; one additional namespace on it.
+ * Everything else in that doc's file-by-file plan (resident engines, warm
+ * sessions, reference counting, no pipeline per tool call, the p50<10ms /
+ * p95<30ms snapshot budget) stands unchanged.
+ *
+ *
+ * DESIGN NOTE 3 — what this file does NOT decide, because the docs did not.
+ *
+ *  - Per-intent behavioural contracts. The architecture doc MANDATES that each
+ *    intent document latency goal, quality target, continuous-vs-one-shot,
+ *    rolling-history behaviour, power posture, background behaviour, required
+ *    permissions and output shape. No document supplies these for ANY of the
+ *    nine visual intents, and there is no equivalent table for activity. The
+ *    vocabulary is minted; the semantics behind each name are not. This is the
+ *    largest hole in the whole design and no amount of TypeScript closes it.
+ *  - Multi-consumer session ownership / reference counting.
+ *  - MediaHandle → bytes resolution, and expiry behaviour.
+ *  - Whether `visual.capture()` may use a different intent from the session.
+ *  - Event vocabularies for visual, activity, deviceContext. (Spatial's is a
+ *    DECISION, recorded at `SpatialEvent`, not a reading of the docs.)
+ *  - Per-event payload schemas for every domain but spatial
+ *    (`SpatialStateEvent`, likewise a DECISION).
+ *  - Background/foreground semantics for activity and connectivity (specified
+ *    only for visual).
+ *  - Numeric thresholds for fresh/aging/stale, and for "materially changed".
+ *  - Cross-domain conflict resolution (activity says walking, spatial speed
+ *    says vehicle) — explicitly deferred as future State Engine Fusion and
+ *    out of v2 scope. A v2 snapshot must be internally coherent; it is NOT
+ *    obliged to reconcile itself with another domain.
+ */