@reticlehq/server 3.2.0 → 3.3.0

package/dist/language/flows/flow-replay-run.js

@@ -6,7 +6,7 @@ import { asRecord, asString } from '@reticlehq/core';
 import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { carryReticleIdentity } from '../../surface/tools/lease-tools.js';
 import { replayFlow } from './flow-replay.js';
-import { anchorQueryArgs } from './flow-step-runners.js';
+import { anchorPrecondition, anchorQueryArgs } from './flow-step-runners.js';
 import { queryRefs } from './replay.js';
 import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
 import { buildDecision, unverifiableReason } from './decision.js';
@@ -47,6 +47,9 @@ export function latestRecordedFlow(events) {
 export function flowErrorMessage(code, detail) {
     if (FlowErrorCode.PARSE_FAILED === code && undefined !== detail)
         return detail;
+    // The detail names both versions and the remedy, so it beats anything generic this could say.
+    if (FlowErrorCode.WRONG_VERSION === code && undefined !== detail)
+        return detail;
     switch (code) {
         case FlowErrorCode.INVALID_NAME:
             return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
@@ -56,6 +59,10 @@ export function flowErrorMessage(code, detail) {
             return FlowParseNote.MALFORMED;
         case FlowErrorCode.NO_RECORDING:
             return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
+        // Never "regenerate it": the file is intact and the reader is the wrong one. Telling somebody
+        // to rewrite an undamaged flow is the failure this code was split out of PARSE_FAILED to stop.
+        case FlowErrorCode.WRONG_VERSION:
+            return 'this flow file was written in a different flow-file format — the file is not damaged, this Reticle cannot read that version. Upgrade or downgrade Reticle rather than editing the flow';
     }
 }
 /** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
@@ -106,20 +113,46 @@ recordRoot) {
 function currentPathOf(session) {
     const routes = session.eventsSince(0).filter((e) => e.type === EventType.ROUTE_CHANGE);
     const last = routes.at(-1);
-    // pathname + hash, because `startPath` is compared against this and must stay NAVIGABLE. Reading
-    // the pathname alone made both sides `/` on a hash router — always "same path", so the hint never
-    // fired however far the tab had drifted, on the router desktop renderers use by default.
+    // pathname + search + hash, because `startPath` is compared against this and must stay NAVIGABLE.
+    //
+    // Reading the pathname alone made both sides `/` on a hash router — always "same path", so the
+    // hint never fired however far the tab had drifted, on the router desktop renderers use by
+    // default. Leaving the SEARCH out was the mirror defect: `startPath` keeps its query, so a flow
+    // starting at `/admin/events/7?tab=wrap` never matched a tab sitting on exactly that, re-navigated
+    // on every replay, and the re-navigation killed the session mid-flow.
+    //
+    // Comparing without the query instead would have been worse in the direction that matters. The
+    // query usually decides what the page renders, so a tab on `?tab=summary` would read as "already
+    // at `?tab=wrap`" and the replay would start on the wrong page with nothing saying so. Both sides
+    // carry it, which keeps a real difference visible and stops the false one.
     const observed = last === undefined ? undefined : routeOfEvent(last);
     if (observed !== undefined)
-        return `${observed.docPath}${observed.hash}`;
+        return `${observed.docPath}${observed.search}${observed.hash}`;
     if (session.url === undefined)
         return undefined;
     const fromUrl = routeOfUrl(session.url);
-    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.hash}`;
+    return fromUrl === undefined ? undefined : `${fromUrl.docPath}${fromUrl.search}${fromUrl.hash}`;
 }
-/** Pathname equality up to a trailing slash — a router normalising one must not read as "elsewhere". */
-function samePath(a, b) {
-    return a.replace(/\/$/, '') === b.replace(/\/$/, '');
+/**
+ * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
+ * did not ask about.
+ *
+ * `startPath` is the SPECIFICATION, so it decides what counts. A query it recorded is compared:
+ * `?tab=wrap` and `?tab=summary` are different pages, and a replay that starts on the wrong one
+ * proves nothing about the right one. A query it did NOT record is ignored: the tab carrying
+ * `?next=%2F` on a login page, or the identity params Reticle puts on a leased tab, are not the flow
+ * being elsewhere, and navigating to strip them costs a session for nothing.
+ *
+ * The asymmetry is the whole point and the reason `observed` and `expected` are named rather than
+ * `a` and `b`. Comparing with the query on both sides always re-navigated a query-bearing
+ * `startPath` (#1059, which killed the session mid-flow); comparing with it on neither side reads a
+ * tab on `?tab=summary` as already at `?tab=wrap`.
+ */
+function samePath(observed, expected) {
+    const trimmed = (path) => path.replace(/\/$/, '');
+    const withoutQuery = (path) => path.replace(/\?[^#]*/, '');
+    const comparable = expected.includes('?') ? observed : withoutQuery(observed);
+    return trimmed(comparable) === trimmed(expected);
 }
 /**
  * Ask the project what it already knows about this flow.
@@ -201,9 +234,26 @@ const REAL_ARRIVAL_CLOCK = {
  * `resolve` throws). Keyed to the navigated tab's own identity on purpose: matching "any session at
  * the target page" would happily hand replay an unrelated tab that was already sitting there.
  */
-function arrivedSuccessor(sessions, oldId, target) {
+function arrivedSuccessor(sessions, oldId, target, 
+/** The handle that issued the navigation, when only a genuinely new one counts as arrival. */
+mustReplace) {
     try {
         const candidate = sessions.resolve(oldId);
+        /*
+         * A RELOAD lands on the path it left, so the path cannot tell the successor from the tab that
+         * is still tearing down — `resolve(oldId)` answers with the dying one while it is registered,
+         * which looks like instant arrival and hands replay a socket that will never answer again.
+         *
+         * The discriminator is the OBJECT, not the id. A leased tab carries its identity across a page
+         * load (that is what the identity params are for), so it reconnects under the SAME id — waiting
+         * for a new id there waits forever, and the first lease this was tried on timed out at step 1
+         * on a tab that was perfectly healthy. `SessionManager.add` replaces the instance on every
+         * reconnect, so a different instance is exactly "the socket came back".
+         *
+         * A navigation to a different route has the path as its discriminator and does not need this.
+         */
+        if (mustReplace !== undefined && candidate === mustReplace)
+            return undefined;
         const path = currentPathOf(candidate);
         return path !== undefined && samePath(path, target) ? candidate : undefined;
     }
@@ -242,36 +292,83 @@ async function firstStepResolvesHere(session, flow) {
     }
 }
 /**
- * Replay's half of the FlowFile contract: navigate to the flow's `startPath` before step 1.
+ * 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.
+ *
+ * The reload is the state contract. Replaying "add a task" twice against a tab nobody reset gives
+ * the second run a world the recording never saw, and its assertions then describe the first run
+ * rather than the app. Our own `replay-determinism.mjs` has always refreshed before every run — the
+ * determinism we measured was never the determinism a user got.
+ *
+ * `requires` is the declared opt-out, and its first caller. A flow that says it starts from state
+ * another flow established is the one flow a page load would destroy, so it is never reset — here
+ * 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 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:
- * when the flow carries no startPath, the tab is already there, the current route is unobservable,
- * the navigation is refused, or the SDK never reconnects in the window, it returns undefined and
- * replay proceeds on the connected session as before — with startPathMismatchHint turning any
- * resulting drift into an actionable next move rather than a mystifying one.
+ * when the flow carries no startPath, the current route is unobservable, the navigation is refused,
+ * or the SDK never reconnects in the window, replay proceeds on the connected session as before —
+ * with startPathMismatchHint turning any resulting drift into an actionable next move rather than a
+ * mystifying one.
  */
 export async function arriveAtStartPath(sessions, session, flow, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK) {
     const target = flow.startPath;
     if (target === undefined || 0 === target.length)
-        return undefined;
+        return {};
     const current = currentPathOf(session);
-    if (current === undefined || samePath(current, target))
-        return undefined;
-    // The route differs — but that only matters if it stops the flow starting. See above.
-    if (await firstStepResolvesHere(session, flow))
-        return undefined;
+    if (current === undefined)
+        return {};
+    // The declared opt-out, both directions. See above.
+    if (0 < (flow.requires?.length ?? 0))
+        return {};
+    const here = samePath(current, target);
+    // 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)))
+        return {};
     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.
-        destination = new URL(target, session.url).toString();
+        // 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();
     }
     catch {
-        return undefined; // no usable base URL — nowhere to navigate from
+        return {}; // no usable base URL — nowhere to navigate from
     }
-    return navigateAndAwait(sessions, session, destination, target, timeoutMs, clock);
+    // 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 arrived = await navigateAndAwait(sessions, session, destination, target, timeoutMs, clock, here);
+    if (arrived === undefined)
+        return {};
+    if (!resolvedBefore || (await firstStepResolvesHere(arrived, flow)))
+        return { session: arrived };
+    return {
+        session: arrived,
+        resetCost: resetCostHint(flow, target),
+    };
+}
+/**
+ * Why step 1 failed after the reset, and the one line that opts the flow out.
+ *
+ * No tool writes `requires`, so naming the field was advice nobody could act on without guessing its
+ * shape. The first anchor IS the precondition: the element step 1 needs, present before it runs.
+ */
+function resetCostHint(flow, target) {
+    const first = flow.steps?.[0];
+    const needs = first === undefined ? undefined : anchorPrecondition(first.anchor);
+    const optOut = needs === undefined
+        ? 'Declare what it needs (`requires`) in the flow file to opt out of the reset'
+        : `Add \`"requires":${JSON.stringify([needs])}\` to the flow file to opt out of the reset`;
+    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`);
 }
 /**
  * Send a tab somewhere and wait for the session that comes back.
@@ -285,7 +382,9 @@ export async function arriveAtStartPath(sessions, session, flow, timeoutMs = STA
  * to move and this decides how, which is also why the deliberate short-circuits live up there and
  * not in here: a caller that has already decided it must move should not have to argue with them.
  */
-export async function navigateAndAwait(sessions, session, destination, expectedPath, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK) {
+export async function navigateAndAwait(sessions, session, destination, expectedPath, timeoutMs = START_PATH_ARRIVAL_TIMEOUT_MS, clock = REAL_ARRIVAL_CLOCK, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload = false) {
     // A leased tab is addressed by URL params, so navigating without them would strand the lease.
     const url = carryReticleIdentity(session.url, destination);
     try {
@@ -303,7 +402,7 @@ export async function navigateAndAwait(sessions, session, destination, expectedP
     }
     const deadline = clock.now() + timeoutMs;
     for (;;) {
-        const arrived = arrivedSuccessor(sessions, session.id, expectedPath);
+        const arrived = arrivedSuccessor(sessions, session.id, expectedPath, isReload ? session : undefined);
         if (arrived !== undefined)
             return arrived;
         if (clock.now() >= deadline)
@@ -361,7 +460,15 @@ async function firstUnmetPrecondition(session, flow, since) {
     for (const claim of flow.requires ?? []) {
         // Zero budget: a precondition is a claim about the state you are starting FROM. Waiting for one
         // turns "was it true" into "did it become true", which is a different and much weaker question.
-        const drift = await assertStepExpect(session, claim, new Set(), waitForPredicate, 0, since);
+        let drift;
+        try {
+            drift = await assertStepExpect(session, claim, waitForPredicate, 0, since);
+        }
+        catch (error) {
+            if (!isDocumentGoneError(error))
+                throw error;
+            return `the page went away while this flow's preconditions were being checked, so nothing ran and nothing was proved. Replay again once the page is back.`;
+        }
         if (drift !== undefined) {
             return `a precondition of this flow does not hold (${JSON.stringify(claim)}), so nothing ran and nothing was proved. Run the flow that establishes it first, or drive that state yourself.`;
         }
@@ -390,7 +497,8 @@ export function lostDocumentResult(name, lost) {
         status: ReplayStatus.OK,
         steps: lost.steps,
         unverifiable: {
-            reason: `the page loaded a new document while step ${String(lost.atStep)} was running, so the run ` +
+            reason: `the page's connection to Reticle was replaced while step ${String(lost.atStep)} was running ` +
+                `(a new document loaded, or its socket reconnected), so the run ` +
                 `could not be graded — the steps before it are reported and nothing after it was observed. ` +
                 `Nothing here says the app failed. If that navigation is part of the journey, record the ` +
                 `step's consequence with \`expect\` and replay again; if it was not, the flow started ` +
@@ -398,7 +506,9 @@ export function lostDocumentResult(name, lost) {
         },
     };
 }
-export async function replayNamedFlow(deps, args) {
+export async function replayNamedFlow(deps, args, 
+/** Wraps the session the steps run on, so a caller can watch what they resolved. */
+observe = (s) => s) {
     const startedAt = deps.now();
     const name = asString(args['flowName']) ?? '';
     // Resolve within the connecting app's scope so a shared daemon replays THIS project's flow, not a
@@ -438,8 +548,11 @@ export async function replayNamedFlow(deps, args) {
     // The FlowFile contract: replay navigates to the flow's startPath before step 1, and the steps run
     // on the session the SDK reconnects as. When arrival can't be confirmed, replay proceeds on the
     // connected session — and the hint below turns the wrong-page drift into an actionable next move.
-    const session = (await arriveAtStartPath(deps.sessions, connected, loaded.value)) ?? connected;
-    const startPathHint = startPathMismatchHint(loaded.value, session);
+    const arrival = await arriveAtStartPath(deps.sessions, connected, loaded.value);
+    const session = arrival.session ?? connected;
+    // The reset's own cost outranks the wrong-page hint: if the reload is why step 1 cannot start,
+    // "navigate there and replay" is advice that would do the same thing again.
+    const startPathHint = arrival.resetCost ?? startPathMismatchHint(loaded.value, session);
     // Floor the success oracle at the start of THIS replay so a stale signal from a prior run
     // in the same session can't fake a pass.
     const replayFloor = session.elapsed();
@@ -506,7 +619,7 @@ export async function replayNamedFlow(deps, args) {
     }
     let steps;
     try {
-        steps = await replayFlow(session, replayable, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous'], undefined, {
+        steps = await replayFlow(observe(session), replayable, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous'], undefined, {
             // How an `invoke` step finds the flow it runs. Scoped to the same project as the flow being
             // replayed, so a composite cannot reach into another app's store for a same-named sub-journey.
             resolveFlow: async (invoked) => {

package/dist/language/flows/flow-replay-types.d.ts

@@ -26,6 +26,15 @@ export interface FlowReplaySession {
     onEvent(listener: (event: ReticleEvent) => void): () => void;
     /** Buffer clock (ms since connect) — required by the predicate engine's `settled` check. */
     elapsed(): number;
+    /**
+     * Where the app under test lives, so a third-party beacon is not mistaken for the app still
+     * working. Optional for the same reason `beginAction` is — a minimal test double should not have
+     * to invent an origin — and it FAILS OPEN: with no origin nothing is foreign, so an omitted value
+     * suppresses nothing rather than silently widening what a replay ignores.
+     */
+    url?: string;
+    /** Same-origin endpoints the project declared as background — see `Session.background`. */
+    background?: readonly string[];
 }
 /**
  * The injected predicate-waiter (the real waitForPredicate) — reused, never reimplemented.

package/dist/language/flows/flow-replay.d.ts

@@ -1,4 +1,3 @@
-import { Surface } from 'open-verification';
 export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
 import type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
 export type { FlowReplaySession, WaitForSignal, Sleep } from './flow-replay-types.js';
@@ -20,6 +19,8 @@ export declare class DocumentLostDuringReplay extends Error {
     readonly atStep: number;
     constructor(steps: FlowStepResult[], atStep: number, lostTo?: unknown);
 }
+/** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
+export declare function runTestidStep(session: FlowReplaySession, step: FlowStep, index: number, value: string, dynamic: ReadonlySet<string>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
 /**
  * After a step's anchor resolves and its action runs, its `expect` is EVALUATED — every kind of it.
  *
@@ -41,16 +42,23 @@ export declare class DocumentLostDuringReplay extends Error {
  * quietly stop agreeing, and the disagreement would land as a flow that replays green against a
  * state it was never meant to run in.
  */
-export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, dynamic: ReadonlySet<string>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
+export declare function assertStepExpect(session: FlowReplaySession, expect: NonNullable<FlowStep['expect']>, waitForSignal: WaitForSignal, timeoutMs: number, since: number): Promise<Drift | undefined>;
 /**
  * Replay a loaded flow by RE-RESOLVING every step's semantic anchor against the live DOM — never
  * a stale ref. A testid anchor is re-found by reticle_query; a signal anchor waits on a predicate.
  * On the first anchor MISS the step carries legible drift and replay STOPS, returning the partial
  * results. This is the "whose fault is it" contract, not a blind "command failed".
  */
-/** Where a replay starts reporting. Steps before it are re-driven, silently, as setup. */
+/**
+ * How a replay is loaded and how far it goes — not WHERE it starts.
+ *
+ * It carried a `from` (and a `surface` that existed only to gate it): replay from step N, re-driving
+ * the prefix silently. The machinery was built, tested and reachable from nothing at all — no tool
+ * argument, no CLI flag, no caller anywhere. Deleted rather than wired: unreachable code is read as
+ * current by the next person and maintained forever, its passing tests make it look load-bearing,
+ * and nobody has asked for resume-from-step. The history keeps it if it is ever wanted.
+ */
 export interface ReplayFromOptions {
-    from?: number;
     /**
      * How to load a flow this one INVOKES. Absent means invocations cannot be followed.
      *
@@ -67,13 +75,6 @@ export interface ReplayFromOptions {
         flow: string;
         step: number;
     }[];
-    /**
-     * Which kind of subject this is. Decides whether re-driving the prefix is allowed at all.
-     *
-     * Defaults to `web`, which is the permissive answer — correct for the only surface that resumes
-     * today, and the reason a caller on a committing surface must say so rather than rely on silence.
-     */
-    surface?: Surface;
     /**
      * Keep going past a step whose ACTION ran and whose declared consequence merely did not hold.
      *