@reticlehq/server 3.8.2 → 3.10.0

package/dist/language/flows/flow-start-path.js

@@ -2,13 +2,14 @@
  * Replay's arrival at a flow's start page: navigate (or reload) before step 1, wait for the session
  * the SDK reconnects as, and say what happened when it does not.
  */
-import { EventType, ReticleCommand, } from '@reticlehq/core';
-import { establishedState, samePath, startPathBudgetMs } from './flow-journey.js';
+import { AnchorKind, EventType, ReticleCommand, } from '@reticlehq/core';
+import { declaredRoute, establishedState, fillRouteParams, isRoutePattern, onRoute, samePath, startPathBudgetMs, unmetRouteClaim, } from './flow-journey.js';
 import { asRecord } from '@reticlehq/core';
 import { navigablePath, routeOfEvent, routeOfUrl, } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
 import { anchorPrecondition, anchorQueryArgs } from './flow-step-runners.js';
 import { queryRefs } from './replay.js';
+import { refFor } from './flow-anchor.js';
 import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
 /**
  * The route the tab is on now: the last observed route.change, falling back to the pathname of the
@@ -136,12 +137,20 @@ async function firstStepResolvesHere(session, flow) {
         return false;
     }
     try {
-        return 0 < queryRefs(await session.command(ReticleCommand.QUERY, args)).length;
+        // THE control the recording meant, by the same rule replay applies to the step: one match, or
+        // the recorded position among exactly as many namesakes. A name that also appears elsewhere
+        // (30 "Edit" links on another page, 10 where the flow was recorded) is not "step 1 starts here".
+        return (refFor(first.anchor, queryRefs(await session.command(ReticleCommand.QUERY, args))) !==
+            undefined);
     }
     catch {
         return false;
     }
 }
+/** An anchor that is the app's own name for one control (a testid, a component): the same on every page. */
+function namesTheControl(anchor) {
+    return AnchorKind.TESTID === anchor?.kind || AnchorKind.COMPONENT === anchor?.kind;
+}
 /** The replay result, with how long replay waited for its start page when that went past the budget. */
 export function withStartPageWait(result, arrival) {
     return arrival.wait === undefined ? result : { ...result, startPageWait: arrival.wait };
@@ -150,6 +159,20 @@ export function withStartPageWait(result, arrival) {
 function waitOf(outcome) {
     return outcome.wait === undefined ? {} : { wait: outcome.wait };
 }
+/*
+ * The page each tab was on when its last replay ended, by session id. A page load gives the tab a
+ * new id, so an entry still matches only when nothing loaded since: the query on that page is what
+ * the last flow left, not what the caller chose.
+ * ponytail: one entry per replayed tab, never pruned; prune on session close if tabs ever churn.
+ */
+const leftByReplay = new Map();
+/** Record where a replay left the tab, so the next reset does not keep that flow's query. */
+export function noteReplayEnded(session) {
+    const path = currentPathOf(session);
+    if (path !== undefined) {
+        leftByReplay.set(session.id, path);
+    }
+}
 /**
  * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
  * RELOAD it if it is already there.
@@ -164,6 +187,10 @@ function waitOf(outcome) {
  * or from the wrong page. Silence is not an opt-out: a flow that depends on leftovers without
  * saying so is a flow whose green means nothing on a fresh machine, and CI is a fresh machine.
  *
+ * A route in `requires` is not an opt-out. It is the page the flow needs, and replay goes there:
+ * see `arriveAtDeclaredRoute`. A suite ran such a flow on the page the previous flow left open,
+ * and its anchors then failed, or matched ambiguously, on an unrelated page (#2034).
+ *
  * A full-page load tears down the session socket, so the navigation must happen here — before any
  * step runs — and the replay continues on the session the SDK reconnects as (found via the same
  * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
@@ -174,6 +201,16 @@ function waitOf(outcome) {
 export async function arriveAtStartPath(sessions, session, flow, timeoutMs = startPathBudgetMs(flow), clock = REAL_ARRIVAL_CLOCK, 
 /** Whether the tab is still loading. Replay passes one for a pool lease, the only tab it can ask. */
 stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
+    const move = {
+        timeoutMs,
+        clock,
+        loadingCapMs,
+        ...(stillLoading === undefined ? {} : { stillLoading }),
+    };
+    const route = declaredRoute(flow);
+    if (route !== undefined) {
+        return arriveAtDeclaredRoute(sessions, session, flow, route, move);
+    }
     const target = flow.startPath;
     if (target === undefined || 0 === target.length) {
         return {};
@@ -190,30 +227,50 @@ stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
     // A route mismatch that step 1 can start from anyway is not worth a page load: navigating away
     // from a persistent anchor could only hurt, and did. Arriving is the goal; resetting a tab that is
     // ALREADY here is a different decision, taken above, and this must not override it.
-    if (!here && (await firstStepResolvesHere(session, flow))) {
+    // Only for an anchor that names the control itself (a testid, a component): a role and a name
+    // found on another page can be that page's own control, and step 1 then acts on the wrong one.
+    if (!here &&
+        namesTheControl(flow.steps?.[0]?.anchor) &&
+        (await firstStepResolvesHere(session, flow))) {
         return {};
     }
+    // A refused navigation left the tab untouched, and replay goes on with the connected session.
+    return (await moveTo(sessions, session, flow, target, here, current, move)) ?? {};
+}
+/**
+ * Navigate (or reload, when `here`) to `target` and say what came back. Undefined when the tab was
+ * not moved at all: no usable base URL, or the browser refused the navigation.
+ */
+async function moveTo(sessions, session, flow, target, here, current, move) {
     let destination;
     try {
         // startPath is a pathname (a host belongs to the machine, not the journey) — resolve it
         // against the tab's own URL to get something the browser can be sent to. Already HERE, the
         // reset reloads the page the tab is on: `samePath` ignored a query the flow did not record, and
         // navigating to `target` would strip it, so the replay would test a different page than the one
-        // it just agreed it was on.
-        destination = new URL(here ? current : target, session.url).toString();
+        // it just agreed it was on. A query that the last replay left is not kept: it is the previous
+        // flow's state, and keeping it gave the next flow a filtered page that it never recorded.
+        const keepQuery = here && leftByReplay.get(session.id) !== current;
+        destination = new URL(keepQuery ? current : target, session.url).toString();
     }
     catch {
-        return {}; // no usable base URL — nowhere to navigate from
+        return undefined; // no usable base URL — nowhere to navigate from
     }
     // Measured either side of the reset, and only when the reset is a reload: reachable before and
     // gone after is the reload's doing, not the flow file's. Without this, an app holding its session
     // in memory comes back signed out and step 1 blames a component that is completely fine.
     const resolvedBefore = here && (await firstStepResolvesHere(session, flow));
-    const outcome = await navigateAndAwait(sessions, session, destination, target, timeoutMs, clock, here, stillLoading, loadingCapMs);
+    const outcome = await navigateAndAwait(sessions, session, destination, target, move.timeoutMs, move.clock, {
+        isReload: here,
+        ...(move.stillLoading === undefined ? {} : { stillLoading: move.stillLoading }),
+        loadingCapMs: move.loadingCapMs,
+    });
     if ('lost' === outcome.kind) {
         const why = outcome.stillLoading
             ? 'The page was still loading when replay stopped waiting: check that the app finishes loading, then replay'
-            : 'A slow or backgrounded tab can take longer to come back: bring it to the front and replay';
+            : 'A dev server that compiles on the first load can take longer than that: raise the wait with ' +
+                '`timeoutMs` on step 1 or `signalTimeoutMs` in the flow file, then replay. A backgrounded tab ' +
+                'can also be slow: bring it to the front';
         return {
             lost: `replay ${here ? 'reloaded' : 'navigated to'} ${target} before step 1 and no page was connected ` +
                 `after ${String(outcome.waitedMs)}ms, so the session it was driving is gone and nothing ran. ${why}`,
@@ -221,7 +278,7 @@ stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
         };
     }
     if ('refused' === outcome.kind) {
-        return {};
+        return undefined;
     }
     if ('redirected' === outcome.kind) {
         const path = currentPathOf(outcome.session) ?? 'another route';
@@ -241,6 +298,107 @@ stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
         ...waitOf(outcome),
     };
 }
+/**
+ * The arrival for a replay that continues at a step and so does not move the tab. A declared route
+ * claim must still hold where the tab is, as it did when it was a precondition the run checked.
+ */
+export function routeClaimsWhereTheTabIs(flow, session) {
+    const route = declaredRoute(flow);
+    if (route === undefined) {
+        return {};
+    }
+    const current = currentPathOf(session);
+    const unmet = current === undefined
+        ? 'replay cannot see which page it is on'
+        : unmetRouteClaim(flow, current);
+    if (unmet === undefined) {
+        return {};
+    }
+    return {
+        unreached: unreachedReason(route, current, `replay continues mid-flow there, and ${unmet}`),
+    };
+}
+/**
+ * Replay's arrival for a flow that declares the route it needs in `requires` (#2034).
+ *
+ * The tab goes to that route before step 1, the same way it goes to a `startPath`, and the same
+ * reset applies once it is there. Two differences, both because the flow SAID where it must be:
+ *
+ * - A route with an entity id (`/cases/:id/notes`) keeps the id of the page the tab is on when that
+ *   page matches. The recorded address names one record, and that record can be deleted since: a
+ *   replay sent there ran a generic flow on a fixture that no longer existed and answered `unknown`.
+ * - When replay cannot put the tab on the route, it says so and nothing runs. Running anyway gave a
+ *   verdict about another page, reported as a missing or ambiguous anchor.
+ */
+async function arriveAtDeclaredRoute(sessions, session, flow, route, move) {
+    const current = currentPathOf(session);
+    if (current === undefined) {
+        return {
+            unreached: unreachedReason(route, undefined, 'replay cannot see which page it is on'),
+        };
+    }
+    const here = onRoute(current, route);
+    // The opt-out keeps the tab as it is. It does not make another page the right one.
+    if (0 < establishedState(flow).length) {
+        if (unmetRouteClaim(flow, current) === undefined) {
+            return {};
+        }
+        return {
+            unreached: unreachedReason(route, current, 'the flow also declares state that a page load would discard, so replay does not move the tab'),
+        };
+    }
+    const target = routeTarget(flow, route, current, here);
+    if (target === undefined) {
+        return {
+            unreached: unreachedReason(route, current, 'the route names an entity id, and the flow records no address on that route to open'),
+        };
+    }
+    const moved = await moveTo(sessions, session, flow, target, samePath(current, target), current, move);
+    if (moved === undefined) {
+        return { unreached: unreachedReason(route, current, `the page refused to open ${target}`) };
+    }
+    const landed = moved.session === undefined ? current : currentPathOf(moved.session);
+    // Every declared route claim, its `contains` too, is checked on the page replay arrived at.
+    const unmet = landed === undefined ? 'replay cannot see which page it is on' : unmetRouteClaim(flow, landed);
+    if (unmet === undefined) {
+        return moved;
+    }
+    const { redirected, ...rest } = moved;
+    const why = redirected === undefined
+        ? `replay opened ${target}, and ${unmet}`
+        : `replay opened ${target}, and the app sent the tab to another page`;
+    return { ...rest, unreached: unreachedReason(route, landed, why) };
+}
+/**
+ * Where replay sends the tab for a declared route.
+ *
+ * A pattern that the tab already matches: the tab's own page, so its id is kept. A pattern whose
+ * ids the tab can give (another section of the same case): the route with those ids. Else the
+ * flow's `startPath` when it is on the route, because it is the page the journey was recorded on.
+ * Else the route itself when it is a plain path. A pattern with no address to open has no target.
+ */
+function routeTarget(flow, route, current, here) {
+    const pattern = isRoutePattern(route);
+    if (here && pattern) {
+        // Without its query: `moveTo` keeps the query unless the previous replay left it.
+        return current.replace(/\?[^#]*/, '');
+    }
+    const filled = pattern ? fillRouteParams(route, current) : undefined;
+    if (filled !== undefined) {
+        return filled;
+    }
+    const start = flow.startPath;
+    if (start !== undefined && 0 < start.length && onRoute(start, route)) {
+        return start;
+    }
+    return pattern ? undefined : route;
+}
+/** Why a flow with a declared route did not run, and the one move that lets it. */
+function unreachedReason(route, current, why) {
+    const where = current ?? 'a page replay cannot see';
+    return (`this flow declares that it starts on ${route}, but the tab is on ${where}: ${why}. ` +
+        `Nothing ran and nothing was proved. Open a page on ${route} (reticle_navigate), then replay`);
+}
 /**
  * Why step 1 failed after the reset, and the one line that opts the flow out.
  *
@@ -256,11 +414,32 @@ function resetCostHint(flow, target) {
     return (`replay reloaded ${target} before step 1 and the first anchor did not come back — this flow ` +
         `starts from state a page load discards. ${optOut}, or record it from a cold page`);
 }
-export async function navigateAndAwait(sessions, session, destination, expectedPath, timeoutMs, clock = REAL_ARRIVAL_CLOCK, 
-/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
-isReload = false, 
-/** Whether the navigated page is still loading; absent when it cannot be asked. */
-stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
+/**
+ * Whether assigning `to` from `from` is a jump within the same document. That is the case when the
+ * URLs differ at most in the fragment and `to` has a fragment; a browser then loads no page. Without
+ * a fragment, the same URL reloads by itself. Undefined or unparsable URLs are not a jump.
+ */
+export function isFragmentJump(from, to) {
+    if (from === undefined) {
+        return false;
+    }
+    try {
+        const a = new URL(from);
+        const b = new URL(to);
+        if (0 === b.hash.length) {
+            return false;
+        }
+        a.hash = '';
+        b.hash = '';
+        return a.href === b.href;
+    }
+    catch {
+        return false;
+    }
+}
+export async function navigateAndAwait(sessions, session, destination, expectedPath, timeoutMs, clock = REAL_ARRIVAL_CLOCK, options = {}) {
+    const { isReload = false, stillLoading, acceptRedirect = false } = options;
+    const loadingCapMs = options.loadingCapMs ?? START_PATH_LOADING_CAP_MS;
     // A leased tab is addressed by URL params, so navigating without them would strand the lease.
     const url = carryReticleIdentity(session.url, destination);
     try {
@@ -268,6 +447,11 @@ stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
         if (!outcome.ok || true !== asRecord(outcome.result)['ok']) {
             return { kind: 'refused' };
         }
+        // A same-document URL with a fragment loads no page: the browser only jumps within it. Ask for
+        // the load this function waits for. A hash-routed app's replay never started without it.
+        if (isFragmentJump(session.url, url)) {
+            await session.command(ReticleCommand.REFRESH, {});
+        }
     }
     catch (error) {
         // A navigation that unloads the page rejects the very command that asked for it — the transport
@@ -291,6 +475,9 @@ stillLoading, loadingCapMs = START_PATH_LOADING_CAP_MS) {
         if (true === arrived?.matches) {
             return { kind: 'arrived', session: arrived.session, ...extendedWait() };
         }
+        if (acceptRedirect && arrived !== undefined) {
+            return { kind: 'redirected', session: arrived.session, ...extendedWait() };
+        }
         if (clock.now() >= deadline) {
             // A live redirect is a different result from no SDK reconnection at all.
             if (arrived !== undefined) {

package/dist/language/flows/flow-step-runners.d.ts

@@ -1,6 +1,7 @@
 import { AnchorKind, type Drift, type FlowAnchor, type FlowReplayResult, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 import { type Reresolved } from './flow-anchor.js';
+import { type Baselines } from '@reticlehq/engine/evidence/baseline.js';
 /** The live act_sequence tool gives each step this transport budget when none was supplied. */
 export declare const DEFAULT_SEQUENCE_STEP_TIMEOUT_MS = 8000;
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
@@ -83,7 +84,15 @@ export declare function anchorPrecondition(anchor: FlowAnchor): Predicate | unde
  * Left alone, so the ordinary verdict stands, when anything else is in the run: a drifted anchor is
  * drift whatever else happened, and a failure that is not staleness is a failure.
  */
-export declare function staleTargetResult(name: string, steps: readonly FlowStepResult[]): FlowReplayResult | undefined;
+export declare function staleTargetResult(name: string, steps: readonly FlowStepResult[], 
+/**
+ * `startControlRequired`: replay loaded the start page itself, with no redirect, and the caller
+ * asked that a missing step 1 control fail. Then the miss means the app does not offer the control
+ * the journey starts with (#2061), so it stays drift. Without it, the miss is not proved.
+ */
+options?: {
+    startControlRequired?: boolean;
+}): FlowReplayResult | undefined;
 /**
  * The honest answer when a step acted on a target no person could have clicked (covered, of no
  * size, off screen). The replay stopped there, and nothing about the app was decided: undecided as a
@@ -93,19 +102,11 @@ export declare function staleTargetResult(name: string, steps: readonly FlowStep
 export declare function unreachableTargetResult(name: string, steps: readonly FlowStepResult[]): FlowReplayResult | undefined;
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
- * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one
- * execute identically.
- *
- * `replayFlow` had no sequence branch at all. It dispatches on `anchor.kind`, so a saved sequence fell
- * to the testid runner and ran ONE act with `action: ''` (a saved sequence carries no top-level
- * action) — sub-steps 2..n never executed. Fixing the anchor without this would have turned a visible
- * drift into a silent partial replay reporting ok.
+ * ACT_SEQUENCE, the shape `replayProgram` uses, so a recorded sequence and a saved one run the same.
  */
 export declare function runSequenceStep(session: FlowReplaySession, step: FlowStep, index: number, subs: readonly FlowStep[], confirmDangerous: boolean, sleep: Sleep, 
 /** Testids whose presence is deliberately NOT asserted — the LLM-output case. */
 dynamic?: ReadonlySet<string>, 
-/**
- * Judge one sub-step's `expect` over the window from `since`, which opens just before that
- * sub-step's dispatch. Omitted for a setup step, whose consequences are not checked.
- */
-judge?: (expectation: Predicate, since: number) => Promise<Drift | undefined>): Promise<FlowStepResult>;
+/** Judge a sub-step's `expect` from `since`, just before its dispatch, against the `before`
+ *  reading; omitted for a setup step, whose consequences are not checked. */
+judge?: (expectation: Predicate, since: number, before?: Baselines) => Promise<Drift | undefined>): Promise<FlowStepResult>;