@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,52 @@
+import { type FlowFile, type InstrumentationGap } from '@reticlehq/core';
+import { IntentStore } from '../../memory/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/language/flows/flow-intent.js

@@ -0,0 +1,123 @@
+import { InstrumentationGapKind, instrumentationGap, } from '@reticlehq/core';
+import { IntentStore } from '../../memory/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/language/flows/flow-learning.d.ts

@@ -0,0 +1,52 @@
+import type { FlowReplayResult } from '@reticlehq/core';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/**
+ * Write back what a replay taught the flow, once the replay has finished writing its own.
+ *
+ * Deliberately OUTSIDE `replayNamedFlow`. Persisting from inside it broke the intent bookkeeping —
+ * a replay records the intent it discharged on the same file, and a second writer in the middle of
+ * that turned `proved` back into `bound`. The test that caught it is
+ * `a passing replay marks the intent proved with the verdict that did it`, and the lesson is
+ * general: a read-modify-write layered into someone else's transaction is a rollback wearing an
+ * update's clothes.
+ *
+ * So this runs after the replay has returned and re-reads the flow first, merging only `learned`
+ * onto whatever the file now says.
+ *
+ * Best-effort by construction: a store that refuses the write must not turn a completed replay into
+ * a failed one. The verdict is about the app; this is bookkeeping about the flow, and losing a
+ * lesson is a smaller loss than losing the run that produced it.
+ */
+export declare function persistLearning(deps: ToolDeps, args: Record<string, unknown>, result: FlowReplayResult): Promise<FlowReplayResult>;
+/**
+ * Replay a flow AND keep what it learned. The entry point every ordinary replay should use.
+ *
+ * Every replay path must route through here, not `replayNamedFlow` — promotion needs CONSECUTIVE
+ * clean runs, so a path that skips the write-back promotes nothing while still reporting `learned`
+ * and `promoted`.
+ *
+ * Wrapped here rather than inside `replayNamedFlow`, for the reason `persistLearning` above gives:
+ * persisting from inside it puts a second writer in the middle of the replay's own intent
+ * bookkeeping and turns `proved` back into `bound`.
+ *
+ * ── WHO MUST NOT USE THIS ───────────────────────────────────────────────────────────────────────
+ * Two callers replay deliberately BROKEN conditions and call `replayNamedFlow` directly on purpose:
+ *
+ * - mutation testing (`flow-mutate-tools.ts`) breaks the app to check the flow notices. Learning
+ *   from that teaches the flow about a defect nobody shipped.
+ * - the perturbed branch of the seed path slows the network to see what the flow does under stress.
+ *   A finding that appears only under perturbation is not a fact about the app.
+ *
+ * Both write a finding that would then have to STOP appearing to be promoted — so the damage is not
+ * a wrong guard today, it is a guard earned against a condition the app is never in.
+ */
+export declare function replayAndLearn(deps: ToolDeps, 
+/**
+ * The tool's args, WHOLE.
+ *
+ * Narrowed to `{ flowName, sessionId }` in the first draft, which silently dropped
+ * `confirmDangerous` — so a replay that had been authorised to drive a destructive control lost
+ * that authorisation on its way through here and refused the step. `tools.flow-replay.test.ts`
+ * caught it. `seed` and anything added later travel the same path, so the whole object goes.
+ */
+args: Record<string, unknown>): Promise<FlowReplayResult>;

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

@@ -0,0 +1,76 @@
+import { asString } from '@reticlehq/core';
+import { flowsForSession } from './flow-store-for-session.js';
+import { replayNamedFlow } from './flow-replay-run.js';
+/**
+ * Write back what a replay taught the flow, once the replay has finished writing its own.
+ *
+ * Deliberately OUTSIDE `replayNamedFlow`. Persisting from inside it broke the intent bookkeeping —
+ * a replay records the intent it discharged on the same file, and a second writer in the middle of
+ * that turned `proved` back into `bound`. The test that caught it is
+ * `a passing replay marks the intent proved with the verdict that did it`, and the lesson is
+ * general: a read-modify-write layered into someone else's transaction is a rollback wearing an
+ * update's clothes.
+ *
+ * So this runs after the replay has returned and re-reads the flow first, merging only `learned`
+ * onto whatever the file now says.
+ *
+ * Best-effort by construction: a store that refuses the write must not turn a completed replay into
+ * a failed one. The verdict is about the app; this is bookkeeping about the flow, and losing a
+ * lesson is a smaller loss than losing the run that produced it.
+ */
+export async function persistLearning(deps, args, result) {
+    const learned = result.learned;
+    if (learned === undefined || 0 === learned.length)
+        return result;
+    const name = asString(args['flowName']) ?? '';
+    if (0 === name.length)
+        return result;
+    try {
+        let projectId;
+        try {
+            projectId = deps.sessions.resolve(asString(args['sessionId'])).projectId;
+        }
+        catch {
+            projectId = undefined;
+        }
+        await flowsForSession(deps, projectId).flows.recordLearned(name, learned, projectId);
+    }
+    catch {
+        // Bookkeeping only.
+    }
+    return result;
+}
+/**
+ * Replay a flow AND keep what it learned. The entry point every ordinary replay should use.
+ *
+ * Every replay path must route through here, not `replayNamedFlow` — promotion needs CONSECUTIVE
+ * clean runs, so a path that skips the write-back promotes nothing while still reporting `learned`
+ * and `promoted`.
+ *
+ * Wrapped here rather than inside `replayNamedFlow`, for the reason `persistLearning` above gives:
+ * persisting from inside it puts a second writer in the middle of the replay's own intent
+ * bookkeeping and turns `proved` back into `bound`.
+ *
+ * ── WHO MUST NOT USE THIS ───────────────────────────────────────────────────────────────────────
+ * Two callers replay deliberately BROKEN conditions and call `replayNamedFlow` directly on purpose:
+ *
+ * - mutation testing (`flow-mutate-tools.ts`) breaks the app to check the flow notices. Learning
+ *   from that teaches the flow about a defect nobody shipped.
+ * - the perturbed branch of the seed path slows the network to see what the flow does under stress.
+ *   A finding that appears only under perturbation is not a fact about the app.
+ *
+ * Both write a finding that would then have to STOP appearing to be promoted — so the damage is not
+ * a wrong guard today, it is a guard earned against a condition the app is never in.
+ */
+export async function replayAndLearn(deps, 
+/**
+ * The tool's args, WHOLE.
+ *
+ * Narrowed to `{ flowName, sessionId }` in the first draft, which silently dropped
+ * `confirmDangerous` — so a replay that had been authorised to drive a destructive control lost
+ * that authorisation on its way through here and refused the step. `tools.flow-replay.test.ts`
+ * caught it. `seed` and anything added later travel the same path, so the whole object goes.
+ */
+args) {
+    return await persistLearning(deps, args, await replayNamedFlow(deps, args));
+}

package/dist/language/flows/flow-mutate-tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The question that grades the FLOW rather than the app: would it notice if the thing it depends on
+ * broke?
+ *
+ * Every decision behind the answer was made and tested apart — the target comes from what the flow
+ * itself declared, the loop guarantees the page is put back, and the grade refuses to count what it
+ * did not establish. This is the call that joins them, and its own job is mostly knowing when to
+ * answer NOTHING.
+ *
+ * Both refusals below produce no outcome on purpose. A mutation score that reports a demotion it did
+ * not measure is worse than one that reports less: it is a number arguing to delete good tests.
+ */
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+export declare const FLOW_MUTATE_TOOL: ToolDef;

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

@@ -0,0 +1,82 @@
+/**
+ * The question that grades the FLOW rather than the app: would it notice if the thing it depends on
+ * broke?
+ *
+ * Every decision behind the answer was made and tested apart — the target comes from what the flow
+ * itself declared, the loop guarantees the page is put back, and the grade refuses to count what it
+ * did not establish. This is the call that joins them, and its own job is mostly knowing when to
+ * answer NOTHING.
+ *
+ * Both refusals below produce no outcome on purpose. A mutation score that reports a demotion it did
+ * not measure is worse than one that reports less: it is a number arguing to delete good tests.
+ */
+import { mutationTargetsFor, ReticleTool, asString } from '@reticlehq/core';
+import { MutationOutcome } from 'open-verification';
+import { z } from 'zod';
+import { sessionMutationPort } from '../../surface/tools/lease-tools.js';
+import { mutationTest } from './mutation-run.js';
+import { replayNamedFlow, sessionProjectId } from './flow-replay-run.js';
+import { flowsForSession } from './flow-store-for-session.js';
+import { ReplayStatus } from '@reticlehq/core';
+const NOTHING_DECLARED = 'this flow declares no network consequence, so it has named nothing whose breakage it could be ' +
+    'expected to notice. Breaking something it never claimed to depend on would manufacture a ' +
+    'demotion rather than measure one. Give a step an `expect: { net: { urlContains } }`, or set the ' +
+    "flow's `success` to a net consequence, and it becomes mutation-testable.";
+const NEEDS_A_DRIVEN_PAGE = 'nothing here can break the page: mutation needs a DRIVEN browser (`reticle drive` / ' +
+    'RETICLE_CDP_URL). An attached tab cannot be perturbed from inside itself, and reporting ' +
+    '"survived" without applying anything would demote every flow on every project that has not driven.';
+export const FLOW_MUTATE_TOOL = {
+    name: ReticleTool.FLOW_MUTATE,
+    description: 'Does this flow NOTICE when the thing it depends on breaks? Replays it, fails the endpoint the flow itself declared it needs, replays it again, and grades the FLOW: "killed" (it went red — it is a real test), "survived" (it stayed green through a broken subject — it is a click sequence, not a test), or "inconclusive" (nothing was established, and it says which). The page is always put back, including when a replay throws. DESTRUCTIVE: really breaks a request on a driven page for the duration.',
+    inputSchema: {
+        flowName: z
+            .string()
+            .optional()
+            .describe('Flow file name (without .json), from reticle_flow{action:"list"}.'),
+        // The same thing under the other name this surface already uses. Both, because an agent that
+        // learned `flow` from reticle_annotate must not be refused here — see surface-consistency.
+        flow: z.string().optional().describe('Alias for `flowName`.'),
+        sessionId: z.string().optional(),
+    },
+    outputSchema: {
+        flow: z.string(),
+        /** Absent when nothing was established — `because` then says why, and it is never a demotion. */
+        outcome: z.string().optional(),
+        target: z.string().optional(),
+        because: z.string(),
+    },
+    handler: async (deps, args) => {
+        const name = asString(args['flowName']) ?? asString(args['flow']) ?? '';
+        const sessionId = asString(args['sessionId']);
+        const projectId = sessionProjectId(deps, sessionId);
+        const loaded = await flowsForSession(deps, projectId).flows.load(name, projectId);
+        if (!loaded.ok) {
+            return { flow: name, because: `could not load "${name}": ${String(loaded.code)}` };
+        }
+        const flow = loaded.value;
+        const target = mutationTargetsFor(flow)[0];
+        if (target === undefined)
+            return { flow: name, because: NOTHING_DECLARED };
+        const port = await sessionMutationPort(deps.realInput, deps.sessions.resolve(sessionId)?.url);
+        if (port === undefined)
+            return { flow: name, target, because: NEEDS_A_DRIVEN_PAGE };
+        const outcome = await mutationTest({
+            replay: async () => {
+                const result = await replayNamedFlow(deps, { flowName: name, sessionId });
+                return ReplayStatus.OK === result.status ? 'pass' : 'fail';
+            },
+            mutate: (mutation) => port.mutate(mutation),
+            revert: () => port.revert(),
+        }, { kind: 'request-fails', target });
+        return { flow: name, target, outcome, because: becauseOf(outcome, target) };
+    },
+};
+function becauseOf(outcome, target) {
+    if (MutationOutcome.KILLED === outcome) {
+        return `the flow went red when ${target} failed — it is testing what it appears to test`;
+    }
+    if (MutationOutcome.SURVIVED === outcome) {
+        return `the flow stayed GREEN while ${target} failed, which it declared it depends on. It is not a test, it is a click sequence — give the step that calls ${target} an \`expect\` naming the consequence it causes`;
+    }
+    return `nothing was established about this flow: it was already failing, the break could not be applied, or a replay did not finish. The page was put back either way`;
+}

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

@@ -0,0 +1,91 @@
+import { FlowErrorCode, type CommandResult, type FlowFile, type FlowReplayResult, type Contradiction, type FlowStepResult, type ReticleEvent } from '@reticlehq/core';
+import type { ArrivalClock } from '../../surface/tools/act/navigation/navigate-arrival.js';
+import type { SessionManager } from '../../portal/session/session-manager.js';
+import type { Session } from '../../portal/session/session.js';
+import { DocumentLostDuringReplay } from './flow-replay.js';
+import type { ToolDeps } from '../../surface/tools/tool-kit.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;
+/**
+ * Replay's half of the FlowFile contract: navigate to the flow's `startPath` before step 1.
+ *
+ * A full-page load tears down the session socket, so the navigation must happen here — before any
+ * step runs — and the replay continues on the session the SDK reconnects as (found via the same
+ * tombstone rebind that lets `resolve(oldId)` answer after any navigation). Best-effort by design:
+ * when the flow carries no startPath, the tab is already there, the current route is unobservable,
+ * the navigation is refused, or the SDK never reconnects in the window, it returns undefined and
+ * replay proceeds on the connected session as before — with startPathMismatchHint turning any
+ * resulting drift into an actionable next move rather than a mystifying one.
+ */
+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>;
+/**
+ * Send a tab somewhere and wait for the session that comes back.
+ *
+ * A navigation is a full page load: the session that issued it DIES and a successor connects with a
+ * new id. Every caller therefore has to wait for that successor rather than reuse the handle it
+ * already holds, and getting this wrong does not error — it leaves the caller talking to a session
+ * that will never answer again.
+ *
+ * Extracted so there is ONE of these rather than one per caller. `arriveAtStartPath` decides WHETHER
+ * to move and this decides how, which is also why the deliberate short-circuits live up there and
+ * not in here: a caller that has already decided it must move should not have to argue with them.
+ */
+export declare function navigateAndAwait(sessions: SessionManager, session: {
+    id: string;
+    /** Optional because a session's URL is, and `carryReticleIdentity` already handles its absence. */
+    url?: string;
+    command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
+}, destination: string, expectedPath: string, timeoutMs?: number, clock?: ArrivalClock): Promise<Session | undefined>;
+/**
+ * The honest answer when the document replay was driving went away mid-run.
+ *
+ * Not a pass: nothing graded the journey, and the steps in hand are only the ones the departed
+ * document answered. Not a failure either — the app was never observed doing anything wrong, and
+ * reporting one would be the false red that sends a reader into product code that is fine. So it
+ * lands in the bucket this engine already has for "nothing was proved", the same one an unmet
+ * precondition uses, with the steps that DID answer attached and no row invented for the one that
+ * did not.
+ *
+ * Why replay reports rather than follows: the successor cannot be identified at the moment the
+ * socket closes. `SessionManager.remove` runs from the close handler, writes the tombstone a
+ * successor is later matched against, and has nothing to match yet — so the rejection is a plain
+ * transport failure by design, and a step in the middle of a journey has no budget to sit and poll
+ * with. `navigateAndAwait` CAN wait, because it knows it asked for the navigation, and it does.
+ */
+export declare function lostDocumentResult(name: string, lost: DocumentLostDuringReplay): FlowReplayResult;
+export declare function replayNamedFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowReplayResult>;
+export declare function crossStepOnly(whole: readonly Contradiction[], steps: readonly FlowStepResult[]): Contradiction[];
+/**
+ * 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.
+ *
+ * Re-exported, not re-implemented. This file carried a BYTE-IDENTICAL second copy, and the two
+ * drifted the moment `ProjectId` was threaded: `session-root`'s copy returned the brand while this
+ * one returned `string`, so every flow tool importing from here was handed a widened value and lost
+ * the brand one line after it was minted. Exactly the weak-annotation failure the brand's own doc
+ * records against `RunStore.list()`.
+ */
+export { sessionProjectId } from '../../memory/project/session-root.js';