@e2edev/e2e 0.2.0

package/dist/cache/decide.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The per-step replay decision (RFC0001 layer 3, cache-in decision).
+ *
+ * Pure and fail-to-miss: every reason a validated entry cannot replay is a
+ * miss that dispatches the live executor, never an error and never a step
+ * failure. Validation has one owner — the store (`readTraceEntry`) — so this
+ * 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 type { ActionTrace, TraceEntry } from './trace.ts';
+/**
+ * Whether two recorded locations are the same page. Pathname only, at both
+ * ends of a trace: a volatile query string (`?utm=…`, a cache-busting stamp)
+ * must not break zero-turn, and the relocated targets and end anchors — not
+ * the query — are what prove the screen is the one the flow was proven on.
+ */
+export declare function samePathname(a: string, b: string): boolean;
+/**
+ * Whether a trace establishes its own starting point by navigating first.
+ * Such a trace needs no start-path precondition — and a trace with neither
+ * anchor can never replay at all, so it is not worth writing.
+ */
+export declare function opensWithNavigate(trace: ActionTrace): boolean;
+/**
+ * The full miss vocabulary of the report. `no-entry` and `invalid-entry` are
+ * assigned by the store-read path; this decision produces the other two.
+ */
+export type TraceReplayMissReason = 'no-entry' | 'invalid-entry' | 'truncated' | 'wrong-context';
+export type TraceReplayDecision = {
+    readonly action: 'replay';
+} | {
+    readonly action: 'miss';
+    readonly reason: 'truncated' | 'wrong-context';
+};
+/**
+ * Decides whether one entry replays for the current step. A trace that does
+ * not open with a navigate carries a start-path precondition: the app must
+ * be on the page where the recording began, or the recorded actions would
+ * run against a different screen than they were proven on.
+ */
+export declare function decideTraceReplay(entry: TraceEntry, currentPath: string | undefined): TraceReplayDecision;
+//# sourceMappingURL=decide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/cache/decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1D;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,eAAe,GAAG,WAAW,GAAG,eAAe,CAAC;AAEjG,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAAA;CAAE,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,mBAAmB,CASrB"}

package/dist/cache/decide.js

@@ -0,0 +1,47 @@
+/**
+ * The per-step replay decision (RFC0001 layer 3, cache-in decision).
+ *
+ * Pure and fail-to-miss: every reason a validated entry cannot replay is a
+ * miss that dispatches the live executor, never an error and never a step
+ * failure. Validation has one owner — the store (`readTraceEntry`) — so this
+ * 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?
+ */
+/**
+ * Whether two recorded locations are the same page. Pathname only, at both
+ * ends of a trace: a volatile query string (`?utm=…`, a cache-busting stamp)
+ * must not break zero-turn, and the relocated targets and end anchors — not
+ * the query — are what prove the screen is the one the flow was proven on.
+ */
+export function samePathname(a, b) {
+    return pathnameOf(a) === pathnameOf(b);
+}
+function pathnameOf(path) {
+    return path.split('?')[0] ?? path;
+}
+/**
+ * Whether a trace establishes its own starting point by navigating first.
+ * Such a trace needs no start-path precondition — and a trace with neither
+ * anchor can never replay at all, so it is not worth writing.
+ */
+export function opensWithNavigate(trace) {
+    return trace.actions.find((action) => action.name !== 'tool')?.name === 'navigate';
+}
+/**
+ * Decides whether one entry replays for the current step. A trace that does
+ * not open with a navigate carries a start-path precondition: the app must
+ * be on the page where the recording began, or the recorded actions would
+ * run against a different screen than they were proven on.
+ */
+export function decideTraceReplay(entry, currentPath) {
+    if (entry.payload.truncated === true)
+        return { action: 'miss', reason: 'truncated' };
+    if (!opensWithNavigate(entry.payload)) {
+        const startPath = entry.payload.startPath;
+        if (startPath === undefined || currentPath === undefined || !samePathname(startPath, currentPath)) {
+            return { action: 'miss', reason: 'wrong-context' };
+        }
+    }
+    return { action: 'replay' };
+}
+//# sourceMappingURL=decide.js.map

package/dist/cache/decide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.js","sourceRoot":"","sources":["../../src/cache/decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,OAAO,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAkB;IAClD,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,IAAI,KAAK,UAAU,CAAC;AACrF,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAiB,EACjB,WAA+B;IAE/B,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACrF,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QAC1C,IAAI,SAAS,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,CAAC;YAClG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC"}

package/dist/cache/identity.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Trace cache key identity (RFC0001 layer 3, cache-in decision).
+ *
+ * A key names the exact context a trace was recorded in. Every field that can
+ * change replay behavior is part of the key, so a stale entry can only ever be
+ * a miss rather than a wrong answer. Secret values never enter a key: a secret
+ * 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.
+ */
+import type { JsonValue } from '../types.ts';
+import { TRACE_SCHEMA_VERSION } from './trace.ts';
+/**
+ * Step kinds the trace cache admits. Only `act` today: an assert must not
+ * change state, so its trace would be action-free, and judgments are made
+ * fresh per run by normative rule (spec 10).
+ */
+export type TraceCacheKind = 'act';
+export interface TraceCacheKey {
+    readonly specVersion: '0.1';
+    readonly cacheSchema: typeof TRACE_SCHEMA_VERSION;
+    /** SHA-256 of the resolved `projectId`. */
+    readonly project: string;
+    readonly testId: string;
+    readonly targetId: string;
+    readonly platform: string;
+    readonly backendName: string;
+    readonly backendVersion: string;
+    readonly backendSpiVersion: number;
+    readonly kind: TraceCacheKind;
+    /** Zero-based occurrence of this signature within the attempt. */
+    readonly callIndex: number;
+    readonly instructionDigest: string;
+    readonly paramsDigest: string;
+    readonly appIdentity: string;
+    readonly policyVersion: string;
+}
+/** Identity of the target/backend/app a trace was recorded against. */
+export interface CacheTargetIdentity {
+    readonly targetId: string;
+    readonly platform: string;
+    readonly backendName: string;
+    readonly backendVersion: string;
+    readonly spiVersion: number;
+    readonly appIdentity: string;
+}
+/**
+ * Reduces a backend version to the part that can change how a semantic node
+ * resolves: `1.61.1` becomes `1.61`. Keying on the exact version cold-started
+ * every entry on a patch release for no benefit; a minor might change matching,
+ * so that part is kept. A version that is not `major.minor[.patch]` is used
+ * unchanged rather than guessed at.
+ */
+export declare function backendCompatibilityVersion(version: string): string;
+/**
+ * Normalizes one instruction before digesting it: CRLF/CR become LF, the text
+ * is NFC-normalized, and leading/trailing Unicode whitespace is trimmed.
+ * Interior whitespace is preserved, because it can be semantically meaningful.
+ */
+export declare function normalizeInstruction(instruction: string): string;
+/** SHA-256 of the normalized instruction. */
+export declare function instructionDigest(instruction: string): string;
+/**
+ * SHA-256/JCS of the projected (secret-free) call parameters. A missing params
+ * object digests as the empty object, so `act(x)` and `act(x, {})` share one
+ * entry.
+ */
+export declare function paramsDigest(params: Readonly<Record<string, JsonValue>> | undefined): string;
+/** SHA-256 of the resolved project identity. */
+export declare function projectIdentity(projectId: string): string;
+/**
+ * What a step asks for, independent of where it sits in the test: the kind
+ * plus the digests of its instruction and projected parameters.
+ *
+ * Two steps sharing a signature are the same request, so this is the scope the
+ * occurrence index counts within. Scoping it any wider — counting every agent
+ * step in the test — would make an unrelated step appearing or disappearing
+ * renumber every entry after it, which is exactly what a conditional flow like
+ * an optional cookie dialog does on a real site.
+ */
+export interface TraceCallSignature {
+    readonly kind: TraceCacheKind;
+    readonly instructionDigest: string;
+    readonly paramsDigest: string;
+}
+/** Builds one signature by digesting the instruction and projected parameters. */
+export declare function traceCallSignature(kind: TraceCacheKind, instruction: string, params: Readonly<Record<string, JsonValue>> | undefined): TraceCallSignature;
+/**
+ * Counts occurrences of each call signature within one attempt, returning the
+ * zero-based index of each step among its own repeats. Per signature rather
+ * than per attempt on purpose: only a genuine repeat of the same request
+ * advances the number.
+ */
+export declare function createCallIndexer(): (signature: TraceCallSignature) => number;
+/**
+ * Assembles one key. Field order is irrelevant to the digest, since JCS sorts
+ * keys, but the explicit shape keeps every required field accounted for.
+ */
+export declare function buildTraceCacheKey(parts: {
+    readonly project: string;
+    readonly testId: string;
+    readonly target: CacheTargetIdentity;
+    readonly signature: TraceCallSignature;
+    readonly callIndex: number;
+    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

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

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

package/dist/cache/identity.js

@@ -0,0 +1,109 @@
+/**
+ * Trace cache key identity (RFC0001 layer 3, cache-in decision).
+ *
+ * A key names the exact context a trace was recorded in. Every field that can
+ * change replay behavior is part of the key, so a stale entry can only ever be
+ * a miss rather than a wrong answer. Secret values never enter a key: a secret
+ * 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.
+ */
+import { canonicalDigest, sha256Hex } from '../internal/ids.js';
+import { TRACE_SCHEMA_VERSION } from './trace.js';
+/**
+ * Reduces a backend version to the part that can change how a semantic node
+ * resolves: `1.61.1` becomes `1.61`. Keying on the exact version cold-started
+ * every entry on a patch release for no benefit; a minor might change matching,
+ * so that part is kept. A version that is not `major.minor[.patch]` is used
+ * unchanged rather than guessed at.
+ */
+export function backendCompatibilityVersion(version) {
+    const match = /^(\d+)\.(\d+)(?:[.\-+].*)?$/u.exec(version);
+    return match === null ? version : `${match[1]}.${match[2]}`;
+}
+/**
+ * Normalizes one instruction before digesting it: CRLF/CR become LF, the text
+ * is NFC-normalized, and leading/trailing Unicode whitespace is trimmed.
+ * Interior whitespace is preserved, because it can be semantically meaningful.
+ */
+export function normalizeInstruction(instruction) {
+    return instruction.replace(/\r\n?/gu, '\n').normalize('NFC').trim();
+}
+/** SHA-256 of the normalized instruction. */
+export function instructionDigest(instruction) {
+    return sha256Hex(normalizeInstruction(instruction));
+}
+/**
+ * SHA-256/JCS of the projected (secret-free) call parameters. A missing params
+ * object digests as the empty object, so `act(x)` and `act(x, {})` share one
+ * entry.
+ */
+export function paramsDigest(params) {
+    return canonicalDigest(params ?? {});
+}
+/** SHA-256 of the resolved project identity. */
+export function projectIdentity(projectId) {
+    return sha256Hex(projectId);
+}
+/** Builds one signature by digesting the instruction and projected parameters. */
+export function traceCallSignature(kind, instruction, params) {
+    return {
+        kind,
+        instructionDigest: instructionDigest(instruction),
+        paramsDigest: paramsDigest(params),
+    };
+}
+/**
+ * Map key for one signature. Both digests are hex, so a colon cannot appear
+ * inside either and the join is unambiguous.
+ */
+function traceCallSignatureKey(signature) {
+    return `${signature.kind}:${signature.instructionDigest}:${signature.paramsDigest}`;
+}
+/**
+ * Counts occurrences of each call signature within one attempt, returning the
+ * zero-based index of each step among its own repeats. Per signature rather
+ * than per attempt on purpose: only a genuine repeat of the same request
+ * advances the number.
+ */
+export function createCallIndexer() {
+    const seen = new Map();
+    return (signature) => {
+        const mapKey = traceCallSignatureKey(signature);
+        const count = seen.get(mapKey) ?? 0;
+        seen.set(mapKey, count + 1);
+        return count;
+    };
+}
+/**
+ * Assembles one key. Field order is irrelevant to the digest, since JCS sorts
+ * keys, but the explicit shape keeps every required field accounted for.
+ */
+export function buildTraceCacheKey(parts) {
+    return {
+        specVersion: '0.1',
+        cacheSchema: TRACE_SCHEMA_VERSION,
+        project: parts.project,
+        testId: parts.testId,
+        targetId: parts.target.targetId,
+        platform: parts.target.platform,
+        backendName: parts.target.backendName,
+        backendVersion: backendCompatibilityVersion(parts.target.backendVersion),
+        backendSpiVersion: parts.target.spiVersion,
+        kind: parts.signature.kind,
+        callIndex: parts.callIndex,
+        instructionDigest: parts.signature.instructionDigest,
+        paramsDigest: parts.signature.paramsDigest,
+        appIdentity: parts.target.appIdentity,
+        policyVersion: parts.policyVersion,
+    };
+}
+/** SHA-256/JCS of one key, used as both the entry digest and its file name. */
+export function traceCacheKeyHash(key) {
+    return canonicalDigest(key);
+}
+//# sourceMappingURL=identity.js.map

package/dist/cache/identity.js.map

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

package/dist/cache/recorder.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Step trace recording (RFC0001 layer 3, cache-in decision).
+ *
+ * Records every grammar action a step commits, capturing a durable target
+ * descriptor at commit time — the moment the harness resolved the node — so
+ * replay can re-find it against a fresh observation. Recording is
+ * defense-in-depth on secrets: callers already hand secret-free input
+ * (`typeSecret` contributes only the secret's stable name), and every string
+ * that could carry screen content is additionally passed through the run's
+ * redactor before it can reach disk.
+ *
+ * Replay inputs are verbatim or nothing. A value the redactor would alter, or
+ * one over the input cap, poisons the trace (`truncated`) instead of being
+ * bent to fit: a trimmed URL or half a typed value would replay a different
+ * action than the one recorded, and could self-finalize a step on the wrong
+ * state. A poisoned trace still documents what happened; it never replays.
+ */
+import { type RecordableAction } from '../agent/actions.ts';
+import { type ActionTrace, type TraceTargetDescriptor } from './trace.ts';
+export interface TraceRecorderOptions {
+    /** The run's secret redactor; applied to every recorded string. */
+    readonly redact: (text: string) => string;
+    readonly testIdAttribute: string;
+    readonly maxActions?: number;
+}
+export declare class TraceRecorder {
+    private readonly actions;
+    private truncated;
+    private readonly redact;
+    private readonly testIdAttribute;
+    private readonly maxActions;
+    constructor(options: TraceRecorderOptions);
+    /** Number of actions recorded so far, gaps included. */
+    get recordedCount(): number;
+    /** Records one committed grammar action. */
+    record(action: RecordableAction): void;
+    /**
+     * Records one mutating project-tool call as a gap. Replay ends here rather
+     * than skipping it: the grammar cannot reproduce the mutation, and a replay
+     * that silently dropped a state change would prove nothing.
+     */
+    recordGap(toolName: string): void;
+    /**
+     * Concludes recording into a trace, or undefined when nothing was recorded —
+     * a step that committed no actions has no flow worth replaying.
+     */
+    finalize(conclusion: {
+        readonly executor: {
+            readonly name: string;
+            readonly version?: string;
+        };
+        readonly summary: string;
+        readonly startPath?: string;
+        readonly endPath?: string;
+        /** Already projected and capped by `describeAnchors`; recorded as given. */
+        readonly endAnchors?: readonly TraceTargetDescriptor[];
+    }): ActionTrace | undefined;
+    private anchorPath;
+    /**
+     * Builds the stored variant for one action. The descriptor and the prose
+     * come from `describeAction` — already redacted and bounded, and the same
+     * text the live event carried. Stored inputs still go through `verbatim`,
+     * whose poisoning marks the trace non-replayable when a value cannot be
+     * kept whole.
+     */
+    private toRecorded;
+    /**
+     * A replay input, verbatim or poisoned. A value the redactor alters carried
+     * a registered secret; an oversized one cannot be stored whole. Either way
+     * the trace is marked non-replayable and a redacted, bounded copy is kept
+     * for documentation only.
+     */
+    private verbatim;
+    private push;
+}
+//# sourceMappingURL=recorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/cache/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAML,KAAK,WAAW,EAEhB,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,OAAO,EAAE,oBAAoB,EAIxC;IAED,wDAAwD;IACxD,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,4CAA4C;IAC5C,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAGrC;IAED;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEhC;IAED;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,QAAQ,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,4EAA4E;QAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;KACxD,GAAG,WAAW,GAAG,SAAS,CAsB1B;IAED,OAAO,CAAC,UAAU;IAOlB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAmClB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,IAAI;CAOb"}

package/dist/cache/recorder.js

@@ -0,0 +1,143 @@
+/**
+ * Step trace recording (RFC0001 layer 3, cache-in decision).
+ *
+ * Records every grammar action a step commits, capturing a durable target
+ * descriptor at commit time — the moment the harness resolved the node — so
+ * replay can re-find it against a fresh observation. Recording is
+ * defense-in-depth on secrets: callers already hand secret-free input
+ * (`typeSecret` contributes only the secret's stable name), and every string
+ * that could carry screen content is additionally passed through the run's
+ * redactor before it can reach disk.
+ *
+ * Replay inputs are verbatim or nothing. A value the redactor would alter, or
+ * one over the input cap, poisons the trace (`truncated`) instead of being
+ * bent to fit: a trimmed URL or half a typed value would replay a different
+ * action than the one recorded, and could self-finalize a step on the wrong
+ * state. A poisoned trace still documents what happened; it never replays.
+ */
+import { describeAction } from '../agent/actions.js';
+import { bound, MAX_TRACE_ACTIONS, MAX_TRACE_DESCRIPTOR_CHARS, MAX_TRACE_INPUT_CHARS, MAX_TRACE_SUMMARY_CHARS, } from './trace.js';
+export class TraceRecorder {
+    actions = [];
+    truncated = false;
+    redact;
+    testIdAttribute;
+    maxActions;
+    constructor(options) {
+        this.redact = options.redact;
+        this.testIdAttribute = options.testIdAttribute;
+        this.maxActions = Math.min(options.maxActions ?? MAX_TRACE_ACTIONS, MAX_TRACE_ACTIONS);
+    }
+    /** Number of actions recorded so far, gaps included. */
+    get recordedCount() {
+        return this.actions.length;
+    }
+    /** Records one committed grammar action. */
+    record(action) {
+        const { target, summary } = describeAction(action, this.redact, this.testIdAttribute);
+        this.push(this.toRecorded(action, target, summary));
+    }
+    /**
+     * Records one mutating project-tool call as a gap. Replay ends here rather
+     * than skipping it: the grammar cannot reproduce the mutation, and a replay
+     * that silently dropped a state change would prove nothing.
+     */
+    recordGap(toolName) {
+        this.push({ name: 'tool', summary: bound(`tool ${this.redact(toolName)}`, MAX_TRACE_SUMMARY_CHARS) });
+    }
+    /**
+     * Concludes recording into a trace, or undefined when nothing was recorded —
+     * a step that committed no actions has no flow worth replaying.
+     */
+    finalize(conclusion) {
+        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.
+        const startPath = this.anchorPath(conclusion.startPath);
+        const endPath = this.anchorPath(conclusion.endPath);
+        return {
+            actions: [...this.actions],
+            executor: {
+                name: conclusion.executor.name,
+                ...(conclusion.executor.version === undefined ? {} : { version: conclusion.executor.version }),
+            },
+            summary: summary.trim() === '' ? 'step passed' : summary,
+            ...(startPath === undefined ? {} : { startPath }),
+            ...(endPath === undefined ? {} : { endPath }),
+            ...(conclusion.endAnchors === undefined || conclusion.endAnchors.length === 0
+                ? {}
+                : { endAnchors: conclusion.endAnchors }),
+            ...(this.truncated ? { truncated: true } : {}),
+        };
+    }
+    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);
+    }
+    /**
+     * Builds the stored variant for one action. The descriptor and the prose
+     * come from `describeAction` — already redacted and bounded, and the same
+     * text the live event carried. Stored inputs still go through `verbatim`,
+     * whose poisoning marks the trace non-replayable when a value cannot be
+     * kept whole.
+     */
+    toRecorded(action, target, summary) {
+        // A targeted commit whose node yields no durable descriptor cannot be
+        // re-found; the trace stays honest by poisoning instead of guessing.
+        const requireTarget = () => {
+            if (target !== undefined)
+                return target;
+            this.truncated = true;
+            return { role: 'unknown' };
+        };
+        switch (action.name) {
+            case 'tap':
+                return { name: 'tap', summary, target: requireTarget() };
+            case 'type':
+                return { name: 'type', summary, target: requireTarget(), value: this.verbatim(action.value) };
+            case 'typeSecret':
+                return { name: 'typeSecret', summary, target: requireTarget(), secret: action.secret };
+            case 'press':
+                return { name: 'press', summary, target: requireTarget(), key: this.verbatim(action.key) };
+            case 'select':
+                return { name: 'select', summary, target: requireTarget(), value: this.verbatim(action.value) };
+            case 'scroll':
+                return {
+                    name: 'scroll',
+                    summary,
+                    direction: action.direction,
+                    ...(target === undefined ? {} : { target }),
+                };
+            case 'navigate':
+                return { name: 'navigate', summary, url: this.verbatim(action.url) };
+        }
+    }
+    /**
+     * A replay input, verbatim or poisoned. A value the redactor alters carried
+     * a registered secret; an oversized one cannot be stored whole. Either way
+     * the trace is marked non-replayable and a redacted, bounded copy is kept
+     * for documentation only.
+     */
+    verbatim(value) {
+        const redacted = this.redact(value);
+        if (redacted === value && value.length <= MAX_TRACE_INPUT_CHARS)
+            return value;
+        this.truncated = true;
+        return bound(redacted, MAX_TRACE_INPUT_CHARS);
+    }
+    push(action) {
+        if (this.actions.length >= this.maxActions) {
+            this.truncated = true;
+            return;
+        }
+        this.actions.push(action);
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/cache/recorder.js.map

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

package/dist/cache/relocate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Deterministic target relocation (RFC0001 layer 3, cache-in decision).
+ *
+ * Re-finds a recorded target descriptor in a fresh observation: exactly one
+ * node must match, or replay diverges. This is the conservative public
+ * ReplayPolicy — no scoring, no fuzzy matching, no vision. A tuned policy may
+ * replace it behind the same seam; the fail-closed contract (one match or
+ * hand off) is not tunable.
+ *
+ * Candidates are compared through the same `describeTarget` projection the
+ * recorder used, so redaction, whitespace collapsing, and bounding cannot
+ * make a node unequal to its own recording. The matching vocabulary — which
+ * tiers a descriptor is tried in, and what "equal on the recorded fields"
+ * means — is exported so end anchors (`anchors.ts`) are checked by the same
+ * rules and can never drift from relocation.
+ */
+import type { SemanticNode } from '../backend/surface.ts';
+import type { TraceTargetDescriptor } from './trace.ts';
+/**
+ * Version of the replay/relocation policy, part of every cache key. Bumping
+ * it cold-starts the cache — which is exactly right when the matching rules
+ * change, because an entry recorded under different rules could relocate to a
+ * different node.
+ */
+export declare const REPLAY_POLICY_VERSION = "conservative/3";
+export type RelocationFailure = 'target-not-found' | 'target-ambiguous';
+export type RelocationResult = {
+    readonly kind: 'found';
+    readonly id: string;
+} | {
+    readonly kind: 'failed';
+    readonly failure: RelocationFailure;
+};
+export type DescriptorField = keyof TraceTargetDescriptor;
+export interface DescriptorMatchOptions {
+    readonly redact: (text: string) => string;
+    readonly testIdAttribute: string;
+}
+/** A node's descriptor projection alongside its per-observation id. */
+export interface DescribedNode {
+    readonly id: string;
+    readonly descriptor: TraceTargetDescriptor;
+}
+/**
+ * The tiers a recorded descriptor is matched in, strictest first:
+ *
+ * 1. **Strict** — every identity field the recording captured must match.
+ * 2. **Semantic** — only when a `testId` was recorded and the remaining
+ *    fields still identify the node: the same descriptor without it. Test
+ *    ids are the strongest discriminator when stable, but some apps mint
+ *    them per render; a node the semantic fields still identify has not
+ *    moved, its label has not changed, and refusing it would fail on
+ *    cosmetics.
+ *
+ * Empty for a descriptor that identifies nothing.
+ */
+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
+ * tier diverges immediately: two candidates sharing the matched identity
+ * cannot be told apart by waiting, and acting on either would be a guess.
+ */
+export declare function relocateDescriptor(descriptor: TraceTargetDescriptor, nodes: ReadonlyMap<string, SemanticNode>, options: DescriptorMatchOptions): RelocationResult;
+//# sourceMappingURL=relocate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relocate.d.ts","sourceRoot":"","sources":["../../src/cache/relocate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAExE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,eAAe,GAAG,MAAM,qBAAqB,CAAC;AAE1D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;CAC5C;AA4BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,qBAAqB,GAAG,SAAS,qBAAqB,EAAE,CAKnG;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CACzB,QAAQ,EAAE,qBAAqB,EAC/B,SAAS,EAAE,qBAAqB,EAChC,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,OAAO,CAET;AAeD,wFAAwF;AACxF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EACxC,OAAO,EAAE,sBAAsB,GAC9B,SAAS,aAAa,EAAE,CAgB1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EACxC,OAAO,EAAE,sBAAsB,GAC9B,gBAAgB,CAOlB"}