test: stop pinning settle capture counts against a wall-clock loop (#1307)

* test: model the UI in settle-observation fixtures instead of a capture count

settle-observation's "contention flakes" were a zero-margin comparison
meeting a 1ms clock skew, not generic load.

runStableCaptureLoop derives pollMs = min(300, max(25, quietMs)), so the
test's settleQuietMs: 25 made pollMs === quietMs, and the settle check
(one sleep(25) plus capture time, against >= 25) a 0ms margin. Node's
setTimeout(25) advances Date.now() by only 24ms in 0.13% of calls idle
and 0.63% under load, because libuv's timers and Date.now() read
different clocks. On a 24 the loop takes a third capture that the
transcript never scripted, and settle's best-effort catch reports the
resulting throw as settled: false.

The fixtures now model the surface rather than the runner's speed: a
quiet UI serves the settled tree to every capture, a busy one a fresh
tree per capture, via new transcript `repeat` entries and result
factories. The snapshot-floor economy guard survives as a bound (2-3
captures), and the follow-up's "no fresh capture" cost — previously
implied by the exact transcript — is now asserted directly.

Production is untouched: the same zero margin only costs a wasted extra
capture and poll there, filed separately as #1306.

* test: stop pinning the settle capture count in the iOS contract scenario too

A sweep for the same bug class found direct-ios-selector's settleObservation
scenario carrying the identical 0ms margin: settleQuietMs: 25 (so pollMs ===
quietMs) against a consume-once transcript scripting exactly two settle
captures, with no injected clock. It has not lost the coin flip in CI yet,
but it fails the same way when it does — a third capture finds no entry and
settle's best-effort catch reports settled: false.

Same fix: the fixture models a quiet UI (every settle capture sees the same
tree) instead of scripting how many captures fit in a wall-clock window.

The rest of the sweep was clean. The other contract scenarios and the
interaction runtime tests already use clamped mocks that repeat the last
snapshot, so any capture count is tolerated; the fake-clock tests are correct
to pin exact counts.

* style: oxfmt quietRunnerSnapshotEntry signature

* test: make one-shot-outranks-repeat a real transcript rule (P2 review)

The review is right: `one-shot entries still outrank a repeat entry` asserted
a guarantee the lookup did not provide. It passed only because the one-shot
happened to be declared first — unordered lookup took the first match, so a
repeat declared ahead of a matching one-shot shadowed it forever and left it
permanently unconsumed. Both failure modes reproduce; the reverse-order test
added here fails on the previous implementation.

Unordered lookup now searches matching one-shots before repeats, so
outranking holds whatever the declaration order. A repeat is documented as
its command's fallback.

Ordered transcripts now reject repeats at construction: ordered lookup only
ever reads the head, so a repeat there never advances and strands every entry
behind it. Refusing the combination beats failing later as a confusing
"Provider command mismatch".

Coverage added for both: reverse declaration order, and ordered + repeat.

Author: thymikee

test/integration/interaction-contract/daemon-harness.ts

@@ -69,6 +69,13 @@ export function runnerSnapshotEntry(nodes: readonly unknown[]): ProviderScenario
   };
 }
 
+// A UI that has gone quiet: every settle capture sees the same tree. How many
+// captures the loop spends reaching that verdict is wall-clock, so the count is
+// not the contract and is never scripted.
+export function quietRunnerSnapshotEntry(nodes: readonly unknown[]): ProviderScenarioProviderEntry {
+  return { ...runnerSnapshotEntry(nodes), repeat: true };
+}
+
 export function runnerTapEntry(
   result: Record<string, unknown>,
   request?: Record<string, unknown>,

test/integration/interaction-contract/direct-ios-selector.contract.test.ts

@@ -13,6 +13,7 @@ import {
   RUNNER_NON_HITTABLE_NODES,
 } from './fixtures.ts';
 import {
+  quietRunnerSnapshotEntry,
   runnerSnapshotEntry,
   runnerTapEntry,
   runnerTapErrorEntry,
@@ -188,11 +189,10 @@ test(scenario('settleObservation'), async () => {
   await withIosContractDaemon(
     [
       // --settle disables the direct path: runtime tree capture, coordinate
-      // tap, then the settle loop's two stable captures of the changed tree.
+      // tap, then the settle loop captures the changed tree until it goes quiet.
       runnerSnapshotEntry(RUNNER_CONTINUE_NODES),
       runnerTapEntry({ x: 200, y: 322 }),
-      runnerSnapshotEntry(RUNNER_CHANGED_NODES),
-      runnerSnapshotEntry(RUNNER_CHANGED_NODES),
+      quietRunnerSnapshotEntry(RUNNER_CHANGED_NODES),
     ],
     async (daemon, transcript) => {
       const click = await daemon.callCommand('click', ['label=Continue'], {

test/integration/provider-scenarios/settle-observation.test.ts

@@ -130,6 +130,30 @@ function snapshotEntry(nodes: readonly unknown[]): ProviderScenarioProviderEntry
   };
 }
 
+// A UI that has gone quiet: every settle capture sees the same tree. How many
+// captures the loop spends reaching that verdict is wall-clock — it polls on a
+// 25ms floor and settles once two identical captures span the quiet window — so
+// the count is not the contract and is never scripted here.
+function quietSnapshotEntry(nodes: readonly unknown[]): ProviderScenarioProviderEntry {
+  return { ...snapshotEntry(nodes), repeat: true };
+}
+
+// A UI that never goes quiet: every capture returns a fresh tree, so the loop
+// can never settle no matter how many captures fit in the budget.
+function changingSnapshotEntry(nodes: (label: string) => unknown[]): ProviderScenarioProviderEntry {
+  let capture = 0;
+  return {
+    command: 'ios.runner.snapshot',
+    deviceId: DEVICE_ID,
+    platform: 'apple',
+    repeat: true,
+    result: () => {
+      capture += 1;
+      return { nodes: nodes(`Loading ${capture}`), truncated: false };
+    },
+  };
+}
+
 function typeEntry(x: number, y: number): ProviderScenarioProviderEntry {
   return {
     command: 'ios.runner.type',
@@ -155,8 +179,7 @@ test('Provider-backed integration press --settle returns the settled diff and fr
     // press label=Continue --settle: resolution capture, tap, settle captures
     snapshotEntry(BEFORE_NODES),
     tapEntry(200, 322),
-    snapshotEntry(SETTLED_NODES),
-    snapshotEntry(SETTLED_NODES),
+    quietSnapshotEntry(SETTLED_NODES),
     // press @e2 (the Done ref from the settled diff): tap on the stored tree
     tapEntry(200, 522),
   ]);
@@ -212,7 +235,14 @@ test('Provider-backed integration press --settle returns the settled diff and fr
       };
       assert.ok(settle, 'press --settle must return a settle observation');
       assert.equal(settle.settled, true);
-      assert.equal(settle.captures, 2);
+      // Snapshot-floor economy: a quiet UI settles on the two identical
+      // captures the verdict needs, or three when the second lands a hair short
+      // of the quiet window. Anything above that is a regression in what settle
+      // spends; pinning a single number would assert the runner's speed.
+      assert.ok(
+        settle.captures >= 2 && settle.captures <= 3,
+        `settle should cost 2-3 captures, got ${settle.captures}`,
+      );
       assert.equal(typeof settle.refsGeneration, 'number');
       assert.deepEqual(settle.diff?.summary, { additions: 1, removals: 2, unchanged: 1 });
       const added = settle.diff?.lines.find((line) => line.kind === 'added');
@@ -229,11 +259,19 @@ test('Provider-backed integration press --settle returns the settled diff and fr
       // directly on the stored settled tree with no fresh snapshot round trip
       // and no stale-refs warning. The plain `@e2` would require a complete
       // frame.
+      const callsBeforeFollowUp = runnerTranscript.calls.length;
       const followUp = await daemon.callCommand('press', [`@e2~s${settle.refsGeneration}`], {});
       const followUpData = assertRpcOk(followUp);
       assert.equal(followUpData.warning, undefined);
       assert.equal(followUpData.x, 200);
       assert.equal(followUpData.y, 522);
+      // The round trip settle exists to remove: the follow-up spends a tap and
+      // nothing else. Asserted directly, since a quiet-UI entry would happily
+      // serve a stray capture.
+      assert.deepEqual(
+        runnerTranscript.calls.slice(callsBeforeFollowUp).map((call) => call.command),
+        ['ios.runner.tap'],
+      );
 
       runnerTranscript.assertComplete();
     },
@@ -258,13 +296,11 @@ test('Provider-backed integration never-settled press --settle does not issue di
     },
   ];
   const runnerTranscript = createProviderTranscript([
-    // press label=Continue --settle: resolution capture, tap, then a changing
-    // settle stream. The loop times out; the final capture is not actionable.
+    // press label=Continue --settle: resolution capture, tap, then a settle
+    // stream that never repeats itself, so the loop can only ever time out.
     snapshotEntry(BEFORE_NODES),
     tapEntry(200, 322),
-    snapshotEntry(loadingNodes('Loading 1')),
-    snapshotEntry(loadingNodes('Loading 2')),
-    snapshotEntry(SETTLED_NODES),
+    changingSnapshotEntry(loadingNodes),
   ]);
   const appleRunnerProvider = createAppleRunnerProviderFromTranscript(
     runnerTranscript,
@@ -293,7 +329,10 @@ test('Provider-backed integration never-settled press --settle does not issue di
       const press = await daemon.callCommand('press', ['label=Continue'], {
         settle: true,
         settleQuietMs: 25,
-        timeoutMs: 60,
+        // Budget the loop spends without settling. Wide enough that a loaded
+        // runner's capture cannot outlast it — a capture that overruns the
+        // budget reports the stalled hint instead of this one.
+        timeoutMs: 300,
       });
       const pressData = assertRpcOk(press);
       const settle = pressData.settle as {
@@ -324,8 +363,7 @@ test('Provider-backed integration modal-dismiss press --settle attaches the unch
     // no added refs, so the tail is the only actionable-target payload.
     snapshotEntry(MODAL_BEFORE_NODES),
     tapEntry(200, 422),
-    snapshotEntry(MODAL_DISMISSED_NODES),
-    snapshotEntry(MODAL_DISMISSED_NODES),
+    quietSnapshotEntry(MODAL_DISMISSED_NODES),
     // press @e3 (the Continue ref from the tail): tap on the stored tree.
     tapEntry(200, 322),
   ]);
@@ -392,11 +430,16 @@ test('Provider-backed integration modal-dismiss press --settle attaches the unch
       // The tail's ref acts directly on the stored settled tree, same as an
       // added-line ref would — consumed in pinned form from the partial frame
       // (ADR 0014).
+      const callsBeforeFollowUp = runnerTranscript.calls.length;
       const followUp = await daemon.callCommand('press', [`@e3~s${settle.refsGeneration}`], {});
       const followUpData = assertRpcOk(followUp);
       assert.equal(followUpData.warning, undefined);
       assert.equal(followUpData.x, 200);
       assert.equal(followUpData.y, 322);
+      assert.deepEqual(
+        runnerTranscript.calls.slice(callsBeforeFollowUp).map((call) => call.command),
+        ['ios.runner.tap'],
+      );
 
       runnerTranscript.assertComplete();
     },
@@ -651,8 +694,7 @@ test('Provider-backed integration fill --settle summoning the keyboard still att
     // fresh capture), the runner types, then the settle loop captures. The
     // keyboard window appears and the field re-labels itself.
     typeEntry(201, 149),
-    snapshotEntry(FILL_SETTLED_NODES),
-    snapshotEntry(FILL_SETTLED_NODES),
+    quietSnapshotEntry(FILL_SETTLED_NODES),
     // press @e17 (the "Discard and go back" ref from the tail): tap on the
     // stored settled tree.
     tapEntry(201, 202),
@@ -724,11 +766,16 @@ test('Provider-backed integration fill --settle summoning the keyboard still att
       assert.equal(settle.tailTruncated, undefined);
       assert.equal(typeof settle.refsGeneration, 'number');
 
+      const callsBeforeFollowUp = runnerTranscript.calls.length;
       const followUp = await daemon.callCommand('press', [`@e17~s${settle.refsGeneration}`], {});
       const followUpData = assertRpcOk(followUp);
       assert.equal(followUpData.warning, undefined);
       assert.equal(followUpData.x, 201);
       assert.equal(followUpData.y, 202);
+      assert.deepEqual(
+        runnerTranscript.calls.slice(callsBeforeFollowUp).map((call) => call.command),
+        ['ios.runner.tap'],
+      );
 
       runnerTranscript.assertComplete();
     },

test/integration/provider-scenarios/transcript.test.ts

@@ -15,6 +15,93 @@ test('provider transcript matches expected calls without requiring incidental or
   transcript.assertComplete();
 });
 
+test('repeat entries serve every matching call and never count as unconsumed', () => {
+  const transcript = createProviderTranscript([
+    { command: 'ios.runner.snapshot', repeat: true, result: { ok: 'snapshot' } },
+    { command: 'ios.runner.tap', result: { ok: 'tap' } },
+  ]);
+
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'snapshot' });
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'snapshot' });
+  assert.deepEqual(transcript.next('ios.runner.tap'), { ok: 'tap' });
+
+  // The repeat entry stays pending forever; only the one-shot tap had to land.
+  transcript.assertComplete();
+  assert.equal(transcript.calls.length, 3);
+});
+
+test('one-shot entries still outrank a repeat entry and remain required', () => {
+  const transcript = createProviderTranscript([
+    { command: 'ios.runner.snapshot', result: { ok: 'first' } },
+    { command: 'ios.runner.snapshot', repeat: true, result: { ok: 'rest' } },
+  ]);
+
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'first' });
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'rest' });
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'rest' });
+  transcript.assertComplete();
+});
+
+test('a repeat declared before a matching one-shot does not shadow it', () => {
+  // Outranking is a rule, not an accident of declaration order: taking the
+  // first match would serve the repeat forever and strand the one-shot.
+  const transcript = createProviderTranscript([
+    { command: 'ios.runner.snapshot', repeat: true, result: { ok: 'rest' } },
+    { command: 'ios.runner.snapshot', result: { ok: 'first' } },
+  ]);
+
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'first' });
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'rest' });
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { ok: 'rest' });
+  transcript.assertComplete();
+});
+
+test('ordered transcripts reject repeat entries outright', () => {
+  // Ordered lookup only ever reads entry 0, so a repeat there never advances
+  // and makes every later entry unreachable. Refuse the combination instead of
+  // failing later as a confusing command mismatch.
+  assert.throws(
+    () =>
+      createOrderedProviderTranscript([
+        { command: 'ios.runner.snapshot', repeat: true, result: { ok: 'snapshot' } },
+        { command: 'ios.runner.tap', result: { ok: 'tap' } },
+      ]),
+    /repeat/i,
+  );
+});
+
+test('unconsumed one-shot entries still fail assertComplete alongside a repeat entry', () => {
+  const transcript = createProviderTranscript([
+    { command: 'ios.runner.snapshot', repeat: true, result: { ok: 'snapshot' } },
+    { command: 'ios.runner.tap', result: { ok: 'tap' } },
+  ]);
+
+  transcript.next('ios.runner.snapshot');
+  assert.throws(() => transcript.assertComplete(), /Unconsumed provider transcript entries.*tap/s);
+});
+
+test('a result factory is invoked per call, so repeated calls can return fresh results', () => {
+  let capture = 0;
+  const transcript = createProviderTranscript([
+    {
+      command: 'ios.runner.snapshot',
+      repeat: true,
+      result: () => {
+        capture += 1;
+        return { label: `Loading ${capture}` };
+      },
+    },
+  ]);
+
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { label: 'Loading 1' });
+  assert.deepEqual(transcript.next('ios.runner.snapshot'), { label: 'Loading 2' });
+  // The recorded call carries the resolved result, not the factory.
+  assert.deepEqual(
+    transcript.calls.map((call) => call.result),
+    [{ label: 'Loading 1' }, { label: 'Loading 2' }],
+  );
+});
+
 test('ordered provider transcript remains available when ordering is the contract', () => {
   const transcript = createOrderedProviderTranscript([
     { command: 'ios.runner.snapshot', result: { ok: 'snapshot' } },