@reticlehq/server 3.5.0 → 3.7.0

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

@@ -35,8 +35,13 @@ export function editDistance(a, b) {
 }
 /**
  * The closest present testid to a missing one, by case-insensitive edit distance, ties broken
- * by shortest length then lexically. Returns null only when nothing is present — so a drift
- * record always names a fix when one exists ("whose fault is it": here is the closest survivor).
+ * by shortest length then lexically — when it is close enough to be a rename. Null when nothing
+ * present is, so a drift record names a fix only when one plausibly exists.
+ *
+ * It used to name the closest survivor however far away it was. A replay that started signed out
+ * missed `compose-prompt` on the login screen and advised rebinding it to `login-submit`: eleven
+ * edits away, a different control on a different page, offered as the fix. Half the longer name is
+ * the ceiling — `chat-send` → `chat-submit` and `checkout-btn` → `checkout-button` stay in.
  */
 export function nearestTestid(missing, present) {
     let best = null;
@@ -53,7 +58,9 @@ export function nearestTestid(missing, present) {
             bestDistance = distance;
         }
     }
-    return best;
+    if (null === best)
+        return null;
+    return bestDistance <= Math.max(missing.length, best.length) / 2 ? best : null;
 }
 /**
  * Bounded settle for anchor re-resolution. A testid step queries the live DOM for the anchor; if a
@@ -139,6 +146,34 @@ export function testidDrift(value, hint) {
         drift.ambiguous = true;
     return drift;
 }
+/**
+ * How an anchor is ADDRESSED — the sentence that names it, and the label a result row carries.
+ *
+ * Two different strings, and neither can be derived from the other: `value` is a raw testid for one
+ * anchor kind and a human-readable label for the others, so one sentence cannot name both. Calling a
+ * role anchor `testid "button "View result""` sends the reader to edit a locator that does not exist
+ * on that step, which is the same misdirection the drift reason exists to remove.
+ *
+ * Derived from the anchor rather than passed in by the caller. The first version of the role fix took
+ * a `described` argument and wrote `ambiguousAnchorDrift(label, n, \`role anchor ${label}\`)` — the
+ * same string twice, so the `anchor` field and the sentence could drift apart with nothing to catch
+ * it, and the next anchor kind would have had to remember the convention on its own.
+ */
+function anchorAddress(anchor) {
+    if (anchor.kind === AnchorKind.TESTID) {
+        return { described: `testid "${anchor.value}"`, label: anchor.value };
+    }
+    if (anchor.kind === AnchorKind.ROLE) {
+        // Kind named explicitly: `button "View result"` alone reads as a testid that happens to contain
+        // a space, and the reader would go looking for a locator nothing on the step declares.
+        const label = `${anchor.role} "${String(anchor.name)}"`;
+        return { described: `role anchor ${label}`, label };
+    }
+    // A component needs no such qualifier: `componentLabel` already answers
+    // `NewDeployButton@Deployments.tsx:107`, which no reader mistakes for a testid.
+    const label = anchor.kind === AnchorKind.COMPONENT ? componentLabel(anchor) : anchorLabel(anchor);
+    return { described: `anchor ${label}`, label };
+}
 /**
  * Build the drift for a step whose anchor matched MORE THAN ONE live element.
  *
@@ -149,16 +184,73 @@ export function testidDrift(value, hint) {
  * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
  * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
  * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ *
+ * Private: callers reach it through `ambiguityDrift`, which is the RULE rather than the record.
+ * Exported, it had three call sites and a fourth anchor kind that never called it at all.
  */
-export function ambiguousAnchorDrift(value, matches) {
+function ambiguousAnchorDrift(anchor, matches) {
+    const { described, label } = anchorAddress(anchor);
     return {
         reasonKind: DriftReason.ANCHOR_AMBIGUOUS,
-        reason: `testid "${value}" matched ${String(matches)} live elements — which one the recording meant is not decidable; anchor this step to something unique`,
-        anchor: value,
+        reason: `${described} matched ${String(matches)} live elements — which one the recording meant is not decidable; anchor this step to something unique`,
+        anchor: label,
         nearest: null,
         ambiguous: true,
     };
 }
+/**
+ * The ambiguity rule itself: an anchor that matched several live elements is DRIFT, never a guess.
+ *
+ * Returns null when the locator named zero or one element, so a runner reads it as
+ * `const drift = ambiguityDrift(anchor, refs); if (drift !== null) return { …, ok: false, drift };`
+ * and never has to reconstruct the record itself.
+ *
+ * ONE function, because three anchor kinds ask the same question and each used to answer for itself.
+ * testid was fixed first and role second, and role's fix was written as a copy of testid's — so "is
+ * this ambiguous" had two answers and COMPONENT had none at all. `runComponentStep` took `refs[0]`,
+ * dispatched and returned `ok: true` whenever `by:'component'` matched several elements, which is the
+ * ordinary case for a component rendered once per row (a table row's action button). The verdict
+ * reads `drift` and `ok` and nothing else, so that green was indistinguishable from a replay that did
+ * what it did before — the #1227 defect, one anchor kind over.
+ *
+ * The caller must not dispatch before checking. Acting and then reporting drift would leave the app
+ * changed by a click nobody can attribute, which is worse than the ambiguity it reports.
+ */
+export function ambiguityDrift(anchor, refs) {
+    return refs.length > 1 && refFor(anchor, refs) === undefined
+        ? ambiguousAnchorDrift(anchor, refs.length)
+        : null;
+}
+/**
+ * The one ref a step means: the only match, or the recorded position among same-named controls
+ * while the page still has exactly as many of them as when it was recorded. Otherwise undefined.
+ */
+export function refFor(anchor, refs) {
+    if (1 === refs.length)
+        return refs[0];
+    const { nth, of } = { ...anchor };
+    return 'number' === typeof nth && of === refs.length ? refs[nth] : undefined;
+}
+/**
+ * The anchor as the stale-ref RETRY found it: one ref to dispatch at, an ambiguity to report, or
+ * neither.
+ *
+ * The same rule as `ambiguityDrift`, one layer deeper, and shared for the same reason: a re-render
+ * can turn an unambiguous anchor into an ambiguous one between the two dispatches, and dispatching
+ * at the first of the new matches would re-make the guess the caller's own check exists to refuse —
+ * in a place the caller cannot see. Written once so the three runners cannot answer it differently,
+ * which is how the component runner came to have no answer at all.
+ *
+ * `refs[0]` is read only after `ambiguityDrift` has cleared the several-match case, so the only way
+ * it is undefined here is zero matches.
+ */
+export function reresolved(anchor, refs) {
+    const drift = ambiguityDrift(anchor, refs);
+    if (drift !== null)
+        return { drift };
+    const ref = refFor(anchor, refs);
+    return ref === undefined ? undefined : { ref };
+}
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

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

@@ -0,0 +1,15 @@
+import type { Contradiction, FlowStepResult } from '@reticlehq/core';
+/** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
+export declare const CROSS_STEP_INDEX = -1;
+/**
+ * The contradictions the whole-span pass found that no individual step could.
+ *
+ * A step's window closes when the step ends, so a request fired at step 2 and still unanswered at
+ * step 5 is invisible to every per-step window: step 2's closed before the answer came and step 5
+ * never saw it start. Re-running the detectors over the whole replay span finds those — and re-finds
+ * everything the steps already reported, which is what the subtraction is for. Reporting a finding
+ * twice teaches a reader that the count is noise.
+ *
+ * Exported for its own test: the subtraction is the whole rule, and it is pure.
+ */
+export declare function crossStepOnly(whole: readonly Contradiction[], steps: readonly FlowStepResult[]): Contradiction[];

package/dist/language/flows/flow-cross-step.js

@@ -0,0 +1,21 @@
+/** A contradiction's identity for de-duplication: the rule that fired, and the evidence it fired on. */
+function contradictionId(found) {
+    return `${found.kind}|${found.detail}`;
+}
+/** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
+export const CROSS_STEP_INDEX = -1;
+/**
+ * The contradictions the whole-span pass found that no individual step could.
+ *
+ * A step's window closes when the step ends, so a request fired at step 2 and still unanswered at
+ * step 5 is invisible to every per-step window: step 2's closed before the answer came and step 5
+ * never saw it start. Re-running the detectors over the whole replay span finds those — and re-finds
+ * everything the steps already reported, which is what the subtraction is for. Reporting a finding
+ * twice teaches a reader that the count is noise.
+ *
+ * Exported for its own test: the subtraction is the whole rule, and it is pure.
+ */
+export function crossStepOnly(whole, steps) {
+    const seen = new Set(steps.flatMap((step) => (step.contradictions ?? []).map(contradictionId)));
+    return whole.filter((found) => !seen.has(contradictionId(found)));
+}

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

@@ -49,4 +49,5 @@ export declare function dischargeFlowIntent(store: IntentStore, flow: FlowFile,
     verdictId: string;
     grade: string;
     at: number;
+    runId?: string;
 }): Promise<boolean>;

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

@@ -1,6 +1,12 @@
 import { type FlowFile, type FlowStep, type Predicate } from '@reticlehq/core';
 /** A short, stable identity for a journey's shape: its start page and its steps. */
 export declare function journeyFingerprint(flow: Pick<FlowFile, 'startPath' | 'steps'>): string;
+/**
+ * Whether `shorter` is `longer` driven with steps left out: same start, and its steps appear in
+ * `longer` in the same order. A re-drive that retried a step, or stopped one short, is the same
+ * journey; two flows that share only a name and a page are not.
+ */
+export declare function withinJourney(longer: Pick<FlowFile, 'startPath' | 'steps'>, shorter: Pick<FlowFile, 'startPath' | 'steps'>): boolean;
 /**
  * Fold two copies of one journey into one file.
  *

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

@@ -31,6 +31,26 @@ export function journeyFingerprint(flow) {
         .digest('hex')
         .slice(0, FINGERPRINT_LENGTH);
 }
+/**
+ * Whether `shorter` is `longer` driven with steps left out: same start, and its steps appear in
+ * `longer` in the same order. A re-drive that retried a step, or stopped one short, is the same
+ * journey; two flows that share only a name and a page are not.
+ */
+export function withinJourney(longer, shorter) {
+    if ((longer.startPath ?? null) !== (shorter.startPath ?? null))
+        return false;
+    const shapes = longer.steps.map((step) => JSON.stringify(stepShape(step)));
+    let at = 0;
+    for (const step of shorter.steps) {
+        const wanted = JSON.stringify(stepShape(step));
+        while (at < shapes.length && shapes[at] !== wanted)
+            at += 1;
+        if (at === shapes.length)
+            return false;
+        at += 1;
+    }
+    return true;
+}
 /** `kept` wins wherever it says something; `other` fills only what `kept` left unsaid. */
 function fillStep(kept, other) {
     if (other === undefined)

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

@@ -53,3 +53,7 @@ export declare function replayAndLearn(deps: ToolDeps,
 args: Record<string, unknown>): Promise<FlowReplayResult>;
 /** Write back the files a clean replay's anchors resolved to. Best-effort, as `persistLearning` is. */
 export declare function persistSources(deps: ToolDeps, args: Record<string, unknown>, sources: Parameters<typeof withLearnedSources>[1]): Promise<void>;
+/** A replay, under seeded perturbation when `seed` asks for one; the page is always put back. */
+export declare function replaySeededOrNot(deps: ToolDeps, args: Record<string, unknown>, 
+/** Where the perturbation port finds the page: the app's origin. */
+appUrl: string | undefined): Promise<FlowReplayResult>;

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

@@ -1,15 +1,13 @@
-import { asString } from '@reticlehq/core';
+import { runSavedFlow } from '../../hooks/driven-by.js';
+import { asNumber, asString, mutationTargetsFor, perturbationFor } from '@reticlehq/core';
+import { sessionPerturbationPort } from '../../surface/tools/lease-tools.js';
 import { flowsForSession } from './flow-store-for-session.js';
+import { safeSessionTarget } from '../../memory/project/session-root.js';
 import { replayNamedFlow } from './flow-replay-run.js';
 import { recordingSources, withLearnedSources } from './learned-sources.js';
 import { ReplayStatus } from '@reticlehq/core';
-function projectOf(deps, args) {
-    try {
-        return deps.sessions.resolve(asString(args['sessionId'])).projectId;
-    }
-    catch {
-        return undefined;
-    }
+function targetOf(deps, args) {
+    return safeSessionTarget(deps, asString(args['sessionId']));
 }
 /**
  * Write back what a replay taught the flow, once the replay has finished writing its own.
@@ -36,8 +34,8 @@ export async function persistLearning(deps, args, result) {
     if (0 === name.length)
         return result;
     try {
-        const projectId = projectOf(deps, args);
-        await flowsForSession(deps, projectId).flows.recordLearned(name, learned, projectId);
+        const target = targetOf(deps, args);
+        await flowsForSession(deps, target).flows.recordLearned(name, learned, target.projectId);
     }
     catch {
         // Bookkeeping only.
@@ -77,10 +75,11 @@ export async function replayAndLearn(deps,
  */
 args) {
     let recorded;
-    const result = await replayNamedFlow(deps, args, (session) => {
+    // A saved flow's steps were asked for by whoever recorded it: no outward gate on them.
+    const result = await runSavedFlow(() => replayNamedFlow(deps, args, (session) => {
         recorded = recordingSources(session);
         return recorded.session;
-    });
+    }));
     // Only a clean run teaches a file: a drifted step may have resolved to the wrong element.
     if (result.status === ReplayStatus.OK && recorded !== undefined && recorded.sources.size > 0) {
         await persistSources(deps, args, recorded.sources);
@@ -93,8 +92,9 @@ export async function persistSources(deps, args, sources) {
     if (0 === name.length)
         return;
     try {
-        const projectId = projectOf(deps, args);
-        const store = flowsForSession(deps, projectId).flows;
+        const target = targetOf(deps, args);
+        const { projectId } = target;
+        const store = flowsForSession(deps, target).flows;
         const current = await store.load(name, projectId);
         // Read first so a flow that already names every file is never rewritten.
         if (!current.ok || withLearnedSources(current.value, sources) === undefined)
@@ -105,3 +105,34 @@ export async function persistSources(deps, args, sources) {
         // Bookkeeping only.
     }
 }
+/** A replay, under seeded perturbation when `seed` asks for one; the page is always put back. */
+export async function replaySeededOrNot(deps, args, 
+/** Where the perturbation port finds the page: the app's origin. */
+appUrl) {
+    const seed = asNumber(args['seed']);
+    if (seed === undefined)
+        return await replayAndLearn(deps, args);
+    /*
+     * The targets are the endpoints the FLOW declared it depends on, so the perturbation lands on
+     * traffic the flow claims to care about. No declared endpoints means nothing to slow, and the
+     * replay runs clean rather than pretending a seed did something. `finally` is not tidiness: a
+     * page left slowed is damage the NEXT run inherits, as a mystery.
+     */
+    const target = targetOf(deps, args);
+    const loaded = await flowsForSession(deps, target)
+        .flows.load(asString(args['flowName']) ?? asString(args['flow']) ?? '', target.projectId)
+        .catch(() => null);
+    const targets = loaded !== null && loaded.ok ? mutationTargetsFor(loaded.value) : [];
+    const rules = perturbationFor(seed, targets);
+    const port = 0 === rules.length ? undefined : await sessionPerturbationPort(deps.realInput, appUrl);
+    if (port === undefined)
+        return replayAndLearn(deps, args);
+    try {
+        await port.slow(rules);
+        const replay = await runSavedFlow(() => replayNamedFlow(deps, args));
+        return { ...replay, perturbed: rules };
+    }
+    finally {
+        await port.clear().catch(() => undefined);
+    }
+}

package/dist/language/flows/flow-mutate-tools.js

@@ -15,7 +15,8 @@ import { MutationOutcome } from 'open-verification';
 import { z } from 'zod';
 import { sessionMutationPort } from '../../surface/tools/lease-tools.js';
 import { mutationTest } from './mutation-run.js';
-import { replayNamedFlow, sessionProjectId } from './flow-replay-run.js';
+import { replayNamedFlow } from './flow-replay-run.js';
+import { sessionTarget } from '../../memory/project/session-root.js';
 import { flowsForSession } from './flow-store-for-session.js';
 import { ReplayStatus } from '@reticlehq/core';
 const NOTHING_DECLARED = 'this flow declares no network consequence, so it has named nothing whose breakage it could be ' +
@@ -48,8 +49,9 @@ export const FLOW_MUTATE_TOOL = {
     handler: async (deps, args) => {
         const name = asString(args['flowName']) ?? asString(args['flow']) ?? '';
         const sessionId = asString(args['sessionId']);
-        const projectId = sessionProjectId(deps, sessionId);
-        const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
+        const project = sessionTarget(deps, sessionId);
+        const { projectId } = project;
+        const loaded = await flowsForSession(deps, project).flows.load(name, projectId);
         if (!loaded.ok) {
             return { flow: name, because: `could not load "${name}": ${String(loaded.code)}` };
         }

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

@@ -1,4 +1,4 @@
-import { type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
+import { type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent } 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';
@@ -20,8 +20,8 @@ interface StartPathSession {
  * 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 for when that
- * navigation was refused or the SDK never reconnected in the window.
+ * 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. */
@@ -30,6 +30,10 @@ export interface StartPathArrival {
     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;
 }
 /**
  * Replay's half of the FlowFile contract: put the tab on the flow's `startPath` before step 1, and
@@ -48,10 +52,9 @@ export interface StartPathArrival {
  * 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, 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.
+ * 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;
@@ -69,6 +72,18 @@ export declare function arriveAtStartPath(sessions: SessionManager, session: 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.
  */
+/** How a navigate ended: target, redirect, refusal (untouched tab), or no successor. */
+export type NavigateOutcome = {
+    kind: 'arrived';
+    session: Session;
+} | {
+    kind: 'redirected';
+    session: Session;
+} | {
+    kind: 'refused';
+} | {
+    kind: 'lost';
+};
 export declare function navigateAndAwait(sessions: SessionManager, session: {
     id: string;
     /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
@@ -76,7 +91,7 @@ export declare function navigateAndAwait(sessions: SessionManager, session: {
     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): Promise<Session | undefined>;
+isReload?: boolean): Promise<NavigateOutcome>;
 /**
  * The honest answer when the document replay was driving went away mid-run.
  *
@@ -97,7 +112,6 @@ export declare function lostDocumentResult(name: string, lost: DocumentLostDurin
 export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>, 
 /** Wraps the session the steps run on, so a caller can watch what they resolved. */
 observe?: (session: FlowReplaySession) => FlowReplaySession): Promise<FlowReplayResult>;
-export declare function crossStepOnly(whole: readonly Contradiction[], steps: readonly FlowStepResult[]): Contradiction[];
 /**
  * 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