@reticlehq/server 3.1.0 → 3.3.0

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

@@ -1,17 +1,44 @@
-import { mayResumeByReplayingPrefix, StepEffect } from '@reticlehq/core';
-import { Surface, formatStepAddress } from 'open-verification';
+import { formatStepAddress } from 'open-verification';
+import { assertsState, expectLabel, expectedElementTestid, withoutClauses } from '@reticlehq/core';
 import { span } from '../../trace.js';
-import { anchorLabel, expectElementDrift, resolveTestid, testidDrift } from './flow-anchor.js';
+import { anchorLabel, expectElementDrift, resolveTestid, testidDrift, ambiguousAnchorDrift, } from './flow-anchor.js';
 export { anchorLabel, componentLabel, componentQueryArgs, editDistance, expectElementDrift, nearestIsAmbiguous, nearestTestid, resolveQuery, testidDrift, } from './flow-anchor.js';
 import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
-import { AnchorKind, DriftReason, EventType, FlowStepTool, ReticleCommand, PredicateKind, } from '@reticlehq/core';
+import { AnchorKind, DriftReason, EventType, FlowStepTool, PredicateKind, } from '@reticlehq/core';
 import { asString, isConsequenceDrift } from '@reticlehq/core';
-import { replayActionArgs, ambiguousTestidNote } from './replay.js';
 import { anchorFieldName } from './fields/flow-secret-field.js';
 import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
-import { successToPredicate } from './flow-success.js';
-import { ReticleTool } from '@reticlehq/core';
+import { inFlightRequestLabels } from '../../surface/tools/act/settle-in-flight.js';
+import { namedNetIsInFlight } from '@reticlehq/engine/evidence/unsettled.js';
+/** What a still-open named request means, in the drift's own words. */
+const IN_FLIGHT_AT_BUDGET_END = 'the request this step declared had not come back when the budget ended — it is still in flight, ' +
+    'so nothing here says the app failed. Raise the step timeout, or look at the endpoint';
+import { isDocumentGoneError, SESSION_DISCONNECTED_REASON, } from '../../portal/session/facts/session-replaced.js';
+import { actOnResolvedRef } from './flow-step-runners.js';
+/**
+ * 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 class DocumentLostDuringReplay extends Error {
+    steps;
+    atStep;
+    constructor(steps, atStep, lostTo) {
+        super(`the document was replaced while step ${String(atStep)} was running`, {
+            cause: lostTo,
+        });
+        this.steps = steps;
+        this.atStep = atStep;
+    }
+}
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * The route (pathname) currently in effect — the page a step runs on. Reads the latest ROUTE_CHANGE
@@ -76,7 +103,7 @@ function summarizeConsequence(events) {
     return parts.length > 0 ? parts.join('; ') : undefined;
 }
 /** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
-async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
+export async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
     const { refs, hint } = await resolveTestid(session, value, sleep);
     if (0 === refs.length) {
         return {
@@ -87,35 +114,50 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
             drift: testidDrift(value, hint),
         };
     }
-    const ref = refs[0] ?? '';
-    const note = refs.length > 1 ? ambiguousTestidNote(value) : undefined;
-    session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref, action: step.action ?? '' });
-    let act;
-    try {
-        act = await session.command(ReticleCommand.ACT, {
-            ref,
-            action: step.action ?? '',
-            // The field this step types into — from the anchor, so a redacted fill can be supplied from
-            // RETICLE_SECRET_<FIELD> without the flow carrying the secret. The testid runner used to pass
-            // the testid string here and the other two runners passed nothing, so a role-anchored login
-            // typed the literal placeholder.
-            args: replayActionArgs(step.args, confirmDangerous, anchorFieldName(step.anchor)),
-        });
-    }
-    finally {
-        session.finishAction?.();
+    /*
+     * More than one match is DRIFT, not a note on a passing step.
+     *
+     * This used to take refs[0], act, and return ok:true with `ambiguousTestidNote`. The verdict
+     * reads `drift` and `ok` and never reads a note, so "we guessed which element you meant" was
+     * indistinguishable from "it did what it did before" -- the one claim a replay makes.
+     *
+     * The action is NOT dispatched. Acting and then reporting drift would leave the app changed by
+     * a click nobody can attribute, which is worse than the ambiguity it reports.
+     */
+    if (refs.length > 1) {
+        return {
+            step: index,
+            tool: step.tool,
+            anchor: value,
+            ok: false,
+            drift: ambiguousAnchorDrift(value, refs.length),
+        };
     }
-    const result = { step: index, tool: step.tool, anchor: value, ok: act.ok };
-    if (!act.ok) {
-        result.error = act.error ?? 'command failed';
-        if (note !== undefined)
-            result.note = note;
+    const ref = refs[0] ?? '';
+    /*
+     * The same dispatch its siblings use, including the one re-resolve on a stale ref (2.3).
+     *
+     * This runner had its own inline copy and no retry, so a flow died on a re-render purely because
+     * the step was anchored by testid rather than by role — the locator deciding how sturdy the replay
+     * is, which is exactly backwards. testid is also the anchor `reticle init` steers people towards,
+     * so the kind most likely to appear in a real flow was the kind without the cure.
+     *
+     * The re-resolve keeps the ambiguity rule above: more than one match is drift, never a guess, so
+     * it hands back a ref only when the locator still names exactly one element.
+     */
+    const result = await actOnResolvedRef(session, step, index, value, ref, confirmDangerous, 
+    // The field this step types into — from the anchor, so a redacted fill can be supplied from
+    // RETICLE_SECRET_<FIELD> without the flow carrying the secret.
+    anchorFieldName(step.anchor), async () => {
+        const again = await resolveTestid(session, value, sleep);
+        return 1 === again.refs.length ? again.refs[0] : undefined;
+    });
+    if (!result.ok)
         return result;
-    }
     // assert the step's expect.element testid is present AFTER the action —
     // unless that testid was marked DYNAMIC (the LLM-output case), in which case its presence/content
     // is NOT asserted (only the action ran). The skip is scoped strictly to the dynamic set.
-    const expectTestid = step.expect?.element?.testid;
+    const expectTestid = expectedElementTestid(step.expect);
     if (expectTestid !== undefined && !dynamic.has(expectTestid)) {
         const expectRefs = await resolveTestid(session, expectTestid, sleep);
         if (0 === expectRefs.refs.length) {
@@ -131,8 +173,6 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
             };
         }
     }
-    if (note !== undefined)
-        result.note = note;
     return result;
 }
 /**
@@ -156,44 +196,63 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
  * 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 async function assertStepExpect(session, expect, dynamic, waitForSignal, timeoutMs, since) {
+export async function assertStepExpect(session, expect, waitForSignal, timeoutMs, since) {
     // A testid is already asserted against the live DOM by the step runner. A role/name locator is
     // not that path — stripping every element made a recorded `until` by button name a no-op, so a
     // flow that proved the control at capture time could not go red when it was gone.
-    const consequences = { ...expect };
-    if (undefined !== consequences.element?.testid) {
-        delete consequences.element;
-    }
-    const predicate = successToPredicate(consequences, dynamic);
+    /*
+     * Two clauses replay must not wait on, both for reasons that predate the tree.
+     *
+     * A testid element was already asserted against the live DOM by the step runner, so waiting on it
+     * again is a second read of a question already answered. A DYNAMIC testid is one whose content a
+     * model writes, and its presence is deliberately never asserted.
+     *
+     * A role/name locator is NEITHER, and stripping every element made a recorded `until` by button
+     * name a no-op — a flow that proved the control at capture time could not go red when it was gone.
+     *
+     * The DYNAMIC set used to be a parameter here and was dead the whole time: the testid was deleted
+     * from the expectation on the line above, and the only thing that read the set asked for the
+     * testid that had just been removed. One production caller was already passing an empty set. The
+     * rule is real and still applies to the flow's SUCCESS oracle, which is where it lives.
+     */
+    const predicate = withoutClauses(expect, 
+    // Only a PRESENT testid is the runner's to check; an absence stays here or nobody checks it.
+    (clause) => PredicateKind.ELEMENT === clause.kind &&
+        clause.query.testid !== undefined &&
+        true !== clause.absent);
     if (predicate === undefined)
         return undefined;
     const verdict = await waitForSignal(session, predicate, timeoutMs, since);
     if (verdict.pass)
         return undefined;
+    // The wait ended because the page stopped being observable, not because the consequence failed:
+    // the same fact as a command the dying socket rejected, so it takes the same path (the replay loop
+    // reports a lost document). As a drift, a socket that blinked for 26ms read as the app's defect.
+    if (true === verdict.observationLost)
+        throw new Error(SESSION_DISCONNECTED_REASON);
+    // A request the step NAMED that had not come back yet is a blind spot, not an assertion the app
+    // failed. The live verdict path already draws this line (namedNetIsInFlight); replay read the
+    // same window and never asked, so a slow endpoint was reported as a consequence that never fired.
+    // An unrelated open request does not pardon a named URL that never started — matching decides it.
+    const openRequests = assertsState(expect)
+        ? []
+        : inFlightRequestLabels(session.eventsSince(since), session.url, session.background);
+    const namedInFlight = namedNetIsInFlight(predicate, openRequests);
     return {
         // The store case keeps its own kind because heal and the run report branch on it; everything
         // else is a consequence that did not hold, and the reason carries observed-vs-expected.
-        reasonKind: expect.state !== undefined ? DriftReason.STATE_MISMATCH : DriftReason.SIGNAL_NOT_OBSERVED,
-        reason: verdict.failureReason ?? "the step's declared consequence did not hold",
+        reasonKind: assertsState(expect)
+            ? DriftReason.STATE_MISMATCH
+            : namedInFlight
+                ? DriftReason.NET_STILL_IN_FLIGHT
+                : DriftReason.SIGNAL_NOT_OBSERVED,
+        reason: namedInFlight
+            ? `${IN_FLIGHT_AT_BUDGET_END} (${openRequests.join(', ')})`
+            : (verdict.failureReason ?? "the step's declared consequence did not hold"),
         anchor: expectLabel(expect),
         nearest: null,
     };
 }
-/** Name the thing that was asserted, for the drift's `anchor` column. */
-function expectLabel(expect) {
-    if (expect.signal !== undefined)
-        return `signal:${expect.signal}`;
-    if (expect.net !== undefined)
-        return `net:${expect.net.urlContains ?? expect.net.method ?? '*'}`;
-    if (expect.state !== undefined)
-        return `state:${expect.state.path}`;
-    if (expect.console !== undefined)
-        return `console:${expect.console.level ?? '*'}`;
-    if (undefined !== expect.element) {
-        return expect.element.testid ?? expect.element.name ?? expect.element.role ?? 'element';
-    }
-    return 'expect';
-}
 /** Run one signal-anchored step: wait for the signal predicate, else drift (no nearest for signals). */
 async function runSignalStep(session, step, index, name, waitForSignal, signalTimeoutMs, since) {
     // Scope to THIS replay's floor, not the whole buffer.
@@ -221,40 +280,6 @@ async function runSignalStep(session, step, index, name, waitForSignal, signalTi
         },
     };
 }
-/**
- * Where to start REPORTING — and whether re-driving the steps before it is allowed at all.
- *
- * "Resume is nearly free, just re-run the prefix" is true of a browser and false on a subject that
- * COMMITS. Re-driving a prefix on a service re-sends every request before step N; on a device it
- * moves an arm again. Neither is a convenience, and a protocol that did it silently would be
- * defective rather than helpful.
- *
- * So the surface's declared profile decides, through the specification's own `resumeStrategy` rather
- * than a local reading of `replayPrefix`. A refusal resumes from 0 — the whole journey is reported,
- * nothing is skipped and nothing is silently repeated beyond what a plain replay already does.
- */
-function resumableFrom(options, steps) {
-    const asked = Math.max(0, options.from ?? 0);
-    if (0 === asked)
-        return 0;
-    if (!mayResumeByReplayingPrefix(options.surface ?? Surface.WEB))
-        return 0;
-    /*
-     * The surface answers for the SUBJECT; a step answers for itself.
-     *
-     * `web` is the permissive profile and it is right about a browser in general and wrong about the
-     * one click that charges a card. The surface check cannot see that, because the distinction is
-     * not a property of the realm — it is a property of the step. A flow that declares a prefix step
-     * as `commits` is saying: re-running me is not free, whatever the surface thinks.
-     *
-     * Refusing means resuming from 0, which is the same fail-safe the surface refusal already uses:
-     * the whole journey is reported and nothing is silently repeated beyond what a plain replay does.
-     * Absent effect is UNKNOWN and stays permissive — every flow recorded before this shipped has no
-     * effect on any step, and assuming the worst there would refuse every resume in existence.
-     */
-    const commitsInPrefix = steps.slice(0, asked).some((step) => StepEffect.COMMITS === step.effect);
-    return commitsInPrefix ? 0 : asked;
-}
 /**
  * Run an `invoke` step: load the named flow and replay it, or fail saying why.
  *
@@ -288,10 +313,7 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
             error: `cannot replay "${name}": it was not found, so this journey would report green having never run it`,
         };
     }
-    // `from` is deliberately dropped rather than forwarded: it is a REPORTING offset into the
-    // caller's own step list, and applying it inside a sub-journey would silently hide that
-    // journey's first steps for a reason that has nothing to do with it.
-    const { from: _ignored, ...carried } = options;
+    const carried = options;
     const nested = await replayFlow(session, sub, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, {
         ...carried,
         via: [{ flow: flow.name, step: index }, ...via],
@@ -309,16 +331,6 @@ async function runInvokeStep(session, flow, step, index, waitForSignal, signalTi
 }
 export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs, confirmDangerous = false, sleep = realSleep, options = {}) {
     const results = [];
-    /*
-     * Where to start REPORTING. Everything before it still runs.
-     *
-     * Resuming is re-driving the prefix, not restoring state: there is no way to put an app back
-     * where it was without driving it there, and at a measured ~27ms a step there is no reason to
-     * try. So the prefix executes silently and the caller sees the journey from the point it asked
-     * about -- which is what makes "fix the break, resume, find the next one" a loop rather than a
-     * full re-read each time.
-     */
-    const from = resumableFrom(options, flow.steps);
     // testids whose region is LLM-dynamic — their expect-presence is NOT asserted.
     const dynamic = new Set((flow.dynamic ?? [])
         .filter((a) => a.kind === AnchorKind.TESTID)
@@ -332,108 +344,114 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     // wait for the slowest step would trade a false red for a slow suite. See FlowStep.timeoutMs.
     const waitFor = (step) => step.timeoutMs ?? flow.signalTimeoutMs ?? signalTimeoutMs;
     let index = 0;
-    for (const step of flow.steps) {
-        if (step.invoke !== undefined) {
-            results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options));
-            const last = results[results.length - 1];
-            if (last !== undefined && false === last.ok)
-                break;
-            index += 1;
-            continue;
-        }
-        const label = anchorLabel(step.anchor);
-        // The page this step runs on (the journey's "which page") — captured before the action.
-        const page = currentRoute(session);
-        // Event-time floor so the consequence reflects only THIS step's aftermath, not prior steps'.
-        const cursorBefore = session.elapsed();
-        const subSteps = step.steps;
-        // Traced per step, so a slow replay says WHICH step and which anchor kind spent the time. The
-        // per-step `durationMs` below is what the agent gets back; this is what a developer profiling
-        // the replay engine gets, nested under the tool call with the browser round-trips beneath it.
-        const result = await span('flow.step', { index, anchor: step.anchor.kind, label }, async () => {
-            if (isDegradedAnchor(step.anchor)) {
-                // Never QUERY the sentinel — it marks "no anchor was determined", not an element to find.
-                return degradedStepResult(step, index, label);
-            }
-            if (subSteps !== undefined && subSteps.length > 0) {
-                return runSequenceStep(session, step, index, subSteps, confirmDangerous, sleep, dynamic);
-            }
-            if (step.anchor.kind === AnchorKind.SIGNAL) {
-                return runSignalStep(session, step, index, label, waitForSignal, waitFor(step), replayFloor);
-            }
-            if (step.anchor.kind === AnchorKind.COMPONENT) {
-                return runComponentStep(session, step, index, step.anchor, confirmDangerous, sleep);
+    try {
+        for (const step of flow.steps) {
+            if (step.invoke !== undefined) {
+                results.push(await runInvokeStep(session, flow, step, index, waitForSignal, signalTimeoutMs, confirmDangerous, sleep, options));
+                const last = results[results.length - 1];
+                if (last !== undefined && false === last.ok)
+                    break;
+                index += 1;
+                continue;
             }
-            if (step.anchor.kind === AnchorKind.ROLE && step.anchor.name !== undefined) {
-                // A NAMED role anchor addresses one element. The nameless one is the degraded placeholder
-                // and keeps its old path, where it fails legibly rather than querying a role as a testid.
-                return runRoleStep(session, step, index, step.anchor, confirmDangerous, sleep);
+            const label = anchorLabel(step.anchor);
+            // The page this step runs on (the journey's "which page") — captured before the action.
+            const page = currentRoute(session);
+            // Event-time floor so the consequence reflects only THIS step's aftermath, not prior steps'.
+            const cursorBefore = session.elapsed();
+            const subSteps = step.steps;
+            // Traced per step, so a slow replay says WHICH step and which anchor kind spent the time. The
+            // per-step `durationMs` below is what the agent gets back; this is what a developer profiling
+            // the replay engine gets, nested under the tool call with the browser round-trips beneath it.
+            const result = await span('flow.step', { index, anchor: step.anchor.kind, label }, async () => {
+                if (isDegradedAnchor(step.anchor)) {
+                    // Never QUERY the sentinel — it marks "no anchor was determined", not an element to find.
+                    return degradedStepResult(step, index, label);
+                }
+                if (subSteps !== undefined && subSteps.length > 0) {
+                    return runSequenceStep(session, step, index, subSteps, confirmDangerous, sleep, dynamic);
+                }
+                if (step.anchor.kind === AnchorKind.SIGNAL) {
+                    return runSignalStep(session, step, index, label, waitForSignal, waitFor(step), replayFloor);
+                }
+                if (step.anchor.kind === AnchorKind.COMPONENT) {
+                    return runComponentStep(session, step, index, step.anchor, confirmDangerous, sleep);
+                }
+                if (step.anchor.kind === AnchorKind.ROLE && step.anchor.name !== undefined) {
+                    // A NAMED role anchor addresses one element. The nameless one is the degraded placeholder
+                    // and keeps its old path, where it fails legibly rather than querying a role as a testid.
+                    return runRoleStep(session, step, index, step.anchor, confirmDangerous, sleep);
+                }
+                return runTestidStep(session, step, index, label, dynamic, confirmDangerous, sleep);
+            });
+            // Once the anchor resolved and the action ran, the step's own expect is evaluated — signal, net,
+            // console and store truth alike — deterministically, in the same cheap replay loop, with no LLM.
+            /*
+             * The step's own expect, and then every sub-step's.
+             *
+             * `classifyFlowAssertions` already walks act_sequence sub-steps and counts an expect on either
+             * level, and states the invariant plainly: this and what replay enforces must move together, or
+             * "the difference is a false green or a lost verification". Enforcing only the top level was
+             * that difference -- a sequence whose sub-step declared a consequence was GRADED asserted and
+             * checked by nothing, so it could not go red while wearing the grade that says it could.
+             *
+             * WEAKER THAN THE LIVE PATH, and deliberately so rather than silently. A recorded sequence is
+             * dispatched as ONE batched command, so there are no per-sub-step cursors to open a window with
+             * -- every sub-step expect is evaluated against the window the whole sequence opened, which
+             * means sub-step three's claim can be satisfied by sub-step one's consequence. The live
+             * `act_sequence` path takes a cursor before each dispatch and does not have this. Narrowing it
+             * here means dispatching sub-steps individually on replay, which is a behaviour change to the
+             * replay path and belongs in its own commit.
+             */
+            const declared = [step.expect, ...(step.steps ?? []).map((sub) => sub.expect)].filter((expectation) => expectation !== undefined);
+            for (const expectation of declared) {
+                if (!result.ok || result.drift !== undefined)
+                    break;
+                const expectDrift = await assertStepExpect(session, expectation, waitForSignal, waitFor(step), cursorBefore);
+                if (expectDrift !== undefined) {
+                    result.ok = false;
+                    result.drift = expectDrift;
+                }
             }
-            return runTestidStep(session, step, index, label, dynamic, confirmDangerous, sleep);
-        });
-        // Once the anchor resolved and the action ran, the step's own expect is evaluated — signal, net,
-        // console and store truth alike — deterministically, in the same cheap replay loop, with no LLM.
-        /*
-         * The step's own expect, and then every sub-step's.
-         *
-         * `classifyFlowAssertions` already walks act_sequence sub-steps and counts an expect on either
-         * level, and states the invariant plainly: this and what replay enforces must move together, or
-         * "the difference is a false green or a lost verification". Enforcing only the top level was
-         * that difference -- a sequence whose sub-step declared a consequence was GRADED asserted and
-         * checked by nothing, so it could not go red while wearing the grade that says it could.
-         *
-         * WEAKER THAN THE LIVE PATH, and deliberately so rather than silently. A recorded sequence is
-         * dispatched as ONE batched command, so there are no per-sub-step cursors to open a window with
-         * -- every sub-step expect is evaluated against the window the whole sequence opened, which
-         * means sub-step three's claim can be satisfied by sub-step one's consequence. The live
-         * `act_sequence` path takes a cursor before each dispatch and does not have this. Narrowing it
-         * here means dispatching sub-steps individually on replay, which is a behaviour change to the
-         * replay path and belongs in its own commit.
-         */
-        const declared = [step.expect, ...(step.steps ?? []).map((sub) => sub.expect)].filter((expectation) => expectation !== undefined);
-        for (const expectation of declared) {
-            if (!result.ok || result.drift !== undefined)
+            if (page !== undefined)
+                result.page = page;
+            const windowEvents = session.eventsSince(cursorBefore).filter((e) => e.t >= cursorBefore);
+            const consequence = summarizeConsequence(windowEvents);
+            if (consequence !== undefined)
+                result.consequence = consequence;
+            // Per-step wall time is NOT shipped: it is `window.until - window.since`, computed from two numbers
+            // the next line already puts in the same object, under the same emission condition. A step used to
+            // carry the subtraction AND both operands, on every step of every replay.
+            const cursorAfter = session.elapsed();
+            // ONE builder, shared with the live act path, so a driven step and a replayed one describe what
+            // happened in identical words rather than in two vocabularies that agree by coincidence.
+            Object.assign(result, stepEffect(windowEvents, { since: cursorBefore, until: cursorAfter }));
+            /*
+             * A prefix step is setup and is not reported -- UNLESS it failed.
+             *
+             * A failure there means the resume never reached the step it was asked to resume from, and the
+             * run did not start where the caller will read it as having started. Swallowing it would turn
+             * "I could not get there" into "I got there and it was fine".
+             */
+            // `tool` is dropped HERE rather than at the ten places that set it, so a new step runner cannot
+            // forget the rule and quietly re-introduce the cost. Spelled out only when it is NOT the default.
+            if (FlowStepTool.ACT === result.tool)
+                delete result.tool;
+            results.push(result);
+            // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the
+            // step left it, so the next step is as meaningful as it was going to be. Anything else halts.
+            const sweepPast = true === options.sweep &&
+                result.drift !== undefined &&
+                isConsequenceDrift(result.drift.reasonKind);
+            if (!sweepPast && (result.drift !== undefined || !result.ok))
                 break;
-            const expectDrift = await assertStepExpect(session, expectation, dynamic, waitForSignal, waitFor(step), cursorBefore);
-            if (expectDrift !== undefined) {
-                result.ok = false;
-                result.drift = expectDrift;
-            }
+            index += 1;
         }
-        if (page !== undefined)
-            result.page = page;
-        const windowEvents = session.eventsSince(cursorBefore).filter((e) => e.t >= cursorBefore);
-        const consequence = summarizeConsequence(windowEvents);
-        if (consequence !== undefined)
-            result.consequence = consequence;
-        // Per-step wall time is NOT shipped: it is `window.until - window.since`, computed from two numbers
-        // the next line already puts in the same object, under the same emission condition. A step used to
-        // carry the subtraction AND both operands, on every step of every replay.
-        const cursorAfter = session.elapsed();
-        // ONE builder, shared with the live act path, so a driven step and a replayed one describe what
-        // happened in identical words rather than in two vocabularies that agree by coincidence.
-        Object.assign(result, stepEffect(windowEvents, { since: cursorBefore, until: cursorAfter }));
-        /*
-         * A prefix step is setup and is not reported -- UNLESS it failed.
-         *
-         * A failure there means the resume never reached the step it was asked to resume from, and the
-         * run did not start where the caller will read it as having started. Swallowing it would turn
-         * "I could not get there" into "I got there and it was fine".
-         */
-        // `tool` is dropped HERE rather than at the ten places that set it, so a new step runner cannot
-        // forget the rule and quietly re-introduce the cost. Spelled out only when it is NOT the default.
-        if (FlowStepTool.ACT === result.tool)
-            delete result.tool;
-        if (index >= from || !result.ok || result.drift !== undefined)
-            results.push(result);
-        // Under `sweep`, a failure whose action still RAN does not stop the run — the page is where the
-        // step left it, so the next step is as meaningful as it was going to be. Anything else halts.
-        const sweepPast = true === options.sweep &&
-            result.drift !== undefined &&
-            isConsequenceDrift(result.drift.reasonKind);
-        if (!sweepPast && (result.drift !== undefined || !result.ok))
-            break;
-        index += 1;
+    }
+    catch (error) {
+        if (!isDocumentGoneError(error))
+            throw error;
+        throw new DocumentLostDuringReplay(results, index, error);
     }
     return results;
 }

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

@@ -1,4 +1,5 @@
 import { FlowErrorCode } from '@reticlehq/core';
+import { type ProjectId } from '@reticlehq/core';
 /** Discriminated result so callers never branch on free strings. */
 export type FlowResult<T> = {
     ok: true;
@@ -14,5 +15,21 @@ export type FlowResult<T> = {
  * An unsafe or absent value collapses to `undefined` — the flat, global store — so a malformed id
  * can never escape `.reticle/flows/`. The store defends the disk boundary itself rather than
  * trusting whatever arrived in a session's HELLO.
+ *
+ * Held to one SEGMENT, not to a flow name. A project id becomes a DIRECTORY; a flow name is an
+ * ADDRESS, and since composites began naming sub-journeys as `onboarding/signup` its pattern has
+ * allowed separators. Validating a directory name with the address guard let a page choose how deep
+ * under `.reticle/` Reticle wrote — not an escape, since neither pattern admits `..` or a leading
+ * separator, but the page naming directories all the same.
+ *
+ * A FILTER, not a mint. It answers "is this id safe on disk", never "is this id a project" — a
+ * session id passes `SAFE_SEGMENT_PATTERN` just as cleanly, so minting the brand here would launder
+ * the exact confusion `ProjectId` exists to catch. The brand arrives already attached, from HELLO
+ * or from `.reticle.json`; see `ProjectId` in core.
+ *
+ * The narrowing said it out loud and nobody was listening: `isValidFlowName` narrows its argument to
+ * `FlowName`, for a value that is a project. The sibling guards for session and run ids have used
+ * the segment pattern since that widening, and `id-guards-are-not-flow-names.test.ts` exists to
+ * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
-export declare const safeProjectId: (projectId?: string) => string | undefined;
+export declare const safeProjectId: (projectId?: ProjectId) => ProjectId | undefined;

package/dist/language/flows/flow-result.js

@@ -1,10 +1,26 @@
 import { FlowErrorCode } from '@reticlehq/core';
-import { isValidFlowName } from '../../memory/project/dir/reticle-dir.js';
+import { SAFE_SEGMENT_PATTERN } from '@reticlehq/core';
 /**
  * A project id that is safe to put in a path, or nothing.
  *
  * An unsafe or absent value collapses to `undefined` — the flat, global store — so a malformed id
  * can never escape `.reticle/flows/`. The store defends the disk boundary itself rather than
  * trusting whatever arrived in a session's HELLO.
+ *
+ * Held to one SEGMENT, not to a flow name. A project id becomes a DIRECTORY; a flow name is an
+ * ADDRESS, and since composites began naming sub-journeys as `onboarding/signup` its pattern has
+ * allowed separators. Validating a directory name with the address guard let a page choose how deep
+ * under `.reticle/` Reticle wrote — not an escape, since neither pattern admits `..` or a leading
+ * separator, but the page naming directories all the same.
+ *
+ * A FILTER, not a mint. It answers "is this id safe on disk", never "is this id a project" — a
+ * session id passes `SAFE_SEGMENT_PATTERN` just as cleanly, so minting the brand here would launder
+ * the exact confusion `ProjectId` exists to catch. The brand arrives already attached, from HELLO
+ * or from `.reticle.json`; see `ProjectId` in core.
+ *
+ * The narrowing said it out loud and nobody was listening: `isValidFlowName` narrows its argument to
+ * `FlowName`, for a value that is a project. The sibling guards for session and run ids have used
+ * the segment pattern since that widening, and `id-guards-are-not-flow-names.test.ts` exists to
+ * hold the distinction — this is the fourth id joined into a path, and the one that file missed.
  */
-export const safeProjectId = (projectId) => projectId !== undefined && isValidFlowName(projectId) ? projectId : undefined;
+export const safeProjectId = (projectId) => projectId !== undefined && SAFE_SEGMENT_PATTERN.test(projectId) ? projectId : undefined;

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

@@ -1,17 +1,26 @@
-/**
- * How one anchored step is turned into a live action.
- *
- * Split out of flow-replay.ts when adding the role+name runner pushed that file past the size cap.
- * These three share one shape — resolve an anchor to a ref, then dispatch — and the sharing is the
- * point: the action window must open and close identically no matter which anchor found the element,
- * or a step's events land in the wrong window depending on how it was addressed.
- */
-import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult } from '@reticlehq/core';
+import { AnchorKind, type FlowAnchor, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
 import type { FlowReplaySession, Sleep } from './flow-replay-types.js';
 export declare function runRoleStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.ROLE;
 }>, confirmDangerous: boolean, sleep: Sleep): Promise<FlowStepResult>;
-export declare function replayDestructiveActionHint(rawError: string): string;
+/**
+ * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
+ * including the action window, whose open/close must not depend on which anchor found the element.
+ */
+export declare function actOnResolvedRef(session: FlowReplaySession, step: FlowStep, index: number, label: string, ref: string, confirmDangerous: boolean, 
+/**
+ * The field name a redacted fill is supplied under, from `anchorFieldName` — the SAME function
+ * redaction uses to decide what to hide. Without it a role-anchored secret is redacted at save
+ * and looked up at replay under no name at all, so the flow types the placeholder into the form.
+ */
+field?: string, 
+/**
+ * Resolve the anchor again. Supplied by the caller because only it knows how this step's anchor is
+ * found, and the retry below is worthless without it: re-dispatching the SAME dead ref fails
+ * identically. What changed between the two attempts is the DOM, so the locator has to be run
+ * against it again.
+ */
+reresolve?: () => Promise<string | undefined>): Promise<FlowStepResult>;
 /** Run one component-anchored step: re-resolve via QUERY by:'component', ACT on the live ref, else drift. */
 export declare function runComponentStep(session: FlowReplaySession, step: FlowStep, index: number, anchor: Extract<FlowAnchor, {
     kind: typeof AnchorKind.COMPONENT;
@@ -39,6 +48,13 @@ export declare function degradedStepResult(step: FlowStep, index: number, label:
  * the step runner's own resolution asking the same thing of the same anchor.
  */
 export declare function anchorQueryArgs(anchor: FlowAnchor): Record<string, unknown> | null;
+/**
+ * The anchor as a PRECONDITION a flow file can store: "this element is on the page".
+ *
+ * What `requires` means for a flow that starts from state a page load discards, in the shape the
+ * flow's own `requires` holds. No tool writes `requires`, so the reset's hint hands over this line.
+ */
+export declare function anchorPrecondition(anchor: FlowAnchor): Predicate | 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