e2e 0.15.2 → 0.17.0

package/dist/cache/identity.js

@@ -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 { canonicalDigest, sha256Hex } from '../internal/ids.js';
 import { TRACE_SCHEMA_VERSION } from './trace.js';
@@ -99,6 +102,8 @@ export function buildTraceCacheKey(parts) {
         instructionDigest: parts.signature.instructionDigest,
         paramsDigest: parts.signature.paramsDigest,
         appIdentity: parts.target.appIdentity,
+        agent: parts.agent.name,
+        agentContextDigest: sha256Hex(parts.agent.context ?? ''),
         policyVersion: parts.policyVersion,
     };
 }
@@ -106,4 +111,3 @@ export function buildTraceCacheKey(parts) {
 export function traceCacheKeyHash(key) {
     return canonicalDigest(key);
 }
-//# sourceMappingURL=identity.js.map

package/dist/cache/recorder.d.ts

@@ -20,12 +20,15 @@ import { type ActionTrace, type DerivedReason, type TraceProvenance, type TraceT
 export interface TraceRecorderOptions {
     /** The run's secret redactor; applied to every recorded string. */
     readonly redact: (text: string) => string;
+    /** `redact` for a field cut at its observed limit (`SecretLedger.redactCut`). */
+    readonly redactCut: (text: string) => string;
     readonly maxActions?: number;
 }
 export declare class TraceRecorder {
     private readonly actions;
     private truncated;
     private readonly redact;
+    private readonly redactCut;
     private readonly maxActions;
     constructor(options: TraceRecorderOptions);
     private lastActionAt;
@@ -61,8 +64,10 @@ export declare class TraceRecorder {
         readonly summary: string;
         readonly startPath?: string;
         readonly endPath?: string;
-        /** Already projected and capped by `describeAnchors`; recorded as given. */
+        /** Already projected and capped by `describeDelta`; recorded as given. */
         readonly endAnchors?: readonly TraceTargetDescriptor[];
+        /** The other side of the same delta: what was on screen at the start and gone at the end. */
+        readonly goneAnchors?: readonly TraceTargetDescriptor[];
         /** How long the recorded run took to reach its end state, plus margin. */
         readonly endWaitMs?: number;
     }): ActionTrace | undefined;
@@ -84,4 +89,12 @@ export declare class TraceRecorder {
     private verbatim;
     private push;
 }
-//# sourceMappingURL=recorder.d.ts.map
+/**
+ * Provenance as an entry stores it. Harness identity rather than screen
+ * content, so the redactor here is belt and braces: a title or agent name
+ * that happened to carry a registered secret is masked like any other
+ * recorded string, and provenance is not replay input, so masking it poisons
+ * nothing. A step compares its own provenance in this form to the entries
+ * the store holds.
+ */
+export declare function recordedProvenance(provenance: TraceProvenance, redact: (text: string) => string): TraceProvenance;

package/dist/cache/recorder.js

@@ -24,9 +24,11 @@ export class TraceRecorder {
     actions = [];
     truncated = false;
     redact;
+    redactCut;
     maxActions;
     constructor(options) {
         this.redact = options.redact;
+        this.redactCut = options.redactCut;
         this.maxActions = Math.min(options.maxActions ?? MAX_TRACE_ACTIONS, MAX_TRACE_ACTIONS);
     }
     lastActionAt;
@@ -40,7 +42,7 @@ export class TraceRecorder {
     }
     /** Records one committed grammar action. */
     record(action) {
-        this.push(this.toRecorded(action, describeAction(action, this.redact)));
+        this.push(this.toRecorded(action, describeAction(action, { redact: this.redact, redactCut: this.redactCut })));
         this.lastActionAt = Date.now();
     }
     /**
@@ -69,9 +71,10 @@ export class TraceRecorder {
         if (this.actions.length === 0)
             return undefined;
         const summary = bound(this.redact(conclusion.summary), MAX_TRACE_SUMMARY_CHARS);
-        // Anchors are replay preconditions, so they follow the input rule: a path
-        // the redactor alters carried a secret (a token in a query string) and
-        // the trace is marked non-replayable rather than storing it verbatim.
+        // Locations are replay preconditions, so they follow the input rule: a
+        // path the redactor alters carried a secret (a token in a query string),
+        // and one too long to keep whole cannot be compared, so either marks the
+        // trace non-replayable rather than storing it bent.
         const startPath = this.anchorPath(conclusion.startPath);
         const endPath = this.anchorPath(conclusion.endPath);
         return {
@@ -80,21 +83,16 @@ export class TraceRecorder {
                 name: conclusion.executor.name,
                 ...(conclusion.executor.version === undefined ? {} : { version: conclusion.executor.version }),
             },
-            recordedFor: {
-                // Harness identity rather than screen content, so the redactor here is
-                // belt and braces: a title that happened to carry a registered secret
-                // is masked like any other recorded string, and provenance is not
-                // replay input, so masking it poisons nothing.
-                testId: bound(this.redact(conclusion.recordedFor.testId), MAX_TRACE_DESCRIPTOR_CHARS),
-                targetId: bound(this.redact(conclusion.recordedFor.targetId), MAX_TRACE_DESCRIPTOR_CHARS),
-                instructionDigest: conclusion.recordedFor.instructionDigest,
-            },
+            recordedFor: recordedProvenance(conclusion.recordedFor, this.redact),
             summary: summary.trim() === '' ? 'step passed' : summary,
             ...(startPath === undefined ? {} : { startPath }),
             ...(endPath === undefined ? {} : { endPath }),
             ...(conclusion.endAnchors === undefined || conclusion.endAnchors.length === 0
                 ? {}
                 : { endAnchors: conclusion.endAnchors }),
+            ...(conclusion.goneAnchors === undefined || conclusion.goneAnchors.length === 0
+                ? {}
+                : { goneAnchors: conclusion.goneAnchors }),
             ...(conclusion.endWaitMs === undefined
                 ? {}
                 : { endWaitMs: Math.min(MAX_TRACE_END_WAIT_MS, Math.max(0, Math.round(conclusion.endWaitMs))) }),
@@ -102,12 +100,7 @@ export class TraceRecorder {
         };
     }
     anchorPath(value) {
-        if (value === undefined || value === '')
-            return undefined;
-        const redacted = this.redact(value);
-        if (redacted !== value)
-            this.truncated = true;
-        return bound(redacted, MAX_TRACE_DESCRIPTOR_CHARS);
+        return value === undefined || value === '' ? undefined : this.verbatim(value);
     }
     /**
      * Builds the stored variant for one action. The descriptor and the prose
@@ -117,13 +110,15 @@ export class TraceRecorder {
      * kept whole.
      */
     toRecorded(action, { target, summary, destination }) {
-        // A targeted commit whose node yields no durable descriptor cannot be
-        // re-found; the trace stays honest by poisoning instead of guessing.
+        // A targeted commit whose node yields no descriptor a replay could
+        // re-find it by (none at all, or an unnamed twin with no named row to
+        // tell it apart) cannot replay; the trace stays honest by poisoning
+        // instead of guessing.
         const require = (descriptor) => {
-            if (descriptor !== undefined)
+            if (descriptor !== undefined && isRelocatableDescriptor(descriptor))
                 return descriptor;
             this.truncated = true;
-            return { role: 'unknown' };
+            return descriptor ?? { role: 'unknown' };
         };
         const requireTarget = () => require(target);
         if (isNodeAction(action))
@@ -240,4 +235,21 @@ function sameTarget(a, b) {
         a.position?.index === b.position?.index &&
         a.position?.of === b.position?.of);
 }
-//# sourceMappingURL=recorder.js.map
+/**
+ * Provenance as an entry stores it. Harness identity rather than screen
+ * content, so the redactor here is belt and braces: a title or agent name
+ * that happened to carry a registered secret is masked like any other
+ * recorded string, and provenance is not replay input, so masking it poisons
+ * nothing. A step compares its own provenance in this form to the entries
+ * the store holds.
+ */
+export function recordedProvenance(provenance, redact) {
+    return {
+        testId: bound(redact(provenance.testId), MAX_TRACE_DESCRIPTOR_CHARS),
+        targetId: bound(redact(provenance.targetId), MAX_TRACE_DESCRIPTOR_CHARS),
+        instructionDigest: provenance.instructionDigest,
+        ...(provenance.paramsDigest === undefined ? {} : { paramsDigest: provenance.paramsDigest }),
+        ...(provenance.callIndex === undefined ? {} : { callIndex: provenance.callIndex }),
+        ...(provenance.agent === undefined ? {} : { agent: bound(redact(provenance.agent), MAX_TRACE_DESCRIPTOR_CHARS) }),
+    };
+}

package/dist/cache/rekeyed.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Recordings stored under a key the runner no longer derives.
+ *
+ * A key names everything that can change replay (`identity.ts`), so a new
+ * replay policy, an engine minor, or an agent's context changing turns every
+ * entry recorded before into a lookup miss, the same `no-entry` as a step
+ * that was never recorded. `cache.strict` lets a never-recorded step run
+ * live, so without this it would let a whole committed cache go quietly
+ * unused. The entries say which step they were recorded for
+ * (`TraceProvenance`), and a step whose own key misses while the store holds
+ * a recording made for exactly that step is stale, not new.
+ *
+ * Only the file store can be listed. The listing is read once per worker
+ * and target, on the first strict miss that asks, and kept: every entry
+ * written since has a key the run derives, so it is a hit rather than a
+ * candidate here.
+ */
+import type { ResolvedCacheConfig } from '../config/resolve.ts';
+import { FileCacheStore } from './store.ts';
+import type { TraceProvenance } from './trace.ts';
+export declare class StoredRecordings {
+    private readonly store;
+    /** Key hashes by `stepKey` of the step each entry was recorded for. */
+    private listing;
+    constructor(store: FileCacheStore);
+    /**
+     * The key hash of an entry recorded for `step` under a key other than
+     * `keyHash`, or undefined when there is none or the store cannot be
+     * listed. `step` is in the form an entry stores it (`recordedProvenance`).
+     * Only an entry that records the whole step counts: one written before the
+     * params, occurrence, and agent were recorded could belong to another call
+     * of the same instruction, and a read-write run that replays it completes
+     * it (`flushStagedTraces`). A truncated entry never replays under any key,
+     * so it is never the reason a step is stale.
+     */
+    underAnotherKey(keyHash: string, step: TraceProvenance): Promise<string | undefined>;
+    /** Every replayable entry that records its whole step, by `stepKey`. */
+    private list;
+}
+/**
+ * The listing `cache.strict` checks a run's misses against, for the file
+ * store only. Undefined when strict is off, the cache is off, or a custom
+ * `cache.store` replaced the file store, which `CacheStore` gives no way to
+ * list.
+ */
+export declare function storedRecordingsFor(cache: ResolvedCacheConfig): StoredRecordings | undefined;

package/dist/cache/rekeyed.js

@@ -0,0 +1,89 @@
+/**
+ * Recordings stored under a key the runner no longer derives.
+ *
+ * A key names everything that can change replay (`identity.ts`), so a new
+ * replay policy, an engine minor, or an agent's context changing turns every
+ * entry recorded before into a lookup miss, the same `no-entry` as a step
+ * that was never recorded. `cache.strict` lets a never-recorded step run
+ * live, so without this it would let a whole committed cache go quietly
+ * unused. The entries say which step they were recorded for
+ * (`TraceProvenance`), and a step whose own key misses while the store holds
+ * a recording made for exactly that step is stale, not new.
+ *
+ * Only the file store can be listed. The listing is read once per worker
+ * and target, on the first strict miss that asks, and kept: every entry
+ * written since has a key the run derives, so it is a hit rather than a
+ * candidate here.
+ */
+import { FileCacheStore, MAX_CACHE_WIRE_BYTES } from './store.js';
+export class StoredRecordings {
+    store;
+    /** Key hashes by `stepKey` of the step each entry was recorded for. */
+    listing;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * The key hash of an entry recorded for `step` under a key other than
+     * `keyHash`, or undefined when there is none or the store cannot be
+     * listed. `step` is in the form an entry stores it (`recordedProvenance`).
+     * Only an entry that records the whole step counts: one written before the
+     * params, occurrence, and agent were recorded could belong to another call
+     * of the same instruction, and a read-write run that replays it completes
+     * it (`flushStagedTraces`). A truncated entry never replays under any key,
+     * so it is never the reason a step is stale.
+     */
+    async underAnotherKey(keyHash, step) {
+        const key = stepKey(step);
+        if (key === undefined)
+            return undefined;
+        let listing;
+        try {
+            this.listing ??= this.list();
+            listing = await this.listing;
+        }
+        catch {
+            return undefined;
+        }
+        for (const candidate of listing.get(key) ?? []) {
+            if (candidate === keyHash)
+                continue;
+            // Listed once: an entry evicted since is no evidence.
+            const read = await this.store.read(candidate).catch(() => undefined);
+            if (read?.status === 'hit')
+                return candidate;
+        }
+        return undefined;
+    }
+    /** Every replayable entry that records its whole step, by `stepKey`. */
+    async list() {
+        const steps = new Map();
+        for (const keyHash of await this.store.keyHashes()) {
+            const read = await this.store.read(keyHash);
+            if (read.status !== 'hit' || read.entry.payload.truncated === true)
+                continue;
+            const key = read.entry.payload.recordedFor === undefined ? undefined : stepKey(read.entry.payload.recordedFor);
+            if (key !== undefined)
+                steps.set(key, [...(steps.get(key) ?? []), keyHash]);
+        }
+        return steps;
+    }
+}
+/**
+ * The listing `cache.strict` checks a run's misses against, for the file
+ * store only. Undefined when strict is off, the cache is off, or a custom
+ * `cache.store` replaced the file store, which `CacheStore` gives no way to
+ * list.
+ */
+export function storedRecordingsFor(cache) {
+    if (cache.strict === false || cache.mode === 'off' || cache.store !== undefined)
+        return undefined;
+    return new StoredRecordings(new FileCacheStore({ directory: cache.dir, maxBytes: MAX_CACHE_WIRE_BYTES, writable: false }));
+}
+/** The whole step as one map key, or undefined when the provenance does not record all of it. */
+function stepKey(step) {
+    const { testId, targetId, instructionDigest, paramsDigest, callIndex, agent } = step;
+    if (paramsDigest === undefined || callIndex === undefined || agent === undefined)
+        return undefined;
+    return JSON.stringify([testId, targetId, instructionDigest, paramsDigest, callIndex, agent]);
+}

package/dist/cache/relocate.d.ts

@@ -14,7 +14,7 @@
  * means — is exported so end anchors (`anchors.ts`) are checked by the same
  * rules and can never drift from relocation.
  */
-import type { SemanticNode } from '../engine/surface.ts';
+import type { RedactedNode } from '../agent/observation.ts';
 import type { TracePosition, TraceTargetDescriptor } from './trace.ts';
 /**
  * Version of the replay/relocation policy, part of every cache key. Bumping
@@ -22,7 +22,7 @@ import type { TracePosition, TraceTargetDescriptor } from './trace.ts';
  * change, because an entry recorded under different rules could relocate to a
  * different node.
  */
-export declare const REPLAY_POLICY_VERSION = "conservative/5";
+export declare 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
@@ -45,14 +45,16 @@ export type RelocationResult = {
     readonly candidates: readonly string[];
 };
 export type DescriptorField = keyof TraceTargetDescriptor;
-export interface DescriptorMatchOptions {
-    readonly redact: (text: string) => string;
-}
-/** A node's descriptor projection alongside its per-observation id. */
-export interface DescribedNode {
-    readonly id: string;
-    readonly descriptor: TraceTargetDescriptor;
-}
+/**
+ * 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 declare function isRelocatableDescriptor(descriptor: TraceTargetDescriptor): boolean;
 /**
  * The tiers a recorded descriptor is matched in, strictest first:
@@ -70,8 +72,6 @@ export declare function isRelocatableDescriptor(descriptor: TraceTargetDescripto
 export declare function descriptorTiers(descriptor: TraceTargetDescriptor): readonly TraceTargetDescriptor[];
 /** Every listed field the recording captured must be present and equal on the candidate. */
 export declare function fieldsEqual(recorded: TraceTargetDescriptor, candidate: TraceTargetDescriptor, fields: readonly DescriptorField[]): boolean;
-/** Projects every node of an observation the way the recorder described its targets. */
-export declare function describeNodes(nodes: ReadonlyMap<string, SemanticNode>, options: DescriptorMatchOptions): readonly DescribedNode[];
 /**
  * Relocates one descriptor against the nodes of a fresh observation, tier by
  * tier (`descriptorTiers`), each exactly-one-or-diverge. Ambiguity at any
@@ -81,12 +81,11 @@ export declare function describeNodes(nodes: ReadonlyMap<string, SemanticNode>,
  * 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 declare function relocateDescriptor(descriptor: TraceTargetDescriptor, nodes: ReadonlyMap<string, SemanticNode>, options: DescriptorMatchOptions): RelocationResult;
+export declare function relocateDescriptor(descriptor: TraceTargetDescriptor, nodes: ReadonlyMap<string, RedactedNode>): RelocationResult;
 /**
  * Where `node` stands among the controls its own description matches on the
  * screen it was acted on, or undefined when the description already names it
  * 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 declare function describePosition(node: SemanticNode, within: string | undefined, nodes: ReadonlyMap<string, SemanticNode>, options: DescriptorMatchOptions): TracePosition | undefined;
-//# sourceMappingURL=relocate.d.ts.map
+export declare function describePosition(node: RedactedNode, within: string | undefined, nodes: ReadonlyMap<string, RedactedNode>): TracePosition | undefined;

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,10 +200,9 @@ 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);
     return index === -1 ? undefined : { index, of: ids.length };
 }
-//# sourceMappingURL=relocate.js.map

package/dist/cache/route.d.ts

@@ -4,44 +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;
-//# sourceMappingURL=route.d.ts.map
+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;