e2e 0.16.0 → 0.18.0

package/dist/cache/relocate.js

@@ -21,7 +21,7 @@ import { containerKey, describeTarget, parentsOf } from '../agent/actions.js';
  * change, because an entry recorded under different rules could relocate to a
  * different node.
  */
-export const REPLAY_POLICY_VERSION = 'conservative/5';
+export const REPLAY_POLICY_VERSION = 'conservative/6';
 /**
  * The share of the viewport a scrolled node must have covered when it was
  * addressed (`ScrollAction.spans`) to scroll as the viewport does once it
@@ -33,18 +33,13 @@ export const MAIN_LIST_SHARE = 0.5;
 const IDENTITY_FIELDS = ['role', 'name', 'testId', 'placeholder', 'inputPurpose'];
 /** Text is identity too when neither a test id nor a name was recorded. */
 const IDENTITY_FIELDS_WITH_TEXT = [...IDENTITY_FIELDS, 'text'];
-/**
- * Whether a descriptor can identify a node at all. Role or selector alone
- * cannot: a wrong match acts on the wrong control, so such a descriptor is
- * not relocatable and, as an anchor, would prove nothing.
- */
 /**
  * A descriptor with nothing to identify the control by: no test id, name,
- * text, or placeholder, only a role. A form built without labels is made of
- * these. Such a descriptor relocates by its place among the unnamed
- * controls of its kind, so it is relocatable only once a position was
- * recorded for it, and it is matched strictly (`fieldsIdentical`): an
- * unnamed textbox must never stand in for a named one.
+ * text, or placeholder, only a role. An icon button and a form built
+ * without labels are made of these. Such a descriptor relocates by its place
+ * among the unnamed controls of its kind, and it is matched strictly
+ * (`fieldsIdentical`): an unnamed textbox must never stand in for a named
+ * one.
  */
 function isAnonymous(descriptor) {
     return (descriptor.testId === undefined &&
@@ -52,8 +47,21 @@ function isAnonymous(descriptor) {
         descriptor.text === undefined &&
         descriptor.placeholder === undefined);
 }
+/**
+ * Whether a descriptor can identify a node at all. Role or selector alone
+ * cannot: a wrong match acts on the wrong control, so such a descriptor is
+ * not relocatable and, as an anchor, would prove nothing. An anonymous one
+ * is relocatable by its recorded place only when that place means something
+ * on the next screen: it was the one unnamed control of its role, or it sits
+ * in a named container (`within`) that tells it from its twins. A place
+ * counted among twins with no container is an order, and rows that reorder
+ * would hand the action to the wrong one, so such a target hands off.
+ */
 export function isRelocatableDescriptor(descriptor) {
-    return isAnonymous(descriptor) ? descriptor.role !== undefined && descriptor.position !== undefined : true;
+    if (!isAnonymous(descriptor))
+        return true;
+    const { position } = descriptor;
+    return descriptor.role !== undefined && position !== undefined && (position.of === 1 || descriptor.within !== undefined);
 }
 /** The semantic tier of a descriptor: every identity field but the test id. */
 function withoutTestId(descriptor) {
@@ -102,17 +110,17 @@ function fieldsIdentical(recorded, candidate, fields) {
  */
 const projections = new WeakMap();
 /** Projects every node of an observation the way the recorder described its targets. */
-export function describeNodes(nodes, options) {
+function describeNodes(nodes) {
     const cached = projections.get(nodes);
-    if (cached !== undefined && cached.redact === options.redact)
-        return cached.described;
+    if (cached !== undefined)
+        return cached;
     const described = [];
     for (const [id, node] of nodes) {
-        const descriptor = describeTarget(node, options.redact);
+        const descriptor = describeTarget(node);
         if (descriptor !== undefined)
             described.push({ id, descriptor });
     }
-    projections.set(nodes, { redact: options.redact, described });
+    projections.set(nodes, described);
     return described;
 }
 /**
@@ -124,8 +132,8 @@ export function describeNodes(nodes, options) {
  * same twins and noted which one it acted on, so the same count of twins
  * resolves to the same one; any other count diverges as before.
  */
-export function relocateDescriptor(descriptor, nodes, options) {
-    const matches = matchingIds(descriptor, nodes, options);
+export function relocateDescriptor(descriptor, nodes) {
+    const matches = matchingIds(descriptor, nodes);
     if (matches.length === 0)
         return { kind: 'failed', failure: 'target-not-found' };
     const { position } = descriptor;
@@ -146,8 +154,8 @@ export function relocateDescriptor(descriptor, nodes, options) {
  * matches. The recorder uses the same projection to notice, before it writes a
  * target, that the description alone would not tell the target from its twins.
  */
-function matchingIds(descriptor, nodes, options) {
-    const candidates = describeNodes(nodes, options);
+function matchingIds(descriptor, nodes) {
+    const candidates = describeNodes(nodes);
     // A recorded container key must hold: the same "Delete" in another row is
     // a different control. Checked against the tree the candidates came from,
     // never guessed.
@@ -155,7 +163,7 @@ function matchingIds(descriptor, nodes, options) {
         ? candidates
         : (() => {
             const parents = parentsOf(nodes);
-            return candidates.filter((candidate) => containerKey(candidate.id, nodes, parents, options.redact) === descriptor.within);
+            return candidates.filter((candidate) => containerKey(candidate.id, nodes, parents) === descriptor.within);
         })();
     for (const tier of descriptorTiers(descriptor)) {
         const matches = tierMatches(tier, keyed);
@@ -183,8 +191,8 @@ const MAX_POSITIONED_TWINS = 1000;
  * alone. Recorded with the target so a replay can tell one "Set up" button per
  * card apart without an app change; a distinct label makes it unnecessary.
  */
-export function describePosition(node, within, nodes, options) {
-    const described = describeTarget(node, options.redact);
+export function describePosition(node, within, nodes) {
+    const described = describeTarget(node);
     if (described === undefined || (described.role === undefined && isAnonymous(described)))
         return undefined;
     // An anonymous target has no identity to match alone; its position is what
@@ -192,7 +200,7 @@ export function describePosition(node, within, nodes, options) {
     // it is the only one, and described with a placeholder position to do so.
     const anonymous = isAnonymous(described);
     const probe = { ...described, ...(within === undefined ? {} : { within }), ...(anonymous ? { position: { index: 0, of: 1 } } : {}) };
-    const ids = matchingIds(probe, nodes, options);
+    const ids = matchingIds(probe, nodes);
     if (ids.length < (anonymous ? 1 : 2) || ids.length > MAX_POSITIONED_TWINS)
         return undefined;
     const index = ids.indexOf(node.ref.id);

package/dist/cache/route.d.ts

@@ -4,43 +4,42 @@
  * The replay precondition asks "is the app on the screen this recording
  * began on", and the postcondition "did we land where the recording landed".
  * A URL answers neither directly: it carries the id the app minted for this
- * run's record, the slug of the record the test happened to open, a search
- * term in the query, a tracking parameter, a fragment. All of that changes
- * between two visits to the same screen, and none of it is the screen.
+ * run's record, a cache buster, a session token, a fragment. All of that
+ * changes between two visits to the same screen, and none of it is the
+ * screen.
  *
- * So a location is reduced to its route: the pathname's segments, with every
- * segment that looks minted per record (a uuid, a hex or digit run, a long
- * token mixing letters and digits, text with whitespace) replaced by `:id`;
- * the query and the fragment dropped, except that an app routing in the
- * fragment (`#/companies/1`) routes by that path. A value the call marked
- * with `unique()` needs no rule here: the recording spells it as a
+ * So a location is reduced to its route: the origin it is on, the pathname's
+ * segments, and the query's parameters, with every segment or parameter
+ * value that looks minted per record (a uuid, a hex or digit run, a long
+ * token mixing letters and digits, a prefixed record id, text with
+ * whitespace) replaced by `:id`.
+ * Every other query value is part of the screen: `?mode=unsafe` is not
+ * `?mode=safe`, and `?tab=notes` shows other controls than no tab. The
+ * fragment is dropped, except that an app routing in the fragment
+ * (`#/companies/1`) routes by that path and its query. A value the call
+ * marked with `unique()` needs no rule here: the recording spells it as a
  * placeholder in every spelling a URL gives it, its slug included
  * (`cache/template.ts`), and replay fills in this run's value on both sides.
  *
- * Two routes that still differ in exactly one segment are `undecided`: a slug
- * of a record the runner never saw the value of reads as two literals, and
- * only the screen can say whether they are the same page. At the end of a
- * step the recorded anchors can, because they are the step's own effect. At
- * the start nothing recorded is specific to the screen (the controls a start
- * screen shows are mostly the app's header and sidebar, shared by every
- * screen), so an undecided start is a miss. A device engine reports a screen
- * title in place of a URL, which is already a route and compares as itself.
+ * The origin is relative to the app (`appLocation`): a location on the app's
+ * own origin is kept as its path, so a recording made against one deployment
+ * of the app replays on another that shares its `app.identity`, while a
+ * screen on any other origin keeps its origin and is another route.
+ *
+ * Two routes are the same screen only when they read alike. A literal that
+ * differs, a slug the runner never saw the value of, is another screen at
+ * both ends of a step: nothing recorded can tell a record's slug from a
+ * route word, and a screen that looks alike on another route (a settings
+ * page and a profile page sharing one layout) is exactly where a wrong link
+ * lands. A device engine reports a screen title in place of a URL, which is
+ * already a route and compares as itself.
  */
-export type Route = {
-    readonly kind: 'url';
-    readonly segments: readonly string[];
-} | {
-    readonly kind: 'opaque';
-    readonly location: string;
-};
-export type RouteVerdict = 'same' | 'different' | 'undecided';
-/** The route of a location. */
-export declare function routeOf(location: string): Route;
-/** A route as one line, for tests and diagnostics: `/companies/:id`, or the opaque location. */
-export declare function routeKey(route: Route): string;
 /**
- * Whether two routes are the same screen: `same` when they read alike,
- * `undecided` when routes of one depth differ in exactly one segment, which
- * the screen must settle, and `different` otherwise.
+ * A location as the cache compares it: a URL on the app's own origin as its
+ * path, query, and fragment, so a recording follows the app to another
+ * deployment of it; anything else (another origin, a device screen title)
+ * as it is.
  */
-export declare function compareRoutes(recorded: Route, live: Route): RouteVerdict;
+export declare function appLocation(location: string, appOrigin: string | undefined): string;
+/** Whether two locations name the same screen: one origin, and segments and query that read alike. */
+export declare function sameRoute(recorded: string, live: string): boolean;

package/dist/cache/route.js

@@ -4,43 +4,66 @@
  * The replay precondition asks "is the app on the screen this recording
  * began on", and the postcondition "did we land where the recording landed".
  * A URL answers neither directly: it carries the id the app minted for this
- * run's record, the slug of the record the test happened to open, a search
- * term in the query, a tracking parameter, a fragment. All of that changes
- * between two visits to the same screen, and none of it is the screen.
+ * run's record, a cache buster, a session token, a fragment. All of that
+ * changes between two visits to the same screen, and none of it is the
+ * screen.
  *
- * So a location is reduced to its route: the pathname's segments, with every
- * segment that looks minted per record (a uuid, a hex or digit run, a long
- * token mixing letters and digits, text with whitespace) replaced by `:id`;
- * the query and the fragment dropped, except that an app routing in the
- * fragment (`#/companies/1`) routes by that path. A value the call marked
- * with `unique()` needs no rule here: the recording spells it as a
+ * So a location is reduced to its route: the origin it is on, the pathname's
+ * segments, and the query's parameters, with every segment or parameter
+ * value that looks minted per record (a uuid, a hex or digit run, a long
+ * token mixing letters and digits, a prefixed record id, text with
+ * whitespace) replaced by `:id`.
+ * Every other query value is part of the screen: `?mode=unsafe` is not
+ * `?mode=safe`, and `?tab=notes` shows other controls than no tab. The
+ * fragment is dropped, except that an app routing in the fragment
+ * (`#/companies/1`) routes by that path and its query. A value the call
+ * marked with `unique()` needs no rule here: the recording spells it as a
  * placeholder in every spelling a URL gives it, its slug included
  * (`cache/template.ts`), and replay fills in this run's value on both sides.
  *
- * Two routes that still differ in exactly one segment are `undecided`: a slug
- * of a record the runner never saw the value of reads as two literals, and
- * only the screen can say whether they are the same page. At the end of a
- * step the recorded anchors can, because they are the step's own effect. At
- * the start nothing recorded is specific to the screen (the controls a start
- * screen shows are mostly the app's header and sidebar, shared by every
- * screen), so an undecided start is a miss. A device engine reports a screen
- * title in place of a URL, which is already a route and compares as itself.
+ * The origin is relative to the app (`appLocation`): a location on the app's
+ * own origin is kept as its path, so a recording made against one deployment
+ * of the app replays on another that shares its `app.identity`, while a
+ * screen on any other origin keeps its origin and is another route.
+ *
+ * Two routes are the same screen only when they read alike. A literal that
+ * differs, a slug the runner never saw the value of, is another screen at
+ * both ends of a step: nothing recorded can tell a record's slug from a
+ * route word, and a screen that looks alike on another route (a settings
+ * page and a profile page sharing one layout) is exactly where a wrong link
+ * lands. A device engine reports a screen title in place of a URL, which is
+ * already a route and compares as itself.
  */
 const PARAM = ':id';
 /**
  * A segment shaped like a value the app mints per record: a uuid, a hex or
  * digit run, a long token carrying letters and at least two digits (a route
- * word such as `companies-v2` has one), or text with whitespace, which no
- * router puts in a path. A capitalized or dashed word is none of these; two
- * of them differing is left to the screen.
+ * word such as `companies-v2` has one), a prefixed record id (letters, a
+ * dash, then a digit tail of two or more: `PROJ-016`, `INV-2041`; a single
+ * digit as in `page-2` is a route word), or text with whitespace, which no
+ * router puts in a path. Any other capitalized or dashed word is none of
+ * these.
  */
 const MINTED_SEGMENT = [
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
     /^[0-9a-f]{8,}$/i,
     /^\d+$/,
     /^(?=(?:[^\d]*\d){2})(?=.*[A-Za-z])[A-Za-z0-9_-]{12,}$/,
+    /^[A-Za-z]+-\d{2,}$/,
     /\s/,
 ];
+/**
+ * A query value is minted on the same rules, with the wider alphabet a
+ * value carries that a path segment cannot: a signed token or a timestamp
+ * (`eyJhbGciOi.x1.y2`, `2026-10-01T10:00:00Z`) has dots, colons, and base64,
+ * and a date (`?from=2026-10-01`, a default an app fills in with today) has
+ * no letter at all.
+ */
+const MINTED_VALUE = [
+    ...MINTED_SEGMENT,
+    /^(?=(?:[^\d]*\d){2})(?=.*[A-Za-z])[\w.~+/=:-]{12,}$/,
+    /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/,
+];
 function decodeSegment(raw) {
     try {
         return decodeURIComponent(raw);
@@ -50,15 +73,30 @@ function decodeSegment(raw) {
     }
 }
 /**
- * The pathname a location routes by, or undefined when the location is not
- * a web address (a device engine's screen title, a browser's own page).
+ * A location as the cache compares it: a URL on the app's own origin as its
+ * path, query, and fragment, so a recording follows the app to another
+ * deployment of it; anything else (another origin, a device screen title)
+ * as it is.
+ */
+export function appLocation(location, appOrigin) {
+    if (appOrigin === undefined || !URL.canParse(location))
+        return location;
+    const url = new URL(location);
+    return url.origin === appOrigin ? `${url.pathname}${url.search}${url.hash}` : location;
+}
+/**
+ * The parts of a location its route is made of, or undefined when the
+ * location is not a web address (a device engine's screen title, a
+ * browser's own page).
  */
-function pathnameOf(location) {
+function locationParts(location) {
+    let origin;
     let rest = location;
     if (URL.canParse(location)) {
         const url = new URL(location);
         if (url.protocol !== 'http:' && url.protocol !== 'https:')
             return undefined;
+        origin = url.origin;
         rest = `${url.pathname}${url.search}${url.hash}`;
     }
     else if (!location.startsWith('/')) {
@@ -66,42 +104,48 @@ function pathnameOf(location) {
     }
     const hashAt = rest.indexOf('#');
     const fragment = hashAt === -1 ? '' : rest.slice(hashAt + 1);
-    const pathname = fragment.startsWith('/') ? fragment : hashAt === -1 ? rest : rest.slice(0, hashAt);
-    return pathname.split('?')[0] ?? '';
+    const [documentPath, documentSearch] = splitOnce(hashAt === -1 ? rest : rest.slice(0, hashAt), '?');
+    if (!fragment.startsWith('/'))
+        return { ...(origin === undefined ? {} : { origin }), pathname: documentPath, search: documentSearch };
+    const [fragmentPath, fragmentSearch] = splitOnce(fragment, '?');
+    return {
+        ...(origin === undefined ? {} : { origin }),
+        pathname: fragmentPath,
+        search: [documentSearch, fragmentSearch].filter((part) => part !== '').join('&'),
+    };
+}
+function splitOnce(text, separator) {
+    const at = text.indexOf(separator);
+    return at === -1 ? [text, ''] : [text.slice(0, at), text.slice(at + 1)];
+}
+/** A query's parameters as route terms, `key=value` with a minted key or value as `:id`, sorted. */
+function queryTerms(search) {
+    const terms = [];
+    for (const [key, value] of new URLSearchParams(search)) {
+        const minted = (text) => text !== '' && MINTED_VALUE.some((pattern) => pattern.test(text));
+        terms.push(`${minted(key) ? PARAM : key}=${minted(value) ? PARAM : value}`);
+    }
+    return terms.toSorted();
 }
 /** The route of a location. */
-export function routeOf(location) {
-    const pathname = pathnameOf(location);
-    if (pathname === undefined)
+function routeOf(location) {
+    const parts = locationParts(location);
+    if (parts === undefined)
         return { kind: 'opaque', location };
-    const segments = pathname
+    const segments = parts.pathname
         .split('/')
         .filter((raw) => raw !== '')
         .map((raw) => {
         const text = decodeSegment(raw);
         return MINTED_SEGMENT.some((pattern) => pattern.test(text)) ? PARAM : text;
     });
-    return { kind: 'url', segments };
+    return { kind: 'url', ...(parts.origin === undefined ? {} : { origin: parts.origin }), segments, query: queryTerms(parts.search) };
 }
-/** A route as one line, for tests and diagnostics: `/companies/:id`, or the opaque location. */
-export function routeKey(route) {
-    return route.kind === 'url' ? `/${route.segments.join('/')}` : route.location;
+/** Whether two locations name the same screen: one origin, and segments and query that read alike. */
+export function sameRoute(recorded, live) {
+    return routeIdentity(routeOf(recorded)) === routeIdentity(routeOf(live));
 }
-/**
- * Whether two routes are the same screen: `same` when they read alike,
- * `undecided` when routes of one depth differ in exactly one segment, which
- * the screen must settle, and `different` otherwise.
- */
-export function compareRoutes(recorded, live) {
-    if (recorded.kind === 'opaque' || live.kind === 'opaque') {
-        return recorded.kind === 'opaque' && live.kind === 'opaque' && recorded.location === live.location ? 'same' : 'different';
-    }
-    if (recorded.segments.length !== live.segments.length)
-        return 'different';
-    let differing = 0;
-    for (const [index, segment] of recorded.segments.entries()) {
-        if (segment !== live.segments[index])
-            differing += 1;
-    }
-    return differing === 0 ? 'same' : differing === 1 ? 'undecided' : 'different';
+/** A route's parts as one comparable string, a slash inside a segment kept inside it. */
+function routeIdentity(route) {
+    return JSON.stringify(route.kind === 'opaque' ? [route.location] : [route.origin ?? null, route.segments, route.query]);
 }

package/dist/cache/store.d.ts

@@ -59,6 +59,12 @@ export declare class FileCacheStore implements CacheStore {
         bytes: number;
     } | undefined>;
     delete(keyHash: string): Promise<void>;
+    /**
+     * The key hashes of the digest-named files in the directory, readable or
+     * not; none when the directory does not exist. Not part of `CacheStore`:
+     * only `cache.strict` lists a store, and only this one.
+     */
+    keyHashes(): Promise<string[]>;
     /**
      * Resolves one entry path. The key hash is the only caller-supplied path
      * component and must be a bare digest, so traversal is impossible by

package/dist/cache/store.js

@@ -13,7 +13,7 @@
  * The interface exists so a remote store — the cloud's shared cache — can
  * replace the filesystem without the harness noticing.
  */
-import { mkdir, readFile, stat, unlink } from 'node:fs/promises';
+import { mkdir, readdir, readFile, stat, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { writeFileAtomic } from '../internal/atomic-write.js';
 import { errorMessage } from '../internal/errors.js';
@@ -83,6 +83,26 @@ export class FileCacheStore {
             return;
         await unlink(path).catch(() => undefined);
     }
+    /**
+     * The key hashes of the digest-named files in the directory, readable or
+     * not; none when the directory does not exist. Not part of `CacheStore`:
+     * only `cache.strict` lists a store, and only this one.
+     */
+    async keyHashes() {
+        let names;
+        try {
+            names = await readdir(this.directory);
+        }
+        catch (cause) {
+            if (cause.code === 'ENOENT')
+                return [];
+            throw cause;
+        }
+        return names.flatMap((name) => {
+            const keyHash = name.endsWith('.json') ? name.slice(0, -'.json'.length) : undefined;
+            return keyHash !== undefined && KEY_HASH.test(keyHash) ? [keyHash] : [];
+        });
+    }
     /**
      * Resolves one entry path. The key hash is the only caller-supplied path
      * component and must be a bare digest, so traversal is impossible by

package/dist/cache/trace.d.ts

@@ -32,26 +32,36 @@ export declare const MAX_TRACE_INPUT_CHARS = 4096;
 /** Caps prose at `maxChars`, marking the cut with an ellipsis. */
 export declare function bound(text: string, maxChars: number): string;
 /**
- * Cap on recorded end anchors. Anchors are the step's own delta — what
- * appeared on screen between the first observation and the passing one — so
- * a same-screen mutation rarely has more than a handful; a step that changes
- * the whole screen keeps the first few in document order.
+ * Cap on recorded anchors, per side of the delta. Anchors are the step's own
+ * delta, what appeared on screen between the first observation and the
+ * passing one and what vanished, so a same-screen mutation rarely has more
+ * than a handful; a step that changes the whole screen keeps the first few,
+ * announcements first (`cache/anchors.ts`).
  */
 export declare const MAX_TRACE_ANCHORS = 8;
 /** Longest a replay waits for the recorded end state to return. */
 export declare const MAX_TRACE_END_WAIT_MS = 120000;
 /**
  * What a trace was recorded for, in the terms a person uses: the test, the
- * target, and the digest of the instruction. None of it is replay input —
- * every one of these fields is already in the key, so a mismatch is a miss
- * before an entry is ever read — and none of it is trusted as such. It exists
- * so a file named after a digest can say which test it belongs to.
+ * target, the digest of the instruction, and, on entries recorded since they
+ * were added, the rest of what names the step within its test. None of it is
+ * replay input — every one of these fields is already in the key, so a
+ * mismatch is a miss before an entry is ever read — and none of it is trusted
+ * as such. It exists so a file named after a digest can say which step it
+ * belongs to, and so `cache.strict` can tell a step whose key changed under
+ * its recording from a step that was never recorded.
  */
 export interface TraceProvenance {
     readonly testId: string;
     readonly targetId: string;
     /** SHA-256 of the normalized instruction (`cache/identity.ts`). */
     readonly instructionDigest: string;
+    /** SHA-256/JCS of the step's params as the key digests them, a placeholder for each `unique()` value. */
+    readonly paramsDigest?: string;
+    /** Zero-based occurrence of the step among its repeats in the attempt. */
+    readonly callIndex?: number;
+    /** Name of the configured agent the step ran with. */
+    readonly agent?: string;
 }
 /**
  * How a recorded action addressed its node, independent of observation ids.
@@ -82,7 +92,23 @@ export interface TraceTargetDescriptor {
      * twin that appeared or vanished still diverges instead of guessing.
      */
     readonly position?: TracePosition;
+    /**
+     * An anchor's states that were on, sorted; anchors only. A switch turned
+     * on is the same control before and after, so its state is what tells
+     * the step's effect from a tap that did nothing.
+     */
+    readonly states?: readonly TraceAnchorState[];
+    /**
+     * An anchor's current input value, redacted and bounded like its text;
+     * anchors only, and never a secure field's, which is never observed. A
+     * field typed into or an option selected is the same control before and
+     * after, so its value is the step's effect.
+     */
+    readonly value?: string;
 }
+/** The node states an anchor records: the ones a step sets on a control it leaves on screen. */
+export declare const TRACE_ANCHOR_STATES: readonly ['checked', 'expanded', 'pressed', 'selected'];
+export type TraceAnchorState = (typeof TRACE_ANCHOR_STATES)[number];
 interface ActionBase {
     /** One-line prose summary — the only view a mid-step hand-off notice shows. */
     readonly summary: string;
@@ -245,7 +271,7 @@ export interface ToolGapAction extends ActionBase {
 export type RecordedAction = NodeAction | TypeAction | TypeSecretAction | PressAction | SelectAction | CheckAction | UploadAction | DragAction | ScrollAction | ScrollUntilAction | NavigateAction | BackAction | PointAction | TypeTextAction | PressKeyAction | DismissKeyboardAction | ToolGapAction;
 export interface ActionTrace {
     readonly actions: readonly RecordedAction[];
-    /** Executor that produced the trace — provenance, never part of the key (OQ10). */
+    /** Executor that produced the trace: provenance, never part of the key, which names the agent instead. */
     readonly executor: {
         readonly name: string;
         readonly version?: string;
@@ -254,12 +280,17 @@ export interface ActionTrace {
     readonly recordedFor?: TraceProvenance;
     /** The recorded run's verdict summary. */
     readonly summary: string;
-    /** Location path when the step began; a precondition unless the trace opens with navigate. */
+    /**
+     * Location when the step began, as the cache compares it (`appLocation`):
+     * a path on the app's own origin, else the whole location. A precondition
+     * unless the trace opens with navigate.
+     */
     readonly startPath?: string;
     /**
-     * Location path when the step passed — the trace's deterministic postcondition.
-     * A full replay self-finalizes only while the live pathname still matches;
-     * a recorded flow whose destination changed hands off instead of passing.
+     * Location when the step passed, spelled like `startPath`: the trace's
+     * deterministic postcondition. A full replay self-finalizes only while
+     * the live route still matches; a recorded flow whose destination changed
+     * hands off instead of passing.
      */
     readonly endPath?: string;
     /**
@@ -271,6 +302,14 @@ export interface ActionTrace {
      * instead of passing on mechanics alone.
      */
     readonly endAnchors?: readonly TraceTargetDescriptor[];
+    /**
+     * Descriptors of nodes that were on screen when the step began and were
+     * gone when it passed: a delete, a dismissed dialog, a cleared draft. A
+     * full replay self-finalizes only while every one of them is gone again,
+     * so a removal that did not happen hands off instead of passing with no
+     * anchor to check.
+     */
+    readonly goneAnchors?: readonly TraceTargetDescriptor[];
     /**
      * How long the recorded run took from its first action to its passing
      * verdict, plus a margin. A replay waits up to this long for the anchors to
@@ -295,7 +334,7 @@ export declare function buildTraceEntry(payload: ActionTrace): TraceEntry;
  */
 export declare function readTraceEntry(document: unknown): TraceEntry | undefined;
 /** Every field of a target descriptor; two descriptors equal on all of them name the same target. */
-export declare const DESCRIPTOR_FIELDS: readonly ['role', 'name', 'text', 'testId', 'placeholder', 'selector', 'inputPurpose', 'within'];
+export declare const DESCRIPTOR_FIELDS: readonly ['role', 'name', 'text', 'testId', 'placeholder', 'selector', 'inputPurpose', 'within', 'value'];
 /** A string rewrite; `undefined` means the text cannot be rewritten and the whole trace is unusable. */
 export type TraceTextMap = (text: string) => string | undefined;
 /**