@e2edev/e2e 0.5.0 → 0.6.0

package/dist/{backend → engine}/index.js

@@ -1,29 +1,29 @@
 /**
- * The backend contract (RFC0002): the typed, model-free body of one target.
+ * The engine contract: the typed, model-free body of one target.
  *
- * A backend never talks to a model. It declares capabilities - observation,
+ * An engine never talks to a model. It declares capabilities - observation,
  * actions, location, state, artifacts, contributed fixtures - and the harness
- * grades what a target can do from what its backend declares: observation
+ * grades what a target can do from what its engine declares: observation
  * unlocks the judgment tier and prompt snapshots, `perform` unlocks the
  * harness-routed node actions (the agent's grammar verbs and the `screen`
  * tier's actions alike), location unlocks `screen`/`expect`. Every piece of
  * model-facing vocabulary is an agent-side `defineTool`; a target with no
- * backend at all is valid and simply runs everything opaque.
+ * engine at all is valid and simply runs everything opaque.
  *
- * Core knows this contract and never a backend's internals: no platform noun
- * appears here. A document backend, a simulator backend, and a desktop backend
+ * Core knows this contract and never an engine's internals: no platform noun
+ * appears here. A document engine, a simulator engine, and a desktop engine
  * fill in the same members with different bodies.
  *
- * `defineBackend` is the loud manifest: capability detection happens here,
- * synchronously, at config load - a malformed backend fails the run instead
+ * `defineEngine` is the loud manifest: capability detection happens here,
+ * synchronously, at config load - a malformed engine fails the run instead
  * of silently demoting itself to a lower tier.
  */
-import { backendBrand } from '../internal/brands.js';
+import { engineBrand } from '../internal/brands.js';
 import { ConfigurationError } from '../internal/errors.js';
-// Semantics the spec requires every backend and contributed fixture to
-// reproduce exactly, exported so a backend never carries its own copy: the
-// runner error taxonomy (06-cli.md), text-pattern matching (04-locators.md),
-// URL matching (03-assertions.md), assertion polling (03-assertions.md), and
+// Semantics the spec requires every engine and contributed fixture to
+// reproduce exactly, exported so an engine never carries its own copy: the
+// runner error taxonomy, text-pattern matching,
+// URL matching, assertion polling, and
 // the JSON-value rules for data a fixture returns.
 export { ConfigurationError, InfrastructureError, TestError } from '../internal/errors.js';
 export { validateJsonValue } from '../internal/json-value.js';
@@ -31,9 +31,10 @@ export { describePattern, matchesText, toTextPattern } from '../internal/text.js
 export { raceAbort } from './timing.js';
 export { Deadline, pollCondition, withTimeout, withinCleanupBudget } from '../internal/time.js';
 export { urlMatches } from '../internal/urls.js';
-import { BACKEND_SPI_VERSION, } from './contract.js';
-export { BACKEND_ERROR_CODES, BACKEND_SPI_VERSION, BackendError, OBSERVED_NAME_LIMIT, OBSERVED_TEXT_LIMIT, RETRYABLE_BACKEND_ERROR_CODES, } from './contract.js';
-/** Every key a backend may declare; anything else is rejected at config load. */
+export { obj } from '../internal/objects.js';
+import { ENGINE_SPI_VERSION, } from './contract.js';
+export { ENGINE_ERROR_CODES, ENGINE_SPI_VERSION, EngineError, OBSERVED_NAME_LIMIT, OBSERVED_TEXT_LIMIT, RETRYABLE_ENGINE_ERROR_CODES, } from './contract.js';
+/** Every key an engine may declare; anything else is rejected at config load. */
 const KNOWN_KEYS = [
     'name',
     'version',
@@ -59,6 +60,20 @@ const NESTED_KEYS = {
     artifacts: ['screenshot', 'startTrace', 'stopTrace'],
     app: ['navigate', 'back', 'restart', 'clearState'],
 };
+/**
+ * Declarative members of the `app` manifest: facts about the app under test,
+ * copied through as data. Their values are validated when the config resolves
+ * the target, where an error can name it.
+ */
+const APP_DECLARATION_KEYS = [
+    'url',
+    'allowedOrigins',
+    'environment',
+    'identity',
+    'command',
+    'readyUrl',
+    'services',
+];
 const FUNCTION_MEMBERS = [
     'observe',
     'locate',
@@ -75,26 +90,36 @@ const FUNCTION_MEMBERS = [
 const RESERVED_FIXTURES = new Set(['agent', 'app', 'screen', 'platform', 'session']);
 const FIXTURE_NAME_PATTERN = /^[a-z][A-Za-z0-9]*$/;
 function invalid(name, detail) {
-    return new ConfigurationError('INVALID_CONFIG', `backend "${name}": ${detail}`);
+    return new ConfigurationError('INVALID_CONFIG', `engine "${name}": ${detail}`);
 }
 /**
  * Validates one nested manifest (`state`, `artifacts`, `app`): a plain object
- * whose keys are closed and whose declared members are functions. Returns a
- * copy with every member bound to the manifest, so class-based bodies work.
+ * whose keys are closed and whose declared members are functions, except the
+ * `app` declaration's data members, which are copied through. Returns a copy
+ * with every function bound to the manifest, so class-based bodies work.
  */
 function nestedManifest(name, key, value, required = []) {
-    if (typeof value !== 'object' || value === null) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw invalid(name, `${key} must be an object`);
     }
-    const allowed = NESTED_KEYS[key];
+    const hooks = NESTED_KEYS[key];
+    const data = key === 'app' ? APP_DECLARATION_KEYS : [];
     const source = value;
     for (const member of Object.keys(source)) {
-        if (!allowed.includes(member)) {
-            throw invalid(name, `${key} has unknown key "${member}"; expected one of ${allowed.join(', ')}`);
+        if (!hooks.includes(member) && !data.includes(member)) {
+            throw invalid(name, `${key} has unknown key "${member}"; expected one of ${[...data, ...hooks].join(', ')}`);
         }
     }
     const bound = {};
-    for (const member of allowed) {
+    for (const member of data) {
+        const fact = source[member];
+        if (fact === undefined)
+            continue;
+        if (typeof fact === 'function')
+            throw invalid(name, `${key}.${member} is a declaration, not a hook`);
+        bound[member] = fact;
+    }
+    for (const member of hooks) {
         const fn = source[member];
         if (fn === undefined) {
             if (required.includes(member))
@@ -108,7 +133,7 @@ function nestedManifest(name, key, value, required = []) {
     return bound;
 }
 /**
- * Validates a backend and computes its capability set. Runs synchronously at
+ * Validates an engine and computes its capability set. Runs synchronously at
  * config load and fails loud: a misspelled member or an undeclared dependency
  * is `INVALID_CONFIG`, never a silent demotion to a lower tier.
  *
@@ -116,19 +141,19 @@ function nestedManifest(name, key, value, required = []) {
  * through the prototype chain and binding every function to the spec, so a
  * class instance (own state fields included) is as valid a body as a literal.
  */
-export function defineBackend(spec) {
+export function defineEngine(spec) {
     if (typeof spec !== 'object' || spec === null) {
-        throw new ConfigurationError('INVALID_CONFIG', 'defineBackend requires a backend object');
+        throw new ConfigurationError('INVALID_CONFIG', 'defineEngine requires an engine object');
     }
     if (typeof spec.name !== 'string' || spec.name.trim() === '') {
-        throw new ConfigurationError('INVALID_CONFIG', 'backend.name must be a non-empty string');
+        throw new ConfigurationError('INVALID_CONFIG', 'engine.name must be a non-empty string');
     }
     const name = spec.name;
     if (typeof spec.version !== 'string' || spec.version.trim() === '') {
         throw invalid(name, 'version must be a non-empty string; it is provenance and keys the trace cache');
     }
-    if (spec.spiVersion !== BACKEND_SPI_VERSION) {
-        throw invalid(name, `declares spiVersion ${String(spec.spiVersion)}; this runner supports ${BACKEND_SPI_VERSION}`);
+    if (spec.spiVersion !== ENGINE_SPI_VERSION) {
+        throw invalid(name, `declares spiVersion ${String(spec.spiVersion)}; this runner supports ${ENGINE_SPI_VERSION}`);
     }
     // A literal's unknown key is a misspelling or a misplaced tool; a class
     // instance's own fields are its state, so only literals are checked.
@@ -136,7 +161,7 @@ export function defineBackend(spec) {
         const known = KNOWN_KEYS;
         for (const key of Object.keys(spec)) {
             if (!known.includes(key)) {
-                throw invalid(name, `unknown key "${key}" - tools belong on the agent, not the backend`);
+                throw invalid(name, `unknown key "${key}" - tools belong on the agent, not the engine`);
             }
         }
     }
@@ -185,7 +210,7 @@ export function defineBackend(spec) {
             }
             capabilities.add(fixture);
         }
-        // Bound like every other member, so a class-based backend keeps `this`
+        // Bound like every other member, so a class-based engine keeps `this`
         // in its fixture factories too.
         handle['fixtures'] = Object.freeze(Object.fromEntries(Object.entries(spec.fixtures).map(([fixture, factory]) => [
             fixture,
@@ -206,17 +231,17 @@ export function defineBackend(spec) {
     }
     if (spec.app !== undefined)
         handle['app'] = nestedManifest(name, 'app', spec.app);
-    // Assembled key by key above, so the record is a Backend by construction.
+    // Assembled key by key above, so the record is an Engine by construction.
     return Object.freeze({
         ...handle,
-        [backendBrand]: true,
+        [engineBrand]: true,
         capabilities,
     });
 }
-/** True for a defineBackend-branded handle, across realms. */
-export function isBackendHandle(value) {
+/** True for a defineEngine-branded handle, across realms. */
+export function isEngineHandle(value) {
     return (typeof value === 'object' &&
         value !== null &&
-        value[backendBrand] === true);
+        value[engineBrand] === true);
 }
 //# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

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

package/dist/engine/session.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The engine-to-session adapter. One adapter per attempt satisfies
+ * the internal `TargetSession` surface over the engine contract, so the agent
+ * tier, the judgment tier, the trace cache, and the fixture graph program
+ * against one shape. It is the single seam every engine call crosses, which
+ * makes it the one place two rules are enforced: a capability the engine does
+ * not declare fails loud with `UNSUPPORTED_CAPABILITY` at the moment of use,
+ * and anything an engine throws that is not an `EngineError` is normalized to
+ * a non-retryable `ENGINE_FAILURE`, so a crashed engine is an infrastructure
+ * failure everywhere and never a retry-eligible test failure.
+ */
+import type { EngineHandle } from './index.ts';
+import { type TargetSession } from './surface.ts';
+export interface EngineSessionOptions {
+    readonly engine: EngineHandle | undefined;
+    readonly targetName: string;
+}
+/**
+ * Builds one session over an engine. One adapter per attempt; revisions are
+ * minted per adapter, so refs can never leak across attempts.
+ */
+export declare function createEngineSession(options: EngineSessionOptions): TargetSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/engine/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/engine/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAmED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAuJhF"}

package/dist/{backend → engine}/session.js

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

package/dist/engine/session.js.map

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

package/dist/{backend → engine}/surface.d.ts

@@ -1,6 +1,6 @@
 /**
  * The internal session surface the harness consumes for one attempt. It is
- * produced only by `createBackendSession` (the backend-to-session adapter) and
+ * produced only by `createEngineSession` (the engine-to-session adapter) and
  * is never part of the public API: the locator engine, the agent tiers, and
  * the attempt executor program against it so that revision minting, staleness
  * checks, and capability gating exist exactly once.
@@ -9,17 +9,17 @@
  */
 import type { Momentum, ScrollDirection } from '../types.ts';
 import type { LocatorAction, LocatorExpression, NodeRef, ObservationPixels, OperationContext, SemanticNode } from './contract.ts';
-import type { BackendObserveOptions, BackendState } from './index.ts';
+import type { EngineObserveOptions, EngineState } from './index.ts';
 export type * from './contract.ts';
-export { BackendError } from './contract.ts';
-export type { BackendObserveOptions, BackendState } from './index.ts';
+export { EngineError } from './contract.ts';
+export type { EngineObserveOptions, EngineState } from './index.ts';
 /**
  * The agent's action grammar, by verb. A session declares which verbs its
- * backend can honor so the agent offers the model exactly that vocabulary.
+ * engine can honor so the agent offers the model exactly that vocabulary.
  */
 export type GrammarVerb = 'tap' | 'type' | 'typeSecret' | 'press' | 'select' | 'scroll' | 'navigate';
 export interface Observation {
-    /** Location captured with this tree, when the backend can provide it. */
+    /** Location captured with this tree, when the engine can provide it. */
     readonly url?: string;
     readonly revision: string;
     readonly capturedAt: string;
@@ -31,7 +31,7 @@ export interface Observation {
         readonly scale: number;
     };
     /**
-     * What the backend masked against what it saw. Pixel completeness is judged
+     * What the engine masked against what it saw. Pixel completeness is judged
      * downstream from these counts: fewer masked regions than secure nodes
      * withholds the pixels and keeps the tree.
      */
@@ -59,10 +59,10 @@ export interface SessionArtifacts {
     stopTrace?(operation: OperationContext): Promise<string>;
 }
 export interface TargetSession {
-    /** Grammar verbs the backend can honor, read from its declaration. */
+    /** Grammar verbs the engine can honor, read from its declaration. */
     readonly verbs: ReadonlySet<GrammarVerb>;
     /** Captures one atomic agent observation; the harness redacts it downstream. */
-    observe(operation: OperationContext, options?: BackendObserveOptions): Promise<Observation>;
+    observe(operation: OperationContext, options?: EngineObserveOptions): Promise<Observation>;
     /** Resolves immediately; the runner owns query polling and strictness. */
     locate(expression: LocatorExpression, operation: OperationContext): Promise<readonly NodeRef[]>;
     /** Reads one node from the resolution that minted its ref. */
@@ -74,9 +74,9 @@ export interface TargetSession {
     readonly app: SessionApp;
     readonly artifacts: SessionArtifacts;
     /** Captures immutable app state for a session envelope. */
-    captureState?(operation: OperationContext): Promise<BackendState>;
+    captureState?(operation: OperationContext): Promise<EngineState>;
     /** Replaces current app state with an immutable captured state. */
-    restoreState?(state: BackendState, operation: OperationContext): Promise<void>;
+    restoreState?(state: EngineState, operation: OperationContext): Promise<void>;
     /** Current top-level URL of the surface, when the platform has one. */
     url?(operation: OperationContext): Promise<string>;
     /** Ends the attempt's isolation within the operation's budget. Idempotent. */

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

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

package/dist/{backend → engine}/surface.js

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

package/dist/engine/surface.js.map

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

package/dist/engine/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/engine/timing.ts"],"names":[],"mappings":"AAIA,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAElH"}

package/dist/engine/timing.js

@@ -0,0 +1,8 @@
+/** Cancellation with the engine error taxonomy and shared lifecycle mechanics. */
+import { withAbort } from '../internal/time.js';
+import { EngineError } from './contract.js';
+/** Checks cancellation before dispatching a thunk, then abandons the wait on abort. */
+export function raceAbort(work, signal, label) {
+    return withAbort(work, signal, () => new EngineError('CANCELLED', `${label} cancelled`, { retryable: false }));
+}
+//# sourceMappingURL=timing.js.map

package/dist/engine/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/engine/timing.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CAAI,IAAqC,EAAE,MAAmB,EAAE,KAAa;IACpG,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,WAAW,EAAE,GAAG,KAAK,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AACjH,CAAC"}

package/dist/expect/async.d.ts

@@ -1,4 +1,4 @@
-/** Runner-owned polling locator assertions (spec 03-assertions.md). */
+/** Runner-owned polling locator assertions. */
 import type { LocatorInternals } from '../locator/screen.ts';
 import type { AsyncExpectation } from '../types.ts';
 export declare function createAsyncExpectation(internals: LocatorInternals): AsyncExpectation;

package/dist/expect/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/expect/async.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAQvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,aAAa,CAAC;AA2P/D,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,GAAG,gBAAgB,CAEpF"}
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/expect/async.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAQ/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAa,MAAM,aAAa,CAAC;AAsS/D,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,GAAG,gBAAgB,CAEpF"}