browser-broker 0.1.0

package/dist/src/service/broker.js

@@ -0,0 +1,120 @@
+import { readDiffSettings } from "../diff/settings.js";
+import { runArbitration } from "./arbitration.js";
+import { createPendingSeeds } from "./pending-seeds.js";
+/**
+ * Bind a service to one store, one environment snapshot and one adapter.
+ *
+ * The settings are read from the environment **here, once**, and handed to
+ * every operation on its input. §6.3: one snapshot per process, so every rule
+ * inside one operation sees one configuration — a handler that read the
+ * environment itself would be a second snapshot taken at a different instant,
+ * inside a transaction other callers are waiting behind.
+ */
+export function createBroker(options) {
+    const settings = {
+        tabBudget: options.environment.tabBudget,
+        leaseSeconds: options.environment.leaseSeconds,
+        queueSeconds: options.environment.queueSeconds,
+        regularBrowsers: options.environment.regularBrowsers,
+        privateBrowsers: options.environment.privateBrowsers,
+    };
+    // The same one-per-process snapshot the arbitration settings are, taken
+    // here for the same reason (§6.3). A bad value refuses the spawn rather
+    // than one capture, which is `readDiffSettings`'s own documented split.
+    const diffSettings = options.diffSettings ?? readDiffSettings();
+    const run = (name, input) => runArbitration({
+        store: options.store,
+        name,
+        adapter: options.adapter,
+        input,
+        ...(options.closeTab === undefined ? {} : { closeTab: options.closeTab }),
+    });
+    /**
+     * The browser connection, added to the six inputs that can use one.
+     *
+     * **Added here rather than by each adapter**, which is the same rule the
+     * bridge holds itself to: a route shapes arguments and names an operation,
+     * and whether a browser is reached is not an argument a caller passes. A
+     * surface that could omit it would be a surface on which a page verb
+     * silently did nothing, and the two surfaces would differ in what they
+     * actually did while agreeing on what they returned — the exact failure
+     * §8's parity assertion exists to catch.
+     */
+    /**
+     * Seeds a granted claim asked for, waiting for its tab's first open.
+     *
+     * **One store per broker, which is one per process** (§1.0 — the service is
+     * spawned by its caller and exits with it). The values are credentials and
+     * are deliberately never written to the store; `pending-seeds.ts` sets out
+     * why, and what a lease granted in one process and driven from another
+     * therefore does not get.
+     */
+    const pendingSeeds = createPendingSeeds();
+    const withBrowser = (input) => ({
+        ...input,
+        ...(options.session === undefined ? {} : { session: options.session }),
+        // Handed to every tab verb rather than only to the one that opens the
+        // page, because **which verb opens the page is not knowable here**: a
+        // lease's first call may be a navigate, a read, a capture or any other,
+        // and `pageFor` is what discovers it is the first. Supplying it only to
+        // one would make seeding depend on which verb a caller happened to reach
+        // for — the same class of defect as a rule holding on one route.
+        pendingSeeds,
+    });
+    /**
+     * The browser connection **and** somewhere to write, for the two verbs that
+     * produce a file: a capture always, and an evaluation whose result is past
+     * the inline cap (§3.10).
+     *
+     * Added here for the same reason {@link withBrowser} is: which store an
+     * artefact lands in is not an argument a caller passes, and a surface that
+     * could omit it would be a surface on which a large evaluation silently
+     * had nowhere to go.
+     */
+    const withBrowserAndArtifacts = (input) => ({
+        ...withBrowser(input),
+        ...(options.artifacts === undefined ? {} : { artifacts: options.artifacts }),
+        // Read once, above, and handed to every capture — never read inside the
+        // handler, for the reason this function's own header gives about the
+        // arbitration settings: a second snapshot taken at a different instant
+        // would let two rules inside one operation see two configurations.
+        diffSettings,
+    });
+    return {
+        claim: async (input) => {
+            const result = await run('claim', { ...input, settings });
+            // **After the call returns, so only a committed grant holds a seed.**
+            // A refused claim throws before reaching here and a queued one carries
+            // no entries (`claim.ts`: a queue placement has no tab to seed and the
+            // entries are deliberately dropped rather than held across an
+            // unbounded wait). So nothing is retained for a lease that does not
+            // exist, and a caller cannot leave values in this process by being
+            // refused repeatedly.
+            if (result.outcome === 'granted') {
+                pendingSeeds.put(result.claimId, result.storageSeed);
+            }
+            return result;
+        },
+        status: (input) => run('status', input),
+        release: (input) => run('release', {
+            ...input,
+            settings,
+        }),
+        navigate: (input) => run('navigate', withBrowser(input)),
+        act: (input) => run('act', withBrowser(input)),
+        read: (input) => run('read', withBrowser(input)),
+        evaluate: (input) => run('evaluate', {
+            ...withBrowser(input),
+            // The artifact store, and deliberately **not** `diffSettings`: an
+            // evaluation never diffs, and handing it a setting it cannot use
+            // would be the surface declaring an argument that does nothing.
+            ...(options.artifacts === undefined ? {} : { artifacts: options.artifacts }),
+        }),
+        capture: (input) => run('capture', withBrowserAndArtifacts(input)),
+        tab_replace: (input) => run('tab_replace', withBrowser(input)),
+        begin_sign_in: (input) => run('begin_sign_in', input),
+        end_sign_in: (input) => run('end_sign_in', input),
+        sign_in: (input) => run('sign_in', input),
+        sign_in_done: (input) => run('sign_in_done', input),
+    };
+}

package/dist/src/service/browser-session.js

@@ -0,0 +1,269 @@
+import path from 'node:path';
+import { profileDirectory } from "../browser/discovery.js";
+import { decideAdoption, recordLaunched, recordLaunchFailed, } from "../browser/adoption.js";
+import { browserIsRunning, modeFor, RealBrowserDriver } from "../browser/real.js";
+import { StartupRefusal } from "../errors.js";
+/**
+ * **How a shipped binary gets a browser.** The join between the adoption
+ * arbitration and the driver that performs what it decides.
+ *
+ * ── Why this file exists, stated as the thing that was missing ───────────
+ *
+ * Every part of this was already built and tested. `decideAdoption` arbitrates
+ * the launch race in the same transaction that arbitrates claims;
+ * `RealBrowserDriver` attaches to a running browser or cold-starts a detached
+ * one; `recordLaunched` and `recordLaunchFailed` close the `starting` window
+ * either way. **Nothing in `src/` called any of them.** The adoption module
+ * had tests and no production caller, so the store's `browsers` table
+ * described a launch race that no shipped code ever ran.
+ *
+ * That is the gap this closes, and it is closed by *composing* those pieces
+ * rather than by writing a second launch path beside them.
+ *
+ * ── Lazy, and that is load-bearing rather than an optimisation ───────────
+ *
+ * **Nothing here touches a browser until a page verb actually needs one.** A
+ * spawn that acquired a browser eagerly would make every command that reaches
+ * the service — `claim`, `status`, `release`, `feedback`, a refusal — depend
+ * on a browser installation, and the two most common states of this service
+ * are *no browser installed* and *no page driven yet*. It would also make the
+ * continuous-integration `operations` job, which spawns the real executables
+ * on a runner with no browser at all, depend on one.
+ *
+ * So {@link browserSessionProvider} returns a function, and the function is
+ * what `operations/pages.ts` calls **inside an after-commit closure**. A
+ * caller that only ever claims and releases never causes a launch.
+ *
+ * ── Memoised per process, because adoption is not idempotent ─────────────
+ *
+ * The six page verbs each resolve a session, and a session is a live
+ * connection over the debugging protocol. Resolving one per call would open a
+ * new connection per verb and run the adoption transaction per verb — and the
+ * second of those is worse than wasteful: the race is decided in the store,
+ * so a process that re-entered it would keep re-answering a question it had
+ * already answered. One session per browser per process, held until the
+ * process exits.
+ *
+ * The memo holds the **promise**, not the resolved session, so two verbs
+ * racing in the same process await one acquisition rather than starting two.
+ *
+ * ── A failed acquisition is not cached ───────────────────────────────────
+ *
+ * If acquiring throws, the memo is cleared, so the next call tries again. The
+ * alternative — caching the rejection — turns one transient failure (a browser
+ * still finishing its start-up, a machine that was briefly out of memory) into
+ * a process that can never drive a page again, and the process serves a whole
+ * session.
+ */
+/**
+ * How long a launch-race loser waits before giving up on the winner —
+ * documented here, not consulted here.
+ *
+ * **Not read by `waitForWinner`.** `environment.launchReadinessTimeoutSeconds`
+ * (`BROKER_LAUNCH_READINESS_TIMEOUT_SECONDS`, `src/config/environment.ts`) is
+ * the number that actually governs a spawn — `environment` is a required
+ * field on {@link BrowserSessionProviderOptions}, so every caller that builds
+ * a provider supplies one. This constant has no production consumer; it is
+ * kept as a doc anchor equal to that variable's default (30s) so the two
+ * cannot silently drift apart, and a test may still use it as a readable
+ * stand-in for "the default" without hardcoding `30_000` a second time.
+ */
+export const WAIT_TIMEOUT_MS = 30_000;
+/** How often a launch-race loser re-asks whether the winner's browser is up. */
+export const WAIT_POLL_INTERVAL_MS = 100;
+export function browserSessionProvider(options) {
+    const driver = options.driver ??
+        new RealBrowserDriver({
+            ...(options.artifacts === undefined
+                ? {}
+                : // The driver names a file; the store decided the directory. See
+                    // `RealDriverOptions.outputDirectory` for why the split is the rule
+                    // rather than a preference, and {@link
+                    // BrowserSessionProviderOptions.artifacts} for why this is the
+                    // shared tree rather than one lease's.
+                    { outputDirectory: path.join(options.artifacts.root, 'snapshots') }),
+            // **The signed-in engine, carried from this process's one environment
+            // snapshot** (§6.3, `DECISIONS.md` §13i). One driver serves every
+            // browser in this process, so the kind-specific engine cannot be chosen
+            // per session here — see the note on `RealDriverOptions.engine` for
+            // what the value does and does not do, which is what makes one engine
+            // per process the honest shape rather than a shortcut.
+            engine: options.environment.regularBrowserEngine,
+        });
+    const inFlight = new Map();
+    const settled = new Map();
+    const session = (browser) => {
+        const existing = inFlight.get(browser);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const acquiring = acquire(driver, browser, options)
+            .then((acquired) => {
+            settled.set(browser, acquired);
+            return acquired;
+        })
+            .catch((error) => {
+            // Not cached. See the header: a cached rejection would end this
+            // process's ability to drive a page for the rest of its life.
+            inFlight.delete(browser);
+            throw error;
+        });
+        inFlight.set(browser, acquiring);
+        return acquiring;
+    };
+    return {
+        session,
+        close: async () => {
+            for (const open of settled.values()) {
+                try {
+                    await open.detach();
+                }
+                catch {
+                    // The browser is adopted and outlives this process regardless.
+                }
+            }
+            settled.clear();
+            inFlight.clear();
+        },
+    };
+}
+/**
+ * Perform one adoption: ask the store what to do, then do it.
+ *
+ * ── The order is the rule, and it is the reason this is not two lines ────
+ *
+ * `SCHEMA.md` §2.4b: no browser work inside the arbitration transaction. So
+ * the observation is made **before** the transaction opens, the transaction
+ * decides, and the launch happens **after** it commits. `adoption.ts` says the
+ * same thing from the other side — its `runningRecord` is a parameter *"for
+ * one reason: reading it means talking to a browser, and this runs inside the
+ * transaction"*.
+ *
+ * The consequence, which `decideAdoption` also states: the observation can be
+ * stale by the time the transaction opens, and the `starting` state is what
+ * covers the gap rather than the observation being made more carefully.
+ */
+async function acquire(driver, browser, options) {
+    const isRunning = options.isRunning ?? browserIsRunning;
+    const profileDir = profileDirectory(options.environment.profileRoot, browser);
+    const observed = await isRunning(profileDir);
+    const decision = await decideAdoption(options.store, browser, observed === undefined || observed.browserUuid === undefined
+        ? undefined
+        : { endpoint: observed.endpoint, browserUuid: observed.browserUuid });
+    return performDecision(driver, decision, profileDir, options);
+}
+/** Do what the transaction decided, outside it. */
+async function performDecision(driver, decision, profileDir, options) {
+    const { browser } = decision;
+    if (decision.action === 'attach') {
+        return driver.attach(browser, {
+            endpoint: decision.endpoint,
+            browserUuid: decision.browserUuid,
+        });
+    }
+    if (decision.action === 'wait') {
+        return waitForWinner(driver, browser, profileDir, options);
+    }
+    // This caller won the race, and the row says `starting` until it says
+    // otherwise. **Both outcomes have to be recorded**: `adoption.ts` is
+    // explicit that a winner which fails and does not release the race leaves
+    // every later caller waiting for a launch that is never coming.
+    try {
+        const started = await driver.coldStart({
+            browser,
+            profileDirectory: profileDir,
+            mode: modeFor(browser),
+        });
+        const described = started.describe();
+        await recordLaunched(options.store, browser, {
+            pid: described.pid,
+            endpoint: described.discovery.endpoint,
+            // A session that connected has read the browser's own identifier, so
+            // this is the verified one rather than the one off disk.
+            browserUuid: described.discovery.browserUuid ?? '',
+        });
+        return started;
+    }
+    catch (error) {
+        await recordLaunchFailed(options.store, browser);
+        throw error;
+    }
+}
+/**
+ * Wait for the caller that won the race, and attach to what it started.
+ *
+ * ── Row #55, settled ──────────────────────────────────────────────────────
+ *
+ * `SCHEMA.md` §1.2b named two candidate moments and refused to conflate
+ * them: the winner **recording** that it launched, and the winner's
+ * debugging endpoint **accepting a connection**. Only the second is what a
+ * loser can actually attach to, so only the second is what this waits for.
+ *
+ * **The signal is `browserIsRunning`, unchanged** — §1.2c's own liveness
+ * (the endpoint answers) plus identity (the browser's own identifier
+ * matches, because ports are reused) check, the one every attach in this
+ * file already trusts. This row does not add a second verification: it is
+ * `readDiscoveryRecord` + `verifyDiscoveryRecord` under `src/browser/real.ts`,
+ * called here exactly as `acquire`'s own observation calls it. A caller that
+ * wrote a second check here would be trusting a claim by two different
+ * routes that could disagree; there is one route.
+ *
+ * **The bound is `environment.launchReadinessTimeoutSeconds`**
+ * (`BROKER_LAUNCH_READINESS_TIMEOUT_SECONDS`, `.env.example`) — a poll
+ * ceiling, never a sleep. Somebody has to do something when the decision
+ * comes back `wait`, and there are exactly three options: return a session
+ * that is not one, block forever, or poll with a ceiling. The first is the
+ * dishonesty this whole row exists to remove and the second turns one failed
+ * launch elsewhere into a hung process here — so this polls, and when the
+ * ceiling is reached it **refuses, naming what it waited for**, rather than
+ * proceeding as if it had a browser. A `StartupRefusal` is the same shape
+ * every other refusal in this module takes, and its message says a caller is
+ * *still starting*, never that the browser *died* — those are different
+ * facts and this function has evidence for only one of them.
+ *
+ * It is deliberately the most minimal shape that can be correct:
+ *
+ * - **It launches nothing.** A loser that started its own browser would be the
+ *   second process against one profile directory, which is the measured
+ *   silent-collision failure the race exists to prevent.
+ * - **It concludes nothing from the ceiling.** Timing out is reported as *this
+ *   caller stopped waiting*, not as *the winner failed*. Nothing here writes
+ *   to the `browsers` row, so the winner keeps its race and the next caller
+ *   asks the same question again.
+ * - **It is the ordinary positive test.** The loop asks `browserIsRunning`,
+ *   which verifies the endpoint answers **and** that the browser identifies
+ *   itself as the one on the record — the same check every other path here
+ *   makes, and the reason a stale record plus a reused port cannot be mistaken
+ *   for a live browser.
+ *
+ * `sleepImpl`/`nowImpl` are injected, following the seam convention
+ * `launch.ts` established for `fetchImpl`/`spawnImpl`/`killImpl`: a test that
+ * proves "refuses at the bound" by actually waiting out a 30-second default
+ * would be a slow, flaky proxy for the same assertion a fake clock makes
+ * instantly and exactly.
+ */
+async function waitForWinner(driver, browser, profileDir, options) {
+    const isRunning = options.isRunning ?? browserIsRunning;
+    const timeoutMs = options.waitTimeoutMs ?? options.environment.launchReadinessTimeoutSeconds * 1000;
+    const intervalMs = options.waitPollIntervalMs ?? WAIT_POLL_INTERVAL_MS;
+    const sleep = options.sleepImpl ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = options.nowImpl ?? Date.now;
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        // §1.2c's two checks, unchanged: liveness (the endpoint answers) and
+        // identity (the browser's own identifier matches the record, since ports
+        // are reused). A record that fails either is stale, and a stale record is
+        // reported here exactly as "not yet reachable" — indistinguishable from
+        // the winner still starting, which is the honest state: this function
+        // cannot tell "not up yet" from "up as something else" apart from "not up
+        // yet", and it does not pretend to.
+        const record = await isRunning(profileDir);
+        if (record !== undefined && record.browserUuid !== undefined) {
+            return driver.attach(browser, record);
+        }
+        if (now() >= deadline) {
+            throw new StartupRefusal('launch.explicit_profile_dir', `Another caller is starting the ${browser} browser and it did not become reachable within ${String(timeoutMs)}ms. This is a caller that is still starting, not a browser that has died: nothing here observed a failure, only the absence of a verified discovery record before the bound. Nothing was launched here either way: a second browser against one profile directory hands its address to the first and opens no endpoint of its own. Try again — the browser may still be starting.`);
+        }
+        await sleep(intervalMs);
+    }
+}

package/dist/src/service/capacity.js

@@ -0,0 +1,62 @@
+/**
+ * Admission: one integer against one integer.
+ *
+ * §2.3 reduces the whole capacity model to one sentence, and everything in
+ * this module is a consequence of it:
+ *
+ * > **Capacity, grants and tabs are the same integer.** The pool bound *is*
+ * > the tab budget *is* the count of live claims. **Need two tabs? Claim
+ * > twice.**
+ *
+ * ── The arithmetic a reader expects, and will not find ──────────────────
+ *
+ * Stated as an absence rather than left to be discovered, because each is a
+ * mechanism somebody may arrive looking for (§2.3, `MILESTONES.md` #12):
+ *
+ * - **No request size.** A claim is one tab. There is no requested-count term
+ *   to add to the count, and anyone implementing a `tabs` argument on the
+ *   claim call is implementing a design that was deleted rather than
+ *   re-tuned.
+ * - **No per-lease allowance.** It would be the one number in this design
+ *   answering to no prior decision, invented to stop one caller taking
+ *   everything, and with a grant of one there is nothing for it to bound.
+ * - **No reservation.** Nothing is held for a tab that has not opened,
+ *   because the claim row **is** the capacity. There is no window in which
+ *   granted and existing could differ and therefore no pair of numbers that
+ *   could disagree.
+ *
+ * **So there is one predicate and it is one comparison.** A function taking a
+ * count and a budget would be the natural place for a future size term to
+ * arrive; this one takes a database handle and reads the count itself, so the
+ * only thing a caller can vary is which store it asks.
+ */
+/**
+ * Count the claims that hold a tab, which is what capacity is a count of.
+ *
+ * Reads the index-only partial index over the live claims (§1.11), which is
+ * why the filter is spelled to match it: the answer comes out of the index
+ * without touching the table, and this count is read inside the transaction
+ * every arbitration call opens, with every other caller on the machine
+ * waiting behind it.
+ */
+export function countActiveClaims(db) {
+    const row = db.prepare("SELECT count(*) AS n FROM claims WHERE state = 'active'").get();
+    return row.n;
+}
+/**
+ * The admission predicate, entire: `count of live claims + 1 <= budget`.
+ *
+ * The `+ 1` is the claim being decided, and it is written out rather than
+ * folded into a `<` because §2.3 and `MILESTONES.md` #12 both spell it this
+ * way — the one place the arithmetic of this design appears, spelled as its
+ * specification spells it, so a reader comparing the two is comparing the
+ * same sentence.
+ *
+ * **This reads a count the same transaction has just reconciled** (§7.1,
+ * `capacity.admission`), so it can never admit against capacity held by a
+ * lease that has already lapsed. That property is the runner's — it sweeps
+ * before any handler runs — and not something this function can check.
+ */
+export function admits(activeClaims, budget) {
+    return activeClaims + 1 <= budget;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * The seam between the comparison feature and the capture pipeline.
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHY A SEAM AT ALL, NOW THAT THE CAPTURE PIPELINE EXISTS
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * The capture pipeline is built (`src/capture/pipeline.ts`), so this is no
+ * longer standing in for something absent. It stays because **the direction of
+ * the dependency is a rule the build enforces**, and an interface is what makes
+ * the rule expressible.
+ *
+ * `capture.no_diff_dependency` (§7.3): "**no capture path reads anything
+ * belonging to the diff feature.** This is what keeps the sequencing property
+ * real rather than intended: diffing is built last, so a capture that consulted
+ * it would make the earlier work depend on the later."
+ *
+ * That rule points one way, and this interface is the other way stated
+ * explicitly: **the diff reads capture, capture never reads the diff.** A
+ * capture path can hand a comparison what it needs without knowing a comparison
+ * exists, and `scripts/check-capture-isolation.mjs` fails the build if that
+ * ever inverts — this module is on its diff-owned list precisely so it does.
+ *
+ * ── What the comparison needs, and what it deliberately does not take ───
+ *
+ * Two operations: find a capture, read its bytes. **Not the pipeline itself**,
+ * and not its result type. A diff runs against a capture that was taken at some
+ * earlier moment, quite possibly by an earlier process — so what it needs is a
+ * way to look one up, not a way to take one.
+ *
+ * ── Why this shape and not a direct query ───────────────────────────────
+ *
+ * The direction of the dependency is the whole point. §7.3 carries
+ * `capture.no_diff_dependency`: "**no capture path reads anything belonging to
+ * the diff feature**. This is what keeps the sequencing property real rather
+ * than intended: diffing is built last, so a capture that consulted it would
+ * make the earlier work depend on the later."
+ *
+ * That rule points one way, and this interface is what makes the other way
+ * explicit: **the diff reads capture, capture never reads the diff.** A capture
+ * row can hand this a source and get a diff back without capture knowing what a
+ * comparison is.
+ */
+import fs from 'node:fs/promises';
+const FIND_CAPTURE = `
+SELECT id, claim_id, path, kind, width, height
+  FROM captures
+ WHERE id = @id
+`;
+/**
+ * The capture source backed by the store the capture pipeline writes to.
+ *
+ * **This is the join, and it lives here rather than being left to a caller.**
+ * The capture pipeline writes a `captures` row and a file through the artifact
+ * store; this reads that row back and resolves that file. Both halves use the
+ * same two facts — the table and the store — so there is no third place for
+ * them to disagree.
+ *
+ * The bytes are read through {@link ArtifactStore.resolve}, which is the only
+ * thing in this build that turns a recorded path into a location, and which
+ * refuses a path that escapes the root in **either** namespace. Reading the
+ * file directly would have meant a second resolver, and the second one is the
+ * one that would be missing a case.
+ */
+export function captureSource(db, artifacts) {
+    return {
+        find: (captureId) => {
+            const row = db.prepare(FIND_CAPTURE).get({ id: captureId });
+            if (row === undefined) {
+                return null;
+            }
+            return {
+                id: row.id,
+                claimId: row.claim_id,
+                path: row.path,
+                kind: row.kind,
+                width: row.width,
+                height: row.height,
+            };
+        },
+        readBytes: async (capture) => new Uint8Array(await fs.readFile(artifacts.resolve(capture.path))),
+    };
+}

package/dist/src/service/capture-store.js

@@ -0,0 +1,91 @@
+/**
+ * The `captures` row (§1.7), written by the layer that owns the transaction.
+ *
+ * ── Why this is a module and not two lines inside the capture handler ────
+ *
+ * `capture/pipeline.ts` says outright what it will not do: *"It does not write
+ * a database row"*, and gives the reason — keeping the split means the
+ * pipeline is testable against the fake driver with no store at all. So the
+ * pipeline computes {@link CaptureTelemetry} and somebody else writes it, and
+ * this is that somebody.
+ *
+ * ── The gap this closes, stated as the thing that was true ──────────────
+ *
+ * `takeCapture` had **no caller anywhere in `src/`**. `decideCapture` reached
+ * the browser directly and threw the picture away: no downscaling, no file,
+ * no row. The consequence was measurable and was measured — a caller driving
+ * the shipped binary got `capture -> {"outcome":"accepted",…}` while `SELECT
+ * count(*) FROM captures` returned **0**, which is the exact observation
+ * `TabOperationResult.pageDriven` was added to describe. `pageDriven` made the
+ * silence honest; this makes the picture exist.
+ *
+ * ── Written after the commit, and why that is correct rather than a compromise ──
+ *
+ * A capture is browser work: it settles the page, takes a picture and writes a
+ * file, none of which may happen inside the arbitration transaction (§2.4b).
+ * So the row is written on its own short statement afterwards, the same way
+ * `recordTabOpened` writes a driver name after a page is opened.
+ *
+ * **The row is the record that a file exists**, so writing it before the file
+ * would be the same class of error this whole area keeps producing: a store
+ * asserting something that did not happen. It is written last, from telemetry
+ * describing a file that is already on disk.
+ */
+/**
+ * Append one capture row.
+ *
+ * `taken_at`, `created_at` and `updated_at` are left to their defaults except
+ * `taken_at`, which carries the pipeline's own instant: the pipeline stamps
+ * the file name from it, and a row whose timestamp disagreed with the name of
+ * the file it points at would be unreadable as a pair.
+ */
+export function recordCapture(db, claimId, tabId, telemetry) {
+    db.prepare(`INSERT INTO captures (
+       id, claim_id, tab_id, taken_at, kind, tier, reason,
+       source_width, source_height, width, height, bytes,
+       path, selector, viewport_width, url, warned
+     ) VALUES (
+       @id, @claimId, @tabId, @takenAt, @kind, @tier, @reason,
+       @sourceWidth, @sourceHeight, @width, @height, @bytes,
+       @path, @selector, @viewportWidth, @url, @warned
+     )`).run({
+        id: telemetry.id,
+        claimId,
+        tabId,
+        takenAt: telemetry.takenAt.toISOString(),
+        kind: telemetry.kind,
+        tier: telemetry.tier,
+        // `null` rather than `undefined`: the driver refuses a bound parameter
+        // that is undefined, and the column is nullable precisely because a reason
+        // is owed only on the top tier.
+        reason: telemetry.reason ?? null,
+        sourceWidth: telemetry.sourceWidth,
+        sourceHeight: telemetry.sourceHeight,
+        width: telemetry.width,
+        height: telemetry.height,
+        bytes: telemetry.bytes,
+        path: telemetry.path,
+        selector: telemetry.selector ?? null,
+        viewportWidth: telemetry.viewportWidth,
+        url: telemetry.url,
+        // The column is an integer with a check constraint on (0, 1); the store is
+        // STRICT, so a boolean would be refused rather than coerced.
+        warned: telemetry.warned ? 1 : 0,
+    });
+}
+/**
+ * How many captures this lease has already taken.
+ *
+ * `takeCapture` takes this as an argument because *"counting is a query
+ * against the store and this module reaches no store"* — so the count is made
+ * here and handed in. It decides only the accounting warning, which is
+ * guidance and never a refusal (`capture/accounting.ts`), so a count read a
+ * moment before another process writes its own row costs a warning that fires
+ * one capture late. It is not a budget and nothing is denied on it.
+ */
+export function capturesTakenBy(db, claimId) {
+    const row = db
+        .prepare('SELECT count(*) AS taken FROM captures WHERE claim_id = ?')
+        .get(claimId);
+    return row?.taken ?? 0;
+}