@reticlehq/server 3.1.0 → 3.3.0

package/dist/language/flows/flow-step-runners.js

@@ -6,7 +6,8 @@
  * point: the action window must open and close identically no matter which anchor found the element,
  * or a step's events land in the wrong window depending on how it was addressed.
  */
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, QueryBy, ReticleCommand, } from '@reticlehq/core';
+import { expectedElementTestid } from '@reticlehq/core';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DriftReason, PredicateKind, QueryBy, ReticleCommand, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { replayActionArgs } from './replay.js';
 import { isStaleRefError } from '../../surface/tools/act/act-sequence-retry.js';
@@ -102,7 +103,7 @@ export async function runRoleStep(session, step, index, anchor, confirmDangerous
  * to recognise the raw refusal still finds it, plus the fix for this specific caller.
  */
 const DESTRUCTIVE_ACTION_PATTERN = /potentially destructive (?:\w+ )*(?:action|tool) blocked/i;
-export function replayDestructiveActionHint(rawError) {
+function replayDestructiveActionHint(rawError) {
     if (!DESTRUCTIVE_ACTION_PATTERN.test(rawError))
         return rawError;
     return (`${rawError} — this is a flow REPLAY: a step's own args.confirmDangerous is stripped before ` +
@@ -118,7 +119,7 @@ export function replayDestructiveActionHint(rawError) {
  * Dispatch one already-resolved step. Shared so every anchor kind runs the action the same way —
  * including the action window, whose open/close must not depend on which anchor found the element.
  */
-async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous, 
+export async function actOnResolvedRef(session, step, index, label, ref, confirmDangerous, 
 /**
  * The field name a redacted fill is supplied under, from `anchorFieldName` — the SAME function
  * redaction uses to decide what to hide. Without it a role-anchored secret is redacted at save
@@ -252,6 +253,21 @@ export function anchorQueryArgs(anchor) {
         return roleQueryArgs(anchor);
     return null;
 }
+/**
+ * The anchor as a PRECONDITION a flow file can store: "this element is on the page".
+ *
+ * What `requires` means for a flow that starts from state a page load discards, in the shape the
+ * flow's own `requires` holds. No tool writes `requires`, so the reset's hint hands over this line.
+ */
+export function anchorPrecondition(anchor) {
+    if (anchor.kind === AnchorKind.TESTID) {
+        return { kind: PredicateKind.ELEMENT, query: { testid: anchor.value } };
+    }
+    if (anchor.kind === AnchorKind.ROLE && !isDegradedAnchor(anchor)) {
+        return { kind: PredicateKind.ELEMENT, query: { role: anchor.role, name: anchor.name } };
+    }
+    return undefined;
+}
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
  * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one
@@ -321,7 +337,7 @@ dynamic = new Set()) {
     };
     /** The sub-step's own expectation, unless its testid is deliberately unasserted. */
     const declaredBy = (sub) => {
-        const testid = sub.expect?.element?.testid;
+        const testid = expectedElementTestid(sub.expect);
         return testid === undefined || dynamic.has(testid) ? undefined : testid;
     };
     /**

package/dist/language/flows/flow-store-for-session.d.ts

@@ -24,8 +24,9 @@
  * returned unchanged.
  */
 import { FlowStore } from './flows.js';
+import type { ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
-export declare function flowsForSession(deps: ToolDeps, projectId: string | undefined): {
+export declare function flowsForSession(deps: ToolDeps, projectId: ProjectId | undefined): {
     flows: FlowStore;
     root: string;
 };

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

@@ -12,21 +12,36 @@
  * tool and the `@reticlehq/test` spec runner share one implementation — no divergent oracle.
  * Pure: no IO, no clock.
  */
-import { type FlowExpect, type FlowFile } from '@reticlehq/core';
-import type { EvalResult, Predicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import { type FlowExpect, type FlowFile, type Predicate } from '@reticlehq/core';
+import type { EvalResult } from '@reticlehq/engine/question/predicate/predicate.js';
 import type { FlowReplaySession, WaitForSignal } from './flow-replay-types.js';
 /** The dynamic (LLM-output) testids whose presence is never asserted — same rule replay uses. */
 export declare function dynamicTestids(flow: FlowFile): Set<string>;
 /** The synthetic step.tool a replay appends when it asserts the flow's success oracle. */
 export declare const SUCCESS_STEP_TOOL = "success";
 /** A short human label for the success end-condition, for result rows. */
-export declare function successLabel(success: FlowExpect): string;
-/** Compile a success FlowExpect into a predicate. undefined → nothing assertable (vacuously met). */
-export declare function successToPredicate(success: FlowExpect, dynamic: ReadonlySet<string>): Predicate | undefined;
+export declare function successLabel(success: Predicate | undefined): string;
+/**
+ * What a flow's success oracle actually asserts, once the file has been read and the dynamic
+ * (LLM-output) testids have been taken out of it.
+ *
+ * Most of what this function used to do is gone, and that is the migration working as intended: it
+ * compiled a flat `FlowExpect` into a `Predicate`, and a step's `expect` IS a predicate now, lifted
+ * by the schema when the file is read. It keeps the name and the signature because it is on
+ * `@reticlehq/test`'s published surface, and it still accepts the flat shape for the same reason a
+ * v1 file still loads — a spec written against the old spelling is not wrong, it is old.
+ *
+ * What remains is the DYNAMIC SKIP, and it is not cosmetic. A testid whose content a model writes is
+ * asserted for PRESENCE by the step layer and never for content; a success oracle bound to one would
+ * assert exactly what the flow has already declared unassertable. Dropping every such clause can
+ * leave nothing at all, and `undefined` is the honest answer — vacuously met, the same as declaring
+ * no success, because nothing here was checkable.
+ */
+export declare function successToPredicate(success: Predicate | FlowExpect | undefined, dynamic: ReadonlySet<string>): Predicate | undefined;
 /**
  * Assert a flow's success end-condition after replay. Delegates to the injected waitForSignal (the
  * real waitForPredicate in production, a fake in unit tests). Passes when: no success was declared,
  * OR every success field was dynamic-skipped (vacuously met), OR the compiled predicate held within
  * the injected timeout. Never reads the wall clock.
  */
-export declare function assertSuccess(session: FlowReplaySession, success: FlowExpect | undefined, dynamic: ReadonlySet<string>, waitForSignal: WaitForSignal, timeoutMs: number, since?: number): Promise<EvalResult>;
+export declare function assertSuccess(session: FlowReplaySession, success: Predicate | undefined, dynamic: ReadonlySet<string>, waitForSignal: WaitForSignal, timeoutMs: number, since?: number): Promise<EvalResult>;

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

@@ -12,7 +12,7 @@
  * tool and the `@reticlehq/test` spec runner share one implementation — no divergent oracle.
  * Pure: no IO, no clock.
  */
-import { AnchorKind, PredicateKind } from '@reticlehq/core';
+import { AnchorKind, PredicateKind, clauseOfKind, flowExpectToPredicate, withoutClauses, } from '@reticlehq/core';
 /** The dynamic (LLM-output) testids whose presence is never asserted — same rule replay uses. */
 export function dynamicTestids(flow) {
     return new Set((flow.dynamic ?? [])
@@ -23,145 +23,59 @@ export function dynamicTestids(flow) {
 export const SUCCESS_STEP_TOOL = 'success';
 /** A short human label for the success end-condition, for result rows. */
 export function successLabel(success) {
-    if (success.signal !== undefined)
-        return success.signal;
-    if (success.net !== undefined)
-        return success.net.urlContains ?? success.net.method ?? 'net';
-    if (success.console !== undefined) {
-        return `console:${true === success.console.absent ? 'clean' : (success.console.level ?? 'error')}`;
+    /*
+     * NOT `expectLabel`, and the difference is the reader.
+     *
+     * That one names a clause for a drift row, where `signal:` tells you which channel failed. This
+     * one is `mustHold` in the domain model an agent reads BEFORE testing — a list of what each flow
+     * guarantees — and there the prefix is noise on the commonest case. A signal's own name is the
+     * sentence: "order:placed" is what must hold.
+     */
+    const signal = clauseOfKind(success, PredicateKind.SIGNAL);
+    if (signal?.name !== undefined)
+        return signal.name;
+    const net = clauseOfKind(success, PredicateKind.NET);
+    if (net !== undefined)
+        return net.urlContains ?? net.method ?? 'net';
+    const console_ = clauseOfKind(success, PredicateKind.CONSOLE);
+    if (console_ !== undefined) {
+        return `console:${true === console_.absent ? 'clean' : (console_.level ?? 'error')}`;
     }
-    if (success.state !== undefined)
-        return `state:${success.state.path}`;
-    if (success.text !== undefined)
-        return `text:${success.text.contains}`;
-    return success.element?.testid ?? success.element?.name ?? success.element?.role ?? 'success';
+    const state = clauseOfKind(success, PredicateKind.STATE);
+    if (state !== undefined)
+        return `state:${state.path}`;
+    const text = clauseOfKind(success, PredicateKind.TEXT);
+    if (text?.contains !== undefined)
+        return `text:${text.contains}`;
+    const element = clauseOfKind(success, PredicateKind.ELEMENT);
+    const q = element?.query;
+    return q?.testid ?? q?.name ?? q?.role ?? 'success';
 }
-/** Compile a success FlowExpect into a predicate. undefined → nothing assertable (vacuously met). */
+/**
+ * What a flow's success oracle actually asserts, once the file has been read and the dynamic
+ * (LLM-output) testids have been taken out of it.
+ *
+ * Most of what this function used to do is gone, and that is the migration working as intended: it
+ * compiled a flat `FlowExpect` into a `Predicate`, and a step's `expect` IS a predicate now, lifted
+ * by the schema when the file is read. It keeps the name and the signature because it is on
+ * `@reticlehq/test`'s published surface, and it still accepts the flat shape for the same reason a
+ * v1 file still loads — a spec written against the old spelling is not wrong, it is old.
+ *
+ * What remains is the DYNAMIC SKIP, and it is not cosmetic. A testid whose content a model writes is
+ * asserted for PRESENCE by the step layer and never for content; a success oracle bound to one would
+ * assert exactly what the flow has already declared unassertable. Dropping every such clause can
+ * leave nothing at all, and `undefined` is the honest answer — vacuously met, the same as declaring
+ * no success, because nothing here was checkable.
+ */
 export function successToPredicate(success, dynamic) {
-    const parts = [];
-    if (success.signal !== undefined) {
-        const signal = {
-            kind: PredicateKind.SIGNAL,
-            name: success.signal,
-        };
-        if (success.signalData !== undefined)
-            signal.dataMatches = success.signalData;
-        if (success.signalCount !== undefined) {
-            signal.count = success.signalCount;
-            // Same post-settle reasoning as net.count: the success waiter is wait-until-true, so an exact
-            // count is transiently satisfied the instant the FIRST matching signal fires — before a
-            // double-fire's duplicate arrives. Gating on `settled` forces the count to be read only after
-            // the app goes quiet, by which point the duplicate IS counted and the over-count fails.
-            parts.push({ kind: PredicateKind.SETTLED });
-        }
-        parts.push(signal);
-    }
-    if (success.route !== undefined) {
-        // The mirror of `predicateToExpect`'s ROUTE case. Replay evaluates predicates, so carrying the
-        // route back here is the whole of what makes a recorded navigation able to fail.
-        const route = {
-            kind: PredicateKind.ROUTE,
-        };
-        if (success.route.pathname !== undefined)
-            route.pathname = success.route.pathname;
-        if (success.route.contains !== undefined)
-            route.contains = success.route.contains;
-        return route;
-    }
-    if (success.net !== undefined) {
-        const net = { kind: PredicateKind.NET };
-        if (success.net.method !== undefined)
-            net.method = success.net.method;
-        if (success.net.urlContains !== undefined)
-            net.urlContains = success.net.urlContains;
-        if (success.net.status !== undefined)
-            net.status = success.net.status;
-        if (success.net.count !== undefined) {
-            net.count = success.net.count;
-            // A cardinality assertion is inherently POST-SETTLE. The success waiter is wait-until-true, so an
-            // exact count (e.g. 1) is transiently satisfied the instant the FIRST matching request lands —
-            // before a double-submit's duplicate arrives. Gating on `settled` forces the count to be read
-            // only after the network has gone quiet, so the duplicate IS counted and the over-count fails.
-            parts.push({ kind: PredicateKind.SETTLED });
-        }
-        parts.push(net);
-    }
-    if (success.console !== undefined) {
-        const con = {
-            kind: PredicateKind.CONSOLE,
-        };
-        if (success.console.level !== undefined)
-            con.level = success.console.level;
-        if (success.console.absent !== undefined) {
-            con.absent = success.console.absent;
-            // An `absent` assertion is post-settle, same as net.count: a wait-until-true waiter sees "no
-            // error yet" at the first poll and passes BEFORE the action's error fires. Gate on `settled` so
-            // the console is read only after the page quiets, by which point any error is in the buffer.
-            if (success.console.absent)
-                parts.push({ kind: PredicateKind.SETTLED });
-        }
-        parts.push(con);
-    }
-    const state = success.state;
-    if (state !== undefined) {
-        const part = {
-            kind: PredicateKind.STATE,
-            path: state.path,
-        };
-        if (state.store !== undefined)
-            part.store = state.store;
-        if (state.equals !== undefined)
-            part.equals = state.equals;
-        // `hold` = an INVARIANT ("this state must still hold after the action settles"), vs the default
-        // wait-for-change. A wait-until-true waiter would pass the instant the path already equals the
-        // value — which, for "an unrelated path stayed put", is true BEFORE a side-effect leak fires. Gate
-        // on `settled` so the read happens after the page quiets, by which point the leak has landed.
-        if (true === state.hold)
-            parts.push({ kind: PredicateKind.SETTLED });
-        parts.push(part);
-    }
-    const element = success.element;
-    if (element !== undefined) {
-        const testid = element.testid;
-        // A dynamic-marked testid is NOT asserted as a success condition (presence-only).
-        if (testid === undefined || !dynamic.has(testid)) {
-            const query = {};
-            if (testid !== undefined)
-                query['testid'] = testid;
-            if (element.role !== undefined)
-                query['role'] = element.role;
-            if (element.name !== undefined)
-                query['name'] = element.name;
-            if (Object.keys(query).length > 0)
-                parts.push({ kind: PredicateKind.ELEMENT, query });
-        }
-    }
-    const text = success.text;
-    if (text !== undefined) {
-        const part = {
-            kind: PredicateKind.TEXT,
-            contains: text.contains,
-        };
-        if (text.scope !== undefined)
-            part.scope = text.scope;
-        if (text.visible !== undefined)
-            part.visible = text.visible;
-        if (true === text.absent) {
-            part.absent = true;
-            // Same post-settle reasoning as `console.absent` and `state.hold`: a wait-until-true waiter
-            // reads "not there yet" on the first poll and passes BEFORE the text it is meant to see
-            // disappear has even been rendered. Gate on `settled` so the read happens after the page
-            // quiets, by which point a text that was going to appear has.
-            parts.push({ kind: PredicateKind.SETTLED });
-        }
-        parts.push(part);
-    }
-    const [first] = parts;
-    if (0 === parts.length)
+    if (success === undefined)
         return undefined;
-    if (1 === parts.length && first !== undefined)
-        return first;
-    return { kind: PredicateKind.ALL_OF, predicates: parts };
+    const predicate = 'kind' in success ? success : flowExpectToPredicate(success);
+    if (predicate === undefined)
+        return undefined;
+    return withoutClauses(predicate, (clause) => PredicateKind.ELEMENT === clause.kind &&
+        clause.query.testid !== undefined &&
+        dynamic.has(clause.query.testid));
 }
 /**
  * Assert a flow's success end-condition after replay. Delegates to the injected waitForSignal (the
@@ -170,8 +84,6 @@ export function successToPredicate(success, dynamic) {
  * the injected timeout. Never reads the wall clock.
  */
 export async function assertSuccess(session, success, dynamic, waitForSignal, timeoutMs, since = 0) {
-    if (success === undefined)
-        return { pass: true };
     const predicate = successToPredicate(success, dynamic);
     if (predicate === undefined)
         return { pass: true };

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

@@ -20,6 +20,7 @@ import { recordingBacktrackWarning } from './recording/recording-backtrack.js';
 import { isValidFlowName, flowPath } from '../../memory/project/dir/reticle-dir.js';
 import {} from './flows.js';
 import { flowsForSession } from './flow-store-for-session.js';
+import { rootForProjectId } from '../../memory/project/session-root.js';
 import { resolveSuiteSelection } from './suite-selection.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun, } from '../../judgement/runs/verification-sync.js';
@@ -34,7 +35,10 @@ import { replayAndLearn } from './flow-learning.js';
  */
 async function syncSavedFlowToCloud(deps, flow, projectId) {
     // Per-project cloud: sync a saved flow only when cloud is attached AND flow sync is enabled.
-    const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
+    // The link file of the project this flow belongs to — the flow itself was already saved through
+    // `flowsForSession`, and reading the credential from a different tree is how one project's work
+    // reaches another project's dashboard.
+    const cloud = await resolveProjectCloud(deps.fs, rootForProjectId(deps, projectId), homedir(), process.env);
     if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
     const result = await syncFlowToCloud(flow, cloud.config, projectId, cloudFetch);
@@ -573,7 +577,7 @@ export const FLOW_TOOLS = [
                 ...(selected.unsatisfied === undefined ? {} : { unsatisfied: selected.unsatisfied }),
             };
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
-            const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
+            const cloud = await resolveProjectCloud(deps.fs, rootForProjectId(deps, projectId), homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
             if (server !== null)
                 return server;
@@ -637,7 +641,7 @@ export const FLOW_TOOLS = [
                         : leaseFailureReplay(requested[i] ?? '', o.error),
                     durationMs: o.ok && o.value !== undefined ? o.value.durationMs : 0,
                 }));
-                const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, parallelRuns);
+                const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), parallelRuns);
                 await persistAndSyncVerificationRun(deps, timed, projectId);
                 const verdict = buildSuiteVerdict(parallelRuns, selected.knownRoutes, SuiteIsolation.PER_FLOW_LEASE);
                 return {
@@ -673,7 +677,7 @@ export const FLOW_TOOLS = [
             // `reticle flow` on the command line, so an AGENT running this tool a hundred times learned
             // nothing about which flows are intermittent. Same product, same ledger, two surfaces, and the
             // one an agent uses was the blind half.
-            const flaky = await recordSuiteFlakes(deps.fs, deps.reticleRoot, runs);
+            const flaky = await recordSuiteFlakes(deps.fs, rootForProjectId(deps, projectId), runs);
             // Emit the consolidated run artifact (Runs tab) + best-effort cloud push. Never blocks the verdict.
             await persistAndSyncVerificationRun(deps, timed, projectId);
             const verdict = buildSuiteVerdict(runs, selected.knownRoutes, SuiteIsolation.SHARED_SESSION);

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

@@ -1,7 +1,8 @@
+import { type Predicate, type ProjectId } from '@reticlehq/core';
 export { REDACTED_FILL } from './fields/flow-secret-field.js';
 import { type FlowResult } from './flow-result.js';
 export type { FlowResult } from './flow-result.js';
-import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
+import type { FlowAnchor, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
 import type { CompiledProgram, RecordedStep } from './recording/tape/recordings.js';
 import type { FileSystemPort } from '../../memory/project/fs/fs-port.js';
 import type { Clock } from '../../machine/clock.js';
@@ -48,9 +49,9 @@ interface SaveSummary {
  * the same bytes as before.
  */
 export interface FlowAnnotations {
-    stepExpect: Map<number, FlowExpect>;
+    stepExpect: Map<number, Predicate>;
     dynamic: string[];
-    success?: FlowExpect;
+    success?: Predicate;
     /** The flow's declared business goal (intent annotation). */
     intent?: string;
 }
@@ -63,15 +64,19 @@ export declare class FlowStore {
      * Optionally fold structured annotations (per-step expect, dynamic[], success) onto
      * the flow before writing. Omitting `annotations` reproduces the same bytes.
      */
-    save(program: CompiledProgram, annotations?: FlowAnnotations, projectId?: string): Promise<FlowResult<SaveSummary>>;
+    save(program: CompiledProgram, annotations?: FlowAnnotations, projectId?: ProjectId): Promise<FlowResult<SaveSummary>>;
     /**
      * Persist an already-anchored FlowFile captured in-page (no recompilation). The
      * browser resolved every semantic anchor at capture time; here we only validate the name +
      * re-run FlowFileSchema before writing. save is left untouched.
      */
-    saveFlow(flow: FlowFile, projectId?: string): Promise<FlowResult<SaveSummary>>;
+    saveFlow(flow: FlowFile, projectId?: ProjectId): Promise<FlowResult<SaveSummary>>;
     /** Write back only what a replay LEARNED. See `#changeInPlace` for why it is not `saveFlow`. */
-    recordLearned(name: string, learned: NonNullable<FlowFile['learned']>, projectId?: string): Promise<FlowResult<{
+    recordLearned(name: string, learned: NonNullable<FlowFile['learned']>, projectId?: ProjectId): Promise<FlowResult<{
+        name: string;
+    }>>;
+    /** Give sourceless steps the files a clean replay resolved them to, merged onto the file as it is now. */
+    recordSources(name: string, sources: ReadonlyMap<string, NonNullable<FlowStep['source']>>, projectId?: ProjectId): Promise<FlowResult<{
         name: string;
     }>>;
     /**
@@ -83,7 +88,7 @@ export declare class FlowStore {
      * it with proposals that already cleared HEAL_CONFIDENCE_MIN. A change whose `from` no longer
      * matches the step's anchor is skipped — idempotent and defensive, never throwing.
      */
-    heal(name: string, changes: HealChange[], projectId?: string): Promise<FlowResult<{
+    heal(name: string, changes: HealChange[], projectId?: ProjectId): Promise<FlowResult<{
         name: string;
         changed: HealChange[];
     }>>;
@@ -97,17 +102,17 @@ export declare class FlowStore {
      * the caller as a reportable error, never be silently filtered away. Callers that build a path from a
      * name must validate first; `flowPath` takes a branded FlowName precisely so the compiler insists.
      */
-    list(projectId?: string): Promise<string[]>;
+    list(projectId?: ProjectId): Promise<string[]>;
     /**
      * Read + zod-validate a flow by name. With a `projectId`, prefers the per-project copy and falls
      * back to a legacy flat (untagged) flow of the same name — so pre-existing flows keep loading.
      */
-    load(name: string, projectId?: string): Promise<FlowResult<FlowFile>>;
+    load(name: string, projectId?: ProjectId): Promise<FlowResult<FlowFile>>;
     /**
      * Delete a flow's file so a renamed/obsolete flow stops lingering in the replay list. Resolves the
      * same path `load` would (per-project copy, else legacy flat, else a subdir scan for the no-pid
      * caller), then removes it. NOT_FOUND when nothing resolves — deleting an absent flow is an error,
      * not a silent no-op, so a typo doesn't read as success.
      */
-    remove(name: string, projectId?: string): Promise<FlowResult<void>>;
+    remove(name: string, projectId?: ProjectId): Promise<FlowResult<void>>;
 }

package/dist/language/flows/flows.js

@@ -1,4 +1,4 @@
-import { asFlowName } from '@reticlehq/core';
+import { asFlowName, asProjectId, } from '@reticlehq/core';
 import { REDACTED_FILL } from './fields/flow-secret-field.js';
 export { REDACTED_FILL } from './fields/flow-secret-field.js';
 import { safeProjectId } from './flow-result.js';
@@ -7,6 +7,7 @@ import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, FlowErrorCode, Flo
 import { ReticleTool } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { applyHealChanges } from './heal.js';
+import { withLearnedSources } from './learned-sources.js';
 import { flowIntentGap, linkFlowIntent } from './flow-intent.js';
 import { IntentStore } from '../../memory/intent/intent-store.js';
 import { flowDir, flowParentDir, flowPath, reticleDirPaths, isValidFlowName, } from '../../memory/project/dir/reticle-dir.js';
@@ -351,6 +352,13 @@ export class FlowStore {
             value: { name },
         }));
     }
+    /** Give sourceless steps the files a clean replay resolved them to, merged onto the file as it is now. */
+    async recordSources(name, sources, projectId) {
+        return await this.#changeInPlace(name, projectId, (flow) => ({
+            next: withLearnedSources(flow, sources) ?? flow,
+            value: { name },
+        }));
+    }
     /**
      * Apply confident testid rebinds to an on-disk flow (the `reticle_flow_heal` apply path),
      * rewriting ONLY the named steps' anchors and preserving every other field. Loading, the name
@@ -362,7 +370,8 @@ export class FlowStore {
      */
     async heal(name, changes, projectId) {
         return await this.#changeInPlace(name, projectId, (flow) => {
-            const { flow: next, applied } = applyHealChanges(flow, changes);
+            // The store's injected clock, so a written flow records when the rebind actually happened.
+            const { flow: next, applied } = applyHealChanges(flow, changes, () => this.#clock.now());
             return { next, value: { name, changed: applied } };
         });
     }
@@ -408,8 +417,11 @@ export class FlowStore {
         catch {
             return legacy.sort();
         }
+        // Every subdirectory of `.reticle/flows/` is a project's, by construction: this class is the
+        // only thing that creates one, and it creates it from a projectId that already passed
+        // `safeProjectId`. Reading the name back is the third provenance boundary, not a cast.
         const subdirs = entries.filter((e) => !e.endsWith(FLOW_SUFFIX));
-        const nested = (await Promise.all(subdirs.map((d) => this.#namesIn(flowDir(this.#root, d))))).flat();
+        const nested = (await Promise.all(subdirs.map((d) => this.#namesIn(flowDir(this.#root, asProjectId(d)))))).flat();
         return [...new Set([...legacy, ...nested])].sort();
     }
     /** The path a flow actually lives at: nested (per-project) if present, else legacy flat, else null. */
@@ -441,8 +453,9 @@ export class FlowStore {
         catch {
             return null;
         }
+        // Same provenance as `#namesIn`'s scan above: a subdir of `.reticle/flows/` is a projectId.
         for (const dir of entries.filter((e) => !e.endsWith(FLOW_SUFFIX))) {
-            const nested = flowPath(this.#root, name, dir);
+            const nested = flowPath(this.#root, name, asProjectId(dir));
             if (await this.#fs.exists(nested))
                 return nested;
         }

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

@@ -25,7 +25,15 @@ export declare function confidenceFor(from: string, to: string): number;
  * skipped (idempotent / defensive), never throwing. Shared by the on-disk writer (FlowStore.heal)
  * and the in-memory pre-write verification in reticle_flow_heal, so both rewrite identically.
  */
-export declare function applyHealChanges(flow: FlowFile, changes: HealChange[]): {
+export declare function applyHealChanges(flow: FlowFile, changes: HealChange[], 
+/**
+ * When the rebind happened. Injected rather than read here, because this function is pure and a
+ * clock inside it would make the flow it returns depend on when a test ran.
+ *
+ * Optional so every existing caller keeps working; without it the step still records WHICH anchor
+ * was replaced, which is the half a reader actually acts on.
+ */
+now?: () => number): {
     flow: FlowFile;
     applied: HealChange[];
 };

package/dist/language/flows/heal.js

@@ -38,7 +38,15 @@ export function confidenceFor(from, to) {
  * skipped (idempotent / defensive), never throwing. Shared by the on-disk writer (FlowStore.heal)
  * and the in-memory pre-write verification in reticle_flow_heal, so both rewrite identically.
  */
-export function applyHealChanges(flow, changes) {
+export function applyHealChanges(flow, changes, 
+/**
+ * When the rebind happened. Injected rather than read here, because this function is pure and a
+ * clock inside it would make the flow it returns depend on when a test ran.
+ *
+ * Optional so every existing caller keeps working; without it the step still records WHICH anchor
+ * was replaced, which is the half a reader actually acts on.
+ */
+now) {
     const byStep = new Map();
     for (const change of changes)
         byStep.set(change.step, change);
@@ -51,7 +59,21 @@ export function applyHealChanges(flow, changes) {
             return step;
         }
         applied.push(change);
-        return { ...step, anchor: { kind: AnchorKind.TESTID, value: change.to } };
+        return {
+            ...step,
+            anchor: { kind: AnchorKind.TESTID, value: change.to },
+            /*
+             * `from` is the ORIGINAL recorded anchor, kept across later heals.
+             *
+             * A step healed twice has an intermediate name nobody ever chose, so overwriting with the
+             * newest would throw away the only anchor a reader wants — the one that was recorded by
+             * driving. The timestamp is the LATEST heal, because that is when this anchor arrived.
+             */
+            healed: {
+                from: step.healed?.from ?? change.from,
+                at: now?.() ?? step.healed?.at ?? 0,
+            },
+        };
     });
     return { flow: { ...flow, steps }, applied };
 }

package/dist/language/flows/learned-sources.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Learn a flow step's source file from the element its anchor resolved to on a replay.
+ *
+ * A step recorded before the build stamped the app names no file, so a scoped re-verify cannot say
+ * which edits it covers. Every replay already asks the page for each anchor's element, and that
+ * element carries its stamp now: this records the answer at the one place every resolution passes
+ * through (the session's QUERY), rather than threading it through each step runner.
+ */
+import { type FlowFile, type FlowStep } from '@reticlehq/core';
+import type { FlowReplaySession } from './flow-replay-types.js';
+type StepSource = NonNullable<FlowStep['source']>;
+/** `src/Pay.tsx:12:4` or `src/Pay.tsx:12` → `{file, line}`; anything else is not a location. */
+export declare function parseCompactSource(value: string): StepSource | undefined;
+/** Wrap a replay session so every anchor QUERY that resolves to one stamped element is remembered. */
+export declare function recordingSources(inner: FlowReplaySession): {
+    session: FlowReplaySession;
+    sources: ReadonlyMap<string, StepSource>;
+};
+/** The flow with every sourceless step given the file its anchor resolved to; undefined if none was. */
+export declare function withLearnedSources(flow: FlowFile, sources: ReadonlyMap<string, StepSource>): FlowFile | undefined;
+export {};