@reticlehq/server 3.1.0 → 3.3.0

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

@@ -6,12 +6,13 @@ 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';
 import { unsuppliedSecrets } from './fields/flow-secret-field.js';
-import { assertStepExpect } from './flow-replay.js';
+import { assertStepExpect, DocumentLostDuringReplay, } from './flow-replay.js';
+import { isDocumentGoneError } from '../../portal/session/facts/session-replaced.js';
 import { classifyFlowAssertions, flattenSteps } from './flow-classify.js';
 import { dischargeFlowIntent, flowIntentStatement, flowReplayVerdictId } from './flow-intent.js';
 import { IntentStore } from '../../memory/intent/intent-store.js';
@@ -29,6 +30,7 @@ import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
 import { consultSubjectFor, selectConsulted } from './flow-memory-consult.js';
 import { log } from '../../log.js';
 import { flowsForSession } from './flow-store-for-session.js';
+import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { FlowParseNote } from './flow-expect-grammar.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
@@ -45,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';
@@ -54,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). */
@@ -76,7 +85,7 @@ async function recordReplayRun(deps, name, status, driftSteps, durationMs, proje
 /** The APP's `.reticle`, resolved from the session — never the daemon's own. */
 recordRoot) {
     const runStatus = replayToRunStatus(status);
-    await deps.project.recordRun({
+    await projectForRoot(deps, recordRoot).recordRun({
         kind: RunKind.FLOW_REPLAY,
         name,
         status: runStatus,
@@ -104,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.
@@ -199,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;
     }
@@ -240,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.
@@ -283,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 {
@@ -291,12 +392,17 @@ export async function navigateAndAwait(sessions, session, destination, expectedP
         if (!outcome.ok || true !== asRecord(outcome.result)['ok'])
             return undefined;
     }
-    catch {
-        return undefined;
+    catch (error) {
+        // A navigation that unloads the page rejects the very command that asked for it — the transport
+        // dies with the document. Reading that as "the navigate failed" skipped the arrival poll below
+        // and left replay driving a handle that could never answer again, which is how a flow with a
+        // startPath died at step 1 on an app that had loaded perfectly. Anything else is a real refusal.
+        if (!isDocumentGoneError(error))
+            return undefined;
     }
     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)
@@ -354,14 +460,55 @@ 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.`;
         }
     }
     return undefined;
 }
-export async function replayNamedFlow(deps, args) {
+/**
+ * The honest answer when the document replay was driving went away mid-run.
+ *
+ * Not a pass: nothing graded the journey, and the steps in hand are only the ones the departed
+ * document answered. Not a failure either — the app was never observed doing anything wrong, and
+ * reporting one would be the false red that sends a reader into product code that is fine. So it
+ * lands in the bucket this engine already has for "nothing was proved", the same one an unmet
+ * precondition uses, with the steps that DID answer attached and no row invented for the one that
+ * did not.
+ *
+ * Why replay reports rather than follows: the successor cannot be identified at the moment the
+ * socket closes. `SessionManager.remove` runs from the close handler, writes the tombstone a
+ * successor is later matched against, and has nothing to match yet — so the rejection is a plain
+ * transport failure by design, and a step in the middle of a journey has no budget to sit and poll
+ * with. `navigateAndAwait` CAN wait, because it knows it asked for the navigation, and it does.
+ */
+export function lostDocumentResult(name, lost) {
+    return {
+        name,
+        status: ReplayStatus.OK,
+        steps: lost.steps,
+        unverifiable: {
+            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 ` +
+                `somewhere it no longer belongs.`,
+        },
+    };
+}
+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
@@ -401,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();
@@ -467,17 +617,25 @@ export async function replayNamedFlow(deps, args) {
             unverifiable: { reason: unmet },
         };
     }
-    const steps = await replayFlow(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) => {
-            const sub = await flowsForSession(deps, projectId).flows.load(invoked, projectId);
-            return sub.ok ? await resolveFlowUploads(deps, sub.value) : undefined;
-        },
-        // Bug-sweep mode: keep going past a step whose action ran and whose consequence merely did
-        // not hold, so one flow reports one verdict per step instead of stopping at the first defect.
-        sweep: true === args['sweep'],
-    });
+    let steps;
+    try {
+        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) => {
+                const sub = await flowsForSession(deps, projectId).flows.load(invoked, projectId);
+                return sub.ok ? await resolveFlowUploads(deps, sub.value) : undefined;
+            },
+            // Bug-sweep mode: keep going past a step whose action ran and whose consequence merely did
+            // not hold, so one flow reports one verdict per step instead of stopping at the first defect.
+            sweep: true === args['sweep'],
+        });
+    }
+    catch (error) {
+        if (!(error instanceof DocumentLostDuringReplay))
+            throw error;
+        return lostDocumentResult(name, error);
+    }
     // Computed HERE, before the synthetic success row is appended below: once that row is pushed,
     // `steps.length` no longer counts only the flow's own steps and the arithmetic is wrong.
     const halted = haltedFrom(steps, loaded.value.steps.length);
@@ -522,7 +680,7 @@ export async function replayNamedFlow(deps, args) {
     // Anti-reward-hacking baseline: record what this flow asserted ONLY when it passed clean. A
     // failing run must never become the baseline a later weakening is measured against.
     if (status === ReplayStatus.OK) {
-        await new AssertionTiersStore(deps.fs, deps.reticleRoot).recordPassing(name, loaded.value.steps.map((s, i) => ({
+        await new AssertionTiersStore(deps.fs, replayRoot).recordPassing(name, loaded.value.steps.map((s, i) => ({
             step: i,
             ...(s.expect === undefined ? {} : { expect: s.expect }),
         })), 
@@ -542,7 +700,7 @@ export async function replayNamedFlow(deps, args) {
         }
     }
     // Push-default: the deviation report over this drive's segments, learned across runs. Best-effort.
-    const deviation = await computeReplayDeviation(deps, session, replayFloor);
+    const deviation = await computeReplayDeviation(deps, session, replayFloor, replayRoot);
     /*
      * What the team already knows about this flow, fetched on the agent's behalf.
      *
@@ -669,12 +827,14 @@ export function crossStepOnly(whole, steps) {
  * The deviation report over a replay's route segments — compared against the learned envelope, which is
  * then updated. Best-effort: any failure (disk, empty window) yields undefined, never breaking the replay.
  */
-async function computeReplayDeviation(deps, session, floor) {
+async function computeReplayDeviation(deps, session, floor, 
+/** The APP's root — the same one the replay resolved eleven lines above the old call. */
+root) {
     try {
         const segments = computeSegments(session.eventsSince(floor));
         if (0 === segments.length)
             return undefined;
-        return await reportAndAccumulate(new EnvelopeStore(deps.fs, deps.reticleRoot), segments);
+        return await reportAndAccumulate(new EnvelopeStore(deps.fs, root), segments);
     }
     catch {
         return undefined;
@@ -691,12 +851,11 @@ function applyStartPathHint(result, hint) {
  * The connecting session's project, or undefined when no browser is attached. Flow tools use it to
  * scope storage to the current app on a shared daemon; resolving must NOT throw here (list/load are
  * documented to work headless), so a missing/unknown session degrades to the global/legacy store.
+ *
+ * Re-exported, not re-implemented. This file carried a BYTE-IDENTICAL second copy, and the two
+ * drifted the moment `ProjectId` was threaded: `session-root`'s copy returned the brand while this
+ * one returned `string`, so every flow tool importing from here was handed a widened value and lost
+ * the brand one line after it was minted. Exactly the weak-annotation failure the brand's own doc
+ * records against `RunStore.list()`.
  */
-export function sessionProjectId(deps, sessionId) {
-    try {
-        return deps.sessions.resolve(sessionId).projectId;
-    }
-    catch {
-        return undefined;
-    }
-}
+export { sessionProjectId } from '../../memory/project/session-root.js';

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,8 +1,26 @@
-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';
 import { type Drift, type FlowFile, type FlowStep, type FlowStepResult } from '@reticlehq/core';
+/**
+ * The document this replay was driving went away mid-run.
+ *
+ * Almost always because the replay itself navigated it — a `startPath` goto, or a step that clicks a
+ * link. The steps already in hand are real answers from the document that WAS there, so they travel
+ * with the error; the step that was in flight has no answer at all and is deliberately absent.
+ * Synthesising one would be a verdict about a page nobody observed, which is the one thing worse
+ * than returning no verdict.
+ *
+ * Typed rather than a message, because the caller has to tell it from a step that genuinely failed:
+ * one says the app is wrong, the other says we stopped watching.
+ */
+export declare class DocumentLostDuringReplay extends Error {
+    readonly steps: FlowStepResult[];
+    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.
  *
@@ -24,16 +42,23 @@ import { type Drift, type FlowFile, type FlowStep, type FlowStepResult } from '@
  * 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.
      *
@@ -50,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.
      *