browser-broker 0.1.0

package/dist/package.json

@@ -0,0 +1,58 @@
+{
+    "name": "browser-broker",
+    "version": "0.1.0",
+    "license": "MIT",
+    "description": "Leases over tabs in a fixed set of browsers: bounded capacity, a queue, reclamation, and an enforced capture policy.",
+    "type": "module",
+    "bin": {
+        "broker": "dist/src/bin/broker.js",
+        "broker-tool": "dist/src/bin/broker-tool.js"
+    },
+    "engines": {
+        "node": ">=22.18"
+    },
+    "scripts": {
+        "check:external-refs": "node scripts/check-external-refs.mjs",
+        "check:doc-links": "node scripts/check-doc-links.mjs",
+        "check:capture-isolation": "node scripts/check-capture-isolation.mjs",
+        "check:install": "node scripts/check-install.mjs",
+        "check:operations": "node scripts/check-operations.mjs",
+        "check:argument-refusals": "node scripts/check-argument-refusals.mjs",
+        "check:injected-tests": "node scripts/check-injected-tests.mjs",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint .",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "test": "node --test \"tests/**/*.test.mjs\" \"tests/**/*.test.ts\"",
+        "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:injected-tests",
+        "check:arbitration": "node scripts/check-arbitration.mjs",
+        "check:artifact-path": "node scripts/check-artifact-path.mjs",
+        "build": "tsc --project tsconfig.build.json",
+        "prepack": "npm run build",
+        "check:package": "node scripts/check-package.mjs"
+    },
+    "dependencies": {
+        "better-sqlite3": "^13.0.3",
+        "pixelmatch": "^7.2.0",
+        "playwright-core": "1.62.1",
+        "pngjs": "^7.0.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/better-sqlite3": "^9.6.0",
+        "@types/node": "^22.18.12",
+        "@types/pngjs": "^6.0.5",
+        "eslint": "^10.9.1",
+        "globals": "^17.11.0",
+        "prettier": "^3.6.2",
+        "typescript": "~5.9.3",
+        "typescript-eslint": "^8.68.0"
+    },
+    "files": [
+        "dist/",
+        ".env.example",
+        "README.md",
+        "RELEASES.md",
+        "LICENSE"
+    ]
+}

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

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

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

@@ -0,0 +1,429 @@
+import { OPERATION_NAMES } from "../operations.js";
+/**
+ * The case table: authored once per operation, crossed with every route.
+ *
+ * `SCHEMA.md` §8 assertion 3 requires **every operation to have a case that
+ * succeeds and a case that is refused**, so each operation below has both.
+ * The runner checks that requirement over the operations routes actually
+ * offer, rather than trusting this file to be complete — a table that
+ * silently lost a case would otherwise weaken the suite without failing it.
+ *
+ * ── What these cases assert while the service layer is unbuilt ──────────
+ *
+ * The rules these cases name are `SCHEMA.md` §7.1's, and the service that
+ * enforces them is row #10 onward — **not on `main` yet**. So the cases are
+ * run against a service double that implements exactly those rules, and what
+ * they prove is the property this row owes: **that the route carries an
+ * outcome faithfully.** Every code and rule name that comes out of the
+ * service arrives at the caller unchanged, with the physical side-effects
+ * unmoved on a refusal.
+ *
+ * That is a narrower claim than #30's and it is stated narrowly on purpose.
+ * When the real service lands, this table is pointed at it and the same cases
+ * become the parity assertion over real enforcement, with no case rewritten —
+ * which is the property the once-per-operation shape exists to give.
+ */
+/**
+ * Mint a live lease and hand its key to the case.
+ *
+ * ── Why every keyed case needs this, rather than a constant ─────────────
+ *
+ * A lease key is **returned once by the claim that granted it and is not
+ * recoverable** (§2.2), so a case cannot write one down. A constant would be
+ * a key the service never issued, and every keyed case would then measure
+ * `key.valid` refusing it — the whole matrix would go green on the wrong
+ * assertion, with the operations themselves never reached.
+ *
+ * The seed runs afresh per case-and-route pair, so each pair gets its own
+ * lease and no pair inherits another's.
+ */
+const withALiveLease = {
+    apply: async (service) => {
+        const granted = await service.perform({
+            operation: 'claim',
+            adapter: 'conformance',
+            arguments: {
+                session_id: 'conformance-seed',
+                browser: 'regular',
+                purpose: 'conformance: a lease for the keyed cases',
+            },
+        });
+        if (granted.outcome !== 'accepted') {
+            throw new Error(`the seed could not obtain a lease: ${granted.rule}`);
+        }
+        // ── Two different outcomes, and only one of them is a live lease ─────
+        //
+        // `granted.outcome` is the **transport's** answer: the call was accepted
+        // rather than refused. `granted.value['outcome']` is the **service's**:
+        // whether the claim was granted a tab or put in the queue. A full budget
+        // answers `accepted` at the transport and `queued` underneath, and a
+        // queued claim holds a real key with no tab behind it.
+        //
+        // Checking only the first is the shape this suite exists to catch. The
+        // docblock above argues that a key the service never issued would send
+        // the whole matrix green on `key.valid`; a queued key is the same defect
+        // one layer in, and harder to see, because the key is genuine — the
+        // operations would refuse for having no tab while the seed reported
+        // success, and the failure would name a rule that looks like a real
+        // finding about the operation under test.
+        //
+        // The sibling seed below already reads `value['outcome']`, because
+        // reaching a queue placement is the thing it is trying to do. This one
+        // wants the opposite and had not said so.
+        if (granted.value['outcome'] !== 'granted') {
+            throw new Error(`the seed obtained a lease that is not live: the service answered ` +
+                `'${String(granted.value['outcome'])}' rather than 'granted', so the key it ` +
+                `returned has no tab behind it and every keyed case would measure that ` +
+                `instead of the operation it names.`);
+        }
+        // **The key is substituted into the case's input**, so the operation
+        // under test is reached rather than being refused for an unknown key.
+        return { lease_key: granted.value['key'] };
+    },
+};
+/**
+ * A live lease whose tab has been given back, so the key is real and there is
+ * no tab behind it.
+ *
+ * The reachable way to exercise `tab.owned`: no surface takes a tab argument
+ * (§3.4), so a caller cannot name another lease's tab and there is no input
+ * that would. Releasing the tab leaves a key that resolves and a tab that
+ * does not, which is the state the rule refuses.
+ */
+/**
+ * A lease that is **live and holds no tab**: a queue placement.
+ *
+ * ── Why the queue rather than a released lease ──────────────────────────
+ *
+ * `tab.owned` is only reachable while the key still resolves. Releasing the
+ * lease ends it, so `claim.live` refuses first and the case measures that
+ * rule instead — which is correct behaviour and the wrong thing to assert
+ * here. §3.14's refusal ordering is a property callers branch on, so a seed
+ * that trips an earlier rule is a seed testing the earlier rule.
+ *
+ * A queued lease is the state that satisfies both halves: §2.5 gives it a key
+ * and no tab, because *"a queued lease has no tab"*. The bridge resolves no
+ * tab for it and the ownership guard refuses — with `tab_not_found`, the same
+ * code an unknown tab gets, because §7.1 requires the two be
+ * indistinguishable so probing cannot enumerate another lease's tabs.
+ *
+ * **Nothing here takes a tab argument**, and could not: no surface offers one
+ * (§3.4). That is why this rule is reached by exhausting the budget rather
+ * than by naming somebody else's tab — the naming route does not exist.
+ */
+const withAQueuedLease = {
+    apply: async (service) => {
+        // Claim until one is queued rather than counting to the budget: the
+        // budget is configurable (§1.10), so a fixture that assumed a number
+        // would break on a build configured differently and would break silently
+        // — every claim granted, nothing queued, and the case measuring an
+        // active lease.
+        for (let attempt = 0; attempt < 200; attempt += 1) {
+            const outcome = await service.perform({
+                operation: 'claim',
+                adapter: 'conformance',
+                arguments: {
+                    session_id: `conformance-queue-${String(attempt)}`,
+                    browser: 'regular',
+                    purpose: 'conformance: filling the budget to reach a queue placement',
+                },
+            });
+            if (outcome.outcome !== 'accepted') {
+                throw new Error(`the seed could not obtain a lease: ${outcome.rule}`);
+            }
+            if (outcome.value['outcome'] === 'queued') {
+                return { lease_key: outcome.value['key'] };
+            }
+        }
+        throw new Error('the seed never reached a queue placement');
+    },
+};
+/**
+ * A live lease that has **already asked for a sign-in**, so the browser is in
+ * `signing-in` and this lease is the one that put it there.
+ *
+ * ── Why the seed asks rather than the case doing it ─────────────────────
+ *
+ * `sign_in_done` is only reachable against a sign-in that is open, and only
+ * by the lease that opened it (§7.1 `signin.finish_owned`). A case cannot
+ * express two calls — it names one operation and one input — so the first of
+ * the two happens here, which is what a seed is for.
+ *
+ * **It goes through the service, exactly like every other seed here.** The
+ * browser is moved to `signing-in` by a real `sign_in` call rather than by
+ * writing the row, so the state this case finishes is a state the product
+ * produced. Seeding it by hand would prove the finish path can move a row
+ * somebody inserted, which is not the claim.
+ */
+const withARequestedSignIn = {
+    apply: async (service) => {
+        const granted = await service.perform({
+            operation: 'claim',
+            adapter: 'conformance',
+            arguments: {
+                session_id: 'conformance-signin-seed',
+                browser: 'regular',
+                purpose: 'conformance: a lease that will ask for a sign-in',
+            },
+        });
+        if (granted.outcome !== 'accepted') {
+            throw new Error(`the seed could not obtain a lease: ${granted.rule}`);
+        }
+        if (granted.value['outcome'] !== 'granted') {
+            throw new Error(`the seed obtained a lease that is not live: the service answered ` +
+                `'${String(granted.value['outcome'])}' rather than 'granted', so it holds no tab ` +
+                `and cannot ask for a sign-in on one.`);
+        }
+        const key = granted.value['key'];
+        const asked = await service.perform({
+            operation: 'sign_in',
+            adapter: 'conformance',
+            arguments: { lease_key: key, what: 'conformance: the account dashboard' },
+        });
+        if (asked.outcome !== 'accepted') {
+            throw new Error(`the seed could not open a sign-in: ${asked.rule}`);
+        }
+        return { lease_key: key };
+    },
+};
+/** A key that was never issued — for the cases whose subject is `key.valid`. */
+const NOT_A_KEY = 'not-a-key';
+export const CONFORMANCE_CASES = [
+    {
+        name: 'claim: a well-formed request is granted',
+        operation: 'claim',
+        input: { session_id: 'session-a', browser: 'regular', purpose: 'conformance: a granted claim' },
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'claim: a browser that is not one of the two is refused',
+        operation: 'claim',
+        // §7.1 `claim.browser_known`. There are exactly two browsers and there is
+        // no third (§1.2), so naming one is a refusal on every route or on none.
+        input: { session_id: 'session-a', browser: 'third', purpose: 'conformance: unknown browser' },
+        expect: { outcome: 'refused', code: 'unknown_browser', rule: 'claim.browser_known' },
+    },
+    {
+        name: 'status: a live lease reports where it stands',
+        operation: 'status',
+        seed: withALiveLease,
+        input: {},
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'status: a call with no key is refused',
+        operation: 'status',
+        // §7.1 `key.present`: every operation except requesting a lease carries a
+        // key, written out explicitly and never derived from a session (§3.1).
+        input: {},
+        expect: { outcome: 'refused', code: 'key_missing', rule: 'key.present' },
+    },
+    {
+        name: 'release: a lease gives back what it holds',
+        operation: 'release',
+        seed: withALiveLease,
+        input: {},
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'release: an unrecognised key is refused',
+        operation: 'release',
+        input: { lease_key: NOT_A_KEY },
+        expect: { outcome: 'refused', code: 'unrecognised_key', rule: 'key.valid' },
+    },
+    {
+        name: 'tab replace: a live lease gets a fresh tab',
+        operation: 'tab_replace',
+        seed: withALiveLease,
+        input: {},
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'tab replace: an unrecognised key is refused',
+        operation: 'tab_replace',
+        input: { lease_key: NOT_A_KEY },
+        expect: { outcome: 'refused', code: 'unrecognised_key', rule: 'key.valid' },
+    },
+    {
+        name: 'navigate: an ordinary web address is accepted',
+        operation: 'navigate',
+        seed: withALiveLease,
+        input: { url: 'https://example.com/' },
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'navigate: a local-file address is refused',
+        operation: 'navigate',
+        // §7.1 `navigate.scheme_allowed`, and the reason it is refused explicitly
+        // rather than merely unsupported: it turns a browser lease into an
+        // arbitrary read of the machine's filesystem.
+        seed: withALiveLease,
+        input: { url: 'file:///etc/passwd' },
+        expect: {
+            outcome: 'refused',
+            code: 'navigate.scheme_allowed',
+            rule: 'navigate.scheme_allowed',
+        },
+    },
+    {
+        name: 'act: a named verb is performed',
+        operation: 'act',
+        seed: withALiveLease,
+        input: { action: 'click', target: 'the-button' },
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'act: a verb that is not on the list is refused',
+        operation: 'act',
+        seed: withALiveLease,
+        input: { action: 'teleport', target: 'the-button' },
+        // The rule is spelled `act.action_known`, which is what the service
+        // actually produces. §8.4 computes coverage from what came back rather
+        // than from what a case declared, so a case naming a rule nothing raises
+        // fails the run instead of quietly passing.
+        expect: { outcome: 'refused', code: 'act.action_known', rule: 'act.action_known' },
+    },
+    {
+        name: 'read: the page snapshot is returned by default',
+        operation: 'read',
+        seed: withALiveLease,
+        input: {},
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'read: an unrecognised key is refused',
+        operation: 'read',
+        input: { lease_key: NOT_A_KEY },
+        expect: { outcome: 'refused', code: 'unrecognised_key', rule: 'key.valid' },
+    },
+    {
+        name: 'evaluate: an expression within the cap is evaluated',
+        operation: 'evaluate',
+        seed: withALiveLease,
+        input: { expression: '1 + 1' },
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'evaluate: an expression over the cap is refused',
+        operation: 'evaluate',
+        // §7.1 `evaluate.expression_bounded`.
+        seed: withALiveLease,
+        input: { expression: 'x'.repeat(100_000) },
+        expect: {
+            outcome: 'refused',
+            code: 'evaluate.expression_bounded',
+            rule: 'evaluate.expression_bounded',
+        },
+    },
+    {
+        name: 'capture: a default-tier picture is taken',
+        operation: 'capture',
+        seed: withALiveLease,
+        input: {},
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'capture: a selector and a full page together are refused',
+        operation: 'capture',
+        // §7.1 `capture.exclusive_mode`. Note this is a refusal about a malformed
+        // argument, never about cost — `capture.never_refused_for_cost` (§7.3) is
+        // what keeps the "never a refusal for cost" promise checkable.
+        seed: withALiveLease,
+        input: { selector: '.thing', full_page: true },
+        expect: {
+            outcome: 'refused',
+            code: 'capture.exclusive_mode',
+            rule: 'capture.exclusive_mode',
+        },
+    },
+    {
+        name: 'claim: a purpose outside its bounds is refused',
+        operation: 'claim',
+        // §7.1 `claim.purpose_bounded`. The purpose is what an operator reads
+        // when deciding whether to revoke a lease (§1.3), so it is bounded at
+        // both ends and the refusal is the same on every route.
+        input: { session_id: 'session-a', browser: 'regular', purpose: 'x' },
+        expect: {
+            outcome: 'refused',
+            code: 'purpose_out_of_bounds',
+            rule: 'claim.purpose_bounded',
+        },
+    },
+    {
+        name: 'navigate: a lease holding no tab is refused',
+        operation: 'navigate',
+        // §7.1 `tab.owned`. **The tab is not an argument on any surface** (§3.4),
+        // so a route cannot name somebody else's — the bridge resolves the tab
+        // from the key. A queued lease is live and holds no tab, which reaches
+        // this rule from the direction a caller can actually get to.
+        seed: withAQueuedLease,
+        input: { url: 'https://example.com/' },
+        // `tab_not_found` and not a code of its own: §7.1 requires an unowned
+        // tab and an unknown one to be indistinguishable to the caller.
+        expect: { outcome: 'refused', code: 'tab_not_found', rule: 'tab.owned' },
+    },
+    {
+        name: 'sign in: a live lease holding a tab can ask a person to sign in',
+        operation: 'sign_in',
+        seed: withALiveLease,
+        input: { what: 'conformance: the account dashboard' },
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'sign in: a request that does not say what it is signing into is refused',
+        operation: 'sign_in',
+        // The one free-text field relayed to a person verbatim by a third party,
+        // so an empty one produces a request nobody can act on. Reached with a
+        // real lease rather than a bad key, because a bad key would refuse on
+        // `key.valid` first and the case would measure that instead (§3.14's
+        // ordering is a property callers branch on).
+        seed: withALiveLease,
+        input: { what: '' },
+        expect: {
+            outcome: 'refused',
+            code: 'sign_in_what_out_of_bounds',
+            rule: 'signin.what_bounded',
+        },
+    },
+    {
+        name: 'sign in done: the lease that asked gives the browser back',
+        operation: 'sign_in_done',
+        seed: withARequestedSignIn,
+        input: {},
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'sign in done: an unrecognised key is refused',
+        operation: 'sign_in_done',
+        input: { lease_key: NOT_A_KEY },
+        expect: { outcome: 'refused', code: 'unrecognised_key', rule: 'key.valid' },
+    },
+    {
+        name: 'feedback: a rated report is recorded without a lease',
+        operation: 'feedback',
+        // §3.16: no lease required, and that is the point rather than a
+        // convenience — requiring one would silence exactly the population the
+        // tool exists to hear from.
+        input: { rating: '4', category: 'worked-well', note: 'conformance: a recorded report' },
+        expect: { outcome: 'accepted' },
+    },
+    {
+        name: 'feedback: a rating outside the scale is refused',
+        operation: 'feedback',
+        input: { rating: '9', category: 'worked-well', note: 'conformance: a rating off the scale' },
+        expect: {
+            outcome: 'refused',
+            code: 'feedback.rating_in_scale',
+            rule: 'feedback.rating_in_scale',
+        },
+    },
+];
+/**
+ * Every operation named by at least one case.
+ *
+ * Exported so a test can assert the table covers the operation list by name
+ * rather than by counting — `MILESTONES.md` records a hollow test that
+ * "iterated a list rather than naming its entries, so deleting an entry
+ * stayed green", and a count would have exactly that shape.
+ */
+export const OPERATIONS_WITH_CASES = OPERATION_NAMES.filter((operation) => CONFORMANCE_CASES.some((testCase) => testCase.operation === operation));

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

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isAdapterId } from "../contract.js";
+/**
+ * Find every adapter this tree contains, and report the ones nothing mounts.
+ *
+ * ── This is the run-time half of "an unregistered adapter fails the suite" ─
+ *
+ * The typed driver map catches a route added to the registry with no driver.
+ * It cannot catch the other direction: a module that implements an adapter
+ * and was **never added to the registry at all**. No type can see a file
+ * nobody imported, so that half is a walk of the source tree.
+ *
+ * An adapter module is one that exports an {@link Adapter} — which is
+ * recognised here by the declaration that names it, `Adapter =` with the type
+ * annotation, rather than by executing anything. **Reading rather than
+ * importing is deliberate:** importing every candidate to see what it exports
+ * would execute code found on disk, and a walk that runs what it finds is a
+ * worse thing to have than the gap it closes.
+ *
+ * ── What this can and cannot see, so nobody over-trusts it ──────────────
+ *
+ * It sees a file under {@link ADAPTER_SOURCE_ROOTS} whose **code** declares an
+ * `Adapter`. It does **not** see: an adapter written outside those roots, one
+ * assembled at run time from something that is not a literal declaration, or
+ * one whose type annotation is spelled differently. The roots are asserted by
+ * this module's own test, so moving or narrowing them is a visible change to
+ * a test rather than a silent loss of coverage — which is the property that
+ * makes a walk-based check worth having at all.
+ *
+ * Comments are blanked before matching, because they are prose about
+ * adapters rather than adapters. That is a fix for a real false positive
+ * rather than a precaution: this file's own header quotes the shape it
+ * matches, and the walk reported that quotation as an unregistered adapter
+ * until {@link withoutComments} was added.
+ *
+ * That is the same shape, and the same honesty, as the hygiene gate's own
+ * header: a green run means no *unregistered adapter of the recognised shape*
+ * exists, not that no adapter anywhere is unregistered.
+ */
+/** Where an adapter may live. Asserted by this module's test. */
+export const ADAPTER_SOURCE_ROOTS = ['src'];
+/**
+ * How an adapter declares itself.
+ *
+ * Matches a declaration annotated with the contract's own type — for example
+ * `export const cliAdapter: Adapter = {`. The annotation is what is matched
+ * rather than the file's name or its directory, because a naming convention
+ * is a thing somebody can be unaware of and a type annotation is a thing the
+ * compiler already made them write.
+ */
+const ADAPTER_DECLARATION = /(?:const|let|var)\s+(\w+)\s*:\s*Adapter\b/gu;
+/**
+ * The identifier an adapter module claims, read from its `id` field.
+ *
+ * Matched on the literal because that is what the registry's keys are
+ * compared against. A computed id would not match, and that is a limitation
+ * this file states rather than papers over.
+ */
+const ADAPTER_ID_FIELD = /\bid\s*:\s*['"]([\w-]+)['"]/u;
+/** Walk a directory for TypeScript sources, skipping what cannot hold one. */
+function* sourceFiles(directory) {
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+                continue;
+            }
+            yield* sourceFiles(full);
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.ts')) {
+            yield full;
+        }
+    }
+}
+/**
+ * Blank out comments, so a declaration *described* in prose is not mistaken
+ * for one.
+ *
+ * This is not a nicety — it was a real false positive. `discovery.ts`'s own
+ * header documents the shape it matches by quoting it, and the walk duly
+ * reported its own documentation as an unregistered adapter. Blanking rather
+ * than deleting keeps every offset intact, so the id lookup that follows a
+ * match still reads the right region of the file.
+ *
+ * **It is a lexer's job done with a regular expression, and it is approximate
+ * in one direction that is worth naming**: a `//` or a comment opener inside a
+ * string literal is treated as the start of a comment. The consequence is a
+ * declaration *after* such a string on the same line being missed, which
+ * would be a false negative. It is accepted because the alternative is
+ * parsing TypeScript to run a check, and because the tests below pin both the
+ * positive and the negative behaviour rather than only the happy one.
+ */
+function withoutComments(text) {
+    const blanked = (match) => match.replaceAll(/[^\n]/gu, ' ');
+    return text.replaceAll(/\/\*[\s\S]*?\*\//gu, blanked).replaceAll(/\/\/[^\n]*/gu, blanked);
+}
+/** Every adapter declared anywhere under the roots. */
+export function discoverAdapters(treeRoot) {
+    const found = [];
+    for (const root of ADAPTER_SOURCE_ROOTS) {
+        for (const file of sourceFiles(path.join(treeRoot, root))) {
+            const text = withoutComments(fs.readFileSync(file, 'utf8'));
+            // The contract itself declares the type; it is not an adapter.
+            const relative = path.relative(treeRoot, file).split(path.sep).join('/');
+            if (relative === 'src/adapter/contract.ts') {
+                continue;
+            }
+            ADAPTER_DECLARATION.lastIndex = 0;
+            let match = ADAPTER_DECLARATION.exec(text);
+            while (match !== null) {
+                const declaration = match[1] ?? '<anonymous>';
+                // Read the id from the object that follows the declaration.
+                const after = text.slice(match.index);
+                const idMatch = ADAPTER_ID_FIELD.exec(after);
+                found.push({ file: relative, declaration, id: idMatch?.[1] });
+                match = ADAPTER_DECLARATION.exec(text);
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Every adapter the tree contains that the registry does not mount.
+ *
+ * **A non-empty result fails the suite.** That is the assertion row #25 is
+ * defined by, and it is proved by a test that actually adds an unregistered
+ * adapter and watches this return it — not by a comment claiming it would.
+ */
+export function unregisteredAdapters(treeRoot) {
+    const unregistered = [];
+    for (const adapter of discoverAdapters(treeRoot)) {
+        if (adapter.id === undefined) {
+            unregistered.push({
+                ...adapter,
+                why: 'its id is not a literal, so nothing can check it against the registry',
+            });
+            continue;
+        }
+        if (!isAdapterId(adapter.id)) {
+            unregistered.push({
+                ...adapter,
+                why: `"${adapter.id}" is not in the registry the application mounts through`,
+            });
+        }
+    }
+    return unregistered;
+}

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

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