@quiesco/agent 0.0.0-stage → 0.1.0

package/src/actions/wheel.ts

@@ -0,0 +1,260 @@
+/**
+ * Real scrolling of wheel pickers (iOS UIPickerView, and UIDatePicker in wheels style) in native mode
+ * (HU 2026-11-09; findings.md "6.3 spike").
+ *
+ * The native module reports each column's touch area (found by hit testing), row height, selected row
+ * and — for a date picker — the date. A wheel is turned by a slow drag that rests before the finger
+ * lifts, so it does not fling; the result is read back once the wheel has stopped and corrected with
+ * further drags. Date pickers: which calendar unit a column turns (year, month, day, hour ...) depends
+ * on the locale, so each column is probed with a one-row drag and the date before / after compared.
+ */
+import { QuiescoError } from '../errors';
+import type { Clock } from '../sync';
+
+/** The parts of @quiesco/native's wheelInfo used here. */
+export interface WheelColumn {
+  selectedRow: number;
+  rows: number;
+  rowHeight: number;
+  title: string | null;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface WheelState {
+  found: boolean;
+  components?: WheelColumn[];
+  moving?: boolean;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  date?: number;
+  /** UIDatePicker.Mode: 0 time, 1 date, 2 date and time, 3 countdown. */
+  datePickerMode?: number;
+}
+
+export interface WheelContext {
+  read(): Promise<WheelState>;
+  /** One finger along a timed path ([point, ms]), window coordinates. */
+  gesture(path: [{ x: number; y: number }, number][]): Promise<void>;
+  clock: Clock;
+  deadline: number;
+  /** Window height, to keep long drags on screen. */
+  viewportHeight: number | null;
+  platform: string;
+}
+
+const POLL_MS = 40;
+/** Readings that must agree (wheel at rest and values unchanged) before a wheel counts as stopped. */
+const STABLE_READS = 3;
+/** The finger rests this long before lifting: no velocity, no fling. */
+const REST_MS = 250;
+const PRESS_MS = 60;
+const MAX_TRAVEL = 360;
+const MAX_ATTEMPTS = 12;
+
+function sleep(clock: Clock, ms: number): Promise<void> {
+  return new Promise((r) => {
+    clock.setTimeout(r, ms);
+  });
+}
+
+function snapshot(s: WheelState): string {
+  return JSON.stringify([s.date ?? null, (s.components ?? []).map((c) => c.selectedRow)]);
+}
+
+/** The wheel once it has stopped: not moving, and the same selection / date over a few readings. */
+export async function settle(ctx: WheelContext): Promise<WheelState> {
+  let last = '';
+  let same = 0;
+  for (;;) {
+    const s = await ctx.read();
+    if (!s.found) throw new QuiescoError('ELEMENT_NOT_FOUND', 'The wheel picker disappeared', { matcher: {} });
+    const key = snapshot(s);
+    same = s.moving !== true && key === last ? same + 1 : 0;
+    last = key;
+    if (same >= STABLE_READS - 1 || ctx.clock.now() >= ctx.deadline) return s;
+    await sleep(ctx.clock, POLL_MS);
+  }
+}
+
+function column(s: WheelState, c: number): Required<Pick<WheelColumn, 'x' | 'width'>> & WheelColumn {
+  const col = s.components?.[c];
+  if (col === undefined || col.x === undefined || col.width === undefined || col.width <= 0) {
+    throw new QuiescoError('ACTION_NOT_SUPPORTED', `wheel column ${c} takes no touches (nothing to drag)`, { action: 'setValue', platform: 'native' });
+  }
+  return col as Required<Pick<WheelColumn, 'x' | 'width'>> & WheelColumn;
+}
+
+/** Turn column `c` by `rows` (positive: towards later rows, i.e. the finger moves up). At most what fits in one drag. */
+async function turn(ctx: WheelContext, s0: WheelState, c: number, rows: number): Promise<void> {
+  // A column takes no touches while UIKit animates it (e.g. the app re-selected the row): wait.
+  let s = s0;
+  while (!(s.components?.[c]?.width !== undefined && (s.components[c]?.width ?? 0) > 0) && ctx.clock.now() < ctx.deadline) {
+    await sleep(ctx.clock, POLL_MS);
+    s = await ctx.read();
+  }
+  const col = column(s, c);
+  const top = s.y ?? 0;
+  const bottom = top + (s.height ?? 0);
+  const maxRows = Math.max(1, Math.floor(MAX_TRAVEL / col.rowHeight));
+  const n = Math.max(-maxRows, Math.min(maxRows, rows));
+  const d = Math.abs(n) * col.rowHeight;
+  const x = col.x + col.width / 2;
+  // The finger must go down on the wheel; it may leave it while moving (the scroll view keeps tracking).
+  // Turning to later rows moves the finger up: start low on the wheel, and vice versa.
+  const cy = (top + bottom) / 2;
+  const inset = Math.min(col.rowHeight, (bottom - top) / 4);
+  let from = n > 0 ? Math.min(cy + d / 2, bottom - inset) : Math.max(cy - d / 2, top + inset);
+  let to = n > 0 ? from - d : from + d;
+  // Keep the finger on screen.
+  const h = ctx.viewportHeight;
+  if (h !== null) {
+    if (to < 4) to = 4;
+    if (to > h - 4) to = h - 4;
+    from = n > 0 ? Math.min(from, to + d) : Math.max(from, to - d);
+  }
+  const moveMs = 150 + d * 3;
+  await ctx.gesture([
+    [{ x, y: from }, 0],
+    [{ x, y: from }, PRESS_MS],
+    [{ x, y: to }, PRESS_MS + moveMs],
+    [{ x, y: to }, PRESS_MS + moveMs + REST_MS],
+  ]);
+}
+
+function giveUp(what: string, platform: string): QuiescoError {
+  return new QuiescoError('ACTION_NOT_SUPPORTED', `setValue could not turn the wheel to ${what}`, {
+    action: 'setValue',
+    platform,
+    hint: 'the wheel did not land on the target after several drags; pass { mode: "js" } to set it through its callbacks',
+  });
+}
+
+/** Turn column `c` until row `target` is selected. */
+export async function selectRow(ctx: WheelContext, c: number, target: number): Promise<WheelState> {
+  let s = await settle(ctx);
+  for (let i = 0; i < MAX_ATTEMPTS; i++) {
+    const cur = s.components?.[c]?.selectedRow ?? -1;
+    if (cur === target) return s;
+    await turn(ctx, s, c, target - cur);
+    s = await settle(ctx);
+  }
+  if ((s.components?.[c]?.selectedRow ?? -1) === target) return s;
+  throw giveUp(`row ${target} (it shows row ${s.components?.[c]?.selectedRow ?? '?'})`, ctx.platform);
+}
+
+// ---- date pickers ----
+
+export type DateUnit = 'year' | 'month' | 'day' | 'date' | 'hour' | 'minute' | 'ampm';
+
+interface Fields {
+  y: number;
+  mo: number;
+  d: number;
+  h: number;
+  mi: number;
+}
+
+function fields(ms: number): Fields {
+  const t = new Date(ms);
+  return { y: t.getFullYear(), mo: t.getMonth(), d: t.getDate(), h: t.getHours(), mi: t.getMinutes() };
+}
+
+function dayNumber(f: Fields): number {
+  return Math.round(Date.UTC(f.y, f.mo, f.d) / 86400000);
+}
+
+/**
+ * The unit a column turned, from the date before and after a one-row turn. `mode` 2 (date and time)
+ * has a single date column (a list of days); `mode` 1 has separate year / month / day wheels.
+ */
+export function classifyTurn(before: number, after: number, mode: number): { unit: DateUnit; step: number } | null {
+  const a = fields(before);
+  const b = fields(after);
+  const sameDay = a.y === b.y && a.mo === b.mo && a.d === b.d;
+  const sameTime = a.h === b.h && a.mi === b.mi;
+  if (!sameDay && sameTime) {
+    if (mode === 2) return { unit: 'date', step: 1 };
+    if (a.y !== b.y && a.mo === b.mo) return { unit: 'year', step: 1 };
+    if (a.mo !== b.mo) return { unit: 'month', step: 1 };
+    return { unit: 'day', step: 1 };
+  }
+  if (sameDay && !sameTime) {
+    if (a.mi !== b.mi && a.h === b.h) {
+      const dm = Math.abs(b.mi - a.mi);
+      return { unit: 'minute', step: Math.min(dm, 60 - dm) };
+    }
+    if (Math.abs(b.h - a.h) === 12 && a.mi === b.mi) return { unit: 'ampm', step: 1 };
+    return { unit: 'hour', step: 1 };
+  }
+  return null;
+}
+
+/** Rows to turn a column of `unit` from `cur` to `target` (12-hour wheels count hours modulo 12). */
+export function rowsFor(unit: DateUnit, step: number, cur: Fields, target: Fields, twelveHour: boolean): number {
+  switch (unit) {
+    case 'year':
+      return target.y - cur.y;
+    case 'month':
+      return target.mo - cur.mo;
+    case 'day':
+      return target.d - cur.d;
+    case 'date':
+      return dayNumber(target) - dayNumber(cur);
+    case 'hour':
+      return twelveHour ? (target.h % 12) - (cur.h % 12) : target.h - cur.h;
+    case 'ampm':
+      return (target.h >= 12 ? 1 : 0) - (cur.h >= 12 ? 1 : 0);
+    case 'minute':
+      return Math.round((target.mi - cur.mi) / Math.max(1, step));
+  }
+}
+
+function matches(cur: Fields, target: Fields, mode: number): boolean {
+  const day = cur.y === target.y && cur.mo === target.mo && cur.d === target.d;
+  const time = cur.h === target.h && cur.mi === target.mi;
+  return mode === 1 ? day : mode === 0 ? time : day && time;
+}
+
+/** Turn the wheels of a UIDatePicker until it shows `target` (date part, time part or both by mode). */
+export async function selectDate(ctx: WheelContext, target: Date): Promise<WheelState> {
+  let s = await settle(ctx);
+  const mode = s.datePickerMode ?? 1;
+  if (mode === 3) throw new QuiescoError('ACTION_NOT_SUPPORTED', 'countdown timers are not supported by setValue', { action: 'setValue', platform: ctx.platform });
+  const n = s.components?.length ?? 0;
+  const twelveHour = (mode === 0 && n === 3) || (mode === 2 && n === 4);
+  const t = fields(target.getTime());
+  const units: ({ unit: DateUnit; step: number } | null)[] = [];
+  for (let pass = 0; pass < 4; pass++) {
+    for (let c = 0; c < n; c++) {
+      if (s.date === undefined) throw new QuiescoError('ACTION_NOT_SUPPORTED', 'the wheel picker reports no date', { action: 'setValue', platform: ctx.platform });
+      if (matches(fields(s.date), t, mode)) return s;
+      if (units[c] === undefined) {
+        // Probe: one row towards later rows (earlier at the end of a non-cyclic wheel).
+        const col = s.components?.[c];
+        const dir = col !== undefined && col.selectedRow >= col.rows - 1 ? -1 : 1;
+        const before = s.date;
+        await turn(ctx, s, c, dir);
+        s = await settle(ctx);
+        const k = s.date === undefined ? null : classifyTurn(before, s.date, mode);
+        units[c] = k;
+      }
+      const u = units[c];
+      if (u === null || u === undefined || s.date === undefined) continue;
+      let rows = rowsFor(u.unit, u.step, fields(s.date), t, twelveHour);
+      for (let i = 0; rows !== 0 && i < MAX_ATTEMPTS; i++) {
+        await turn(ctx, s, c, rows);
+        s = await settle(ctx);
+        if (s.date === undefined) break;
+        rows = rowsFor(u.unit, u.step, fields(s.date), t, twelveHour);
+      }
+    }
+  }
+  if (s.date !== undefined && matches(fields(s.date), t, mode)) return s;
+  const shown = s.date === undefined ? '?' : new Date(s.date).toString();
+  throw giveUp(`${target.toString()} (it shows ${shown})`, ctx.platform);
+}

package/src/api-types.ts

@@ -0,0 +1,32 @@
+/** Public app-side API (requirements.md §6.5, §6.6). Shared by index.ts and the production stub. */
+import type { JsonValue } from '@quiesco/protocol';
+
+/** A backdoor: test-only function the host can call. Arguments and result must be JSON-serializable. */
+export type Backdoor = (...args: never[]) => unknown;
+
+/** Clears one persistent store during soft reset (AsyncStorage, MMKV, SecureStore, ...). */
+export interface StorageAdapter {
+  name: string;
+  clear(): void | Promise<void>;
+}
+
+export interface QuiescoApi {
+  /** Register a backdoor under `name` (re-registering replaces it). Returns an unregister function. */
+  backdoor(name: string, fn: Backdoor): () => void;
+  /** Hook run on every soft reset, after storage is cleared and before the app remounts. */
+  onReset(hook: () => void | Promise<void>): () => void;
+  /** Extra store to clear on soft reset. AsyncStorage (native) / web storage are cleared built-in. */
+  registerStorage(adapter: StorageAdapter): () => void;
+  /**
+   * Arguments the test launched the app with (`app.device.relaunch({ args })`, config `launchArgs`), with
+   * their JSON types. `{}` when there are none, in production, and in JS-only native builds.
+   */
+  launchArgs(): Record<string, JsonValue>;
+  /**
+   * Index of the parallel test worker driving this app (0 when tests run serially; Phase 6.12). `null`
+   * until the host has connected (it connects before the first test command) and in production. For
+   * resources the app needs at startup (an API URL), pass them as launch arguments instead: the config
+   * can be a function of the worker index (`({ workerIndex }) => ({ launchArgs: { … } })`).
+   */
+  workerIndex(): number | null;
+}

package/src/api.ts

@@ -0,0 +1,11 @@
+import type { QuiescoApi } from './api-types';
+import { getRuntime } from './singleton';
+
+/** App-side API: backdoors, reset hooks and extra storage adapters. */
+export const quiesco: QuiescoApi = {
+  backdoor: (name, fn) => getRuntime().backdoors.register(name, fn),
+  onReset: (hook) => getRuntime().resets.onReset(hook),
+  registerStorage: (adapter) => getRuntime().resets.registerStorage(adapter),
+  launchArgs: () => getRuntime().launchArgs(),
+  workerIndex: () => getRuntime().workerIndex(),
+};

package/src/assertions/index.ts

@@ -0,0 +1,160 @@
+/**
+ * Assertion evaluation (requirements.md §6.4). One evaluation is a pure check of the current tree; the
+ * runtime retries it until it passes or the timeout expires.
+ *
+ * Semantics with several matches (no `index`):
+ * - visible: at least one match is visible. notVisible: no match is visible (no match at all passes).
+ * - exists: at least one match. notExists: no match. count: number of matches.
+ * - text / prop / focused / enabled / checked / value / label (and their negations): exactly one match
+ *   is required; otherwise the assertion fails (and is retried).
+ * - visible with `ratio`: at least one match shows at least that fraction of its area.
+ */
+import type { AssertionSpec, ElementSummary, JsonValue, TextMatch } from '@quiesco/protocol';
+
+import { QuiescoError } from '../errors';
+import type { HostNode, Viewport } from '../fiber-adapter';
+import { findAll, summarize, toJsonValue, toRegExp } from '../query';
+
+function isTextMatch(v: unknown): v is TextMatch {
+  return typeof v === 'string' || (typeof v === 'object' && v !== null && !Array.isArray(v) && 'regex' in v && Object.keys(v).length === 1);
+}
+
+export interface Evaluation {
+  pass: boolean;
+  expected: JsonValue;
+  actual: JsonValue;
+  elements: ElementSummary[];
+}
+
+function describeText(t: TextMatch): string {
+  return typeof t === 'string' ? t : `/${t.regex.source}/${t.regex.flags}`;
+}
+
+function textMatches(value: string, pattern: TextMatch): boolean {
+  const p = toRegExp(pattern);
+  if (typeof p === 'string') return value === p;
+  p.lastIndex = 0;
+  return p.test(value);
+}
+
+/** A prop as the user wrote it: host props first, then the owning composite (e.g. Pressable `disabled`). */
+export function readProp(node: HostNode, prop: string): unknown {
+  const own = node.props[prop];
+  return own !== undefined ? own : node.ownerProps()[prop];
+}
+
+export function jsonEqual(a: JsonValue | undefined, b: JsonValue | undefined): boolean {
+  if (a === b) return true;
+  if (a === undefined || b === undefined || a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((x, i) => jsonEqual(x, b[i]));
+  const ka = Object.keys(a);
+  const ao = a as Record<string, JsonValue>;
+  const bo = b as Record<string, JsonValue>;
+  return ka.length === Object.keys(bo).length && ka.every((k) => jsonEqual(ao[k], bo[k]));
+}
+
+function single(nodes: HostNode[]): HostNode | string {
+  if (nodes.length === 1) return nodes[0] as HostNode;
+  return nodes.length === 0 ? 'no matching element' : `${nodes.length} matching elements (add index or narrow the matcher)`;
+}
+
+export function evaluate(roots: readonly HostNode[], spec: AssertionSpec, viewport: Viewport | null): Evaluation {
+  const ev = evaluatePositive(roots, spec, viewport);
+  if (!('not' in spec) || spec.not !== true) return ev;
+  // Negated single-element assertions still need exactly one element to say anything about it.
+  const needsOne = spec.type !== 'count';
+  if (needsOne && ev.elements.length !== 1) return { ...ev, pass: false, expected: `not ${JSON.stringify(ev.expected)}` };
+  return { ...ev, pass: !ev.pass, expected: `not ${JSON.stringify(ev.expected)}` };
+}
+
+function evaluatePositive(roots: readonly HostNode[], spec: AssertionSpec, viewport: Viewport | null): Evaluation {
+  let nodes: HostNode[];
+  try {
+    nodes = findAll(roots, spec.matcher);
+  } catch (e) {
+    // `within` did not resolve to exactly one element: same as "no match" for this evaluation.
+    if (!(e instanceof QuiescoError)) throw e;
+    if (spec.type === 'notExists' || spec.type === 'notVisible') return { pass: true, expected: spec.type, actual: e.message, elements: [] };
+    return { pass: false, expected: spec.type, actual: e.message, elements: [] };
+  }
+  const elements = nodes.map((n) => summarize(n, viewport));
+
+  /** Single-element state assertions: `pick` reads the state from the element's summary. */
+  const stateOf = (expected: JsonValue, pick: (e: ElementSummary) => JsonValue | undefined, ok: (actual: JsonValue | undefined) => boolean): Evaluation => {
+    const n = single(nodes);
+    if (typeof n === 'string') return { pass: false, expected, actual: n, elements };
+    const actual = pick(elements[0] as ElementSummary);
+    return { pass: ok(actual), expected, actual: actual ?? null, elements };
+  };
+
+  switch (spec.type) {
+    case 'visible': {
+      if (spec.ratio !== undefined) {
+        const ratio = spec.ratio;
+        const best = elements.reduce((m, e) => Math.max(m, e.visibleRatio), 0);
+        const pass = elements.some((e) => e.visibleRatio >= ratio);
+        const actual = nodes.length === 0 ? 'no matching element' : `${Math.round(best * 100)}% visible`;
+        return { pass, expected: `at least ${Math.round(ratio * 100)}% visible`, actual, elements };
+      }
+      const pass = elements.some((e) => e.visible);
+      return { pass, expected: 'visible', actual: nodes.length === 0 ? 'no matching element' : pass ? 'visible' : 'not visible', elements };
+    }
+    case 'focused':
+      return stateOf('focused', (e) => (e.focused ? 'focused' : 'not focused'), (a) => a === 'focused');
+    case 'notFocused':
+      return stateOf('not focused', (e) => (e.focused ? 'focused' : 'not focused'), (a) => a === 'not focused');
+    case 'enabled':
+      return stateOf('enabled', (e) => (e.enabled ? 'enabled' : 'disabled'), (a) => a === 'enabled');
+    case 'disabled':
+      return stateOf('disabled', (e) => (e.enabled ? 'enabled' : 'disabled'), (a) => a === 'disabled');
+    case 'checked':
+      return stateOf(true, (e) => e.checked, (a) => a === true);
+    case 'notChecked':
+      return stateOf(false, (e) => e.checked, (a) => a === false);
+    case 'label':
+      return stateOf(describeText(spec.expected), (e) => e.label, (a) => typeof a === 'string' && textMatches(a, spec.expected));
+    case 'value': {
+      const expected = spec.expected;
+      if (isTextMatch(expected) && typeof expected !== 'string') {
+        return stateOf(describeText(expected), (e) => e.value, (a) => typeof a === 'string' && textMatches(a, expected));
+      }
+      return stateOf(expected as JsonValue, (e) => e.value, (a) => jsonEqual(a, expected as JsonValue));
+    }
+    case 'notVisible': {
+      if (spec.ratio !== undefined) {
+        const ratio = spec.ratio;
+        const n = elements.filter((e) => e.visibleRatio >= ratio).length;
+        return { pass: n === 0, expected: `less than ${Math.round(ratio * 100)}% visible`, actual: n === 0 ? 'not visible enough' : `${n} element(s) at least ${Math.round(ratio * 100)}% visible`, elements };
+      }
+      const n = elements.filter((e) => e.visible).length;
+      return { pass: n === 0, expected: 'not visible', actual: n === 0 ? 'not visible' : `${n} visible element(s)`, elements };
+    }
+    case 'exists':
+      return { pass: nodes.length > 0, expected: 'exists', actual: nodes.length > 0 ? `${nodes.length} element(s)` : 'no matching element', elements };
+    case 'notExists':
+      return { pass: nodes.length === 0, expected: 'does not exist', actual: nodes.length === 0 ? 'no matching element' : `${nodes.length} element(s)`, elements };
+    case 'count':
+      return { pass: nodes.length === spec.expected, expected: spec.expected, actual: nodes.length, elements };
+    case 'text': {
+      const n = single(nodes);
+      const expected = describeText(spec.expected);
+      if (typeof n === 'string') return { pass: false, expected, actual: n, elements };
+      return { pass: textMatches(n.text, spec.expected), expected, actual: n.text, elements };
+    }
+    case 'prop': {
+      const n = single(nodes);
+      if (typeof n === 'string') return { pass: false, expected: spec.expected, actual: n, elements };
+      const actual = toJsonValue(readProp(n, spec.prop));
+      return { pass: jsonEqual(actual, spec.expected), expected: spec.expected, actual: actual ?? null, elements };
+    }
+  }
+}
+
+export function assertionMessage(spec: AssertionSpec, ev: Evaluation, timeoutMs: number, matcherText: string): string {
+  const what = spec.type === 'prop' ? `prop "${spec.prop}" of ${matcherText}` : matcherText;
+  if (spec.type === 'checked' || spec.type === 'notChecked') {
+    return `expect ${spec.type} failed after ${timeoutMs}ms for ${what}: expected checked=${JSON.stringify(ev.expected)}, actual ${ev.actual === null ? 'no checked state (not a switch, checkbox or radio, and no accessibilityState.checked)' : JSON.stringify(ev.actual)}`;
+  }
+  return `expect ${spec.type} failed after ${timeoutMs}ms for ${what}: expected ${JSON.stringify(ev.expected)}, actual ${JSON.stringify(ev.actual)}`;
+}

package/src/backdoor.ts

@@ -0,0 +1,54 @@
+/** Backdoor registry (requirements.md §6.6). */
+import type { JsonValue } from '@quiesco/protocol';
+
+import type { Backdoor } from './api-types';
+import { QuiescoError } from './errors';
+import { findNonJson } from './json-check';
+
+export class BackdoorRegistry {
+  private readonly fns = new Map<string, Backdoor>();
+
+  register(name: string, fn: Backdoor): () => void {
+    if (typeof name !== 'string' || name === '') throw new TypeError('quiesco.backdoor(name, fn): name must be a non-empty string');
+    if (typeof fn !== 'function') throw new TypeError(`quiesco.backdoor('${name}', fn): fn must be a function`);
+    this.fns.set(name, fn);
+    return () => {
+      if (this.fns.get(name) === fn) this.fns.delete(name);
+    };
+  }
+
+  names(): string[] {
+    return [...this.fns.keys()].sort();
+  }
+
+  /** Run a backdoor. The caller waits for idle afterwards. */
+  async call(name: string, args: readonly JsonValue[]): Promise<JsonValue> {
+    const fn = this.fns.get(name);
+    if (fn === undefined) {
+      const registered = this.names();
+      throw new QuiescoError(
+        'BACKDOOR_NOT_REGISTERED',
+        `No backdoor named "${name}". Registered: ${registered.length > 0 ? registered.join(', ') : '(none)'}`,
+        { name, registered },
+      );
+    }
+    const badArg = findNonJson(args, '$args');
+    if (badArg !== null) {
+      throw new QuiescoError('NOT_SERIALIZABLE', `Backdoor "${name}" argument at ${badArg.path} is not JSON (${badArg.reason})`, { where: 'args', path: badArg.path });
+    }
+    let value: unknown;
+    try {
+      value = await (fn as (...a: unknown[]) => unknown)(...args);
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      const data = err.stack === undefined ? { name, message: err.message } : { name, message: err.message, stack: err.stack };
+      throw new QuiescoError('BACKDOOR_FAILED', `Backdoor "${name}" threw: ${err.message}`, data);
+    }
+    if (value === undefined) return null;
+    const bad = findNonJson(value, '$result');
+    if (bad !== null) {
+      throw new QuiescoError('NOT_SERIALIZABLE', `Backdoor "${name}" returned a value that is not JSON at ${bad.path} (${bad.reason})`, { where: 'result', path: bad.path });
+    }
+    return value as JsonValue;
+  }
+}

package/src/build-config.ts

@@ -0,0 +1,6 @@
+/**
+ * Build-time fallback connection parameters. `withQuiesco()` (metro.cjs) replaces this module with a
+ * generated one in e2e builds (docs/spikes/00-summary.md agent §6: in JS-only mode there are no
+ * launch parameters, and `EXPO_PUBLIC_*` is not inlined inside node_modules).
+ */
+export const buildConfig: { port: number | null; session: string | null } = { port: null, session: null };