@reticlehq/server 3.8.2 → 3.10.0

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;

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

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { PredicateKind } from '@reticlehq/core';
+import { routePathOf } from '@reticlehq/engine/question/predicate/predicate-route.js';
 /**
  * One journey, however many times it was driven.
  *
@@ -104,17 +105,108 @@ export function routeClaims(startPath, steps) {
 /**
  * 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 function establishedState(flow) {
+    return (flow.requires ?? []).filter((claim) => !(PredicateKind.ROUTE === claim.kind && claim.pathname !== undefined));
+}
+/**
+ * The route claims in `requires` that say more than the flow's `startPath`, in order.
+ *
+ * A claim on the `startPath` itself is left out: that is the claim every saved drive writes, and
+ * replay already arrives there. Every other claim names a page the flow needs (#2034).
+ */
+function pageClaims(flow) {
     const start = flow.startPath;
-    return (flow.requires ?? []).filter((claim) => !(start !== undefined &&
-        PredicateKind.ROUTE === claim.kind &&
-        claim.pathname !== undefined &&
-        samePath(claim.pathname, start)));
+    const claims = [];
+    for (const claim of flow.requires ?? []) {
+        if (PredicateKind.ROUTE !== claim.kind || claim.pathname === undefined) {
+            continue;
+        }
+        if (0 === claim.pathname.length) {
+            continue;
+        }
+        if (start !== undefined && samePath(claim.pathname, start)) {
+            continue;
+        }
+        claims.push({
+            pathname: claim.pathname,
+            ...(claim.contains === undefined ? {} : { contains: claim.contains }),
+        });
+    }
+    return claims;
+}
+/**
+ * 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 function declaredRoute(flow) {
+    return pageClaims(flow)[0]?.pathname;
+}
+/**
+ * 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 function unmetRouteClaim(flow, observed) {
+    for (const claim of pageClaims(flow)) {
+        if (!onRoute(observed, claim.pathname)) {
+            return `it is not on ${claim.pathname}`;
+        }
+        if (claim.contains !== undefined && !observed.includes(claim.contains)) {
+            return `its address does not contain "${claim.contains}"`;
+        }
+    }
+    return undefined;
+}
+/** The mark of a route segment that stands for any one entity id: `:id` in `/cases/:id/notes`. */
+const ROUTE_PARAM_MARK = ':';
+/** Whether a route segment is a placeholder such as `:id`. */
+function isRouteParam(segment) {
+    return segment.startsWith(ROUTE_PARAM_MARK) && ROUTE_PARAM_MARK.length < segment.length;
+}
+/** The segments of the path the router is on, without a query or a trailing slash. */
+function routerSegments(path) {
+    let parsed;
+    try {
+        parsed = new URL(path, 'http://localhost');
+    }
+    catch {
+        return undefined;
+    }
+    return routePathOf(parsed.pathname, parsed.hash).replace(/\/$/, '').split('/');
+}
+/** Whether a declared route names an entity id with a `:name` segment, for example `/cases/:id/notes`. */
+export function isRoutePattern(route) {
+    return (routerSegments(route) ?? []).some(isRouteParam);
+}
+/**
+ * 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 function onRoute(observed, route) {
+    if (!isRoutePattern(route)) {
+        return samePath(observed, route);
+    }
+    const here = routerSegments(observed);
+    const wanted = routerSegments(route);
+    if (here === undefined || wanted === undefined || here.length !== wanted.length) {
+        return false;
+    }
+    return wanted.every((segment, i) => {
+        const at = here[i] ?? '';
+        return isRouteParam(segment) ? 0 < at.length : segment === at;
+    });
 }
 /**
  * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
@@ -150,3 +242,41 @@ export function startPathBudgetMs(flow) {
     const first = flow.steps[0]?.timeoutMs ?? flow.signalTimeoutMs ?? 0;
     return Math.max(START_PATH_ARRIVAL_TIMEOUT_MS, first);
 }
+/**
+ * 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 function fillRouteParams(route, observed) {
+    const wanted = routerSegments(route);
+    const here = routerSegments(observed);
+    if (wanted === undefined || here === undefined) {
+        return undefined;
+    }
+    const values = [];
+    for (const [i, segment] of wanted.entries()) {
+        if (!isRouteParam(segment)) {
+            continue;
+        }
+        const agrees = wanted
+            .slice(0, i)
+            .every((before, j) => isRouteParam(before) || before === here[j]);
+        const value = here[i] ?? '';
+        if (!agrees || 0 === value.length) {
+            return undefined;
+        }
+        values.push(value);
+    }
+    if (0 === values.length) {
+        return undefined;
+    }
+    let next = 0;
+    return route.replace(/(?<=\/):[^/?#]+/g, (param) => {
+        const value = values[next] ?? param;
+        next += 1;
+        return value;
+    });
+}

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

@@ -6,22 +6,6 @@ export declare function latestRecordedFlow(events: ReticleEvent[]): {
     flow: import('@reticlehq/core').FlowFile;
 } | undefined;
 export { flowErrorMessage } from './flow-result.js';
-/**
- * The honest answer when the document replay was driving went away mid-run.
- *
- * Not a pass: nothing graded the journey, and the steps in hand are only the ones the departed
- * document answered. Not a failure either — the app was never observed doing anything wrong, and
- * reporting one would be the false red that sends a reader into product code that is fine. So it
- * lands in the bucket this engine already has for "nothing was proved", the same one an unmet
- * precondition uses, with the steps that DID answer attached and no row invented for the one that
- * did not.
- *
- * Why replay reports rather than follows: the successor cannot be identified at the moment the
- * socket closes. `SessionManager.remove` runs from the close handler, writes the tombstone a
- * successor is later matched against, and has nothing to match yet — so the rejection is a plain
- * transport failure by design, and a step in the middle of a journey has no budget to sit and poll
- * with. `navigateAndAwait` CAN wait, because it knows it asked for the navigation, and it does.
- */
 export declare function lostDocumentResult(name: string, lost: DocumentLostDuringReplay): FlowReplayResult;
 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. */