@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/src/device-state/activityClassifier.ts

@@ -0,0 +1,151 @@
+/**
+ * What the user is doing, and how the phone is being held — as a pure function.
+ *
+ * Separated from the sensor plumbing so the JUDGEMENTS are testable: every
+ * threshold below is a claim about human beings, and a claim that decides
+ * whether a guide says "you have arrived" to someone sitting in a moving car
+ * deserves a test rather than a comment.
+ *
+ * WHY THIS DOMAIN EXISTS AT ALL WHEN SPATIAL ALREADY REPORTS MOVEMENT: GPS is
+ * what fails indoors, and indoors is where a guide most needs to know whether
+ * the user is walking. Steps come from the pedometer, which does not care about
+ * a roof. Spatial answers "are you moving through the world"; Activity answers
+ * "are you walking" — in a mall those are different questions with different
+ * sensors, and only one of them still works.
+ */
+import type { Confidence } from '@ateam-ai-mobile/plugin-runtime';
+
+export type HumanActivityValue =
+  | 'stationary' | 'walking' | 'running' | 'cycling' | 'driving' | 'unknown';
+export type PlacementValue = 'handheld' | 'pocket' | 'table' | 'mounted' | 'unknown';
+export type PoseOrientation = 'portrait' | 'landscape' | 'flat' | 'unknown';
+
+export interface ActivityInput {
+  /** Steps per minute over the recent window. `null` = no pedometer reading. */
+  cadenceSpm: number | null;
+  /**
+   * Variance of accelerometer magnitude (g²) over the recent window.
+   * `null` = the accelerometer has not reported yet.
+   */
+  accelVariance: number | null;
+  /** Low-pass gravity estimate in g. `null` = not sampled yet. */
+  gravity: { x: number; y: number; z: number } | null;
+  /**
+   * Speed from Spatial, when a spatial session is streaming.
+   *
+   * Passed IN rather than read here, so this stays pure. It exists for exactly
+   * one job: a phone in a moving car looks identical to a phone on a desk —
+   * no steps, little vibration — and calling that `stationary` would tell a
+   * guide the user has arrived while they are doing 50 km/h.
+   */
+  speedMps: number | null;
+}
+
+export interface ActivityVerdict {
+  human: { state: HumanActivityValue; confidence: Confidence };
+  pose: { placement: PlacementValue; orientation: PoseOrientation; confidence: Confidence };
+}
+
+/**
+ * Cadence bands, in steps per minute.
+ *
+ * Ordinary walking sits around 100–120 spm and running around 160–180. 140 is
+ * placed in the gap rather than at either edge: misreading a fast walk as a run
+ * is harmless, but the reverse would have a guide give walking directions to
+ * someone covering ground twice as fast.
+ *
+ * 20 spm is the floor for "walking at all" — below that it is a few steps of
+ * shuffling, which is not travel.
+ */
+const RUN_SPM = 140;
+const WALK_SPM = 20;
+
+/**
+ * Accelerometer magnitude variance, in g².
+ *
+ * A phone lying on a table reads a near-constant 1g, so its variance is
+ * essentially sensor noise. A hand holding a phone never manages that.
+ */
+const STILL_VAR = 0.002;
+/** Above this the phone is being moved about, not merely held. */
+const ACTIVE_VAR = 0.02;
+
+/**
+ * Speed at which the user is certainly not walking, in m/s.
+ *
+ * 3 m/s is ~11 km/h — above a fast walk (~2 m/s) and below anything a vehicle
+ * does in traffic.
+ */
+const VEHICLE_MPS = 3;
+
+/** Gravity component that has to dominate before an axis names the pose. */
+const AXIS_DOMINANT = 0.75;
+
+export function classifyActivity(input: ActivityInput): ActivityVerdict {
+  return { human: classifyHuman(input), pose: classifyPose(input) };
+}
+
+function classifyHuman({ cadenceSpm, accelVariance, speedMps }: ActivityInput): ActivityVerdict['human'] {
+  // Steps are the strongest evidence there is, and the only one that survives
+  // indoors. Take them first when they exist.
+  if (cadenceSpm !== null && cadenceSpm >= RUN_SPM) {
+    return { state: 'running', confidence: { level: 'high' } };
+  }
+  if (cadenceSpm !== null && cadenceSpm >= WALK_SPM) {
+    return { state: 'walking', confidence: { level: 'high' } };
+  }
+
+  // No meaningful stepping. Before calling it stationary, rule out a vehicle:
+  // riding is not walking, and it is not standing still either.
+  if (speedMps !== null && speedMps >= VEHICLE_MPS) {
+    // Moving fast without stepping. Which vehicle it is cannot be told from an
+    // accelerometer and a pedometer — separating cycling from driving needs
+    // real activity recognition (CMMotionActivity), which is not available
+    // here. `unknown` with the speed already published by Spatial is honest;
+    // guessing `driving` because it is the commoner case is not.
+    return { state: 'unknown', confidence: { level: 'low' } };
+  }
+
+  if (accelVariance !== null && accelVariance < STILL_VAR && (cadenceSpm === null || cadenceSpm < WALK_SPM)) {
+    // Genuinely still. Medium rather than high: a phone resting in a
+    // stationary car at a red light produces exactly this, and Spatial's speed
+    // cannot separate them either while the car is stopped.
+    return { state: 'stationary', confidence: { level: 'medium' } };
+  }
+
+  // Something is moving but nothing identifies it — a phone being handled
+  // while its owner stands still, most often. Naming an activity here would be
+  // a guess dressed as a reading.
+  return { state: 'unknown', confidence: { level: 'unknown' } };
+}
+
+function classifyPose({ gravity, accelVariance }: ActivityInput): ActivityVerdict['pose'] {
+  if (!gravity) {
+    return { placement: 'unknown', orientation: 'unknown', confidence: { level: 'unknown' } };
+  }
+
+  const { x, y, z } = gravity;
+  const orientation: PoseOrientation =
+    Math.abs(z) >= AXIS_DOMINANT ? 'flat'
+      : Math.abs(y) >= AXIS_DOMINANT ? 'portrait'
+      : Math.abs(x) >= AXIS_DOMINANT ? 'landscape'
+      : 'unknown';
+
+  // Flat and utterly still is a surface. This is the one placement the sensors
+  // can actually establish.
+  if (orientation === 'flat' && accelVariance !== null && accelVariance < STILL_VAR) {
+    return { placement: 'table', orientation, confidence: { level: 'high' } };
+  }
+
+  // Upright and moving a little is a hand. Medium, because a phone in a shirt
+  // pocket looks much the same and this cannot tell them apart.
+  if (orientation !== 'flat' && accelVariance !== null && accelVariance >= ACTIVE_VAR) {
+    return { placement: 'handheld', orientation, confidence: { level: 'medium' } };
+  }
+
+  // `pocket` and `mounted` are NEVER returned. Distinguishing a pocket needs
+  // the proximity or light sensor, and a car mount needs Bluetooth or CarPlay
+  // context — none of which is wired. The orientation is still reported,
+  // because it was actually measured.
+  return { placement: 'unknown', orientation, confidence: { level: 'unknown' } };
+}

package/src/device-state/activityEngine.ts

@@ -0,0 +1,252 @@
+/**
+ * The Activity engine — steps and motion, sampled into short windows.
+ *
+ * Sensors only. Every judgement made from them lives in `activityClassifier`,
+ * which is pure and tested; this file's whole job is to keep two subscriptions
+ * alive and turn their streams into the three numbers the classifier wants.
+ *
+ * IT IS SESSION-SCOPED, and that is a power decision rather than a stylistic
+ * one. An accelerometer left running is a background drain and a pedometer
+ * subscription is a permission-visible one, so neither starts until a plugin
+ * declares it needs Activity. `getSnapshot()` with no session open returns an
+ * explicit unknown rather than quietly switching the sensors on — a read must
+ * not have that side effect.
+ */
+import type { HumanActivityValue } from './activityClassifier';
+
+/**
+ * expo-sensors is loaded LAZILY, on the first `start()`, and never at import.
+ *
+ * This module is reachable from app startup, and expo-sensors is a NATIVE
+ * module: an app binary built before it was added does not contain it. A
+ * top-level import that threw during evaluation would not degrade the Activity
+ * domain — it would fail the bundle and black-screen the whole app, on exactly
+ * the builds that predate this change. So the failure is contained here, where
+ * it can be reported as "no sensors" instead.
+ */
+let sensors: any = null;
+let sensorsMissing = false;
+
+function loadSensors(): any {
+  if (sensors || sensorsMissing) return sensors;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    sensors = require('expo-sensors');
+  } catch {
+    sensorsMissing = true;
+    sensors = null;
+  }
+  return sensors;
+}
+
+/** Accelerometer cadence. 5 Hz is plenty for pose and for a variance band. */
+const ACCEL_INTERVAL_MS = 200;
+/** Motion window. Long enough to smooth a stride, short enough to be current. */
+const MOTION_WINDOW_MS = 3000;
+/**
+ * Step window.
+ *
+ * 20s, because cadence over a shorter window swings wildly at the start and end
+ * of walking — someone who takes four steps and stops would otherwise read as
+ * a steady 120 spm for a moment.
+ */
+const STEP_WINDOW_MS = 20_000;
+/** Low-pass coefficient isolating gravity from the raw accelerometer. */
+const GRAVITY_ALPHA = 0.1;
+
+interface StepSample { steps: number; t: number }
+
+class ActivityEngine {
+  private accelSub: { remove(): void } | null = null;
+  private stepSub: { remove(): void } | null = null;
+
+  private magnitudes: Array<{ m: number; t: number }> = [];
+  private gravity: { x: number; y: number; z: number } | null = null;
+  private steps: StepSample[] = [];
+
+  private sessionId: string | null = null;
+  private startedAt = 0;
+  /** When the CURRENT reading last changed — feeds `human.since`. */
+  private pedometerAvailable: boolean | null = null;
+
+  isRunning(): boolean { return this.sessionId !== null; }
+  session(): { id: string; startedAt: number } | null {
+    return this.sessionId ? { id: this.sessionId, startedAt: this.startedAt } : null;
+  }
+
+  /**
+   * @param classify how to name the current activity — injected so the engine
+   * keeps no opinion of its own and the classifier stays pure and testable.
+   */
+  async start(classify: () => HumanActivityValue): Promise<{ id: string; startedAt: number }> {
+    if (this.sessionId) return this.session()!;
+    this.sessionId = `activity_${Date.now()}`;
+    this.startedAt = Date.now();
+
+    const s = loadSensors();
+    if (!s) {
+      // An app binary built before expo-sensors was added. The session is open
+      // — stopping it would be a lie in the other direction — but nothing
+      // samples, so every window stays empty and the classifier says `unknown`.
+      this.pedometerAvailable = false;
+      this.startTicking(classify);
+      return this.session()!;
+    }
+    const { Accelerometer, Pedometer } = s;
+
+    Accelerometer.setUpdateInterval(ACCEL_INTERVAL_MS);
+    this.accelSub = Accelerometer.addListener(({ x, y, z }: { x: number; y: number; z: number }) => {
+      const now = Date.now();
+      // Raw magnitude includes gravity, so a still phone sits at ~1g and the
+      // variance of this series is the motion signal.
+      this.magnitudes.push({ m: Math.sqrt(x * x + y * y + z * z), t: now });
+      const cutoff = now - MOTION_WINDOW_MS;
+      if (this.magnitudes.length > 8 && this.magnitudes[0].t < cutoff) {
+        this.magnitudes = this.magnitudes.filter(s => s.t >= cutoff);
+      }
+      // Gravity by low-pass: what survives smoothing is the constant pull, and
+      // that is what says which way up the phone is.
+      this.gravity = this.gravity
+        ? {
+            x: this.gravity.x + GRAVITY_ALPHA * (x - this.gravity.x),
+            y: this.gravity.y + GRAVITY_ALPHA * (y - this.gravity.y),
+            z: this.gravity.z + GRAVITY_ALPHA * (z - this.gravity.z),
+          }
+        : { x, y, z };
+    });
+
+    try {
+      this.pedometerAvailable = await Pedometer.isAvailableAsync();
+    } catch {
+      this.pedometerAvailable = false;
+    }
+    if (this.pedometerAvailable) {
+      try {
+        this.stepSub = Pedometer.watchStepCount(({ steps }: { steps: number }) => {
+          this.steps.push({ steps, t: Date.now() });
+          const cutoff = Date.now() - STEP_WINDOW_MS;
+          if (this.steps.length > 2 && this.steps[0].t < cutoff) {
+            this.steps = this.steps.filter(s => s.t >= cutoff);
+          }
+        });
+      } catch {
+        // Permission refused, most likely (iOS Motion & Fitness). Cadence stays
+        // null, the classifier says `unknown`, and nothing pretends otherwise.
+        this.stepSub = null;
+        this.pedometerAvailable = false;
+      }
+    }
+
+    this.startTicking(classify);
+    return this.session()!;
+  }
+
+  stop(): void {
+    this.accelSub?.remove();
+    this.stepSub?.remove();
+    this.accelSub = null;
+    this.stepSub = null;
+    this.sessionId = null;
+    this.stopTicking();
+    // The windows belong to the session. Keeping them would let a later read
+    // report a walk that finished before the phone went in a drawer.
+    this.magnitudes = [];
+    this.steps = [];
+    this.gravity = null;
+  }
+
+  /** Variance of accelerometer magnitude over the motion window, in g². */
+  accelVariance(): number | null {
+    const cutoff = Date.now() - MOTION_WINDOW_MS;
+    const window = this.magnitudes.filter(s => s.t >= cutoff);
+    // Two samples is not a variance; it is a coincidence.
+    if (window.length < 5) return null;
+    const mean = window.reduce((a, s) => a + s.m, 0) / window.length;
+    return window.reduce((a, s) => a + (s.m - mean) ** 2, 0) / window.length;
+  }
+
+  currentGravity(): { x: number; y: number; z: number } | null { return this.gravity; }
+
+  /**
+   * Steps per minute over the step window.
+   *
+   * Computed from the DIFFERENCE between the first and last cumulative counts,
+   * so it does not matter whether the platform counts from subscription start
+   * or from midnight.
+   *
+   * Returns null — not 0 — when the window is too short to divide by. Zero
+   * steps per minute is a real claim ("standing still") and must only be made
+   * once there is a window long enough to support it.
+   */
+  cadenceSpm(): number | null {
+    const cutoff = Date.now() - STEP_WINDOW_MS;
+    const window = this.steps.filter(s => s.t >= cutoff);
+    if (window.length < 2) {
+      // The pedometer is alive and has simply reported nothing recently, which
+      // is what standing still looks like: no callbacks at all.
+      if (this.pedometerAvailable && Date.now() - this.startedAt > STEP_WINDOW_MS) return 0;
+      return null;
+    }
+    const first = window[0], last = window[window.length - 1];
+    const minutes = (last.t - first.t) / 60_000;
+    if (minutes <= 0) return null;
+    return (last.steps - first.steps) / minutes;
+  }
+
+  /** Whether a pedometer exists and is permitted. Null before `start()`. */
+  hasPedometer(): boolean | null { return this.pedometerAvailable; }
+
+  /** When the newest sample arrived — what freshness is actually about. */
+  observedAt(): number | null {
+    const ts = [
+      this.magnitudes[this.magnitudes.length - 1]?.t,
+      this.steps[this.steps.length - 1]?.t,
+    ].filter((t): t is number => typeof t === 'number');
+    return ts.length ? Math.max(...ts) : null;
+  }
+
+  // ── transitions ──
+  //
+  // Tracked on a timer inside the engine rather than computed when someone
+  // reads, because a transition is an EVENT: "you started walking" happens
+  // between two reads, and a domain that only classifies on demand reports the
+  // state and loses the moment it changed. `since` has the same problem.
+
+  private current: HumanActivityValue = 'unknown';
+  private since: number | null = null;
+  private transitions: Array<{ name: string; timestamp: number }> = [];
+  private ticker: ReturnType<typeof setInterval> | null = null;
+
+  /** Feed the engine its own classification once a second. */
+  private startTicking(classify: () => HumanActivityValue): void {
+    this.ticker = setInterval(() => {
+      const next = classify();
+      if (next === this.current) return;
+      this.current = next;
+      this.since = Date.now();
+      // The transition NAME reuses the frozen HumanActivity vocabulary — it is
+      // the state being entered. The freeze leaves transition names as bare
+      // strings with no controlled vocabulary, and inventing one ("walk_start")
+      // would put a word in plugins that the freeze may later contradict.
+      this.transitions = [...this.transitions, { name: next, timestamp: this.since }].slice(-10);
+    }, 1000);
+  }
+
+  private stopTicking(): void {
+    if (this.ticker) clearInterval(this.ticker);
+    this.ticker = null;
+    this.current = 'unknown';
+    this.since = null;
+    this.transitions = [];
+  }
+
+  /** When the current activity began, or null if it has not been established. */
+  currentSince(): number | null { return this.since; }
+  /** Newest last, bounded. Empty is a real answer: nothing has changed yet. */
+  recentTransitions(): Array<{ name: string; timestamp: number }> {
+    return [...this.transitions];
+  }
+}
+
+/** One engine per app: the sensors are singleton hardware. */
+export const activityEngine = new ActivityEngine();

package/src/device-state/collectors.ts

@@ -0,0 +1,31 @@
+/**
+ * The explicit dependencies the composition root injects into the domains.
+ *
+ * Collectors arrive by INJECTION rather than import: the two repos keep
+ * device-bridge in different places, so a hard relative import can only compile
+ * in one of them. Injection also matches how the rest of this SDK takes host
+ * capabilities, and lets a test drive the engines without an Expo runtime.
+ */
+export interface DeviceStateCollectors {
+  connectivity?: { collectConnectivity(): Promise<any> };
+  location?: {
+    getPosition(opts?: { accuracy?: 'low' | 'high' }): Promise<any>;
+    watchPosition(cb: (pos: any) => void): () => void;
+    hasPermission(): Promise<boolean>;
+  };
+}
+
+/**
+ * The one number Activity needs from Spatial, and the only thing shared between
+ * two domains.
+ *
+ * Passed as an explicit reference rather than a cross-domain import, because
+ * Activity's job is to answer "is the user walking" and it cannot do that
+ * honestly without knowing whether the phone is in a moving vehicle: no steps
+ * and no vibration describes a desk and a car equally well.
+ *
+ * `at` matters as much as the value. A speed from two minutes ago says nothing
+ * about now, and a stale speed used to rule out "stationary" would be worse than
+ * having none.
+ */
+export interface SpeedRef { mps: number | null; at: number }

package/src/device-state/domains/activity.ts

@@ -0,0 +1,93 @@
+// ── activity ─────────────────────────────────────────────────────────────
+//   THE INDOOR MOVEMENT SIGNAL (Spatial stops working indoors).
+import type { DeviceState, ActivitySnapshot } from '@ateam-ai-mobile/plugin-runtime';
+import { activityEngine } from '../activityEngine';
+import { classifyActivity, type ActivityInput } from '../activityClassifier';
+import type { SpeedRef } from '../collectors';
+import { qualityFrom, qualityUnknown, unsupported } from '../quality';
+
+/**
+ * What the user is doing, and how the phone is being held.
+ *
+ * THIS IS THE INDOOR MOVEMENT SIGNAL. Spatial answers "are you moving through
+ * the world" and stops being able to indoors, which is exactly where a guide
+ * most needs to know whether its user is walking. The pedometer does not care
+ * about a roof.
+ *
+ * SESSION-SCOPED, unlike the passive domains. An accelerometer left running is
+ * a background drain and a pedometer subscription is permission-visible on
+ * iOS, so nothing samples until a plugin says it needs this. A `getSnapshot()`
+ * with no session open returns an explicit unknown rather than switching the
+ * sensors on — a read must not have that side effect, and one that did would
+ * also return junk, since the windows would be empty at the moment it started.
+ */
+export function createActivityDomain(speedRef: SpeedRef): DeviceState['activity'] {
+  /** A speed older than this says nothing about now. */
+  const SPEED_MAX_AGE_MS = 15_000;
+
+  const input = (): ActivityInput => ({
+    cadenceSpm: activityEngine.cadenceSpm(),
+    accelVariance: activityEngine.accelVariance(),
+    gravity: activityEngine.currentGravity(),
+    speedMps:
+      speedRef.at && Date.now() - speedRef.at < SPEED_MAX_AGE_MS ? speedRef.mps : null,
+  });
+
+  return {
+    async getSnapshot(): Promise<ActivitySnapshot> {
+      if (!activityEngine.isRunning()) {
+        // Nothing is sampling. Every field says so rather than describing a
+        // motionless phone, which is what an unstarted engine would look like.
+        return {
+          human: { state: 'unknown', since: null, confidence: { level: 'unknown' } },
+          devicePose: { placement: 'unknown', orientation: 'unknown', confidence: { level: 'unknown' } },
+          recentTransitions: [],
+          quality: qualityUnknown(),
+        };
+      }
+
+      const verdict = classifyActivity(input());
+      const observedAt = activityEngine.observedAt();
+      const transitions = activityEngine.recentTransitions();
+
+      return {
+        human: {
+          state: verdict.human.state,
+          since: activityEngine.currentSince(),
+          confidence: verdict.human.confidence,
+        },
+        devicePose: {
+          placement: verdict.pose.placement,
+          orientation: verdict.pose.orientation,
+          confidence: verdict.pose.confidence,
+        },
+        transition: {
+          current: verdict.human.state,
+          // A hint, and we have no basis for one. The freeze calls `likelyNext`
+          // advisory; advisory is not licence to invent it.
+          likelyNext: null,
+        },
+        recentTransitions: transitions,
+        quality: observedAt === null
+          ? qualityUnknown()
+          : qualityFrom(observedAt, verdict.human.confidence),
+      };
+    },
+
+    /**
+     * Start sampling. The intent is recorded but does not yet change strategy —
+     * there is no native power-tuning layer for it to reach.
+     */
+    async start(options) {
+      const s = await activityEngine.start(() => classifyActivity(input()).human.state);
+      return { id: s.id, intent: options.intent, startedAt: s.startedAt } as any;
+    },
+
+    async stop() { activityEngine.stop(); },
+
+    // No activity event vocabulary is frozen — the design notes there is no
+    // "Initial Activity Events" list at all — so naming events here would put
+    // words in plugins that the freeze may contradict.
+    subscribe() { throw unsupported('activity.subscribe'); },
+  };
+}

package/src/device-state/domains/capability.ts

@@ -0,0 +1,60 @@
+// ── capability ───────────────────────────────────────────────────────────
+//   permission ✓   availability ✗   restriction ✗
+import type { DeviceState, CapabilitySnapshot, CapabilityStatus } from '@ateam-ai-mobile/plugin-runtime';
+import type { DeviceStateCollectors } from '../collectors';
+import { qualityFrom, unsupported } from '../quality';
+
+/**
+ * The bridge's permission model is 4-valued (`not_requested | granted | denied
+ * | not_needed`); the frozen one is 7-valued. The extra states are real OS
+ * distinctions nothing currently reads, so they map to `unknown` rather than
+ * being collapsed into `denied` — "restricted by policy" and "the user said no"
+ * are different problems with different remedies, and guessing between them
+ * would put a wrong instruction in front of the user.
+ */
+function statusFrom(granted: boolean | null): CapabilityStatus {
+  return {
+    support: 'unknown',
+    permission: granted === null ? 'unknown' : granted ? 'granted' : 'denied',
+    availability: 'unknown',
+  };
+}
+
+const UNKNOWN_STATUS: CapabilityStatus = {
+  support: 'unknown',
+  permission: 'unknown',
+  availability: 'unknown',
+};
+
+export function createCapabilityDomain(collectors: DeviceStateCollectors): DeviceState['capability'] {
+  return {
+    async getSnapshot(): Promise<CapabilitySnapshot> {
+      const observedAt = Date.now();
+      const locationGranted = collectors.location
+        ? await collectors.location.hasPermission().catch(() => null)
+        : null;
+
+      return {
+        // Only location has a real reader today. The rest are declared by the
+        // contract and answered honestly rather than omitted.
+        camera: UNKNOWN_STATUS,
+        microphone: UNKNOWN_STATUS,
+        location: {
+          ...statusFrom(locationGranted),
+          // iOS 14+ distinguishes precise from approximate; nothing reads it.
+          precision: 'unknown',
+          backgroundPermission: 'unknown',
+        },
+        motion: UNKNOWN_STATUS,
+        bluetooth: UNKNOWN_STATUS,
+        uwb: UNKNOWN_STATUS,
+        nfc: UNKNOWN_STATUS,
+        quality: qualityFrom(observedAt),
+      } as CapabilitySnapshot;
+    },
+
+    // No OS permission-change stream is wired. Same reasoning as connectivity:
+    // silence would be indistinguishable from stability.
+    subscribe() { throw unsupported('capability.subscribe'); },
+  };
+}

package/src/device-state/domains/connectivity.ts

@@ -0,0 +1,60 @@
+// ── connectivity ─────────────────────────────────────────────────────────
+//   reachability ✓  transport ✓   quality/stability/metered ✗
+import type { DeviceState, ConnectivitySnapshot } from '@ateam-ai-mobile/plugin-runtime';
+import type { DeviceStateCollectors } from '../collectors';
+import { qualityFrom, qualityUnknown, unsupported } from '../quality';
+
+export function createConnectivityDomain(collectors: DeviceStateCollectors): DeviceState['connectivity'] {
+  return {
+    async getSnapshot(): Promise<ConnectivitySnapshot> {
+      const observedAt = Date.now();
+      try {
+        if (!collectors.connectivity) throw unsupported('connectivity collector');
+        const data: any = await collectors.connectivity.collectConnectivity();
+        const online = data?.is_connected === true;
+        const type = String(data?.type || '').toLowerCase();
+
+        return {
+          reachability: data?.is_connected == null ? 'unknown' : online ? 'online' : 'offline',
+          transport:
+            type === 'wifi' ? 'wifi'
+              : type === 'cellular' ? 'cellular'
+              : type === 'ethernet' ? 'ethernet'
+              : online ? 'other'
+              : data?.is_connected === false ? 'none'
+              : 'unknown',
+          // All four below need measurement nobody takes yet. `unknown` is the
+          // designed answer — "return unknown rather than stale precision".
+          qualityClass: 'unknown',
+          stability: 'unknown',
+          latencyMs: null,
+          bandwidthClass: 'unknown',
+          metered: null,
+          constrained: null,
+          quality: qualityFrom(observedAt),
+        };
+      } catch {
+        return {
+          reachability: 'unknown',
+          transport: 'unknown',
+          qualityClass: 'unknown',
+          stability: 'unknown',
+          latencyMs: null,
+          bandwidthClass: 'unknown',
+          metered: null,
+          constrained: null,
+          quality: qualityUnknown(),
+        };
+      }
+    },
+
+    // Intent selects a native sampling strategy — latency probes, quality
+    // classification. Nothing here samples anything, so accepting an intent
+    // would be accepting an instruction we do not carry out.
+    async start() { throw unsupported('connectivity.start'); },
+    async stop() { throw unsupported('connectivity.stop'); },
+    // A subscription that can never fire is worse than none: the caller
+    // reasonably reads silence as "nothing changed".
+    subscribe() { throw unsupported('connectivity.subscribe'); },
+  };
+}