@reticlehq/server 3.7.0 → 3.8.1

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

@@ -5,11 +5,11 @@ import { ambiguityDrift, anchorLabel, expectElementDrift, reresolved, resolveTes
 export { nearestIsAmbiguous, nearestTestid, resolveQuery } from './flow-anchor.js';
 import { routeOfEvent, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { evalConsole } from '@reticlehq/engine/question/predicate/predicate-console.js';
-import { stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
+import { appScope, stepEffect } from '@reticlehq/engine/evidence/step-effect.js';
 import { AnchorKind, DriftReason, EventType, FlowStepTool, StepEffect, PredicateKind, ReplayStatus, } from '@reticlehq/core';
 import { asString, invokedFlowMissing, isConsequenceDrift } from '@reticlehq/core';
 import { anchorFieldName } from './fields/flow-secret-field.js';
-import { degradedStepResult, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
+import { degradedStepResult, isDocumentPressStep, isDegradedAnchor, runComponentStep, runRoleStep, runSequenceStep, } from './flow-step-runners.js';
 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. */
@@ -464,6 +464,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
                 continue;
             }
             const label = anchorLabel(step.anchor);
+            /** One sub-step's expect, over the window that sub-step opened. See runSequenceStep. */
+            const judgeSubStep = async (expectation, since) => (await assertStepExpect(session, expectation, waitForSignal, waitFor(step), since)) ??
+                lateConsoleDrift(expectation, session.eventsSince(since).filter((e) => e.t >= since));
             // 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'.
@@ -477,8 +480,12 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
                     // Never QUERY the sentinel — it marks "no anchor was determined", not an element to find.
                     return degradedStepResult(step, index, label);
                 }
+                if (subSteps === undefined && isDocumentPressStep(step)) {
+                    // A document-key press: dispatched with no ref, as it ran live (#1559).
+                    return actOnResolvedRef(session, step, index, label, '', confirmDangerous);
+                }
                 if (subSteps !== undefined && subSteps.length > 0) {
-                    return runSequenceStep(session, step, index, subSteps, confirmDangerous, sleep, dynamic);
+                    return runSequenceStep(session, step, index, subSteps, confirmDangerous, sleep, dynamic, index < from ? undefined : judgeSubStep);
                 }
                 if (step.anchor.kind === AnchorKind.SIGNAL) {
                     return runSignalStep(session, step, index, label, waitForSignal, waitFor(step), replayFloor);
@@ -496,25 +503,18 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             // 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.
+             * The step's own expect. A sub-step's expect was judged by the sequence runner, in the window
+             * of that sub-step, as the live `act_sequence` path judges it.
              *
-             * 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.
+             * `classifyFlowAssertions` walks act_sequence sub-steps and counts an expect on either level,
+             * and this and what replay enforces must move together, or "the difference is a false green or
+             * a lost verification". Judged here, at the end, a route expect on a middle sub-step failed
+             * once a later one moved on, and a later claim could pass on an earlier sub-step's request.
              */
             const declared = [step.expect, ...(step.steps ?? []).map((sub) => sub.expect)].filter((expectation) => expectation !== undefined);
+            const own = step.expect === undefined ? [] : [step.expect];
             // A setup step's consequence is not checked: it is re-driven to get somewhere, not to prove it.
-            const checked = index < from ? [] : declared;
+            const checked = index < from ? [] : own;
             for (const expectation of checked) {
                 if (!result.ok || result.drift !== undefined)
                     break;
@@ -551,7 +551,9 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
             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 }));
+            Object.assign(result, stepEffect(windowEvents, { since: cursorBefore, until: cursorAfter }, 
+            // A failure the step declared is its expected result, as it is on the live path.
+            { ...appScope(session), declared }));
             /*
              * A prefix step is setup and is not reported -- UNLESS it failed.
              *

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

@@ -0,0 +1,38 @@
+/**
+ * Whether a saved flow can replay at all, decided when it is saved, and what save changes so it can.
+ *
+ * Of 34 flows saved over one night, 5 replayed green. None of the misses was a defect in the app:
+ * a flow with no starting page, an anchor six buttons share, a live count ("Open 336") the next run
+ * cannot see again, or a step that WROTE real data each time it replayed. Each was found by a
+ * replay that drifted, never said when the flow was saved. This says it at save, and again with
+ * every suite verdict.
+ *
+ * Pure: a flow in, a flow or a report out. No IO, no clock.
+ */
+import { z } from 'zod';
+import { type FlowFile } from '@reticlehq/core';
+export declare const Replayable: {
+    readonly YES: "replayable";
+    readonly NO: "not_replayable";
+    /** It replays, but an expect names data the next run will not see again. */
+    readonly DATA_BOUND: "data_bound";
+};
+export type Replayable = (typeof Replayable)[keyof typeof Replayable];
+export interface Replayability {
+    status: Replayable;
+    /** One sentence for each reason, by step. Absent when there is nothing to say. */
+    why?: string[];
+    /** A step sends a write request, so a replay changes real data. */
+    writes?: true;
+}
+/**
+ * The flow as it is saved: a live count in a text expect becomes word-level where the step allows
+ * it, and a step whose expect names a write request is marked `writes`. A money check keeps its
+ * number exact, and the report then says the flow is bound to the data.
+ */
+export declare function readyForReplay(flow: FlowFile): FlowFile;
+/** Whether the flow can replay, and why not, by step. */
+export declare function replayability(flow: FlowFile): Replayability;
+/** The suite's argument and field for this, worded once. */
+export declare const SKIP_WRITES_ARG: z.ZodOptional<z.ZodBoolean>;
+export declare const REPLAYABILITY_OUTPUT: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;

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

@@ -0,0 +1,179 @@
+/**
+ * Whether a saved flow can replay at all, decided when it is saved, and what save changes so it can.
+ *
+ * Of 34 flows saved over one night, 5 replayed green. None of the misses was a defect in the app:
+ * a flow with no starting page, an anchor six buttons share, a live count ("Open 336") the next run
+ * cannot see again, or a step that WROTE real data each time it replayed. Each was found by a
+ * replay that drifted, never said when the flow was saved. This says it at save, and again with
+ * every suite verdict.
+ *
+ * Pure: a flow in, a flow or a report out. No IO, no clock.
+ */
+import { z } from 'zod';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, MUTATING_METHODS, PredicateKind, } from '@reticlehq/core';
+export const Replayable = {
+    YES: 'replayable',
+    NO: 'not_replayable',
+    /** It replays, but an expect names data the next run will not see again. */
+    DATA_BOUND: 'data_bound',
+};
+const NUMBER = /\d[\d,.]*/g;
+const HAS_NUMBER = /\d/;
+/** The words of a money check. Its number IS the claim, so it is never made word-level. */
+const MONEY = /credit|price|cost|charge|balance|paid|pay|invoice|refund|\$|€|£/i;
+/** A fragment kept as the words of a count: at least two letters. */
+const WORDS = /[A-Za-z]{2,}/;
+const NUMBER_PATTERN = '\\d[\\d,.]*';
+const MATCHES_PATTERN = 'matchesPattern';
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * A text expect with a live count, made word-level: the words stay exact, the number may change.
+ * Undefined when it cannot be: no words beside the number, a money check, or a `satisfies` already.
+ */
+function wordLevel(contains, money) {
+    if (money || MONEY.test(contains))
+        return undefined;
+    const words = contains
+        .split(NUMBER)
+        .map((part) => part.trim())
+        .filter((part) => WORDS.test(part))
+        .sort((a, b) => b.length - a.length)[0];
+    if (words === undefined)
+        return undefined;
+    const pattern = contains.split(NUMBER).map(escapeRegex).join(NUMBER_PATTERN);
+    return {
+        kind: PredicateKind.TEXT,
+        contains: words,
+        satisfies: { property: MATCHES_PATTERN, pattern },
+    };
+}
+function relax(predicate, money) {
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
+        return { ...predicate, predicates: predicate.predicates.map((p) => relax(p, money)) };
+    }
+    if (PredicateKind.TEXT === predicate.kind &&
+        predicate.satisfies === undefined &&
+        predicate.contains !== undefined &&
+        HAS_NUMBER.test(predicate.contains)) {
+        const relaxed = wordLevel(predicate.contains, money);
+        if (relaxed !== undefined) {
+            const { contains: _contains, ...rest } = predicate;
+            return { ...rest, ...relaxed };
+        }
+    }
+    return predicate;
+}
+/** Every leaf predicate under a composite, `not` included: a count is data-bound either way. */
+function leaves(predicate) {
+    if (predicate === undefined)
+        return [];
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
+        return predicate.predicates.flatMap(leaves);
+    }
+    if (PredicateKind.NOT === predicate.kind)
+        return leaves(predicate.predicate);
+    return [predicate];
+}
+/** The write requests an expect names, as "METHOD url". */
+function writesNamed(predicate) {
+    return leaves(predicate).flatMap((leaf) => PredicateKind.NET === leaf.kind &&
+        leaf.method !== undefined &&
+        MUTATING_METHODS.includes(leaf.method.toUpperCase())
+        ? [`${leaf.method.toUpperCase()} ${leaf.urlContains ?? ''}`.trim()]
+        : []);
+}
+/** The live data an expect names: a number in text, in an element's name or text, or in state. */
+function liveData(predicate) {
+    return leaves(predicate).flatMap((leaf) => {
+        if (PredicateKind.TEXT === leaf.kind && leaf.satisfies === undefined) {
+            return leaf.contains !== undefined && HAS_NUMBER.test(leaf.contains) ? [leaf.contains] : [];
+        }
+        if (PredicateKind.ELEMENT === leaf.kind) {
+            return [leaf.query.name, leaf.query.text].filter((value) => value !== undefined && HAS_NUMBER.test(value));
+        }
+        if (PredicateKind.STATE === leaf.kind && 'number' === typeof leaf.equals) {
+            return [`${leaf.path} = ${String(leaf.equals)}`];
+        }
+        return [];
+    });
+}
+function readyStep(step, money) {
+    const steps = step.steps?.map((sub) => readyStep(sub, money));
+    const expect = step.expect === undefined ? undefined : relax(step.expect, money);
+    const writes = true === step.writes ||
+        0 < writesNamed(step.expect).length ||
+        true === steps?.some((sub) => true === sub.writes);
+    return {
+        ...step,
+        ...(expect === undefined ? {} : { expect }),
+        ...(steps === undefined ? {} : { steps }),
+        ...(writes ? { writes: true } : {}),
+    };
+}
+/**
+ * The flow as it is saved: a live count in a text expect becomes word-level where the step allows
+ * it, and a step whose expect names a write request is marked `writes`. A money check keeps its
+ * number exact, and the report then says the flow is bound to the data.
+ */
+export function readyForReplay(flow) {
+    const money = MONEY.test(flow.intent ?? '');
+    return { ...flow, steps: flow.steps.map((step) => readyStep(step, money)) };
+}
+function addressed(steps, prefix = '') {
+    return steps.flatMap((step, i) => {
+        const at = `${prefix}${String(i + 1)}`;
+        return [{ at, step }, ...addressed(step.steps ?? [], `${at}.`)];
+    });
+}
+/** Whether the flow can replay, and why not, by step. */
+export function replayability(flow) {
+    const blocked = [];
+    const bound = [];
+    const writes = [];
+    if (flow.startPath === undefined || '' === flow.startPath) {
+        blocked.push('no starting page was recorded, so a replay starts wherever the tab is');
+    }
+    for (const { at, step } of addressed(flow.steps)) {
+        // A hand-written flow read without the schema can lack an anchor; it then says nothing here.
+        const anchor = step.anchor;
+        // A sequence's own anchor is a copy of a sub-step's; the sub-step answers for it.
+        const own = step.steps === undefined;
+        if (own &&
+            (true === step.degraded ||
+                (AnchorKind.ROLE === anchor?.kind && DEGRADED_ANCHOR_ROLE === anchor.role))) {
+            blocked.push(`step ${at} has no anchor a replay can find`);
+        }
+        else if (own && AnchorKind.TESTID === anchor?.kind && anchor.of !== undefined) {
+            blocked.push(`step ${at} anchors on test id '${anchor.value}', which ${String(anchor.of)} elements share`);
+        }
+        if (own &&
+            AnchorKind.ROLE === anchor?.kind &&
+            anchor.name !== undefined &&
+            HAS_NUMBER.test(anchor.name)) {
+            bound.push(`step ${at} acts on a control named '${anchor.name}', a live count`);
+        }
+        for (const data of liveData(step.expect))
+            bound.push(`step ${at} expects '${data}', live data`);
+        for (const write of own ? writesNamed(step.expect) : [])
+            writes.push(`step ${at} sends ${write}`);
+        if (own && true === step.writes && 0 === writesNamed(step.expect).length) {
+            writes.push(`step ${at} sent a write request when it was recorded`);
+        }
+    }
+    const why = [...blocked, ...bound, ...writes];
+    const status = 0 < blocked.length ? Replayable.NO : 0 < bound.length ? Replayable.DATA_BOUND : Replayable.YES;
+    return {
+        status,
+        ...(0 === why.length ? {} : { why }),
+        ...(0 === writes.length ? {} : { writes: true }),
+    };
+}
+/** The suite's argument and field for this, worded once. */
+export const SKIP_WRITES_ARG = z
+    .boolean()
+    .optional()
+    .describe('Certify without changing data: hold back every flow with a step that sends a write request (POST, PUT, PATCH, DELETE), and name them in `skippedWrites`.');
+export const REPLAYABILITY_OUTPUT = z
+    .array(z.unknown())
+    .optional()
+    .describe('Each flow that cannot replay as saved: not_replayable (no starting page, an anchor no replay can find or several elements share) or data_bound (live data in an expect), and writes when a step sends a write request. A drift on such a flow is the flow, not the app.');

package/dist/language/flows/flow-start-path.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Replay's arrival at a flow's start page: navigate (or reload) before step 1, wait for the session
+ * the SDK reconnects as, and say what happened when it does not.
+ */
+import { type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent, type StartPageWait } from '@reticlehq/core';
+import type { ArrivalClock } from '../../surface/tools/act/navigation/navigate-arrival.js';
+import type { SessionManager } from '../../portal/session/session-manager.js';
+import type { Session } from '../../portal/session/session.js';
+/** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
+interface StartPathSession {
+    url?: string;
+    eventsSince(cursor: number): ReticleEvent[];
+}
+/**
+ * When a flow records the page its journey started on (`startPath`) and the tab is currently on a
+ * different route, step 1 drifts for a reason that has nothing to do with the app regressing — the
+ * anchor simply isn't on this page yet. Detect that so the decision says "navigate there first"
+ * instead of a mystifying "a step no longer matches". Returns undefined when the routes agree or the
+ * current route is unobservable — never a false alarm. Replay normally never gets here on a
+ * wrong page (arriveAtStartPath navigates before step 1); this is the fallback when navigation
+ * was refused. A page that never reconnected is reported as unverifiable before step 1.
+ */
+export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
+/** What replay learned on its way to step 0. Both fields absent = the tab was left exactly as it was. */
+export interface StartPathArrival {
+    /** The successor session replay must continue on. Absent when nothing was navigated, or arrival timed out. */
+    session?: Session;
+    /** Set when the RESET itself is why step 1 cannot start — the reason a step-1 red is not drift. */
+    resetCost?: string;
+    /** Set when the tab was sent away and nothing reconnected: the old handle will never answer (#1129). */
+    lost?: string;
+    /** A live successor arrived on a different route, so replay must not use the dead old handle. */
+    redirected?: string;
+    /** Set when the page's loading kept replay waiting past the step budget. */
+    wait?: StartPageWait;
+}
+/** The replay result, with how long replay waited for its start page when that went past the budget. */
+export declare function withStartPageWait<R extends FlowReplayResult>(result: R, arrival: StartPathArrival): R;
+/**
+ * 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 current route is unobservable, or navigation is refused,
+ * replay proceeds on the connected session. A missing successor stops before step 1; a redirect
+ * continues on the live successor with a route-specific hint.
+ */
+export declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
+    id: string;
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock, 
+/** Whether the tab is still loading. Replay passes one for a pool lease, the only tab it can ask. */
+stillLoading?: () => Promise<boolean>, loadingCapMs?: number): Promise<StartPathArrival>;
+/**
+ * Send a tab somewhere and wait for the session that comes back.
+ *
+ * A navigation is a full page load: the session that issued it DIES and a successor connects with a
+ * new id. Every caller therefore has to wait for that successor rather than reuse the handle it
+ * already holds, and getting this wrong does not error — it leaves the caller talking to a session
+ * that will never answer again.
+ *
+ * Extracted so there is ONE of these rather than one per caller. `arriveAtStartPath` decides WHETHER
+ * 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.
+ */
+/**
+ * How a navigate ended: target, redirect, refusal (untouched tab), or no successor. `wait` is set
+ * when the page's loading earned it time past the budget.
+ */
+export type NavigateOutcome = {
+    kind: 'arrived';
+    session: Session;
+    wait?: StartPageWait;
+} | {
+    kind: 'redirected';
+    session: Session;
+    wait?: StartPageWait;
+} | {
+    kind: 'refused';
+} | {
+    kind: 'lost';
+    waitedMs: number;
+    stillLoading: boolean;
+    wait?: StartPageWait;
+};
+export declare function navigateAndAwait(sessions: SessionManager, session: {
+    id: string;
+    /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
+    url?: string;
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}, destination: string, expectedPath: string, timeoutMs: number, clock?: ArrivalClock, 
+/** True when the destination is the page we are already on — see `arrivedSuccessor`. */
+isReload?: boolean, 
+/** Whether the navigated page is still loading; absent when it cannot be asked. */
+stillLoading?: () => Promise<boolean>, loadingCapMs?: number): Promise<NavigateOutcome>;
+export {};