e2e 0.15.2 → 0.17.0

package/dist/cache/anchors.js

@@ -1,20 +1,31 @@
 /**
- * End anchors.
+ * Anchors: the step's recorded delta.
  *
  * 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.
+ * effect. Anchors restore the check as data: the descriptors of nodes the
+ * step made appear (`endAnchors`) and of nodes it made vanish
+ * (`goneAnchors`), each with the states a step sets on a control it leaves
+ * on screen (a switch turned on, a field typed into). They are checked by
+ * the relocation vocabulary (`relocate.ts`) with two deliberate differences:
+ * every recorded field must be equal, text, value, and states included, and
+ * presence is enough, uniqueness is not asked.
+ *
+ * A replay passes on its own only when the delta happened again: everything
+ * that appeared is there, everything that vanished is gone, and at least one
+ * of those changes, or the route, actually moved during the replay
+ * (`deltaEvidenced`), so a status that already read "Submitted" before a
+ * submit that did nothing is no proof. An alert the replay raised that the
+ * recording never saw is an outcome the recording did not have, whatever
+ * else matched (`deltaHolds`).
  */
 import { describeTarget } from '../agent/actions.js';
-import { describeNodes, descriptorTiers, fieldsEqual, } from './relocate.js';
-import { MAX_TRACE_ANCHORS } from './trace.js';
+import { collapseText } from '../internal/text.js';
+import { descriptorTiers, fieldsEqual } from './relocate.js';
+import { bound, MAX_TRACE_ANCHORS, MAX_TRACE_DESCRIPTOR_CHARS, TRACE_ANCHOR_STATES, } 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
@@ -25,57 +36,95 @@ import { MAX_TRACE_ANCHORS } from './trace.js';
  */
 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.
+ * Roles an app announces an outcome in: the ARIA live regions a screen
+ * reader reads out on change, and the alert dialog. The app itself says
+ * this text reports what just happened, so these are recorded before any
+ * other anchor and the cap never crowds them out.
  */
-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 ANNOUNCEMENT_ROLES = new Set(['alert', 'alertdialog', 'status']);
+/**
+ * The announcements that interrupt: an error, a warning, a confirmation the
+ * user must answer. A replay that raises one the recording never saw has
+ * another outcome than the recording, so every one that appears is recorded
+ * whatever its text, and checked both ways.
+ */
+const ALERT_ROLES = new Set(['alert', 'alertdialog']);
+/**
+ * Derives one step's delta between its starting observation and its passing
+ * one. Each side is ordered announcements first, then leaves, 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. `routeMoved`
+ * says the step ended on another route than it began on, whose counts are
+ * that screen's data rather than the step's result (`COUNT_TEXT`).
+ *
+ * A node counts as gone only when no end node matches its anchor the way
+ * `deltaHolds` checks one, on the recorded fields alone: a radio label
+ * "Express" the pick replaced with a status reading "Express" vanished, but
+ * an anchor of that text would still match the status, and the recording
+ * would fail its own check on every replay.
+ */
+export function describeDelta(startNodes, endNodes, routeMoved) {
+    const start = projectAnchors(startNodes);
+    const end = projectAnchors(endNodes);
+    const startKeys = new Set(start.map((anchor) => anchor.key));
+    const endKeys = new Set(end.map((anchor) => anchor.key));
+    return {
+        appeared: deltaSide(end, start, (anchor) => startKeys.has(anchor.key), routeMoved),
+        gone: deltaSide(start, end, (anchor) => endKeys.has(anchor.key) || anchorIn(anchor.descriptor, end), routeMoved),
+    };
+}
+/** The side of the delta `nodes` holds and `other` does not (`inOther`), ordered and capped. */
+function deltaSide(nodes, other, inOther, routeMoved) {
+    const otherShapes = new Set(other.map((anchor) => countShape(anchor.descriptor)));
+    const volatile = (anchor) => isVolatileAnchor(anchor, (count) => routeMoved || otherShapes.has(countShape(count)));
     const seen = new Set();
+    const announcements = [];
     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))
+    for (const anchor of nodes) {
+        if (seen.has(anchor.key) || inOther(anchor))
             continue;
-        seen.add(key);
-        (node.children === undefined || node.children.length === 0 ? leaves : containers).push(descriptor);
+        seen.add(anchor.key);
+        const role = anchor.descriptor.role ?? '';
+        (ANNOUNCEMENT_ROLES.has(role) ? announcements : anchor.leaf ? leaves : containers).push(anchor);
     }
-    const all = [...leaves, ...containers];
-    const stable = all.filter((anchor) => !isVolatileAnchor(anchor));
-    return (stable.length > 0 ? stable : all).slice(0, MAX_TRACE_ANCHORS);
+    const all = [...announcements, ...leaves, ...containers];
+    const stable = all.filter((anchor) => isAlert(anchor.descriptor) || !volatile(anchor.descriptor));
+    return (stable.length > 0 ? stable : all).slice(0, MAX_TRACE_ANCHORS).map((anchor) => anchor.descriptor);
 }
 /**
  * Text that cannot read the same on the next run: a minted key prefix or id,
- * a countdown or age, a date, a clock time, a timing in milliseconds, a
- * pagination range or record count that grows with the data every run
- * leaves behind. An anchor made of it hands every replay off, so it is
- * skipped while some stable anchor exists; with nothing else, the volatile
- * ones stay, because a replay that always hands off is still safer than
- * one that passes on mechanics alone.
+ * a countdown or age, a date, a clock time, a timing in milliseconds. An
+ * anchor made of it hands every replay off, so it is skipped while some
+ * stable anchor exists; with nothing else, the volatile ones stay, because a
+ * replay that always hands off is still safer than one that passes on
+ * mechanics alone. An alert keeps it, and is compared with these parts read
+ * as placeholders (`alertShape`).
  */
 const VOLATILE_TEXT = [
     /\b(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{12,}\b/,
     /\b\d+\s*(?:ms|s|secs?|seconds?|m|mins?|minutes?|h|hrs?|hours?|d|days?|weeks?|months?|years?)\b/i,
-    /\b\d+\s*(?:to|-|\u2013)\s*\d+\s+of\s+\d+\b/i,
-    /\b\d+\s+(?:results?|items?|rows?|entries|records?|matches|total)\b/i,
     /\b(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?\s+\d{1,2}(?:,?\s+\d{4})?\b/i,
     /\b\d{1,2}\s+(?:jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?(?:\s+\d{4})?\b/i,
     /\b\d{4}-\d{2}-\d{2}\b/,
     /\b\d{1,2}:\d{2}(?::\d{2})?\b/,
 ];
+/**
+ * A count that names what it counts: a pagination range, `12 items`, `3
+ * records imported`. Such a count is the step's own result when the step
+ * made it appear on the screen it acted on, and must read the same again:
+ * `0 records imported` is not the import the recording saw. It is the data
+ * instead, which the next run, with what an earlier run left behind, reads
+ * differently, when the other side of the delta already showed the same
+ * text with other numbers (`41 items` became `42 items`), or when the step
+ * moved to another route and the count is part of the screen it opened.
+ */
+const COUNT_TEXT = [
+    /\b\d+\s*(?:to|-|\u2013)\s*\d+\s+of\s+\d+\b/i,
+    /\b\d+\s+(?:results?|items?|rows?|entries|records?|matches|total)\b/i,
+];
 /**
  * A bare number is a badge or a tally, `11` unread, and reads differently
  * once the data changes; it is volatile when it is all the anchor has to say.
@@ -86,39 +135,162 @@ function isBareNumber(anchor) {
     const label = anchor.name ?? anchor.text;
     return label !== undefined && /^\d+$/.test(label) && anchor.testId === undefined && (anchor.name === undefined || anchor.text === undefined || anchor.name === anchor.text);
 }
-function isVolatileAnchor(anchor) {
-    return (isBareNumber(anchor) ||
-        [anchor.text, anchor.name].some((value) => value !== undefined && VOLATILE_TEXT.some((pattern) => pattern.test(value))));
+/** Whether an anchor's text cannot read the same on the next run; `countIsData` decides an anchor holding a count. */
+function isVolatileAnchor(anchor, countIsData) {
+    const texts = [anchor.text, anchor.name, anchor.value].filter((value) => value !== undefined);
+    if (isBareNumber(anchor) || texts.some((value) => VOLATILE_TEXT.some((pattern) => pattern.test(value))))
+        return true;
+    return texts.some((value) => COUNT_TEXT.some((pattern) => pattern.test(value))) && countIsData(anchor);
+}
+/** An anchor with every digit run read as one placeholder: the text a running count keeps while its numbers move. */
+function countShape(anchor) {
+    return anchorKey({ ...anchor, ...digitless('name', anchor.name), ...digitless('text', anchor.text), ...digitless('value', anchor.value) });
+}
+function digitless(field, value) {
+    return value === undefined ? {} : { [field]: value.replace(/\d+/g, '#') };
+}
+function isAlert(anchor) {
+    return anchor.role !== undefined && ALERT_ROLES.has(anchor.role);
+}
+const VOLATILE_SPANS = VOLATILE_TEXT.map((pattern) => new RegExp(pattern.source, `${pattern.flags}g`));
+/**
+ * An alert with its volatile parts read as one placeholder each: `Session
+ * expires at 17:42` and `Session expires at 17:45` are the same alert, which
+ * a replay must neither miss nor mistake for one the recording never saw.
+ */
+function alertShape(anchor) {
+    const mask = (text) => VOLATILE_SPANS.reduce((masked, span) => masked.replace(span, '#'), text);
+    return {
+        ...anchor,
+        ...(anchor.name === undefined ? {} : { name: mask(anchor.name) }),
+        ...(anchor.text === undefined ? {} : { text: mask(anchor.text) }),
+    };
+}
+/**
+ * Whether the recorded end state holds on a fresh observation: every
+ * appeared anchor present (some tier of it, `descriptorTiers`, so a test id
+ * that churned per render is forgiven when the remaining fields still
+ * identify the node, equal on every anchor field and state), no gone anchor
+ * present, and no alert on screen that was not on `beforeNodes` and is not
+ * one the recording saw appear. Two nodes matching one anchor are the effect
+ * twice over, not an ambiguity.
+ */
+export function deltaHolds(delta, nodes, beforeNodes) {
+    const live = projectAnchors(nodes);
+    const appeared = delta.endAnchors ?? [];
+    if (!appeared.every((anchor) => anchorIn(anchor, live)))
+        return false;
+    if ((delta.goneAnchors ?? []).some((anchor) => anchorIn(anchor, live)))
+        return false;
+    const before = projectAnchors(beforeNodes).filter((anchor) => isAlert(anchor.descriptor));
+    return live.every((anchor) => !isAlert(anchor.descriptor) ||
+        before.some((earlier) => anchorIn(anchor.descriptor, [earlier])) ||
+        appeared.some((recorded) => anchorIn(recorded, [anchor])));
 }
 /**
- * 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.
+ * Whether the replay itself produced some of the recorded delta, measured
+ * from `baselineNodes`, the first screen the replay saw on the route it
+ * ended on: an anchor that appeared was absent there, or a gone one was
+ * there. Without that, every check `deltaHolds` makes could have held before
+ * the actions that should have produced it: the screen already read the
+ * outcome, and nothing the replay did is proven to have done anything. A
+ * recording with no delta at all is never evidence. Undefined `baselineNodes`
+ * means the replay saw no screen on that route before its last action, so
+ * that action moved the route, which is the evidence.
+ *
+ * A control one of the trace's own actions targeted (`inputTargets`) that
+ * shows on both sides of the delta, a field typed into or a switch flipped,
+ * echoes the input: the replay typed, so the value is there, whatever the
+ * step was for. Such echoes are evidence only when the delta holds nothing
+ * else; otherwise the rest of the delta must have moved, so a subscribe
+ * form typed into on a page that already read "You're subscribed" proves
+ * nothing.
  */
-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))));
+export function deltaEvidenced(delta, baselineNodes, inputTargets) {
+    if (baselineNodes === undefined)
+        return true;
+    const appeared = delta.endAnchors ?? [];
+    const gone = delta.goneAnchors ?? [];
+    const targets = new Set(inputTargets.map(identityKey));
+    const changed = new Set(appeared.map(identityKey).filter((key) => gone.some((anchor) => identityKey(anchor) === key)));
+    const echoes = (anchor) => changed.has(identityKey(anchor)) && targets.has(identityKey(anchor));
+    const outcome = [...appeared, ...gone].some((anchor) => !echoes(anchor));
+    const counted = (anchor) => !outcome || !echoes(anchor);
+    const baseline = projectAnchors(baselineNodes);
+    return (appeared.some((anchor) => counted(anchor) && !anchorIn(anchor, baseline)) ||
+        gone.some((anchor) => counted(anchor) && anchorIn(anchor, baseline)));
+}
+/** A control's key without what a step sets on it, its value and states: the same control before and after. */
+function identityKey(descriptor) {
+    const { value: _value, states: _states, ...control } = descriptor;
+    return anchorKey(control);
+}
+/**
+ * Whether some tier of a recorded anchor equals some projected node on every
+ * anchor field, and on its value and states exactly: an empty field is not
+ * the field filled in, nor an unchecked switch the switch turned on. An
+ * alert is compared by its shape (`alertShape`).
+ */
+function anchorIn(anchor, nodes) {
+    const states = statesKey(anchor.states);
+    const shape = isAlert(anchor) ? alertShape : (descriptor) => descriptor;
+    return descriptorTiers(anchor).some((tier) => nodes.some((node) => node.descriptor.value === anchor.value &&
+        statesKey(node.descriptor.states) === states &&
+        fieldsEqual(shape(tier), shape(node.descriptor), ANCHOR_FIELDS)));
+}
+/**
+ * Anchor projections per observation: a replay checks the same end screen
+ * once per poll and the start screen for every check, while the projection
+ * of a node is a pure function of the node.
+ */
+const projections = new WeakMap();
+/** Every node of an observation that can serve as an anchor, in document order. */
+function projectAnchors(nodes) {
+    const cached = projections.get(nodes);
+    if (cached !== undefined)
+        return cached;
+    const anchors = [];
+    for (const node of nodes.values()) {
+        const descriptor = anchorDescriptor(node);
+        if (descriptor === undefined)
+            continue;
+        // An alert keyed by its shape: one whose countdown ticked while the step
+        // ran stayed on screen, and is on neither side of the delta.
+        const key = anchorKey(isAlert(descriptor) ? alertShape(descriptor) : descriptor);
+        anchors.push({ descriptor, key, leaf: node.children === undefined || node.children.length === 0 });
+    }
+    projections.set(nodes, anchors);
+    return anchors;
 }
 /** One node's anchor projection, or undefined when it could identify nothing. */
-function anchorDescriptor(node, options) {
-    const described = describeTarget(node, options.redact);
+function anchorDescriptor(node) {
+    const described = describeTarget(node);
     if (described === undefined || descriptorTiers(described).length === 0)
         return undefined;
     const { selector: _selector, ...anchor } = described;
-    return anchor;
+    const states = TRACE_ANCHOR_STATES.filter((state) => node.states?.[state] === true);
+    const value = node.value === undefined || node.states?.secure === true ? '' : collapseText(node.value);
+    return {
+        ...anchor,
+        ...(value === '' ? {} : { value: bound(value, MAX_TRACE_DESCRIPTOR_CHARS) }),
+        ...(states.length === 0 ? {} : { states }),
+    };
+}
+function statesKey(states) {
+    return states === undefined ? '' : states.join(',');
 }
 /**
  * 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.
+ * fields, in fixed order, and its states. 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. The states make a control that changed state a node
+ * of the delta on both sides: the switch as it was, gone, and as it is,
+ * appeared; the value does the same for a field typed into.
  */
 function anchorKey(descriptor) {
     const tiers = descriptorTiers(descriptor);
     const loosest = tiers[tiers.length - 1] ?? descriptor;
-    return JSON.stringify(ANCHOR_FIELDS.map((field) => loosest[field]));
+    return JSON.stringify([...ANCHOR_FIELDS.map((field) => loosest[field]), descriptor.value, statesKey(descriptor.states)]);
 }
-//# sourceMappingURL=anchors.js.map

package/dist/cache/context.d.ts

@@ -8,9 +8,10 @@
  * re-records.
  */
 import type { ResolvedCacheConfig } from '../config/resolve.ts';
-import { type CacheTargetIdentity, type TraceCacheKind } from './identity.ts';
+import { type CacheAgentIdentity, type CacheTargetIdentity, type TraceCacheKind } from './identity.ts';
+import type { StoredRecordings } from './rekeyed.ts';
 import { type CacheStore } from './store.ts';
-import type { ActionTrace } from './trace.ts';
+import type { ActionTrace, TraceProvenance } from './trace.ts';
 import type { JsonValue } from '../types.ts';
 /**
  * One cache entry held back until the attempt confirms or implicates it: a
@@ -18,7 +19,9 @@ import type { JsonValue } from '../types.ts';
  * stands. A kept entry carries no payload, so the replay's expansion of it
  * (every `unique()` slot filled with this run's value) can never be written;
  * confirmed, the file keeps its bytes and `createdAt`, and a committed cache
- * directory stays clean. Unconfirmed, both kinds are evicted alike.
+ * directory stays clean, unless its provenance predates the step's
+ * occurrence fields (`recordedFor`, as stored), which the replay proved and
+ * are then written in. Unconfirmed, both kinds are evicted alike.
  */
 export type StagedTrace = {
     readonly keyHash: string;
@@ -29,34 +32,40 @@ export type StagedTrace = {
     readonly trace: ActionTrace;
 } | {
     readonly kind: 'keep';
+    readonly recordedFor: TraceProvenance;
 });
+/** One step's claimed key: its hash, and the step it names as an entry records it. */
+export interface ClaimedKey {
+    readonly keyHash: string;
+    /** The step's identity before redaction; the recorder redacts it on the way to disk. */
+    readonly step: TraceProvenance;
+}
 export interface AgentCacheContext {
     readonly mode: 'read-only' | 'read-write';
     readonly store: CacheStore;
-    /** Test and target a write is recorded for, as `e2e cache ls` prints them. */
-    readonly identity: {
-        readonly testId: string;
-        readonly targetId: string;
-    };
     /** Whether this attempt may replay; writes are governed by `mode` alone. */
     readonly replayEligible: boolean;
     /**
      * A recording that no longer replays fails its step (`REPLAY_STALE`)
      * instead of handing it to the executor, with `advice` on how to re-record
-     * it: the knobs to turn off and where the entry lives.
+     * it: the knobs to turn off and where the entry lives. `recordings`, set
+     * when the store can be listed, finds the recording of a step whose key
+     * changed under it, which is stale too rather than missing.
      */
     readonly strict: false | {
         readonly advice: string;
+        readonly recordings?: StoredRecordings;
     };
     /**
-     * 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.
+     * Claims one step's key. Not a pure derivation: each claim advances
+     * the per-attempt occurrence index for its agent and 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;
+    claimKey(kind: TraceCacheKind, instruction: string, params: Readonly<Record<string, JsonValue>> | undefined, agent: CacheAgentIdentity): ClaimedKey;
     /**
      * 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
@@ -93,7 +102,7 @@ export interface AttemptSettlement {
  * for an interrupted attempt: interruption implicates nothing, so it writes
  * nothing and evicts nothing. An entry a step replayed whole is staged too,
  * so the same rule evicts it when nothing confirmed it; when something did,
- * it is left exactly as it was found.
+ * it is left exactly as it was found, but for provenance it lacked.
  */
 export declare function flushStagedTraces(context: AgentCacheContext, settlement: AttemptSettlement): Promise<void>;
 /**
@@ -110,5 +119,6 @@ export declare function createAgentCacheContext(options: {
     readonly testId: string;
     readonly target: CacheTargetIdentity;
     readonly attemptIndex: number;
+    /** The file store's listing under `cache.strict`, shared by the attempts of one worker and target (`storedRecordingsFor`). */
+    readonly recordings?: StoredRecordings | undefined;
 }): AgentCacheContext | undefined;
-//# sourceMappingURL=context.d.ts.map

package/dist/cache/context.js

@@ -38,6 +38,18 @@ function flowOf(trace) {
         }),
     });
 }
+/**
+ * Writes the step's full provenance into a kept entry recorded before the
+ * occurrence fields were, leaving every other entry untouched. Its replay
+ * proved which step it belongs to, and `cache.strict` matches only entries
+ * that say so exactly (`rekeyed.ts`).
+ */
+async function completeProvenance(store, keyHash, recordedFor) {
+    const existing = await store.read(keyHash);
+    if (existing.status !== 'hit' || existing.entry.payload.recordedFor?.callIndex !== undefined)
+        return;
+    await store.write(keyHash, { ...existing.entry.payload, recordedFor });
+}
 /**
  * Settles the attempt's staged trace writes. A staged trace is confirmed only
  * when a verification step — a deterministic assertion or an agent judgment
@@ -54,7 +66,7 @@ function flowOf(trace) {
  * for an interrupted attempt: interruption implicates nothing, so it writes
  * nothing and evicts nothing. An entry a step replayed whole is staged too,
  * so the same rule evicts it when nothing confirmed it; when something did,
- * it is left exactly as it was found.
+ * it is left exactly as it was found, but for provenance it lacked.
  */
 export async function flushStagedTraces(context, settlement) {
     const staged = context.staged.splice(0);
@@ -68,7 +80,11 @@ export async function flushStagedTraces(context, settlement) {
                     await context.store.delete?.(entry.keyHash);
                 continue;
             }
-            if (entry.kind === 'keep' || (await holdsSameFlow(context.store, entry.keyHash, entry.trace)))
+            if (entry.kind === 'keep') {
+                await completeProvenance(context.store, entry.keyHash, entry.recordedFor);
+                continue;
+            }
+            if (await holdsSameFlow(context.store, entry.keyHash, entry.trace))
                 continue;
             await context.store.write(entry.keyHash, entry.trace);
         }
@@ -95,23 +111,49 @@ export function createAgentCacheContext(options) {
             writable: mode === 'read-write',
         });
     const project = projectIdentity(options.projectId);
-    const nextCallIndex = createCallIndexer();
+    // One occurrence count per agent: the agent is part of the key, so another
+    // agent's call of the same instruction must not renumber this one's.
+    const indexers = new Map();
+    const nextCallIndex = (agent, signature) => {
+        // Folded like the key folds it (`buildTraceCacheKey`): no context is the empty one.
+        const agentKey = canonicalJson([agent.name, agent.context ?? '']);
+        const indexer = indexers.get(agentKey) ?? createCallIndexer();
+        indexers.set(agentKey, indexer);
+        return indexer(signature);
+    };
     return {
         mode,
         store,
-        identity: { testId: options.testId, targetId: options.target.targetId },
         replayEligible: options.attemptIndex === 0,
-        strict: options.cache.strict === false ? false : { advice: staleAdvice(options.cache, options.cache.strict, options.projectRoot) },
-        claimKeyHash: (kind, instruction, params) => {
+        strict: options.cache.strict === false
+            ? false
+            : {
+                advice: staleAdvice(options.cache, options.cache.strict, options.projectRoot),
+                ...(options.recordings === undefined ? {} : { recordings: options.recordings }),
+            },
+        claimKey: (kind, instruction, params, agent) => {
             const signature = traceCallSignature(kind, instruction, params);
-            return traceCacheKeyHash(buildTraceCacheKey({
+            const callIndex = nextCallIndex(agent, signature);
+            const keyHash = traceCacheKeyHash(buildTraceCacheKey({
                 project,
                 testId: options.testId,
                 target: options.target,
                 signature,
-                callIndex: nextCallIndex(signature),
+                callIndex,
+                agent,
                 policyVersion: REPLAY_POLICY_VERSION,
             }));
+            return {
+                keyHash,
+                step: {
+                    testId: options.testId,
+                    targetId: options.target.targetId,
+                    instructionDigest: signature.instructionDigest,
+                    paramsDigest: signature.paramsDigest,
+                    callIndex,
+                    agent: agent.name,
+                },
+            };
         },
         staged: [],
     };
@@ -133,4 +175,3 @@ function staleAdvice(cache, source, projectRoot) {
     const where = relative === '' || relative.startsWith('..') || path.isAbsolute(relative) ? cache.dir : relative;
     return `${run} and commit the changed entry under ${where.split(path.sep).join('/')}`;
 }
-//# sourceMappingURL=context.js.map

package/dist/cache/decide.d.ts

@@ -31,8 +31,7 @@ export type TraceReplayDecision = {
  * not open with a navigate carries a start precondition: the app must be on
  * the screen where the recording began, or the recorded actions would run
  * against a different screen than they were proven on. The screen is its
- * route (`routeOf`), not its URL; a route the path leaves undecided is a
- * miss, since nothing recorded at the start is specific enough to settle it.
+ * route (`cache/route.ts`), not its URL: the same origin, path, and query,
+ * whatever the ids in them.
  */
 export declare function decideTraceReplay(entry: TraceEntry, currentPath: string | undefined): TraceReplayDecision;
-//# sourceMappingURL=decide.d.ts.map

package/dist/cache/decide.js

@@ -7,7 +7,7 @@
  * decision takes an already-trusted entry and answers only the questions the
  * entry alone cannot: is it whole, and is the app where the recording began?
  */
-import { compareRoutes, routeOf } from './route.js';
+import { sameRoute } from './route.js';
 /**
  * Whether a trace establishes its own starting point by navigating first.
  * Such a trace needs no start-path precondition — and a trace with neither
@@ -21,8 +21,8 @@ export function opensWithNavigate(trace) {
  * not open with a navigate carries a start precondition: the app must be on
  * the screen where the recording began, or the recorded actions would run
  * against a different screen than they were proven on. The screen is its
- * route (`routeOf`), not its URL; a route the path leaves undecided is a
- * miss, since nothing recorded at the start is specific enough to settle it.
+ * route (`cache/route.ts`), not its URL: the same origin, path, and query,
+ * whatever the ids in them.
  */
 export function decideTraceReplay(entry, currentPath) {
     const trace = entry.payload;
@@ -32,8 +32,5 @@ export function decideTraceReplay(entry, currentPath) {
         return { action: 'replay' };
     if (trace.startPath === undefined || currentPath === undefined)
         return { action: 'miss', reason: 'wrong-context' };
-    return compareRoutes(routeOf(trace.startPath), routeOf(currentPath)) === 'same'
-        ? { action: 'replay' }
-        : { action: 'miss', reason: 'wrong-context' };
+    return sameRoute(trace.startPath, currentPath) ? { action: 'replay' } : { action: 'miss', reason: 'wrong-context' };
 }
-//# sourceMappingURL=decide.js.map

package/dist/cache/identity.d.ts

@@ -7,10 +7,13 @@
  * contributes only its stable name and purpose, exactly as the executor sees
  * it in the projected params.
  *
- * Executor identity is deliberately absent (OQ10's conservative default):
- * entries are shared across roster members and carry their producer as
- * provenance on the entry, so a future ReplayPolicy can reject foreign traces
- * without a re-key.
+ * The agent a step runs with is part of the key: its configured name, since
+ * two agents of one test (`agent: ['buyer', 'admin']`) act as different
+ * people, and a digest of the context it reads, since a test's
+ * `agentContext` decides what the step does. The context is digested after
+ * redaction, so a registered secret in it contributes its name only. The
+ * executor that produced a trace stays provenance on the entry: the agent's
+ * name already keeps two configured agents apart.
  */
 import type { JsonValue } from '../types.ts';
 import { TRACE_SCHEMA_VERSION } from './trace.ts';
@@ -37,8 +40,18 @@ export interface TraceCacheKey {
     readonly instructionDigest: string;
     readonly paramsDigest: string;
     readonly appIdentity: string;
+    /** Name of the configured agent the step ran with. */
+    readonly agent: string;
+    /** SHA-256 of the agent's redacted context (its `context` then the test's `agentContext`), or of the empty string. */
+    readonly agentContextDigest: string;
     readonly policyVersion: string;
 }
+/** The agent a step runs with, as the key sees it. */
+export interface CacheAgentIdentity {
+    readonly name: string;
+    /** The context the agent reads, already redacted. */
+    readonly context: string | undefined;
+}
 /** Identity of the target/engine/app a trace was recorded against. */
 export interface CacheTargetIdentity {
     readonly targetId: string;
@@ -106,8 +119,8 @@ export declare function buildTraceCacheKey(parts: {
     readonly target: CacheTargetIdentity;
     readonly signature: TraceCallSignature;
     readonly callIndex: number;
+    readonly agent: CacheAgentIdentity;
     readonly policyVersion: string;
 }): TraceCacheKey;
 /** SHA-256/JCS of one key, used as both the entry digest and its file name. */
 export declare function traceCacheKeyHash(key: TraceCacheKey): string;
-//# sourceMappingURL=identity.d.ts.map