@e2edev/e2e 0.5.0 → 0.6.0

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

@@ -1,7 +1,7 @@
 /**
- * The backend contract vocabulary (RFC0002): the platform-neutral types every
- * backend speaks and the harness consumes. A backend imports these from
- * `@e2edev/e2e/backend`; core never imports anything from a backend.
+ * The engine contract vocabulary: the platform-neutral types every
+ * engine speaks and the harness consumes. An engine imports these from
+ * `@e2edev/e2e/engine`; core never imports anything from an engine.
  *
  * Everything here is capability vocabulary - semantic nodes, locator
  * expressions, action kinds, the error contract - never a platform noun. A
@@ -9,18 +9,18 @@
  * words, which is what lets `screen`, `expect`, and the agent work identically
  * on all of them.
  */
-/** The backend contract version this runner speaks. */
-export const BACKEND_SPI_VERSION = 1;
+/** The engine contract version this runner speaks. */
+export const ENGINE_SPI_VERSION = 1;
 /**
- * Per-field bounds a backend applies to observation-tree nodes. A `name` or
+ * Per-field bounds an engine applies to observation-tree nodes. A `name` or
  * `text` whose length reaches its limit was cut at exactly that limit, so
  * "length >= limit" is a precise truncation signal; every shorter value is
  * complete. Single-node reads are unbounded and always carry the full value.
  */
 export const OBSERVED_NAME_LIMIT = 256;
 export const OBSERVED_TEXT_LIMIT = 512;
-/** The closed backend error code set; the type is derived from it, so the two cannot drift. */
-export const BACKEND_ERROR_CODES = [
+/** The closed engine error code set; the type is derived from it, so the two cannot drift. */
+export const ENGINE_ERROR_CODES = [
     'NODE_STALE',
     'FRAME_NOT_FOUND',
     'FRAME_AMBIGUOUS',
@@ -30,31 +30,31 @@ export const BACKEND_ERROR_CODES = [
     'CANCELLED',
     'UNSUPPORTED_CAPABILITY',
     'INVALID_STATE',
-    'BACKEND_FAILURE',
+    'ENGINE_FAILURE',
 ];
 /**
  * The only codes that may be retryable: both describe a repeatable read. Any
  * other retryable claim, from this module's class or a foreign copy of it, is
- * coerced to a non-retryable `BACKEND_FAILURE`.
+ * coerced to a non-retryable `ENGINE_FAILURE`.
  */
-export const RETRYABLE_BACKEND_ERROR_CODES = new Set([
+export const RETRYABLE_ENGINE_ERROR_CODES = new Set([
     'NODE_STALE',
     'FRAME_NOT_FOUND',
 ]);
 /**
- * The error contract a backend throws across the seam. Retryability is closed
- * to `RETRYABLE_BACKEND_ERROR_CODES`; any other retryable claim is coerced to
- * a non-retryable `BACKEND_FAILURE` so a backend can never talk the harness
+ * The error contract an engine throws across the seam. Retryability is closed
+ * to `RETRYABLE_ENGINE_ERROR_CODES`; any other retryable claim is coerced to
+ * a non-retryable `ENGINE_FAILURE` so an engine can never talk the harness
  * into repeating an action that may have committed.
  */
-export class BackendError extends Error {
+export class EngineError extends Error {
     code;
     retryable;
     constructor(code, message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
-        this.name = 'BackendError';
-        if (options.retryable && !RETRYABLE_BACKEND_ERROR_CODES.has(code)) {
-            this.code = 'BACKEND_FAILURE';
+        this.name = 'EngineError';
+        if (options.retryable && !RETRYABLE_ENGINE_ERROR_CODES.has(code)) {
+            this.code = 'ENGINE_FAILURE';
             this.retryable = false;
             return;
         }

package/dist/engine/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/engine/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,sDAAsD;AACtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAuEpC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAgGvC,8FAA8F;AAC9F,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,gBAAgB;IAChB,2BAA2B;IAC3B,mBAAmB;IACnB,WAAW;IACX,wBAAwB;IACxB,eAAe;IACf,gBAAgB;CACR,CAAC;AAIX;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAiC,IAAI,GAAG,CAAC;IAChF,YAAY;IACZ,iBAAiB;CAClB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAkB;IACtB,SAAS,CAAU;IAE5B,YACE,IAAqB,EACrB,OAAe,EACf,OAAgD;QAEhD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,OAAO,CAAC,SAAS,IAAI,CAAC,4BAA4B,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACjE,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;YAC7B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;YACvB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;CACF"}

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

@@ -1,24 +1,24 @@
 /**
- * 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.ts';
+import { engineBrand } from '../internal/brands.ts';
 export { ConfigurationError, InfrastructureError, TestError } from '../internal/errors.ts';
 export { validateJsonValue, type JsonValueRules } from '../internal/json-value.ts';
 export { describePattern, matchesText, toTextPattern } from '../internal/text.ts';
@@ -26,23 +26,83 @@ export type { TextMatch } from '../types.ts';
 export { raceAbort } from './timing.ts';
 export { Deadline, pollCondition, withTimeout, withinCleanupBudget, type PollConditionOptions } from '../internal/time.ts';
 export { urlMatches } from '../internal/urls.ts';
-import type { Expectable, Locator, Momentum, Screen, ScrollDirection } from '../types.ts';
-import { type BackendSpiVersion, type LocatorAction, type LocatorExpression, type NodeRef, type ObservationPixels, type OperationContext, type SemanticNode } from './contract.ts';
+export { obj, type WithoutUndefined } from '../internal/objects.ts';
+import type { CommandConfig, Expectable, Locator, Momentum, Screen, ScrollDirection, ServiceConfig } from '../types.ts';
+import { type EngineSpiVersion, type LocatorAction, type LocatorExpression, type NodeRef, type ObservationPixels, type OperationContext, type SemanticNode } from './contract.ts';
 export type * from './contract.ts';
-export { BACKEND_ERROR_CODES, BACKEND_SPI_VERSION, BackendError, OBSERVED_NAME_LIMIT, OBSERVED_TEXT_LIMIT, RETRYABLE_BACKEND_ERROR_CODES, } from './contract.ts';
-export type { Expectable, JsonValue, Locator, Momentum, Platform, Screen, ScrollDirection, SelectOption, } from '../types.ts';
+export { ENGINE_ERROR_CODES, ENGINE_SPI_VERSION, EngineError, OBSERVED_NAME_LIMIT, OBSERVED_TEXT_LIMIT, RETRYABLE_ENGINE_ERROR_CODES, } from './contract.ts';
+export type { CommandConfig, ServiceConfig, Expectable, JsonValue, Locator, Momentum, Platform, Screen, ScrollDirection, SelectOption, } from '../types.ts';
 /**
  * Capability names: the closed harness capabilities plus one name per
  * contributed fixture. `actions` is `perform`; `location` is `locate`. Both
  * require observation, because their refs live in the observation's id space.
  */
-export type BackendCapability = 'observation' | 'actions' | 'location' | 'state' | 'artifacts' | (string & {});
-/** The app under test as the harness resolved it, shared with every backend. */
-export interface BackendAppInfo {
+export type EngineCapability = 'observation' | 'actions' | 'location' | 'state' | 'artifacts' | (string & {});
+/**
+ * What an engine declares about the app it drives. The app
+ * under test is the engine's to describe: a browser engine names a URL, a
+ * device engine a bundle id. The harness resolves the declaration once per
+ * target and owns everything built on it - navigation and origin policy,
+ * cache and session identity, the report's target record, and the app
+ * process it starts before the run.
+ */
+export interface EngineAppDeclaration {
+    /**
+     * Base URL of an addressable app: `app.open()` opens it and relative
+     * navigation resolves against it. WHATWG-normalized; no userinfo, query, or
+     * fragment; a missing scheme becomes `https://`, or `http://` for a
+     * loopback host. Plain HTTP is accepted for loopback hosts only.
+     */
+    readonly url?: string;
+    /**
+     * Origins navigation and secret fills admit; each entry a serialized
+     * origin. Defaults to the URL's origin, or to none without a URL.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /**
+     * Labels the target in the report and joins the cache and session identity
+     * digest; never gates a run. Defaults to `test` for loopback, `.localhost`,
+     * and `.test` hosts and for a surface without a URL, `production` otherwise.
+     */
+    readonly environment?: 'test' | 'staging' | 'production';
+    /**
+     * Stable logical identity of the app under test, keying trace cache and
+     * session entries. Defaults to the URL's origin and base path, so an
+     * ephemeral per-deploy origin (a PR preview) cold-starts every entry; an
+     * explicit identity keys them by what the app *is* instead of where it is
+     * served this run. A surface without a URL has no default: declare one
+     * (a bundle id, say) or entries key on the target alone. Never share one
+     * identity across genuinely different apps: recorded traces would replay
+     * across them.
+     */
+    readonly identity?: string;
+    /**
+     * Process the runner starts before the first test and stops on every exit
+     * path (a dev server). Structured, never shell-interpreted; the child
+     * inherits only `PATH`, `HOME`, the temp-directory variables, and
+     * `command.env`. Targets declaring the same command share one process,
+     * probed at the first declaring target's `readyUrl`.
+     */
+    readonly command?: CommandConfig;
+    /** URL polled until `command` is ready (a 200-499 status); defaults to `url`. */
+    readonly readyUrl?: string;
+    /**
+     * Dependency processes the app needs before it can boot (a database
+     * container, a migration step), started in declaration order before any
+     * app command and torn down in reverse after it. Valid without `command`:
+     * the app may already be running, or be one of the services itself.
+     * Services declared identically by several targets start once; shared
+     * services must be declared in one order, and an explicit `name` must mean
+     * one process across the run.
+     */
+    readonly services?: readonly ServiceConfig[];
+}
+/** The app under test as the harness resolved the engine's declaration, handed back at init. */
+export interface EngineAppInfo {
     /**
      * Normalized base URL; the target of `app.open()` with no path. Absent when
-     * the project configured no app URL: a surface that needs one then fails
-     * the call that needs it, and never navigates to a placeholder.
+     * the engine declared no `url`: a surface that needs one then fails the
+     * call that needs it, and never navigates to a placeholder.
      */
     readonly baseUrl?: string;
     /** Origins navigation and cookie policy admit. */
@@ -62,14 +122,14 @@ export type FixtureOperations<T extends object> = {
     readonly [Key in keyof T]?: T[Key] extends (...args: infer Args) => Promise<unknown> ? FixtureOperation<Args> : T[Key] extends object ? FixtureOperations<T[Key]> : never;
 };
 /** Context handed to a contributed fixture factory, once per attempt. */
-export interface BackendFixtureContext {
+export interface EngineFixtureContext {
     readonly targetName: string;
     /** Records the declared operations before invoking them; undeclared accessors retain their identity. */
     fixture<T extends object>(name: string, surface: T, operations: FixtureOperations<T>): T;
-    readonly app: BackendAppInfo & {
+    readonly app: EngineAppInfo & {
         /**
          * Resolves a navigation target against the base URL and the origin
-         * policy. Throws `APP_URL_REQUIRED` when no app URL is configured and
+         * policy. Throws `APP_URL_REQUIRED` when the engine declared no URL and
          * `POLICY_DENIED` for a disallowed origin or scheme, so a fixture never
          * re-implements the policy the harness owns.
          */
@@ -111,22 +171,22 @@ export interface BackendFixtureContext {
 }
 /**
  * A contributed fixture: any record of async methods, sync accessors, and
- * nested namespaces. Declare recorded methods with context.fixture; their
- * metadata controls labels, deadlines and verification. Plain surfaces remain
- * supported through the legacy adapter for existing backend factories.
+ * nested namespaces, declared through context.fixture so its metadata controls
+ * labels, deadlines and verification. The factory must return the declared
+ * surface; a plain one is rejected with INVALID_CONFIG.
  */
-export type BackendFixtureFactory = (context: BackendFixtureContext) => object;
+export type EngineFixtureFactory = (context: EngineFixtureContext) => object;
 /**
- * An opaque, restorable snapshot of a backend's state. `data` is JSON the
+ * An opaque, restorable snapshot of an engine's state. `data` is JSON the
  * harness never inspects - a document platform's storage state, a device's app state, a
  * desktop's window state all satisfy it identically. `format`/`version` let a
- * backend reject a snapshot it can no longer read.
+ * engine reject a snapshot it can no longer read.
  */
-export interface BackendState {
+export interface EngineState {
     readonly format: string;
     readonly version: number;
     readonly data: unknown;
-    /** Earliest moment the state is known to be invalid, if the backend knows one. */
+    /** Earliest moment the state is known to be invalid, if the engine knows one. */
     readonly expiresAt?: string;
 }
 /**
@@ -137,23 +197,23 @@ export interface BackendState {
  * the app under test. The duties split at the seam. The harness owns the
  * snapshot from the moment `capture` returns: it encrypts it at rest with a
  * per-run AES-256-GCM key that never touches disk, stores it under the run's
- * private session directory, binds it to the run, target, backend, and app
+ * private session directory, binds it to the run, target, engine, and app
  * identity, and deletes it when the run ends; it never logs it, reports it,
- * digests it, or sends it to a model. A backend MUST NOT persist, cache, or
+ * digests it, or sends it to a model. An engine MUST NOT persist, cache, or
  * log a snapshot on its own, MUST NOT echo snapshot contents in an error
  * message, and MUST treat `restore` as a replacement of the surface's whole
  * persisted state, never a merge, so a restored session cannot leak into the
  * next attempt.
  */
-export interface BackendStateCapability {
-    capture(context: OperationContext): Promise<BackendState>;
-    restore(state: BackendState, context: OperationContext): Promise<void>;
+export interface EngineStateCapability {
+    capture(context: OperationContext): Promise<EngineState>;
+    restore(state: EngineState, context: OperationContext): Promise<void>;
 }
 /**
  * Evidence capture. Paths are relative to the attempt artifact directory the
- * backend received in `startAttempt`.
+ * engine received in `startAttempt`.
  */
-export interface BackendArtifacts {
+export interface EngineArtifacts {
     /** Captures a redacted screenshot; secure fields are masked at the source. */
     screenshot(label: string | undefined, context: OperationContext): Promise<string>;
     /** Starts recording an execution trace for the attempt. */
@@ -162,10 +222,12 @@ export interface BackendArtifacts {
     stopTrace?(context: OperationContext): Promise<string>;
 }
 /**
- * App-level hooks behind the universal `app` fixture and the agent's
- * `navigate` verb. Node actions never live here; they are `perform`.
+ * The app under test: what the engine declares about it
+ * (`EngineAppDeclaration`) and the app-level hooks behind the universal
+ * `app` fixture and the agent's `navigate` verb. Node actions never live
+ * here; they are `perform`.
  */
-export interface BackendApp {
+export interface EngineApp extends EngineAppDeclaration {
     /**
      * Opens one URL the harness already resolved against the base URL and the
      * origin policy. Absent on a surface without addressable locations.
@@ -182,7 +244,7 @@ export interface BackendApp {
  * Facts handed to `prepare`, once per run and target in the runner process,
  * before any worker exists.
  */
-export interface BackendPrepareInfo {
+export interface EnginePrepareInfo {
     readonly runId: string;
     readonly targetName: string;
     /**
@@ -207,17 +269,17 @@ export interface BackendPrepareInfo {
     readonly log: (line: string) => void;
 }
 /** Run identity and harness-resolved facts handed to `init`, once per worker before the first step. */
-export interface BackendInitInfo {
+export interface EngineInitInfo {
     readonly runId: string;
     readonly targetName: string;
     /**
      * Directory relative paths in the config resolve against: the config file's
-     * directory, or the run's `cwd` for a programmatic config. A backend option
+     * directory, or the run's `cwd` for a programmatic config. An engine option
      * naming a file (a build to install) resolves here, never against
      * `process.cwd()`, which an in-process run does not change.
      */
     readonly projectRoot: string;
-    readonly app: BackendAppInfo;
+    readonly app: EngineAppInfo;
     /** Attribute the `testId` query resolves against. */
     readonly testIdAttribute: string;
     /** Whether the run asked for a visible surface (`--headed`). */
@@ -226,11 +288,11 @@ export interface BackendInitInfo {
     readonly signal: AbortSignal;
 }
 /**
- * Per-attempt isolation context. A backend that must give each test a fresh
+ * Per-attempt isolation context. An engine that must give each test a fresh
  * surface (a fresh isolated context per test, a reset device) sets it up in
  * `startAttempt` and tears it down in `endAttempt`.
  */
-export interface BackendAttemptContext {
+export interface EngineAttemptContext {
     readonly attemptId: string;
     /** Absolute directory every artifact of this attempt is written under. */
     readonly artifactsDir: string;
@@ -246,22 +308,22 @@ export interface BackendAttemptContext {
  * the budget is exhausted, so a hook that cannot finish in time stops instead
  * of running on into the next attempt's setup.
  */
-export interface BackendCleanupContext {
+export interface EngineCleanupContext {
     readonly signal: AbortSignal;
     /** Remaining cleanup budget when the call starts. */
     readonly timeoutMs: number;
 }
-export interface BackendObserveOptions {
+export interface EngineObserveOptions {
     /** Requests masked viewport pixels for the same revision as the tree. */
     readonly pixels?: boolean;
 }
 /**
  * One fresh semantic snapshot of the surface under test. The harness owns
  * everything downstream: revision minting, secret redaction, and the
- * observation byte budget apply to every backend equally.
+ * observation byte budget apply to every engine equally.
  */
-export interface BackendSnapshot {
-    /** Location captured with this tree, when the backend can provide it. */
+export interface EngineSnapshot {
+    /** Location captured with this tree, when the engine can provide it. */
     readonly url?: string;
     readonly nodes: readonly SemanticNode[];
     readonly viewport?: {
@@ -275,24 +337,24 @@ export interface BackendSnapshot {
     readonly maskedRegionCount?: number;
 }
 /** The body of one target: typed, model-free, capability-graded. */
-export interface Backend {
+export interface Engine {
     readonly name: string;
     /**
      * Implementation version, recorded as provenance and part of the trace
-     * cache identity: a backend that resolves nodes differently must not replay
-     * another version's traces, so an unversioned backend is not accepted.
+     * cache identity: an engine that resolves nodes differently must not replay
+     * another version's traces, so an unversioned engine is not accepted.
      */
     readonly version: string;
     /**
      * Contract version literal. Additive optional members never bump it;
      * changed required semantics do.
      */
-    readonly spiVersion: BackendSpiVersion;
+    readonly spiVersion: EngineSpiVersion;
     /** capability: observation. */
-    observe?(context: OperationContext, options?: BackendObserveOptions): Promise<BackendSnapshot>;
+    observe?(context: OperationContext, options?: EngineObserveOptions): Promise<EngineSnapshot>;
     /**
      * capability: actions - requires observation. Performs exactly one action
-     * on a ref this backend minted, from the newest observation or from
+     * on a ref this engine minted, from the newest observation or from
      * `locate` (both live in one id space), with the platform's actionability
      * checks. The agent's grammar verbs (tap, type, press, select, node scroll)
      * and the `screen` tier's actions both bottom out here, so a surface
@@ -308,7 +370,7 @@ export interface Backend {
      * capability: location - requires observation. Deterministic locator
      * resolution for the `screen`/`expect` tier: resolve one expression to the
      * nodes it currently matches. The harness owns polling, strictness, and
-     * staleness; a backend resolves once, immediately.
+     * staleness; an engine resolves once, immediately.
      */
     locate?(expression: LocatorExpression, context: OperationContext): Promise<readonly SemanticNode[]>;
     /**
@@ -317,17 +379,17 @@ export interface Backend {
      */
     swipe?(direction: ScrollDirection, momentum: Momentum | undefined, context: OperationContext): Promise<void>;
     /**
-     * Named deterministic surfaces this backend contributes to TestFixtures
+     * Named deterministic surfaces this engine contributes to TestFixtures
      * (a device fixture, a document fixture - anything). Keys become fixture and
      * capability names; `requires: ['<name>']` gates at selection.
      */
-    readonly fixtures?: Readonly<Record<string, BackendFixtureFactory>>;
+    readonly fixtures?: Readonly<Record<string, EngineFixtureFactory>>;
     /** capability: state - opaque snapshot capture/restore for session reuse. */
-    readonly state?: BackendStateCapability;
+    readonly state?: EngineStateCapability;
     /** capability: artifacts - screenshots and traces under the attempt directory. */
-    readonly artifacts?: BackendArtifacts;
-    /** App-level hooks: navigate, back, restart, clearState. */
-    readonly app?: BackendApp;
+    readonly artifacts?: EngineArtifacts;
+    /** The app under test: its declaration (url, identity, command...) and hooks (navigate, back, restart, clearState). */
+    readonly app?: EngineApp;
     /**
      * Current top-level URL of the surface, when the platform has one. Enables
      * trace start anchors and the secret-fill origin check.
@@ -335,40 +397,40 @@ export interface Backend {
     url?(context: OperationContext): Promise<string>;
     /**
      * Once per run and target, in the runner process, before any worker starts
-     * and outside every launch budget. Provision what the backend needs on this
+     * and outside every launch budget. Provision what the engine needs on this
      * machine here (a first-run browser download, a toolchain fetch), so it
      * happens once instead of per worker and its progress reaches the reporter
      * through `info.log`. Failure is infrastructure and ends the run before any
      * test executes.
      */
-    prepare?(info: BackendPrepareInfo): Promise<void>;
+    prepare?(info: EnginePrepareInfo): Promise<void>;
     /**
      * Once per worker, before the first step; boot devices here, not in a step
      * budget. The same handle can be booted again after `dispose`: a config-held
      * handle outlives an in-process worker, so init MUST work on a disposed
-     * backend as it does on a fresh one.
+     * engine as it does on a fresh one.
      */
-    init?(info: BackendInitInfo): Promise<void>;
+    init?(info: EngineInitInfo): Promise<void>;
     /** Before each attempt: set up per-test isolation. */
-    startAttempt?(context: BackendAttemptContext): Promise<void>;
+    startAttempt?(context: EngineAttemptContext): Promise<void>;
     /**
      * After each attempt, within the cleanup budget: tear that isolation down.
      * MUST be idempotent, and safe to call after a failed `startAttempt`.
      */
-    endAttempt?(context: BackendCleanupContext): Promise<void>;
+    endAttempt?(context: EngineCleanupContext): Promise<void>;
     /**
      * Worker shutdown, within the cleanup budget; failure is a run error. Runs
-     * whether or not `init` ran, so it MUST tolerate a cold backend.
+     * whether or not `init` ran, so it MUST tolerate a cold engine.
      */
-    dispose?(context: BackendCleanupContext): Promise<void>;
+    dispose?(context: EngineCleanupContext): Promise<void>;
 }
-/** A validated backend: branded, frozen, capabilities computed. */
-export interface BackendHandle extends Backend {
-    readonly [backendBrand]: true;
-    readonly capabilities: ReadonlySet<BackendCapability>;
+/** A validated engine: branded, frozen, capabilities computed. */
+export interface EngineHandle extends Engine {
+    readonly [engineBrand]: true;
+    readonly capabilities: ReadonlySet<EngineCapability>;
 }
 /**
- * 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.
  *
@@ -376,7 +438,7 @@ export interface BackendHandle extends Backend {
  * 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 declare function defineBackend(spec: Backend): BackendHandle;
-/** True for a defineBackend-branded handle, across realms. */
-export declare function isBackendHandle(value: unknown): value is BackendHandle;
+export declare function defineEngine(spec: Engine): EngineHandle;
+/** True for a defineEngine-branded handle, across realms. */
+export declare function isEngineHandle(value: unknown): value is EngineHandle;
 //# sourceMappingURL=index.d.ts.map

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

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