@reticlehq/server 2.2.1 → 2.3.0

package/dist/events/unit-mismatch.js

@@ -0,0 +1,167 @@
+import { ContradictionKind, EventType } from '@reticlehq/core';
+/**
+ * The app sent a money value back in a DIFFERENT unit than the API gave it.
+ *
+ * Payment APIs overwhelmingly speak minor units — Stripe, Razorpay, Adyen, PayPal all state amounts
+ * in paise/cents as integers. A UI renders that as a major-unit string, and the bug is writing the
+ * rendered number back into the field the integer came from.
+ *
+ * Measured on a real payments dashboard: `GET /payments` returns `amount: 118701` for a payment, the
+ * row renders "₹1,187.01", and the refund posts `{"amount": 1187.01}` into the same field. The server
+ * takes 1187 paise and answers `200 {"status": "processed"}`. That is a 100x UNDER-REFUND, and every
+ * channel agrees it worked: the status is 200, the payload says processed, the UI advances, the page
+ * settles, and the number in the request is exactly the number on the screen. Nothing disagrees,
+ * because the disagreement is with a value the API returned EARLIER in the session.
+ *
+ * Which is the point: this is only visible to something holding the whole request timeline with
+ * bodies. A snapshot cannot see it, a status column cannot see it, and a human reading the request
+ * sees the amount they expected.
+ *
+ * Not a heuristic about decimals. Firing on "an amount had a fractional part" would accuse every API
+ * that legitimately uses major units. This fires only when the SAME field of the SAME entity was
+ * observed at a different scale — a comparison, not a guess.
+ */
+/** Fields worth comparing. Deliberately short: money, not every number an app sends. */
+const MONEY_FIELDS = new Set(['amount', 'value', 'price', 'total', 'fee', 'cost', 'balance']);
+/**
+ * Scales that indicate a minor/major confusion. 100 covers two-decimal currencies; 1000 covers the
+ * three-decimal ones (KWD, BHD, JOD, TND).
+ */
+const SCALES = [100, 1000];
+/**
+ * Prefixed ids (`pay_NkT10001`) and uuids, matched anywhere in a URL or a string field.
+ *
+ * Numeric ids are handled separately by path segment: `/api/orders/9/capture` is at least as common
+ * as a prefixed id, and a bare `9` cannot be pattern-matched out of arbitrary text without matching
+ * every other number too.
+ */
+const ID_PATTERN = /[A-Za-z]{2,}_[A-Za-z0-9]{2,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/g;
+function parse(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every (id, field, value) triple in a payload, from objects that carry an id of their own. */
+function moneyByEntity(node, into) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            moneyByEntity(item, into);
+        return;
+    }
+    if (typeof node !== 'object' || node === null)
+        return;
+    const record = node;
+    // An id may arrive as a number (`{"id": 9}`) — normalised so a numeric path segment matches it.
+    const raw = record['id'];
+    const id = typeof raw === 'string' ? raw : typeof raw === 'number' ? String(raw) : undefined;
+    if (id !== undefined) {
+        for (const [key, value] of Object.entries(record)) {
+            if (!MONEY_FIELDS.has(key) || typeof value !== 'number')
+                continue;
+            const fields = into.get(id) ?? new Map();
+            fields.set(key, value);
+            into.set(id, fields);
+        }
+    }
+    for (const value of Object.values(record))
+        moneyByEntity(value, into);
+}
+/** Ids named anywhere in a URL or a request payload — how a write says which entity it targets. */
+function idsIn(url, body) {
+    const found = new Set(url.match(ID_PATTERN) ?? []);
+    // Numeric path segments: `/api/orders/9/capture` names entity 9.
+    for (const segment of url.split('?')[0]?.split('/') ?? []) {
+        if (segment.length > 0 && /^\d+$/.test(segment))
+            found.add(segment);
+    }
+    if (typeof body === 'object' && body !== null) {
+        for (const value of Object.values(body)) {
+            if (typeof value === 'string')
+                for (const id of value.match(ID_PATTERN) ?? [])
+                    found.add(id);
+        }
+    }
+    return Array.from(found);
+}
+/** The scale between a known value and a sent one, or undefined when they are consistent. */
+function scaleBetween(known, sent) {
+    if (sent === 0 || known === 0)
+        return undefined;
+    for (const scale of SCALES) {
+        // A tolerance, because the major-unit form is a rounded render of the minor one.
+        if (Math.abs(known - sent * scale) <= scale / 2)
+            return scale;
+    }
+    return undefined;
+}
+/**
+ * @param prior events from BEFORE the window, used only to learn what the API has stated.
+ *
+ * The scale error is a disagreement with a value the API gave EARLIER — by definition before the
+ * action that sends it back. `reticle_assert` scopes its window to the last act's cursor, so the
+ * stating response falls outside it and `known` is empty exactly when it matters. Measured live on
+ * the payments panel: `reticle_observe` over a wide window reported the mismatch while `assert` on
+ * the same session reported none — the verdict tool, the one an agent gates on, was the blind one.
+ *
+ * Prior events TEACH, they are never themselves findings: widening the window instead would make
+ * every other rule blame this action for events it did not cause, and would re-report every earlier
+ * mistake on every assert.
+ */
+export function findUnitMismatches(events, prior = []) {
+    // What the API has told us about each entity so far, in the API's own units.
+    const known = new Map();
+    for (const event of prior) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const body = parse(event.data['responseBody']);
+        if (body !== undefined)
+            moneyByEntity(body, known);
+    }
+    const found = [];
+    const seen = new Set();
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        const requestBody = parse(event.data['requestBody']);
+        // Compare BEFORE recording this call's own response, or a request that echoes its own reply
+        // would compare against itself.
+        if (typeof requestBody === 'object' && requestBody !== null) {
+            const sentFields = requestBody;
+            for (const id of idsIn(url, requestBody)) {
+                const fields = known.get(id);
+                if (fields === undefined)
+                    continue;
+                for (const [key, sent] of Object.entries(sentFields)) {
+                    if (!MONEY_FIELDS.has(key) || typeof sent !== 'number')
+                        continue;
+                    const priorValue = fields.get(key);
+                    if (priorValue === undefined)
+                        continue;
+                    const scale = scaleBetween(priorValue, sent);
+                    if (scale === undefined)
+                        continue;
+                    const key2 = `${id}:${key}`;
+                    if (seen.has(key2))
+                        continue;
+                    seen.add(key2);
+                    found.push({
+                        kind: ContradictionKind.UNIT_MISMATCH,
+                        claim: `the request sent ${key}=${String(sent)} and the server accepted it`,
+                        counter: `the API reports ${key}=${String(priorValue)} for ${id} — the value sent is ${String(scale)}x SMALLER, i.e. a major-unit number written into a minor-unit field`,
+                        detail: `${url} — at this scale the operation moves ${String(sent)} minor units instead of ${String(priorValue)}; nothing else can see this, because the number sent is exactly the number rendered on screen`,
+                    });
+                }
+            }
+        }
+        const responseBody = parse(event.data['responseBody']);
+        if (responseBody !== undefined)
+            moneyByEntity(responseBody, known);
+    }
+    return found;
+}

package/dist/flows/affected-tools.d.ts

@@ -0,0 +1,18 @@
+import type { ToolDef } from '../tools/tools.js';
+/**
+ * `reticle_affected` — which saved flows must re-verify for a set of changed files.
+ *
+ * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
+ * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
+ * this does not change it: the tool is NOT advertised by any profile. It is reachable through
+ * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
+ *
+ * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
+ * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
+ * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
+ * the party with the index.
+ *
+ * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
+ * this" is never confused with "this definitely touches your change".
+ */
+export declare const AFFECTED_TOOLS: ToolDef[];

package/dist/flows/affected-tools.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { ReticleTool } from '../tools/tool-names.js';
+import { loadNamedFlows, resolveChangedFiles } from '../cli-flow-commands.js';
+import { affectedSavedFlows } from './flow-sources.js';
+/**
+ * `reticle_affected` — which saved flows must re-verify for a set of changed files.
+ *
+ * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
+ * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
+ * this does not change it: the tool is NOT advertised by any profile. It is reachable through
+ * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
+ *
+ * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
+ * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
+ * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
+ * the party with the index.
+ *
+ * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
+ * this" is never confused with "this definitely touches your change".
+ */
+export const AFFECTED_TOOLS = [
+    {
+        name: ReticleTool.AFFECTED,
+        description: 'Which saved flows must re-verify for a set of changed files. Pass the files you edited (and/or `since` for a git ref to diff against). Returns { changedFiles, affected, unknownProvenance } — `affected` is what to re-run, and `unknownProvenance` are flows included only because Reticle cannot tell which sources they cover, so they are re-verified by default rather than silently skipped.',
+        example: { files: ['src/App.tsx'] },
+        inputSchema: {
+            files: z
+                .array(z.string())
+                .optional()
+                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
+        },
+        outputSchema: {
+            changedFiles: z.array(z.string()),
+            affected: z.array(z.string()),
+            unknownProvenance: z.array(z.string()),
+        },
+        handler: async (deps, args) => {
+            const files = Array.isArray(args['files'])
+                ? args['files'].filter((f) => typeof f === 'string')
+                : [];
+            const since = typeof args['since'] === 'string' ? args['since'] : undefined;
+            const changedFiles = await resolveChangedFiles(files, since);
+            const flows = await loadNamedFlows(deps.fs, deps.reticleRoot);
+            const result = affectedSavedFlows(flows, changedFiles);
+            return { changedFiles, ...result };
+        },
+    },
+];

package/dist/flows/affected.d.ts

@@ -22,4 +22,3 @@ export interface AffectedResult {
  * a repo-relative change matches an absolute stamp and vice-versa.
  */
 export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;
-//# sourceMappingURL=affected.d.ts.map

package/dist/flows/affected.js

@@ -33,4 +33,3 @@ export function affectedFlows(flows, changedFiles) {
     }
     return { affected, unknownProvenance };
 }
-//# sourceMappingURL=affected.js.map

package/dist/flows/annotate-tools.d.ts

@@ -13,4 +13,3 @@ import type { ToolDef } from '../tools/tools.js';
  * agent that annotates at the wrong moment gets a clear error rather than a crash.
  */
 export declare const ANNOTATE_TOOLS: ToolDef[];
-//# sourceMappingURL=annotate-tools.d.ts.map

package/dist/flows/annotate-tools.js

@@ -1,5 +1,14 @@
 import { z } from 'zod';
 import { AnnotationErrorCode, AnnotationSchema } from '@reticlehq/core';
+import { RECOVERY } from '../tools/error-recovery.js';
+/**
+ * An unknown kind is almost always a free-text annotation, which this tool deliberately refuses to
+ * guess into a predicate. Naming the six kinds turns a dead end into one retry.
+ */
+const UNKNOWN_KIND_RECOVERY = 'Annotations are structured, never free text. Pass one of: ' +
+    '{ kind: "assert-signal", name }, { kind: "assert-visible", testid }, ' +
+    '{ kind: "assert-state", statePath }, { kind: "mark-dynamic", testid }, ' +
+    '{ kind: "success-state", signal|testid }, or { kind: "intent", text }.';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asString } from '../tools/tools-helpers.js';
 import { compileAnnotation } from './annotate.js';
@@ -20,6 +29,7 @@ const DEFAULT_RECORDING = 'default';
 export const ANNOTATE_TOOLS = [
     {
         name: ReticleTool.ANNOTATE,
+        example: { kind: 'assert-signal', name: 'todos:loaded' },
         description: 'Attach a STRUCTURED annotation to the active recording, compiling it into the flow. kind: ' +
             'assert-signal { name, dataMatches? } → the last step asserts that signal; assert-visible ' +
             '{ testid } → the last step asserts that element is present; assert-state ' +
@@ -98,6 +108,7 @@ export const ANNOTATE_TOOLS = [
         },
         outputSchema: {
             ok: z.boolean(),
+            recovery: z.string().optional(),
             target: z.string().optional(),
             compiled: z.string().optional(),
             code: z.string().optional(),
@@ -107,12 +118,20 @@ export const ANNOTATE_TOOLS = [
             // Structured boundary: a free NL string / unknown kind fails the schema → UNKNOWN_KIND.
             const parsed = AnnotationSchema.safeParse(args);
             if (!parsed.success) {
-                return Promise.resolve({ ok: false, code: AnnotationErrorCode.UNKNOWN_KIND });
+                return Promise.resolve({
+                    ok: false,
+                    code: AnnotationErrorCode.UNKNOWN_KIND,
+                    recovery: UNKNOWN_KIND_RECOVERY,
+                });
             }
             const stepCount = deps.recordings.stepCount(name);
             const compiled = deps.recordings.getCompiled(name) !== undefined;
             if (stepCount === undefined && !compiled) {
-                return Promise.resolve({ ok: false, code: AnnotationErrorCode.NO_ACTIVE_RECORDING });
+                return Promise.resolve({
+                    ok: false,
+                    code: AnnotationErrorCode.NO_ACTIVE_RECORDING,
+                    recovery: RECOVERY.MISSING_RECORDING,
+                });
             }
             const outcome = compileAnnotation(parsed.data, stepCount ?? 0);
             if (!outcome.result.ok)
@@ -133,4 +152,3 @@ export const ANNOTATE_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=annotate-tools.js.map

package/dist/flows/annotate.d.ts

@@ -19,4 +19,3 @@ export declare function compileAnnotation(a: Annotation, stepCount: number): Ann
  * e.g. `will assert signal diff:shown`. The leading word is the named COMPILED_PREDICATE_PREFIX.
  */
 export declare function describeCompiled(a: Annotation): string;
-//# sourceMappingURL=annotate.d.ts.map

package/dist/flows/annotate.js

@@ -131,4 +131,3 @@ export function describeCompiled(a) {
             return `${COMPILED_PREDICATE_PREFIX} intent: ${a.text}`;
     }
 }
-//# sourceMappingURL=annotate.js.map

package/dist/flows/annotation-store.d.ts

@@ -20,4 +20,3 @@ export declare class AnnotationStore {
     /** Drop a recording's annotations (called after reticle_flow_save folds them onto disk). */
     clear(name: string): void;
 }
-//# sourceMappingURL=annotation-store.d.ts.map

package/dist/flows/annotation-store.js

@@ -48,4 +48,3 @@ export class AnnotationStore {
         this.#byName.delete(name);
     }
 }
-//# sourceMappingURL=annotation-store.js.map

package/dist/flows/assertion-integrity.d.ts

@@ -21,4 +21,3 @@ export interface DowngradeFinding {
  * lives with the affected index.
  */
 export declare function detectDowngrades(before: readonly StepExpect[], after: readonly StepExpect[]): DowngradeFinding[];
-//# sourceMappingURL=assertion-integrity.d.ts.map

package/dist/flows/assertion-integrity.js

@@ -24,4 +24,3 @@ export function detectDowngrades(before, after) {
     }
     return findings;
 }
-//# sourceMappingURL=assertion-integrity.js.map

package/dist/flows/assertion-tiers-store.d.ts

@@ -77,4 +77,3 @@ export declare class AssertionTiersStore {
     /** Record one flow's assertion shape + covered sources after it PASSED. Never breaks a replay. */
     recordPassing(name: string, steps: readonly StepExpect[], sources?: readonly string[]): Promise<void>;
 }
-//# sourceMappingURL=assertion-tiers-store.d.ts.map

package/dist/flows/assertion-tiers-store.js

@@ -96,4 +96,3 @@ export class AssertionTiersStore {
         }
     }
 }
-//# sourceMappingURL=assertion-tiers-store.js.map

package/dist/flows/buddy-status.d.ts

@@ -22,4 +22,3 @@ export interface BuddyStatusInput {
  * `✗ 2 deviations: checkout, billing · 39 nominal · 1 flaky quarantined`
  */
 export declare function formatBuddyStatus(input: BuddyStatusInput): string;
-//# sourceMappingURL=buddy-status.d.ts.map

package/dist/flows/buddy-status.js

@@ -30,4 +30,3 @@ export function formatBuddyStatus(input) {
     }
     return parts.join(' · ');
 }
-//# sourceMappingURL=buddy-status.js.map

package/dist/flows/coverage.d.ts

@@ -25,4 +25,3 @@ export interface Coverage {
     overallPct: number;
 }
 export declare function computeCoverage(declared: DeclaredSurface, exercised: DeclaredSurface): Coverage;
-//# sourceMappingURL=coverage.d.ts.map

package/dist/flows/coverage.js

@@ -19,4 +19,3 @@ export function computeCoverage(declared, exercised) {
     const overallPct = total === 0 ? 100 : Math.round((covered / total) * 100);
     return { testids, signals, flows, overallPct };
 }
-//# sourceMappingURL=coverage.js.map

package/dist/flows/decision.d.ts

@@ -10,4 +10,3 @@ export declare function buildSuiteVerdict(runs: ReadonlyArray<{
     replay: FlowReplayResult;
     flow?: FlowFile;
 }>): SuiteVerdict;
-//# sourceMappingURL=decision.d.ts.map

package/dist/flows/decision.js

@@ -117,4 +117,3 @@ export function buildSuiteVerdict(runs) {
         : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}`;
     return { status, total, passed, failed, summary, failures };
 }
-//# sourceMappingURL=decision.js.map

package/dist/flows/flake-store.d.ts

@@ -17,4 +17,3 @@ export declare class FlakeStore {
     /** The flows currently quarantined as flaky — what the gate excludes from blocking. */
     flakyFlows(): Promise<string[]>;
 }
-//# sourceMappingURL=flake-store.d.ts.map

package/dist/flows/flake-store.js

@@ -56,4 +56,3 @@ export class FlakeStore {
             .map(([flow]) => flow);
     }
 }
-//# sourceMappingURL=flake-store.js.map

package/dist/flows/flake.d.ts

@@ -55,4 +55,3 @@ export declare function recordOutcome(record: FlakeRecord, passed: boolean): Fla
 export declare function isFlaky(record: FlakeRecord, minRuns?: number): boolean;
 /** Observed intermittent-failure rate (0 when too few runs to judge). */
 export declare function flakeRate(record: FlakeRecord): number;
-//# sourceMappingURL=flake.d.ts.map

package/dist/flows/flake.js

@@ -33,4 +33,3 @@ export function isFlaky(record, minRuns = DEFAULT_MIN_FLAKE_RUNS) {
 export function flakeRate(record) {
     return record.runs === 0 ? 0 : record.fails / record.runs;
 }
-//# sourceMappingURL=flake.js.map

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

@@ -49,4 +49,3 @@ export interface FlowAssertionClassification {
     warning?: string;
 }
 export declare function classifyFlowAssertions(flow: FlowFile): FlowAssertionClassification;
-//# sourceMappingURL=flow-classify.d.ts.map

package/dist/flows/flow-classify.js

@@ -88,4 +88,3 @@ export function classifyFlowAssertions(flow) {
         ...(warning !== undefined ? { warning } : {}),
     };
 }
-//# sourceMappingURL=flow-classify.js.map

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

@@ -30,4 +30,3 @@ export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unk
  * documented to work headless), so a missing/unknown session degrades to the global/legacy store.
  */
 export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): string | undefined;
-//# sourceMappingURL=flow-replay-run.d.ts.map

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

@@ -30,11 +30,11 @@ export function flowErrorMessage(code) {
         case FlowErrorCode.INVALID_NAME:
             return 'invalid flow name — use a single safe segment (letters/digits/-/_), no path separators';
         case FlowErrorCode.NOT_FOUND:
-            return 'no such flow on disk — run reticle_flow_list to see saved flows';
+            return 'no such flow on disk — run reticle_flow{action:"list"} to see saved flows';
         case FlowErrorCode.PARSE_FAILED:
             return 'flow file is malformed — fix or regenerate it with reticle_flow_save';
         case FlowErrorCode.NO_RECORDING:
-            return 'no compiled recording by that name — record one (reticle_record_start/stop) first';
+            return 'no compiled recording by that name — record one (reticle_record{action:"start"|"stop"}) first';
     }
 }
 /** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
@@ -216,4 +216,3 @@ export function sessionProjectId(deps, sessionId) {
         return undefined;
     }
 }
-//# sourceMappingURL=flow-replay-run.js.map

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

@@ -1,4 +1,4 @@
-import { type CommandResult, type FlowFile, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
+import { AnchorKind, type CommandResult, type FlowAnchor, type FlowFile, type FlowStepResult, type ReticleEvent, type QueryEmptyHint } from '@reticlehq/core';
 import type { EvalResult, Predicate } from '../events/predicate.js';
 /**
  * The session surface flow-replay needs: QUERY to re-resolve a testid anchor against the live
@@ -40,13 +40,31 @@ export declare function editDistance(a: string, b: string): number;
  */
 export declare function nearestTestid(missing: string, present: string[]): string | null;
 /** Injected sleeper so tests drive replay with a no-op clock; production waits on a real timer. */
-type Sleep = (ms: number) => Promise<void>;
+export type Sleep = (ms: number) => Promise<void>;
 /**
  * True when ≥2 present testids tie at the minimum edit distance to the missing one — `nearest` is
  * then an arbitrary lexical-tiebreak pick, so auto-healing would be a coin-flip between candidates.
  * Such a drift is surfaced (with a nearest) but never auto-healed.
  */
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
+/**
+ * Re-resolve any QUERY against the live DOM, tolerating an in-flight render: QUERY, and while it
+ * returns zero refs, sleep and retry up to ANCHOR_SETTLE_ATTEMPTS. Returns as soon as refs appear,
+ * so a present anchor costs one query; a genuinely missing one costs the full (bounded) settle and
+ * then drifts. The last result's near-miss hint is returned for the drift record.
+ */
+export declare function resolveQuery(session: FlowReplaySession, queryArgs: Record<string, unknown>, sleep: Sleep): Promise<{
+    refs: string[];
+    hint?: QueryEmptyHint;
+}>;
+/** A compact, legible label for a component auto-anchor (component@file:line, or its best part). */
+export declare function componentLabel(anchor: Extract<FlowAnchor, {
+    kind: typeof AnchorKind.COMPONENT;
+}>): string;
+/** QUERY args for a component auto-anchor — source (precise) + component name (coarse) as given. */
+export declare function componentQueryArgs(anchor: Extract<FlowAnchor, {
+    kind: typeof AnchorKind.COMPONENT;
+}>): Record<string, unknown>;
 /**
  * Replay a loaded flow by RE-RESOLVING every step's semantic anchor against the live DOM — never
  * a stale ref. A testid anchor is re-found by reticle_query; a signal anchor waits on a predicate.
@@ -54,5 +72,3 @@ export declare function nearestIsAmbiguous(missing: string, present: string[]):
  * results. This is the "whose fault is it" contract, not a blind "command failed".
  */
 export declare function replayFlow(session: FlowReplaySession, flow: FlowFile, waitForSignal: WaitForSignal, signalTimeoutMs: number, confirmDangerous?: boolean, sleep?: Sleep): Promise<FlowStepResult[]>;
-export {};
-//# sourceMappingURL=flow-replay.d.ts.map

package/dist/flows/flow-replay.js

@@ -1,6 +1,7 @@
 import { AnchorKind, DriftReason, EventType, ReticleCommand, QueryBy, } from '@reticlehq/core';
 import { asRecord, asString } from '../tools/tools-helpers.js';
 import { replayActionArgs, ambiguousTestidNote, queryRefs } from './replay.js';
+import { runRoleStep, runComponentStep } from './flow-step-runners.js';
 import { ReticleTool } from '../tools/tool-names.js';
 /**
  * A single ASCII-ish edit distance (case-insensitive). Small inputs (testids), so O(n*m) is fine.
@@ -124,7 +125,7 @@ function testidDrift(value, hint) {
  * so a present anchor costs one query; a genuinely missing one costs the full (bounded) settle and
  * then drifts. The last result's near-miss hint is returned for the drift record.
  */
-async function resolveQuery(session, queryArgs, sleep) {
+export async function resolveQuery(session, queryArgs, sleep) {
     let last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
     for (let attempt = 1; last.refs.length === 0 && attempt < ANCHOR_SETTLE_ATTEMPTS; attempt += 1) {
         await sleep(ANCHOR_SETTLE_DELAY_MS);
@@ -196,7 +197,7 @@ function summarizeConsequence(events) {
     return parts.length > 0 ? parts.join('; ') : undefined;
 }
 /** A compact, legible label for a component auto-anchor (component@file:line, or its best part). */
-function componentLabel(anchor) {
+export function componentLabel(anchor) {
     if (anchor.source !== undefined) {
         const base = anchor.source.file.split('/').pop() ?? anchor.source.file;
         const loc = `${base}:${anchor.source.line}`;
@@ -215,7 +216,7 @@ function anchorLabel(anchor) {
     return anchor.name ?? anchor.role;
 }
 /** QUERY args for a component auto-anchor — source (precise) + component name (coarse) as given. */
-function componentQueryArgs(anchor) {
+export function componentQueryArgs(anchor) {
     const args = { by: QueryBy.COMPONENT };
     if (anchor.component !== undefined)
         args['component'] = anchor.component;
@@ -223,45 +224,6 @@ function componentQueryArgs(anchor) {
         args['source'] = anchor.source;
     return args;
 }
-/** Run one component-anchored step: re-resolve via QUERY by:'component', ACT on the live ref, else drift. */
-async function runComponentStep(session, step, index, anchor, confirmDangerous, sleep) {
-    const label = componentLabel(anchor);
-    const { refs } = await resolveQuery(session, componentQueryArgs(anchor), sleep);
-    if (refs.length === 0) {
-        return {
-            step: index,
-            tool: step.tool,
-            anchor: label,
-            ok: false,
-            drift: {
-                reasonKind: DriftReason.COMPONENT_NOT_FOUND,
-                reason: `component anchor "${label}" not found`,
-                anchor: label,
-                nearest: null,
-            },
-        };
-    }
-    const ref = refs[0] ?? '';
-    // Attribute the step's effects to the step. Without this window they arrive with no actionId and are
-    // learned as ambient churn on the very regions the flow exercises.
-    session.beginAction?.(ReticleTool.FLOW_REPLAY, { ref, action: step.action ?? '' });
-    let act;
-    try {
-        act = await session.command(ReticleCommand.ACT, {
-            ref,
-            action: step.action ?? '',
-            args: replayActionArgs(step.args, confirmDangerous),
-        });
-    }
-    finally {
-        // Close on every exit so a throwing step cannot leak the window onto the next step's events.
-        session.finishAction?.();
-    }
-    const result = { step: index, tool: step.tool, anchor: label, ok: act.ok };
-    if (!act.ok)
-        result.error = act.error ?? 'command failed';
-    return result;
-}
 /** Run one testid-anchored step: re-resolve via QUERY, then ACT on the live ref, else drift. */
 async function runTestidStep(session, step, index, value, dynamic, confirmDangerous, sleep) {
     const { refs, hint } = await resolveTestid(session, value, sleep);
@@ -393,6 +355,11 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
         else if (step.anchor.kind === AnchorKind.COMPONENT) {
             result = await runComponentStep(session, step, index, step.anchor, confirmDangerous, sleep);
         }
+        else if (step.anchor.kind === AnchorKind.ROLE && step.anchor.name !== undefined) {
+            // A NAMED role anchor addresses one element. The nameless one is the degraded placeholder and
+            // keeps its old path, where it fails legibly rather than querying a role as if it were a testid.
+            result = await runRoleStep(session, step, index, step.anchor, confirmDangerous, sleep);
+        }
         else {
             result = await runTestidStep(session, step, index, label, dynamic, confirmDangerous, sleep);
         }
@@ -422,4 +389,3 @@ export async function replayFlow(session, flow, waitForSignal, signalTimeoutMs,
     }
     return results;
 }
-//# sourceMappingURL=flow-replay.js.map

package/dist/flows/flow-report.d.ts

@@ -20,4 +20,3 @@ interface FlowReportInput {
 }
 export declare function buildFlowReport(input: FlowReportInput): string;
 export {};
-//# sourceMappingURL=flow-report.d.ts.map

package/dist/flows/flow-report.js

@@ -104,4 +104,3 @@ export function buildFlowReport(input) {
     out.push('');
     return out.join('\n');
 }
-//# sourceMappingURL=flow-report.js.map

package/dist/flows/flow-scope.d.ts

@@ -22,4 +22,3 @@ export declare function flowInProjectScope(flowProjectId: string | undefined, se
  * flows starting from a non-testid anchor get a chip with no `start` (shown on every page).
  */
 export declare function buildFlowChips(flows: readonly FlowFile[], sessionProjectId: string | undefined): FlowChip[];
-//# sourceMappingURL=flow-scope.d.ts.map

package/dist/flows/flow-scope.js

@@ -31,4 +31,3 @@ export function buildFlowChips(flows, sessionProjectId) {
     }
     return chips;
 }
-//# sourceMappingURL=flow-scope.js.map

package/dist/flows/flow-sources.d.ts

@@ -17,4 +17,3 @@ export interface NamedFlow {
 export declare function toFlowSources(flows: readonly NamedFlow[]): FlowSources[];
 /** Which saved flows a set of changed files affects — the derivation + index in one call. */
 export declare function affectedSavedFlows(flows: readonly NamedFlow[], changedFiles: readonly string[]): AffectedResult;
-//# sourceMappingURL=flow-sources.d.ts.map