@reticlehq/server 2.0.0

package/dist/flows/decision.js

@@ -0,0 +1,111 @@
+import { AnchorKind, ReplayStatus, } from '@reticlehq/core';
+import { classifyFlowAssertions } from './flow-classify.js';
+/**
+ * Turn a replay result into the autonomy DECISION envelope — the judgement a human reviewer used to
+ * make, expressed so a coding agent can act on it without one. Pure: no IO, no clock.
+ *
+ *   pass  → intent held; next action is none (or "add a consequence oracle" if the flow asserts nothing).
+ *   drift → a locator/anchor missed; point at WHERE (file:line from the source anchor) + a rebind hint.
+ *   fail  → an action ran but its consequence/success oracle didn't fire (green-but-wrong) — check the handler.
+ */
+/** The first step that drifted or failed (drift takes precedence as the legible cause). */
+function failingStep(steps) {
+    return steps.find((s) => s.drift !== undefined) ?? steps.find((s) => !s.ok);
+}
+/** `file:line` for a step, preferring the recorded component anchor's source, else the live page. */
+function whereInSource(step, flow) {
+    const anchor = flow?.steps[step.step]?.anchor;
+    if (anchor?.kind === AnchorKind.COMPONENT && anchor.source !== undefined) {
+        return `${anchor.source.file}:${anchor.source.line}`;
+    }
+    return step.page;
+}
+export function buildDecision(result, flow) {
+    const { name, status, steps } = result;
+    if (status === ReplayStatus.OK) {
+        // Green — but is it green-for-the-right-reason? A flow that asserts no consequence can pass while
+        // broken, so the honest next action is to add one.
+        const grade = flow !== undefined ? classifyFlowAssertions(flow) : undefined;
+        const verifiesOutcome = grade?.hasConsequenceAssertion === true;
+        const intent = flow?.intent;
+        return {
+            verdict: 'pass',
+            summary: intent !== undefined
+                ? `"${name}" passed — intent "${intent}" ${verifiesOutcome ? 'verified' : 'NOT asserted'}.`
+                : `"${name}" passed (${steps.length} steps).`,
+            nextAction: verifiesOutcome
+                ? 'none — the flow held and its consequence was observed.'
+                : 'add a consequence assertion (assert-signal / success-state) so this flow can fail when the feature breaks.',
+        };
+    }
+    const step = failingStep(steps);
+    const where = step !== undefined ? whereInSource(step, flow) : undefined;
+    if (status === ReplayStatus.DRIFT && step?.drift !== undefined) {
+        const { drift } = step;
+        const fix = drift.nearest !== null && drift.ambiguous !== true
+            ? `rebind the anchor to "${drift.nearest}" (closest survivor)`
+            : drift.nearest !== null
+                ? `candidates exist (e.g. "${drift.nearest}") but are ambiguous — choose deliberately`
+                : undefined;
+        return {
+            verdict: 'drift',
+            summary: `"${name}" drifted at step ${step.step} (${step.anchor}).`,
+            whatChanged: drift.reason,
+            ...(where !== undefined ? { whereInSource: where } : {}),
+            ...(fix !== undefined ? { suggestedFix: fix } : {}),
+            nextAction: fix !== undefined
+                ? `${fix}, or update the flow if the change was intended.`
+                : `inspect ${where ?? 'the step'} — the anchored element is gone; rebind or update the flow.`,
+        };
+    }
+    // status error: an action failed, or the success oracle was not satisfied (green-but-wrong).
+    const message = result.error?.message ?? step?.error ?? 'the flow failed';
+    const isSuccessOracle = step?.tool === 'success';
+    return {
+        verdict: 'fail',
+        summary: `"${name}" failed${step !== undefined ? ` at step ${step.step} (${step.anchor})` : ''}.`,
+        whatChanged: message,
+        ...(where !== undefined ? { whereInSource: where } : {}),
+        nextAction: isSuccessOracle
+            ? 'the steps ran but the business outcome never fired — check the handler/effect behind the action, not the locator.'
+            : 'the action could not complete — check the element state and the handler at the step above.',
+    };
+}
+/** Map a replay status to the suite verdict's three-state outcome. */
+function suiteVerdictOf(status) {
+    if (status === ReplayStatus.OK)
+        return 'pass';
+    return status === ReplayStatus.DRIFT ? 'drift' : 'fail';
+}
+/**
+ * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
+ * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
+ * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
+ * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
+ */
+export function buildSuiteVerdict(runs) {
+    const failures = [];
+    let passed = 0;
+    for (const { replay, flow } of runs) {
+        if (replay.status === ReplayStatus.OK) {
+            passed += 1;
+            continue;
+        }
+        const decision = replay.decision ?? buildDecision(replay, flow);
+        const row = { flow: replay.name, verdict: suiteVerdictOf(replay.status) };
+        if (decision.whatChanged !== undefined)
+            row.whatChanged = decision.whatChanged;
+        if (decision.whereInSource !== undefined)
+            row.whereInSource = decision.whereInSource;
+        row.nextAction = decision.nextAction;
+        failures.push(row);
+    }
+    const total = runs.length;
+    const failed = failures.length;
+    const status = failed === 0 ? 'pass' : 'fail';
+    const summary = failed === 0
+        ? `all ${total} flow${total === 1 ? '' : 's'} pass`
+        : `${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/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../../src/flows/decision.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,52 @@
+/**
+ * Classify whether a flow asserts an observable CONSEQUENCE or is "assertion-free" / presence-only.
+ *
+ * Why this exists (grounded in real testing behavior):
+ *  - Martin Fowler, *Assertion-Free Testing*: teams hit 100% coverage with tests that "weren't any
+ *    assertions" — green, but verifying nothing.
+ *  - Kent C. Dodds, *Make Your Test Fail*: a test that doesn't fail when you break the code gives
+ *    false security.
+ *  - Self-healing vendors (mabl, qate.ai) admit a locator healed to the WRONG element makes a test
+ *    pass green while a real regression ships — but only if the test merely checks presence.
+ *  - AI agents agree with human pass/fail only ~68% of the time (arXiv 2510.02418), so the flow
+ *    itself must carry a real oracle, not rely on the agent eyeballing success.
+ *
+ * For a flow, an FlowExpect can assert a `signal` (app emitted an event), a `net` call, or just an
+ * `element` presence. signal/net are OBSERVABLE CONSEQUENCES — they can't be satisfied by a wrong
+ * element. element-only is WEAK — a healed-but-wrong locator can still satisfy it. A flow with no
+ * expect on any step and no success end-condition asserts nothing at all.
+ *
+ * Pure: no IO, no clock.
+ */
+import type { FlowFile } from '@reticlehq/core';
+export declare const FlowAssertionGrade: {
+    /** At least one step (or the success end-condition) asserts a signal/network consequence. */
+    readonly ASSERTED: "asserted";
+    /** Only element-presence checks — a healed-but-wrong locator could still pass. */
+    readonly PRESENCE_ONLY: "presence-only";
+    /** Performs actions but asserts nothing observable — passes even if the feature is broken. */
+    readonly ASSERTION_FREE: "assertion-free";
+};
+export type FlowAssertionGrade = (typeof FlowAssertionGrade)[keyof typeof FlowAssertionGrade];
+export interface FlowAssertionClassification {
+    grade: FlowAssertionGrade;
+    /** True when at least one signal/net assertion exists (step-level or success). */
+    hasConsequenceAssertion: boolean;
+    totalSteps: number;
+    consequenceSteps: number;
+    weakSteps: number;
+    successIsConsequence: boolean;
+    /** The flow's declared business goal, if any (the intent annotation). */
+    intent?: string;
+    /**
+     * True only when the flow BOTH declares a business intent AND asserts an observable business
+     * OUTCOME (a consequence — signal/net). This is the "intent + outcome oracle": a flow earns
+     * `intentVerified` when it can actually fail if its declared goal stops being met. A flow with an
+     * intent but only presence-only checks is the dangerous case — it claims a goal it cannot verify.
+     */
+    intentVerified: boolean;
+    /** Present for presence-only / assertion-free flows: how to make the flow a real test. */
+    warning?: string;
+}
+export declare function classifyFlowAssertions(flow: FlowFile): FlowAssertionClassification;
+//# sourceMappingURL=flow-classify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-classify.d.ts","sourceRoot":"","sources":["../../src/flows/flow-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAc,QAAQ,EAAY,MAAM,iBAAiB,CAAC;AAEtE,eAAO,MAAM,kBAAkB;IAC7B,6FAA6F;;IAE7F,kFAAkF;;IAElF,8FAA8F;;CAEtF,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,kFAAkF;IAClF,uBAAuB,EAAE,OAAO,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqCD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,GAAG,2BAA2B,CA0ClF"}

package/dist/flows/flow-classify.js

@@ -0,0 +1,99 @@
+/**
+ * Classify whether a flow asserts an observable CONSEQUENCE or is "assertion-free" / presence-only.
+ *
+ * Why this exists (grounded in real testing behavior):
+ *  - Martin Fowler, *Assertion-Free Testing*: teams hit 100% coverage with tests that "weren't any
+ *    assertions" — green, but verifying nothing.
+ *  - Kent C. Dodds, *Make Your Test Fail*: a test that doesn't fail when you break the code gives
+ *    false security.
+ *  - Self-healing vendors (mabl, qate.ai) admit a locator healed to the WRONG element makes a test
+ *    pass green while a real regression ships — but only if the test merely checks presence.
+ *  - AI agents agree with human pass/fail only ~68% of the time (arXiv 2510.02418), so the flow
+ *    itself must carry a real oracle, not rely on the agent eyeballing success.
+ *
+ * For a flow, an FlowExpect can assert a `signal` (app emitted an event), a `net` call, or just an
+ * `element` presence. signal/net are OBSERVABLE CONSEQUENCES — they can't be satisfied by a wrong
+ * element. element-only is WEAK — a healed-but-wrong locator can still satisfy it. A flow with no
+ * expect on any step and no success end-condition asserts nothing at all.
+ *
+ * Pure: no IO, no clock.
+ */
+export const FlowAssertionGrade = {
+    /** At least one step (or the success end-condition) asserts a signal/network consequence. */
+    ASSERTED: 'asserted',
+    /** Only element-presence checks — a healed-but-wrong locator could still pass. */
+    PRESENCE_ONLY: 'presence-only',
+    /** Performs actions but asserts nothing observable — passes even if the feature is broken. */
+    ASSERTION_FREE: 'assertion-free',
+};
+const ASSERTION_FREE_WARNING = 'This flow performs actions but asserts no observable consequence — 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).';
+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.';
+/** signal, net, or state present → the expect verifies a consequence a wrong element cannot fake. */
+function expectIsConsequence(e) {
+    return (e !== undefined && (e.signal !== undefined || e.net !== undefined || e.state !== undefined));
+}
+/** element-only (no signal/net/state) → presence check, weak. */
+function expectIsWeak(e) {
+    return (e !== undefined &&
+        e.element !== undefined &&
+        e.signal === undefined &&
+        e.net === undefined &&
+        e.state === undefined);
+}
+/** Walk steps + act_sequence sub-steps so an expect on either level is counted. */
+function flattenSteps(steps) {
+    const out = [];
+    for (const s of steps) {
+        out.push(s);
+        if (s.steps !== undefined)
+            out.push(...flattenSteps(s.steps));
+    }
+    return out;
+}
+export function classifyFlowAssertions(flow) {
+    const all = flattenSteps(flow.steps);
+    let consequenceSteps = 0;
+    let weakSteps = 0;
+    for (const s of all) {
+        if (expectIsConsequence(s.expect))
+            consequenceSteps++;
+        else if (expectIsWeak(s.expect))
+            weakSteps++;
+    }
+    const successIsConsequence = expectIsConsequence(flow.success);
+    const successIsWeak = expectIsWeak(flow.success);
+    const hasConsequenceAssertion = consequenceSteps > 0 || successIsConsequence;
+    const hasAnyAssertion = hasConsequenceAssertion || weakSteps > 0 || successIsWeak;
+    const intent = flow.intent;
+    const intentVerified = intent !== undefined && hasConsequenceAssertion;
+    let grade;
+    let warning;
+    if (hasConsequenceAssertion) {
+        grade = FlowAssertionGrade.ASSERTED;
+    }
+    else if (hasAnyAssertion) {
+        grade = FlowAssertionGrade.PRESENCE_ONLY;
+        warning = PRESENCE_ONLY_WARNING;
+    }
+    else {
+        grade = FlowAssertionGrade.ASSERTION_FREE;
+        warning = ASSERTION_FREE_WARNING;
+    }
+    // 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;
+    return {
+        grade,
+        hasConsequenceAssertion,
+        totalSteps: all.length,
+        consequenceSteps,
+        weakSteps,
+        successIsConsequence,
+        ...(intent !== undefined ? { intent } : {}),
+        intentVerified,
+        ...(warning !== undefined ? { warning } : {}),
+    };
+}
+//# sourceMappingURL=flow-classify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-classify.js","sourceRoot":"","sources":["../../src/flows/flow-classify.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,15 @@
+import { FlowErrorCode, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
+import type { ToolDeps } from '../tools/tools.js';
+export declare function latestRecordedFlow(events: ReticleEvent[]): {
+    name: string;
+    flow: import('@reticlehq/core').FlowFile;
+} | undefined;
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export declare function flowErrorMessage(code: FlowErrorCode): string;
+/**
+ * Replay one named flow end to end: load → re-resolve+run each step → assert the success oracle →
+ * status + decision. Shared by reticle_flow_replay (single flow) and reticle_flow_verify (whole suite) so
+ * both produce identical FlowReplayResults. Every exit path records a run to project.json.
+ */
+export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowReplayResult>;
+//# sourceMappingURL=flow-replay-run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-replay-run.d.ts","sourceRoot":"","sources":["../../src/flows/flow-replay-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EAKb,KAAK,gBAAgB,EAErB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,iBAAiB,EAAE,QAAQ,CAAA;CAAE,GAAG,SAAS,CAQxE;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAW5D;AA+BD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAyE3B"}

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

@@ -0,0 +1,120 @@
+import { EventType, FLOW_SIGNAL_TIMEOUT_MS, FlowErrorCode, RecordedFlowSchema, ReplayStatus, RunKind, RunStatus, } from '@reticlehq/core';
+import { asString } from '../tools/tools-helpers.js';
+import { replayFlow } from './flow-replay.js';
+import { assertSuccess, dynamicTestids, successLabel, SUCCESS_STEP_TOOL } from './flow-success.js';
+import { buildDecision } from './decision.js';
+import { waitForPredicate } from '../events/predicate.js';
+export function latestRecordedFlow(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event?.type !== EventType.FLOW_RECORDED)
+            continue;
+        const parsed = RecordedFlowSchema.safeParse(event.data);
+        if (parsed.success)
+            return { name: parsed.data.name, flow: parsed.data.flow };
+    }
+    return undefined;
+}
+/** Map a structured FlowErrorCode to a legible one-line message for the agent. */
+export function flowErrorMessage(code) {
+    switch (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';
+        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';
+    }
+}
+/** Map the wire ReplayStatus onto the persisted RunStatus (ok→pass). */
+function replayToRunStatus(status) {
+    switch (status) {
+        case ReplayStatus.OK:
+            return RunStatus.PASS;
+        case ReplayStatus.DRIFT:
+            return RunStatus.DRIFT;
+        case ReplayStatus.ERROR:
+            return RunStatus.ERROR;
+    }
+}
+/** Append a flow-replay outcome to .reticle/project.json (never throws into replay). */
+async function recordReplayRun(deps, name, status, driftSteps, durationMs) {
+    await deps.project.recordRun({
+        kind: RunKind.FLOW_REPLAY,
+        name,
+        status: replayToRunStatus(status),
+        evidence: { driftSteps },
+        durationMs,
+    });
+}
+/**
+ * Replay one named flow end to end: load → re-resolve+run each step → assert the success oracle →
+ * status + decision. Shared by reticle_flow_replay (single flow) and reticle_flow_verify (whole suite) so
+ * both produce identical FlowReplayResults. Every exit path records a run to project.json.
+ */
+export async function replayNamedFlow(deps, args) {
+    const startedAt = deps.now();
+    const name = asString(args['flowName']) ?? '';
+    // Resolve within the connecting app's scope so a shared daemon replays THIS project's flow, not a
+    // same-named flow from another app. Safe-resolve: a missing session degrades to the global store,
+    // and the load-then-session order (unchanged) still surfaces a not-found before a no-session error.
+    let projectId;
+    try {
+        projectId = deps.sessions.resolve(asString(args['sessionId'])).projectId;
+    }
+    catch {
+        projectId = undefined;
+    }
+    const loaded = await deps.flows.load(name, projectId);
+    if (!loaded.ok) {
+        await recordReplayRun(deps, name, ReplayStatus.ERROR, 0, deps.now() - startedAt);
+        return {
+            name,
+            status: ReplayStatus.ERROR,
+            steps: [],
+            error: { code: loaded.code, message: flowErrorMessage(loaded.code) },
+        };
+    }
+    const session = deps.sessions.resolve(asString(args['sessionId']));
+    // Floor the success oracle at the start of THIS replay so a stale signal from a prior run
+    // in the same session can't fake a pass.
+    const replayFloor = session.elapsed();
+    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, args['confirmDangerous'] === true);
+    // "green means intent satisfied": when every step ran clean, assert the flow's success
+    // end-condition as a real consequence. A signal/net success that never fires FAILS the replay
+    // even though all locators resolved — the regression a healed-but-wrong locator ships green.
+    const stepsClean = steps.length > 0 && steps.every((s) => s.ok && s.drift === undefined);
+    if (stepsClean && loaded.value.success !== undefined) {
+        const verdict = await assertSuccess(session, loaded.value.success, dynamicTestids(loaded.value), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, replayFloor);
+        const row = {
+            step: steps.length,
+            tool: SUCCESS_STEP_TOOL,
+            anchor: successLabel(loaded.value.success),
+            ok: verdict.pass,
+            ...(verdict.pass ? {} : { error: verdict.failureReason ?? 'flow.success not satisfied' }),
+        };
+        steps.push(row);
+    }
+    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);
+    const failed = steps.find((step) => !step.ok && step.drift === undefined);
+    if (failed !== undefined) {
+        const errored = {
+            name,
+            status,
+            steps,
+            error: { code: ReplayStatus.ERROR, message: failed.error ?? 'flow action failed' },
+        };
+        errored.decision = buildDecision(errored, loaded.value);
+        return errored;
+    }
+    const result = { name, status, steps };
+    if (status !== ReplayStatus.OK)
+        result.decision = buildDecision(result, loaded.value);
+    return result;
+}
+//# sourceMappingURL=flow-replay-run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-replay-run.js","sourceRoot":"","sources":["../../src/flows/flow-replay-run.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,49 @@
+import { type CommandResult, type FlowFile, type FlowStepResult, type ReticleEvent } 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
+ * DOM, ACT to run the step, and the event/onEvent pair so a signal anchor can wait on a predicate
+ * (via the injected waitForPredicate). Mirrors PredicateSession so the same fake drives both.
+ */
+export interface FlowReplaySession {
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+    eventsSince(cursor: number): ReticleEvent[];
+    onEvent(listener: (event: ReticleEvent) => void): () => void;
+    /** Buffer clock (ms since connect) — required by the predicate engine's `settled` check. */
+    elapsed(): number;
+}
+/**
+ * The injected predicate-waiter (the real waitForPredicate) — reused, never reimplemented.
+ * `since` is the event-time floor (default 0 = whole buffer): pass the cursor captured before a
+ * replay so the success oracle can't be satisfied by a stale signal from a prior replay/run.
+ */
+export type WaitForSignal = (session: FlowReplaySession, predicate: Predicate, timeoutMs: number, since?: number) => Promise<EvalResult>;
+/**
+ * A single ASCII-ish edit distance (case-insensitive). Small inputs (testids), so O(n*m) is fine.
+ * Exported so the heal proposal layer derives its confidence from the SAME distance used to
+ * pick `nearest` — no second, divergent heuristic enters the trust boundary.
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The closest present testid to a missing one, by case-insensitive edit distance, ties broken
+ * by shortest length then lexically. Returns null only when nothing is present — so a drift
+ * record always names a fix when one exists ("whose fault is it": here is the closest survivor).
+ */
+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>;
+/**
+ * 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;
+/**
+ * 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.
+ * On the first anchor MISS the step carries legible drift and replay STOPS, returning the partial
+ * 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-replay.d.ts","sourceRoot":"","sources":["../../src/flows/flow-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,aAAa,EAIlB,KAAK,QAAQ,EAEb,KAAK,cAAc,EACnB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAIpE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9E,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC5C,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC7D,4FAA4F;IAC5F,OAAO,IAAI,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,KACX,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAkB/E;AAYD,mGAAmG;AACnG,KAAK,KAAK,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AA4B3C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAc9E;AA8QD;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,QAAQ,EACd,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,MAAM,EACvB,gBAAgB,UAAQ,EACxB,KAAK,GAAE,KAAiB,GACvB,OAAO,CAAC,cAAc,EAAE,CAAC,CAgD3B"}