browser-broker 0.1.0

package/dist/src/browser/adoption.js

@@ -0,0 +1,143 @@
+/**
+ * Decide, under arbitration, what this caller should do about a browser.
+ *
+ * `runningRecord` is what the caller observed **before** calling — the
+ * verified discovery record if a browser is genuinely reachable, or
+ * `undefined` if not. It is a parameter rather than something read here for
+ * one reason: reading it means talking to a browser, and this runs inside the
+ * transaction.
+ *
+ * That ordering has a consequence worth stating rather than leaving to be
+ * discovered: the observation is made outside the lock, so it can be stale by
+ * the time the transaction opens. The `starting` state is what covers the gap
+ * — a caller whose observation said *nothing is running* still loses the race
+ * if another caller has already recorded that it is launching, and the store
+ * is what settles that rather than the observation.
+ */
+export async function decideAdoption(store, browser, runningRecord) {
+    return store.immediate(({ db }) => {
+        const row = db
+            .prepare('SELECT state, endpoint, browser_uuid FROM browsers WHERE id = ?')
+            .get(browser);
+        if (row === undefined) {
+            // The two rows are created by the first schema step and there is no
+            // delete operation on any surface, so this is a store that was not
+            // stepped rather than a browser that went missing.
+            throw new Error(`The store has no row for the ${browser} browser. The two rows are created by the first schema step, so this store has not been stepped.`);
+        }
+        // The caller verified a live browser. Record what it found and attach.
+        // This also repairs a row that says `stopped` while a browser is in fact
+        // running — which is the ordinary state after a process died between
+        // launching a browser and recording it.
+        if (runningRecord !== undefined) {
+            // `pid` is coalesced rather than overwritten, and the constraint is why
+            // it cannot simply be left alone: the row's check requires an
+            // identifier for every state that is not stopped, and this path moves a
+            // row to `running` that may be stopped, holding a null one.
+            //
+            // **Never overwritten**, because the identifier already there is the
+            // browser's and this process does not know it — the browser was adopted,
+            // not started here, so there is no handle to read one from. Writing this
+            // process's identifier over the browser's would corrupt the one fact
+            // §1.2 calls the isolation fact: the service acts on the process
+            // recorded here and on nothing else. Falling back to this process's
+            // identifier only when there is none at all keeps the row legal while
+            // never claiming to know something it does not; the browser's own
+            // identifier is restored by whichever caller launches it next.
+            db.prepare(`UPDATE browsers
+            SET state = 'running',
+                pid = COALESCE(pid, ?),
+                endpoint = ?,
+                browser_uuid = ?,
+                updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+          WHERE id = ?`).run(process.pid, runningRecord.endpoint, runningRecord.browserUuid, browser);
+            return {
+                value: {
+                    action: 'attach',
+                    browser,
+                    endpoint: runningRecord.endpoint,
+                    browserUuid: runningRecord.browserUuid,
+                },
+            };
+        }
+        // Nothing is running, and somebody else has already said they are
+        // starting it. One row, one winner — this caller is the loser and waits.
+        if (row.state === 'starting') {
+            return { value: { action: 'wait', browser } };
+        }
+        // Nothing is running and nobody has claimed the launch. Claim it here,
+        // inside the transaction, so a second caller arriving now sees
+        // `starting` and waits instead of launching a second browser.
+        //
+        // ── Why `pid` is this process and not the browser's ─────────────────
+        //
+        // The row's check constraint ties a null identifier to the stopped state
+        // and requires one for every other state, so `starting` cannot be
+        // recorded with a null identifier — and it must be recorded *before* a
+        // browser process exists, because claiming the race is the whole point of
+        // doing it inside the transaction. The browser's identifier is not a fact
+        // yet and writing a placeholder would be a lie the reclamation path
+        // branches on.
+        //
+        // So what is written is the identifier of **the process that is
+        // launching**, which is a true statement about the row for the duration
+        // it holds: during `starting`, the thing to look at if this browser never
+        // comes up is the caller that took the race. {@link recordLaunched}
+        // writes the browser's own identifier over it at the moment that becomes
+        // a fact, and {@link recordLaunchFailed} clears it back to null along
+        // with the state.
+        db.prepare(`UPDATE browsers
+          SET state = 'starting',
+              pid = ?,
+              endpoint = NULL,
+              browser_uuid = NULL,
+              updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+        WHERE id = ?`).run(process.pid, browser);
+        return { value: { action: 'launch', browser } };
+    });
+}
+/**
+ * Record a browser this caller successfully started.
+ *
+ * Separate from {@link decideAdoption} and called **after** the launch,
+ * because the launch is browser work and browser work does not happen inside
+ * the arbitration transaction. The two calls are two transactions by design,
+ * and the window between them is exactly what the `starting` state exists to
+ * describe. This writes the browser's own identifier over the placeholder the
+ * race left, at the moment it becomes a fact.
+ */
+export async function recordLaunched(store, browser, launched) {
+    await store.immediate(({ db }) => {
+        db.prepare(`UPDATE browsers
+          SET state = 'running',
+              pid = ?,
+              endpoint = ?,
+              browser_uuid = ?,
+              launched_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+        WHERE id = ?`).run(launched.pid, launched.endpoint, launched.browserUuid, browser);
+        return { value: undefined };
+    });
+}
+/**
+ * Record that a launch this caller won did not produce a browser.
+ *
+ * Without this, a caller that wins the race and then fails leaves the row at
+ * `starting` forever, and **every later caller waits for a launch that is
+ * never coming**. Releasing the race is therefore part of failing it, not
+ * cleanup that can be skipped.
+ */
+export async function recordLaunchFailed(store, browser) {
+    await store.immediate(({ db }) => {
+        db.prepare(`UPDATE browsers
+          SET state = 'stopped',
+              pid = NULL,
+              endpoint = NULL,
+              browser_uuid = NULL,
+              launched_at = NULL,
+              restart_count = restart_count + 1,
+              updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+        WHERE id = ?`).run(browser);
+        return { value: undefined };
+    });
+}

package/dist/src/browser/automation-probe.js

@@ -0,0 +1,113 @@
+// This is the browser module reaching the automation library for a doctor
+// probe — the one exception `driver.import_isolated` (`SCHEMA.md` §7.3)
+// already carves out is "only the browser module reaches the automation
+// library", and this file is that module doing so for a read rather than a
+// launch. It never opens a browser: it only asks the library where the
+// binary it would launch is supposed to be, and checks that path exists.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { chromium } from 'playwright-core';
+const require = createRequire(import.meta.url);
+/**
+ * `playwright-core`'s own version, read from its installed `package.json`
+ * rather than duplicated as a string constant here — a pin in `package.json`
+ * and a constant beside this code are two places that could disagree, and
+ * `node_modules` is the one that is actually running. Resolved once at
+ * module load: it cannot change without a fresh install, which this process
+ * would not observe anyway.
+ *
+ * Exported so a test can assert this specifically, independent of whether a
+ * browser binary has been fetched: resolving the *library's own* version
+ * from its `package.json` cannot depend on that, but reaching this value
+ * through {@link resolveAutomationProbe}'s `present: true` branch would —
+ * that branch requires `pathExists` to hold, which is exactly the thing a
+ * CI runner with no Chromium fetched cannot provide.
+ */
+export function resolvePlaywrightCoreVersion() {
+    try {
+        const manifestPath = require.resolve('playwright-core/package.json');
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const version = manifest.version;
+        return typeof version === 'string' ? version : undefined;
+    }
+    catch {
+        // The version is informational only — a failure to resolve it should not
+        // turn "is the automation tool present" into a thrown error.
+        return undefined;
+    }
+}
+/**
+ * Exported so a test can assert `libraryVersion` is actually wired into the
+ * dependency object the default resolution uses — not just that
+ * {@link resolvePlaywrightCoreVersion} works in isolation, which would not
+ * catch the two being disconnected again. Asserting through this constant
+ * needs no browser binary fetched, unlike asserting through
+ * {@link resolveAutomationProbe}'s `present: true` branch, which does.
+ */
+export const REAL_DEPENDENCIES = {
+    resolveExecutablePath: () => chromium.executablePath(),
+    pathExists: (candidate) => fs.existsSync(candidate),
+    libraryVersion: resolvePlaywrightCoreVersion(),
+};
+/**
+ * Resolve the doctor's automation probe for real.
+ *
+ * **This does not launch anything.** `chromium.executablePath()` only
+ * computes where the automation library expects its browser binary to sit —
+ * it neither downloads one nor verifies one is there, which is why the
+ * existence check is a second, separate step here rather than trusted as
+ * part of the first. A computed path that resolves to nothing is exactly the
+ * state a fresh machine following `docs/ROLLOUT.md` without ever having
+ * installed a browser binary would be in, and that state must report
+ * `present: false` — not throw, and not silently read as `unknown`.
+ *
+ * `resolveExecutablePath()` itself is not expected to throw on the versions
+ * this build pins, but a caller asking "is the automation tool present" is
+ * the last place that question should go unanswered because of an
+ * unexpected library error, so a thrown error is caught and reported as
+ * `present: false` with the error's message as the detail — rather than
+ * propagating and turning `broker doctor` itself into the failure.
+ */
+export function resolveAutomationProbe(dependencies = REAL_DEPENDENCIES) {
+    // `BROKER_DOCTOR_AUTOMATION_OVERRIDE` is **not** a documented configuration
+    // variable — it is not in `Environment` (`src/config/environment.ts`) or
+    // `.env.example`, and no operator should ever set it. It exists only so
+    // that a test spawning the real `broker` binary as a child process — with
+    // no seam to inject `AutomationProbeDependencies` through — can still pin
+    // this probe's answer deterministically, on a machine with or without a
+    // browser binary fetched. `present` and (optionally) `detail` come from the
+    // override, verbatim; unset, this branch is not taken and the real
+    // resolution below runs exactly as it always has.
+    const override = process.env.BROKER_DOCTOR_AUTOMATION_OVERRIDE;
+    if (override === 'present') {
+        return {
+            present: true,
+            version: dependencies.libraryVersion,
+            detail: 'Forced present for a test.',
+        };
+    }
+    if (override === 'absent') {
+        return { present: false, detail: 'Forced absent for a test.' };
+    }
+    let executablePath;
+    try {
+        executablePath = dependencies.resolveExecutablePath();
+    }
+    catch (error) {
+        return {
+            present: false,
+            detail: `Could not resolve where the automation tool's browser binary should be: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (!dependencies.pathExists(executablePath)) {
+        return {
+            present: false,
+            detail: `No browser binary at the path the automation tool resolved (${executablePath}). This build depends on playwright-core, which does not download a browser on install.`,
+        };
+    }
+    return {
+        present: true,
+        version: dependencies.libraryVersion,
+        detail: `Present at ${executablePath}.`,
+    };
+}

package/dist/src/browser/conformance/case.js

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/conformance/cases.js

@@ -0,0 +1,192 @@
+import { ARTIFACT_COLLECTION, READ_ARTIFACTS } from "../driver.js";
+/**
+ * The properties both driver implementations must satisfy, each argued.
+ *
+ * ── The selection rule, restated because it is the deliverable ───────────
+ *
+ * `case.ts` states it: a property belongs here when **the service reasons
+ * about it** — when a path in `src/` derives a decision from it, so two
+ * implementations disagreeing means the service decides differently against
+ * one than against the other. Everything below names that path.
+ *
+ * What that rule **excludes** is as much the point as what it admits, so the
+ * rejected candidates are recorded at the bottom of this file rather than
+ * silently omitted. A reader who wonders "why is navigation not pinned here"
+ * deserves the answer without having to reconstruct it.
+ *
+ * ── The keeper tab dominates this list, and that is not an accident ──────
+ *
+ * Four of the six properties are about the keeper. The reason is structural
+ * rather than a failure of imagination: the keeper is **the one object on
+ * this seam that the service must reason about without being able to address
+ * it**. Every other page is reached through a handle a caller holds, so a
+ * disagreement about it surfaces as an operation that fails. The keeper is
+ * reached through no handle at all — its whole specification is a set of
+ * *absences* (`SCHEMA.md` §3.15: never leased, never addressable, never
+ * counted), and an absence is precisely what a fixture can agree with while
+ * being wrong.
+ *
+ * That is why the original defect was a keeper defect, and why the properties
+ * that keep it from recurring are keeper properties.
+ */
+/** A discovery record shaped like one read off disk and then verified. */
+const RECORD = { endpoint: 'http://127.0.0.1:0', browserUuid: 'conformance' };
+export { RECORD as CONFORMANCE_RECORD };
+export const SEAM_PROPERTIES = [
+    {
+        name: 'the keeper tab is absent from listTabs',
+        rule: 'keeper.never_leased',
+        why: 'Reconciliation closes every listed page no live lease owns, and the keeper is owned by no lease by construction — so an implementation that lists it makes the destructive behaviour and the correct behaviour agree, and closing the keeper kills the shared signed-in browser (SCHEMA.md §3.15).',
+        check: async ({ session }) => {
+            const keeper = await session.ensureKeeperTab();
+            const listed = await session.listTabs();
+            // Named, not counted. A count would pass against an implementation that
+            // listed the keeper and omitted some *other* page — which is a second
+            // bug wearing this one's clothes, and reconciliation would then close a
+            // page a live lease owns.
+            if (listed.some((tab) => tab.driverTabId === keeper.driverTabId)) {
+                return `listTabs returned the keeper tab (${keeper.driverTabId}), so reconciliation would treat it as an unowned page and close it`;
+            }
+            return undefined;
+        },
+    },
+    {
+        name: 'a leased tab IS in listTabs, so the exclusion is not simply an empty answer',
+        rule: 'keeper.never_leased',
+        why: 'The property above is satisfied by an implementation whose listTabs always answers nothing — an assertion over an empty set passes forever and silently. Reconciliation reads this list to decide what exists, so an always-empty answer would make every recorded tab look vanished and close every live lease.',
+        check: async ({ session }) => {
+            await session.ensureKeeperTab();
+            const leased = await session.openTab();
+            const listed = await session.listTabs();
+            if (!listed.some((tab) => tab.driverTabId === leased.driverTabId)) {
+                return `listTabs did not return a tab this session had just opened (${leased.driverTabId}), so the list is not a live reading of what the browser has open`;
+            }
+            return undefined;
+        },
+    },
+    {
+        name: 'the keeper tab survives being named to closeTab',
+        rule: 'keeper.never_leased',
+        why: 'SCHEMA.md §3.15 and §7.3: the keeper is never addressable, and a caller cannot close what it cannot name. The handle ensureKeeperTab returns exists so the service can assert the tab is present, not so anything can drive it — an implementation on which that handle closes the keeper turns a lever the service holds for a safety check into the exact destructive act it is checking against.',
+        check: async ({ session }) => {
+            const keeper = await session.ensureKeeperTab();
+            // Closing is best effort by design (§2.4b), so this must not reject —
+            // and it must not do anything either. Both halves matter: a rejection
+            // would be a driver reporting a failure the service is specified to
+            // ignore, and a close would be the keeper gone.
+            await session.closeTab(keeper);
+            // ── What is asserted, and why it is identity rather than presence ────
+            //
+            // The keeper is **the one page on this seam with no observable except
+            // its own identity**: it is excluded from `listTabs` by the first
+            // property in this file, so "is it still open" cannot be asked through
+            // the seam at all. What *can* be asked is whether the tab the session
+            // now calls its keeper is the same one it called its keeper before —
+            // and because `ensureKeeperTab` is idempotent (the property below),
+            // a **changed** identifier means the original was destroyed and
+            // replaced. On a headed browser there would have been no second chance
+            // to replace it; the browser would already be gone.
+            //
+            // An earlier draft of this property asked whether the re-established
+            // keeper appeared in `listTabs`, and it was wrong in a way worth
+            // recording: an implementation that destroys the keeper and hands back
+            // a fresh handle keeps it out of the list too, so the check passed
+            // against the very mutation it was written for. It was caught by the
+            // control asserting its own mutation had applied.
+            const after = await session.ensureKeeperTab();
+            if (after.driverTabId !== keeper.driverTabId) {
+                return `closing the keeper destroyed it: the session called it ${keeper.driverTabId} before the close and ${after.driverTabId} after, so a caller holding that handle can end the shared browser`;
+            }
+            return undefined;
+        },
+    },
+    {
+        name: 'establishing the keeper twice yields one keeper, not two',
+        rule: 'keeper.present',
+        why: 'It is a spawn-time precondition checked on every spawn (SCHEMA.md §7.2), and this service is spawned per caller — so a non-idempotent implementation accumulates one uncounted page per spawn. Those pages are excluded from listTabs by the property above, which means reconciliation cannot see them either: the leak is invisible to the one mechanism built to find leaks.',
+        check: async ({ session }) => {
+            const first = await session.ensureKeeperTab();
+            const second = await session.ensureKeeperTab();
+            if (first.driverTabId !== second.driverTabId) {
+                return `two calls to ensureKeeperTab reported different tabs (${first.driverTabId} then ${second.driverTabId}), so each spawn establishes another keeper`;
+            }
+            return undefined;
+        },
+    },
+    {
+        name: 'a tab handle names the browser it belongs to',
+        rule: 'claim.browser_known',
+        why: 'Capacity is one total across both browsers (DECISIONS.md §6) and the store indexes a physical tab by (browser_id, driver_tab_id) — so a handle carrying the wrong browser is a row written against the wrong browser, and reconciliation then compares one browser’s pages against the other’s records.',
+        check: async ({ session }) => {
+            const described = session.describe();
+            const leased = await session.openTab();
+            const keeper = await session.ensureKeeperTab();
+            for (const [label, handle] of [
+                ['openTab', leased],
+                ['ensureKeeperTab', keeper],
+            ]) {
+                if (handle.browser !== described.browser) {
+                    return `${label} returned a handle naming the ${handle.browser} browser from a session describing itself as ${described.browser}`;
+                }
+            }
+            for (const tab of await session.listTabs()) {
+                if (tab.browser !== described.browser) {
+                    return `listTabs returned a handle naming the ${tab.browser} browser from a session describing itself as ${described.browser}`;
+                }
+            }
+            return undefined;
+        },
+    },
+    {
+        name: 'a cookie summary carries no value, on any implementation',
+        rule: 'read.cookies_no_values',
+        why: 'SCHEMA.md §7.1 makes this a shape rather than a refusal: the value field is absent, not masked. The service writes this structure straight to a file (real.ts read()), with no redaction step in between — so an implementation that added a value field would put cookie values on disk with no line of code anywhere saying so.',
+        check: async ({ session }) => {
+            const tab = await session.openTab();
+            const summaries = await session.cookies(tab);
+            // Asserted over the keys actually present rather than by reading a
+            // named field: `CookieSummary` has no `value`, so a test reading
+            // `summary.value` would not compile and could never fail. The runtime
+            // question — did this implementation put one there anyway — is only
+            // answerable by looking at what the object has.
+            for (const summary of summaries) {
+                const forbidden = Object.keys(summary).filter((key) => ['value', 'values', 'cookievalue'].includes(key.toLowerCase().replace(/[_-]/gu, '')));
+                if (forbidden.length > 0) {
+                    return `a cookie summary carried ${forbidden.join(', ')}, and the service writes this structure to disk verbatim`;
+                }
+            }
+            return undefined;
+        },
+    },
+];
+/**
+ * Properties that were considered and **deliberately left out**, with the
+ * reason each was rejected.
+ *
+ * ── Why the rejections are written down ─────────────────────────────────
+ *
+ * A list of what a suite covers invites the question of what it does not, and
+ * a reader who cannot find the answer assumes an omission is an oversight.
+ * Worse, the next person to extend this file re-derives the same candidates
+ * and adds the mechanical ones, because nothing recorded that they were
+ * weighed. This is the argument, kept next to the thing it is about.
+ *
+ * | Candidate | Why it is not here |
+ * |---|---|
+ * | **Navigation returns the post-redirect address** | The fake's navigation always arrives and never redirects. Pinning it would assert the fake's canned answer, not an agreement — real redirect behaviour needs a real server and belongs to the row that owns navigation. |
+ * | **`act` returns a fresh snapshot** | Both do, but the fake's path names no file on disk. The property the service reasons about is *that a snapshot came back*, which is type-level and already structural; *what is in it* is not comparable between the two by construction. |
+ * | **`settlePage` precedes `capture`** | This is an ordering the **pipeline** performs, not a property of either implementation — the seam deliberately splits the two calls so the ordering is the caller's. It is asserted against the fake's call log where sequences are observable, which is the right place for it. |
+ * | **Tab identifier spelling** | Nothing derives a decision from the format. Real uses the browser's own target id; the fake counts. Pinning it would only make the fake harder to change. |
+ * | **`detach` leaves tabs open** | Genuinely load-bearing (§1.2a is the measurement the shared-session design rests on) — but not checkable through the seam: after `detach` the real session's connection is closed, so there is no way to ask it what is open without attaching afresh, which needs a driver rather than a session. It stays a fake-log assertion in `fake.test.ts` and a measured claim in `real.ts`. |
+ * | **`openTab` establishes the keeper first** | **A real divergence, found by measuring: `real.ts` awaits `ensureKeeperTab()` as the first line of `openTab`; the fake does not.** It is left out because it is not observable through the seam — `listTabs` excludes the keeper by the first property above, so no sequence of seam calls distinguishes an implementation that established one from an implementation that did not. It is reported in the pull request rather than pinned here, because a property this file cannot check must not appear to be one it does. |
+ */
+export const REJECTED_PROPERTY_COUNT = 6;
+/**
+ * Every artefact whose collection model the service depends on.
+ *
+ * Exported for the suite's own completeness assertion rather than used here:
+ * `ARTIFACT_COLLECTION` decides whether asking for an artefact costs
+ * anything, and a member added to `ReadArtifact` without an entry there would
+ * make that question unanswerable for the new one.
+ */
+export const ARTIFACTS_WITH_A_COLLECTION_MODEL = READ_ARTIFACTS.filter((artifact) => ARTIFACT_COLLECTION[artifact] !== undefined);

package/dist/src/browser/conformance/run.js

@@ -0,0 +1,102 @@
+/** Roughly a sentence. A justification shorter than this is not an argument. */
+const JUSTIFICATION_MINIMUM_WORDS = 12;
+function wordCount(text) {
+    const trimmed = text.trim();
+    if (trimmed === '') {
+        return 0;
+    }
+    return trimmed.split(/\s+/u).length;
+}
+/**
+ * Run every property against every available implementation.
+ *
+ * Each property gets **its own session**, freshly opened and disposed. That is
+ * deliberate and it costs a browser page per property on the real subject:
+ * these properties open tabs and establish keepers, so a shared session would
+ * let one property's leftovers decide another's answer, and the order they
+ * happened to run in would become part of the specification.
+ */
+export async function runSeamConformance(options) {
+    const findings = [];
+    const skipped = [];
+    const subjectsRun = [];
+    const browser = options.browser ?? 'private';
+    let pairsRun = 0;
+    // An assertion evaluated over an empty set passes forever and silently, so
+    // the set is checked directly rather than only iterated.
+    if (options.properties.length === 0) {
+        findings.push({
+            kind: 'property-table-empty',
+            detail: 'the property table is empty, so every per-property assertion would pass vacuously',
+        });
+    }
+    const seen = new Set();
+    for (const property of options.properties) {
+        if (seen.has(property.name)) {
+            findings.push({
+                kind: 'property-name-duplicated',
+                property: property.name,
+                detail: `two properties are named "${property.name}", so a finding cannot be attributed to one of them`,
+            });
+        }
+        seen.add(property.name);
+        // The bar `cases.ts` sets is that every property is argued. An argument
+        // nobody wrote down is one nobody can check, and the mechanical entries
+        // this suite is meant to exclude are exactly the ones with nothing to say.
+        if (wordCount(property.why) < JUSTIFICATION_MINIMUM_WORDS) {
+            findings.push({
+                kind: 'property-unjustified',
+                property: property.name,
+                rule: property.rule,
+                detail: `"${property.name}" gives no argument for why the service reasons about it`,
+            });
+        }
+    }
+    for (const subject of options.subjects) {
+        const reason = subject.unavailable();
+        if (reason !== undefined) {
+            skipped.push({ subject: subject.name, reason });
+            continue;
+        }
+        subjectsRun.push(subject.name);
+        for (const property of options.properties) {
+            const opened = await subject.open(browser);
+            try {
+                const complaint = await property.check({ session: opened.session });
+                pairsRun += 1;
+                if (complaint !== undefined) {
+                    findings.push({
+                        kind: 'property-violated',
+                        subject: subject.name,
+                        property: property.name,
+                        rule: property.rule,
+                        detail: complaint,
+                    });
+                }
+            }
+            catch (error) {
+                pairsRun += 1;
+                findings.push({
+                    kind: 'property-threw',
+                    subject: subject.name,
+                    property: property.name,
+                    rule: property.rule,
+                    detail: `the property threw rather than reporting: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+            finally {
+                await opened.dispose();
+            }
+        }
+    }
+    // Every subject skipping is not the same as every subject passing, and a
+    // report that did not say so would be the exact defect this suite exists
+    // to close — a green result standing in for an unrun one.
+    if (subjectsRun.length === 0) {
+        findings.push({
+            kind: 'no-subject-ran',
+            detail: `no implementation of the seam could be exercised here, so this run proves nothing: ${skipped.map((entry) => `${entry.subject} (${entry.reason})`).join('; ') || 'none offered'}`,
+        });
+    }
+    return { findings, pairsRun, skipped, subjectsRun };
+}

package/dist/src/browser/conformance/subjects.js

@@ -0,0 +1,19 @@
+import { FakeBrowserDriver } from "../fake.js";
+import { CONFORMANCE_RECORD } from "./cases.js";
+/**
+ * The fake, which runs everywhere.
+ *
+ * A fresh driver per session rather than one shared across properties: the
+ * properties open tabs and establish keepers, so a shared driver would let
+ * one property's leftovers decide another's answer — and the two would then
+ * be being asked different questions depending on the order they ran in.
+ */
+export const fakeSubject = {
+    name: 'fake',
+    unavailable: () => undefined,
+    open: async (browser) => {
+        const driver = new FakeBrowserDriver();
+        const session = await driver.attach(browser, CONFORMANCE_RECORD);
+        return { session, dispose: () => Promise.resolve() };
+    },
+};