@reticlehq/server 2.14.0 → 3.2.0

package/dist/flows/flake.d.ts

@@ -1,56 +0,0 @@
-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, {
-    flows: Record<string, {
-        runs: number;
-        fails: number;
-    }>;
-    version: 1;
-}, {
-    flows: Record<string, {
-        runs: number;
-        fails: number;
-    }>;
-    version: 1;
-}>;
-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/flows/flow-classify.d.ts

@@ -1,51 +0,0 @@
-/**
- * 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;

package/dist/flows/flow-classify.js

@@ -1,102 +0,0 @@
-/**
- * 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. */
-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 } : {}),
-    };
-}

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

@@ -1,33 +0,0 @@
-/**
- * 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 './flows.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/flows/flow-expect-grammar.js

@@ -1,155 +0,0 @@
-/**
- * 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 '../events/predicate.js';
-import { predicateToExpect } from './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 };
-}

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

@@ -1,52 +0,0 @@
-import { type FlowFile, type InstrumentationGap } from '@reticlehq/core';
-import { IntentStore } from '../intent/intent-store.js';
-/** The ledger id a flow's own prose goal is declared under. */
-export declare function flowIntentId(flowName: string): string;
-/** The verdict that a replay of this flow, at this time, constitutes — what `provenBy` records. */
-export declare function flowReplayVerdictId(flowName: string, at: number): string;
-/**
- * Promote a flow's prose goal into the ledger and stamp the id back onto the flow.
- *
- * The binding is attached only when the flow asserts an observable consequence, because that is the
- * only case where replaying it green proves anything. A flow that asserts nothing leaves its intent
- * `declared` — and `dischargeIntent` refuses to prove an unbound intent, so an assertion-free flow
- * can never discharge one. That is the whole guard, and it is the ledger's own rule, not a new one.
- *
- * Returns the flow unchanged (and writes nothing) when there is no intent, so a flow file saved
- * before any of this existed keeps its exact bytes.
- */
-export declare function linkFlowIntent(store: IntentStore, flow: FlowFile): Promise<FlowFile>;
-/**
- * The nudge a flow saved without an intent earns, or nothing.
- *
- * Every save path routes through here, so the three of them cannot drift into three different ways
- * of saying the same thing. It says it in the vocabulary the instrumentation gaps already use — what
- * is missing, what it costs, and the one change that closes it — because "nobody said what this is
- * for" is the same finding `undeclared-change` makes about an edit, one artifact later.
- *
- * Deliberately generic. It names no step, no assertion and not even the flow, for the reason this
- * file already gives twice: anything specific enough to identify the goal is specific enough to be
- * read AS the goal. It also never fails the save — a flow with no intent is still far better than no
- * flow, and a verification tool that refuses to record work is one people route around.
- */
-export declare function flowIntentGap(flow: FlowFile): InstrumentationGap | undefined;
-/**
- * What the ledger currently says this flow is for, or undefined when nothing declared it.
- *
- * Read from the ledger rather than from the flow file's own copy: the ledger is where an amendment
- * lands, and a report that quotes the stale copy would be the two-vocabularies problem all over
- * again — one sentence in review, a different one in the failure message.
- */
-export declare function flowIntentStatement(store: IntentStore, flow: FlowFile): Promise<string | undefined>;
-/**
- * Record that this replay proved the flow's intent. False when there was nothing to prove.
- *
- * Best-effort by construction: `IntentStore.discharge` returns false rather than throwing on an
- * unknown or unbound id, because discharge runs off the back of a verdict and must never be the
- * reason one fails to return.
- */
-export declare function dischargeFlowIntent(store: IntentStore, flow: FlowFile, proof: {
-    verdictId: string;
-    grade: string;
-    at: number;
-}): Promise<boolean>;

package/dist/flows/flow-intent.js

@@ -1,123 +0,0 @@
-import { InstrumentationGapKind, instrumentationGap, } from '@reticlehq/core';
-import { IntentStore } from '../intent/intent-store.js';
-import { classifyFlowAssertions } from './flow-classify.js';
-/**
- * The link between a saved flow and the intent ledger — what the flow is FOR.
- *
- * A replay used to report only in the language of the DOM: step 3 drifted, this assertion failed.
- * True, actionable, and illegible — the reader still had to reconstruct what stopped working. The
- * ledger in `.reticle/intent.json` already holds the other half (prose statements, declared → bound
- * → proved, and the verdict that discharged each one), so a flow does not need its own notion of
- * intent. It needs an id.
- *
- * Nothing here derives an intent from step names. A flow that declares none reports that it declares
- * none — a guessed intent puts words in the product owner's mouth and an agent will act on them,
- * which is strictly worse than the honest absence.
- */
-/** Namespaced so a flow-declared intent never collides with one an agent declared by hand. */
-const FLOW_INTENT_ID_PREFIX = 'flow:';
-const FLOW_VERDICT_ID_PREFIX = 'flow_replay:';
-const ID_SEPARATOR = ':';
-/** The ledger id a flow's own prose goal is declared under. */
-export function flowIntentId(flowName) {
-    return `${FLOW_INTENT_ID_PREFIX}${flowName}`;
-}
-/** The verdict that a replay of this flow, at this time, constitutes — what `provenBy` records. */
-export function flowReplayVerdictId(flowName, at) {
-    return `${FLOW_VERDICT_ID_PREFIX}${flowName}${ID_SEPARATOR}${String(at)}`;
-}
-/**
- * Which ledger row this flow answers to, or nothing.
- *
- * An explicit `intentId` wins, so a flow can discharge an intent that was declared before it existed.
- * Otherwise the flow's own prose implies one. A flow with neither has no intent, and says so.
- */
-function intentIdOf(flow) {
-    if (flow.intentId !== undefined)
-        return flow.intentId;
-    // TRIMMED, not merely defined. `intent: "   "` satisfied `!== undefined` and silenced the gap, so
-    // a flow whose stated goal is whitespace looked identical on disk to one somebody thought about.
-    //
-    // The worse direction of the two: this gap is the ONLY thing that would ever tell anyone the flow
-    // has no goal, so suppressing it wrongly means the flow replays for months and the day it goes red
-    // the report names the broken step and nothing else — the precise failure it was written to
-    // prevent. Found by probing the seam rather than reading it.
-    return undefined === flow.intent || '' === flow.intent.trim()
-        ? undefined
-        : flowIntentId(flow.name);
-}
-/**
- * Promote a flow's prose goal into the ledger and stamp the id back onto the flow.
- *
- * The binding is attached only when the flow asserts an observable consequence, because that is the
- * only case where replaying it green proves anything. A flow that asserts nothing leaves its intent
- * `declared` — and `dischargeIntent` refuses to prove an unbound intent, so an assertion-free flow
- * can never discharge one. That is the whole guard, and it is the ledger's own rule, not a new one.
- *
- * Returns the flow unchanged (and writes nothing) when there is no intent, so a flow file saved
- * before any of this existed keeps its exact bytes.
- */
-export async function linkFlowIntent(store, flow) {
-    const id = intentIdOf(flow);
-    if (id === undefined)
-        return flow;
-    if (flow.intent !== undefined) {
-        await store.declare([{ id, statement: flow.intent, surface: { flow: flow.name } }]);
-    }
-    if (classifyFlowAssertions(flow).hasConsequenceAssertion) {
-        await store.bind(id, { flow: flow.name });
-    }
-    return { ...flow, intentId: id };
-}
-/**
- * The nudge a flow saved without an intent earns, or nothing.
- *
- * Every save path routes through here, so the three of them cannot drift into three different ways
- * of saying the same thing. It says it in the vocabulary the instrumentation gaps already use — what
- * is missing, what it costs, and the one change that closes it — because "nobody said what this is
- * for" is the same finding `undeclared-change` makes about an edit, one artifact later.
- *
- * Deliberately generic. It names no step, no assertion and not even the flow, for the reason this
- * file already gives twice: anything specific enough to identify the goal is specific enough to be
- * read AS the goal. It also never fails the save — a flow with no intent is still far better than no
- * flow, and a verification tool that refuses to record work is one people route around.
- */
-export function flowIntentGap(flow) {
-    if (intentIdOf(flow) !== undefined)
-        return undefined;
-    return instrumentationGap(InstrumentationGapKind.NO_FLOW_INTENT, 'this flow declares no intent, so nothing on disk says what it is meant to prove', 'it will replay for months, and the day it goes red the report can only name the step that broke — not the thing that stopped being true — so whoever reads it has to reconstruct the goal from the steps before they can tell a real regression from a moved button');
-}
-/**
- * What the ledger currently says this flow is for, or undefined when nothing declared it.
- *
- * Read from the ledger rather than from the flow file's own copy: the ledger is where an amendment
- * lands, and a report that quotes the stale copy would be the two-vocabularies problem all over
- * again — one sentence in review, a different one in the failure message.
- */
-export async function flowIntentStatement(store, flow) {
-    const id = intentIdOf(flow);
-    if (id === undefined)
-        return undefined;
-    const found = (await store.read()).find((intent) => intent.id === id);
-    return found?.statement ?? flow.intent;
-}
-/**
- * Record that this replay proved the flow's intent. False when there was nothing to prove.
- *
- * Best-effort by construction: `IntentStore.discharge` returns false rather than throwing on an
- * unknown or unbound id, because discharge runs off the back of a verdict and must never be the
- * reason one fails to return.
- */
-export async function dischargeFlowIntent(store, flow, proof) {
-    const id = intentIdOf(flow);
-    if (id === undefined)
-        return false;
-    try {
-        return await store.discharge(id, proof);
-    }
-    catch {
-        // A ledger that cannot be written is a small problem; a verdict that never returns because of
-        // one is a large problem. The replay already succeeded — the proof is simply not recorded.
-        return false;
-    }
-}

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

@@ -1,43 +0,0 @@
-import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult, type ReticleEvent } from '@reticlehq/core';
-import type { ArrivalClock } from '../tools/navigate-arrival.js';
-import type { SessionManager } from '../session/session-manager.js';
-import type { Session } from '../session/session.js';
-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, detail?: string): string;
-/** The slice of a session the start-path logic reads: the live URL plus the event buffer. */
-interface StartPathSession {
-    url?: string;
-    eventsSince(cursor: number): ReticleEvent[];
-}
-/**
- * When a flow records the page its journey started on (`startPath`) and the tab is currently on a
- * different route, step 1 drifts for a reason that has nothing to do with the app regressing — the
- * anchor simply isn't on this page yet. Detect that so the decision says "navigate there first"
- * instead of a mystifying "a step no longer matches". Returns undefined when the routes agree or the
- * current route is unobservable — never a false alarm. Replay normally never gets here on a
- * wrong page (arriveAtStartPath navigates before step 1); this is the fallback for when that
- * navigation was refused or the SDK never reconnected in the window.
- */
-export declare function startPathMismatchHint(flow: FlowFile, session: StartPathSession): string | undefined;
-export declare function arriveAtStartPath(sessions: SessionManager, session: StartPathSession & {
-    id: string;
-    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
-}, flow: FlowFile, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
-/**
- * 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>;
-/**
- * The connecting session's project, or undefined when no browser is attached. Flow tools use it to
- * scope storage to the current app on a shared daemon; resolving must NOT throw here (list/load are
- * 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;
-export {};