simframe 0.8.0 → 0.10.0

package/src/graph.js

@@ -9,11 +9,75 @@ import path from 'node:path';
 import { hashDistance } from './analyze.js';
 import { informative } from './refs.js';
 import * as fingerprint from './fingerprint.js';
+import * as metrics from './metrics.js';
 import * as matching from './matching.js';
 import * as store from './store.js';
 
 const GRAPH_VERSION = 3;
 
+/**
+ * How many observed settle durations an edge remembers. Research §7.
+ *
+ * Fifty is a window, not a history: an app that got faster after an update
+ * should stop being waited for at its old speed, and a mean over everything
+ * ever observed never forgets.
+ */
+export const TIMING_WINDOW = 50;
+/** Below this many samples an edge has no distribution worth trusting. */
+export const COLD_SAMPLES = 5;
+/**
+ * What a cold edge waits: exactly what every step waited before Phase 11.
+ *
+ * Deliberately unchanged, so the first traversal of an edge behaves as it
+ * always did and only a *measured* edge gets a tighter bound. A conservative
+ * default that is also the historical default cannot make anything worse.
+ */
+export const COLD_TIMEOUT_MS = 8000;
+/**
+ * The hard cap on waiting, from research §7: Nielsen's attention limit. Past
+ * ten seconds a person has stopped believing the screen is coming, and so
+ * should the agent — it escalates instead.
+ */
+export const HARD_CAP_MS = 10_000;
+
+/**
+ * How long to wait for a transition that has been measured.
+ *
+ * p95 plus a margin, where the margin is the larger of 150 ms and a fifth of
+ * p95. The floor matters for fast edges: a tab switch with a p95 of 90 ms
+ * would otherwise get a 108 ms budget, and one slow frame would call a
+ * perfectly ordinary transition a timeout.
+ */
+export function adaptiveTimeout({ p95, samples } = {}) {
+  if (!Number.isFinite(p95) || !Number.isFinite(samples) || samples < COLD_SAMPLES) {
+    return { timeoutMs: COLD_TIMEOUT_MS, cold: true, reason: `fewer than ${COLD_SAMPLES} samples` };
+  }
+  const margin = Math.max(150, Math.round(p95 * 0.2));
+  return { timeoutMs: Math.min(HARD_CAP_MS, p95 + margin), cold: false, reason: null, margin };
+}
+
+/**
+ * Is this transition taking longer than this edge usually does?
+ *
+ * Two different answers hide behind a slow transition, and §7 asks for both:
+ * a screen that is *working* (a spinner, a load) should be waited for up to
+ * the hard cap, while a screen that is doing nothing visible has already
+ * given its answer. The classifier's `loading` kind is what separates them.
+ */
+export function slowerThanUsual({ elapsedMs, p95, settled, kind } = {}) {
+  if (settled || !Number.isFinite(elapsedMs) || !Number.isFinite(p95)) return { slower: false };
+  if (elapsedMs <= p95) return { slower: false };
+  const working = kind === 'loading';
+  return {
+    slower: true,
+    working,
+    keepWaiting: working && elapsedMs < HARD_CAP_MS,
+    note: working
+      ? `slower than usual (${elapsedMs}ms against a p95 of ${p95}ms) and still loading`
+      : `slower than usual (${elapsedMs}ms against a p95 of ${p95}ms) with nothing visibly happening`,
+  };
+}
+
 /**
  * Which fingerprint produced the hashes in these files.
  *
@@ -276,7 +340,193 @@ export function findScreen(udid, query) {
 }
 
 /** Remember that doing `action` on `from` led to `to`. */
-export function record(udid, { from, action, to, kind }) {
+/**
+ * Add one observed settle duration to an edge's rolling window.
+ *
+ * Kept on the edge rather than in a separate store because it is a property of
+ * this transition on this screen — the same tap costs 90 ms on a tab bar and
+ * 2.4 s on a screen that fetches — and because the graph is already persisted,
+ * versioned and pruned.
+ */
+function noteSettle(edge, settleMs, quietGapMs, focusMs) {
+  if (Number.isFinite(settleMs) && settleMs >= 0) {
+    edge.settles = [...(edge.settles ?? []), Math.round(settleMs)].slice(-TIMING_WINDOW);
+  }
+  // Recorded even when zero: "this transition never paused" is exactly the
+  // observation that lets the next one stop waiting 500ms to find out.
+  if (Number.isFinite(quietGapMs) && quietGapMs >= 0) {
+    edge.quietGaps = [...(edge.quietGaps ?? []), Math.round(quietGapMs)].slice(-TIMING_WINDOW);
+  }
+  // How long the *field* took to take focus, which is a different duration from
+  // how long the step took: it is measured between the tap and the keyboard,
+  // inside a step whose settle is measured after the typing. One edge, two
+  // waits, so two distributions.
+  if (Number.isFinite(focusMs) && focusMs >= 0) {
+    edge.focuses = [...(edge.focuses ?? []), Math.round(focusMs)].slice(-TIMING_WINDOW);
+  }
+}
+
+/**
+ * Record the unbiased pause statistic for an edge already written.
+ *
+ * Separate from `record` because it arrives later on purpose. The biased
+ * `quietGaps` are gathered from inside the wait and are therefore bounded by
+ * when the wait chose to stop; `trueGaps` are read off the frame history once
+ * the transition is definitely over, which is one step later. So the edge has
+ * to be found again rather than passed along.
+ *
+ * Nothing reads `trueGaps` yet, and that is deliberate. Phase 11 built the
+ * learned stillness window on the biased statistic, it corrupted the graph
+ * inside an afternoon, and the lesson taken was not "use a better estimator" —
+ * it was that a number gets to *act* only after it has been watched for a while
+ * doing nothing. This is the watching.
+ */
+export function noteTrueGap(udid, screen, step, trueGapMs) {
+  if (!Number.isFinite(trueGapMs) || trueGapMs < 0) return null;
+  const node = screen?.hash ? nearestScreen(udid, screen)?.node : null;
+  if (!node) return null;
+  const edge = node.edges?.find((e) => e.action === actionSignature(step));
+  if (!edge) return null;
+  edge.trueGaps = [...(edge.trueGaps ?? []), Math.round(trueGapMs)].slice(-TIMING_WINDOW);
+  save(udid, node);
+  return edge;
+}
+
+/**
+ * How long a screen must hold still on this edge before it is finished.
+ *
+ * Derived from the longest pause ever seen *inside* this transition, plus a
+ * margin, and never longer than the caller's own default — this can only make
+ * a wait shorter, never longer, which is what keeps a learned number from
+ * becoming a new way to hang.
+ *
+ * The floor is 150 ms because a settle also needs at least one fresh frame to
+ * judge, and the capture loop's own idle interval is the limit on how fast an
+ * answer can arrive.
+ */
+export const STILLNESS_FLOOR_MS = 150;
+
+export function stillnessFor({ gapSamples, gapP95 } = {}, fallbackMs) {
+  if (!Number.isFinite(gapP95) || !Number.isFinite(gapSamples) || gapSamples < COLD_SAMPLES) {
+    return { stillnessMs: fallbackMs, cold: true };
+  }
+  const margin = Math.max(100, Math.round(gapP95 * 0.5));
+  return {
+    stillnessMs: Math.max(STILLNESS_FLOOR_MS, Math.min(fallbackMs, gapP95 + margin)),
+    cold: false,
+  };
+}
+
+/**
+ * How long to wait for a tapped field to take focus.
+ *
+ * The three numbers this replaces were the last genuinely fixed waits on the
+ * action path: 250 ms of stillness, a 900 ms reaction window, a 3 s timeout.
+ * What makes them different from the step budget is the shape of the failure.
+ * A step budget that is too short reports `no-visible-change` and the flow can
+ * see it. A focus wait that is too short types into a field that does not have
+ * focus yet, `typeText` succeeds because input has no feedback channel, and the
+ * step reports that it typed — the worst shape a failure can take, and the bug
+ * this helper was written to fix in the first place.
+ *
+ * So this one is asymmetric on purpose: **a learned window may only lengthen
+ * the wait**, never shorten it. p95 of what this field has actually cost, when
+ * that is longer than 3 s, is a field that was being typed into too early and
+ * now is not. Where it is shorter, the measurement is discarded rather than
+ * banked as a saving — 5% of a distribution is one silent wrong type in twenty
+ * runs, and there is no amount of median wall time worth that.
+ *
+ * The one shortening is not a learned number at all, it is positive evidence:
+ * if the keyboard was already up before the tap, this tap moves a caret. There
+ * is no keyboard animation to wait for, so the reaction window collapses to the
+ * stillness window instead of paying 900 ms to watch a screen that was never
+ * going to move. `beforeScreen` already carries `keyboard`, so the evidence is
+ * free — it is the same perception pass the step was going to run anyway.
+ */
+export function focusPlan(stats, { reactionMs, timeoutMs, stillnessMs, keyboardUp } = {}) {
+  if (keyboardUp) {
+    return {
+      reactionMs: stillnessMs ?? reactionMs,
+      timeoutMs,
+      cold: false,
+      from: 'the keyboard was already up, so this tap moves a caret',
+    };
+  }
+  const { focusP50, focusP95, focusSamples } = stats ?? {};
+  if (!Number.isFinite(focusP95) || !Number.isFinite(focusSamples) || focusSamples < COLD_SAMPLES) {
+    return { reactionMs, timeoutMs, cold: true, from: `fewer than ${COLD_SAMPLES} focus samples` };
+  }
+  const margin = Math.max(150, Math.round(focusP95 * 0.2));
+  const learnedTimeout = Math.min(HARD_CAP_MS, focusP95 + margin);
+  const learnedReaction = Math.min(learnedTimeout, focusP50 + margin);
+  return {
+    // max, not min. See above: only ever longer.
+    reactionMs: Math.max(reactionMs, learnedReaction),
+    timeoutMs: Math.max(timeoutMs, learnedTimeout),
+    cold: false,
+    from: `p95 ${focusP95}ms over ${focusSamples} focus samples`,
+  };
+}
+
+/** What this edge's observed settle durations say, or that it has none. */
+export function timingOf(edge) {
+  const samples = edge?.settles ?? [];
+  const gaps = edge?.quietGaps ?? [];
+  const focuses = edge?.focuses ?? [];
+  return {
+    samples: samples.length,
+    p50: metrics.percentile(samples, 50),
+    p95: metrics.percentile(samples, 95),
+    gapSamples: gaps.length,
+    gapP95: metrics.percentile(gaps, 95),
+    // The same statistic measured after the transition rather than during it.
+    // Reported side by side so the size of the bias is visible rather than
+    // argued about — see `index.longestQuietGap`.
+    trueGapSamples: (edge?.trueGaps ?? []).length,
+    trueGapP95: metrics.percentile(edge?.trueGaps ?? [], 95),
+    focusSamples: focuses.length,
+    focusP50: metrics.percentile(focuses, 50),
+    focusP95: metrics.percentile(focuses, 95),
+  };
+}
+
+/**
+ * How long to wait for `step` on `screen`, from what it has cost before.
+ *
+ * Returns the cold default when this screen or this action has not been
+ * measured, and says which — a timeout nobody can explain is how a fixed sleep
+ * gets reintroduced as a constant with a comment.
+ */
+export function timingFor(udid, screen, step) {
+  const node = screen?.hash ? nearestScreen(udid, screen)?.node : null;
+  const edge = node?.edges?.find((e) => e.action === actionSignature(step));
+  const stats = timingOf(edge);
+  return { ...stats, ...adaptiveTimeout(stats), known: Boolean(edge) };
+}
+
+/**
+ * What getting *to* this screen has cost before.
+ *
+ * `sim_state` is asked "what is on screen and is it done moving", with no
+ * action in hand, so there is no outgoing edge to consult. The useful answer
+ * is the inbound one: the edge most recently traversed into this screen is how
+ * we got here, and its distribution is what "slower than usual" means right
+ * now. Most recently seen rather than most travelled — a screen reachable two
+ * ways is being timed against the way it was just reached.
+ */
+export function timingInto(udid, hash) {
+  if (!hash) return null;
+  let best = null;
+  for (const node of allNodes(udid)) {
+    for (const edge of node.edges ?? []) {
+      if (edge.to !== hash) continue;
+      if (!best || (edge.lastSeen ?? 0) > (best.lastSeen ?? 0)) best = edge;
+    }
+  }
+  return best ? { ...timingOf(best), action: best.action, kind: best.kind ?? null } : null;
+}
+
+export function record(udid, { from, action, to, kind, settleMs, quietGapMs, focusMs }) {
   const fromKey = typeof from === 'string' ? { hash: from } : from;
   const toHash = typeof to === 'string' ? to : to?.hash;
   if (!fromKey?.hash || !toHash) return null;
@@ -343,6 +593,7 @@ export function record(udid, { from, action, to, kind }) {
         save(udid, target);
         existing.count += 1;
         existing.lastSeen = Date.now();
+        noteSettle(existing, settleMs, quietGapMs, focusMs);
         save(udid, node);
         return node;
       }
@@ -354,6 +605,13 @@ export function record(udid, { from, action, to, kind }) {
     existing.kind = kind ?? existing.kind;
     existing.count += 1;
     existing.lastSeen = Date.now();
+    // Every argument, and it is worth saying why this line once passed one.
+    // `quietGapMs` was dropped here — on the *main* path, the one nearly every
+    // recorded edge takes — so the pause statistic only ever accumulated on a
+    // brand-new edge and on the variant branch. The window that reads it looked
+    // permanently cold, which is a measurement quietly not being taken rather
+    // than a wrong number, and those are the ones nothing complains about.
+    noteSettle(existing, settleMs, quietGapMs, focusMs);
   } else {
     node.edges.push({
       action: signature,
@@ -364,6 +622,9 @@ export function record(udid, { from, action, to, kind }) {
       kind,
       count: 1,
       lastSeen: Date.now(),
+      settles: Number.isFinite(settleMs) && settleMs >= 0 ? [Math.round(settleMs)] : [],
+      quietGaps: Number.isFinite(quietGapMs) && quietGapMs >= 0 ? [Math.round(quietGapMs)] : [],
+      focuses: Number.isFinite(focusMs) && focusMs >= 0 ? [Math.round(focusMs)] : [],
     });
   }
   save(udid, node);