simframe 0.9.0 → 0.11.0

package/src/graph.js

@@ -295,6 +295,38 @@ function replayable(step) {
   return step.launch != null || step.openUrl != null ? null : step;
 }
 
+/**
+ * What has worked from this screen before, in the caller's own vocabulary.
+ *
+ * The graph has always known this and never said it. A map reported
+ * `(known, 3 known exits)` — the *count* — so an agent on a screen simframe had
+ * driven successfully six times still had to read it to learn what was tappable.
+ * Measured across two peer rounds: a flow whose steps were known in advance ran
+ * 16 steps in **one** call, and the same agent on a screen the graph also knew
+ * but whose labels it did not spent 25 calls on 31 steps. The difference was not
+ * perception. It was whether a plan existed before execution started.
+ *
+ * Ordered by how often each has worked, because that is the order an agent
+ * should try them in.
+ */
+export function exitsOf(node, { limit = 8 } = {}) {
+  return (node?.edges ?? [])
+    .map((e) => ({
+      action: e.step?.action ?? (e.action ?? '').split(':')[0] ?? 'tap',
+      label: e.step?.value ?? e.step?.target ?? e.step?.label ?? e.step?.into ?? null,
+      to: e.to ?? null,
+      count: e.count ?? 0,
+      kind: e.kind ?? null,
+    }))
+    // A `#13` was a ref on the screen it was typed on and means nothing on the
+    // next visit; a raw coordinate is not a name either. Neither is reusable
+    // vocabulary, which is the whole point of this list.
+    .filter((e) => e.label != null && !/^#\d+$/.test(String(e.label).trim())
+      && !/^@?-?\d+\s*,\s*-?\d+$/.test(String(e.label).trim()))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, limit);
+}
+
 /**
  * What to call this screen, for a human typing `goto`.
  *
@@ -348,7 +380,7 @@ export function findScreen(udid, query) {
  * 2.4 s on a screen that fetches — and because the graph is already persisted,
  * versioned and pruned.
  */
-function noteSettle(edge, settleMs, quietGapMs) {
+function noteSettle(edge, settleMs, quietGapMs, focusMs) {
   if (Number.isFinite(settleMs) && settleMs >= 0) {
     edge.settles = [...(edge.settles ?? []), Math.round(settleMs)].slice(-TIMING_WINDOW);
   }
@@ -357,6 +389,39 @@ function noteSettle(edge, settleMs, quietGapMs) {
   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;
 }
 
 /**
@@ -384,16 +449,76 @@ export function stillnessFor({ gapSamples, gapP95 } = {}, fallbackMs) {
   };
 }
 
+/**
+ * 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),
   };
 }
 
@@ -433,7 +558,7 @@ export function timingInto(udid, hash) {
   return best ? { ...timingOf(best), action: best.action, kind: best.kind ?? null } : null;
 }
 
-export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
+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;
@@ -500,7 +625,7 @@ export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
         save(udid, target);
         existing.count += 1;
         existing.lastSeen = Date.now();
-        noteSettle(existing, settleMs, quietGapMs);
+        noteSettle(existing, settleMs, quietGapMs, focusMs);
         save(udid, node);
         return node;
       }
@@ -512,7 +637,13 @@ export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
     existing.kind = kind ?? existing.kind;
     existing.count += 1;
     existing.lastSeen = Date.now();
-    noteSettle(existing, settleMs);
+    // 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,
@@ -525,6 +656,7 @@ export function record(udid, { from, action, to, kind, settleMs, quietGapMs }) {
       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);
@@ -656,12 +788,36 @@ export const VERDICTS = ['ok', 'no-visible-change', 'unexpected-screen', 'unveri
  * app and the verdict still said `unexpected-screen`, because the verdict never
  * asked the graph.
  */
+/**
+ * Are these two readings the same screen?
+ *
+ * `nearestScreen` has always had a token-similarity tolerance, precisely so
+ * that a screen whose *content* differs — a list with different rows, a form
+ * showing a different record — still resolves to the screen it is. The
+ * verification path threw that away: it passed bare hash strings, and a string
+ * carries no tokens, so only an exact hash could ever match.
+ *
+ * The cost was measured. `unexpected-screen` fired three times in one reported
+ * run and was wrong all three; two were this — the tester picked a different
+ * asset than earlier runs had, so the content differed, so the hash differed,
+ * so a correct navigation was called a wrong turn. Their conclusion: *"this
+ * will fire on every run that varies its test data — i.e. every useful run."*
+ * And because a failed step abandons the rest of its batch, each false alarm
+ * costs a round trip, which is the thing the whole design is trying to buy.
+ *
+ * So pass the reading, not just its name: `{hash, tokens}` lets the tolerance
+ * that already exists do its job. A string still works and still means "exact
+ * match only", which is right for a stored prediction that has no tokens.
+ */
 function sameScreen(udid, a, b) {
-  if (!a || !b) return false;
-  if (a === b) return true;
+  const hashOf = (v) => (typeof v === 'string' ? v : v?.hash);
+  const ha = hashOf(a);
+  const hb = hashOf(b);
+  if (!ha || !hb) return false;
+  if (ha === hb) return true;
   if (!udid) return false;
-  const nodeA = nearestScreen(udid, a)?.node;
-  const nodeB = nearestScreen(udid, b)?.node;
+  const nodeA = nearestScreen(udid, typeof a === 'string' ? a : { hash: ha, tokens: a?.tokens })?.node;
+  const nodeB = nearestScreen(udid, typeof b === 'string' ? b : { hash: hb, tokens: b?.tokens })?.node;
   return Boolean(nodeA && nodeB && nodeA.hash === nodeB.hash);
 }
 
@@ -677,9 +833,35 @@ function sameScreen(udid, a, b) {
  */
 export const CONFIDENT_OBSERVATIONS = 2;
 
-export function verdict({ udid, prediction, before, after, kind }) {
-  if (!before || !after) return { verdict: 'unverified', detail: 'no state to compare' };
-  const moved = before !== after;
+/**
+ * Actions whose correct outcome is that the screen stays where it is.
+ *
+ * Typing into a field does not navigate, so screen-identity movement cannot
+ * say whether it worked — and answering with `no-visible-change` was actively
+ * harmful three ways. It printed a verdict contradicting the wait's own
+ * observation on the same line (`[a small change, in one region only] …
+ * [no-visible-change]`, both true, of different questions). It is an escalating
+ * verdict, so a clean flow that typed anything told the caller to stop and
+ * think. And it invited a re-type, which doubles a field that cannot be
+ * cleared.
+ *
+ * These steps are verified by reading the field back instead — see
+ * `fieldContents` in actions.js.
+ */
+export const STAYS_ON_SCREEN = new Set(['type', 'paste', 'key']);
+
+export function verdict({ udid, prediction, before, after, kind, action }) {
+  // `before`/`after` may be a hash or a whole reading. A reading carries its
+  // tokens, which is what lets a content-varied screen still be recognised as
+  // the screen it is.
+  const hashOf = (v) => (typeof v === 'string' ? v : v?.hash);
+  const beforeHash = hashOf(before);
+  const afterHash = hashOf(after);
+  if (!beforeHash || !afterHash) return { verdict: 'unverified', detail: 'no state to compare' };
+  const moved = beforeHash !== afterHash;
+  if (STAYS_ON_SCREEN.has(action) && !moved) {
+    return { verdict: 'ok', detail: 'the screen was not expected to change, and did not' };
+  }
   if (!prediction) {
     if (!moved) return { verdict: 'no-visible-change', detail: 'the screen did not change, and nothing predicted it would' };
     return { verdict: 'unverified', detail: 'this action has not been seen on this screen before' };