@e2edev/e2e 0.2.0

package/dist/backend/session.js

@@ -0,0 +1,213 @@
+/**
+ * The backend-to-session adapter (RFC0002). One adapter per attempt satisfies
+ * the internal `TargetSession` surface over the backend contract, so the agent
+ * tier, the judgment tier, the trace cache, and the fixture graph program
+ * against one shape. It is the single seam every backend call crosses, which
+ * makes it the one place two rules are enforced: a capability the backend does
+ * not declare fails loud with `UNSUPPORTED_CAPABILITY` at the moment of use,
+ * and anything a backend throws that is not a `BackendError` is normalized to
+ * a non-retryable `BACKEND_FAILURE`, so a crashed backend is an infrastructure
+ * failure everywhere and never a retry-eligible test failure.
+ */
+import { asBackendError, ConfigurationError, E2EError, errorMessage, isForeignE2EError, } from '../internal/errors.js';
+import { BackendError, } from './surface.js';
+/** Located refs are pruned oldest-first past this bound so the map cannot grow unboundedly. */
+const MAX_LOCATED_REFS = 2048;
+/** Revision prefixes: the adapter mints `l<n>` for locate and `b<n>` for observe. */
+const LOCATE_REVISION_PREFIX = 'l';
+const OBSERVE_REVISION_PREFIX = 'b';
+/**
+ * Stamps the adapter's revision onto every ref. Backends mint stable ids;
+ * the adapter owns revisions, so the staleness rule (act on the newest
+ * observation only) holds without every backend reimplementing it.
+ */
+function stampRevision(node, revision) {
+    return {
+        ...node,
+        ref: { id: node.ref.id, revision },
+        ...(node.children === undefined
+            ? {}
+            : { children: node.children.map((child) => stampRevision(child, revision)) }),
+    };
+}
+/** Wraps a backend snapshot's root nodes into the single-root observation tree. */
+function toTree(nodes, revision) {
+    const stamped = nodes.map((node) => stampRevision(node, revision));
+    const first = stamped[0];
+    if (stamped.length === 1 && first !== undefined)
+        return first;
+    return { ref: { id: 'root', revision }, role: 'root', children: stamped };
+}
+function countSecure(nodes) {
+    let count = 0;
+    for (const node of nodes) {
+        if (node.states?.secure === true)
+            count += 1;
+        if (node.children !== undefined)
+            count += countSecure(node.children);
+    }
+    return count;
+}
+/**
+ * Normalizes what a backend threw onto the error contract. `BackendError`
+ * (from any module copy) and runner errors pass through; anything else is the
+ * backend failing outside its contract, reported as infrastructure.
+ */
+function normalize(cause, label) {
+    if (cause instanceof E2EError || isForeignE2EError(cause) || asBackendError(cause) !== undefined) {
+        throw cause;
+    }
+    throw new BackendError('BACKEND_FAILURE', `${label} failed: ${errorMessage(cause)}`, {
+        retryable: false,
+        cause,
+    });
+}
+/** The grammar verbs a backend declaration can honor. */
+function declaredVerbs(backend) {
+    const verbs = new Set();
+    if (backend?.perform !== undefined) {
+        for (const verb of ['tap', 'type', 'typeSecret', 'press', 'select'])
+            verbs.add(verb);
+    }
+    if (backend?.swipe !== undefined)
+        verbs.add('scroll');
+    if (backend?.app?.navigate !== undefined)
+        verbs.add('navigate');
+    return verbs;
+}
+/**
+ * Builds one session over a backend. One adapter per attempt; revisions are
+ * minted per adapter, so refs can never leak across attempts.
+ */
+export function createBackendSession(options) {
+    const { backend, targetName } = options;
+    let revision = 0;
+    let viewport = { width: 1, height: 1, scale: 1 };
+    const unsupported = (what) => {
+        throw new ConfigurationError('UNSUPPORTED_CAPABILITY', `target "${targetName}" has no backend capability for ${what}`);
+    };
+    /**
+     * One declared member as a guarded call: capability-checked at the moment of
+     * use and error-normalized. `defineBackend` bound every member to its body,
+     * so the function is called as is.
+     */
+    const guard = (what, fn) => async (...args) => {
+        if (fn === undefined)
+            return unsupported(what);
+        try {
+            return await fn(...args);
+        }
+        catch (cause) {
+            return normalize(cause, what);
+        }
+    };
+    // Located nodes, cached by id so `read(ref)` answers from the resolution
+    // that minted the ref. A read against an older resolution is NODE_STALE,
+    // which the engine treats as retryable: it re-resolves and reads again.
+    let locateRevision = 0;
+    const located = new Map();
+    const stale = (ref) => new BackendError('NODE_STALE', `node ${ref.id} is stale; re-resolve`, { retryable: true });
+    /**
+     * A located ref from a superseded resolution never reaches the backend.
+     * Observation refs are exempt: they are checked by the backend against its
+     * newest observation, and a backend with stable ids may legitimately hand
+     * the same id to both tiers.
+     */
+    const rejectSupersededLocate = (ref) => {
+        if (!ref.revision.startsWith(LOCATE_REVISION_PREFIX))
+            return;
+        const known = located.get(ref.id);
+        if (known !== undefined && known.ref.revision !== ref.revision)
+            throw stale(ref);
+    };
+    const locateRaw = guard('locators (screen)', backend?.locate);
+    const observeRaw = guard('observation', backend?.observe);
+    const app = {
+        open: guard('navigation', backend?.app?.navigate),
+        back: guard('back navigation', backend?.app?.back),
+        restart: guard('app restart', backend?.app?.restart),
+        clearState: guard('app state clearing', backend?.app?.clearState),
+    };
+    const artifacts = {
+        screenshot: guard('screenshots', backend?.artifacts?.screenshot),
+        ...(backend?.artifacts?.startTrace === undefined || backend.artifacts.stopTrace === undefined
+            ? {}
+            : {
+                startTrace: guard('traces', backend.artifacts.startTrace),
+                stopTrace: guard('traces', backend.artifacts.stopTrace),
+            }),
+    };
+    let ended = false;
+    return {
+        verbs: declaredVerbs(backend),
+        app,
+        artifacts,
+        ...(backend?.state === undefined
+            ? {}
+            : {
+                captureState: guard('state capture', backend.state.capture),
+                restoreState: guard('state restore', backend.state.restore),
+            }),
+        ...(backend?.url === undefined ? {} : { url: guard('the current URL', backend.url) }),
+        async observe(operation, observeOptions) {
+            const snapshot = await observeRaw(operation, observeOptions?.pixels === true ? { pixels: true } : {});
+            if (snapshot.viewport !== undefined)
+                viewport = snapshot.viewport;
+            revision += 1;
+            const minted = `${OBSERVE_REVISION_PREFIX}${revision}`;
+            return {
+                revision: minted,
+                capturedAt: new Date().toISOString(),
+                ...(snapshot.pixels === undefined ? {} : { pixels: snapshot.pixels }),
+                tree: toTree(snapshot.nodes, minted),
+                viewport,
+                redaction: {
+                    secureNodeCount: countSecure(snapshot.nodes),
+                    maskedRegionCount: snapshot.maskedRegionCount ?? 0,
+                },
+            };
+        },
+        async locate(expression, operation) {
+            const nodes = await locateRaw(expression, operation);
+            locateRevision += 1;
+            const locateRev = `${LOCATE_REVISION_PREFIX}${locateRevision}`;
+            const refs = [];
+            for (const node of nodes) {
+                const stamped = stampRevision(node, locateRev);
+                located.delete(stamped.ref.id);
+                located.set(stamped.ref.id, stamped);
+                refs.push(stamped.ref);
+            }
+            for (const oldest of located.keys()) {
+                if (located.size <= MAX_LOCATED_REFS)
+                    break;
+                located.delete(oldest);
+            }
+            return refs;
+        },
+        async read(ref) {
+            if (backend?.locate === undefined)
+                unsupported('locators (screen)');
+            const node = located.get(ref.id);
+            if (node === undefined || node.ref.revision !== ref.revision)
+                throw stale(ref);
+            return node;
+        },
+        async perform(ref, action, operation) {
+            rejectSupersededLocate(ref);
+            if (action.kind === 'dragTo')
+                rejectSupersededLocate(action.target);
+            await guard(`the "${action.kind}" action`, backend?.perform)(ref, action, operation);
+        },
+        swipe: guard('swipe gestures', backend?.swipe),
+        // The backend outlives the attempt; only the per-attempt isolation ends
+        // here, exactly once. dispose() belongs to the worker.
+        close: guard('attempt end', async (operation) => {
+            if (ended)
+                return;
+            ended = true;
+            await backend?.endAttempt?.({ signal: operation.signal, timeoutMs: operation.timeoutMs });
+        }),
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/backend/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/backend/session.ts"],"names":[],"mappings":"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"}

package/dist/backend/surface.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The internal session surface the harness consumes for one attempt. It is
+ * produced only by `createBackendSession` (the backend-to-session adapter) and
+ * is never part of the public API: the locator engine, the agent tiers, and
+ * the attempt executor program against it so that revision minting, staleness
+ * checks, and capability gating exist exactly once.
+ *
+ * Re-exports the contract vocabulary so internal modules import one path.
+ */
+import type { Momentum, ScrollDirection } from '../types.ts';
+import type { LocatorAction, LocatorExpression, NodeRef, ObservationPixels, OperationContext, SemanticNode } from './contract.ts';
+import type { BackendObserveOptions, BackendState } from './index.ts';
+export type * from './contract.ts';
+export { BackendError } from './contract.ts';
+export type { BackendObserveOptions, BackendState } from './index.ts';
+/**
+ * The agent's action grammar, by verb. A session declares which verbs its
+ * backend can honor so the agent offers the model exactly that vocabulary.
+ */
+export type GrammarVerb = 'tap' | 'type' | 'typeSecret' | 'press' | 'select' | 'scroll' | 'navigate';
+export interface Observation {
+    readonly revision: string;
+    readonly capturedAt: string;
+    readonly pixels?: ObservationPixels;
+    readonly tree: SemanticNode;
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+        readonly scale: number;
+    };
+    /**
+     * What the backend masked against what it saw. Pixel completeness is judged
+     * downstream from these counts: fewer masked regions than secure nodes
+     * withholds the pixels and keeps the tree.
+     */
+    readonly redaction: {
+        readonly secureNodeCount: number;
+        readonly maskedRegionCount: number;
+    };
+}
+export interface SessionApp {
+    /** Opens the app at one resolved URL. */
+    open(url: string, operation: OperationContext): Promise<void>;
+    /** Navigates back once. */
+    back(operation: OperationContext): Promise<void>;
+    /** Recreates the app context without clearing persisted state. */
+    restart(operation: OperationContext): Promise<void>;
+    /** Clears persisted client state and relaunches. */
+    clearState(operation: OperationContext): Promise<void>;
+}
+export interface SessionArtifacts {
+    /** Captures a redacted screenshot and returns an artifact-relative path. */
+    screenshot(label: string | undefined, operation: OperationContext): Promise<string>;
+    /** Starts trace recording. */
+    startTrace?(operation: OperationContext): Promise<void>;
+    /** Stops trace recording and returns an artifact-relative path. */
+    stopTrace?(operation: OperationContext): Promise<string>;
+}
+export interface TargetSession {
+    /** Grammar verbs the backend can honor, read from its declaration. */
+    readonly verbs: ReadonlySet<GrammarVerb>;
+    /** Captures one atomic agent observation; the harness redacts it downstream. */
+    observe(operation: OperationContext, options?: BackendObserveOptions): Promise<Observation>;
+    /** Resolves immediately; the runner owns query polling and strictness. */
+    locate(expression: LocatorExpression, operation: OperationContext): Promise<readonly NodeRef[]>;
+    /** Reads one node from the resolution that minted its ref. */
+    read(ref: NodeRef, operation: OperationContext): Promise<SemanticNode>;
+    /** Performs exactly one action on a located or observed node. */
+    perform(ref: NodeRef, action: LocatorAction, operation: OperationContext): Promise<void>;
+    /** Performs a viewport-level swipe. */
+    swipe(direction: ScrollDirection, momentum: Momentum | undefined, operation: OperationContext): Promise<void>;
+    readonly app: SessionApp;
+    readonly artifacts: SessionArtifacts;
+    /** Captures immutable app state for a session envelope. */
+    captureState?(operation: OperationContext): Promise<BackendState>;
+    /** Replaces current app state with an immutable captured state. */
+    restoreState?(state: BackendState, operation: OperationContext): Promise<void>;
+    /** Current top-level URL of the surface, when the platform has one. */
+    url?(operation: OperationContext): Promise<string>;
+    /** Ends the attempt's isolation within the operation's budget. Idempotent. */
+    close(operation: OperationContext): Promise<void>;
+}
+//# sourceMappingURL=surface.d.ts.map

package/dist/backend/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/backend/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACb,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE,mBAAmB,eAAe,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;KACpC,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,2BAA2B;IAC3B,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,kEAAkE;IAClE,OAAO,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,oDAAoD;IACpD,UAAU,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpF,8BAA8B;IAC9B,UAAU,CAAC,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,mEAAmE;IACnE,SAAS,CAAC,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACzC,gFAAgF;IAChF,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5F,0EAA0E;IAC1E,MAAM,CAAC,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IAChG,8DAA8D;IAC9D,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACvE,iEAAiE;IACjE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,uCAAuC;IACvC,KAAK,CACH,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,SAAS,EAAE,gBAAgB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,2DAA2D;IAC3D,YAAY,CAAC,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClE,mEAAmE;IACnE,YAAY,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,uEAAuE;IACvE,GAAG,CAAC,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,8EAA8E;IAC9E,KAAK,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/backend/surface.js

@@ -0,0 +1,11 @@
+/**
+ * The internal session surface the harness consumes for one attempt. It is
+ * produced only by `createBackendSession` (the backend-to-session adapter) and
+ * is never part of the public API: the locator engine, the agent tiers, and
+ * the attempt executor program against it so that revision minting, staleness
+ * checks, and capability gating exist exactly once.
+ *
+ * Re-exports the contract vocabulary so internal modules import one path.
+ */
+export { BackendError } from './contract.js';
+//# sourceMappingURL=surface.js.map

package/dist/backend/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/backend/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/cache/anchors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * End anchors (RFC0001 layer 3, cache-in decision).
+ *
+ * A recording run does not end when its last action commits; it ends when the
+ * executor looks at the screen and judges the step done. The trace used to
+ * keep only the actions and drop that look, so a replay could run every
+ * recorded action mechanically — a fill that never committed, a save that
+ * produced an unnamed record — and self-finalize with nothing checking the
+ * effect. Anchors restore the check as data: the descriptors of nodes that
+ * were on screen when the step passed and were not there when it began. They
+ * are the step's own delta, checked by the relocation vocabulary
+ * (`relocate.ts`) with two deliberate differences: every recorded field must
+ * be equal, text included, and presence is enough — uniqueness is not asked.
+ */
+import type { SemanticNode } from '../backend/surface.ts';
+import { type DescriptorMatchOptions } from './relocate.ts';
+import { type TraceTargetDescriptor } from './trace.ts';
+export type AnchorOptions = DescriptorMatchOptions;
+/**
+ * Derives the end anchors of one step: relocatable descriptors present in the
+ * passing observation and absent from the starting one, deduplicated, capped.
+ * Leaves come first, then containers, each in document order: a container's
+ * accessible name is usually the concatenation of its children's, so it
+ * repeats what the leaves already say — and on a list-heavy screen those
+ * repeats would crowd the one status line that names the effect out of the
+ * cap.
+ */
+export declare function describeAnchors(startNodes: ReadonlyMap<string, SemanticNode>, endNodes: ReadonlyMap<string, SemanticNode>, options: AnchorOptions): TraceTargetDescriptor[];
+/**
+ * Whether every anchor is present in a fresh observation: some tier of the
+ * anchor (`descriptorTiers` — so a test id that churned per render is
+ * forgiven when the remaining fields still identify the node) equals some
+ * candidate on every anchor field. Two matching nodes are the effect twice
+ * over, not an ambiguity.
+ */
+export declare function anchorsPresent(anchors: readonly TraceTargetDescriptor[], nodes: ReadonlyMap<string, SemanticNode>, options: AnchorOptions): boolean;
+//# sourceMappingURL=anchors.d.ts.map

package/dist/cache/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../../src/cache/anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAYnD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAC7C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAC3C,OAAO,EAAE,aAAa,GACrB,qBAAqB,EAAE,CAkBzB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EACxC,OAAO,EAAE,aAAa,GACrB,OAAO,CAOT"}

package/dist/cache/anchors.js

@@ -0,0 +1,89 @@
+/**
+ * End anchors (RFC0001 layer 3, cache-in decision).
+ *
+ * A recording run does not end when its last action commits; it ends when the
+ * executor looks at the screen and judges the step done. The trace used to
+ * keep only the actions and drop that look, so a replay could run every
+ * recorded action mechanically — a fill that never committed, a save that
+ * produced an unnamed record — and self-finalize with nothing checking the
+ * effect. Anchors restore the check as data: the descriptors of nodes that
+ * were on screen when the step passed and were not there when it began. They
+ * are the step's own delta, checked by the relocation vocabulary
+ * (`relocate.ts`) with two deliberate differences: every recorded field must
+ * be equal, text included, and presence is enough — uniqueness is not asked.
+ */
+import { describeTarget } from '../agent/actions.js';
+import { describeNodes, descriptorTiers, fieldsEqual, } from './relocate.js';
+import { MAX_TRACE_ANCHORS } from './trace.js';
+/**
+ * Every field an anchor records. Unlike target relocation, text is never
+ * optional here: for a target, text is a fallback identity and a relabeled
+ * button is still the button, but for an anchor the text *is* the effect (a
+ * status reading "saved" rather than "empty"), so a looser match would pass a
+ * step whose save never took. The structural selector is left out — anchors
+ * ask whether an effect is visible, never where it sits in the document.
+ */
+const ANCHOR_FIELDS = ['role', 'name', 'text', 'testId', 'placeholder', 'inputPurpose'];
+/**
+ * Derives the end anchors of one step: relocatable descriptors present in the
+ * passing observation and absent from the starting one, deduplicated, capped.
+ * Leaves come first, then containers, each in document order: a container's
+ * accessible name is usually the concatenation of its children's, so it
+ * repeats what the leaves already say — and on a list-heavy screen those
+ * repeats would crowd the one status line that names the effect out of the
+ * cap.
+ */
+export function describeAnchors(startNodes, endNodes, options) {
+    const before = new Set();
+    for (const node of startNodes.values()) {
+        const descriptor = anchorDescriptor(node, options);
+        if (descriptor !== undefined)
+            before.add(anchorKey(descriptor));
+    }
+    const seen = new Set();
+    const leaves = [];
+    const containers = [];
+    for (const node of endNodes.values()) {
+        const descriptor = anchorDescriptor(node, options);
+        if (descriptor === undefined)
+            continue;
+        const key = anchorKey(descriptor);
+        if (before.has(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        (node.children === undefined || node.children.length === 0 ? leaves : containers).push(descriptor);
+    }
+    return [...leaves, ...containers].slice(0, MAX_TRACE_ANCHORS);
+}
+/**
+ * Whether every anchor is present in a fresh observation: some tier of the
+ * anchor (`descriptorTiers` — so a test id that churned per render is
+ * forgiven when the remaining fields still identify the node) equals some
+ * candidate on every anchor field. Two matching nodes are the effect twice
+ * over, not an ambiguity.
+ */
+export function anchorsPresent(anchors, nodes, options) {
+    const candidates = describeNodes(nodes, options).map((node) => node.descriptor);
+    return anchors.every((anchor) => descriptorTiers(anchor).some((tier) => candidates.some((candidate) => fieldsEqual(tier, candidate, ANCHOR_FIELDS))));
+}
+/** One node's anchor projection, or undefined when it could identify nothing. */
+function anchorDescriptor(node, options) {
+    const described = describeTarget(node, options.redact, options.testIdAttribute);
+    if (described === undefined || descriptorTiers(described).length === 0)
+        return undefined;
+    const { selector: _selector, ...anchor } = described;
+    return anchor;
+}
+/**
+ * Set key for one descriptor: its loosest identifying tier over the anchor
+ * fields, in fixed order. Keying on the semantic tier whenever it identifies
+ * the node means an app that mints test ids per render cannot make every
+ * unchanged control look new after a re-render and crowd the real effect out
+ * of the capped list; a node only a test id identifies keeps it.
+ */
+function anchorKey(descriptor) {
+    const tiers = descriptorTiers(descriptor);
+    const loosest = tiers[tiers.length - 1] ?? descriptor;
+    return JSON.stringify(ANCHOR_FIELDS.map((field) => loosest[field]));
+}
+//# sourceMappingURL=anchors.js.map

package/dist/cache/anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.js","sourceRoot":"","sources":["../../src/cache/anchors.ts"],"names":[],"mappings":"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"}

package/dist/cache/context.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-attempt cache context (RFC0001 layer 3, cache-in decision).
+ *
+ * Built by the runner once per attempt and handed to the agent tier: the
+ * resolved store, key derivation over the attempt's fixed identity, and the
+ * staging ground for trace writes. Replay is eligible only on a first attempt
+ * — a retry exists because something already went wrong, so it runs fresh and
+ * re-records.
+ */
+import type { ResolvedCacheConfig } from '../config/resolve.ts';
+import { type CacheTargetIdentity, type TraceCacheKind } from './identity.ts';
+import { type TraceCacheStore } from './store.ts';
+import type { ActionTrace } from './trace.ts';
+import type { JsonValue } from '../types.ts';
+/** One trace write held back until the attempt confirms or implicates it. */
+export interface StagedTraceWrite {
+    readonly keyHash: string;
+    readonly trace: ActionTrace;
+    /** Index of the recording step in the attempt's step timeline. */
+    readonly stepIndex: number;
+}
+export interface AgentCacheContext {
+    readonly mode: 'read-only' | 'read-write';
+    readonly store: TraceCacheStore;
+    /** Whether this attempt may replay; writes are governed by `mode` alone. */
+    readonly replayEligible: boolean;
+    /**
+     * Claims one step's key hash. Not a pure derivation: each claim advances
+     * the per-attempt occurrence index for its signature, which is what lets a
+     * test repeat the same instruction and cache each occurrence separately.
+     * Exactly one claim per dispatched step, in execution order — the
+     * `StepTraceSession` constructor is the sole caller and owns that
+     * invariant structurally.
+     */
+    claimKeyHash(kind: TraceCacheKind, instruction: string, params: Readonly<Record<string, JsonValue>> | undefined): string;
+    /**
+     * Trace writes staged during the attempt. A trace is not trusted the moment
+     * its own step passes — the verification step after it is what proves the
+     * flow reached the right state. The runner settles at attempt end via
+     * `flushStagedTraces`.
+     */
+    readonly staged: StagedTraceWrite[];
+}
+/**
+ * Settles the attempt's staged trace writes. A staged trace is confirmed only
+ * when a verification step — a deterministic assertion or an agent judgment
+ * (`run/steps.ts`, `StepRunOptions.verifies`) — passed after it: an act's own
+ * verdict is the recording executor's opinion of its work, and a later act
+ * passing says only that the executor coped with whatever state it found. A
+ * passing attempt confirms nothing by itself, so a flow no assertion ever
+ * checked is never replayed blind, and a failing attempt confirms exactly
+ * what had been verified before the failure landed. An unconfirmed trace is
+ * not merely withheld: its entry is evicted, so a cached flow implicated in
+ * a failure — or one that was never checked — re-records on the next pass
+ * instead of replaying a poisoned state forever. The runner does not call
+ * this for an interrupted attempt: interruption implicates nothing, so it
+ * writes nothing and evicts nothing.
+ */
+export declare function flushStagedTraces(context: AgentCacheContext, lastVerifiedStepIndex: number): Promise<void>;
+/**
+ * Builds one attempt's cache context, or undefined when the cache is off.
+ * A configured custom store replaces the file store wholesale — that is the
+ * seam a cloud-shared store (Redis, an API) plugs into. Its hits are
+ * re-validated at the one read site (`StepTraceSession.begin`), like
+ * every other store's.
+ */
+export declare function createAgentCacheContext(options: {
+    readonly cache: ResolvedCacheConfig;
+    readonly projectId: string;
+    readonly testId: string;
+    readonly target: CacheTargetIdentity;
+    readonly attemptIndex: number;
+}): AgentCacheContext | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/cache/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/cache/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAML,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;OAOG;IACH,YAAY,CACV,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,SAAS,GACtD,MAAM,CAAC;IACV;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,qBAAqB,EAAE,MAAM,GAC5B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GAAG,iBAAiB,GAAG,SAAS,CA+BhC"}

package/dist/cache/context.js

@@ -0,0 +1,82 @@
+/**
+ * Per-attempt cache context (RFC0001 layer 3, cache-in decision).
+ *
+ * Built by the runner once per attempt and handed to the agent tier: the
+ * resolved store, key derivation over the attempt's fixed identity, and the
+ * staging ground for trace writes. Replay is eligible only on a first attempt
+ * — a retry exists because something already went wrong, so it runs fresh and
+ * re-records.
+ */
+import { REPLAY_POLICY_VERSION } from './relocate.js';
+import { buildTraceCacheKey, createCallIndexer, projectIdentity, traceCacheKeyHash, traceCallSignature, } from './identity.js';
+import { FileTraceCacheStore, MAX_CACHE_WIRE_BYTES } from './store.js';
+/**
+ * Settles the attempt's staged trace writes. A staged trace is confirmed only
+ * when a verification step — a deterministic assertion or an agent judgment
+ * (`run/steps.ts`, `StepRunOptions.verifies`) — passed after it: an act's own
+ * verdict is the recording executor's opinion of its work, and a later act
+ * passing says only that the executor coped with whatever state it found. A
+ * passing attempt confirms nothing by itself, so a flow no assertion ever
+ * checked is never replayed blind, and a failing attempt confirms exactly
+ * what had been verified before the failure landed. An unconfirmed trace is
+ * not merely withheld: its entry is evicted, so a cached flow implicated in
+ * a failure — or one that was never checked — re-records on the next pass
+ * instead of replaying a poisoned state forever. The runner does not call
+ * this for an interrupted attempt: interruption implicates nothing, so it
+ * writes nothing and evicts nothing.
+ */
+export async function flushStagedTraces(context, lastVerifiedStepIndex) {
+    const staged = context.staged.splice(0);
+    if (context.mode !== 'read-write')
+        return;
+    for (const write of staged) {
+        const confirmed = write.stepIndex < lastVerifiedStepIndex;
+        try {
+            if (confirmed)
+                await context.store.write(write.keyHash, write.trace);
+            else
+                await context.store.delete?.(write.keyHash);
+        }
+        catch {
+            // The cache is disposable; a failed flush is a slower next run only.
+        }
+    }
+}
+/**
+ * Builds one attempt's cache context, or undefined when the cache is off.
+ * A configured custom store replaces the file store wholesale — that is the
+ * seam a cloud-shared store (Redis, an API) plugs into. Its hits are
+ * re-validated at the one read site (`StepTraceSession.begin`), like
+ * every other store's.
+ */
+export function createAgentCacheContext(options) {
+    const mode = options.cache.mode;
+    if (mode === 'off')
+        return undefined;
+    const store = options.cache.store ??
+        new FileTraceCacheStore({
+            directory: options.cache.dir,
+            maxBytes: MAX_CACHE_WIRE_BYTES,
+            writable: mode === 'read-write',
+        });
+    const project = projectIdentity(options.projectId);
+    const nextCallIndex = createCallIndexer();
+    return {
+        mode,
+        store,
+        replayEligible: options.attemptIndex === 0,
+        claimKeyHash: (kind, instruction, params) => {
+            const signature = traceCallSignature(kind, instruction, params);
+            return traceCacheKeyHash(buildTraceCacheKey({
+                project,
+                testId: options.testId,
+                target: options.target,
+                signature,
+                callIndex: nextCallIndex(signature),
+                policyVersion: REPLAY_POLICY_VERSION,
+            }));
+        },
+        staged: [],
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/cache/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/cache/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GAGnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAwB,MAAM,YAAY,CAAC;AAuC7F;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA0B,EAC1B,qBAA6B;IAE7B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,OAAO,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,GAAG,qBAAqB,CAAC;QAC1D,IAAI,CAAC;YACH,IAAI,SAAS;gBAAE,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;;gBAChE,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;QACvE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAMvC;IACC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;IAChC,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,CAAC,KAAK;QACnB,IAAI,mBAAmB,CAAC;YACtB,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG;YAC5B,QAAQ,EAAE,oBAAoB;YAC9B,QAAQ,EAAE,IAAI,KAAK,YAAY;SAChC,CAAC,CAAC;IACL,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,iBAAiB,EAAE,CAAC;IAC1C,OAAO;QACL,IAAI;QACJ,KAAK;QACL,cAAc,EAAE,OAAO,CAAC,YAAY,KAAK,CAAC;QAC1C,YAAY,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;YAC1C,MAAM,SAAS,GAAG,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;YAChE,OAAO,iBAAiB,CACtB,kBAAkB,CAAC;gBACjB,OAAO;gBACP,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,SAAS;gBACT,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC;gBACnC,aAAa,EAAE,qBAAqB;aACrC,CAAC,CACH,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,EAAE;KACX,CAAC;AACJ,CAAC"}