@reticlehq/server 3.7.0 → 3.8.1

package/dist/language/flows/flows.js

@@ -1,18 +1,22 @@
 import { asFlowName, asProjectId, } from '@reticlehq/core';
-import { REDACTED_FILL, SECRET_NAME_ARG, secretEnvKey } from './fields/flow-secret-field.js';
+import { REDACTED_FILL, SECRET_FIELD_ARG, SECRET_NAME_ARG, secretEnvKey, withDistinctSecretKeys, } from './fields/flow-secret-field.js';
 export { REDACTED_FILL, secretEnvKey } from './fields/flow-secret-field.js';
 import { safeProjectId } from './flow-result.js';
 import { changeInPlace } from './narrow-write.js';
-import { AnchorKind, DEGRADED_ANCHOR_ROLE, FLOW_FILE_VERSION, flowFileVersionFor, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, defaultIsSensitiveKey, } from '@reticlehq/core';
-import { ReticleTool, flowJsonReplacer } from '@reticlehq/core';
+import { dirname } from 'node:path';
+import { gitTracks } from '../../machine/git-tracks.js';
+import { AnchorKind, DEGRADED_ANCHOR_ROLE, DOCUMENT_ANCHOR_ROLE, FLOW_FILE_VERSION, flowFileVersionFor, FlowErrorCode, FlowFileSchema, FlowStepTool, QueryBy, defaultIsSensitiveKey, isGlobalPressCall, } from '@reticlehq/core';
+import { ReticleTool, flowJsonReplacer, mainCheckoutTwin } 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 { journeyFingerprint, journeyName, mergeJourney, routeClaims, withinJourney, } from './flow-journey.js';
 import { IntentStore } from '../../memory/intent/intent-store.js';
+import { readTextOrUndefined } from '../../memory/project/fs/fs-port.js';
 import { flowDir, flowParentDir, flowPath, reticleDirPaths, isValidFlowName, } from '../../memory/project/dir/reticle-dir.js';
 import { describeFlowZodFailure, parseFlowFileText } from './flow-expect-grammar.js';
+import { readyForReplay, replayability, Replayable, } from './flow-replayable.js';
 /**
  * The anchor for a DEGRADED step (no resolvable testid). A volatile eXX ref is NEVER persisted —
  * the on-disk flow carries a placeholder ROLE anchor + degraded:true instead, so a ref can never
@@ -64,6 +68,9 @@ export function anchorForStep(args) {
         const source = sourceArg(args);
         if (source !== undefined)
             anchor.source = source;
+        const of = args['of'];
+        if ('number' === typeof of && 1 < of)
+            anchor.of = of;
         return { anchor, degraded: false };
     }
     // Role + NAME is a real anchor, not a degraded placeholder.
@@ -73,6 +80,14 @@ export function anchorForStep(args) {
     // that means "add a data-testid". So a step the recorder anchored by accessible name arrived here
     // and had that name thrown away, which is precisely the anchor that distinguishes one row's
     // control from another's when a shared JSX source location cannot.
+    // A document-key press compiled with no element (#1559): a real anchor, not a degraded one. It is
+    // nameless on purpose, because it names no element; the press is what replay dispatches.
+    if (by === QueryBy.ROLE &&
+        value === DOCUMENT_ANCHOR_ROLE &&
+        args['name'] === undefined &&
+        isGlobalPressCall({ action: args['action'], args: args['args'] })) {
+        return { anchor: { kind: AnchorKind.ROLE, role: DOCUMENT_ANCHOR_ROLE }, degraded: false };
+    }
     if (by === QueryBy.ROLE && value !== undefined) {
         const name = asString(args['name']);
         if (name !== undefined && name.length > 0) {
@@ -96,7 +111,8 @@ function subStepToFlowStep(raw) {
     const action = asString(sub['action']);
     const args = asRecord(sub['args']);
     const { anchor, degraded } = anchorForStep(sub);
-    const step = buildStep(ReticleTool.ACT, anchor, action, args, degraded);
+    const step = buildStep(ReticleTool.ACT, anchor, action, args, degraded, markedSecret(sub));
+    keepRoleSource(step, sub);
     /*
      * The sub-step's own declared consequence, carried rather than folded into the parent.
      *
@@ -124,15 +140,23 @@ function subStepToFlowStep(raw) {
  * `defaultIsSensitiveKey` is the same rule the network channel redacts by, so a field considered
  * sensitive on the wire cannot be considered safe on disk.
  */
-function redactSecretFill(anchor, args) {
+function redactSecretFill(anchor, args, 
+/** The SDK said the target holds a secret: redact whatever the field is called. */
+secret = false) {
     if (typeof args['value'] !== 'string')
         return args;
     const field = anchorFieldName(anchor);
-    if (field === undefined || !defaultIsSensitiveKey(field))
+    const sensitive = secret || (field !== undefined && defaultIsSensitiveKey(field));
+    if (!sensitive)
         return args;
+    // ponytail: a secret field with no name (a component anchor) gets no variable; replay then refuses it.
+    if (field === undefined)
+        return { ...args, value: REDACTED_FILL };
     // The variable that supplies it, beside the placeholder: the file alone says what to set.
     return { ...args, value: REDACTED_FILL, [SECRET_NAME_ARG]: secretEnvKey(field) };
 }
+/** Whether a recorded step's args carry the SDK's secret mark. */
+const markedSecret = (args) => true === args[SECRET_FIELD_ARG];
 /**
  * The recorded steps as they may be SHOWN: every credential fill carries the placeholder.
  *
@@ -154,7 +178,7 @@ function redactNormalizedArgs(normalized) {
     const inner = normalized['args'];
     if ('object' !== typeof inner || null === inner)
         return normalized;
-    const redacted = redactSecretFill(anchorForStep(normalized).anchor, asRecord(inner));
+    const redacted = redactSecretFill(anchorForStep(normalized).anchor, asRecord(inner), markedSecret(normalized));
     return redacted === inner ? normalized : { ...normalized, args: redacted };
 }
 /**
@@ -179,8 +203,19 @@ export function anchorFieldName(anchor) {
         return anchor.name;
     return undefined;
 }
-function buildStep(tool, anchor, action, args, degraded) {
-    const step = { tool, anchor, args: redactSecretFill(anchor, args) };
+/**
+ * A role anchor has no room for a source, so the stamped source goes on the step. Without it the
+ * flow named no file: the gate called the driven component unflowed, and `affected` replayed the
+ * flow for every change.
+ */
+function keepRoleSource(step, src) {
+    const source = sourceArg(src);
+    if (AnchorKind.ROLE === step.anchor.kind && source !== undefined) {
+        step.source = { file: source.file, line: source.line };
+    }
+}
+function buildStep(tool, anchor, action, args, degraded, secret = false) {
+    const step = { tool, anchor, args: redactSecretFill(anchor, args, secret) };
     if (action !== undefined)
         step.action = action;
     if (degraded)
@@ -200,6 +235,8 @@ export function recordedStepToFlowStep(step) {
         out.page = step.page;
     if (step.endPage !== undefined && step.endPage !== step.page)
         out.endPage = step.endPage;
+    if (true === step.writes)
+        out.writes = true;
     return out;
 }
 function anchoredStep(step) {
@@ -235,7 +272,8 @@ function anchoredStep(step) {
     const action = asString(step.args['action']);
     const args = asRecord(step.args['args']);
     const { anchor, degraded } = anchorForStep(step.args);
-    const out = buildStep(step.tool, anchor, action, args, degraded);
+    const out = buildStep(step.tool, anchor, action, args, degraded, markedSecret(step.args));
+    keepRoleSource(out, step.args);
     if (step.expect !== undefined)
         out.expect = step.expect;
     return out;
@@ -271,11 +309,24 @@ export class FlowStore {
      * new run (`RunStore` takes the same callback). Without it a flow saved with no run behind it
      * waited for the timer, and a daemon that exited first never sent it.
      */
+    /**
+     * The main checkout's flows, read-only, when this store sits in a linked git worktree and git
+     * ignores `.reticle/`. A flow saved there is then still replayed here. Writes never go to it.
+     * When git tracks `.reticle/`, the worktree already has every committed flow, and reading the
+     * main checkout brought back a flow that the branch deleted.
+     */
+    #main;
     constructor(fs, root, clock, opts = {}) {
         this.#fs = fs;
         this.#root = root;
         this.#clock = clock;
         this.#onWrote = opts.onWrote;
+        const twin = mainCheckoutTwin(root, readTextOrUndefined);
+        // The main checkout has no twin of its own, so this never nests deeper than one level.
+        this.#main =
+            twin === undefined || gitTracks(reticleDirPaths(root).flows)
+                ? undefined
+                : new FlowStore(fs, twin, clock);
     }
     /**
      * The single byte-stable flow serializer: 2-space indent + one trailing newline. save,
@@ -306,12 +357,16 @@ export class FlowStore {
      */
     #summary(flow) {
         const gap = flowIntentGap(flow);
+        const replay = replayability(flow);
         return {
             name: flow.name,
             stepCount: flow.steps.length,
             degraded: flow.steps.filter((s) => true === s.degraded).length,
             empty: 0 === flow.steps.length,
             ...(gap === undefined ? {} : { intentGap: gap }),
+            ...(Replayable.YES === replay.status && replay.writes === undefined
+                ? {}
+                : { replayability: replay }),
         };
     }
     /** The on-disk flow a compiled recording becomes, before anything is written. */
@@ -336,13 +391,17 @@ export class FlowStore {
         };
         const intent = program.steps.find((step) => step.intent !== undefined)?.intent;
         const annotated = withAnnotations(base, annotations);
-        return {
+        return readyForReplay(withDistinctSecretKeys({
             ...annotated,
             // The action's own intent, when nobody annotated the flow — see RecordedStep.intent.
             ...(annotated.intent === undefined && intent !== undefined ? { intent } : {}),
+            // Else the sentence an auto-saved drive built from its expects, marked as built.
+            ...(annotated.intent === undefined && intent === undefined && program.intent !== undefined
+                ? { intent: program.intent, ...(program.intentDerived ? { intentDerived: true } : {}) }
+                : {}),
             ...routeClaims(annotated.startPath, annotated.steps),
             ...(program.author === undefined ? {} : { author: program.author }),
-        };
+        }));
     }
     /**
      * Convert a CompiledProgram (testid-normalized) into an anchored, on-disk flow + write it.
@@ -458,7 +517,7 @@ export class FlowStore {
                 detail: describeFlowZodFailure(parsed.error),
             };
         }
-        const valid = await this.#linkIntent(parsed.data);
+        const valid = await this.#linkIntent(readyForReplay(parsed.data));
         await this.#fs.mkdir(flowParentDir(this.#root, asFlowName(valid.name), pid));
         await this.#fs.writeFile(flowPath(this.#root, asFlowName(valid.name), pid), this.#serialize(valid));
         this.#onWrote?.();
@@ -477,8 +536,12 @@ export class FlowStore {
             load: (n, p) => this.load(n, p),
             // Branded at the boundary: the port speaks strings, the store speaks FlowName, and the
             // name has already passed isValidFlowName inside changeInPlace.
-            resolvePath: (n, p) => this.#resolveReadPath(asFlowName(n), p),
-            write: (path, contents) => this.#fs.writeFile(path, contents),
+            // A flow read from the main checkout is changed in a copy in this worktree.
+            resolvePath: async (n, p) => (await this.#resolveReadPath(asFlowName(n), p)) ?? flowPath(this.#root, asFlowName(n), p),
+            write: async (path, contents) => {
+                await this.#fs.mkdir(dirname(path));
+                await this.#fs.writeFile(path, contents);
+            },
             serialize: (flow) => this.#serialize(flow),
             readRaw: (path) => this.#fs.readFile(path),
         }, name, projectId, change);
@@ -539,6 +602,12 @@ export class FlowStore {
      * name must validate first; `flowPath` takes a branded FlowName precisely so the compiler insists.
      */
     async list(projectId) {
+        const own = await this.#listOwn(projectId);
+        if (this.#main === undefined)
+            return own;
+        return [...new Set([...own, ...(await this.#main.list(projectId))])].sort();
+    }
+    async #listOwn(projectId) {
         const flowsDir = reticleDirPaths(this.#root).flows;
         const pid = safeProjectId(projectId);
         const legacy = await this.#namesIn(flowsDir);
@@ -604,6 +673,12 @@ export class FlowStore {
      * back to a legacy flat (untagged) flow of the same name — so pre-existing flows keep loading.
      */
     async load(name, projectId) {
+        const own = await this.#loadOwn(name, projectId);
+        if (own.ok || own.code !== FlowErrorCode.NOT_FOUND || this.#main === undefined)
+            return own;
+        return this.#main.load(name, projectId);
+    }
+    async #loadOwn(name, projectId) {
         if (!isValidFlowName(name))
             return { ok: false, code: FlowErrorCode.INVALID_NAME };
         const path = await this.#resolveReadPath(name, safeProjectId(projectId));

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

@@ -6,12 +6,18 @@
  * fires (heal the locator, never the intent).
  */
 import { type FlowHealResult } from '@reticlehq/core';
+import { DriftReason } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /**
- * Why heal produced no proposal: a floor it consulted, or a kind of drift it cannot rebind.
+ * Why heal produced no proposal. Three cases.
  *
- * Exported for its own test — the distinction is a sentence a reader ACTS on, and the wrong one
- * sends them to lower a threshold that had no part in the refusal.
+ * A testid anchor drifted, but no candidate cleared the confidence floor: UNHEALABLE.
+ * Every drift is a consequence (the anchors resolved, the assertion failed): NOT_A_REBIND.
+ * Any other drift means an anchor did not resolve, so the step did not run: ANCHOR_UNRESOLVED.
+ * That message names the nearest candidate when there is one.
+ *
+ * Exported for its own test. A reader acts on this sentence, and the wrong one sends them to
+ * lower a threshold that had no part in the refusal.
  */
-export declare function unhealableMessage(reasons: readonly string[]): string;
+export declare function unhealableMessage(reasons: readonly DriftReason[], nearest?: string | null): string;
 export declare function healFlow(deps: ToolDeps, args: Record<string, unknown>): Promise<FlowHealResult>;

package/dist/language/flows/heal-run.js

@@ -6,7 +6,7 @@
  * fires (heal the locator, never the intent).
  */
 import { FLOW_SIGNAL_TIMEOUT_MS, HEAL_CONFIDENCE_MIN, HealStatus, ReplayStatus, } from '@reticlehq/core';
-import { asString, DriftReason } from '@reticlehq/core';
+import { asString, DriftReason, isConsequenceDrift } from '@reticlehq/core';
 import { waitForPredicate } from '@reticlehq/engine/question/predicate/predicate.js';
 import { replayFlow } from './flow-replay.js';
 import { applyHealChanges, collectProposals } from './heal.js';
@@ -30,24 +30,39 @@ const HEAL_MESSAGES = {
      * questions.
      */
     NOT_A_REBIND: 'drift found, but none of it is a renamed locator, so there is nothing to rebind — the anchors resolved and what failed was what the steps assert afterwards. The confidence floor was never consulted. Fix the app so the consequence fires again, or update the step expectations by hand',
+    ANCHOR_UNRESOLVED: 'drift found, but a step anchor did not resolve on the page, so the step did not run. Heal does not rebind this kind of anchor, and the confidence floor was not used. Update the step anchor by hand',
+    ANCHOR_NEAREST_PREFIX: 'The nearest candidate on the page is',
     HEALED_UNVERIFIED: "rewrote drifted testid anchors. This flow declares its consequences per STEP rather than as a flow `success`, so the rebind was not re-verified end to end — the steps will assert on the next replay, but nothing proved the healed flow still reaches its outcome. Set the flow's `success` (reticle_annotate) to have future heals re-verified before they are written.",
     CONSEQUENCE_BROKEN: 'rebind resolves the drifted locator to a surviving element, but the healed flow no longer satisfies its success consequence — refusing to write (a heal that loses the intent would ship a green-but-dead test). Fix by hand and verify',
 };
 /**
- * Why heal produced no proposal: a floor it consulted, or a kind of drift it cannot rebind.
+ * Why heal produced no proposal. Three cases.
  *
- * Exported for its own test — the distinction is a sentence a reader ACTS on, and the wrong one
- * sends them to lower a threshold that had no part in the refusal.
+ * A testid anchor drifted, but no candidate cleared the confidence floor: UNHEALABLE.
+ * Every drift is a consequence (the anchors resolved, the assertion failed): NOT_A_REBIND.
+ * Any other drift means an anchor did not resolve, so the step did not run: ANCHOR_UNRESOLVED.
+ * That message names the nearest candidate when there is one.
+ *
+ * Exported for its own test. A reader acts on this sentence, and the wrong one sends them to
+ * lower a threshold that had no part in the refusal.
  */
-export function unhealableMessage(reasons) {
-    const rebindable = reasons.some((reason) => DriftReason.TESTID_NOT_FOUND === reason);
-    return rebindable ? HEAL_MESSAGES.UNHEALABLE : HEAL_MESSAGES.NOT_A_REBIND;
+export function unhealableMessage(reasons, nearest = null) {
+    if (reasons.some((reason) => DriftReason.TESTID_NOT_FOUND === reason)) {
+        return HEAL_MESSAGES.UNHEALABLE;
+    }
+    if (reasons.every((reason) => isConsequenceDrift(reason))) {
+        return HEAL_MESSAGES.NOT_A_REBIND;
+    }
+    return null === nearest
+        ? HEAL_MESSAGES.ANCHOR_UNRESOLVED
+        : `${HEAL_MESSAGES.ANCHOR_UNRESOLVED}. ${HEAL_MESSAGES.ANCHOR_NEAREST_PREFIX} "${nearest}".`;
 }
 function toChange(proposal) {
     return { step: proposal.step, from: proposal.from, to: proposal.to };
 }
 export async function healFlow(deps, args) {
-    const name = asString(args['flowName']) ?? '';
+    // `flow` is the alias the tool's schema offers; ignoring it healed a flow named "".
+    const name = asString(args['flowName']) ?? asString(args['flow']) ?? '';
     const apply = true === args['apply'];
     const target = sessionTarget(deps, asString(args['sessionId']));
     const { projectId } = target;
@@ -91,13 +106,15 @@ export async function healFlow(deps, args) {
     }
     const proposals = collectProposals(steps);
     if (0 === proposals.length) {
+        const drifts = steps.flatMap((step) => (step.drift === undefined ? [] : [step.drift]));
         return {
             name,
             status: HealStatus.UNHEALABLE,
             applied: false,
             proposals: [],
             changed: [],
-            message: unhealableMessage(steps.flatMap((step) => (step.drift === undefined ? [] : [step.drift.reasonKind]))),
+            message: unhealableMessage(drifts.map((drift) => drift.reasonKind), drifts.find((drift) => !isConsequenceDrift(drift.reasonKind) && null !== drift.nearest)
+                ?.nearest ?? null),
         };
     }
     if (!apply) {

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

@@ -8,13 +8,7 @@ import { z } from 'zod';
 declare const FlakeRecordSchema: z.ZodObject<{
     runs: z.ZodNumber;
     fails: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    runs: number;
-    fails: number;
-}, {
-    runs: number;
-    fails: number;
-}>;
+}, z.core.$strip>;
 type FlakeRecord = z.infer<typeof FlakeRecordSchema>;
 /** Per-flow map (flow name → record). */
 export type FlakeLedger = Record<string, FlakeRecord>;
@@ -23,26 +17,8 @@ export declare const FlakeFileSchema: z.ZodObject<{
     flows: z.ZodRecord<z.ZodString, z.ZodObject<{
         runs: z.ZodNumber;
         fails: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        runs: number;
-        fails: number;
-    }, {
-        runs: number;
-        fails: number;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    flows: Record<string, {
-        runs: number;
-        fails: number;
-    }>;
-    version: 1;
-}, {
-    flows: Record<string, {
-        runs: number;
-        fails: number;
-    }>;
-    version: 1;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare function emptyRecord(): FlakeRecord;
 /** Accrue one unchanged-code replay outcome. */
 export declare function recordOutcome(record: FlakeRecord, passed: boolean): FlakeRecord;

package/dist/language/flows/recording/flake.js

@@ -11,7 +11,7 @@ const FlakeRecordSchema = z.object({
 });
 export const FlakeFileSchema = z.object({
     version: z.literal(1),
-    flows: z.record(FlakeRecordSchema),
+    flows: z.record(z.string(), FlakeRecordSchema),
 });
 /** Minimum unchanged-code replays before flakiness can be judged (too few = noise). */
 const DEFAULT_MIN_FLAKE_RUNS = 5;

package/dist/language/flows/recording/recording-backtrack.js

@@ -6,11 +6,8 @@
  * exists on search. That shape is visible from the route list with no change to the flow file, so
  * stop/save can warn instead of writing a flow that fails on the next click.
  */
-import { EventType } from '@reticlehq/core';
+import { EventType, asString } from '@reticlehq/core';
 import { routePathOf } from '@reticlehq/engine/question/predicate/predicate-route.js';
-function asString(value) {
-    return 'string' === typeof value ? value : undefined;
-}
 /**
  * The page a recording step sat on, comparable across path routers and hash routers.
  *

package/dist/language/flows/recording/tape/recordings.d.ts

@@ -47,6 +47,8 @@ export interface RecordedStep {
      * never saved silently.
      */
     unkeptExpect?: string;
+    /** The step sent a write request (POST, PUT, PATCH, DELETE) while it was recorded. */
+    writes?: true;
 }
 interface ActiveRecording {
     cursor: number;
@@ -92,6 +94,9 @@ export interface CompiledProgram {
     routes?: string[];
     /** Who made it — see FlowFile.author. Stamped by the caller that knows. */
     author?: FlowFile['author'];
+    /** A sentence built from the steps' expects (an auto-saved drive): see FlowFile.intentDerived. */
+    intent?: string;
+    intentDerived?: true;
 }
 /**
  * The `tool` written on an invocation step — core's constant, re-exported for this module's callers.
@@ -153,7 +158,12 @@ export declare class RecordingStore {
      * they are, so the journey it belongs to is not auto-saved as a flow (#1459).
      */
     markMocked(session: string | undefined, active: boolean): void;
-    capture(step: RecordedStep, route?: string, session?: string): void;
+    /**
+     * `forAmbient` is the step as the ambient tape keeps it, when that differs: a journey's refuted
+     * claims come off the ambient tape (see `unassertLast`), and a recording somebody opened keeps
+     * every claim they declared, held or not.
+     */
+    capture(step: RecordedStep, route?: string, session?: string, forAmbient?: RecordedStep): void;
     /**
      * Add a consequence to the last captured step of every active recording.
      *

package/dist/language/flows/recording/tape/recordings.js

@@ -101,7 +101,12 @@ export class RecordingStore {
         else
             this.#mocked.delete(session ?? '');
     }
-    capture(step, route, session) {
+    /**
+     * `forAmbient` is the step as the ambient tape keeps it, when that differs: a journey's refuted
+     * claims come off the ambient tape (see `unassertLast`), and a recording somebody opened keeps
+     * every claim they declared, held or not.
+     */
+    capture(step, route, session, forAmbient) {
         this.#navigatedSinceStep = false;
         const mocked = this.#mocked.has(session ?? '');
         const ambient = ambientRecordingOf(session);
@@ -138,13 +143,14 @@ export class RecordingStore {
             // The route rides on the AMBIENT tape only: a recording somebody opened deliberately is
             // already one journey by construction, and stamping a route on its steps would change what a
             // deliberate recording contains.
+            const taped = isAmbient(name) ? (forAmbient ?? step) : step;
             rec.steps.push(isAmbient(name) && (route !== undefined || mocked)
                 ? {
-                    ...step,
+                    ...taped,
                     ...(route === undefined ? {} : { route }),
                     ...(mocked ? { mocked: true } : {}),
                 }
-                : step);
+                : taped);
         }
     }
     /**

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

@@ -1,4 +1,4 @@
-import { type Predicate } from '@reticlehq/core';
+import { pathOf, type Predicate, type ReticleEvent } from '@reticlehq/core';
 import { type CommandResult } from '@reticlehq/core';
 import type { RecordedStep, CompiledProgram } from './recording/tape/recordings.js';
 import type { Session } from '../../portal/session/session.js';
@@ -34,7 +34,16 @@ export declare function replayActionArgs(value: unknown, confirmDangerous?: bool
  * Pathname rather than the whole url, because that is what `startPath` is compared against and what
  * a hash-routed app makes meaningless in the document location — see routeOfEvent.
  */
-export declare function pathOf(url: string | undefined): string | undefined;
+export { pathOf };
+/**
+ * Did the app send a write request in this window? A step that did is saved `writes: true`, so a
+ * replay does not repeat it unasked. The dev server's own traffic is not the app's.
+ */
+export declare function wroteIn(events: readonly ReticleEvent[]): boolean;
+/** `wroteIn` over a session's window, best-effort: the record must never fail the drive it records. */
+export declare function wroteSince(session: {
+    eventsSince(since: number): readonly ReticleEvent[];
+}, since: number): boolean;
 /** What a saved flow could not keep, and the fix. See RecordedStep.unkeptExpect. */
 export declare const UNKEPT_EXPECT: string;
 /**
@@ -51,14 +60,18 @@ export declare function captureAct(recordings: {
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
 route?: string, 
 /** The session that acted: only recordings it started take the step. */
-session?: string): void;
+session?: string, 
+/** The act's window sent a write request; see `wroteIn`. */
+wrote?: boolean): void;
 /**
  * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
  * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
  * a regression test asserting something never once observed to hold because of the action. The
  * action itself is always recorded: it happened, and replay needs it to reach the next step.
  */
-export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined, session?: string): void;
+export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined, session?: string, 
+/** The act's window sent a write request; see `wroteIn`. */
+wrote?: boolean): void;
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
 export declare function captureAssertion(recordings: {
     attachExpect: (expect: Predicate, session?: string) => void;
@@ -76,6 +89,14 @@ export declare function compileActStep(args: Record<string, unknown>, res: unkno
  * every sequence unreplayable on an app without testids.
  */
 export declare function compileSequenceStep(args: Record<string, unknown>, res: unknown): RecordedStep;
+/**
+ * A compiled step that presses a document key at no element (#1559).
+ *
+ * Both halves are required. The anchor alone is not enough, because a hand-edited `role: document`
+ * on a click would then dispatch that click at nothing; and the press alone is not enough, because a
+ * recorded Escape aimed at a named element keeps that element.
+ */
+export declare function isDocumentPress(step: Record<string, unknown>): boolean;
 interface ReplayStepResult {
     tool: string;
     ok: boolean;
@@ -103,4 +124,3 @@ via?: readonly {
     flow: string;
     step: number;
 }[]): Promise<ReplayStepResult[]>;
-export {};