@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,240 @@
+import { AnchorKind, DriftReason, ReticleCommand, QueryBy, asRecord, asString, } from '@reticlehq/core';
+import { queryRefs } from './replay.js';
+/**
+ * Finding a step's anchor again, and saying legibly why it could not be found.
+ *
+ * Split out of `flow-replay.ts` because `flow-step-runners.ts` needs six of these and had to import
+ * them back out of the module that imports IT — a real runtime cycle, not a type-erased one. These
+ * functions know nothing about running a step; they resolve a locator and describe a miss, which is
+ * why they can sit underneath both.
+ */
+/**
+ * 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 function editDistance(a, b) {
+    const s = a.toLowerCase();
+    const t = b.toLowerCase();
+    const rows = s.length + 1;
+    const cols = t.length + 1;
+    const prev = new Array(cols);
+    const curr = new Array(cols);
+    for (let j = 0; j < cols; j++)
+        prev[j] = j;
+    for (let i = 1; i < rows; i++) {
+        curr[0] = i;
+        for (let j = 1; j < cols; j++) {
+            const cost = s[i - 1] === t[j - 1] ? 0 : 1;
+            curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        for (let j = 0; j < cols; j++)
+            prev[j] = curr[j] ?? 0;
+    }
+    return prev[cols - 1] ?? 0;
+}
+/**
+ * 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 function nearestTestid(missing, present) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of present) {
+        const distance = editDistance(missing, candidate);
+        if (distance < bestDistance ||
+            (distance === bestDistance && best !== null && candidate.length < best.length) ||
+            (distance === bestDistance &&
+                best !== null &&
+                candidate.length === best.length &&
+                candidate < best)) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/**
+ * Bounded settle for anchor re-resolution. A testid step queries the live DOM for the anchor; if a
+ * render is still in flight (post-login route swap, modal mount, list paint) the element exists but
+ * isn't painted yet, and a single QUERY would read zero and FALSELY drift. We re-query a few times
+ * with a short delay before concluding the anchor is gone — a real regression (renamed/removed
+ * testid) stays missing across every attempt, so this removes flakiness without masking breaks.
+ */
+const ANCHOR_SETTLE_ATTEMPTS = 8;
+const ANCHOR_SETTLE_DELAY_MS = 150;
+/**
+ * The budget that actually governs, in wall-clock milliseconds.
+ *
+ * Attempts were the bound, and on an event-chatty page that collapsed. `settleTick` ends on EITHER
+ * an event OR the tick, so a page emitting continuously (API calls, a large form render, CSS
+ * transition start/end pairs) burned all eight attempts in **224–758ms measured** — a budget
+ * documented as 1.2s, spent in a fifth of it, before a newly routed page had mounted its controls.
+ * Cross-route replays drifted `testid_not_found` at 278ms while the same flow passed on a quiet page.
+ *
+ * An event arriving is evidence the page is still working. It should EXTEND the wait, not spend it.
+ * So the deadline decides when to give up, and the attempt cap below survives only as a backstop
+ * against a pathological storm spinning this loop hot.
+ */
+const ANCHOR_SETTLE_BUDGET_MS = ANCHOR_SETTLE_ATTEMPTS * ANCHOR_SETTLE_DELAY_MS;
+/** Backstop only. Generous on purpose: the deadline is the real bound, this just prevents a spin. */
+const ANCHOR_SETTLE_MAX_ATTEMPTS = 40;
+/** Extract the live element refs + the zero-match near-miss hint from a QUERY command result. */
+function readQuery(result) {
+    const refs = queryRefs(result);
+    if (!result.ok)
+        return { refs };
+    const payload = asRecord(result.result);
+    const rawHint = payload['hint'];
+    if ('object' === typeof rawHint && rawHint !== null) {
+        const hint = asRecord(rawHint);
+        const present = Array.isArray(hint['presentTestids'])
+            ? hint['presentTestids'].filter((t) => 'string' === typeof t)
+            : [];
+        return {
+            refs,
+            hint: {
+                route: asString(hint['route']) ?? '',
+                presentTestids: present,
+                presentRegions: [],
+                knownEmptyState: true === hint['knownEmptyState'],
+            },
+        };
+    }
+    return { refs };
+}
+/**
+ * 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 function nearestIsAmbiguous(missing, present) {
+    if (present.length < 2)
+        return false;
+    let min = Number.POSITIVE_INFINITY;
+    let count = 0;
+    for (const candidate of present) {
+        const distance = editDistance(missing, candidate);
+        if (distance < min) {
+            min = distance;
+            count = 1;
+        }
+        else if (distance === min) {
+            count += 1;
+        }
+    }
+    return count >= 2;
+}
+/** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
+export function testidDrift(value, hint) {
+    const present = hint?.presentTestids ?? [];
+    const drift = {
+        reasonKind: DriftReason.TESTID_NOT_FOUND,
+        reason: `testid "${value}" not found`,
+        anchor: value,
+        nearest: nearestTestid(value, present),
+    };
+    if (nearestIsAmbiguous(value, present))
+        drift.ambiguous = true;
+    return drift;
+}
+/**
+ * Build the drift for a step whose `expect.element` testid was absent after the action ran.
+ *
+ * Deliberately not `testidDrift`: that one means "this step's anchor is gone", and reusing it here
+ * put the assertion's target in the result's `anchor` field — the field documented as the value the
+ * step is bound to. A caller then reads `testid_not_found` naming something that was never the
+ * step's locator and goes hunting for a rename, while the truth is the step ran and its
+ * consequence did not hold.
+ */
+export function expectElementDrift(value, hint) {
+    const present = hint?.presentTestids ?? [];
+    const drift = {
+        reasonKind: DriftReason.EXPECT_ELEMENT_NOT_FOUND,
+        reason: `expect.element testid "${value}" not present after the action`,
+        anchor: value,
+        nearest: nearestTestid(value, present),
+    };
+    if (nearestIsAmbiguous(value, present))
+        drift.ambiguous = true;
+    return drift;
+}
+/**
+ * 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.
+ */
+/**
+ * One wait between anchor attempts: the fixed tick, or the next DOM event — whichever comes first.
+ *
+ * An element mounting IS a mutation, and the session already streams those, so sleeping out the rest
+ * of a 150ms tick after the thing has already appeared is pure latency. Measured on next-app-router:
+ * a single `flow.step` span was 1079ms around nine QUERY round-trips of 1–2ms each — the cost was
+ * entirely the sleeping, and four such steps made up 4.3s of that app's 7.6s.
+ *
+ * It can only resolve the wait EARLIER, never end the loop earlier: the attempt budget above is
+ * untouched, so a genuinely missing anchor still spends the full settle before it drifts. An early
+ * "not found" would be a false drift, which is the failure this loop exists to prevent.
+ */
+async function settleTick(session, sleep) {
+    let unsubscribe;
+    try {
+        await new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                resolve();
+            };
+            unsubscribe = session.onEvent(finish);
+            void sleep(ANCHOR_SETTLE_DELAY_MS).then(finish);
+        });
+    }
+    finally {
+        unsubscribe?.();
+    }
+}
+export async function resolveQuery(session, queryArgs, sleep, now = Date.now) {
+    let last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
+    const deadline = now() + ANCHOR_SETTLE_BUDGET_MS;
+    for (let attempt = 1; 0 === last.refs.length && now() < deadline && attempt < ANCHOR_SETTLE_MAX_ATTEMPTS; attempt += 1) {
+        await settleTick(session, sleep);
+        last = readQuery(await session.command(ReticleCommand.QUERY, queryArgs));
+    }
+    return last;
+}
+/** Re-resolve a testid anchor. */
+export function resolveTestid(session, value, sleep) {
+    return resolveQuery(session, { by: QueryBy.TESTID, value }, sleep);
+}
+/** A compact, legible label for a component auto-anchor (component@file:line, or its best part). */
+export function componentLabel(anchor) {
+    if (anchor.source !== undefined) {
+        const base = anchor.source.file.split('/').pop() ?? anchor.source.file;
+        const loc = `${base}:${anchor.source.line}`;
+        return anchor.component !== undefined ? `${anchor.component}@${loc}` : loc;
+    }
+    return anchor.component ?? anchor.name ?? anchor.role ?? 'component';
+}
+/** The value of a step's primary anchor, for labelling the result row. */
+export function anchorLabel(anchor) {
+    if (anchor.kind === AnchorKind.TESTID)
+        return anchor.value;
+    if (anchor.kind === AnchorKind.SIGNAL)
+        return anchor.name;
+    if (anchor.kind === AnchorKind.COMPONENT)
+        return componentLabel(anchor);
+    return anchor.name ?? anchor.role;
+}
+/** QUERY args for a component auto-anchor — source (precise) + component name (coarse) as given. */
+export function componentQueryArgs(anchor) {
+    const args = { by: QueryBy.COMPONENT };
+    if (anchor.component !== undefined)
+        args['component'] = anchor.component;
+    if (anchor.source !== undefined)
+        args['source'] = anchor.source;
+    return args;
+}

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

@@ -0,0 +1,73 @@
+/**
+ * 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, FlowStep } 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;
+}
+/**
+ * A step expect counts the same as a flow-level one, because replay now evaluates the same set.
+ *
+ * This was briefly narrowed to `state` only — correctly, at the time: replay checked element presence
+ * and state and nothing else, so grading a step signal/net as a consequence produced a flow that
+ * reported `grade: "asserted"` and could not go red. `assertStepExpect` closed that by compiling
+ * every step expect through the same `successToPredicate` the flow-level path uses, so the narrow
+ * rule is no longer true and would now UNDER-grade real assertions.
+ *
+ * The invariant to keep: this function and what replay enforces must move together. If one ever
+ * describes more than the other, the difference is a false green or a lost verification.
+ */
+/** Walk steps + act_sequence sub-steps so an expect on either level is counted. */
+export declare function flattenSteps(steps: readonly FlowStep[]): FlowStep[];
+export declare function classifyFlowAssertions(flow: FlowFile, 
+/**
+ * The flows this one invokes, already loaded.
+ *
+ * A map rather than a loader so this stays pure and synchronous: the caller has the store and the
+ * async, and a classifier that could do IO would be a classifier that could fail for reasons that
+ * have nothing to do with the flow it is grading.
+ */
+invoked?: ReadonlyMap<string, FlowFile>): FlowAssertionClassification;

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

@@ -0,0 +1,146 @@
+/**
+ * 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 { flowExpectHasConsequence, flowExpectIsPresenceOnly } from '@reticlehq/core';
+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, so it will pass even if the feature is broken. Add a consequence assertion with reticle_annotate (assert-signal / assert-net) or a success-state.';
+const PRESENCE_ONLY_WARNING = 'This flow only checks element presence, not an observable consequence (signal/network). A locator healed to the wrong element can still pass it. Add a consequence assertion (assert-signal / assert-net / success-state).';
+const INTENT_WITHOUT_OUTCOME_WARNING = 'This flow declares a business intent but asserts no observable outcome (signal/network) — it claims to verify a goal it cannot actually check. Add a success-state consequence so the flow fails when the goal stops being met.';
+// Consequence vs presence-only classification lives in @reticlehq/core (one source for all graders).
+const expectIsConsequence = flowExpectHasConsequence;
+const expectIsWeak = flowExpectIsPresenceOnly;
+/**
+ * A step expect counts the same as a flow-level one, because replay now evaluates the same set.
+ *
+ * This was briefly narrowed to `state` only — correctly, at the time: replay checked element presence
+ * and state and nothing else, so grading a step signal/net as a consequence produced a flow that
+ * reported `grade: "asserted"` and could not go red. `assertStepExpect` closed that by compiling
+ * every step expect through the same `successToPredicate` the flow-level path uses, so the narrow
+ * rule is no longer true and would now UNDER-grade real assertions.
+ *
+ * The invariant to keep: this function and what replay enforces must move together. If one ever
+ * describes more than the other, the difference is a false green or a lost verification.
+ */
+/** Walk steps + act_sequence sub-steps so an expect on either level is counted. */
+export function flattenSteps(steps) {
+    const out = [];
+    for (const s of steps) {
+        out.push(s);
+        if (s.steps !== undefined)
+            out.push(...flattenSteps(s.steps));
+    }
+    return out;
+}
+/**
+ * Does this flow, or anything it invokes, assert a consequence?
+ *
+ * A composite is as asserted as what it runs. Driving one showed why this is not optional: a
+ * journey invoking a sub-flow that asserts a signal still graded `assertion-free`, warning that it
+ * "claims to verify a goal it cannot actually check". That was correct about the FILE — the invoke
+ * step carries no `expect` — and wrong about the JOURNEY, which asserts exactly once, in the
+ * document that owns the steps. Left alone it pushes people to duplicate the sub-flow's assertion
+ * into every caller, which is the copy-paste composition exists to remove.
+ *
+ * A sub-flow that cannot be READ is not credited. Same direction as every other "cannot tell" here:
+ * crediting an assertion nobody has looked at grades a composite on a promise.
+ *
+ * `seen` makes a cycle terminate. Typecheck refuses those at rest and this must not depend on that
+ * having run — grading is reached from save, which is exactly where a bad composite arrives first.
+ */
+function invokedAssertsConsequence(flow, invoked, seen) {
+    if (seen.has(flow.name))
+        return false;
+    const deeper = new Set([...seen, flow.name]);
+    for (const step of flattenSteps(flow.steps)) {
+        if (step.invoke === undefined)
+            continue;
+        const sub = invoked.get(step.invoke);
+        if (sub === undefined)
+            continue;
+        const subSteps = flattenSteps(sub.steps);
+        if (subSteps.some((s) => expectIsConsequence(s.expect)) || expectIsConsequence(sub.success)) {
+            return true;
+        }
+        if (invokedAssertsConsequence(sub, invoked, deeper))
+            return true;
+    }
+    return false;
+}
+export function classifyFlowAssertions(flow, 
+/**
+ * The flows this one invokes, already loaded.
+ *
+ * A map rather than a loader so this stays pure and synchronous: the caller has the store and the
+ * async, and a classifier that could do IO would be a classifier that could fail for reasons that
+ * have nothing to do with the flow it is grading.
+ */
+invoked = new Map()) {
+    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 invokedAsserts = invokedAssertsConsequence(flow, invoked, new Set());
+    const successIsConsequence = expectIsConsequence(flow.success);
+    const successIsWeak = expectIsWeak(flow.success);
+    const hasConsequenceAssertion = consequenceSteps > 0 || successIsConsequence || invokedAsserts;
+    const hasAnyAssertion = hasConsequenceAssertion || weakSteps > 0 || successIsWeak;
+    const 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 } : {}),
+    };
+}

package/dist/language/flows/flow-expect-grammar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Accept the assertion grammar a drive already uses, in a saved flow file.
+ *
+ * FlowExpect is a flat object (`signal` is a name string; `net`/`state` sit beside it). Agents write
+ * the `act_and_wait` shape instead — `{ kind: "allOf", predicates: [...] }`, or sibling channels
+ * with `signal: { name, count }` — and replay answered `flow_parse_failed` / "malformed". That sent
+ * people looking for a JSON syntax error in a file they had just written, and the workaround was to
+ * drop every channel but one.
+ *
+ * Coercion happens at load: the on-disk schema does not move, FLOW_FILE_VERSION stays 1, and a
+ * re-save writes the canonical shape. A kind a saved flow cannot enforce is refused, not stripped
+ * to an empty expect that would grade asserted-while-unchecked.
+ */
+import { type FlowFile } from '@reticlehq/core';
+import type { ZodError } from 'zod';
+import type { FlowResult } from './flow-result.js';
+export declare const FlowParseNote: {
+    readonly NOT_JSON: "flow file is not valid JSON — fix the syntax or regenerate it with reticle_flow_save";
+    readonly MALFORMED: "flow file is malformed — fix or regenerate it with reticle_flow_save";
+    readonly UNSUPPORTED_SHAPE: "valid JSON, unsupported expect shape";
+    readonly UNENFORCED: "valid JSON, but this expect uses a predicate kind a saved flow cannot enforce (settled, route, animation, anyOf, not)";
+};
+export type CoerceExpectResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare function coerceFlowExpect(raw: unknown): CoerceExpectResult;
+export declare function coerceFlowFileExpects(raw: unknown): CoerceExpectResult;
+export declare function describeFlowZodFailure(error: ZodError): string;
+export declare function parseFlowFileText(text: string): FlowResult<FlowFile>;

package/dist/language/flows/flow-expect-grammar.js

@@ -0,0 +1,155 @@
+/**
+ * Accept the assertion grammar a drive already uses, in a saved flow file.
+ *
+ * FlowExpect is a flat object (`signal` is a name string; `net`/`state` sit beside it). Agents write
+ * the `act_and_wait` shape instead — `{ kind: "allOf", predicates: [...] }`, or sibling channels
+ * with `signal: { name, count }` — and replay answered `flow_parse_failed` / "malformed". That sent
+ * people looking for a JSON syntax error in a file they had just written, and the workaround was to
+ * drop every channel but one.
+ *
+ * Coercion happens at load: the on-disk schema does not move, FLOW_FILE_VERSION stays 1, and a
+ * re-save writes the canonical shape. A kind a saved flow cannot enforce is refused, not stripped
+ * to an empty expect that would grade asserted-while-unchecked.
+ */
+import { FlowErrorCode, FlowFileSchema } from '@reticlehq/core';
+import { PredicateSchema } from '@reticlehq/engine/question/predicate/predicate.js';
+import { predicateToExpect } from '../../judgement/outcome/predicate-to-expect.js';
+export const FlowParseNote = {
+    NOT_JSON: 'flow file is not valid JSON — fix the syntax or regenerate it with reticle_flow_save',
+    MALFORMED: 'flow file is malformed — fix or regenerate it with reticle_flow_save',
+    UNSUPPORTED_SHAPE: 'valid JSON, unsupported expect shape',
+    UNENFORCED: 'valid JSON, but this expect uses a predicate kind a saved flow cannot enforce (settled, route, animation, anyOf, not)',
+};
+function isRecord(value) {
+    return 'object' === typeof value && null !== value && !Array.isArray(value);
+}
+/**
+ * Flatten `signal: { name, count }` into the on-disk fields. Other channels already match FlowExpect.
+ * Leave a signal object with no name alone so the schema failure can name the key.
+ */
+function flattenSignalObject(raw) {
+    const signal = raw['signal'];
+    if (!isRecord(signal))
+        return raw;
+    const name = signal['name'];
+    if ('string' !== typeof name)
+        return raw;
+    const out = { ...raw, signal: name };
+    if ('number' === typeof signal['count'])
+        out['signalCount'] = signal['count'];
+    if (undefined !== signal['dataMatches'])
+        out['signalData'] = signal['dataMatches'];
+    return out;
+}
+export function coerceFlowExpect(raw) {
+    if (isRecord(raw) && 'kind' in raw) {
+        const parsed = PredicateSchema.safeParse(raw);
+        if (!parsed.success) {
+            return { ok: false, detail: describePredicateExpectFailure(parsed.error) };
+        }
+        const expect = predicateToExpect(parsed.data);
+        if (undefined === expect)
+            return { ok: false, detail: FlowParseNote.UNENFORCED };
+        return { ok: true, value: expect };
+    }
+    if (!isRecord(raw))
+        return { ok: true, value: raw };
+    return { ok: true, value: flattenSignalObject(raw) };
+}
+function describePredicateExpectFailure(error) {
+    const issue = error.issues[0];
+    if (undefined === issue)
+        return FlowParseNote.UNSUPPORTED_SHAPE;
+    const key = issue.path[0];
+    if ('string' === typeof key || 'number' === typeof key) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} key "${String(key)}"`;
+    }
+    return FlowParseNote.UNSUPPORTED_SHAPE;
+}
+export function coerceFlowFileExpects(raw) {
+    if (!isRecord(raw))
+        return { ok: true, value: raw };
+    const next = { ...raw };
+    const stepsIn = next['steps'];
+    if (Array.isArray(stepsIn)) {
+        const steps = [];
+        for (let i = 0; i < stepsIn.length; i++) {
+            const step = stepsIn[i];
+            if (!isRecord(step) || undefined === step['expect']) {
+                steps.push(step);
+                continue;
+            }
+            const coerced = coerceFlowExpect(step['expect']);
+            if (!coerced.ok) {
+                return {
+                    ok: false,
+                    detail: `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(i)}: ${coerced.detail}`,
+                };
+            }
+            steps.push({ ...step, expect: coerced.value });
+        }
+        next['steps'] = steps;
+    }
+    if (undefined !== next['success']) {
+        const coerced = coerceFlowExpect(next['success']);
+        if (!coerced.ok) {
+            return {
+                ok: false,
+                detail: `${FlowParseNote.UNSUPPORTED_SHAPE} at success: ${coerced.detail}`,
+            };
+        }
+        next['success'] = coerced.value;
+    }
+    return { ok: true, value: next };
+}
+export function describeFlowZodFailure(error) {
+    const issue = error.issues[0];
+    if (undefined === issue)
+        return FlowParseNote.MALFORMED;
+    const path = issue.path;
+    // A strict object reports an unrecognized key as `unrecognized_keys` on the OBJECT's path, with
+    // the offending names in `keys` — not as an issue whose path ends in the key. Reading only the
+    // path shape reported the one failure this exists to name as a bare "malformed", which sends the
+    // author back to the file to find a typo we had already identified.
+    if ('unrecognized_keys' === issue.code) {
+        const named = issue.keys.map((k) => `"${k}"`).join(', ');
+        if ('steps' === path[0] && 'number' === typeof path[1] && 'expect' === path[2]) {
+            return `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(path[1])} key ${named}`;
+        }
+        if ('success' === path[0])
+            return `${FlowParseNote.UNSUPPORTED_SHAPE} at success key ${named}`;
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} — unrecognized key ${named}`;
+    }
+    if ('steps' === path[0] &&
+        'number' === typeof path[1] &&
+        'expect' === path[2] &&
+        'string' === typeof path[3]) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(path[1])} key "${path[3]}"`;
+    }
+    if ('success' === path[0] && 'string' === typeof path[1]) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} at success key "${path[1]}"`;
+    }
+    return FlowParseNote.MALFORMED;
+}
+export function parseFlowFileText(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: FlowParseNote.NOT_JSON };
+    }
+    const coerced = coerceFlowFileExpects(parsed);
+    if (!coerced.ok) {
+        return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: coerced.detail };
+    }
+    const result = FlowFileSchema.safeParse(coerced.value);
+    if (!result.success) {
+        return {
+            ok: false,
+            code: FlowErrorCode.PARSE_FAILED,
+            detail: describeFlowZodFailure(result.error),
+        };
+    }
+    return { ok: true, value: result.data };
+}