@e2edev/e2e 0.2.0

package/dist/backend/contract.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ *
+ * Everything here is capability vocabulary - semantic nodes, locator
+ * expressions, action kinds, the error contract - never a platform noun. A
+ * document platform, a simulator, and a desktop shell describe themselves with the same
+ * 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;
+/**
+ * Per-field bounds a backend 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 = [
+    'NODE_STALE',
+    'FRAME_NOT_FOUND',
+    'FRAME_AMBIGUOUS',
+    'NOT_ACTIONABLE',
+    'ACTION_MAY_HAVE_COMMITTED',
+    'OPERATION_TIMEOUT',
+    'CANCELLED',
+    'UNSUPPORTED_CAPABILITY',
+    'INVALID_STATE',
+    'BACKEND_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`.
+ */
+export const RETRYABLE_BACKEND_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
+ * into repeating an action that may have committed.
+ */
+export class BackendError 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.retryable = false;
+            return;
+        }
+        this.code = code;
+        this.retryable = options.retryable;
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/backend/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/backend/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AA+DrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAgGvC,+FAA+F;AAC/F,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,gBAAgB;IAChB,2BAA2B;IAC3B,mBAAmB;IACnB,WAAW;IACX,wBAAwB;IACxB,eAAe;IACf,iBAAiB;CACT,CAAC;AAIX;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAkC,IAAI,GAAG,CAAC;IAClF,YAAY;IACZ,iBAAiB;CAClB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,SAAS,CAAU;IAE5B,YACE,IAAsB,EACtB,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,cAAc,CAAC;QAC3B,IAAI,OAAO,CAAC,SAAS,IAAI,CAAC,6BAA6B,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;YAC9B,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/index.d.ts

@@ -0,0 +1,316 @@
+/**
+ * The backend contract (RFC0002): the typed, model-free body of one target.
+ *
+ * A backend 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
+ * 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.
+ *
+ * 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
+ * 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
+ * of silently demoting itself to a lower tier.
+ */
+import { backendBrand } 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';
+export type { TextMatch } from '../types.ts';
+export { Deadline, pollCondition, 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 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';
+/**
+ * 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 {
+    /**
+     * 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.
+     */
+    readonly baseUrl?: string;
+    /** Origins navigation and cookie policy admit. */
+    readonly allowedOrigins: readonly string[];
+}
+/** Context handed to a contributed fixture factory, once per attempt. */
+export interface BackendFixtureContext {
+    readonly targetName: string;
+    readonly app: BackendAppInfo & {
+        /**
+         * Resolves a navigation target against the base URL and the origin
+         * policy. Throws `APP_URL_REQUIRED` when no app URL is configured and
+         * `POLICY_DENIED` for a disallowed origin or scheme, so a fixture never
+         * re-implements the policy the harness owns.
+         */
+        resolveUrl(url: string): string;
+    };
+    /** Harness budgets, for fixtures that poll or navigate. */
+    readonly timeouts: {
+        readonly test: number;
+        readonly action: number;
+        readonly assertion: number;
+    };
+    /** Aborts with the attempt. */
+    readonly signal: AbortSignal;
+    /** Per-call operation budget: the action timeout (or an explicit one) plus the attempt signal. */
+    operation(timeoutMs?: number): OperationContext;
+    /** Registers a file the current step produced under the attempt artifact directory. */
+    attachArtifact(kind: 'screenshot' | 'trace' | 'video' | 'download' | 'log', relativePath: string): void;
+    /** Records the viewport the current step established. */
+    attachViewport(viewport: {
+        width: number;
+        height: number;
+        scale: number;
+    }): void;
+    /** Mints a public locator from a raw expression (a platform selector, say). */
+    locator(expression: LocatorExpression): Locator;
+    /** Mints a screen scope whose every query is wrapped by `scope` (a nested document, say). */
+    screen(scope: (expression: LocatorExpression) => LocatorExpression): Screen;
+    /**
+     * Attaches an expectation surface to a fixture object so `expect(fixture)`
+     * returns it. The harness records every matcher call as an assertion step
+     * named `expect.<matcher>`; the factory only decides what the matchers mean.
+     */
+    expectable<T extends object, E extends object>(target: T, factory: () => E): T & Expectable<E>;
+}
+/**
+ * A contributed fixture: any record of async methods, sync accessors, and
+ * nested namespaces. The harness owns how every async method call runs - a
+ * recorded, timeout-bounded step named `<fixture>.<method>` - and never
+ * learns what the methods mean. A synchronous member is an accessor and is
+ * returned as is.
+ */
+export type BackendFixtureFactory = (context: BackendFixtureContext) => object;
+/**
+ * An opaque, restorable snapshot of a backend'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.
+ */
+export interface BackendState {
+    readonly format: string;
+    readonly version: number;
+    readonly data: unknown;
+    /** Earliest moment the state is known to be invalid, if the backend knows one. */
+    readonly expiresAt?: string;
+}
+/**
+ * Platform-neutral state capture and restore. A setup test captures a
+ * snapshot; an ordinary test restores it at launch.
+ *
+ * Snapshots are credentials: cookies, tokens, and storage that authenticate
+ * 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
+ * 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
+ * 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>;
+}
+/**
+ * Evidence capture. Paths are relative to the attempt artifact directory the
+ * backend received in `startAttempt`.
+ */
+export interface BackendArtifacts {
+    /** 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. */
+    startTrace?(context: OperationContext): Promise<void>;
+    /** Stops the trace and returns its relative path. */
+    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`.
+ */
+export interface BackendApp {
+    /**
+     * Opens one URL the harness already resolved against the base URL and the
+     * origin policy. Absent on a surface without addressable locations.
+     */
+    navigate?(url: string, context: OperationContext): Promise<void>;
+    /** Navigates back once in the surface's history. */
+    back?(context: OperationContext): Promise<void>;
+    /** Recreates the execution context, keeping persisted state, and relaunches. */
+    restart?(context: OperationContext): Promise<void>;
+    /** Clears persisted client state and relaunches. */
+    clearState?(context: OperationContext): Promise<void>;
+}
+/** Run identity and harness-resolved facts handed to `init`, once per worker before the first step. */
+export interface BackendInitInfo {
+    readonly runId: string;
+    readonly targetName: string;
+    readonly app: BackendAppInfo;
+    /** Attribute the `testId` query resolves against. */
+    readonly testIdAttribute: string;
+    /** Whether the run asked for a visible surface (`--headed`). */
+    readonly headed: boolean;
+    /** Aborts on interrupt and when init exceeds the launch timeout; init must stop promptly. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Per-attempt isolation context. A backend 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 {
+    readonly attemptId: string;
+    /** Absolute directory every artifact of this attempt is written under. */
+    readonly artifactsDir: string;
+    /**
+     * Aborts with the attempt, and the moment `startAttempt` fails or exceeds
+     * the launch timeout: a hook still running then must stop, because the
+     * harness ends the attempt's isolation right behind it and may retry.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * Budget of one cleanup hook (`endAttempt`, `dispose`). `signal` aborts when
+ * 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 {
+    readonly signal: AbortSignal;
+    /** Remaining cleanup budget when the call starts. */
+    readonly timeoutMs: number;
+}
+export interface BackendObserveOptions {
+    /** 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.
+ */
+export interface BackendSnapshot {
+    readonly nodes: readonly SemanticNode[];
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+        readonly scale: number;
+    };
+    /** Masked pixels, when requested and producible; omitted otherwise. */
+    readonly pixels?: ObservationPixels;
+    /** Regions masked in `pixels`; the harness checks it covers every secure node. */
+    readonly maskedRegionCount?: number;
+}
+/** The body of one target: typed, model-free, capability-graded. */
+export interface Backend {
+    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.
+     */
+    readonly version: string;
+    /**
+     * Contract version literal. Additive optional members never bump it;
+     * changed required semantics do.
+     */
+    readonly spiVersion: BackendSpiVersion;
+    /** capability: observation. */
+    observe?(context: OperationContext, options?: BackendObserveOptions): Promise<BackendSnapshot>;
+    /**
+     * capability: actions - requires observation. Performs exactly one action
+     * on a ref this backend 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
+     * implements each action once.
+     *
+     * Error contract (load-bearing for trace replay): throw a retryable
+     * `NODE_STALE`-coded error when a ref no longer binds, and an
+     * `ACTION_MAY_HAVE_COMMITTED`-coded error when input may have reached the
+     * app - the harness never blindly repeats an uncertain mutation.
+     */
+    perform?(ref: NodeRef, action: LocatorAction, context: OperationContext): Promise<void>;
+    /**
+     * 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.
+     */
+    locate?(expression: LocatorExpression, context: OperationContext): Promise<readonly SemanticNode[]>;
+    /**
+     * Viewport-level swipe behind the agent's `scroll` verb, `screen.swipe`,
+     * and `scrollUntilVisible`; requires observation.
+     */
+    swipe?(direction: ScrollDirection, momentum: Momentum | undefined, context: OperationContext): Promise<void>;
+    /**
+     * Named deterministic surfaces this backend 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>>;
+    /** capability: state - opaque snapshot capture/restore for session reuse. */
+    readonly state?: BackendStateCapability;
+    /** capability: artifacts - screenshots and traces under the attempt directory. */
+    readonly artifacts?: BackendArtifacts;
+    /** App-level hooks: navigate, back, restart, clearState. */
+    readonly app?: BackendApp;
+    /**
+     * Current top-level URL of the surface, when the platform has one. Enables
+     * trace start anchors and the secret-fill origin check.
+     */
+    url?(context: OperationContext): Promise<string>;
+    /**
+     * 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.
+     */
+    init?(info: BackendInitInfo): Promise<void>;
+    /** Before each attempt: set up per-test isolation. */
+    startAttempt?(context: BackendAttemptContext): 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>;
+    /**
+     * Worker shutdown, within the cleanup budget; failure is a run error. Runs
+     * whether or not `init` ran, so it MUST tolerate a cold backend.
+     */
+    dispose?(context: BackendCleanupContext): Promise<void>;
+}
+/** A validated backend: branded, frozen, capabilities computed. */
+export interface BackendHandle extends Backend {
+    readonly [backendBrand]: true;
+    readonly capabilities: ReadonlySet<BackendCapability>;
+}
+/**
+ * Validates a backend 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.
+ *
+ * The handle is assembled member by member from the known keys, reading
+ * 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;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/backend/index.js

@@ -0,0 +1,219 @@
+/**
+ * The backend contract (RFC0002): the typed, model-free body of one target.
+ *
+ * A backend 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
+ * 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.
+ *
+ * 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
+ * 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
+ * of silently demoting itself to a lower tier.
+ */
+import { backendBrand } 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
+// the JSON-value rules for data a fixture returns.
+export { ConfigurationError, InfrastructureError, TestError } from '../internal/errors.js';
+export { validateJsonValue } from '../internal/json-value.js';
+export { describePattern, matchesText, toTextPattern } from '../internal/text.js';
+export { Deadline, pollCondition } 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. */
+const KNOWN_KEYS = [
+    'name',
+    'version',
+    'spiVersion',
+    'observe',
+    'locate',
+    'perform',
+    'swipe',
+    'fixtures',
+    'state',
+    'artifacts',
+    'app',
+    'url',
+    'init',
+    'startAttempt',
+    'endAttempt',
+    'dispose',
+];
+/** Keys of the nested manifests, closed like the top level. */
+const NESTED_KEYS = {
+    state: ['capture', 'restore'],
+    artifacts: ['screenshot', 'startTrace', 'stopTrace'],
+    app: ['navigate', 'back', 'restart', 'clearState'],
+};
+const FUNCTION_MEMBERS = [
+    'observe',
+    'locate',
+    'perform',
+    'swipe',
+    'url',
+    'init',
+    'startAttempt',
+    'endAttempt',
+    'dispose',
+];
+/** Universal fixture names a contribution may never shadow. */
+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}`);
+}
+/**
+ * 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.
+ */
+function nestedManifest(name, key, value, required = []) {
+    if (typeof value !== 'object' || value === null) {
+        throw invalid(name, `${key} must be an object`);
+    }
+    const allowed = NESTED_KEYS[key];
+    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(', ')}`);
+        }
+    }
+    const bound = {};
+    for (const member of allowed) {
+        const fn = source[member];
+        if (fn === undefined) {
+            if (required.includes(member))
+                throw invalid(name, `${key}.${member} must be a function`);
+            continue;
+        }
+        if (typeof fn !== 'function')
+            throw invalid(name, `${key}.${member} must be a function`);
+        bound[member] = fn.bind(source);
+    }
+    return bound;
+}
+/**
+ * Validates a backend 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.
+ *
+ * The handle is assembled member by member from the known keys, reading
+ * 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) {
+    if (typeof spec !== 'object' || spec === null) {
+        throw new ConfigurationError('INVALID_CONFIG', 'defineBackend requires a backend object');
+    }
+    if (typeof spec.name !== 'string' || spec.name.trim() === '') {
+        throw new ConfigurationError('INVALID_CONFIG', 'backend.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}`);
+    }
+    // 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.
+    if (Object.getPrototypeOf(spec) === Object.prototype) {
+        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`);
+            }
+        }
+    }
+    for (const member of FUNCTION_MEMBERS) {
+        if (spec[member] !== undefined && typeof spec[member] !== 'function') {
+            throw invalid(name, `${member} must be a function`);
+        }
+    }
+    const capabilities = new Set();
+    if (spec.observe !== undefined)
+        capabilities.add('observation');
+    if (spec.perform !== undefined) {
+        if (!capabilities.has('observation')) {
+            throw invalid(name, 'declares perform without observe: action targets are observation refs');
+        }
+        capabilities.add('actions');
+    }
+    if (spec.locate !== undefined) {
+        if (!capabilities.has('observation')) {
+            throw invalid(name, 'declares locate without observe: located nodes share the observation id space');
+        }
+        capabilities.add('location');
+    }
+    if (spec.swipe !== undefined && !capabilities.has('observation')) {
+        throw invalid(name, 'declares swipe without observe');
+    }
+    const handle = { name, version: spec.version, spiVersion: spec.spiVersion };
+    for (const member of FUNCTION_MEMBERS) {
+        const fn = spec[member];
+        if (fn !== undefined)
+            handle[member] = fn.bind(spec);
+    }
+    if (spec.fixtures !== undefined) {
+        if (typeof spec.fixtures !== 'object' || spec.fixtures === null) {
+            throw invalid(name, 'fixtures must be an object');
+        }
+        for (const [fixture, factory] of Object.entries(spec.fixtures)) {
+            if (!FIXTURE_NAME_PATTERN.test(fixture)) {
+                throw invalid(name, `fixture name "${fixture}" must be a lower-camel identifier`);
+            }
+            if (RESERVED_FIXTURES.has(fixture)) {
+                throw invalid(name, `fixture name "${fixture}" shadows a universal fixture`);
+            }
+            if (typeof factory !== 'function') {
+                throw invalid(name, `fixtures.${fixture} must be a factory function`);
+            }
+            capabilities.add(fixture);
+        }
+        // Bound like every other member, so a class-based backend keeps `this`
+        // in its fixture factories too.
+        handle['fixtures'] = Object.freeze(Object.fromEntries(Object.entries(spec.fixtures).map(([fixture, factory]) => [
+            fixture,
+            factory.bind(spec),
+        ])));
+    }
+    if (spec.state !== undefined) {
+        handle['state'] = nestedManifest(name, 'state', spec.state, ['capture', 'restore']);
+        capabilities.add('state');
+    }
+    if (spec.artifacts !== undefined) {
+        const artifacts = nestedManifest(name, 'artifacts', spec.artifacts, ['screenshot']);
+        if ((artifacts['startTrace'] === undefined) !== (artifacts['stopTrace'] === undefined)) {
+            throw invalid(name, 'artifacts.startTrace and stopTrace must be declared together');
+        }
+        handle['artifacts'] = artifacts;
+        capabilities.add('artifacts');
+    }
+    if (spec.app !== undefined)
+        handle['app'] = nestedManifest(name, 'app', spec.app);
+    // Assembled key by key above, so the record is a Backend by construction.
+    return Object.freeze({
+        ...handle,
+        [backendBrand]: true,
+        capabilities,
+    });
+}
+/** True for a defineBackend-branded handle, across realms. */
+export function isBackendHandle(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[backendBrand] === true);
+}
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

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

package/dist/backend/session.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The backend-to-session adapter (RFC0002). One adapter per attempt satisfies
+ * the internal `TargetSession` surface over the backend 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
+ * 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
+ * failure everywhere and never a retry-eligible test failure.
+ */
+import type { BackendHandle } from './index.ts';
+import { type TargetSession } from './surface.ts';
+export interface BackendSessionOptions {
+    readonly backend: BackendHandle | undefined;
+    readonly targetName: string;
+}
+/**
+ * Builds one session over a backend. One adapter per attempt; revisions are
+ * minted per adapter, so refs can never leak across attempts.
+ */
+export declare function createBackendSession(options: BackendSessionOptions): TargetSession;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/backend/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAmED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CA2IlF"}