@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/src/device-state/quality.ts

@@ -0,0 +1,60 @@
+/**
+ * The honesty helpers — one place, shared by every domain module.
+ *
+ * A snapshot's `quality` says how much to trust it. R5 centralizes the three
+ * ways a domain answers honestly here so no domain re-implements them:
+ *   - qualityFrom(observedAt)  a live read, freshness stamped from its age.
+ *   - qualityUnknown()         "nothing was observed" — never dressed as fresh.
+ *   - unsupported(what)        an ACTION this build can't honour, refused by name.
+ *
+ * The `unknown` freshness shape is NOT re-declared here: it is the single
+ * canonical `neverObserved()` from the contract package, so the engine, the gate
+ * (deviceStateHost) and the types can never drift into three subtly different
+ * "unknown"s.
+ */
+import { neverObserved } from '@ateam-ai-mobile/plugin-runtime';
+import type { StateQuality } from '@ateam-ai-mobile/plugin-runtime';
+
+// ── Freshness ────────────────────────────────────────────────────────────
+//
+// Every snapshot carries when it was observed. `observedAt` is stamped at read
+// time by a live-reading domain; a caching domain passes its cache timestamp
+// instead. This is the one place the fresh/aging/stale thresholds live.
+
+export const FRESH_MS = 10_000;
+export const AGING_MS = 60_000;
+
+export function qualityFrom(
+  observedAt: number,
+  confidence?: StateQuality['confidence'],
+): StateQuality {
+  const ageMs = Date.now() - observedAt;
+  return {
+    freshness: {
+      state: ageMs < FRESH_MS ? 'fresh' : ageMs < AGING_MS ? 'aging' : 'stale',
+      observedAt,
+      ageMs,
+    },
+    ...(confidence ? { confidence } : {}),
+  };
+}
+
+/** Age genuinely unknown — treated as stale, never as fresh. */
+export function qualityUnknown(): StateQuality {
+  return { freshness: neverObserved() };
+}
+
+/**
+ * Refuse, by name, with the frozen error code.
+ *
+ * Used where the contract declares a method this build cannot honour. The
+ * alternative — a no-op that resolves — is the fabrication pattern in method
+ * form: the caller cannot tell "did nothing" from "worked".
+ */
+export function unsupported(what: string): Error {
+  const err: any = new Error(
+    `${what} is not implemented in this build — the native engine behind it does not exist yet.`,
+  );
+  err.code = 'UNSUPPORTED';
+  return err;
+}

package/src/device-state/replay.ts

@@ -0,0 +1,220 @@
+/**
+ * Replay — run guidance logic against a RECORDED WALK instead of a phone.
+ *
+ * WHY THIS EXISTS. Everything device-shaped is verifiable only on real
+ * hardware: the simulator has no camera, no pedometer, no moving GPS. So the
+ * loop was write → ask for a build → wait → ask someone to walk around the
+ * block. We could unit-test that the window clamp picks the smaller number; we
+ * could not test that THE GUIDE SAYS "TURN RIGHT" AT THE CORNER, which is the
+ * only thing a user cares about.
+ *
+ * A fixture is one real walk, recorded once by the app (see
+ * docs/SPEC_device_walk_recorder.md) and replayed here forever.
+ *
+ * IT REPLAYS AT THE SNAPSHOT LEVEL, not the sensor level, and that is a
+ * deliberate boundary. The engines already have their own tests — the turn
+ * detector, the activity classifier, the window clamp. What had no test was
+ * everything ABOVE them. So this implements the same `DeviceState` surface a
+ * plugin sees and serves recorded snapshots through it: the code under test is
+ * the guidance logic, unchanged, unaware it is not on a phone.
+ *
+ * THE CLOCK IS VIRTUAL. A ten-minute walk runs in milliseconds, and a test
+ * never waits. `t` in a fixture is milliseconds since the recording started,
+ * never a wall clock, so a fixture does not rot when the date changes.
+ *
+ * WHAT IT REFUSES TO SMOOTH OVER: a fixture's `unknown`s, `null`s and refusals
+ * are replayed exactly as recorded. They are the most valuable records in the
+ * file — they are what a guide must handle correctly, and precisely what a
+ * hand-written fixture would never contain.
+ */
+import type { DeviceState } from '@ateam-ai-mobile/plugin-runtime';
+
+/** One tick of a recorded walk. Domains are stored verbatim, never normalised. */
+export interface WalkSample {
+  /** Milliseconds since recording started. NOT a wall clock. */
+  t: number;
+  spatial?: any;
+  activity?: any;
+  visual?: any;
+  deviceContext?: any;
+  interaction?: any;
+  connectivity?: any;
+  capability?: any;
+  environment?: any;
+}
+
+/**
+ * A domain whose `start()` FAILED during recording.
+ *
+ * Recorded so a replayed walk fails the same way the real one did. Without it,
+ * a fixture where the pedometer was denied is indistinguishable from a fixture
+ * where activity simply never appeared — and only one of those is a bug.
+ */
+export interface WalkRefusal {
+  domain: string;
+  /** The error code the real call threw, e.g. RESTRICTED / UNSUPPORTED. */
+  code: string;
+  message?: string;
+}
+
+export interface WalkFixture {
+  /** Provenance. Without `sdkCommit`, a fixture that stops matching cannot be
+   *  told apart from a regression. */
+  header: {
+    recordedAt?: string;
+    appVersion?: string;
+    sdkCommit?: string;
+    device?: string;
+    os?: string;
+    /** What the visual engine reported it was really holding. */
+    retentionMs?: number | null;
+    withFrames?: boolean;
+    note?: string;
+  };
+  refusals?: WalkRefusal[];
+  /** Ascending by `t`. */
+  samples: WalkSample[];
+}
+
+/** A clock a test drives by hand. Nothing here ever waits. */
+export interface ReplayClock {
+  /** Current position in the walk, ms since start. */
+  now(): number;
+  /** Jump forward. Returns the new position. */
+  advance(ms: number): number;
+  /** Jump to an absolute offset. */
+  seek(ms: number): number;
+  /** Run to the end of the fixture. */
+  end(): number;
+  /** Total length of the recorded walk. */
+  durationMs(): number;
+}
+
+export interface ReplaySession {
+  deviceState: DeviceState;
+  clock: ReplayClock;
+  /** Which domains had a session opened by the code under test. */
+  started(): string[];
+}
+
+const DOMAINS = [
+  'spatial', 'visual', 'activity', 'deviceContext',
+  'connectivity', 'capability', 'environment', 'interaction',
+] as const;
+
+/** The snapshot a domain returns when the fixture has nothing for it. */
+function unknownSnapshot(domain: string): any {
+  const quality = { freshness: { state: 'unknown', observedAt: null, ageMs: null }, confidence: { level: 'unknown' } };
+  switch (domain) {
+    case 'spatial':
+      return { ...{ quality }, position: null, movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: 'unknown' }, orientation: { headingDeg: null }, recentPath: [] };
+    case 'visual':
+      return { quality, camera: { available: false, active: false, facing: 'unknown' }, latest: null, recentTimeline: { windowMs: 0, frames: [] } };
+    case 'activity':
+      return { quality, human: { state: 'unknown', since: null, confidence: { level: 'unknown' } }, devicePose: { placement: 'unknown', orientation: 'unknown', confidence: { level: 'unknown' } }, recentTransitions: [] };
+    default:
+      return { quality };
+  }
+}
+
+function refusal(domain: string, code: string, message?: string): Error {
+  const err: any = new Error(message || `deviceState.${domain}: refused during recording (${code}).`);
+  err.code = code;
+  err.domain = domain;
+  return err;
+}
+
+/**
+ * Build a `DeviceState` backed by a recorded walk.
+ *
+ * Hand the result to the code under test exactly as the host would hand it the
+ * real one — it cannot tell the difference, which is the point.
+ */
+export function createReplayDeviceState(fixture: WalkFixture): ReplaySession {
+  const samples = [...(fixture.samples || [])].sort((a, b) => a.t - b.t);
+  const duration = samples.length ? samples[samples.length - 1].t : 0;
+  const refusals = new Map((fixture.refusals || []).map(r => [r.domain, r]));
+  const openSessions = new Set<string>();
+
+  let cursor = 0;
+
+  const clock: ReplayClock = {
+    now: () => cursor,
+    advance: ms => (cursor = Math.min(duration, Math.max(0, cursor + ms))),
+    seek: ms => (cursor = Math.min(duration, Math.max(0, ms))),
+    end: () => (cursor = duration),
+    durationMs: () => duration,
+  };
+
+  /**
+   * The newest sample AT OR BEFORE the cursor.
+   *
+   * Never the nearest, and never interpolated. A guide reads what the device
+   * had ALREADY produced at that instant; letting a test see a value from
+   * slightly in the future would make it pass on information the real code
+   * could not have had.
+   */
+  const sampleAt = (): WalkSample | null => {
+    let found: WalkSample | null = null;
+    for (const s of samples) {
+      if (s.t > cursor) break;
+      found = s;
+    }
+    return found;
+  };
+
+  const domainFor = (name: string): any => ({
+    async getSnapshot() {
+      const s = sampleAt();
+      const recorded = s ? (s as any)[name] : undefined;
+      // Nothing recorded is an honest unknown, not an empty object — the same
+      // answer the real gate gives for a domain it cannot serve.
+      return recorded ?? unknownSnapshot(name);
+    },
+    async start() {
+      const r = refusals.get(name);
+      // Replay the refusal the real walk hit. A fixture recorded with the
+      // pedometer denied must fail here, or a test proves the guide works in
+      // conditions the user never had.
+      if (r) throw refusal(name, r.code, r.message);
+      openSessions.add(name);
+      return { id: `replay_${name}`, intent: 'replay', startedAt: 0 } as any;
+    },
+    async stop() { openSessions.delete(name); },
+    subscribe() {
+      // Deliberately unsupported: a fixture is a timeline a test steps through,
+      // so events would have to fire on `advance()`, and a subscription that
+      // silently never fires reads as "nothing has changed" — the failure this
+      // whole layer exists to prevent. Step the clock and read instead.
+      throw refusal(name, 'UNSUPPORTED', `deviceState.${name}.subscribe is not replayable — advance the clock and read.`);
+    },
+  });
+
+  const deviceState: any = {};
+  for (const d of DOMAINS) deviceState[d] = domainFor(d);
+
+  return { deviceState: deviceState as DeviceState, clock, started: () => [...openSessions] };
+}
+
+/** Parse a `.jsonl` recording into a fixture. First line is the header. */
+export function parseWalkJsonl(text: string): WalkFixture {
+  const lines = text.split('\n').map(l => l.trim()).filter(Boolean);
+  if (!lines.length) throw new Error('Empty recording — no header line.');
+
+  const first = JSON.parse(lines[0]);
+  const header = first.header ?? first;
+  const refusals: WalkRefusal[] = first.refusals ?? [];
+  const samples: WalkSample[] = [];
+
+  for (const line of lines.slice(1)) {
+    const rec = JSON.parse(line);
+    // Refusals may arrive as their own records mid-file (a session that failed
+    // partway through), not only in the header.
+    if (rec.refusal) { refusals.push(rec.refusal); continue; }
+    if (typeof rec.t === 'number') samples.push(rec);
+  }
+
+  // A truncated file is still usable — a walk that ended on a flat battery
+  // should not cost us the part that was recorded.
+  return { header, refusals, samples };
+}

package/src/device-state/turnDetector.ts

@@ -0,0 +1,121 @@
+/**
+ * Turning, and which way.
+ *
+ * "Turn right at the corner" and "you have just turned left" are the two
+ * sentences a walking guide says most, and neither can be read off a single
+ * heading — they need heading OVER TIME. This is that, as a pure state machine
+ * with no Expo import, so it can be tested against a scripted walk instead of
+ * against a phone in someone's hand.
+ *
+ * SIGN IS THE WHOLE POINT. Compass degrees increase clockwise, so a positive
+ * delta is a turn to the RIGHT and a negative one to the LEFT. A caller that
+ * wants only the magnitude can take the absolute value; a caller handed a
+ * magnitude cannot recover the side, and "turn 90°" without the side is worse
+ * than saying nothing.
+ *
+ * THE HARD PART IS NOT DETECTING TURNS, IT IS NOT INVENTING THEM. A phone held
+ * by a walking person swings 15–20° with every stride, and a compass drifts.
+ * Compare against a fixed origin and the drift eventually crosses any threshold
+ * on its own, so the machine re-baselines whenever the heading holds steady:
+ * "straight ahead" is wherever you have been pointing for the last couple of
+ * seconds, not wherever you were pointing when the session opened.
+ */
+
+/** A completed turn. `deg` is signed: **positive = clockwise = right**. */
+export interface TurnEvent {
+  deg: number;
+  /** When the turn was recognised as complete. */
+  timestamp: number;
+}
+
+export interface TurnDetectorOptions {
+  /**
+   * How far the heading must swing before it counts as a turn.
+   *
+   * 35° is a judgement, not a measurement: a street corner is ~90°, a gentle
+   * bend in a corridor 30–45°, and hand-sway while walking routinely 15–20°.
+   * Lower and the detector narrates the user's arm.
+   */
+  minTurnDeg?: number;
+  /** Within this of the reference counts as "still pointing the same way". */
+  stableDeg?: number;
+  /** How long it must stay there before the reference moves. */
+  stableMs?: number;
+}
+
+/** Signed shortest arc from `a` to `b`, in (-180, 180]. */
+export function signedDelta(a: number, b: number): number {
+  return ((b - a + 540) % 360) - 180;
+}
+
+export class TurnDetector {
+  private readonly minTurnDeg: number;
+  private readonly stableDeg: number;
+  private readonly stableMs: number;
+
+  /** The heading currently treated as "straight ahead". */
+  private refDeg: number | null = null;
+  private stableSince = 0;
+  private lastTurn: TurnEvent | null = null;
+
+  constructor(opts: TurnDetectorOptions = {}) {
+    this.minTurnDeg = opts.minTurnDeg ?? 35;
+    this.stableDeg = opts.stableDeg ?? 12;
+    this.stableMs = opts.stableMs ?? 2500;
+  }
+
+  /** Feed one compass reading. `null` degrees means the compass said nothing. */
+  push(deg: number | null, now: number): TurnEvent | null {
+    if (deg === null) return null;
+
+    if (this.refDeg === null) {
+      this.refDeg = deg;
+      this.stableSince = now;
+      return null;
+    }
+
+    const delta = signedDelta(this.refDeg, deg);
+
+    if (Math.abs(delta) >= this.minTurnDeg) {
+      // Re-baseline immediately, so a continuous 180° about-face is reported as
+      // the turns it is made of. Left as one growing delta it would flip sign
+      // at the halfway point and report a right turn for a left one.
+      this.lastTurn = { deg: Math.round(delta), timestamp: now };
+      this.refDeg = deg;
+      this.stableSince = now;
+      return this.lastTurn;
+    }
+
+    if (Math.abs(delta) > this.stableDeg) {
+      // Moving, but not far enough yet. Hold the reference and keep watching —
+      // this is what lets a slow 90° turn accumulate instead of being
+      // re-baselined away one degree at a time.
+      this.stableSince = now;
+      return null;
+    }
+
+    // Steady. After a while, treat here as the new straight-ahead.
+    if (now - this.stableSince >= this.stableMs) {
+      this.refDeg = deg;
+      this.stableSince = now;
+    }
+    return null;
+  }
+
+  /**
+   * The most recent completed turn, or null if none this session.
+   *
+   * It does NOT expire on its own: the age is derivable from `timestamp`, and
+   * "recent enough to mention" is a product judgement this layer must not make
+   * on the caller's behalf.
+   */
+  last(): TurnEvent | null {
+    return this.lastTurn;
+  }
+
+  reset(): void {
+    this.refDeg = null;
+    this.stableSince = 0;
+    this.lastTurn = null;
+  }
+}