browser-broker 0.1.0

package/dist/src/adapter/conformance/drivers.js

@@ -0,0 +1,36 @@
+import { cliConformanceDriver } from "../../cli/conformance-driver.js";
+import { toolStdioConformanceDriver } from "../../tool/conformance-driver.js";
+/**
+ * One conformance driver per mounted route.
+ *
+ * ── This object is the compile-time half of "an unregistered adapter fails
+ *    the suite" ──────────────────────────────────────────────────────────
+ *
+ * Its type is `Record<AdapterId, ConformanceDriver>`, and `AdapterId` is
+ * `keyof typeof ADAPTER_REGISTRY` — **the registry the application mounts
+ * through**, not a list kept beside it. So the moment a route is added to
+ * that registry, this object stops compiling with
+ * `Property '<id>' is missing`, and the only way to make it compile is to
+ * write that route's driver.
+ *
+ * `MILESTONES.md` asks for exactly this: "in a map typed from the route
+ * registry the application actually mounts through, so adding a route without
+ * adding its driver does not compile."
+ *
+ * ── What it does not catch, said plainly ────────────────────────────────
+ *
+ * A module that implements {@link Adapter} and was **never added to the
+ * registry** is invisible here — no type can see a file nobody imported. That
+ * half is closed at run time by the discovery walk in `discovery.ts`, which
+ * finds adapter modules on disk and asserts each is registered. Neither half
+ * substitutes for the other, and a reader who assumed this map alone was the
+ * mechanism would be wrong in the direction that matters.
+ *
+ * **Do not widen this to `Partial`, and do not add an index signature.**
+ * Either change converts the compile error into a silently absent row in the
+ * matrix, which is the failure this file exists to prevent.
+ */
+export const CONFORMANCE_DRIVERS = {
+    'tool-stdio': toolStdioConformanceDriver,
+    cli: cliConformanceDriver,
+};

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

@@ -0,0 +1,224 @@
+import { ADAPTER_IDS } from "../contract.js";
+import { isWriteOperation, OPERATION_NAMES } from "../operations.js";
+/** Roughly four words, the same bar the hygiene gate holds a waiver to. */
+const WAIVER_MINIMUM_WORDS = 4;
+function wordCount(text) {
+    const trimmed = text.trim();
+    if (trimmed === '') {
+        return 0;
+    }
+    return trimmed.split(/\s+/u).length;
+}
+/**
+ * Run the suite.
+ *
+ * Every route in {@link ADAPTER_IDS} is visited — the list comes from the
+ * registry the application mounts through, so a mounted route cannot be
+ * skipped by this file not mentioning it.
+ */
+export async function runConformance(options) {
+    const findings = [];
+    const rulesObserved = new Set();
+    let pairsRun = 0;
+    // An assertion evaluated over an empty set passes forever and silently
+    // (`MILESTONES.md`), so both sets are checked directly rather than only
+    // being iterated.
+    if (options.rules.names.length === 0) {
+        findings.push({
+            kind: 'rule-registry-empty',
+            detail: 'the rule registry is empty, so every per-rule assertion would pass vacuously',
+        });
+    }
+    if (options.cases.length === 0) {
+        findings.push({
+            kind: 'case-table-empty',
+            detail: 'the case table is empty, so the conformance matrix would be empty',
+        });
+    }
+    const knownOperations = new Set(OPERATION_NAMES);
+    for (const adapterId of ADAPTER_IDS) {
+        const driver = options.drivers[adapterId];
+        const { adapter } = driver;
+        const offered = new Set();
+        for (const operation of adapter.operations) {
+            if (!knownOperations.has(operation)) {
+                findings.push({
+                    kind: 'unknown-operation-offered',
+                    adapter: adapterId,
+                    detail: `offers "${String(operation)}", which is not an operation this service has`,
+                });
+                continue;
+            }
+            offered.add(operation);
+        }
+        const waived = new Set();
+        for (const waiver of adapter.waivers) {
+            // A waiver has to say something. An empty one silences the assertion
+            // without leaving anything in the diff for a reviewer to disagree with.
+            if (wordCount(waiver.reason) < WAIVER_MINIMUM_WORDS) {
+                findings.push({
+                    kind: 'waiver-not-permitted',
+                    adapter: adapterId,
+                    operation: waiver.operation,
+                    detail: 'the waiver does not give a reason',
+                });
+                continue;
+            }
+            // `MILESTONES.md`: no operation any registered rule can refuse may be
+            // waived by a route that exposes any write operation. A route is
+            // read-only by declaration, or fully covered, with nothing in between —
+            // otherwise a driver that declines to expose anything passes the first
+            // assertion vacuously.
+            if (!adapter.readOnly && isWriteOperation(waiver.operation)) {
+                findings.push({
+                    kind: 'waiver-not-permitted',
+                    adapter: adapterId,
+                    operation: waiver.operation,
+                    detail: 'a route exposing a write operation may not waive one; declare the route read-only, or cover it',
+                });
+                continue;
+            }
+            waived.add(waiver.operation);
+        }
+        for (const operation of OPERATION_NAMES) {
+            if (!offered.has(operation) && !waived.has(operation)) {
+                findings.push({
+                    kind: 'operation-neither-offered-nor-waived',
+                    adapter: adapterId,
+                    operation,
+                    detail: 'neither offered nor carrying a written waiver',
+                });
+            }
+        }
+        for (const testCase of options.cases) {
+            if (!offered.has(testCase.operation)) {
+                continue;
+            }
+            const subject = await options.makeService();
+            try {
+                // What the seed established, merged over the case's own input. See
+                // `CaseSeed.apply` for why some of it can only be known here.
+                const substitutions = (await testCase.seed?.apply(subject.service)) ?? {};
+                const seeded = {
+                    ...testCase,
+                    input: { ...testCase.input, ...substitutions },
+                };
+                // **Read after the seed, not before it.** A seed that mints a lease
+                // moves the claim count, and a baseline taken before it would make
+                // every keyed case look as though the operation itself had moved the
+                // count — turning assertion 2 into a test of the fixture.
+                const claimsBefore = subject.liveClaimCount();
+                const callsBefore = subject.driverCalls().length;
+                const observation = await driver.run(subject.service, seeded, {
+                    driverCalls: subject.driverCalls,
+                    liveClaimCount: subject.liveClaimCount,
+                });
+                pairsRun += 1;
+                const { outcome } = observation;
+                if (outcome.outcome === 'refused') {
+                    rulesObserved.add(outcome.rule);
+                }
+                if (testCase.expect.outcome !== outcome.outcome) {
+                    findings.push({
+                        kind: 'outcome-mismatch',
+                        adapter: adapterId,
+                        operation: testCase.operation,
+                        caseName: testCase.name,
+                        // **The refusal's own code and rule are carried**, not just the
+                        // fact that the outcomes differed. `MILESTONES.md` #72 is the
+                        // reason: an intermittent failure here read only "expected
+                        // accepted, got refused", which names no rule and so gives a
+                        // reader nothing to attribute it to — two separate
+                        // investigations reproduced it and still could not say which
+                        // guard had fired. The rule name was the whole diagnosis, and it
+                        // was being discarded one line before it could be reported.
+                        detail: outcome.outcome === 'refused'
+                            ? `expected ${testCase.expect.outcome}, got ${outcome.outcome} (${outcome.code} / ${outcome.rule})`
+                            : `expected ${testCase.expect.outcome}, got ${outcome.outcome}`,
+                    });
+                }
+                else if (testCase.expect.outcome === 'refused' && outcome.outcome === 'refused') {
+                    // The code and the rule are compared; the sentence never is
+                    // (`SCHEMA.md` §3.14) — asserting text is brittle and a weaker
+                    // claim than asserting the code.
+                    if (outcome.code !== testCase.expect.code || outcome.rule !== testCase.expect.rule) {
+                        findings.push({
+                            kind: 'outcome-mismatch',
+                            adapter: adapterId,
+                            operation: testCase.operation,
+                            caseName: testCase.name,
+                            detail: `expected ${testCase.expect.code} / ${testCase.expect.rule}, got ${outcome.code} / ${outcome.rule}`,
+                        });
+                    }
+                }
+                if (outcome.outcome === 'refused') {
+                    // Both readings, because they catch different bugs (§8.2): a guard
+                    // that opens a tab and closes it on the way to refusing leaves the
+                    // count unchanged and the log full; a guard that decrements a
+                    // counter without telling the browser leaves the log empty and the
+                    // count wrong.
+                    const callsDuring = observation.driverCalls.slice(callsBefore);
+                    if (callsDuring.length > 0) {
+                        findings.push({
+                            kind: 'refusal-touched-the-browser',
+                            adapter: adapterId,
+                            operation: testCase.operation,
+                            caseName: testCase.name,
+                            detail: `a refusal asked the browser to ${callsDuring.map((call) => call.name).join(', ')}`,
+                        });
+                    }
+                    if (observation.liveClaimCount !== claimsBefore) {
+                        findings.push({
+                            kind: 'refusal-moved-the-claim-count',
+                            adapter: adapterId,
+                            operation: testCase.operation,
+                            caseName: testCase.name,
+                            detail: `a refusal moved the live claim count from ${String(claimsBefore)} to ${String(observation.liveClaimCount)}`,
+                        });
+                    }
+                }
+            }
+            finally {
+                await subject.dispose?.();
+            }
+        }
+    }
+    // §8.3 — every operation some route offers has both a case that succeeds
+    // and a case that is refused. Computed over the operations actually
+    // offered, so an operation no route has reached yet is not a failing
+    // assertion about work nobody has done.
+    const offeredAnywhere = new Set();
+    for (const adapterId of ADAPTER_IDS) {
+        for (const operation of options.drivers[adapterId].adapter.operations) {
+            offeredAnywhere.add(operation);
+        }
+    }
+    for (const operation of OPERATION_NAMES) {
+        if (!offeredAnywhere.has(operation)) {
+            continue;
+        }
+        const forOperation = options.cases.filter((testCase) => testCase.operation === operation);
+        const accepts = forOperation.some((testCase) => testCase.expect.outcome === 'accepted');
+        const refuses = forOperation.some((testCase) => testCase.expect.outcome === 'refused');
+        if (!accepts || !refuses) {
+            findings.push({
+                kind: 'operation-without-both-cases',
+                operation,
+                detail: accepts ? 'has no case that is refused' : 'has no case that succeeds',
+            });
+        }
+    }
+    // §8.4 — every rule appears in at least one refusal **the service actually
+    // produced**, computed from what came back rather than from what a case
+    // declared. A case naming a rule the service never returned does not
+    // satisfy this, which is what keeps the suite honest a year from now.
+    for (const rule of options.rules.names) {
+        if (!rulesObserved.has(rule)) {
+            findings.push({
+                kind: 'rule-without-a-case',
+                detail: `rule "${rule}" was never produced by a refusal in this run`,
+            });
+        }
+    }
+    return { findings, pairsRun, rulesObserved: [...rulesObserved].sort() };
+}

package/dist/src/adapter/conformance/service-subject.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { FakeBrowserDriver } from "../../browser/fake.js";
+import { countActiveClaims } from "../../service/capacity.js";
+import { createRuntime } from "../../service/runtime.js";
+/**
+ * The **real service**, as the conformance suite's subject.
+ *
+ * ── Why the suite's subject has to be this and not a stand-in ───────────
+ *
+ * §8 asks whether **the rules are the same through every door**. A subject
+ * that implements the case table's rules itself cannot answer that: the rules
+ * being compared are the stand-in's, so a green matrix says only that each
+ * route carries an outcome faithfully — a much narrower claim, and one that
+ * holds just as well against a service enforcing something else entirely.
+ *
+ * `createRuntime` builds the service both shipped binaries build: the real
+ * store, the real schema, the real artifact store, the real broker, the real
+ * bridge. With it behind the seam, every assertion in `run.ts` is an
+ * assertion about enforcement, and no case or driver has to be shaped
+ * differently to get there — which is what the seam is for.
+ *
+ * ── The one thing that is faked, and the argument for faking it ─────────
+ *
+ * **The browser driver.** Continuous integration runs headless with no
+ * browser binary, and the two routes are spawned there on every change; a
+ * subject that needed a real browser would make the parity suite unrunnable
+ * in the one place it most needs to run.
+ *
+ * **A real service over a fake driver is still the real service**, and that
+ * is not a concession — it is the right shape for this particular assertion.
+ * §8's four assertions are about *rules*: the same acceptance or the same
+ * refusal code and rule name on every route, a refusal that touches no
+ * browser and moves no claim count, every operation covered both ways, every
+ * rule produced by a real refusal. Not one of them is a claim about what a
+ * page does. Every rule those assertions are about is enforced inside the
+ * arbitration transaction, before any browser is reached — §2.4b guarantees
+ * exactly that — so the driver is downstream of everything under test.
+ *
+ * What the fake buys, beyond running at all, is the **second half of
+ * assertion 2**: `SCHEMA.md` §8 requires that a refusal never touched the
+ * browser, and "never touched" is only checkable against something that
+ * records being touched. A real browser would have to be interrogated about
+ * what it did; the fake keeps an ordered log, which is a stronger reading of
+ * the same property.
+ *
+ * **What it therefore does not prove, stated plainly:** that a page navigates,
+ * that a capture contains pixels, or that any verb does its physical work.
+ * Those belong to the browser suites, which are local-only for the same
+ * reason this is not. A green run here is evidence about rules and routes, and
+ * reading it as evidence about browsers would be over-reading it.
+ *
+ * ── Isolated per case, because the runner asks for that ─────────────────
+ *
+ * `ConformanceRunOptions.makeService` is called **per case-and-route pair**,
+ * so each subject below gets its own temporary directory and its own store. A
+ * shared store would let one case's claim be visible to the next, and the
+ * claim-count assertion would then be reading somebody else's leftovers.
+ * `dispose` removes the tree.
+ */
+/** Every rule the real service produces in this suite's run. */
+export const SERVICE_RULE_REGISTRY = {
+    names: [
+        'key.present',
+        'key.valid',
+        'claim.browser_known',
+        'claim.purpose_bounded',
+        'tab.owned',
+        'navigate.scheme_allowed',
+        'act.action_known',
+        'evaluate.expression_bounded',
+        'capture.exclusive_mode',
+        'feedback.rating_in_scale',
+        // The sign-in request's own bound. It is the only one of the three
+        // §5.5.2 rules a conformance case reaches, and that is deliberate rather
+        // than an omission: this registry is *"every rule the real service
+        // produces in this suite's run"*, and the suite asserts equality in both
+        // directions — so a name listed here that no case produces fails just as
+        // loudly as one produced and not listed. `signin.requester_holds_tab` and
+        // `signin.finish_owned` are exercised by the service tests, where a
+        // second lease and a queued lease can be arranged; a conformance case
+        // names one operation and one input and cannot set either up.
+        'signin.what_bounded',
+    ],
+};
+/**
+ * Build one isolated real service, with a fake browser behind it.
+ *
+ * The environment is passed as a record rather than set on the process:
+ * `readEnvironment` takes one, and a subject that mutated `process.env` would
+ * be read by every other test sharing the process.
+ */
+/** How many times a subject's directory is removed before the failure is reported. */
+const REMOVE_ATTEMPTS = 10;
+/** How long to wait between removal attempts, in milliseconds. */
+const REMOVE_RETRY_DELAY_MS = 30;
+/**
+ * Remove a subject's temporary directory, waiting out a handle the OS is still
+ * releasing — and **saying so** if the directory genuinely will not go.
+ *
+ * `dispose` is called from a `finally` in the conformance runner, so anything
+ * thrown here becomes the result of the case that just ran. On Windows a
+ * still-live handle makes `rmSync` fail with `EPERM` (`force` suppresses only
+ * `ENOENT`), and `node --test` attributes such a throw to the **file** rather
+ * than to any test — producing a bare file-level failure with every subtest
+ * passing. That is a fixture fault wearing the costume of a test fault, and it
+ * is worth naming because this suite has already spent a red Windows run on it.
+ *
+ * The retry is written out rather than delegated to `rmSync`'s own
+ * `maxRetries`/`retryDelay`: measured here, those options make no difference to
+ * this failure at all (`{ maxRetries: 20 }` gives up as fast as
+ * `{ maxRetries: 0 }`), so relying on them would look like a fix while changing
+ * nothing.
+ *
+ * A directory that survives every attempt still throws. The alternative —
+ * swallowing it — is how ~1,450 stores accumulated unnoticed in the first place.
+ */
+function removeSubjectDirectory(directory) {
+    let lastError;
+    for (let attempt = 0; attempt < REMOVE_ATTEMPTS; attempt += 1) {
+        try {
+            fs.rmSync(directory, { recursive: true, force: true });
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < REMOVE_ATTEMPTS - 1) {
+                // Blocking on purpose: the caller is synchronous, and the wait exists
+                // to let the OS finish a release this thread cannot observe otherwise.
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, REMOVE_RETRY_DELAY_MS);
+            }
+        }
+    }
+    throw new Error(`could not remove the conformance subject's store at ${directory}. ` +
+        'A handle was most likely still open when the subject was disposed.', { cause: lastError });
+}
+export async function makeServiceSubject() {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'broker-conformance-'));
+    const driver = new FakeBrowserDriver();
+    const runtime = await createRuntime({
+        adapter: 'cli',
+        driver,
+        env: {
+            BROKER_DB: path.join(directory, 'broker.db'),
+            BROKER_ARTIFACTS_ROOT: path.join(directory, 'artefacts'),
+            BROKER_PROFILE_ROOT: path.join(directory, 'profiles'),
+        },
+    });
+    return {
+        service: runtime.service,
+        // The fake's own log, which is what makes "a refusal touched no browser"
+        // checkable rather than asserted.
+        driverCalls: () => driver.calls,
+        // **The same predicate the capacity check uses**, per `driver.ts`'s
+        // requirement for this reading — not a count of rows in `claims`, which
+        // would include the ended ones and move for reasons a refusal did not
+        // cause.
+        liveClaimCount: () => countActiveClaims(runtime.store.db),
+        dispose: () => {
+            runtime.close();
+            removeSubjectDirectory(directory);
+        },
+    };
+}

package/dist/src/adapter/contract.js

@@ -0,0 +1,24 @@
+/**
+ * Every route this application mounts.
+ *
+ * **This is the registry, and it is the one the application uses.** Not a
+ * manifest kept beside the real wiring — the moment there are two, the
+ * conformance suite is asserting over the copy and the application is serving
+ * from the other, and nothing reports the difference. Every consumer, the
+ * suite included, reads this.
+ *
+ * `SCHEMA.md` §8: there are **two routes, not three**, because nothing is
+ * served (§4). The generated operations document is not a route: it performs
+ * no operation and refuses nothing, so it has nothing to be at parity with.
+ * Do not add it here.
+ */
+export const ADAPTER_REGISTRY = {
+    'tool-stdio': 'The tool surface over standard input and output. Spawned by its caller, serves that session, exits with it. The primary route.',
+    cli: 'The command line. In process, because there is nothing else for a command to talk to.',
+};
+/** Every mounted route's identifier, in a stable order. */
+export const ADAPTER_IDS = Object.keys(ADAPTER_REGISTRY);
+/** Whether a string names a mounted route. */
+export function isAdapterId(value) {
+    return Object.prototype.hasOwnProperty.call(ADAPTER_REGISTRY, value);
+}

package/dist/src/adapter/operations.js

@@ -0,0 +1,114 @@
+/**
+ * The operations every route offers, named once.
+ *
+ * `SCHEMA.md` §8 is the claim this file exists to make checkable: *the same
+ * rules through every door*. A rule implemented inside one route is enforced
+ * for that route's callers and for nobody else, **and nothing reports it** —
+ * so the names an adapter is measured against cannot be written down once per
+ * adapter. They are written down here, and every adapter is measured against
+ * this list.
+ *
+ * ── Why a closed union rather than a string ─────────────────────────────
+ *
+ * {@link OperationName} is a union of literals, so an adapter claiming to
+ * expose an operation this service does not have is a **type error** rather
+ * than a case that quietly never runs. That matters more than it looks: the
+ * conformance runner takes the cross product of cases with the adapters
+ * exposing each operation, and an adapter that misspells a name would
+ * otherwise contribute an empty row to the matrix and pass vacuously.
+ * `MILESTONES.md` names that failure directly — an assertion evaluated over
+ * an empty set "passes forever and silently".
+ */
+/**
+ * The twelve operations of `SCHEMA.md` §3.1, in the order it lists them.
+ *
+ * Twelve tools, twelve commands (§5.3), one list. The diff rides on `capture`
+ * as an argument rather than being an operation of its own (§3.11), and the
+ * two removed tools are absent rather than deprecated (§3.1) —
+ * `browser_compare` folded into capture, and `browser_tab_close` deleted
+ * outright because it produced a lease owning nothing while still consuming
+ * budget.
+ *
+ * ── Why the eleventh and twelfth are two names rather than one ──────────
+ *
+ * `sign_in` and `sign_in_done` are the two halves of asking a person to sign
+ * in (§5.5.2), and they are separate operations for the reason §3.1 gives
+ * when it reconciles folding comparison into capture: **a destructive
+ * operation keeps its own name; a non-destructive one may be an argument on
+ * another.** Both halves move the browser's state under every other caller —
+ * one takes it away and one gives it back — so a rule matching on the
+ * operation name has to be able to see each. Folding the second into the
+ * first as a `done: true` argument would hide precisely the transition an
+ * operator reading the ledger is trying to find.
+ *
+ * **They are not `begin_sign_in`/`end_sign_in`.** That pair is a person's,
+ * takes no key, and is deliberately absent from this list: §3.13's ceiling is
+ * that *"the worst thing an agent can do through this surface is close its
+ * own tab"*, and an unkeyed verb that ends a sign-in by naming a browser
+ * would end a person's, mid-password. These two are keyed, and the key is
+ * what makes each answerable — which lease to exempt, and which lease is
+ * entitled to finish.
+ */
+export const OPERATION_NAMES = [
+    'claim',
+    'status',
+    'release',
+    'tab_replace',
+    'navigate',
+    'act',
+    'read',
+    'evaluate',
+    'capture',
+    'feedback',
+    'sign_in',
+    'sign_in_done',
+];
+/**
+ * Whether an operation changes anything a later caller can observe.
+ *
+ * Recorded here rather than inferred by an adapter, because it decides what a
+ * waiver may cover: `MILESTONES.md` requires that a route exposing **any**
+ * write operation may not waive an operation any registered rule can refuse.
+ * "A route is read-only by declaration, or fully covered, with nothing in
+ * between — otherwise a driver that declines to expose anything passes the
+ * first assertion vacuously."
+ *
+ * `feedback` is a write and is deliberately marked as one even though it
+ * takes no lease (§3.16): it appends a row to the installation's own store.
+ */
+const WRITE_OPERATIONS = new Set([
+    'claim',
+    'status',
+    'release',
+    'tab_replace',
+    'navigate',
+    'act',
+    'read',
+    'evaluate',
+    'capture',
+    'feedback',
+    // Both halves of a requested sign-in write: each moves the browser's state,
+    // each appends a ledger row, and each renews the lease that called it.
+    'sign_in',
+    'sign_in_done',
+]);
+/**
+ * Every operation here writes, and that is the design rather than an
+ * oversight worth flagging.
+ *
+ * `SCHEMA.md` §7.1 `arbitration.writes`: *"every arbitration path declares its
+ * intent to write when it opens its transaction, and every one of them does
+ * write"*, and §5.2 spells out the consequence for this route — any command
+ * that goes through arbitration performs the lazy sweep, so even a listing
+ * command closes somebody's lapsed tabs. `status` is the one that surprises
+ * people, and it is a write for exactly that reason: it extends the lease
+ * (§3.1, "there is no keyed call that does not extend").
+ *
+ * The predicate is kept as a predicate rather than collapsed to `true`
+ * because the waiver rule it feeds is about the *category*, and an operation
+ * that genuinely reads is a thing a later row may add. A function that
+ * returned `true` unconditionally would be a rule nobody could ever see fail.
+ */
+export function isWriteOperation(operation) {
+    return WRITE_OPERATIONS.has(operation);
+}

package/dist/src/adapter/service-seam.js

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