@reticlehq/server 3.2.0 → 3.4.0

package/dist/language/flows/annotate-notes/annotate.js

@@ -1,4 +1,4 @@
-import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, flowExpectHasConsequence, flowExpectIsPresenceOnly, } from '@reticlehq/core';
+import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, flowExpectHasConsequence, flowExpectIsPresenceOnly, PredicateKind, } from '@reticlehq/core';
 /**
  * The PURE compiler at the heart of the annotation facet. A structured annotation +
  * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
@@ -14,35 +14,71 @@ import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICA
  * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema
  * rejects it upstream; the tool maps that to UNKNOWN_KIND). No NL parser exists or is faked.
  */
+/**
+ * A network annotation as a predicate, `count` included.
+ *
+ * Written once because it is compiled on two paths — a step gate and a flow's success oracle — and
+ * the first version of this migration wrote it twice and dropped `count` from both. The schema's own
+ * comment says why that matters: presence says the request fired, cardinality catches the
+ * double-submit that fired it twice, and `count` is the point of the annotation.
+ *
+ * A counted assertion also gates on `settled`. A wait-until-true evaluator satisfies `count: 1` the
+ * instant the FIRST request lands, which is before a duplicate arrives — so without the gate the
+ * guard passes on exactly the bug it exists to catch.
+ */
+function netPredicate(net) {
+    const clause = {
+        kind: PredicateKind.NET,
+    };
+    if (net.method !== undefined)
+        clause.method = net.method;
+    if (net.urlContains !== undefined)
+        clause.urlContains = net.urlContains;
+    if (net.status !== undefined)
+        clause.status = net.status;
+    if (net.count === undefined)
+        return clause;
+    clause.count = net.count;
+    return { kind: PredicateKind.ALL_OF, predicates: [{ kind: PredicateKind.SETTLED }, clause] };
+}
 export function compileAnnotation(a, stepCount) {
     switch (a.kind) {
         case AnnotationKind.ASSERT_SIGNAL: {
             if (0 === stepCount)
                 return noStep();
-            const expect = { signal: a.name };
+            const signal = {
+                kind: PredicateKind.SIGNAL,
+                name: a.name,
+            };
             if (a.dataMatches !== undefined)
-                expect.signalData = a.dataMatches;
-            return stepPatch(a, stepCount, expect);
+                signal.dataMatches = a.dataMatches;
+            return stepPatch(a, stepCount, signal);
         }
         case AnnotationKind.ASSERT_VISIBLE: {
             if (0 === stepCount)
                 return noStep();
-            return stepPatch(a, stepCount, { element: { testid: a.testid } });
+            return stepPatch(a, stepCount, {
+                kind: PredicateKind.ELEMENT,
+                query: { testid: a.testid },
+            });
         }
         case AnnotationKind.ASSERT_STATE: {
             if (0 === stepCount)
                 return noStep();
-            const state = { path: a.statePath };
+            const state = {
+                kind: PredicateKind.STATE,
+                path: a.statePath,
+            };
             if (a.store !== undefined)
                 state.store = a.store;
             if (a.equals !== undefined)
                 state.equals = a.equals;
-            return stepPatch(a, stepCount, { state });
+            return stepPatch(a, stepCount, state);
         }
         case AnnotationKind.ASSERT_NET: {
             if (0 === stepCount)
                 return noStep();
-            return stepPatch(a, stepCount, { net: a.net });
+            return stepPatch(a, stepCount, netPredicate(a.net));
         }
         case AnnotationKind.MARK_DYNAMIC:
             return {
@@ -53,39 +89,51 @@ export function compileAnnotation(a, stepCount) {
             // Precedence: signal > state > net > console > testid (a consequence end-condition beats a
             // presence check). None of them → MISSING_FIELD.
             if (a.signal !== undefined) {
-                return flowSuccess(a, { signal: a.signal });
+                return flowSuccess(a, { kind: PredicateKind.SIGNAL, name: a.signal });
             }
             if (a.statePath !== undefined) {
-                const state = { path: a.statePath };
+                const state = {
+                    kind: PredicateKind.STATE,
+                    path: a.statePath,
+                };
                 if (a.store !== undefined)
                     state.store = a.store;
                 if (a.equals !== undefined)
                     state.equals = a.equals;
-                if (a.hold !== undefined)
-                    state.hold = a.hold;
-                return flowSuccess(a, { state });
+                // `hold` was a v1 flag meaning "this must STILL be true after the page settles". A predicate
+                // says that by composing: the settle gate is a clause, not a boolean on another clause.
+                return flowSuccess(a, true === a.hold
+                    ? { kind: PredicateKind.ALL_OF, predicates: [{ kind: PredicateKind.SETTLED }, state] }
+                    : state);
             }
             if (a.net !== undefined) {
-                return flowSuccess(a, { net: a.net });
+                return flowSuccess(a, netPredicate(a.net));
             }
             if (a.console !== undefined) {
-                return flowSuccess(a, { console: a.console });
+                return flowSuccess(a, {
+                    kind: PredicateKind.CONSOLE,
+                    ...(a.console.level === undefined ? {} : { level: a.console.level }),
+                    ...(a.console.absent === undefined ? {} : { absent: a.console.absent }),
+                });
             }
             if (a.testid !== undefined) {
-                return flowSuccess(a, { element: { testid: a.testid } });
+                return flowSuccess(a, { kind: PredicateKind.ELEMENT, query: { testid: a.testid } });
             }
             // Last, and above only MISSING_FIELD. An element is a locator and text is content; where a
             // caller offered both, the locator is the more stable anchor. But text beats nothing at all,
             // which is what an app whose only observable is a rendered value used to get (#811).
             if (a.text !== undefined) {
-                const text = { contains: a.text.contains };
+                const text = {
+                    kind: PredicateKind.TEXT,
+                    contains: a.text.contains,
+                };
                 if (a.text.scope !== undefined)
                     text.scope = a.text.scope;
                 if (a.text.absent !== undefined)
                     text.absent = a.text.absent;
                 if (a.text.visible !== undefined)
                     text.visible = a.text.visible;
-                return flowSuccess(a, { text });
+                return flowSuccess(a, text);
             }
             return { result: { ok: false, code: AnnotationErrorCode.MISSING_FIELD } };
         }

package/dist/language/flows/change/affected.d.ts

@@ -22,3 +22,12 @@ export interface AffectedResult {
  * a repo-relative change matches an absolute stamp and vice-versa.
  */
 export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;
+export declare function isInteractiveSource(text: string): boolean;
+/**
+ * Changed interactive components that no saved flow's manifest names.
+ *
+ * `affectedFlows` starts from the flows, so a file no flow ever touched affects nothing — and a gate
+ * built only on it passed a brand-new feature that had never been driven. This starts from the
+ * change instead. `isInteractive` is injected so the decision stays pure; the CLI reads the file.
+ */
+export declare function unflowedFiles(flows: readonly FlowSources[], changedFiles: readonly string[], isInteractive: (file: string) => boolean): string[];

package/dist/language/flows/change/affected.js

@@ -33,3 +33,38 @@ export function affectedFlows(flows, changedFiles) {
     }
     return { affected, unknownProvenance };
 }
+/** A file a source stamper can put on an element — the only files a flow's manifest can ever name. */
+const COMPONENT_FILE = /\.(?:jsx|tsx|vue|svelte|astro)$/;
+/** Same test-file rule the stampers use, so a test is never demanded a flow. */
+const TEST_FILE = /(?:\.(?:test|spec)\.[^./]+$)|(?:^|\/)__tests__\//;
+/**
+ * Something a step could act on: a handler prop (`onClick=`, `@click`, `v-on:`, `on:submit`) or a
+ * native control.
+ *
+ * ponytail: a text heuristic, not a parse. A flow's manifest only names the file of the element a
+ * step ACTED on, so a display-only component can never be attributed and demanding a flow for one
+ * would block forever. A handler passed in from a parent under another name escapes it; upgrade to
+ * recording the source of the element an `expect` matched if that proves common.
+ */
+const INTERACTIVE = /\bon[A-Z]\w*=|@[a-z]+[=.]|\bv-on:|\bon:[a-z]+|<(?:button|input|select|textarea|form|a|summary)[\s>/]/;
+export function isInteractiveSource(text) {
+    return INTERACTIVE.test(text);
+}
+/**
+ * Changed interactive components that no saved flow's manifest names.
+ *
+ * `affectedFlows` starts from the flows, so a file no flow ever touched affects nothing — and a gate
+ * built only on it passed a brand-new feature that had never been driven. This starts from the
+ * change instead. `isInteractive` is injected so the decision stays pure; the CLI reads the file.
+ */
+export function unflowedFiles(flows, changedFiles, isInteractive) {
+    const sources = flows.flatMap((flow) => (flow.sources ?? []).map(normalize));
+    return changedFiles.filter((file) => {
+        const c = normalize(file);
+        if (!COMPONENT_FILE.test(c) || TEST_FILE.test(c))
+            return false;
+        if (sources.some((s) => c === s || c.endsWith(`/${s}`) || s.endsWith(`/${c}`)))
+            return false;
+        return isInteractive(file);
+    });
+}

package/dist/language/flows/change/gate.d.ts

@@ -22,6 +22,16 @@ interface GateInput {
     downgraded?: readonly DowngradedFlow[];
     /** Flows that covered a changed file but no longer exist — coverage deleted rather than satisfied. */
     deleted?: readonly string[];
+    /** Changed interactive components no saved flow touches — a change nothing has driven. */
+    unflowed?: readonly string[];
+    /** Coverage levels below the best they ever reached — something new appeared, nothing covered it. */
+    coverageRegressed?: readonly {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    /** Changed files the browser loaded and never ran a function of. */
+    unexecuted?: readonly string[];
 }
 interface GateResult {
     /** True when every affected, non-flaky flow has a passing artifact AND nothing was weakened/deleted. */
@@ -34,6 +44,16 @@ interface GateResult {
     downgraded: DowngradedFlow[];
     /** Deleted flows that covered changed files — BLOCKING for the same reason. */
     deleted: string[];
+    /** Changed interactive components no flow covers — BLOCKING: the change was never driven. */
+    unflowed: string[];
+    /** BLOCKING: the app grew something nothing has covered. */
+    coverageRegressed: {
+        level: string;
+        was: number;
+        now: number;
+    }[];
+    /** BLOCKING: changed code that never ran in any drive. */
+    unexecuted: string[];
 }
 export declare function gateDecision(input: GateInput): GateResult;
 export {};

package/dist/language/flows/change/gate.js

@@ -23,11 +23,22 @@ export function gateDecision(input) {
     // trivially gameable, which is the exact failure this gate exists to prevent.
     const downgraded = [...(input.downgraded ?? [])];
     const deleted = [...(input.deleted ?? [])];
+    const unflowed = [...(input.unflowed ?? [])];
+    const coverageRegressed = [...(input.coverageRegressed ?? [])];
+    const unexecuted = [...(input.unexecuted ?? [])];
     return {
-        pass: 0 === uncovered.length && 0 === downgraded.length && 0 === deleted.length,
+        pass: 0 === uncovered.length &&
+            0 === downgraded.length &&
+            0 === deleted.length &&
+            0 === unflowed.length &&
+            0 === coverageRegressed.length &&
+            0 === unexecuted.length,
         uncovered,
         quarantined,
         downgraded,
         deleted,
+        unflowed,
+        coverageRegressed,
+        unexecuted,
     };
 }

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

@@ -28,6 +28,18 @@ export declare function nearestTestid(missing: string, present: string[]): strin
 export declare function nearestIsAmbiguous(missing: string, present: string[]): boolean;
 /** Build the legible-drift record for a testid anchor that resolved to zero live elements. */
 export declare function testidDrift(value: string, hint: QueryEmptyHint | undefined): Drift;
+/**
+ * Build the drift for a step whose anchor matched MORE THAN ONE live element.
+ *
+ * `ambiguous: true` is set because that is exactly what it is, and it is the field heal already
+ * reads to refuse an auto-rebind -- an ambiguous drift must never be healed to an arbitrary pick,
+ * which is the same reasoning that made this a drift instead of a note in the first place.
+ *
+ * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
+ * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
+ * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ */
+export declare function ambiguousAnchorDrift(value: string, matches: number): Drift;
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

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

@@ -139,6 +139,26 @@ export function testidDrift(value, hint) {
         drift.ambiguous = true;
     return drift;
 }
+/**
+ * Build the drift for a step whose anchor matched MORE THAN ONE live element.
+ *
+ * `ambiguous: true` is set because that is exactly what it is, and it is the field heal already
+ * reads to refuse an auto-rebind -- an ambiguous drift must never be healed to an arbitrary pick,
+ * which is the same reasoning that made this a drift instead of a note in the first place.
+ *
+ * `nearest` is null on purpose. There is no nearest: the anchor was found, several times over, and
+ * proposing one of the matches as "the" match would re-make the guess this reason exists to stop.
+ * The fix is a NARROWER anchor, and only a human or an agent looking at the page can choose it.
+ */
+export function ambiguousAnchorDrift(value, matches) {
+    return {
+        reasonKind: DriftReason.ANCHOR_AMBIGUOUS,
+        reason: `testid "${value}" matched ${String(matches)} live elements — which one the recording meant is not decidable; anchor this step to something unique`,
+        anchor: value,
+        nearest: null,
+        ambiguous: true,
+    };
+}
 /**
  * Build the drift for a step whose `expect.element` testid was absent after the action ran.
  *

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

@@ -0,0 +1,7 @@
+import type { FlowFile } from '@reticlehq/core';
+/**
+ * Who is making a flow right now: the agent that announced itself over MCP, and the person signed in
+ * to Reticle on this machine. A key handed over in the environment names no person, so none is
+ * written — the cloud can still attribute the push by the key that sent it.
+ */
+export declare function flowAuthor(env?: NodeJS.ProcessEnv, home?: string): FlowFile['author'];

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

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { mcpClientIdentity } from '../../surface/mcp/peer/client-identity.js';
+import { readAccountState } from '../../memory/cloud/account-state.js';
+/**
+ * Who is making a flow right now: the agent that announced itself over MCP, and the person signed in
+ * to Reticle on this machine. A key handed over in the environment names no person, so none is
+ * written — the cloud can still attribute the push by the key that sent it.
+ */
+export function flowAuthor(env = process.env, home = homedir()) {
+    const agent = mcpClientIdentity().name;
+    const account = readAccountState(home, env);
+    const person = account.signedIn ? account.email : undefined;
+    if (agent === undefined && person === undefined)
+        return undefined;
+    return {
+        ...(agent === undefined ? {} : { agent }),
+        ...(person === undefined ? {} : { person }),
+    };
+}

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

@@ -18,9 +18,8 @@ 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 = {
+type CoerceExpectResult = {
     ok: true;
     value: unknown;
 } | {
@@ -31,3 +30,4 @@ 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>;
+export {};

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

@@ -11,14 +11,11 @@
  * 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';
+import { FlowExpectSchema, FlowPredicateSchema, READABLE_FLOW_VERSIONS, FlowErrorCode, FlowFileSchema, } from '@reticlehq/core';
 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);
@@ -43,20 +40,44 @@ function flattenSignalObject(raw) {
 }
 export function coerceFlowExpect(raw) {
     if (isRecord(raw) && 'kind' in raw) {
-        const parsed = PredicateSchema.safeParse(raw);
+        const parsed = FlowPredicateSchema.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 };
+        // Kept AS the predicate. There is nothing to convert to any more, so nothing to refuse for
+        // being inexpressible — the shape an agent wrote is the shape the file holds.
+        return { ok: true, value: parsed.data };
     }
     if (!isRecord(raw))
         return { ok: true, value: raw };
-    return { ok: true, value: flattenSignalObject(raw) };
+    const flattened = flattenSignalObject(raw);
+    /*
+     * A v1 expect is validated HERE so a misspelling is named.
+     *
+     * The schema accepts both formats as a union, and a union rejection reports every branch's
+     * complaint at once — so `{ signal: 'x', signl: 'typo' }` came back as "flow file is malformed"
+     * without the word `signl` in it. The file was still refused, which is the half that matters, but
+     * the reader was left to find a one-character typo by eye. Checking the v1 shape on its own, on
+     * the path that already knows this is a v1 expect, puts the key back in the message.
+     */
+    const asV1 = FlowExpectSchema.safeParse(flattened);
+    if (!asV1.success) {
+        return { ok: false, detail: describePredicateExpectFailure(asV1.error) };
+    }
+    return { ok: true, value: flattened };
 }
 function describePredicateExpectFailure(error) {
+    const refused = error.issues.find((one) => 'custom' === one.code);
+    if (refused !== undefined)
+        return `${FlowParseNote.UNSUPPORTED_SHAPE}: ${refused.message}`;
+    // An unrecognized key FIRST: a strict object reports it on the object's own path with the names
+    // in `keys`, so reading `path[0]` misses the one thing worth saying. A misspelling is the failure
+    // this whole check exists to catch, and naming it is the difference between a fix and a hunt.
+    const unknownKey = error.issues.find((one) => 'unrecognized_keys' === one.code);
+    if (unknownKey !== undefined && 'unrecognized_keys' === unknownKey.code) {
+        const named = unknownKey.keys.map((k) => `"${k}"`).join(', ');
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} key ${named}`;
+    }
     const issue = error.issues[0];
     if (undefined === issue)
         return FlowParseNote.UNSUPPORTED_SHAPE;
@@ -102,8 +123,48 @@ export function coerceFlowFileExpects(raw) {
     }
     return { ok: true, value: next };
 }
+/**
+ * The issues a union rejection buries.
+ *
+ * `expect` accepts a predicate OR a v1 expect, and zod reports a union failure as one
+ * `invalid_union` issue whose branch errors live inside `unionErrors`. The one that matters is the
+ * v1 branch's `unrecognized_keys` — the misspelled field. Without this the file was still correctly
+ * REFUSED and the message said only "malformed", which sends the author back to hunt a
+ * one-character typo we had already identified.
+ */
+function flatten(issues) {
+    return issues.flatMap((issue) => 'invalid_union' === issue.code
+        ? [issue, ...flatten(issue.unionErrors.flatMap((e) => e.issues))]
+        : [issue]);
+}
 export function describeFlowZodFailure(error) {
-    const issue = error.issues[0];
+    const all = flatten(error.issues);
+    /*
+     * The most SPECIFIC complaint wins, wherever in the union it was reported.
+     *
+     * An unrecognized key names the typo. Failing that, an issue whose path reaches INTO an expect
+     * names the field that was the wrong type — `{ signal: { count: 1 } }`, a signal object with no
+     * name, is reported on `steps.0.expect.signal` and that path is the whole answer. The union's own
+     * top-level `invalid_union` says only "malformed", which is true and useless.
+     */
+    const named = (one) => {
+        // NOT the discriminator complaint. `invalid_union_discriminator` on `expect.kind` is the
+        // PREDICATE branch objecting that a v1 expect has no `kind` — which is true of every v1 expect
+        // ever written and tells the author nothing. The useful issue is the one from the branch they
+        // were actually writing.
+        if ('invalid_union_discriminator' === one.code)
+            return false;
+        return (('steps' === one.path[0] && 'expect' === one.path[2] && one.path.length > 3) ||
+            ('success' === one.path[0] && one.path.length > 1));
+    };
+    // A refinement carries its own reason (a session ref, named by field), and that reason IS the fix.
+    const refused = all.find((one) => 'custom' === one.code);
+    if (refused !== undefined && 'steps' === refused.path[0] && 'number' === typeof refused.path[1]) {
+        return `${FlowParseNote.UNSUPPORTED_SHAPE} at step ${String(refused.path[1])}: ${refused.message}`;
+    }
+    if (refused !== undefined)
+        return `${FlowParseNote.UNSUPPORTED_SHAPE}: ${refused.message}`;
+    const issue = all.find((one) => 'unrecognized_keys' === one.code) ?? all.find(named) ?? error.issues[0];
     if (undefined === issue)
         return FlowParseNote.MALFORMED;
     const path = issue.path;
@@ -139,6 +200,26 @@ export function parseFlowFileText(text) {
     catch {
         return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: FlowParseNote.NOT_JSON };
     }
+    /*
+     * Version BEFORE schema. When the format does not match, nothing else in the file can be trusted
+     * to mean what this reader thinks it means, so the first unrelated field that happens to fail
+     * would be noise about the wrong thing -- and `version` is a `z.literal`, so the schema's own
+     * complaint about it is indistinguishable from a typo.
+     *
+     * Only a NUMBER that is not ours counts. A missing or non-numeric `version` is a damaged field
+     * rather than a different format, and stays PARSE_FAILED.
+     */
+    const declared = isRecord(parsed) ? parsed['version'] : undefined;
+    if ('number' === typeof declared && !READABLE_FLOW_VERSIONS.has(declared)) {
+        return {
+            ok: false,
+            code: FlowErrorCode.WRONG_VERSION,
+            detail: `this flow file is version ${String(declared)} and this Reticle reads versions ` +
+                `${[...READABLE_FLOW_VERSIONS].join(', ')}. The file is not damaged, the reader is the ` +
+                'wrong one. ' +
+                'Upgrade or downgrade Reticle rather than editing the flow.',
+        };
+    }
     const coerced = coerceFlowFileExpects(parsed);
     if (!coerced.ok) {
         return { ok: false, code: FlowErrorCode.PARSE_FAILED, detail: coerced.detail };

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

@@ -6,7 +6,7 @@ import { classifyFlowAssertions } from './flow-classify.js';
  *
  * 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
+ * ledger in `.reticle/intent/` 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.
  *

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

@@ -0,0 +1,54 @@
+import { type FlowFile, type FlowStep, type Predicate } from '@reticlehq/core';
+/** A short, stable identity for a journey's shape: its start page and its steps. */
+export declare function journeyFingerprint(flow: Pick<FlowFile, 'startPath' | 'steps'>): string;
+/**
+ * Fold two copies of one journey into one file.
+ *
+ * Gap-filling, never overwriting: whatever the kept flow already says — its name, its intent, a
+ * step's declared consequence, a quarantine a person wrote — survives, and the other copy only
+ * supplies what is missing. So a merge can add an assertion or an intent and can never remove one.
+ */
+export declare function mergeJourney(kept: FlowFile, other: FlowFile): FlowFile;
+/**
+ * The name a new journey saves under.
+ *
+ * Its readable name when that is free or already this journey's; otherwise the same name with the
+ * fingerprint's head, so two different journeys that share an intent never overwrite each other.
+ */
+export declare function journeyName(base: string, fingerprint: string, taken: ReadonlyMap<string, string>): string;
+/**
+ * What must hold before a journey and what it leaves behind, read from where it started and ended.
+ *
+ * Routes only: the page is the one piece of state every recorded step knows for certain, and a
+ * claim written from a guess about the rest would be a precondition nobody met. Written in the
+ * exact form `canFollow` compares by value, so A-then-B is answerable from the two files alone.
+ */
+export declare function routeClaims(startPath: string | undefined, steps: readonly FlowStep[]): {
+    requires?: Predicate[];
+    ensures?: Predicate[];
+};
+/**
+ * The preconditions only another flow can establish.
+ *
+ * A route claim on the page the flow starts on is not one of them: replay navigates there itself, so
+ * it neither opts the flow out of the reset nor gates the run. That is the claim a saved drive writes
+ * for the map (see routeClaims) — reading it as "starts from leftover state" would stop every
+ * auto-saved flow from ever being reset.
+ */
+export declare function establishedState(flow: FlowFile): readonly Predicate[];
+/**
+ * Is the tab where the flow asked to start? Up to a trailing slash, and up to the query the flow
+ * did not ask about.
+ *
+ * `startPath` is the SPECIFICATION, so it decides what counts. A query it recorded is compared:
+ * `?tab=wrap` and `?tab=summary` are different pages, and a replay that starts on the wrong one
+ * proves nothing about the right one. A query it did NOT record is ignored: the tab carrying
+ * `?next=%2F` on a login page, or the identity params Reticle puts on a leased tab, are not the flow
+ * being elsewhere, and navigating to strip them costs a session for nothing.
+ *
+ * The asymmetry is the whole point and the reason `observed` and `expected` are named rather than
+ * `a` and `b`. Comparing with the query on both sides always re-navigated a query-bearing
+ * `startPath` (#1059, which killed the session mid-flow); comparing with it on neither side reads a
+ * tab on `?tab=summary` as already at `?tab=wrap`.
+ */
+export declare function samePath(observed: string, expected: string): boolean;