@reticlehq/server 3.9.0 → 3.10.0

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

@@ -1,5 +1,5 @@
 import { AnchorKind, DriftReason, ReticleCommand, QueryBy, asRecord, asString, } from '@reticlehq/core';
-import { queryRefs } from './replay.js';
+import { namelessRefs, queryRefs } from './replay.js';
 /**
  * Finding a step's anchor again, and saying legibly why it could not be found.
  *
@@ -20,16 +20,18 @@ export function editDistance(a, b) {
     const cols = t.length + 1;
     const prev = new Array(cols);
     const curr = new Array(cols);
-    for (let j = 0; j < cols; j++)
+    for (let j = 0; j < cols; j++) {
         prev[j] = j;
+    }
     for (let i = 1; i < rows; i++) {
         curr[0] = i;
         for (let j = 1; j < cols; j++) {
             const cost = s[i - 1] === t[j - 1] ? 0 : 1;
             curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
         }
-        for (let j = 0; j < cols; j++)
+        for (let j = 0; j < cols; j++) {
             prev[j] = curr[j] ?? 0;
+        }
     }
     return prev[cols - 1] ?? 0;
 }
@@ -58,8 +60,9 @@ export function nearestTestid(missing, present) {
             bestDistance = distance;
         }
     }
-    if (null === best)
+    if (null === best) {
         return null;
+    }
     return bestDistance <= Math.max(missing.length, best.length) / 2 ? best : null;
 }
 /**
@@ -90,8 +93,9 @@ const ANCHOR_SETTLE_MAX_ATTEMPTS = 40;
 /** Extract the live element refs + the zero-match near-miss hint from a QUERY command result. */
 function readQuery(result) {
     const refs = queryRefs(result);
-    if (!result.ok)
+    if (!result.ok) {
         return { refs };
+    }
     const payload = asRecord(result.result);
     const rawHint = payload['hint'];
     if ('object' === typeof rawHint && rawHint !== null) {
@@ -117,8 +121,9 @@ function readQuery(result) {
  * Such a drift is surfaced (with a nearest) but never auto-healed.
  */
 export function nearestIsAmbiguous(missing, present) {
-    if (present.length < 2)
+    if (present.length < 2) {
         return false;
+    }
     let min = Number.POSITIVE_INFINITY;
     let count = 0;
     for (const candidate of present) {
@@ -142,8 +147,9 @@ export function testidDrift(value, hint) {
         anchor: value,
         nearest: nearestTestid(value, present),
     };
-    if (nearestIsAmbiguous(value, present))
+    if (nearestIsAmbiguous(value, present)) {
         drift.ambiguous = true;
+    }
     return drift;
 }
 /**
@@ -159,6 +165,19 @@ export function testidDrift(value, hint) {
  * 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.
  */
+/**
+ * How a role anchor reads in a message: `button "View result"`, or for a control with no accessible
+ * name, `button (no accessible name, #2 of 3)` — never `button "undefined"`.
+ */
+export function roleAnchorLabel(anchor) {
+    if (anchor.name !== undefined) {
+        return `${anchor.role} "${anchor.name}"`;
+    }
+    const at = anchor.nth !== undefined && anchor.of !== undefined
+        ? `, #${String(anchor.nth + 1)} of ${String(anchor.of)}`
+        : '';
+    return `${anchor.role} (no accessible name${at})`;
+}
 function anchorAddress(anchor) {
     if (anchor.kind === AnchorKind.TESTID) {
         return { described: `testid "${anchor.value}"`, label: anchor.value };
@@ -166,7 +185,7 @@ function anchorAddress(anchor) {
     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)}"`;
+        const label = roleAnchorLabel(anchor);
         return { described: `role anchor ${label}`, label };
     }
     // A component needs no such qualifier: `componentLabel` already answers
@@ -226,8 +245,9 @@ export function ambiguityDrift(anchor, refs) {
  * 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)
+    if (1 === refs.length) {
         return refs[0];
+    }
     const { nth, of } = { ...anchor };
     return 'number' === typeof nth && of === refs.length ? refs[nth] : undefined;
 }
@@ -246,8 +266,9 @@ export function refFor(anchor, refs) {
  */
 export function reresolved(anchor, refs) {
     const drift = ambiguityDrift(anchor, refs);
-    if (drift !== null)
+    if (drift !== null) {
         return { drift };
+    }
     const ref = refFor(anchor, refs);
     return ref === undefined ? undefined : { ref };
 }
@@ -268,8 +289,9 @@ export function expectElementDrift(value, hint) {
         anchor: value,
         nearest: nearestTestid(value, present),
     };
-    if (nearestIsAmbiguous(value, present))
+    if (nearestIsAmbiguous(value, present)) {
         drift.ambiguous = true;
+    }
     return drift;
 }
 /**
@@ -296,8 +318,9 @@ async function settleTick(session, sleep) {
         await new Promise((resolve) => {
             let done = false;
             const finish = () => {
-                if (done)
+                if (done) {
                     return;
+                }
                 done = true;
                 resolve();
             };
@@ -313,15 +336,34 @@ async function settleTick(session, sleep) {
 export async function queryOnce(session, queryArgs) {
     return readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
 }
-export async function resolveQuery(session, queryArgs, sleep, now = Date.now) {
-    let last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
+export async function resolveQuery(session, queryArgs, sleep, now = Date.now, read = readQuery) {
+    return await resolveAnyQuery(session, [queryArgs], sleep, now, read);
+}
+/**
+ * Several queries for one control, pooled: each attempt runs every query and joins the refs, so
+ * the settle budget is spent once, not once for each query. A role anchor with `alsoRoles` uses it.
+ */
+export async function resolveAnyQuery(session, queries, sleep, now = Date.now, read = readQuery) {
+    const look = async () => {
+        const reads = [];
+        for (const queryArgs of queries) {
+            reads.push(read(await session.command(ReticleCommand.QUERY, queryArgs)));
+        }
+        const hint = reads.find((read) => read.hint !== undefined)?.hint;
+        return { refs: reads.flatMap((read) => read.refs), ...(hint === undefined ? {} : { hint }) };
+    };
+    let last = await look();
     const deadline = now() + ANCHOR_SETTLE_BUDGET_MS;
     for (let attempt = 1; 0 === last.refs.length && now() < deadline && attempt < ANCHOR_SETTLE_MAX_ATTEMPTS; attempt += 1) {
         await settleTick(session, sleep);
-        last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
+        last = await look();
     }
     return last;
 }
+/** `resolveQuery`'s reader for a nameless role anchor: only the matches with no accessible name. */
+export function readNamelessQuery(result) {
+    return { refs: namelessRefs(result) };
+}
 /** Re-resolve a testid anchor. */
 export function resolveTestid(session, value, sleep) {
     return resolveQuery(session, { by: QueryBy.TESTID, value }, sleep);
@@ -337,20 +379,83 @@ export function componentLabel(anchor) {
 }
 /** The value of a step's primary anchor, for labelling the result row. */
 export function anchorLabel(anchor) {
-    if (anchor.kind === AnchorKind.TESTID)
+    if (anchor.kind === AnchorKind.TESTID) {
         return anchor.value;
-    if (anchor.kind === AnchorKind.SIGNAL)
+    }
+    if (anchor.kind === AnchorKind.SIGNAL) {
         return anchor.name;
-    if (anchor.kind === AnchorKind.COMPONENT)
+    }
+    if (anchor.kind === AnchorKind.COMPONENT) {
         return componentLabel(anchor);
+    }
     return anchor.name ?? anchor.role;
 }
 /** QUERY args for a component auto-anchor — source (precise) + component name (coarse) as given. */
 export function componentQueryArgs(anchor) {
     const args = { by: QueryBy.COMPONENT };
-    if (anchor.component !== undefined)
+    if (anchor.component !== undefined) {
         args['component'] = anchor.component;
-    if (anchor.source !== undefined)
+    }
+    if (anchor.source !== undefined) {
         args['source'] = anchor.source;
+    }
+    if (anchor.text !== undefined) {
+        args['text'] = anchor.text;
+    }
+    // An older SDK ignores a role on a component query and answers as before.
+    if (anchor.role !== undefined) {
+        args['role'] = anchor.role;
+    }
     return args;
 }
+/** Query args for a NAMED role anchor — the handle that identifies an instance, not a JSX site. */
+export function roleQueryArgs(anchor) {
+    return {
+        by: QueryBy.ROLE,
+        value: anchor.role,
+        ...(anchor.name === undefined ? {} : { name: anchor.name }),
+    };
+}
+/** One query for each role the anchor accepts: its own role, then `alsoRoles`. */
+function roleQueries(anchor) {
+    return [anchor.role, ...(anchor.alsoRoles ?? [])].map((role) => roleQueryArgs({ ...anchor, role }));
+}
+/**
+ * Resolve a role anchor. ONE function for the first look and the re-resolve after a stale ref: the
+ * re-resolve used to count every control of the role, so a nameless anchor's position came back
+ * ambiguous on a working page.
+ *
+ * A nameless anchor's position counts only the nameless controls of its role (an icon-only edit
+ * button is the 2nd nameless button of its row, not the 5th button), so it reads only those.
+ */
+export async function resolveRoleAnchor(session, anchor, sleep) {
+    // Every role the anchor accepts (`alsoRoles`), pooled in one settle loop; a nameless anchor keeps
+    // only the matches with no accessible name.
+    const found = await resolveAnyQuery(session, roleQueries(anchor), sleep, Date.now, anchor.name === undefined ? readNamelessQuery : undefined);
+    if (found.refs.length > 0 || anchor.name === undefined || anchor.within === undefined) {
+        return found;
+    }
+    const refs = await refsWithin(session, anchor.role, anchor.within);
+    return refs.length > 0 ? { refs } : found;
+}
+/**
+ * The controls of `role` inside the recorded container chain, for a named control whose name is
+ * gone (a correct build may word a button differently). The chain is walked outermost first, and
+ * each container must be the only one of its role in the one before. When a container is not
+ * unique, its matches come back, so the caller reports the step as ambiguous and does not act.
+ */
+async function refsWithin(session, role, within) {
+    let scope;
+    for (const container of [...within].reverse()) {
+        const { refs } = await queryOnce(session, {
+            by: QueryBy.ROLE,
+            value: container,
+            ...(scope === undefined ? {} : { scope }),
+        });
+        if (1 !== refs.length) {
+            return refs;
+        }
+        scope = refs[0];
+    }
+    return (await queryOnce(session, { by: QueryBy.ROLE, value: role, scope })).refs;
+}

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

@@ -19,6 +19,7 @@
  * Pure: no IO, no clock.
  */
 import type { FlowFile, FlowStep } from '@reticlehq/core';
+import { z } from 'zod';
 export declare const FlowAssertionGrade: {
     /** At least one step (or the success end-condition) asserts a signal/network consequence. */
     readonly ASSERTED: "asserted";
@@ -45,9 +46,28 @@ export interface FlowAssertionClassification {
      * intent but only presence-only checks is the dangerous case — it claims a goal it cannot verify.
      */
     intentVerified: boolean;
+    /**
+     * How many checks of each predicate kind the flow runs, over every step, sub-step and the success
+     * state, composites flattened. Absent when the flow checks nothing. A presence-only grade with
+     * this list says WHAT is checked, so the grade does not read as "checks nothing" (#1840).
+     */
+    checks?: Record<string, number>;
     /** Present for presence-only / assertion-free flows: how to make the flow a real test. */
     warning?: string;
 }
+/**
+ * The `assertions` block of the `reticle_flow_save` result. Declared here, next to the type it
+ * describes, because a validating profile removes a field that the output schema does not declare.
+ */
+export declare const FLOW_ASSERTIONS_OUTPUT: z.ZodOptional<z.ZodObject<{
+    grade: z.ZodString;
+    hasConsequenceAssertion: z.ZodBoolean;
+    totalSteps: z.ZodNumber;
+    consequenceSteps: z.ZodNumber;
+    weakSteps: z.ZodNumber;
+    checks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    warning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
 /**
  * A step expect counts the same as a flow-level one, because replay now evaluates the same set.
  *

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

@@ -18,7 +18,8 @@
  *
  * Pure: no IO, no clock.
  */
-import { flowExpectHasConsequence, flowExpectIsPresenceOnly } from '@reticlehq/core';
+import { PredicateKind, flowExpectHasConsequence, flowExpectIsPresenceOnly } from '@reticlehq/core';
+import { z } from 'zod';
 export const FlowAssertionGrade = {
     /** At least one step (or the success end-condition) asserts a signal/network consequence. */
     ASSERTED: 'asserted',
@@ -27,8 +28,32 @@ export const FlowAssertionGrade = {
     /** Performs actions but asserts nothing observable — passes even if the feature is broken. */
     ASSERTION_FREE: 'assertion-free',
 };
+/**
+ * The `assertions` block of the `reticle_flow_save` result. Declared here, next to the type it
+ * describes, because a validating profile removes a field that the output schema does not declare.
+ */
+export const FLOW_ASSERTIONS_OUTPUT = z
+    .object({
+    grade: z.string().describe('asserted | presence-only | assertion-free'),
+    hasConsequenceAssertion: z.boolean(),
+    totalSteps: z.number(),
+    consequenceSteps: z.number(),
+    weakSteps: z.number(),
+    checks: z
+        .record(z.string(), z.number())
+        .optional()
+        .describe('Checks of each predicate kind (text, element, route, net, signal, …) the flow runs.'),
+    warning: z.string().optional(),
+})
+    .optional();
 const ASSERTION_FREE_WARNING = 'This flow performs actions but asserts no observable consequence, so it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state.';
-const PRESENCE_ONLY_WARNING = 'This flow only checks element presence, not an observable consequence (signal/network). A locator healed to the wrong element can still pass it. Add a consequence assertion (assert-signal / assert-net / success-state).';
+/** Why a presence check is weaker than a consequence, and the fix. Shared by both presence notes. */
+const PRESENCE_ONLY_ADVICE = 'A locator healed to the wrong element can still pass it. Add a consequence assertion (assert-signal / assert-net / success-state).';
+const PRESENCE_ONLY_WARNING = `This flow only checks element presence, not an observable consequence (signal/network). ${PRESENCE_ONLY_ADVICE}`;
+/** The presence note when the checks are known: it names them, then says why they are weak. */
+const presenceOnlyWarning = (checks) => `This flow checks ${checks} on the page. These are presence checks, not an observable consequence (signal/network). ${PRESENCE_ONLY_ADVICE}`;
+/** The intent note when the flow has presence checks: it names them, then says what is not checked (#1801). */
+const intentWithPresenceWarning = (checks) => `This flow declares a business intent and checks ${checks} on the page, but no step checks a request, a signal or app state. A change that keeps the page as it is but breaks the work behind it still passes. Add a success-state consequence so the flow fails when the goal stops being met.`;
 const INTENT_WITHOUT_OUTCOME_WARNING = 'This flow declares a business intent but asserts no observable outcome (signal/network) — it claims to verify a goal it cannot actually check. Add a success-state consequence so the flow fails when the goal stops being met.';
 // Consequence vs presence-only classification lives in @reticlehq/core (one source for all graders).
 const expectIsConsequence = flowExpectHasConsequence;
@@ -50,8 +75,9 @@ export function flattenSteps(steps) {
     const out = [];
     for (const s of steps) {
         out.push(s);
-        if (s.steps !== undefined)
+        if (s.steps !== undefined) {
             out.push(...flattenSteps(s.steps));
+        }
     }
     return out;
 }
@@ -72,24 +98,65 @@ export function flattenSteps(steps) {
  * having run — grading is reached from save, which is exactly where a bad composite arrives first.
  */
 function invokedAssertsConsequence(flow, invoked, seen) {
-    if (seen.has(flow.name))
+    if (seen.has(flow.name)) {
         return false;
+    }
     const deeper = new Set([...seen, flow.name]);
     for (const step of flattenSteps(flow.steps)) {
-        if (step.invoke === undefined)
+        if (step.invoke === undefined) {
             continue;
+        }
         const sub = invoked.get(step.invoke);
-        if (sub === undefined)
+        if (sub === undefined) {
             continue;
+        }
         const subSteps = flattenSteps(sub.steps);
         if (subSteps.some((s) => expectIsConsequence(s.expect)) || expectIsConsequence(sub.success)) {
             return true;
         }
-        if (invokedAssertsConsequence(sub, invoked, deeper))
+        if (invokedAssertsConsequence(sub, invoked, deeper)) {
             return true;
+        }
     }
     return false;
 }
+/** Every leaf clause of an expectation, composites flattened. */
+function leafClauses(expect) {
+    if (expect === undefined) {
+        return [];
+    }
+    if (PredicateKind.ALL_OF === expect.kind || PredicateKind.ANY_OF === expect.kind) {
+        return expect.predicates.flatMap(leafClauses);
+    }
+    if (PredicateKind.NOT === expect.kind) {
+        return leafClauses(expect.predicate);
+    }
+    return [expect];
+}
+/** Checks of each kind over the given expectations, keys in name order, or undefined for none. */
+function countChecks(expects) {
+    const counts = new Map();
+    for (const clause of expects.flatMap(leafClauses)) {
+        counts.set(clause.kind, (counts.get(clause.kind) ?? 0) + 1);
+    }
+    if (0 === counts.size) {
+        return undefined;
+    }
+    return Object.fromEntries([...counts.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+/** "text (3), element (1) and route (1)": most checks first, ties in name order. */
+function describeChecks(checks) {
+    const parts = Object.entries(checks)
+        .sort(([a, x], [b, y]) => y - x || a.localeCompare(b))
+        .map(([kind, n]) => `${kind} (${String(n)})`);
+    const last = parts.pop() ?? '';
+    return 0 === parts.length ? last : `${parts.join(', ')} and ${last}`;
+}
+function responseIsDeclared(step) {
+    const r = step.response;
+    return (r !== undefined &&
+        (r.status !== undefined || r.contains !== undefined || r.absent !== undefined));
+}
 export function classifyFlowAssertions(flow, 
 /**
  * The flows this one invokes, already loaded.
@@ -103,16 +170,20 @@ invoked = new Map()) {
     let consequenceSteps = 0;
     let weakSteps = 0;
     for (const s of all) {
-        if (expectIsConsequence(s.expect))
+        // A request step's declared response judges what the server answered: a consequence.
+        if (expectIsConsequence(s.expect) || responseIsDeclared(s)) {
             consequenceSteps++;
-        else if (expectIsWeak(s.expect))
+        }
+        else if (expectIsWeak(s.expect)) {
             weakSteps++;
+        }
     }
     const invokedAsserts = invokedAssertsConsequence(flow, invoked, new Set());
     const successIsConsequence = expectIsConsequence(flow.success);
     const successIsWeak = expectIsWeak(flow.success);
     const hasConsequenceAssertion = consequenceSteps > 0 || successIsConsequence || invokedAsserts;
     const hasAnyAssertion = hasConsequenceAssertion || weakSteps > 0 || successIsWeak;
+    const checks = countChecks([...all.map((s) => s.expect), flow.success]);
     const intent = flow.intent;
     const intentVerified = intent !== undefined && hasConsequenceAssertion;
     let grade;
@@ -122,7 +193,9 @@ invoked = new Map()) {
     }
     else if (hasAnyAssertion) {
         grade = FlowAssertionGrade.PRESENCE_ONLY;
-        warning = PRESENCE_ONLY_WARNING;
+        // What it checks first, so the grade does not read as "checks nothing" (#1840).
+        warning =
+            checks === undefined ? PRESENCE_ONLY_WARNING : presenceOnlyWarning(describeChecks(checks));
     }
     else {
         grade = FlowAssertionGrade.ASSERTION_FREE;
@@ -130,8 +203,12 @@ invoked = new Map()) {
     }
     // A declared-but-unverifiable business goal is the sharper failure: surface it over the generic
     // assertion warning, since the flow actively claims to check something it cannot.
-    if (intent !== undefined && !hasConsequenceAssertion)
-        warning = INTENT_WITHOUT_OUTCOME_WARNING;
+    if (intent !== undefined && !hasConsequenceAssertion) {
+        warning =
+            checks === undefined
+                ? INTENT_WITHOUT_OUTCOME_WARNING
+                : intentWithPresenceWarning(describeChecks(checks));
+    }
     return {
         grade,
         hasConsequenceAssertion,
@@ -139,6 +216,7 @@ invoked = new Map()) {
         consequenceSteps,
         weakSteps,
         successIsConsequence,
+        ...(checks === undefined ? {} : { checks }),
         ...(intent !== undefined ? { intent } : {}),
         intentVerified,
         ...(warning !== undefined ? { warning } : {}),

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

@@ -1,4 +1,10 @@
-import type { Contradiction, FlowStep, FlowStepResult, Predicate } from '@reticlehq/core';
+import { type Contradiction, type FlowStep, type FlowStepResult, type Predicate } from '@reticlehq/core';
+/** True for a finding that only means something inside one action's window (see ONE_ACTION_ONLY). */
+export declare function isOneActionOnly(found: {
+    kind: string;
+}): boolean;
+/** A step's own findings, without the ones only the end of the replay can decide. */
+export declare function stepContradictions(found: readonly Contradiction[]): Contradiction[];
 /** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
 export declare const CROSS_STEP_INDEX = -1;
 /**

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

@@ -1,8 +1,32 @@
+import { ContradictionKind, } from '@reticlehq/core';
 import { flattenSteps } from './flow-classify.js';
 /** 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}`;
 }
+/**
+ * Kinds that only mean something inside ONE action's window. A duplicate request claims "one user
+ * action was performed"; across a whole flow there are many actions, so a toggle hit once per step
+ * (Pause, then Resume) read as a double submit (#2013). Each step already checks its own window.
+ */
+const ONE_ACTION_ONLY = new Set([
+    ContradictionKind.DUPLICATE_REQUEST,
+    ContradictionKind.DUPLICATE_REQUEST_UNRELATED,
+]);
+/** True for a finding that only means something inside one action's window (see ONE_ACTION_ONLY). */
+export function isOneActionOnly(found) {
+    return ONE_ACTION_ONLY.has(found.kind);
+}
+/**
+ * Kinds a step window cannot decide. "Never settled" means never, and a step's window closes while
+ * the replay still runs: a request a step's predecessor started late can finish a moment after this
+ * window ends. The whole-span pass, run when the replay is over, sees whether it ever came back.
+ */
+const DECIDED_AT_THE_END = new Set([ContradictionKind.REQUEST_NEVER_SETTLED]);
+/** A step's own findings, without the ones only the end of the replay can decide. */
+export function stepContradictions(found) {
+    return found.filter((c) => !DECIDED_AT_THE_END.has(c.kind));
+}
 /** Cross-step findings belong to no single step; -1 is the address the suite verdict already uses. */
 export const CROSS_STEP_INDEX = -1;
 /**
@@ -18,7 +42,7 @@ export const CROSS_STEP_INDEX = -1;
  */
 export function crossStepOnly(whole, steps) {
     const seen = new Set(steps.flatMap((step) => (step.contradictions ?? []).map(contradictionId)));
-    return whole.filter((found) => !seen.has(contradictionId(found)));
+    return whole.filter((found) => !seen.has(contradictionId(found)) && !isOneActionOnly(found));
 }
 /**
  * Every consequence the flow declared, sub-steps included. The whole-span pass judges the same

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

@@ -36,12 +36,37 @@ export declare function routeClaims(startPath: string | undefined, steps: readon
 /**
  * The preconditions only another flow can establish.
  *
- * A route claim on the page the flow starts on is not one of them: replay navigates there itself, so
- * it neither opts the flow out of the reset nor gates the run. That is the claim a saved drive writes
- * for the map (see routeClaims) — reading it as "starts from leftover state" would stop every
- * auto-saved flow from ever being reset.
+ * A route claim with a `pathname` is not one of them: replay navigates to a declared route itself
+ * (see `declaredRoute`), and checks the claim, its `contains` too, once the tab is there (see
+ * `unmetRouteClaim`). So a route claim neither opts the flow out of the reset nor gates the run
+ * here. The claim on the page the flow starts on is the one a saved drive writes for the map (see
+ * routeClaims) — reading it as "starts from leftover state" would stop every auto-saved flow from
+ * ever being reset. A route claim on ANOTHER page was read that way, and a suite then ran the flow
+ * on whatever page the previous flow left open (#2034).
  */
 export declare function establishedState(flow: FlowFile): readonly Predicate[];
+/**
+ * The route a flow declares in `requires` when that says more than its `startPath`: the first
+ * such claim, in any order of the claims. Undefined when there is none, and replay then arrives
+ * at `startPath` as before. Replay puts the tab on this route before step 1 (#2034).
+ */
+export declare function declaredRoute(flow: FlowFile): string | undefined;
+/**
+ * The first declared route claim that the page `observed` does not satisfy, said for a reader.
+ * Undefined when they all hold. Each claim is checked whole: its `pathname` by `onRoute`, and its
+ * `contains` against the whole route, as the `route` predicate checks it.
+ */
+export declare function unmetRouteClaim(flow: FlowFile, observed: string): string | undefined;
+/** Whether a declared route names an entity id with a `:name` segment, for example `/cases/:id/notes`. */
+export declare function isRoutePattern(route: string): boolean;
+/**
+ * Is the tab on a declared route?
+ *
+ * A plain route is compared as `samePath` compares a `startPath`. A pattern is compared segment by
+ * segment on the router's path, and a `:name` segment matches any one non-empty segment. The query
+ * is not compared for a pattern: the pattern says which page, and the id says which record.
+ */
+export declare function onRoute(observed: string, route: string): boolean;
 /**
  * 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.
@@ -66,3 +91,12 @@ export declare function samePath(observed: string, expected: string): boolean;
  * consequence can also wait 15 s for its page.
  */
 export declare function startPathBudgetMs(flow: FlowFile): number;
+/**
+ * A pattern route with its `:name` segments filled from the page `observed`.
+ *
+ * A segment is taken only when every segment before it in the route agrees with the page: from
+ * `/cases/c-42/files`, the route `/cases/:id/notes` becomes `/cases/c-42/notes`. So another section
+ * of the same case keeps the case, and the recorded id, which can be a deleted record, is not used.
+ * Undefined when the page has no id to give (`/settings`), or the route has no `:name` segment.
+ */
+export declare function fillRouteParams(route: string, observed: string): string | undefined;