@e2edev/e2e 0.2.0

package/dist/cache/relocate.js

@@ -0,0 +1,125 @@
+/**
+ * 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 { describeTarget } from '../agent/actions.js';
+/**
+ * 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 const REPLAY_POLICY_VERSION = 'conservative/3';
+/** Identity fields that must match whenever the recording captured them. */
+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.
+ */
+function isRelocatableDescriptor(descriptor) {
+    return (descriptor.testId !== undefined ||
+        descriptor.name !== undefined ||
+        descriptor.text !== undefined ||
+        descriptor.placeholder !== undefined);
+}
+/** The semantic tier of a descriptor: every identity field but the test id. */
+function withoutTestId(descriptor) {
+    const { testId: _testId, ...semantic } = descriptor;
+    return semantic;
+}
+/**
+ * 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 function descriptorTiers(descriptor) {
+    if (!isRelocatableDescriptor(descriptor))
+        return [];
+    if (descriptor.testId === undefined)
+        return [descriptor];
+    const semantic = withoutTestId(descriptor);
+    return isRelocatableDescriptor(semantic) ? [descriptor, semantic] : [descriptor];
+}
+/** Every listed field the recording captured must be present and equal on the candidate. */
+export function fieldsEqual(recorded, candidate, fields) {
+    return fields.every((field) => recorded[field] === undefined || candidate[field] === recorded[field]);
+}
+/**
+ * Descriptor projections per observation. A replay relocates every recorded
+ * action, in two tiers, against the same node map (and again per settling
+ * retry), and the anchor check projects it once more, while the projection of
+ * a node is a pure function of the node: it is computed once per observation
+ * and shared by every lookup into it.
+ */
+const projections = new WeakMap();
+/** Projects every node of an observation the way the recorder described its targets. */
+export function describeNodes(nodes, options) {
+    const cached = projections.get(nodes);
+    if (cached !== undefined &&
+        cached.redact === options.redact &&
+        cached.testIdAttribute === options.testIdAttribute) {
+        return cached.described;
+    }
+    const described = [];
+    for (const [id, node] of nodes) {
+        const descriptor = describeTarget(node, options.redact, options.testIdAttribute);
+        if (descriptor !== undefined)
+            described.push({ id, descriptor });
+    }
+    projections.set(nodes, { redact: options.redact, testIdAttribute: options.testIdAttribute, described });
+    return described;
+}
+/**
+ * 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 function relocateDescriptor(descriptor, nodes, options) {
+    const candidates = describeNodes(nodes, options);
+    for (const tier of descriptorTiers(descriptor)) {
+        const result = matchTier(tier, candidates);
+        if (result.kind === 'found' || result.failure === 'target-ambiguous')
+            return result;
+    }
+    return { kind: 'failed', failure: 'target-not-found' };
+}
+function matchTier(tier, candidates) {
+    const fields = tier.testId === undefined && tier.name === undefined ? IDENTITY_FIELDS_WITH_TEXT : IDENTITY_FIELDS;
+    const matches = [];
+    for (const candidate of candidates) {
+        if (!fieldsEqual(tier, candidate.descriptor, fields))
+            continue;
+        matches.push(candidate.id);
+        if (matches.length > 1)
+            return { kind: 'failed', failure: 'target-ambiguous' };
+    }
+    const only = matches[0];
+    if (only === undefined)
+        return { kind: 'failed', failure: 'target-not-found' };
+    return { kind: 'found', id: only };
+}
+//# sourceMappingURL=relocate.js.map

package/dist/cache/relocate.js.map

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

package/dist/cache/store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Trace entry storage (RFC0001 layer 3, cache-in decision).
+ *
+ * One file per key under `.e2e/cache/`, named for the key digest. Reads fail
+ * closed: an oversized or unreadable entry is a miss, never a repair. Writes go
+ * through a temporary file and an atomic rename, so a crashed or concurrent
+ * writer cannot leave a torn entry behind.
+ *
+ * There is no locking. Two writers only ever collide on a key when the same
+ * step runs concurrently on the same path, and then they are writing the same
+ * flow, so last-write-wins is the correct outcome rather than a hazard.
+ *
+ * The interface exists so a remote store — the cloud's shared cache — can
+ * replace the filesystem without the harness noticing.
+ */
+import { type ActionTrace, type TraceEntry } from './trace.ts';
+/** Hard wire ceiling on one entry, on both the read and the write path. */
+export declare const MAX_CACHE_WIRE_BYTES = 1048576;
+export type CacheReadResult = {
+    readonly status: 'hit';
+    readonly entry: TraceEntry;
+    readonly bytes: number;
+} | {
+    readonly status: 'miss';
+} | {
+    readonly status: 'invalid';
+    readonly reason: string;
+    readonly bytes?: number;
+};
+export interface TraceCacheStore {
+    readonly writable: boolean;
+    read(keyHash: string): Promise<CacheReadResult>;
+    /** Persists one trace, returning its size, or undefined when not written. */
+    write(keyHash: string, payload: ActionTrace): Promise<{
+        bytes: number;
+    } | undefined>;
+    /**
+     * Evicts one entry, best-effort. Called when a replayed or just-recorded
+     * flow is implicated in a failed attempt: the entry re-records on the next
+     * pass instead of replaying a poisoned flow forever. Optional — a store
+     * without eviction merely stays stale until the next confirmed write.
+     */
+    delete?(keyHash: string): Promise<void>;
+}
+export interface FileTraceCacheStoreOptions {
+    readonly directory: string;
+    /** Entry size cap for tests; production passes the wire ceiling, which clamps it. */
+    readonly maxBytes: number;
+    readonly writable: boolean;
+}
+export declare class FileTraceCacheStore implements TraceCacheStore {
+    readonly writable: boolean;
+    private readonly directory;
+    private readonly maxBytes;
+    constructor(options: FileTraceCacheStoreOptions);
+    read(keyHash: string): Promise<CacheReadResult>;
+    write(keyHash: string, payload: ActionTrace): Promise<{
+        bytes: number;
+    } | undefined>;
+    delete(keyHash: string): Promise<void>;
+    /**
+     * Resolves one entry path. The key hash is the only caller-supplied path
+     * component and must be a bare digest, so traversal is impossible by
+     * construction rather than by canonicalization after the fact.
+     */
+    private entryPath;
+}
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EAAmC,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhG,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChD,6EAA6E;IAC7E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IACrF;;;;;OAKG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,OAAO,EAAE,0BAA0B,EAI9C;IAEK,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA6BpD;IAEK,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAsBzF;IAEK,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3C;IAED;;;;OAIG;IACH,OAAO,CAAC,SAAS;CAGlB"}

package/dist/cache/store.js

@@ -0,0 +1,106 @@
+/**
+ * Trace entry storage (RFC0001 layer 3, cache-in decision).
+ *
+ * One file per key under `.e2e/cache/`, named for the key digest. Reads fail
+ * closed: an oversized or unreadable entry is a miss, never a repair. Writes go
+ * through a temporary file and an atomic rename, so a crashed or concurrent
+ * writer cannot leave a torn entry behind.
+ *
+ * There is no locking. Two writers only ever collide on a key when the same
+ * step runs concurrently on the same path, and then they are writing the same
+ * flow, so last-write-wins is the correct outcome rather than a hazard.
+ *
+ * The interface exists so a remote store — the cloud's shared cache — can
+ * replace the filesystem without the harness noticing.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errorMessage } from '../internal/errors.js';
+import { buildTraceEntry, readTraceEntry } from './trace.js';
+/** Hard wire ceiling on one entry, on both the read and the write path. */
+export const MAX_CACHE_WIRE_BYTES = 1_048_576;
+const KEY_HASH = /^[a-f0-9]{64}$/u;
+export class FileTraceCacheStore {
+    writable;
+    directory;
+    maxBytes;
+    constructor(options) {
+        this.directory = options.directory;
+        this.maxBytes = Math.min(options.maxBytes, MAX_CACHE_WIRE_BYTES);
+        this.writable = options.writable;
+    }
+    async read(keyHash) {
+        const path = this.entryPath(keyHash);
+        if (path === undefined)
+            return { status: 'invalid', reason: 'key hash is not a SHA-256 digest' };
+        let bytes;
+        try {
+            bytes = (await stat(path)).size;
+        }
+        catch {
+            return { status: 'miss' };
+        }
+        // Checked before the read so an oversized file is never pulled into memory.
+        if (bytes > this.maxBytes) {
+            return {
+                status: 'invalid',
+                reason: `cache entry is ${bytes} bytes, over the ${this.maxBytes}-byte limit`,
+                bytes,
+            };
+        }
+        let entry;
+        try {
+            entry = readTraceEntry(JSON.parse(await readFile(path, 'utf8')));
+        }
+        catch (cause) {
+            return { status: 'invalid', reason: `cache entry is unreadable: ${errorMessage(cause)}`, bytes };
+        }
+        if (entry === undefined) {
+            return { status: 'invalid', reason: 'cache entry is not a replayable trace-1 entry', bytes };
+        }
+        return { status: 'hit', entry, bytes };
+    }
+    async write(keyHash, payload) {
+        if (!this.writable)
+            return undefined;
+        const path = this.entryPath(keyHash);
+        if (path === undefined)
+            return undefined;
+        const serialized = `${JSON.stringify(buildTraceEntry(payload), null, 2)}\n`;
+        const bytes = Buffer.byteLength(serialized, 'utf8');
+        if (bytes > this.maxBytes)
+            return undefined;
+        await mkdir(this.directory, { recursive: true });
+        // Random rather than pid+clock: two writers racing on one key in the same
+        // millisecond would otherwise pick the same temporary name, and the first
+        // rename would pull the file out from under the second.
+        const temporary = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+        try {
+            await writeFile(temporary, serialized, { encoding: 'utf8', mode: 0o600 });
+            await rename(temporary, path);
+        }
+        catch (cause) {
+            await unlink(temporary).catch(() => undefined);
+            throw cause;
+        }
+        return { bytes };
+    }
+    async delete(keyHash) {
+        if (!this.writable)
+            return;
+        const path = this.entryPath(keyHash);
+        if (path === undefined)
+            return;
+        await unlink(path).catch(() => undefined);
+    }
+    /**
+     * Resolves one entry path. The key hash is the only caller-supplied path
+     * component and must be a bare digest, so traversal is impossible by
+     * construction rather than by canonicalization after the fact.
+     */
+    entryPath(keyHash) {
+        return KEY_HASH.test(keyHash) ? join(this.directory, `${keyHash}.json`) : undefined;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/cache/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/cache/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAqC,MAAM,YAAY,CAAC;AAEhG,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C,MAAM,QAAQ,GAAG,iBAAiB,CAAC;AA4BnC,MAAM,OAAO,mBAAmB;IACrB,QAAQ,CAAU;IAEV,SAAS,CAAS;IAClB,QAAQ,CAAS;IAElC,YAAY,OAAmC;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;QACjE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAe;QACxB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAC;QAEjG,IAAI,KAAa,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC5B,CAAC;QACD,4EAA4E;QAC5E,IAAI,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1B,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,kBAAkB,KAAK,oBAAoB,IAAI,CAAC,QAAQ,aAAa;gBAC7E,KAAK;aACN,CAAC;QACJ,CAAC;QAED,IAAI,KAA6B,CAAC;QAClC,IAAI,CAAC;YACH,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QACnE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,8BAA8B,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC;QACnG,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,+CAA+C,EAAE,KAAK,EAAE,CAAC;QAC/F,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAe,EAAE,OAAoB;QAC/C,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO,SAAS,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAEzC,MAAM,UAAU,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;QAC5E,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACpD,IAAI,KAAK,GAAG,IAAI,CAAC,QAAQ;YAAE,OAAO,SAAS,CAAC;QAE5C,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,0EAA0E;QAC1E,0EAA0E;QAC1E,wDAAwD;QACxD,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QAClE,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1E,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC/C,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAe;QAC1B,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACK,SAAS,CAAC,OAAe;QAC/B,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,CAAC;CACF"}

package/dist/cache/trace.d.ts

@@ -0,0 +1,146 @@
+/**
+ * `trace-1` entry format (RFC0001 layer 3, cache-in decision).
+ *
+ * A trace is the ordered list of grammar actions one passing `agent.act()`
+ * step performed, each with a durable target descriptor and secret-free,
+ * verbatim input — never model output, never plaintext secrets. An entry is
+ * deliberately small: a schema version, when it was written, and the trace
+ * with the provenance it had. It does not repeat its own key: the file name
+ * is the key digest and a reader only ever opens the digest of the key it
+ * just computed.
+ *
+ * Actions are a discriminated union: each variant carries exactly the typed
+ * input its grammar action needs, so validation here is the one owner of
+ * replayability — a document that reads back as an entry replays verbatim,
+ * and a document this runner cannot replay verbatim comes back as
+ * `undefined`, never as a repaired or partially trusted entry.
+ */
+import type { ScrollDirection } from '../types.ts';
+export declare const TRACE_SCHEMA_VERSION = "trace-1";
+/** Mirrors the default step action budget; overflow marks the trace truncated. */
+export declare const MAX_TRACE_ACTIONS = 50;
+/** Prose caps keep an entry a receipt, not a transcript. */
+export declare const MAX_TRACE_SUMMARY_CHARS = 300;
+export declare const MAX_TRACE_DESCRIPTOR_CHARS = 300;
+/**
+ * Cap on verbatim replay inputs (typed text, URLs, option labels). Inputs are
+ * never truncated to fit — a trimmed URL or half a typed value would replay a
+ * different action than the one recorded — so an oversized input poisons the
+ * trace (`truncated`) instead of bending the value.
+ */
+export declare const MAX_TRACE_INPUT_CHARS = 4096;
+/** Caps prose at `maxChars`, marking the cut with an ellipsis. */
+export declare function bound(text: string, maxChars: number): string;
+/**
+ * Cap on recorded end anchors. Anchors are the step's own delta — what
+ * appeared on screen between the first observation and the passing one — so
+ * a same-screen mutation rarely has more than a handful; a step that changes
+ * the whole screen keeps the first few in document order.
+ */
+export declare const MAX_TRACE_ANCHORS = 8;
+/**
+ * How a recorded action addressed its node, independent of observation ids.
+ * Ids are minted per observation, so replay re-finds the node from the
+ * semantic fields against a fresh observation, and whatever they resolve to
+ * is still checked before use. The structural `selector` is captured as
+ * provenance for tuned replay policies; the conservative policy ignores it.
+ */
+export interface TraceTargetDescriptor {
+    readonly role?: string;
+    readonly name?: string;
+    readonly text?: string;
+    readonly testId?: string;
+    readonly placeholder?: string;
+    readonly selector?: string;
+    readonly inputPurpose?: string;
+}
+interface ActionBase {
+    /** One-line prose summary — the only view a mid-step hand-off notice shows. */
+    readonly summary: string;
+}
+export interface TapAction extends ActionBase {
+    readonly name: 'tap';
+    readonly target: TraceTargetDescriptor;
+}
+export interface TypeAction extends ActionBase {
+    readonly name: 'type';
+    readonly target: TraceTargetDescriptor;
+    readonly value: string;
+}
+/** A secret fill, recorded by its stable name only — never the plaintext. */
+export interface TypeSecretAction extends ActionBase {
+    readonly name: 'typeSecret';
+    readonly target: TraceTargetDescriptor;
+    readonly secret: string;
+}
+export interface PressAction extends ActionBase {
+    readonly name: 'press';
+    readonly target: TraceTargetDescriptor;
+    readonly key: string;
+}
+export interface SelectAction extends ActionBase {
+    readonly name: 'select';
+    readonly target: TraceTargetDescriptor;
+    readonly value: string;
+}
+export interface ScrollAction extends ActionBase {
+    readonly name: 'scroll';
+    readonly direction: ScrollDirection;
+    readonly target?: TraceTargetDescriptor;
+}
+export interface NavigateAction extends ActionBase {
+    readonly name: 'navigate';
+    readonly url: string;
+}
+/**
+ * A project-tool mutation the grammar cannot reproduce — a gap that ends any
+ * replay rather than silently skipping a state change.
+ */
+export interface ToolGapAction extends ActionBase {
+    readonly name: 'tool';
+}
+export type RecordedAction = TapAction | TypeAction | TypeSecretAction | PressAction | SelectAction | ScrollAction | NavigateAction | ToolGapAction;
+export interface ActionTrace {
+    readonly actions: readonly RecordedAction[];
+    /** Executor that produced the trace — provenance, never part of the key (OQ10). */
+    readonly executor: {
+        readonly name: string;
+        readonly version?: string;
+    };
+    /** The recorded run's verdict summary. */
+    readonly summary: string;
+    /** Location path when the step began; a precondition unless the trace opens with navigate. */
+    readonly startPath?: string;
+    /**
+     * Location path when the step passed — the trace's deterministic postcondition.
+     * A full replay self-finalizes only while the live pathname still matches;
+     * a recorded flow whose destination changed hands off instead of passing.
+     */
+    readonly endPath?: string;
+    /**
+     * Descriptors of nodes that were on screen when the step passed and were
+     * not there when it began — the recorded run's verification, made
+     * mechanical. A full replay self-finalizes only while every anchor is
+     * present again; a flow whose actions replayed but whose effect did not
+     * (a save that never committed, an unnamed form left behind) hands off
+     * instead of passing on mechanics alone.
+     */
+    readonly endAnchors?: readonly TraceTargetDescriptor[];
+    /** Set when recording overflowed a cap; the trace documents, never replays. */
+    readonly truncated?: boolean;
+}
+export interface TraceEntry {
+    readonly schemaVersion: typeof TRACE_SCHEMA_VERSION;
+    readonly createdAt: string;
+    readonly payload: ActionTrace;
+}
+/** Wraps one trace as a fresh entry. */
+export declare function buildTraceEntry(payload: ActionTrace): TraceEntry;
+/**
+ * Reads one document as a `trace-1` entry, or returns undefined when it is
+ * not one this runner can trust. Unknown fields are dropped rather than
+ * carried: the returned entry contains exactly the validated shape.
+ */
+export declare function readTraceEntry(document: unknown): TraceEntry | undefined;
+export {};
+//# sourceMappingURL=trace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/cache/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C,kEAAkE;AAClE,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAInC;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,UAAU,UAAU;IAClB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;CACxC;AAED,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,gBAAgB,GAChB,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,cAAc,GACd,aAAa,CAAC;AAElB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACvD,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,aAAa,EAAE,OAAO,oBAAoB,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAKD,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAexE"}