@reticlehq/server 2.2.0 → 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

@@ -9,6 +9,10 @@ import { AssertionTiersStore } from './assertion-tiers-store.js';
 import { toFlowSources } from './flow-sources.js';
 import { reportAndAccumulate } from '../journal/deviation-service.js';
 import { EnvelopeStore } from '../journal/envelope-store.js';
+import { homedir } from 'node:os';
+import { syncRunRecordToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { log } from '../log.js';
 export function latestRecordedFlow(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
@@ -26,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). */
@@ -44,15 +48,28 @@ function replayToRunStatus(status) {
             return RunStatus.ERROR;
     }
 }
-/** Append a flow-replay outcome to .reticle/project.json (never throws into replay). */
-async function recordReplayRun(deps, name, status, driftSteps, durationMs) {
+/**
+ * Append a flow-replay outcome to .reticle/project.json (never throws into replay) and, when logged in,
+ * best-effort mirror it to Reticle Cloud so the team's server-side regression history stays current. The
+ * cloud push is fire-and-forget: not logged in → skipped, a network failure is logged and swallowed.
+ */
+async function recordReplayRun(deps, name, status, driftSteps, durationMs, projectId) {
+    const runStatus = replayToRunStatus(status);
     await deps.project.recordRun({
         kind: RunKind.FLOW_REPLAY,
         name,
-        status: replayToRunStatus(status),
+        status: runStatus,
         evidence: { driftSteps },
         durationMs,
     });
+    // Per-project cloud: push memory outcomes only when cloud is attached AND memory sync is enabled.
+    const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
+    if (cloud.config === null || !cloud.policy.memory)
+        return; // not attached / memory disabled → local only
+    const result = await syncRunRecordToCloud({ kind: RunKind.FLOW_REPLAY, name, status: runStatus, at: deps.now(), durationMs }, projectId, cloud.config, (url, init) => fetch(url, init));
+    if (result.outcome !== SyncOutcome.SYNCED) {
+        log('cloud-run-record-sync-failed', { flow: name, status: result.status, error: result.error });
+    }
 }
 /**
  * When a flow records the page its journey started on (`startPath`) and the tab is currently on a
@@ -95,7 +112,7 @@ export async function replayNamedFlow(deps, args) {
     }
     const loaded = await deps.flows.load(name, projectId);
     if (!loaded.ok) {
-        await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt);
+        await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt, projectId);
         return {
             name,
             status: ReplayStatus.ERROR,
@@ -129,7 +146,7 @@ export async function replayNamedFlow(deps, args) {
     const driftSteps = steps.filter((s) => s.drift !== undefined).length;
     const allOk = steps.every((s) => s.ok);
     const status = driftSteps > 0 ? ReplayStatus.DRIFT : allOk ? ReplayStatus.OK : ReplayStatus.ERROR;
-    await recordReplayRun(deps, name, status, driftSteps, deps.now() - startedAt);
+    await recordReplayRun(deps, name, status, driftSteps, deps.now() - startedAt, projectId);
     // Anti-reward-hacking baseline: record what this flow asserted ONLY when it passed clean. A
     // failing run must never become the baseline a later weakening is measured against.
     if (status === ReplayStatus.OK) {
@@ -199,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