@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/pool/playwright-launcher.js

@@ -0,0 +1,150 @@
+/**
+ * The real Playwright adapter behind BrowserPool: wraps `chromium.launch` into the pool's small
+ * PooledBrowser/Context/Page interfaces. Kept thin and separate so the pool's lifecycle logic stays
+ * unit-tested with a fake while this glue is exercised only by the e2e battery (it needs Chromium).
+ *
+ * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
+ */
+import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
+import { chromiumLaunchOptions } from '../../chromium-launch-options.js';
+import { getSessionMetrics } from '../../telemetry/session-metrics.js';
+import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
+import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
+import { installNetworkMocks } from '../input/network-mock.js';
+/**
+ * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
+ * the rest of this file needs a real Chromium.
+ *
+ * `waitUntil: 'domcontentloaded'` — NOT Playwright's default of `load`. `load` waits for every
+ * subresource, so an app with one that never finishes burns the whole nav budget and the lease then
+ * reports "is the app running?" about an app that is running. Measured on the sveltekit fixture:
+ * 30,501ms and a false diagnosis. The SDK connect is a module script and runs before
+ * DOMContentLoaded, and the pool separately waits for the session to register, so the load event was
+ * never what proved the page was usable.
+ */
+export function gotoOptions(timeoutMs) {
+    return {
+        waitUntil: 'domcontentloaded',
+        // Absent, not zero: zero means "no timeout" to Playwright, which would turn a slow page into a
+        // lease that never returns.
+        ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
+    };
+}
+function wrapBrowser(browser) {
+    return {
+        isConnected: () => browser.isConnected(),
+        newContext: async () => {
+            const context = await browser.newContext();
+            return {
+                newPage: async () => {
+                    const page = await context.newPage();
+                    return {
+                        goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
+                        close: () => page.close(),
+                        // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
+                        screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
+                        // Three moves, same as performGesture: a single move to the center can be a no-op if
+                        // the pointer was already there, and CSS :hover needs a native hit-test to apply.
+                        hover: async (x, y) => {
+                            await page.mouse.move(x, y);
+                            await page.mouse.move(x + 1, y);
+                            await page.mouse.move(x, y);
+                        },
+                        installMocks: (rules) => installNetworkMocks(page, [...rules]),
+                        setViewport: (size) => page.setViewportSize(size),
+                        onCrash: (handler) => page.on('crash', handler),
+                        onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
+                        onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
+                        addInitScript: async (script, arg) => {
+                            const handle = (await page.addInitScript(script, arg));
+                            const dispose = handle?.dispose;
+                            if ('function' !== typeof dispose) {
+                                throw new Error('Storage seeding failed: Playwright page.addInitScript did not return a disposable handle');
+                            }
+                            return { dispose: () => dispose() };
+                        },
+                    };
+                },
+                addCookies: (cookies) => context.addCookies(cookies),
+                close: () => context.close(),
+            };
+        },
+        close: () => browser.close(),
+        onDisconnected: (handler) => browser.on('disconnected', handler),
+    };
+}
+/**
+ * The fix for the most common first-run failure: Chromium isn't installed for Playwright.
+ *
+ * Pinned to the playwright this process bundles. Unpinned, `npx` fetches the latest playwright and
+ * installs ITS browser revision — a build this launcher will never look at — so the user follows the
+ * advice, it succeeds, and the next launch fails identically. Shares one builder with `doctor` so the
+ * two cannot suggest different commands for the same missing browser.
+ */
+const CHROMIUM_MISSING_HINT = `Chromium is not installed for Playwright. Run: ${chromiumInstallCommand(bundledPlaywrightVersion())}`;
+/**
+ * A DIFFERENT first-run failure from the one above: the browser binary is already there, but the
+ * host is missing the OS-level shared libraries (e.g. `libnspr4.so`) Playwright's own
+ * host-requirement check refuses to launch without. `npx playwright install chromium` does nothing
+ * for this — it re-downloads a binary that was never the problem — so this needs its own hint
+ * pointing at `install-deps`, pinned the same way and for the same reason as the one above.
+ */
+const CHROMIUM_MISSING_DEPS_HINT = `Chromium is installed, but the host system is missing shared-library dependencies it needs. Run: ${chromiumInstallDepsCommand(bundledPlaywrightVersion())}`;
+/** A Launcher that boots a real headless Chromium and adapts it to the pool's interface. */
+export function playwrightLauncher(opts = {}) {
+    const headless = opts.headless ?? true;
+    // `playwright` is an OPTIONAL dependency. A static value-import here would be pulled in by the
+    // server's main entry (index.ts re-exports this module) and crash the whole process with
+    // ERR_MODULE_NOT_FOUND on any install without Chromium — the CLI, the MCP server, everything.
+    // Import it lazily, only when a browser is actually launched, so absence fails at drive-time
+    // (where it's meaningful) instead of at import-time (where it kills unrelated features).
+    return async () => {
+        const { chromium } = await import('playwright');
+        // A pooled launch serves N parallel leases, so this counts BROWSERS, not contexts — which is the
+        // number that actually costs memory and the one that explains a slow machine.
+        const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
+        try {
+            const browser = wrapBrowser(await chromium.launch(chromiumLaunchOptions(headless)));
+            settle();
+            return browser;
+        }
+        catch (err) {
+            settle(classifyConnectFailure(err));
+            // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
+            const msg = err instanceof Error ? err.message : String(err);
+            // Checked FIRST: Playwright's host-requirement validation error also contains
+            // "browserType.launch", so the generic check below would otherwise misdiagnose it as a
+            // missing binary and send the user through a fix that changes nothing.
+            if (/host system is missing dependencies/i.test(msg)) {
+                throw new Error(CHROMIUM_MISSING_DEPS_HINT);
+            }
+            if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
+                throw new Error(CHROMIUM_MISSING_HINT);
+            }
+            throw err;
+        }
+    };
+}
+const MAX_CONTEXTS_CEILING = 8;
+const MAX_CONTEXTS_FLOOR = 1;
+/**
+ * Hard backstop for an EXPLICIT RETICLE_MAX_CONTEXTS. The operator override still wins for any
+ * realistic value (well above the CPU-derived ceiling), but a typo/abuse like 5000 can't spawn 5000
+ * browser contexts and exhaust memory/FDs — the fork-bomb the function's own comment warns about.
+ */
+const MAX_CONTEXTS_HARD_CEILING = 128;
+/**
+ * Resolve the pool's concurrency cap. An explicit RETICLE_MAX_CONTEXTS wins (clamped to
+ * [1, hard ceiling]); otherwise scale with the machine but never above the CPU-derived ceiling.
+ * Pure (env value + cpu count passed in) so it's testable.
+ */
+export function resolveMaxContexts(envValue, cpuCount) {
+    if (envValue !== undefined) {
+        const parsed = parseInt(envValue, 10);
+        if (!isNaN(parsed) && parsed >= MAX_CONTEXTS_FLOOR) {
+            return Math.min(MAX_CONTEXTS_HARD_CEILING, parsed);
+        }
+    }
+    const byCpu = Math.max(MAX_CONTEXTS_FLOOR, cpuCount - 1);
+    return Math.min(MAX_CONTEXTS_CEILING, byCpu);
+}

package/dist/portal/pool/pool-contract.d.ts

@@ -0,0 +1,116 @@
+/**
+ * What the pool drives, stated as interfaces and nothing else.
+ *
+ * A leaf: `storage-seed.ts` needs four of these shapes and had to import them back out of
+ * `browser-pool.ts`, which imports IT. Real Playwright `Page`/`BrowserContext`/`Browser` satisfy
+ * these structurally, which is how the pool stays testable without a real Chromium.
+ */
+/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
+export interface PooledPage {
+    goto(url: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+    /** Fires when THIS page's renderer crashes — lets the pool reclaim just this lease, not the fleet. */
+    onCrash(handler: () => void): void;
+    /**
+     * Fires for each console message the page logs. OPTIONAL: a fake that does not implement it makes
+     * the pool record nothing, which is the correct degradation — an absent dial address must read as
+     * "the page said nothing", never as "the page dialled correctly".
+     */
+    onConsole?(handler: (text: string) => void): void;
+    /**
+     * Capture the page as a PNG. OPTIONAL, like `onConsole`: a fake that does not implement it makes
+     * the pool report "no provider", which is the correct degradation — an absent screenshotter must
+     * read as "this context cannot be captured", never as a blank image that a visual diff would then
+     * compare against and pass.
+     */
+    screenshot?(opts?: {
+        fullPage?: boolean;
+    }): Promise<Uint8Array>;
+    /**
+     * Move the real pointer to (x, y) so CSS `:hover` applies. OPTIONAL, like `screenshot`: a fake
+     * that does not implement it makes hover refuse rather than dispatch a synthetic mouseover that
+     * reports dispatched/settled while the styles never ran.
+     */
+    hover?(x: number, y: number): Promise<void>;
+    /** Add an init script to run after document creation but before any page scripts run. */
+    addInitScript?<Arg>(script: ((arg: Arg) => void) | string, arg?: Arg): Promise<InitScriptHandle | void>;
+    /**
+     * Install (or clear) network mocks on this page. OPTIONAL: a fake that does not implement it
+     * makes `reticle_network_mock` refuse rather than claiming it stubbed a request it cannot intercept.
+     */
+    installMocks?(rules: readonly PooledMockRule[]): Promise<void>;
+    /**
+     * Resize this page's viewport. OPTIONAL, like `installMocks`: a fake that does not implement it
+     * makes `reticle_viewport` refuse rather than claim a resize the page never took.
+     *
+     * A lease IS a real browser page, so the resize was always possible — the tool simply had no route
+     * to it and consulted only the driven-provider path. On an SDK-only install there is no such
+     * provider, so mobile-only UI (a `lg:hidden` hamburger, a drawer that only mounts under a
+     * breakpoint) could not be driven at all without installing Playwright separately.
+     */
+    setViewport?(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Fires when the page opens a native `window.confirm`/`alert`/`prompt`. OPTIONAL, like `onConsole`:
+     * a fake that does not implement it means the pool cannot see or arbitrate the dialog, and the
+     * page is left to whatever the underlying engine does with no listener attached.
+     *
+     * The pool always dismisses on this handler (see `acquire`) — a page blocked on a native dialog
+     * previously wedged the whole session (every subsequent tool call timed out and no recovery
+     * existed short of restarting the daemon), because nothing in the stack ever answered it.
+     */
+    onDialog?(handler: (dialog: PooledDialog) => void): void;
+}
+/** A native dialog the page opened, handed to the pool so it can be dismissed instead of left blocking. */
+export interface PooledDialog {
+    /** The dialog's message text — kept for diagnostics (`BrowserPool#lastDialogMessage`). */
+    readonly message: string;
+    dismiss(): Promise<void>;
+}
+export interface InitScriptHandle {
+    dispose(): Promise<void>;
+}
+export interface PooledCookie {
+    name: string;
+    value: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * One interception rule the pool can install. Same fields as the drive-path mock rule, kept here so
+ * the pool does not import Playwright.
+ */
+export interface PooledMockRule {
+    urlContains: string;
+    method?: string;
+    status?: number;
+    body?: string;
+    contentType?: string;
+    delayMs?: number;
+    abort?: boolean;
+}
+/** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
+export interface PooledContext {
+    newPage(): Promise<PooledPage>;
+    close(): Promise<void>;
+    addCookies?(cookies: PooledCookie[]): Promise<void>;
+}
+/** The launched browser. Real Playwright `Browser` satisfies this. */
+export interface PooledBrowser {
+    isConnected(): boolean;
+    newContext(): Promise<PooledContext>;
+    close(): Promise<void>;
+    /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */
+    onDisconnected(handler: () => void): void;
+}
+/** Produces a freshly launched browser. Injected so tests can supply a fake. */
+export type Launcher = () => Promise<PooledBrowser>;

package/dist/portal/pool/pool-contract.js

@@ -0,0 +1,8 @@
+/**
+ * What the pool drives, stated as interfaces and nothing else.
+ *
+ * A leaf: `storage-seed.ts` needs four of these shapes and had to import them back out of
+ * `browser-pool.ts`, which imports IT. Real Playwright `Page`/`BrowserContext`/`Browser` satisfy
+ * these structurally, which is how the pool stays testable without a real Chromium.
+ */
+export {};

package/dist/portal/pool/storage-seed.d.ts

@@ -0,0 +1,23 @@
+import { type SeedStorage } from '@reticlehq/core';
+import type { InitScriptHandle, PooledContext, PooledCookie, PooledPage } from './pool-contract.js';
+export declare function targetOriginOf(navUrl: string): string | undefined;
+export declare function normalizeCookies(cookies: SeedStorage['cookies'], navUrl: string): PooledCookie[];
+export interface StorageSeedResult {
+    handle?: InitScriptHandle;
+    checkError?: () => void;
+}
+/**
+ * Seed initial storage state (cookies, localStorage, sessionStorage) into a leased context and page
+ * before the first navigation happens.
+ *
+ * Cookies are injected into the BrowserContext cookie jar so the initial HTTP GET to the target URL
+ * already carries the Cookie header (including httpOnly session cookies).
+ *
+ * Local and session storage are injected via an init script evaluated after document creation but
+ * before any inline or bundled application scripts run. The init script is scoped strictly to the
+ * top-level target origin document (not child iframes or external redirect origins).
+ *
+ * Returns a handle that allows the caller to dispose of the init script once the initial navigation
+ * has resolved, ensuring one-time semantics (reloads or future navigations do not reapply the seed).
+ */
+export declare function seedStorageInto(context: PooledContext, page: PooledPage, targetUrl: string, seed: SeedStorage): Promise<StorageSeedResult | void>;

package/dist/portal/realm/conformance-client.d.ts

@@ -0,0 +1,43 @@
+import { type Claim } from 'open-verification';
+import type { WebRealm } from './web-realm.js';
+/**
+ * The binding between the conformance driver and a live Reticle session.
+ *
+ * Three methods over a `WebRealm`, no new rules and no second adjudicator: every verdict comes from
+ * the specification's own `adjudicate`, so a score produced through this is a score against the
+ * published rules rather than against whatever Reticle happens to do.
+ *
+ * ── WHAT IT STILL CANNOT DO ─────────────────────────────────────────────────────────────────────
+ * Plant a defect. The suite inverts that contract deliberately — it cannot inject a fault into an
+ * application it does not own, so the implementation supplies a subject that answers
+ * `x-conformance.plant`. Reticle's own fixture does not answer it yet, so a full self-score is
+ * still out of reach and every scenario comes back ABSENT: the connection problem is solved here,
+ * the subject problem is not.
+ */
+/** What the driver needs, and nothing more. */
+export interface ConformanceClient {
+    hello(): Promise<{
+        channels: readonly string[];
+        commands: readonly string[];
+    }>;
+    command(name: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** How a person names a control, turned into a handle `command` will accept as `ref`. */
+    locate(query: unknown): Promise<readonly {
+        ref: string;
+        describes: string;
+    }[]>;
+    verify(claim: Claim): Promise<{
+        verdict: string;
+        ground: string;
+        reason?: string;
+    }>;
+}
+/**
+ * A client the conformance driver can drive, over one live session.
+ *
+ * `verify` opens a window, observes it, and hands everything to the specification's adjudicator.
+ * It deliberately does NOT consult Reticle's own verdict kernel: the point of a conformance run
+ * is to score an implementation against the published rules, and scoring it against its own
+ * rules would make every implementation conformant by construction.
+ */
+export declare function conformanceClient(realm: WebRealm, now: () => number): ConformanceClient;

package/dist/portal/realm/conformance-client.js

@@ -0,0 +1,227 @@
+import { adjudicate, assertionsHeld, Declaration, isDeterminismProfile, } from 'open-verification';
+import { CloseCondition, Grade, ProvenanceClass } from 'open-verification';
+/** How long a scenario's window is given before it is judged on what it saw. */
+const WINDOW_BUDGET_MS = 8_000;
+/**
+ * An observation that records a send and can never record its outcome.
+ *
+ * A one-way dispatch is the clearest case and the one that produced a false green: the caller
+ * gets no reply by construction, so no later event can tell anybody whether the effect happened.
+ * `presence` is exactly what that is worth -- something was there -- and the whole point of the
+ * grade is that presence may not buy a `yes`.
+ *
+ * Deliberately narrow. A request still IN FLIGHT is not included: it may settle inside the window
+ * and its settled event carries the outcome, so downgrading it would discard evidence the
+ * verifier is about to be given. That case is already handled, and handled in the right place --
+ * as a `still-in-flight` blind spot in coverage, which says "I stopped watching" rather than
+ * "this proves nothing".
+ */
+function provesOnlyDispatch(observation) {
+    const value = observation.value;
+    if ('object' !== typeof value || null === value)
+        return false;
+    return true === value.oneWay;
+}
+/**
+ * How this window actually closed, rather than how it hoped to.
+ *
+ * The binding used to report `closedBy: window.closes` -- the condition the window was OPENED
+ * with -- so `closedCleanly` was true by construction and clause 5 could never fire. A field
+ * always set to the happy value is the same defect as `impeaching`, which made clause 6
+ * unreachable: defined, deferred to somebody, and decided by nobody.
+ *
+ * The honest answer available here is the budget. If the window was still open when its budget
+ * ran out, the verifier stopped watching, and that is `budget-exhausted` whatever the window was
+ * waiting for. Quiescence itself is the realm's to measure; this is the part the binding knows.
+ */
+function closedBy(window, closedAt, settleUnmeasurable) {
+    // A throttled page is the case the specification singles out: *"'the verifier gave up' and
+    // 'this realm cannot measure the close condition' are different facts, and an implementation
+    // MUST NOT report the second as the first."* A hidden tab never flushes the frame quiescence
+    // is read from, and it is the NORMAL state for agent-driven verification, so reporting
+    // budget-exhausted here would make every backgrounded subject permanently unprovable at
+    // clause 5.
+    //
+    // The gap is reported instead as a non-impeaching `time` blind spot by the realm, which costs
+    // a claim nothing unless it reads `time`. This line is what stops the budget derivation
+    // overriding that.
+    if (settleUnmeasurable)
+        return window.closes;
+    return closedAt - window.openedAt >= window.budgetMs
+        ? CloseCondition.BUDGET_EXHAUSTED
+        : window.closes;
+}
+/**
+ * Evidence from what the realm observed, at the grades its own channel declaration assigns.
+ *
+ * Built here rather than by the realm, because a realm that produced evidence would be grading
+ * the weight of its own observations — the separation the specification exists to keep.
+ */
+function asEvidence(realm, observations, at) {
+    const declared = new Map(realm.channels().map((c) => [c.id, c]));
+    const out = [];
+    for (const observation of observations) {
+        const channel = declared.get(observation.channel);
+        if (channel === undefined)
+            continue; // observed on a channel we never declared: not evidence
+        out.push({
+            observation,
+            provenance: {
+                class: ProvenanceClass.OBSERVED,
+                source: 'reticle',
+                method: 'in-page instrumentation',
+                subject: realm.identity(),
+                at,
+            },
+            independence: channel.independence,
+            // The channel's grade is a CEILING, not every observation's grade. Taking it unconditionally
+            // is how `fire-and-forget` came back `yes`: a one-way `ipcRenderer.send` travels on `net`,
+            // `net` is declared consequence-grade, and so "something was dispatched and can never
+            // report an outcome" was counted as proof that the outcome happened.
+            //
+            // Reticle already knew better -- the desktop battery asserts that a one-way call is
+            // "reported as one-way with NO status", precisely because dispatched is not succeeded --
+            // and that knowledge stopped at the observer. This is the adapter's job: the specification
+            // supplies the two grades, and which one an observation deserves is a realm's judgement.
+            grade: provesOnlyDispatch(observation) ? Grade.PRESENCE : channel.grade,
+        });
+    }
+    return out;
+}
+/**
+ * A client the conformance driver can drive, over one live session.
+ *
+ * `verify` opens a window, observes it, and hands everything to the specification's adjudicator.
+ * It deliberately does NOT consult Reticle's own verdict kernel: the point of a conformance run
+ * is to score an implementation against the published rules, and scoring it against its own
+ * rules would make every implementation conformant by construction.
+ */
+export function conformanceClient(realm, now) {
+    /** The window the last action was performed inside, handed to the next `verify`. */
+    let open;
+    return {
+        async hello() {
+            // `describe` is REQUIRED by the interface and was called by nothing in this binding, so an
+            // implementation could have thrown from it and still earned a profile. It is exercised
+            // here rather than in a scenario because it is not a claim about an application: it is the
+            // question "can this implementation read its own subject at all", which belongs with the
+            // other two handshake answers.
+            //
+            // A failure refuses the run instead of scoring it. That is deliberately unlike a plant we
+            // cannot apply, which is ABSENT: ABSENT means *we* could not ask, and this means the
+            // implementation does not answer something the interface obliges it to.
+            let described;
+            try {
+                described = await realm.describe();
+            }
+            catch (error) {
+                throw new Error(`the implementation's describe() threw, and the interface requires it: ${String(error)}`);
+            }
+            if (described === undefined) {
+                throw new Error("the implementation's describe() answered nothing, and it is required");
+            }
+            /*
+             * `determinism()` is required too, and reading it here is what stops it being decorative.
+             *
+             * A member no binding ever calls can be stubbed or thrown from and the implementation still
+             * earns a profile — the same hole `describe()` above was closed for. The shape is checked
+             * rather than taken on trust because the derived strategy falls through to "re-drive the
+             * prefix" for anything it does not recognise: a stubbed `{}` would quietly authorise
+             * re-driving a payment service's prefix.
+             *
+             * What is NOT checked is whether the declaration is TRUE. A realm claiming `free` that cannot
+             * afford it is telling the same kind of lie as one declaring a channel it cannot observe, and
+             * only driving the subject can catch either.
+             */
+            if (!isDeterminismProfile(realm.determinism())) {
+                throw new Error("the implementation's determinism() did not return a complete profile, and the interface " +
+                    'requires one: { reset, replayPrefix, time, observation, actions }. Silence here would ' +
+                    'be read as "this subject may be re-driven freely".');
+            }
+            // Both answers below are already declared; the interface is async for an implementation
+            // that has to go and ask.
+            return {
+                channels: realm.channels().map((c) => c.id),
+                commands: realm.capabilities().map((c) => c.name),
+            };
+        },
+        locate(query) {
+            // A read, so it returns data. It cannot go through `command`, which reports a receipt and
+            // never results -- the separation that stops an action reporting whether it worked.
+            return realm.locate === undefined ? Promise.resolve([]) : realm.locate(query);
+        },
+        async command(name, args = {}) {
+            // The window must be opened BEFORE the action — a window opened in `verify()` contains
+            // nothing, because the action has already happened. That is the specification's ordering: a
+            // claim is registered before the action and a window is opened to hold what follows.
+            //
+            // The budget is the subject's to shorten. One scenario needs a window that runs out before
+            // the application settles -- the verifier giving up, which must never be read as the
+            // application failing -- and there is no way to produce that without asking for less time
+            // than the work takes.
+            const budget = 'number' === typeof args['budgetMs'] ? args['budgetMs'] : WINDOW_BUDGET_MS;
+            open = realm.openWindow(budget);
+            const receipt = await realm.perform({
+                id: `conformance-${String(now())}`,
+                actor: 'conformance',
+                capability: name,
+                ...('string' === typeof args['ref'] ? { target: args['ref'] } : {}),
+                parameters: args,
+                at: now(),
+            });
+            // A refusal is reported as a refusal, never as a plant that quietly failed. The driver
+            // scores an unplantable scenario ABSENT, which is the honest outcome and is never a pass.
+            return receipt.dispatched
+                ? { planted: true, ...args }
+                : { planted: false, reason: receipt.refused?.detail ?? 'refused' };
+        },
+        async verify(claim) {
+            // The window opened by `command`, holding what the action caused. Falling back to a fresh
+            // one keeps a caller that verifies without acting honest rather than crashing -- it will
+            // observe nothing and be told so.
+            const window = open ?? realm.openWindow(WINDOW_BUDGET_MS);
+            open = undefined;
+            const closedAt = now();
+            const observations = await realm.observe(window);
+            const coverage = await realm.coverage(window);
+            const decided = adjudicate({
+                claim: { ...claim, declaredAt: claim.declaredAt ?? Declaration.BEFORE_ACTION },
+                window: {
+                    ...window,
+                    closedAt: closedAt,
+                    closedBy: closedBy(window, closedAt, realm.settleWasThrottled()),
+                },
+                channels: realm.channels(),
+                evidence: asEvidence(realm, observations, now()),
+                coverage,
+                // Asked for, at last. The binding passed an empty array for as long as the interface
+                // had no way to return one, and three planted defects came back `yes` because of it.
+                anomalies: realm.detect === undefined ? [] : await realm.detect(window, observations),
+                // The specification evaluates its own predicate forms, so this is a real answer now
+                // rather than a shrug. Still three-valued: a claim written in a language the
+                // specification does not speak comes back `undefined`, which means nobody evaluated it
+                // and must never be read as either pass or fail.
+                assertionsHeld: assertionsHeld(claim.assertions, observations),
+                // NOT supplied, and deliberately left `undefined` rather than `false`. The
+                // specification reads `undefined` here as NOBODY CHECKED and `false` as "checked, and
+                // it did not already hold" -- so passing `false` to fill the field would be a lie that
+                // scores better, which is the one thing a conformance client must never do.
+                //
+                // It is not supplied because this client cannot answer it: the window opens at
+                // `command` and the claim only arrives here at `verify`, so at the moment the
+                // before-state could be read there is nothing yet to evaluate against. Answering it
+                // needs the claim declared before the action, which the protocol already has a word
+                // for (`Declaration.BEFORE_ACTION`) and this binding does not yet act on.
+                //
+                // The cost is exact and worth writing down: clause 10 (`already-true`) is the one
+                // adjudication clause no run of this suite can reach. Pinned in
+                // conformance/subjects/coverage.test.mjs so closing this gap deletes a line there.
+            });
+            return {
+                verdict: decided.verdict,
+                ground: decided.ground,
+                ...(decided.reasons[0] === undefined ? {} : { reason: decided.reasons[0] }),
+            };
+        },
+    };
+}

package/dist/portal/realm/http-witness.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The reference witness: a second vantage point that can look and cannot touch.
+ *
+ * Every channel a `Realm` declares is, in the end, the subject describing itself — the DOM says the
+ * DOM changed, the store says the store changed. That is enough for most questions and useless for
+ * the one that matters most: *did the thing the app claims to have done actually happen out in the
+ * world?* Clicking "Delete account" changes the screen AND drops a row, sends an email, revokes a
+ * session in another tab. Every one of those is invisible to an in-subject observer, and every one
+ * of them is where the expensive bugs live.
+ *
+ * This reads a real HTTP endpoint over the real network, in a different process from the page. No
+ * fixture, no recorded response, no stub in the product path: a witness consulting a canned answer
+ * is the subject describing itself with extra steps, and the evidence would be worth nothing.
+ *
+ * `open-verification` ships the abstraction and requires it be proved twice. This is the second proof.
+ */
+import { Witness, type ChannelDescriptor, type Coverage, type Observation, type SubjectRef, type Window } from 'open-verification';
+/** Everything it needs from outside itself — no globals, no ambient clock. */
+export interface HttpWitnessInput {
+    /** What to ask. A read-only endpoint: a witness that mutated would stop being one. */
+    url: string;
+    fetch: (url: string) => Promise<{
+        ok: boolean;
+        status: number;
+        text(): Promise<string>;
+    }>;
+    now: () => number;
+}
+export declare class HttpWitness extends Witness {
+    #private;
+    constructor(input: HttpWitnessInput);
+    identity(): SubjectRef;
+    /**
+     * `net`, and INDEPENDENT — which is the entire reason asking is worth anything.
+     *
+     * The page's own network channel is actuation-derived: it reports the requests the page made. This
+     * one is the answer read back from outside the page, so it can contradict the app rather than
+     * echo it, and it is graded at `consequence` for exactly that reason.
+     */
+    channels(): readonly ChannelDescriptor[];
+    openWindow(budgetMs: number): Window;
+    observe(window: Window): Promise<readonly Observation[]>;
+    /**
+     * An empty `blindSpots` is a POSITIVE claim that nothing was hidden, so it is only ever returned
+     * after a look that actually completed.
+     */
+    coverage(window: Window): Promise<Coverage>;
+}