@reticlehq/server 2.14.0 → 3.2.0

package/dist/language/flows/heal-run.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The self-heal state machine — load → replay → collect confident proposals → (apply ? verify+write:
+ * dry). Split out of flow-tools.ts (which keeps only the FLOW_HEAL ToolDef) as a sibling of
+ * flow-replay-run.ts. Never silently rewrites: only proposals that cleared HEAL_CONFIDENCE_MIN are
+ * eligible, and only when apply:true; before persisting it re-verifies the success consequence still
+ * fires (heal the locator, never the intent).
+ */
+import { type FlowHealResult } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/**
+ * Why heal produced no proposal: a floor it consulted, or a kind of drift it cannot rebind.
+ *
+ * Exported for its own test — the distinction is a sentence a reader ACTS on, and the wrong one
+ * sends them to lower a threshold that had no part in the refusal.
+ */
+export declare function unhealableMessage(reasons: readonly string[]): string;
+export declare function healFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowHealResult>;

package/dist/language/flows/heal-run.js

@@ -0,0 +1,186 @@
+/**
+ * The self-heal state machine — load → replay → collect confident proposals → (apply ? verify+write:
+ * dry). Split out of flow-tools.ts (which keeps only the FLOW_HEAL ToolDef) as a sibling of
+ * flow-replay-run.ts. Never silently rewrites: only proposals that cleared HEAL_CONFIDENCE_MIN are
+ * eligible, and only when apply:true; before persisting it re-verifies the success consequence still
+ * fires (heal the locator, never the intent).
+ */
+import { FLOW_SIGNAL_TIMEOUT_MS, HEAL_CONFIDENCE_MIN, HealStatus, ReplayStatus, } from '@reticlehq/core';
+import { asString, DriftReason } from '@reticlehq/core';
+import { waitForPredicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import { replayFlow } from './flow-replay.js';
+import { applyHealChanges, collectProposals } from './heal.js';
+import { healPrecondition } from './heal-precondition.js';
+import { assertSuccess, dynamicTestids, successLabel } from './flow-success.js';
+import { flowErrorMessage, sessionProjectId } from './flow-replay-run.js';
+import { flowsForSession } from './flow-store-for-session.js';
+const HEAL_MESSAGES = {
+    NOTHING: 'nothing to heal — every anchor resolved on replay',
+    HEALED: "rewrote drifted testid anchors to their nearest surviving match and re-verified the flow's success consequence still fires",
+    DRIFT_DRY: 'confident rebind(s) proposed — re-run with apply:true to write them to disk',
+    UNHEALABLE: `drift found, but no nearest match cleared the confidence floor (HEAL_CONFIDENCE_MIN=${HEAL_CONFIDENCE_MIN}); file left untouched; add a data-testid or fix the flow by hand`,
+    /**
+     * Heal can only rebind a locator, and not every drift is one.
+     *
+     * Reported as a confidence failure until it was measured: a flow whose EXPECTATION stopped
+     * appearing exits `proposeRebindWith` at its first line, before any candidate is scored, and the
+     * old message still named the floor — so replay confidently naming a survivor and heal citing a
+     * threshold read as the two disagreeing about the same candidate. They were answering different
+     * questions.
+     */
+    NOT_A_REBIND: 'drift found, but none of it is a renamed locator, so there is nothing to rebind — the anchors resolved and what failed was what the steps assert afterwards. The confidence floor was never consulted. Fix the app so the consequence fires again, or update the step expectations by hand',
+    HEALED_UNVERIFIED: "rewrote drifted testid anchors. This flow declares its consequences per STEP rather than as a flow `success`, so the rebind was not re-verified end to end — the steps will assert on the next replay, but nothing proved the healed flow still reaches its outcome. Set the flow's `success` (reticle_annotate) to have future heals re-verified before they are written.",
+    CONSEQUENCE_BROKEN: 'rebind resolves the drifted locator to a surviving element, but the healed flow no longer satisfies its success consequence — refusing to write (a heal that loses the intent would ship a green-but-dead test). Fix by hand and verify',
+};
+/**
+ * Why heal produced no proposal: a floor it consulted, or a kind of drift it cannot rebind.
+ *
+ * Exported for its own test — the distinction is a sentence a reader ACTS on, and the wrong one
+ * sends them to lower a threshold that had no part in the refusal.
+ */
+export function unhealableMessage(reasons) {
+    const rebindable = reasons.some((reason) => DriftReason.TESTID_NOT_FOUND === reason);
+    return rebindable ? HEAL_MESSAGES.UNHEALABLE : HEAL_MESSAGES.NOT_A_REBIND;
+}
+function toChange(proposal) {
+    return { step: proposal.step, from: proposal.from, to: proposal.to };
+}
+export async function healFlow(deps, args) {
+    const name = asString(args['flowName']) ?? '';
+    const apply = true === args['apply'];
+    const projectId = sessionProjectId(deps, asString(args['sessionId']));
+    const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
+    if (!loaded.ok) {
+        return {
+            name,
+            status: HealStatus.ERROR,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message: flowErrorMessage(loaded.code, loaded.detail),
+            error: { code: loaded.code, message: flowErrorMessage(loaded.code, loaded.detail) },
+        };
+    }
+    const session = deps.sessions.resolve(asString(args['sessionId']));
+    const steps = await replayFlow(session, loaded.value, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
+    const drifted = steps.some((s) => s.drift !== undefined);
+    const failed = steps.find((s) => !s.ok && s.drift === undefined);
+    if (failed !== undefined) {
+        const message = failed.error ?? 'flow replay failed before an anchor could be healed';
+        return {
+            name,
+            status: HealStatus.ERROR,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message,
+            error: { code: ReplayStatus.ERROR, message },
+        };
+    }
+    if (!drifted) {
+        return {
+            name,
+            status: HealStatus.NOTHING_TO_HEAL,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message: HEAL_MESSAGES.NOTHING,
+        };
+    }
+    const proposals = collectProposals(steps);
+    if (0 === proposals.length) {
+        return {
+            name,
+            status: HealStatus.UNHEALABLE,
+            applied: false,
+            proposals: [],
+            changed: [],
+            message: unhealableMessage(steps.flatMap((step) => (step.drift === undefined ? [] : [step.drift.reasonKind]))),
+        };
+    }
+    if (!apply) {
+        return {
+            name,
+            status: HealStatus.DRIFT,
+            applied: false,
+            proposals,
+            changed: [],
+            message: HEAL_MESSAGES.DRIFT_DRY,
+        };
+    }
+    /*
+     * A flow with no consequence may not be healed at all.
+     *
+     * The rebind is checked by the CONSEQUENCE: a locator healed to the wrong element cannot fake a
+     * signal, a request or a store value. A flow that asserts nothing has nothing to check it against,
+     * so healing it yields a flow that passes forever and proves nothing — worse than the drift it
+     * replaced, because the drift was at least visible. Presence-only is refused for the sharpest
+     * version of the same reason: "the element is there" is exactly what a wrong rebind makes true.
+     *
+     * This used to heal and say "the rebind is unverified" in the message, which put the one sentence
+     * that mattered where an agent reads it after banking a green.
+     *
+     * Refused at the WRITE, not before the replay: the drift is real, and a human may well want to
+     * fix it by hand, so the proposal still travels. Same split as CONSEQUENCE_BROKEN.
+     */
+    const unfalsifiable = healPrecondition(loaded.value);
+    if (unfalsifiable !== undefined) {
+        return {
+            name,
+            status: unfalsifiable.status,
+            applied: false,
+            proposals,
+            changed: [],
+            message: unfalsifiable.message,
+        };
+    }
+    // Heal the locator, never the intent: verify the rebind on a healed copy before persisting. A rebound
+    // testid can resolve to a real but WRONG element that no longer triggers the success consequence.
+    const { flow: healed } = applyHealChanges(loaded.value, proposals.map(toChange));
+    if (healed.success !== undefined) {
+        // Verify from the FIRST DRIFTED step forward, not the whole flow — re-running the prefix would
+        // double-execute a non-idempotent flow (a false CONSEQUENCE_BROKEN that refuses a correct heal).
+        const firstDrift = steps.findIndex((s) => s.drift !== undefined);
+        const toVerify = firstDrift > 0 ? { ...healed, steps: healed.steps.slice(firstDrift) } : healed;
+        // Floor the success oracle at the start of the VERIFY replay so the earlier drift replay's signal
+        // cannot fake the verification.
+        const verifyFloor = session.elapsed();
+        const verifySteps = await replayFlow(session, toVerify, waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, true === args['confirmDangerous']);
+        const verifyClean = verifySteps.length > 0 && verifySteps.every((s) => s.ok && s.drift === undefined);
+        const verdict = verifyClean
+            ? await assertSuccess(session, healed.success, dynamicTestids(healed), waitForPredicate, FLOW_SIGNAL_TIMEOUT_MS, verifyFloor)
+            : { pass: false, failureReason: 'healed flow did not replay cleanly' };
+        if (!verdict.pass) {
+            return {
+                name,
+                status: HealStatus.CONSEQUENCE_BROKEN,
+                applied: false,
+                proposals,
+                changed: [],
+                message: `${HEAL_MESSAGES.CONSEQUENCE_BROKEN} (${successLabel(healed.success)}: ${verdict.failureReason ?? 'not satisfied'})`,
+            };
+        }
+    }
+    // Healing WRITES, so it must land where the load came from — a heal that read the app's flow and
+    // wrote the daemon's copy would silently fork the two.
+    const written = await flowsForSession(deps, projectId).flows.heal(name, proposals.map(toChange), projectId);
+    if (!written.ok) {
+        return {
+            name,
+            status: HealStatus.ERROR,
+            applied: false,
+            proposals,
+            changed: [],
+            message: flowErrorMessage(written.code),
+            error: { code: written.code, message: flowErrorMessage(written.code) },
+        };
+    }
+    return {
+        name,
+        status: HealStatus.HEALED,
+        applied: written.value.changed.length > 0,
+        proposals,
+        changed: written.value.changed,
+        message: loaded.value.success !== undefined ? HEAL_MESSAGES.HEALED : HEAL_MESSAGES.HEALED_UNVERIFIED,
+    };
+}

package/dist/language/flows/heal.js

@@ -0,0 +1,97 @@
+import { AnchorKind, DriftReason, HEAL_CONFIDENCE_MIN, } from '@reticlehq/core';
+import { editDistance } from './flow-anchor.js';
+/**
+ * The pure proposal layer. It turns a `Drift` (with its already-
+ * computed nearest testid) into a concrete, confidence-scored rebind. No new heuristics enter the
+ * trust boundary: confidence is derived only from the existing case-insensitive edit distance, so
+ * the "never silently rewrite a bad guess" invariant lives in a single numeric floor
+ * (HEAL_CONFIDENCE_MIN). Separated from the reticle_flow_heal tool so it is unit-testable without a
+ * live session or the filesystem.
+ *
+ * FIRST CUT: testid-anchor rebinds only, scored by string distance.
+ * Future: rebind by alternate anchors (role+name, signal correlation); multi-candidate
+ * ranking when several testids tie; confidence beyond string distance (DOM-position / a11y-role
+ * agreement, contract-diff awareness); healing degraded (ROLE-unresolved) steps; signal-drift
+ * healing (signals have no nearest-match today — intentionally nearest:null, no proposal).
+ */
+/**
+ * Normalize a case-insensitive edit distance to a (0,1] confidence: 1 on an exact match, decaying
+ * with distance relative to the longer string's length. Always clamped to (0,1] — never 0, never
+ * above 1 — so a present-but-distant testid is still legibly scored (below the floor), not dropped.
+ */
+export function confidenceFor(from, to) {
+    if (from === to)
+        return 1;
+    const span = Math.max(from.length, to.length);
+    if (0 === span)
+        return 1;
+    const raw = 1 - editDistance(from, to) / span;
+    if (raw >= 1)
+        return 1;
+    if (raw <= 0)
+        return Number.EPSILON;
+    return raw;
+}
+/**
+ * Pure: rewrite the named steps' testid anchors (from→to) and return the new flow plus the changes
+ * that actually applied. A change whose `from` no longer matches that step's testid anchor is
+ * skipped (idempotent / defensive), never throwing. Shared by the on-disk writer (FlowStore.heal)
+ * and the in-memory pre-write verification in reticle_flow_heal, so both rewrite identically.
+ */
+export function applyHealChanges(flow, changes) {
+    const byStep = new Map();
+    for (const change of changes)
+        byStep.set(change.step, change);
+    const applied = [];
+    const steps = flow.steps.map((step, index) => {
+        const change = byStep.get(index);
+        if (change === undefined ||
+            step.anchor.kind !== AnchorKind.TESTID ||
+            step.anchor.value !== change.from) {
+            return step;
+        }
+        applied.push(change);
+        return { ...step, anchor: { kind: AnchorKind.TESTID, value: change.to } };
+    });
+    return { flow: { ...flow, steps }, applied };
+}
+/** Internal: propose with a caller-supplied floor (enables the tunable-confidence API). */
+function proposeRebindWith(drift, step, minConfidence) {
+    if (drift.reasonKind !== DriftReason.TESTID_NOT_FOUND)
+        return undefined;
+    // Never auto-heal an ambiguous drift: when two present testids tie at the minimum distance, the
+    // `nearest` pick is arbitrary, so a rebind would be a coin-flip that can land on the wrong element
+    // and ship a bug green. Surface it (the drift still carries `nearest`) and defer to a human.
+    if (true === drift.ambiguous)
+        return undefined;
+    const to = drift.nearest;
+    if (null === to)
+        return undefined;
+    const confidence = confidenceFor(drift.anchor, to);
+    if (confidence < minConfidence)
+        return undefined;
+    return { step, from: drift.anchor, to, confidence };
+}
+/**
+ * Public compat wrapper — uses HEAL_CONFIDENCE_MIN (the existing default floor).
+ * Prefer collectProposals(steps, minConfidence) for new callers.
+ */
+export function proposeRebind(drift, step) {
+    return proposeRebindWith(drift, step, HEAL_CONFIDENCE_MIN);
+}
+/**
+ * Map step results → confident proposals (skips ok steps, signal drift, and below-floor drift).
+ * Pass minConfidence to tighten (0.9 → near-certain only) or loosen (0.0 → all candidates)
+ * the floor. Defaults to HEAL_CONFIDENCE_MIN (0.5) for backwards compatibility.
+ */
+export function collectProposals(steps, minConfidence = HEAL_CONFIDENCE_MIN) {
+    const proposals = [];
+    for (const step of steps) {
+        if (step.drift === undefined)
+            continue;
+        const proposal = proposeRebindWith(step.drift, step.step, minConfidence);
+        if (proposal !== undefined)
+            proposals.push(proposal);
+    }
+    return proposals;
+}

package/dist/language/flows/mutation-run.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Replay, break the thing the flow watches, replay again, and grade the FLOW.
+ *
+ * This is the loop that turns *"most recorded steps would not notice if the feature broke"* from a
+ * complaint into a number the engine assigns itself. Everything it needs already exists — a realm
+ * that can perturb a driven page, a replay that produces a verdict, and the pure grade. What this
+ * adds is the property that makes running it safe at all.
+ *
+ * **The reversal is the design, not a tidy-up.** A mutation is a real break on a real page. If a
+ * replay throws mid-flight and the break is left behind, the next flow inherits a subject that is
+ * not the subject: every verdict after it is about an app answering 500 to something no developer
+ * broke, and the run reports a cascade of failures with no cause anybody can find. The undo
+ * therefore runs on every path out of here, including the ones nobody planned.
+ *
+ * Pure orchestration: the three capabilities are injected, so this is tested without a browser, a
+ * realm or a flow file — and so it cannot quietly acquire a dependency on any of them.
+ */
+import { MutationOutcome, type Reversal } from 'open-verification';
+export interface MutationTestDeps {
+    /** Replay the flow and report its verdict. */
+    replay(): Promise<'pass' | 'fail'>;
+    /** Break the subject. Rejecting is a refusal, and a refusal is not a result. */
+    mutate(mutation: {
+        kind: string;
+        target?: string;
+    }): Promise<Reversal>;
+    /** Put it back. */
+    revert(): Promise<void>;
+}
+export declare function mutationTest(deps: MutationTestDeps, mutation: {
+    kind: string;
+    target?: string;
+}): Promise<MutationOutcome>;

package/dist/language/flows/mutation-run.js

@@ -0,0 +1,60 @@
+/**
+ * Replay, break the thing the flow watches, replay again, and grade the FLOW.
+ *
+ * This is the loop that turns *"most recorded steps would not notice if the feature broke"* from a
+ * complaint into a number the engine assigns itself. Everything it needs already exists — a realm
+ * that can perturb a driven page, a replay that produces a verdict, and the pure grade. What this
+ * adds is the property that makes running it safe at all.
+ *
+ * **The reversal is the design, not a tidy-up.** A mutation is a real break on a real page. If a
+ * replay throws mid-flight and the break is left behind, the next flow inherits a subject that is
+ * not the subject: every verdict after it is about an app answering 500 to something no developer
+ * broke, and the run reports a cascade of failures with no cause anybody can find. The undo
+ * therefore runs on every path out of here, including the ones nobody planned.
+ *
+ * Pure orchestration: the three capabilities are injected, so this is tested without a browser, a
+ * realm or a flow file — and so it cannot quietly acquire a dependency on any of them.
+ */
+import { gradeMutation, MutationOutcome } from 'open-verification';
+export async function mutationTest(deps, mutation) {
+    let before;
+    try {
+        before = await deps.replay();
+    }
+    catch {
+        return MutationOutcome.INCONCLUSIVE;
+    }
+    /*
+     * A flow that was already failing is inconclusive whatever happens next, so the page is never
+     * broken for it. That is not only a saving: every mutation carries the risk of not being undone,
+     * and the cheapest way to never leave a break behind is not to make one.
+     */
+    if ('pass' !== before)
+        return MutationOutcome.INCONCLUSIVE;
+    try {
+        await deps.mutate(mutation);
+    }
+    catch {
+        // The realm refused. Nothing was applied, so there is nothing to revert — and reverting anyway
+        // would clear rules somebody else installed.
+        return MutationOutcome.INCONCLUSIVE;
+    }
+    try {
+        const after = await deps.replay();
+        return gradeMutation({ before, after });
+    }
+    catch {
+        /*
+         * A replay that threw did not stay green — it said nothing. Grading it SURVIVED would demote a
+         * flow for an error in the harness, which is the mutation score blaming the suite for its own
+         * failure.
+         */
+        return MutationOutcome.INCONCLUSIVE;
+    }
+    finally {
+        // Every path, including the ones above that return early from the try. A revert that itself
+        // fails cannot be fixed from here, and throwing would replace a usable grade with an exception:
+        // the page belongs to the caller, and so does that failure.
+        await deps.revert().catch(() => undefined);
+    }
+}

package/dist/language/flows/narrow-write.d.ts

@@ -0,0 +1,32 @@
+import { type ProjectId, type FlowFile } from '@reticlehq/core';
+import { type FlowResult } from './flow-result.js';
+/**
+ * Change one thing about a saved flow, and write the same file that load resolved.
+ *
+ * The shape two writers need — `heal` rebinding an anchor, `recordLearned` storing what a replay
+ * learned — and which both spelled out separately until one of them got it wrong.
+ *
+ * Three properties, each paid for:
+ *
+ *  - The NAME is guarded before any path is joined, so a traversal name never reaches the disk.
+ *  - The write goes to the path LOAD resolved (nested if the flow lives there, else legacy flat), so
+ *    a change never forks a second copy of a flow.
+ *  - It VALIDATES before writing. `load` validates; a writer that does not authors files its own
+ *    reader rejects — and that is not hypothetical. A cross-step finding is addressed as step -1
+ *    while the schema said non-negative, so the first one written made the flow unloadable forever.
+ *    Replay, heal and the suite all lost it, and it read as user corruption rather than our write.
+ *
+ * Deliberately NOT `saveFlow`, which re-runs intent linking over the whole document and reverted an
+ * intent a replay had just discharged. A whole-document save is not a field update: it re-applies
+ * every rule the document has ever been subject to.
+ */
+export interface NarrowWritePort {
+    load: (name: string, projectId?: ProjectId) => Promise<FlowResult<FlowFile>>;
+    resolvePath: (name: string, projectId?: ProjectId) => Promise<string | null>;
+    write: (path: string, contents: string) => Promise<void>;
+    serialize: (flow: FlowFile) => string;
+}
+export declare function changeInPlace<T>(port: NarrowWritePort, name: string, projectId: ProjectId | undefined, change: (flow: FlowFile) => {
+    next: FlowFile;
+    value: T;
+}): Promise<FlowResult<T>>;

package/dist/language/flows/narrow-write.js

@@ -0,0 +1,26 @@
+import { FlowErrorCode, FlowFileSchema } from '@reticlehq/core';
+import { describeFlowZodFailure } from './flow-expect-grammar.js';
+import { isValidFlowName } from '../../memory/project/dir/reticle-dir.js';
+import { safeProjectId } from './flow-result.js';
+export async function changeInPlace(port, name, projectId, change) {
+    if (!isValidFlowName(name))
+        return { ok: false, code: FlowErrorCode.INVALID_NAME };
+    const pid = safeProjectId(projectId);
+    const loaded = await port.load(name, pid);
+    if (!loaded.ok)
+        return { ok: false, code: loaded.code };
+    const path = await port.resolvePath(name, pid);
+    if (null === path)
+        return { ok: false, code: FlowErrorCode.NOT_FOUND };
+    const { next, value } = change(loaded.value);
+    const parsed = FlowFileSchema.safeParse(next);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            code: FlowErrorCode.PARSE_FAILED,
+            detail: describeFlowZodFailure(parsed.error),
+        };
+    }
+    await port.write(path, port.serialize(parsed.data));
+    return { ok: true, value };
+}

package/dist/language/flows/recording/flake.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+/**
+ * Flake ledger. Trust in the red is the product; one unexplained flake a week kills it. A flow that
+ * fails intermittently at UNCHANGED code is flaky, not a real regression — it must be quarantined
+ * (excluded from gate-blocking) and surfaced for repair, never silently blocking. The caller accrues an
+ * outcome ONLY for unchanged-code replays (a fail after a code change is a legitimate red, not flake).
+ */
+declare const FlakeRecordSchema: z.ZodObject<{
+    runs: z.ZodNumber;
+    fails: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    runs: number;
+    fails: number;
+}, {
+    runs: number;
+    fails: number;
+}>;
+type FlakeRecord = z.infer<typeof FlakeRecordSchema>;
+/** Per-flow map (flow name → record). */
+export type FlakeLedger = Record<string, FlakeRecord>;
+export declare const FlakeFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    flows: z.ZodRecord<z.ZodString, z.ZodObject<{
+        runs: z.ZodNumber;
+        fails: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        runs: number;
+        fails: number;
+    }, {
+        runs: number;
+        fails: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    flows: Record<string, {
+        runs: number;
+        fails: number;
+    }>;
+}, {
+    version: 1;
+    flows: Record<string, {
+        runs: number;
+        fails: number;
+    }>;
+}>;
+export declare function emptyRecord(): FlakeRecord;
+/** Accrue one unchanged-code replay outcome. */
+export declare function recordOutcome(record: FlakeRecord, passed: boolean): FlakeRecord;
+/**
+ * Flaky = enough unchanged-code runs, and it has BOTH passed and failed (intermittent). A flow that
+ * always fails is a real red; one that always passes is healthy; only the mix is flake.
+ */
+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;
+export {};

package/dist/language/flows/recording/recording-backtrack.js

@@ -0,0 +1,73 @@
+/**
+ * A recorded flow that backtracks across pages cannot replay.
+ *
+ * The recorder stores clicks, not navigations. A drive that opens a product and then returns to
+ * search saves both clicks; replay lands on the product page and looks for a control that only
+ * exists on search. That shape is visible from the route list with no change to the flow file, so
+ * stop/save can warn instead of writing a flow that fails on the next click.
+ */
+import { EventType } from '@reticlehq/core';
+import { routePathOf } from '@reticlehq/engine/question/predicate/predicate-route.js';
+function asString(value) {
+    return 'string' === typeof value ? value : undefined;
+}
+/**
+ * The page a recording step sat on, comparable across path routers and hash routers.
+ *
+ * A startPath is stored as pathname+hash (`/#/search`); a ROUTE_CHANGE carries them separately.
+ * Without this, every hash-router page compares as `/` and a backtrack is invisible.
+ */
+export function recordingRouteOf(pathname, hash = '') {
+    const hashIdx = pathname.indexOf('#/');
+    if (hashIdx >= 0) {
+        return routePathOf(pathname.slice(0, hashIdx) || '/', pathname.slice(hashIdx));
+    }
+    const fragment = hash.startsWith('#') ? hash : 0 === hash.length ? '' : `#${hash}`;
+    if (fragment.startsWith('#/'))
+        return routePathOf(0 === pathname.length ? '/' : pathname, fragment);
+    return pathname;
+}
+function collapseConsecutive(routes) {
+    const out = [];
+    for (const route of routes) {
+        if (0 === route.length)
+            continue;
+        if (out.at(-1) === route)
+            continue;
+        out.push(route);
+    }
+    return out;
+}
+/**
+ * Warn when the journey left a page and came back. Linear A→B→C is silent: that still cannot
+ * replay either if a later click needs a previous page, but the reported failure is specifically
+ * the backtrack, and inventing a warning for every multi-page drive would teach agents to ignore it.
+ */
+export function recordingBacktrackWarning(routes) {
+    const path = collapseConsecutive(routes);
+    const seen = new Set();
+    for (const route of path) {
+        if (seen.has(route)) {
+            return (`this recording returned to ${route} after leaving it — replay has no navigation steps, so ` +
+                'the next click looks for a control that only exists on a page the tab is no longer on. ' +
+                `Journey: ${path.join(' → ')}. Split into one flow per page, or record the control that navigates back.`);
+        }
+        seen.add(route);
+    }
+    return undefined;
+}
+/** Ordered pages the recording sat on, startPath first, consecutive stays collapsed. */
+export function routesFromRecording(startPath, events) {
+    const raw = [];
+    if (undefined !== startPath)
+        raw.push(recordingRouteOf(startPath));
+    for (const event of events) {
+        if (EventType.ROUTE_CHANGE !== event.type)
+            continue;
+        const pathname = asString(event.data['pathname']) ?? asString(event.data['to']);
+        if (undefined === pathname)
+            continue;
+        raw.push(recordingRouteOf(pathname, asString(event.data['hash']) ?? ''));
+    }
+    return collapseConsecutive(raw);
+}