feat: LTL operators, sampling, and default generators (#17)

* feat(ltl): add Now/Next/Eventually/Implies/Or/And/Not formulas

Replace the fold-with-latch evaluator with a residual-formula reducer.
Each Observe() instantiates a fresh obligation from the root (stripping
an outer Always), reduces each pending obligation against current state,
latches Violated on first failure, and surfaces Pending verdicts for
deferred obligations. Existing Always/Pure/Thunk tests continue to pass.

* feat(ltl): support relative duration for eventually().within()

* feat(proto): add Swipe, PressKey, RecentLogs RPCs

* feat(verifier,runner): formula handles, new action kinds, rich state

- verifier: add formula-spec registry; bindNow/bindNext/bindEventually with
  chainable .implies/.or/.and/.not and .within(n,unit) on eventually; bindFrom
  for uniform sampling. bindAlways keeps accepting plain predicates.
- verifier: store lastTree, lastAction, step time, logs, exceptions on the
  Verifier; SnapshotInput replaces the (snapshots, tree) pair. stateObject now
  produces state.lastAction/time/logs/exceptions matching the TS State type.
- verifier: make taps/swipes/waitOnce/pressKey built-in generators actually
  fire; taps picks a clickable, enabled element from the last hierarchy.
- agent: add exceptions field to Message wire format.
- driver: add Swipe/PressKey/RecentLogs to Driver interface; wire maestro
  client and mock driver. LogEntry exposed for runner consumption.
- runner: apply Swipe/PressKey/Wait actions; collect logcat and exceptions;
  pass lastAction and step time into PushSnapshot.

* feat(spec-api): LTL operators, new actions, richer State

- ltl.ts exports now/next/eventually; always overload accepts a Formula
- types.ts: Formula gains implies/or/and/not; EventuallyFormula adds .within;
  State gains lastAction/time/logs/exceptions; Swipe/PressKey/Wait action types
- actions.ts: Swipe/PressKey/Wait/from constructors; waitOnce + pressKey
  default generators
- tests exercise the chaining, sampling, and new actions through a recorded
  fake runtime

* feat(sidecar): add swipe, pressKey, recentLogs RPC handlers

* feat(sdk-android): capture uncaught exceptions

Install a default uncaught handler on Uatu.start, chained with any
existing handler so Android's crash reporter still runs. Expose
Uatu.reportError for callers to forward caught throwables. A bounded
circular buffer (default 50) drains into each STATE message's new
exceptions field. Protocol.kt serializes/deserializes the field,
matching the Go wire format added to internal/agent/protocol.go.

* feat(spec-api): add @uatu/spec/defaults/properties bundle

* feat(sample-app): exercise new LTL operators + defaults

spec.ts now imports eventually/next/now/from from @uatu/spec and
noUncaughtExceptions from @uatu/spec/defaults/properties. It declares
three properties that exercise the new surface:

- accountCountNonNegative: plain always() safety
- addAccountAdvances: always(now(x).implies(next(y)))
- eventuallyLoggedIn: eventually(p).within(30, "seconds")
- noUncaughtExceptions: imported default

The weighted actions root uses from() for random phone/name sampling
and entries for taps/swipes/waitOnce/pressKey built-ins.

SampleApplication gains a debug hook gated on the system property
uatu.inject_error so the e2e run can synthesize an Uatu.reportError and
verify noUncaughtExceptions violates.

cmd/uatu/test_run.go adds a subpath alias so specs importing
"@uatu/spec/defaults/properties" resolve against the in-tree source
when running from the uatu checkout. The spec-integration tests swap
the old click-counter fixtures for the new login hierarchy.

* feat(trace): record swipe/key/wait details + exceptions

trace.Step gains an Exceptions array so the trace captures the
class/message/stackTrace for each SDK-reported throwable in a step.
trace.Action gains FromX/FromY/ToX/ToY/Key/DurationMillis so the full
payload of Swipe/PressKey/Wait actions is visible in trace.jsonl.

sample-app's debug error hook now gates on ApplicationInfo.DEBUGGABLE
instead of a system property (adb setprop fails on non-rooted
emulators).

pkg/spec-api/src/actions.ts

@@ -3,7 +3,13 @@ import type {
   Action,
   ActionGenerator,
   InputTextAction,
+  Key,
+  Point,
+  PressKeyAction,
+  Sampler,
+  SwipeAction,
   TapAction,
+  WaitAction,
   WeightedEntry,
 } from "./types.ts";
 
@@ -15,22 +21,50 @@ export function weighted(...entries: WeightedEntry[]): ActionGenerator {
   return globalThis.__uatu__.weighted(...entries);
 }
 
+export function from<T>(items: readonly T[]): Sampler<T> {
+  return globalThis.__uatu__.from(items);
+}
+
 export function Tap(parameters: { on: string | AccessibilityElement }): TapAction {
   return globalThis.__uatu__.tap(parameters);
 }
 
-export function InputText(parameters: { into: string | AccessibilityElement; text: string }): InputTextAction {
+export function InputText(parameters: {
+  into: string | AccessibilityElement;
+  text: string;
+}): InputTextAction {
   return globalThis.__uatu__.inputText(parameters);
 }
 
-export const taps: ActionGenerator = new Proxy({} as ActionGenerator, {
-  get(_target, property) {
-    return (globalThis.__uatu__.taps as unknown as Record<string | symbol, unknown>)[property];
-  },
-});
+export function Swipe(parameters: {
+  from: Point | AccessibilityElement;
+  to: Point | AccessibilityElement;
+  durationMillis?: number;
+}): SwipeAction {
+  return globalThis.__uatu__.swipe(parameters);
+}
 
-export const swipes: ActionGenerator = new Proxy({} as ActionGenerator, {
-  get(_target, property) {
-    return (globalThis.__uatu__.swipes as unknown as Record<string | symbol, unknown>)[property];
-  },
-});
+export function PressKey(parameters: { key: Key }): PressKeyAction {
+  return globalThis.__uatu__.pressKey(parameters);
+}
+
+export function Wait(parameters: { durationMillis: number }): WaitAction {
+  return globalThis.__uatu__.wait(parameters);
+}
+
+function builtinGenerator(name: "taps" | "swipes" | "waitOnce" | "pressKeys"): ActionGenerator {
+  return new Proxy({} as ActionGenerator, {
+    get(_target, property) {
+      const runtime = globalThis.__uatu__[name] as unknown as Record<
+        string | symbol,
+        unknown
+      >;
+      return runtime[property];
+    },
+  });
+}
+
+export const taps: ActionGenerator = builtinGenerator("taps");
+export const swipes: ActionGenerator = builtinGenerator("swipes");
+export const waitOnce: ActionGenerator = builtinGenerator("waitOnce");
+export const pressKey: ActionGenerator = builtinGenerator("pressKeys");

pkg/spec-api/src/defaults/properties.ts

@@ -0,0 +1,21 @@
+import { always } from "../ltl.ts";
+import { extract } from "../extract.ts";
+import type { Formula } from "../types.ts";
+
+const exceptionCount = extract<number>((state) => state.exceptions.length);
+
+// Fails when the SDK captured an uncaught throwable or a Uatu.reportError
+// call surfaced one during the run.
+export const noUncaughtExceptions: Formula = always(
+  () => exceptionCount.current === 0,
+);
+
+const errorLogCount = extract<number>(
+  (state) => state.logs.reduce((count, log) => count + (log.level === "E" ? 1 : 0), 0),
+);
+
+// Fails when the runner's logcat fetch observed any error-level lines since
+// the previous step.
+export const noLogcatErrors: Formula = always(
+  () => errorLogCount.current === 0,
+);

pkg/spec-api/src/index.ts

@@ -3,15 +3,38 @@ export type {
   AccessibilityTree,
   Action,
   ActionGenerator,
+  EventuallyFormula,
+  ExceptionRecord,
   Extracted,
   Formula,
   InputTextAction,
+  Key,
+  LogEntry,
+  Point,
+  PressKeyAction,
+  Sampler,
   Snapshots,
   State,
+  SwipeAction,
   TapAction,
+  UatuRuntime,
+  WaitAction,
   WeightedEntry,
 } from "./types.ts";
 
 export { extract } from "./extract.ts";
-export { always } from "./ltl.ts";
-export { Tap, InputText, actions, weighted, taps, swipes } from "./actions.ts";
+export { always, eventually, next, now } from "./ltl.ts";
+export {
+  InputText,
+  PressKey,
+  Swipe,
+  Tap,
+  Wait,
+  actions,
+  from,
+  pressKey,
+  swipes,
+  taps,
+  waitOnce,
+  weighted,
+} from "./actions.ts";

pkg/spec-api/src/ltl.ts

@@ -1,5 +1,20 @@
-import type { Formula } from "./types.ts";
+import type { EventuallyFormula, Formula } from "./types.ts";
 
-export function always(predicate: () => boolean): Formula {
-  return globalThis.__uatu__.always(predicate);
+export function always(predicateOrFormula: (() => boolean) | Formula): Formula {
+  return globalThis.__uatu__.always(predicateOrFormula);
+}
+
+export function now(predicate: () => boolean): Formula {
+  return globalThis.__uatu__.now(predicate);
+}
+
+export function next(predicate: () => boolean): Formula {
+  return globalThis.__uatu__.next(predicate);
+}
+
+// An unbounded `eventually` never forces a violation within a finite run —
+// prefer `.within(n, unit)` when you want the verifier to fail a property
+// that stalls.
+export function eventually(predicate: () => boolean): EventuallyFormula {
+  return globalThis.__uatu__.eventually(predicate);
 }

pkg/spec-api/src/types.ts

@@ -4,6 +4,8 @@ export interface AccessibilityElement {
   id?: string;
   text?: string;
   bounds?: { left: number; top: number; right: number; bottom: number };
+  x?: number;
+  y?: number;
 }
 
 export interface AccessibilityTree {
@@ -11,9 +13,27 @@ export interface AccessibilityTree {
   findAll(selector: string): AccessibilityElement[];
 }
 
+export interface LogEntry {
+  unixMillis: number;
+  level: string;
+  tag: string;
+  message: string;
+}
+
+export interface ExceptionRecord {
+  class: string;
+  message: string;
+  stackTrace: string;
+  unixMillis?: number;
+}
+
 export interface State {
   snapshots: Snapshots;
   ax: AccessibilityTree;
+  lastAction: Action | null;
+  time: number;
+  logs: readonly LogEntry[];
+  exceptions: readonly ExceptionRecord[];
 }
 
 export interface Extracted<T> {
@@ -21,9 +41,41 @@ export interface Extracted<T> {
   readonly previous: T | undefined;
 }
 
+export interface Point {
+  x: number;
+  y: number;
+}
+
 export type TapAction = { kind: "Tap"; on: string | AccessibilityElement };
-export type InputTextAction = { kind: "InputText"; into: string | AccessibilityElement; text: string };
-export type Action = TapAction | InputTextAction;
+export type InputTextAction = {
+  kind: "InputText";
+  into: string | AccessibilityElement;
+  text: string;
+};
+export type SwipeAction = {
+  kind: "Swipe";
+  from: Point | AccessibilityElement;
+  to: Point | AccessibilityElement;
+  durationMillis?: number;
+};
+export type PressKeyAction = { kind: "PressKey"; key: Key };
+export type WaitAction = { kind: "Wait"; durationMillis: number };
+export type Action =
+  | TapAction
+  | InputTextAction
+  | SwipeAction
+  | PressKeyAction
+  | WaitAction;
+
+export type Key =
+  | "back"
+  | "home"
+  | "enter"
+  | "tab"
+  | "up"
+  | "down"
+  | "left"
+  | "right";
 
 export interface ActionGenerator {
   readonly __uatuActionGenerator: true;
@@ -32,17 +84,45 @@ export interface ActionGenerator {
 
 export interface Formula {
   readonly __uatuFormula: true;
+  implies(other: Formula): Formula;
+  or(other: Formula): Formula;
+  and(other: Formula): Formula;
+  not(): Formula;
+}
+
+export interface EventuallyFormula extends Formula {
+  within(amount: number, unit: "milliseconds" | "seconds" | "steps"): Formula;
+}
+
+export interface Sampler<T> {
+  generate(): T;
 }
 
 export interface UatuRuntime {
   extract: <T>(getter: (state: State) => T) => Extracted<T>;
-  always: (predicate: () => boolean) => Formula;
+  always: (predicateOrFormula: (() => boolean) | Formula) => Formula;
+  now: (predicate: () => boolean) => Formula;
+  next: (predicate: () => boolean) => Formula;
+  eventually: (predicate: () => boolean) => EventuallyFormula;
   actions: (generator: () => Action[]) => ActionGenerator;
   weighted: (...entries: WeightedEntry[]) => ActionGenerator;
+  from: <T>(items: readonly T[]) => Sampler<T>;
   tap: (parameters: { on: string | AccessibilityElement }) => TapAction;
-  inputText: (parameters: { into: string | AccessibilityElement; text: string }) => InputTextAction;
+  inputText: (parameters: {
+    into: string | AccessibilityElement;
+    text: string;
+  }) => InputTextAction;
+  swipe: (parameters: {
+    from: Point | AccessibilityElement;
+    to: Point | AccessibilityElement;
+    durationMillis?: number;
+  }) => SwipeAction;
+  pressKey: (parameters: { key: Key }) => PressKeyAction;
+  wait: (parameters: { durationMillis: number }) => WaitAction;
   taps: ActionGenerator;
   swipes: ActionGenerator;
+  waitOnce: ActionGenerator;
+  pressKeys: ActionGenerator;
 }
 
 export type WeightedEntry = readonly [number, ActionGenerator];