browser-broker 0.1.0

package/dist/src/service/operations/pages.js

@@ -0,0 +1,771 @@
+import { updateSweptTabs } from "../arbitration.js";
+import { append } from "../events.js";
+import { extendLease, resolveLease } from "../leases.js";
+import { resolveOwnedTabOrRefuse } from "../ownership.js";
+import { disposeEvaluationResult, MAX_INLINE_RESULT_BYTES, validateCaptureMode, resolveReadArtifacts, validateAction, validateExpression, validateNavigationTarget, } from "../pages.js";
+import { recordTabOpened, reserveTab } from "../tabs.js";
+import { seedRecord } from "../storage-seed.js";
+import { BrokerError } from "../../errors.js";
+import { sanitiseLabel, stampFromInstant } from "../../artifacts/names.js";
+import { takeCapture } from "../../capture/pipeline.js";
+import { capturesTakenBy, recordCapture } from "../capture-store.js";
+import { captureSource } from "../capture-seam.js";
+import { insertComparison } from "../comparison-store.js";
+import { runComparison } from "../comparison.js";
+import { DEFAULT_DIFF_SETTINGS } from "../../diff/settings.js";
+/**
+ * Steps 1 to 3, which are identical for all six and therefore written once.
+ *
+ * Written as one function rather than copied into each handler because the
+ * order is the rule: a handler that validated before renewing, or resolved
+ * the tab before validating, would refuse in a different order than every
+ * other operation, and the difference would be invisible until a caller
+ * depended on it.
+ */
+function admit(scope, input, kind) {
+    const { db, adapter, swept } = scope;
+    const lease = resolveLease(db, input.key, {
+        adapter,
+        kind: 'claim_renewed',
+        recordRefusal: scope.recordRefusal,
+    });
+    const expiresAt = extendLease(db, lease, { adapter, now: swept.sweptAt });
+    const tab = resolveOwnedTabOrRefuse(db, lease, input.tabId, {
+        adapter,
+        kind,
+        recordRefusal: scope.recordRefusal,
+    });
+    return { lease, tab, expiresAt };
+}
+/**
+ * Get the page this tab names, opening it if it has never been opened.
+ *
+ * ── Why the page is opened here rather than when the lease was granted ──
+ *
+ * Granting a lease reserves a tab **row** — `opening`, with no driver name,
+ * because §1.4 requires a tab to carry a driver name only once a page
+ * genuinely exists. Nothing about granting capacity requires a page to exist
+ * yet, and it would be the wrong moment to make one: the grant happens inside
+ * the arbitration transaction, and opening a page there is precisely the
+ * browser I/O §2.4b forbids.
+ *
+ * So the page is opened the first time somebody actually addresses the tab,
+ * after that call's commit, by the caller that has the browser connection.
+ * That is also the only moment at which a session is guaranteed to be
+ * available: capacity can be granted to a caller that has not connected to
+ * anything, and refusing to grant it until one had would make the queue
+ * depend on the caller's own connection state.
+ *
+ * **The driver name is written on its own statement, outside the arbitration
+ * transaction that has already committed.** It is a single-row update against
+ * a row nobody else can address — the tab belongs to one lease, and this runs
+ * only for the caller holding that lease's key.
+ */
+async function pageFor(scope, session, tab, input, claimId) {
+    if (tab.driverTabId !== null) {
+        return { browser: tab.browserId, driverTabId: tab.driverTabId };
+    }
+    const opened = await session.openTab();
+    recordTabOpened(scope.db, tab.tabId, opened.driverTabId);
+    // ── The seed, here and nowhere else (§3.2, row #65) ───────────────────
+    //
+    // **This is the only moment that satisfies "before the tab's first
+    // navigation".** The page has just been created and no caller has
+    // addressed it yet — the verb that triggered this open has not run its own
+    // work, because `pageFor` is awaited first. A seed written any later would
+    // be written after the load it exists to precede, which is the whole
+    // feature; a seed written any earlier has no page to write into.
+    //
+    // It is also correctly outside the arbitration transaction: this runs
+    // inside an after-commit closure (§2.4b), which is why `openTab` above is
+    // allowed to be here at all.
+    await applyPendingSeed(scope, session, opened, tab, input, claimId);
+    return opened;
+}
+/**
+ * Write a granted lease's seed into its brand-new page, and record what was
+ * actually written.
+ *
+ * ── Why the ledger row is written here rather than at claim time ────────
+ *
+ * The claim appends a `storage_seeded` row saying a seed was **requested**,
+ * which is the whole of what is true at that point: the claim is decided
+ * inside the arbitration transaction, and §2.4b keeps browser work outside
+ * it, so the tab is a row with no page behind it. This row says what was
+ * **applied**, and the distinction is the point: §3.2 wants *"which leases
+ * started life already holding a credential"* answerable, and a request is
+ * not an answer to that. A ledger that recorded the ask and not the act
+ * overstates, and a security question answered by an overstatement is read as
+ * an all-clear.
+ *
+ * **Origins and keys, never values**, through `seedRecord` — the same
+ * structural redaction the claim's row uses, so neither call site can leak a
+ * value by being written carelessly.
+ *
+ * ── A seed that fails is a seed that is not recorded ────────────────────
+ *
+ * The throw propagates. It is not caught here, and that is deliberate: the
+ * caller is `pageFor`, inside the after-commit closure `afterCommitWork`
+ * built, whose `catch` records the reason and rethrows for the runner to
+ * swallow (§2.4b). So a browser that refuses the write leaves the lease real,
+ * the decision committed, `pageDriven: false`, a reason the caller can read —
+ * **and no `applied` row**, because the row is written after the write
+ * returns. A caller told its page was not driven has been told its seed did
+ * not land.
+ */
+async function applyPendingSeed(scope, session, page, tab, input, claimId) {
+    const entries = input.pendingSeeds?.take(claimId) ?? [];
+    if (entries.length === 0) {
+        return;
+    }
+    // **The driver seam, with the entries as data.** `seedStorage` takes a list
+    // of origin/area/key/string — there is no position in that signature in
+    // which a caller's bytes could be read as a program, which is the entire
+    // safety argument for this feature. Nothing here builds an init script, a
+    // template or any other source text out of an entry, and doing so would
+    // rebuild the interpreting position §3.2 exists to avoid.
+    await session.seedStorage(page, entries);
+    append(scope.db, {
+        kind: 'storage_seeded',
+        outcome: 'allow',
+        adapter: scope.adapter,
+        claimId,
+        tabId: tab.tabId,
+        browserId: tab.browserId,
+        detail: { entries: seedRecord(entries), seed: 'applied' },
+    });
+}
+/**
+ * Schedule one piece of browser work, if the caller brought a browser.
+ *
+ * **Returns the fact alongside the work, because this is the only place that
+ * knows it.** Handing `pageDriven` back next to `afterCommit` means the report
+ * and the reality are computed once, from the same place, and no handler can
+ * spell the answer differently from the work it scheduled.
+ *
+ * ── Why this is a getter and not a plain boolean ────────────────────────
+ *
+ * It used to answer `input.session === undefined`, which was exactly right
+ * while nothing ever supplied a session: with no session there is no browser,
+ * and `false` was a fact at the moment it was computed.
+ *
+ * **The moment a session is supplied, that same expression becomes a
+ * prediction rather than a fact** — and predicting `true` before the browser
+ * has been touched reintroduces the precise defect this field was added to
+ * remove, only harder to see. Every failure in after-commit work is swallowed
+ * by design (§2.4b), so a browser that is not installed, refuses to launch,
+ * loses the launch race, or dies mid-operation produces **no error anywhere a
+ * caller can see it**. A caller would be told `accepted` with `pageDriven:
+ * true` for a navigation that never happened. That is the same lie as the
+ * capture that wrote no row, told with more confidence.
+ *
+ * So the answer is not settled until the work has either run or failed. The
+ * runner awaits every after-commit action **before** the value is returned
+ * (`store/transaction.ts`), so by the time any caller can read this field the
+ * work is over — and the field reads a flag the work itself set.
+ *
+ * **Report and reality are still one expression**, which was the property
+ * worth keeping: `driven` is written in exactly one place, the last statement
+ * of the closure that does the driving. It cannot be set by a handler, it
+ * cannot be set on a path that skipped the work, and it cannot be set by the
+ * failure path, because the throw happens first.
+ *
+ * ── Every failure is still swallowed, and now it is also reported ───────
+ *
+ * The swallowing is unchanged and required: the transaction has committed, the
+ * decision stands, capacity was taken, and a driver that will not answer
+ * cannot be allowed to unmake it. What the swallowing does not do is tell the
+ * caller the page moved. It gets `accepted` — because the arbitration half
+ * genuinely happened and is genuinely durable — carrying `pageDriven: false`,
+ * which is the honest description of *your lease is real and your page is
+ * not*. What it costs is visible in the store rather than hidden: a tab whose
+ * page could not be opened keeps its `opening` row and no driver name.
+ */
+function afterCommitWork(scope, input, tab, work, claimId) {
+    const source = input.session;
+    if (source === undefined) {
+        return {
+            afterCommit: [],
+            pageDriven: false,
+            notDrivenReason: 'This build has no browser to drive: the call was decided, recorded and its lease renewed, but no page was touched.',
+        };
+    }
+    // The one mutable cell, written by the one statement below and read by the
+    // getter. Not exposed: a handler receives the getter and never this.
+    let driven = false;
+    // ── Why the failure's reason is kept, and not only the fact of it ───────
+    //
+    // `pageDriven: false` is honest and it is **not actionable**: it says the
+    // page did not move and says nothing about whether the caller can do
+    // anything about that. The causes want opposite responses — a browser that
+    // will not launch is not the caller's to fix, while a stale element
+    // reference is fixed by reading the page again, which is a thing a caller
+    // can do unattended and immediately.
+    //
+    // The failure is still swallowed (§2.4b) and the outcome is still
+    // `accepted`, both for the reasons above; what changes is that the reason
+    // travels with the report instead of dying in the runner's empty `catch`.
+    // A refusal's `rule` is carried when there is one, because that is the
+    // half a caller can branch on without matching on English.
+    let notDrivenReason;
+    return {
+        afterCommit: [
+            async () => {
+                try {
+                    const session = await source(tab.browserId);
+                    await work(session, await pageFor(scope, session, tab, input, claimId));
+                    // **Last, deliberately.** Anything above this that throws leaves the
+                    // flag false, which is what makes a browser failing mid-operation
+                    // report as the page not having been driven rather than as success.
+                    driven = true;
+                }
+                catch (error) {
+                    // Recorded, then **rethrown unchanged**. The runner's swallow is
+                    // what keeps a committed decision from being unmade by a browser
+                    // that will not answer, and catching here without rethrowing would
+                    // quietly take that path over — including for the callers of this
+                    // helper that are not about references at all.
+                    notDrivenReason =
+                        error instanceof BrokerError
+                            ? `${error.rule}: ${error.message}`
+                            : error instanceof Error
+                                ? error.message
+                                : String(error);
+                    throw error;
+                }
+            },
+        ],
+        get pageDriven() {
+            return driven;
+        },
+        get notDrivenReason() {
+            return notDrivenReason;
+        },
+    };
+}
+/**
+ * Attach the scheduled work's live answer to a result that carries everything
+ * else.
+ *
+ * ── Why a helper and not `pageDriven: work.pageDriven` at each site ─────
+ *
+ * That spelling **reads the getter immediately** and copies the boolean into
+ * the object, which puts the answer back where it was: decided before the
+ * browser was touched. The bug would be invisible — the property is there, it
+ * is the right name, it holds a value from the right place — and it would
+ * report `true` for every failed navigation.
+ *
+ * Composing the getter through instead means the six results share one
+ * definition of the field, so it cannot hold on five verbs and be a stale copy
+ * on the sixth. That is the same reason {@link TabOperationResult} declares it
+ * on the shared base rather than on each verb.
+ */
+function withPageDriven(value, work) {
+    const withFlag = Object.defineProperty(value, 'pageDriven', {
+        get: () => work.pageDriven,
+        enumerable: true,
+    });
+    // Composed through the same way and for the same reason: read eagerly it
+    // would always be `undefined`, because nothing has run yet.
+    return Object.defineProperty(withFlag, 'notDrivenReason', {
+        get: () => work.notDrivenReason,
+        enumerable: true,
+    });
+}
+/**
+ * `navigate` (§3.5) — point an owned tab at an address.
+ *
+ * The address is checked against the scheme allowlist before anything is
+ * written, so a refused scheme leaves no trace but the refusal row.
+ */
+export function decideNavigate(scope, input) {
+    const url = validateNavigationTarget(input.url);
+    const { lease, tab, expiresAt } = admit(scope, input, 'navigate');
+    append(scope.db, {
+        kind: 'navigate',
+        outcome: 'allow',
+        adapter: scope.adapter,
+        claimId: lease.claimId,
+        tabId: tab.tabId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        detail: { url },
+    });
+    const work = afterCommitWork(scope, input, tab, (session, page) => session.navigate(page, url), lease.claimId);
+    return {
+        value: withPageDriven({ claimId: lease.claimId, tabId: tab.tabId, expiresAt, url }, work),
+        afterCommit: work.afterCommit,
+    };
+}
+/**
+ * `act` (§3.6) — one interaction against an owned tab.
+ *
+ * The argument shape is turned from `unknown` into the driver's discriminated
+ * union by `validateAction`, which is the boundary the driver seam asks for:
+ * no cast, and thirteen actions each with their own required fields.
+ */
+export function decideAct(scope, input) {
+    const request = validateAction(input.request);
+    const { lease, tab, expiresAt } = admit(scope, input, 'act');
+    append(scope.db, {
+        kind: 'act',
+        outcome: 'allow',
+        adapter: scope.adapter,
+        claimId: lease.claimId,
+        tabId: tab.tabId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        detail: { action: request.action },
+    });
+    const work = afterCommitWork(scope, input, tab, (session, page) => session.act(page, request), lease.claimId);
+    return {
+        value: withPageDriven({ claimId: lease.claimId, tabId: tab.tabId, expiresAt, action: request.action }, work),
+        afterCommit: work.afterCommit,
+    };
+}
+/**
+ * `read` (§3.7) — collect artifacts from an owned tab.
+ */
+export function decideRead(scope, input) {
+    const artifacts = resolveReadArtifacts(input.artifacts);
+    const { lease, tab, expiresAt } = admit(scope, input, 'read');
+    append(scope.db, {
+        kind: 'read',
+        outcome: 'allow',
+        adapter: scope.adapter,
+        claimId: lease.claimId,
+        tabId: tab.tabId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        detail: { artifacts: [...artifacts] },
+    });
+    // Set inside the after-commit closure and read by the getter below — the
+    // same arrangement `decideCapture` uses for `written`, and for the same
+    // reason: the paths do not exist until the work has run, so a value read
+    // eagerly here would always be empty.
+    let collected;
+    const work = afterCommitWork(scope, input, tab, async (session, page) => {
+        const results = await session.read(page, artifacts);
+        // **The return value is what carries the paths.** The driver knows them;
+        // a handler that ignores this leaves the caller unable to open anything
+        // it just collected.
+        collected = results.map((result) => ({
+            artifact: result.artifact,
+            path: result.path,
+            bytes: result.bytes,
+        }));
+    }, lease.claimId);
+    const value = withPageDriven({ claimId: lease.claimId, tabId: tab.tabId, expiresAt, artifacts }, work);
+    return {
+        // Enumerable, deliberately: both surfaces serialise their result, and a
+        // getter that is not enumerable is invisible to `JSON.stringify` — present
+        // in process, absent on the wire.
+        value: Object.defineProperty(value, 'collected', {
+            get: () => collected,
+            enumerable: true,
+        }),
+        afterCommit: work.afterCommit,
+    };
+}
+/**
+ * `evaluate` (§3.9) — run an expression in an owned tab.
+ *
+ * The expression is bounded and otherwise uninspected: there is no allowlist
+ * and no filtering, which `pages.ts` states as a deliberate position rather
+ * than an omission. **This handler adds no target, context, world or scope
+ * argument to that path**, which that file's comment names as the specific
+ * way the capability it declined would arrive back by accident.
+ */
+export function decideEvaluate(scope, input) {
+    const expression = validateExpression(input.expression);
+    const { lease, tab, expiresAt } = admit(scope, input, 'evaluate');
+    const expressionBytes = Buffer.byteLength(expression, 'utf8');
+    append(scope.db, {
+        kind: 'evaluate',
+        outcome: 'allow',
+        adapter: scope.adapter,
+        claimId: lease.claimId,
+        tabId: tab.tabId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        // The expression itself is not recorded. It is caller code, it can be
+        // four kilobytes of it, and the ledger is read by people.
+        detail: { expressionBytes },
+    });
+    // Set inside the after-commit closure and read by the getter below — the
+    // arrangement `decideCapture` uses for `written`, and for the same reason:
+    // the value does not exist until the work has run, so a copy taken here
+    // would always be absent. **This is row #24's missing half.** The
+    // evaluation already happened in after-commit, correctly (§2.4b); what was
+    // absent was any path by which its value reached the caller.
+    let evaluated;
+    const artifacts = input.artifacts;
+    const work = afterCommitWork(scope, input, tab, async (session, page) => {
+        const result = await session.evaluate(page, expression);
+        // The spill decision is made against the result the page actually
+        // produced, which is only knowable here. `disposeEvaluationResult` is
+        // what decides it, and it is the same function the seam's own tests
+        // measure.
+        const disposition = disposeEvaluationResult(result.value);
+        if (!disposition.spill) {
+            evaluated = { spilled: false, value: disposition.serialised, bytes: disposition.bytes };
+            return;
+        }
+        // ── Past the cap, and nowhere to put it ──────────────────────────────
+        //
+        // **Thrown rather than returned**, for the reason `decideCapture` gives
+        // where it is handed a browser and no store: running to completion here
+        // would report `pageDriven: true` for a call whose value the caller
+        // cannot reach, in either place §3.10 says it may be. Throwing takes the
+        // ordinary after-commit failure path — swallowed by the runner, ledger
+        // row and decision still committed — so the caller is told plainly, and
+        // `notDrivenReason` carries which of the two it was.
+        if (artifacts === undefined) {
+            throw new BrokerError('evaluate.result_serialisable', `That expression produced ${String(disposition.bytes)} bytes, past the ${String(MAX_INLINE_RESULT_BYTES)}-byte inline limit, and this call supplied no artifact store to spill it into. Nothing was returned.`);
+        }
+        // The same store, the same refusal and the same relative-path form every
+        // other artefact uses (§1.7a). Written through `ArtifactStore.write` and
+        // not `writeFileSync`, because that method is the single implementation
+        // that refuses a name resolving outside the root.
+        const stored = artifacts.write(lease.claimId, 'snapshots', evaluationFileName(new Date(), lease.claimId), Buffer.from(disposition.serialised, 'utf8'));
+        evaluated = { spilled: true, path: stored.relativePath, bytes: disposition.bytes };
+    }, lease.claimId);
+    return {
+        value: withPageDriven({
+            claimId: lease.claimId,
+            tabId: tab.tabId,
+            expiresAt,
+            expressionBytes,
+            // A getter for the same reason `pageDriven` is one — see
+            // {@link withPageDriven}. Read eagerly it would always be absent.
+            get result() {
+                return evaluated;
+            },
+        }, work),
+        afterCommit: work.afterCommit,
+    };
+}
+/**
+ * What a spilled evaluation is called on disk.
+ *
+ * Every part is derived rather than supplied: an instant and the claim, both
+ * of which this service generates. **Nothing a caller sent reaches the name**
+ * — not the expression, not the value — which is `names.ts`'s rule one
+ * (a file name travels further than a column does) applied to the one
+ * artefact whose contents are entirely the caller's.
+ *
+ * `.json` because the contents are exactly what `JSON.stringify` produced,
+ * and a reader opening the file should be able to tell.
+ */
+function evaluationFileName(when, claimId) {
+    return `evaluation-${stampFromInstant(when)}-${sanitiseLabel(claimId)}.json`;
+}
+/**
+ * `capture` (§3.10) — take an image of an owned tab.
+ *
+ * **`fullPage` defaults to false rather than being required**, which is the
+ * one reading this handler had to choose: `CaptureRequest` makes the field
+ * mandatory on the seam, and no validator for it exists anywhere in
+ * `pages.ts`. A viewport capture is the cheaper and more common of the two
+ * and is what a caller who did not think about it almost certainly wants, so
+ * that is the default. The choice is recorded in the ledger either way, so a
+ * caller surprised by it can see what was actually taken.
+ */
+export function decideCapture(scope, input) {
+    const fullPage = input.fullPage === true;
+    // **Before `admit`, like every other argument validation in this file.** A
+    // capture that contradicts itself is refused before the lease is resolved,
+    // before ownership is checked and before a single row is written, so the
+    // refusal leaves nothing behind but its own ledger entry.
+    validateCaptureMode({ fullPage, selector: input.selector });
+    const request = {
+        fullPage,
+        ...(input.selector === undefined ? {} : { selector: input.selector }),
+    };
+    const { lease, tab, expiresAt } = admit(scope, input, 'capture');
+    append(scope.db, {
+        kind: 'capture',
+        outcome: 'allow',
+        adapter: scope.adapter,
+        claimId: lease.claimId,
+        tabId: tab.tabId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        detail: { fullPage },
+    });
+    // Read inside the transaction, where every other read this handler makes
+    // happens. It decides the accounting warning only — never a refusal — so
+    // reading it here rather than in the closure costs nothing but keeps the
+    // store access on the transaction's side of §2.4b.
+    const takenBefore = input.artifacts === undefined ? 0 : capturesTakenBy(scope.db, lease.claimId);
+    let written;
+    // Set inside the after-commit closure, read by the getter below — the same
+    // arrangement `written` uses and for the same reason: neither value exists
+    // until the work has run.
+    let compared;
+    const artifacts = input.artifacts;
+    const compareTo = input.compareTo;
+    const work = afterCommitWork(scope, input, tab, async (session, page) => {
+        if (artifacts === undefined) {
+            // A browser but nowhere to put the picture. Taking one and dropping it
+            // is precisely the behaviour this handler exists to stop, so the shutter
+            // is not pressed at all.
+            //
+            // **Thrown rather than returned**, and the difference is the honesty of
+            // the answer. Returning would leave the closure to run to completion and
+            // report `pageDriven: true` — for a call that reached no page, wrote no
+            // file and left `captures` empty, which is the precise combination this
+            // field exists to make impossible. Throwing takes the same path a
+            // browser failure takes: swallowed by the runner (§2.4b), the decision
+            // and its ledger row still committed, and the caller told plainly that
+            // nothing was driven.
+            throw new BrokerError('capture.arguments_consistent', 'A capture needs somewhere to write the image, and this call supplied a browser without one. No picture was taken.');
+        }
+        // **The pipeline, not `session.capture` directly.** Reaching the seam here
+        // was the defect: it skipped the settle, the downscale to the requested
+        // rung, and the write through the artifact store — the only thing that
+        // decides where a file may go — and then discarded the bytes. Everything
+        // the `captures` row needs comes back as telemetry.
+        const taken = await takeCapture({ tabs: session, artifacts }, lease.claimId, page, {
+            fullPage,
+            ...(request.selector === undefined ? {} : { selector: request.selector }),
+        }, takenBefore);
+        // The row last, describing a file that is already on disk. See
+        // `capture-store.ts` for why that order is the rule and not a preference.
+        recordCapture(scope.db, lease.claimId, tab.tabId, taken.telemetry);
+        written = {
+            captureId: taken.captureId,
+            path: taken.path,
+            width: taken.width,
+            height: taken.height,
+            bytes: taken.bytes,
+        };
+        // ── The diff, when one was asked for (§3.11, §1.9) ──────────────────
+        //
+        // **Here, and not one line earlier.** Three separate rules put it at this
+        // exact point and they agree:
+        //
+        // 1. §2.4b — never browser I/O inside the arbitration transaction. This
+        //    whole closure is after-commit, so the shutter above already obeyed
+        //    that. The comparison itself is arithmetic over two decoded images
+        //    and some file writes: no browser, no seam method, nothing that could
+        //    reintroduce the thing that rule forbids.
+        // 2. §1.7 order — the `captures` row is written above, *before* this
+        //    runs, because the comparison names that capture as its source and a
+        //    row referencing one that does not exist yet is a foreign key waiting
+        //    to fail.
+        // 3. `capture.no_diff_dependency` (§7.3) — the direction still runs one
+        //    way. This module reads the diff feature; the diff feature does not
+        //    read this. `takeCapture` was handed no comparison argument and
+        //    returned before any of this was considered, so the pipeline remains
+        //    a module that could be built with the diff feature deleted.
+        //
+        // **Nothing here can fail the capture.** `runComparison` throws only on a
+        // programming mistake and returns an explanation for every caller-caused
+        // failure, so a diff that cannot run leaves `written` exactly as it is
+        // above and the caller still gets its picture — which is §3.11's rule that
+        // an optional argument may not withhold the thing it is optional on.
+        if (compareTo !== undefined) {
+            const source = captureSource(scope.db, artifacts);
+            const justTaken = {
+                id: taken.captureId,
+                claimId: lease.claimId,
+                path: taken.path,
+                kind: taken.telemetry.kind,
+                width: taken.width,
+                height: taken.height,
+            };
+            compared = await runComparison({
+                capture: justTaken,
+                // **Read back through the seam rather than kept from the pipeline.**
+                // `takeCapture` returns `bytes` as a *file size*, not the image, and
+                // deliberately so — §3.11 is emphatic that a capture result carries
+                // "a path, the dimensions … **Never the image**", and `CaptureResult`
+                // has no field that could hold pixels. So the bytes are read from the
+                // file just written, through `ArtifactStore.resolve` — the single
+                // implementation that refuses a path escaping the root in either
+                // namespace. Reading the file directly would have meant a second
+                // resolver, and the second one is the one missing a case.
+                captureBytes: await source.readBytes(justTaken),
+                targetCaptureId: compareTo,
+                source,
+                settings: input.diffSettings ?? DEFAULT_DIFF_SETTINGS,
+                artifacts,
+                // The row is written through the same handle every other write in
+                // this closure uses, so a comparison and the capture it describes
+                // cannot end up in different states of the store.
+                writeRow: (row) => insertComparison(scope.db, row),
+            });
+        }
+    }, lease.claimId);
+    return {
+        value: withPageDriven({
+            claimId: lease.claimId,
+            tabId: tab.tabId,
+            expiresAt,
+            fullPage,
+            // A getter for the same reason `pageDriven` is one: the value is not
+            // known until the after-commit work has run, and a copy taken here
+            // would always be absent.
+            get capture() {
+                return written;
+            },
+            // A getter for the same reason `capture` is one. Stays `undefined`
+            // when no diff was asked for, which is what distinguishes "you did
+            // not ask" from a comparison that ran and found nothing.
+            get comparison() {
+                return compared;
+            },
+        }, work),
+        afterCommit: work.afterCommit,
+    };
+}
+/**
+ * `tab_replace` (§3.11) — give up this lease's tab and take a fresh one.
+ *
+ * ── Why this is one operation and not a release followed by a claim ─────
+ *
+ * A lease is one tab (§2.3), so a caller wanting a clean page has to give up
+ * the one it has. Doing that as two calls means dropping to zero tabs in
+ * between — at which point the capacity it just freed is fair game for
+ * whoever is at the front of the queue, and a caller tidying up its own page
+ * can lose its lease for doing so. Inside one transaction the count never
+ * dips, and nothing can be promoted into the gap because there is no gap.
+ *
+ * Closing the tab being given up is after-commit work, like every other
+ * close: the row goes to `closing` inside the transaction, which is §1.4's
+ * honest representation of *the tool was asked and has not answered*, and a
+ * tab that does not close is a leaked tab rather than a leaked lease.
+ */
+export function decideTabReplace(scope, input) {
+    const { db, adapter } = scope;
+    const { lease, tab, expiresAt } = admit(scope, input, 'tab_closing');
+    const browser = tab.browserId;
+    // Out first, in second, both inside the one transaction. The order matters
+    // only for the ledger reading sensibly; the count never changes, because
+    // the reservation is written before the commit that would have let anyone
+    // else see the tab go.
+    //
+    // **Which state the tab goes out through is not this operation's rule to
+    // invent**, and writing it here was a real defect the schema caught: a tab
+    // still `opening` has no page, and moving one to `closing` asserts an
+    // outstanding round trip that nobody is coming to answer — which the
+    // `(state = 'opening') = (driver_tab_id IS NULL)` constraint refuses
+    // outright. `updateSweptTabs` is the one place that rule is written, it is
+    // exported precisely so the sweep and release cannot spell it differently,
+    // and this is the third caller that needs exactly it. What comes back is
+    // the subset a browser still owes an answer about.
+    const pendingCloses = updateSweptTabs(db, [{ tabId: tab.tabId, claimId: lease.claimId, browserId: browser }], scope.swept.sweptAt);
+    append(db, {
+        kind: 'tab_closing',
+        outcome: 'allow',
+        adapter,
+        claimId: lease.claimId,
+        tabId: tab.tabId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        detail: { givenUpFor: 'a fresh tab', pageToClose: pendingCloses.length === 1 },
+    });
+    const replacementId = reserveTab(db, lease.claimId, browser);
+    append(db, {
+        kind: 'tab_opening',
+        outcome: 'allow',
+        adapter,
+        claimId: lease.claimId,
+        tabId: replacementId,
+        sessionId: lease.sessionId,
+        browserId: tab.browserId,
+        detail: { takenOverFrom: tab.tabId },
+    });
+    const source = input.session;
+    // **The same live answer the other five verbs give, not a second spelling of
+    // it.** This handler cannot use `afterCommitWork` — its work closes one page
+    // and opens another rather than driving one, so it does not take that
+    // helper's shape — and the previous arrangement answered `source !==
+    // undefined` here instead. That was a *second* computation of a field whose
+    // whole value is that it is computed once: correct while nothing supplied a
+    // session, and a prediction the moment something did.
+    //
+    // It matters more here than anywhere else, for the reason
+    // {@link TabReplaceResult.pageDriven} gives: this verb exchanges the tab in
+    // the store regardless, so a caller told the swap succeeded believes it holds
+    // a clean page. If the browser could not be reached, it holds a fresh
+    // identifier over a row that is still `opening` with nothing under it.
+    //
+    // So the flag is declared here and written by the closure below, and the
+    // field is composed by {@link withPageDriven} — the same function the other
+    // five go through, which is what stops the two answers drifting.
+    let driven = false;
+    // Carried for the same reason and by the same rule as in
+    // {@link afterCommitWork}: the fact that the swap did not reach a browser is
+    // not actionable on its own. This verb addresses no element, so the stale
+    // reference case cannot arise here — what it reports is a browser that could
+    // not be reached or a page that would not open.
+    let notDrivenReason = source === undefined
+        ? 'This build has no browser to drive: the tab was exchanged in the store, but no page was opened for it.'
+        : undefined;
+    const work = {
+        get pageDriven() {
+            return driven;
+        },
+        get notDrivenReason() {
+            return notDrivenReason;
+        },
+        afterCommit: source === undefined
+            ? []
+            : [
+                async () => {
+                    try {
+                        const session = await source(browser);
+                        // The tab being given up is closed first, and only if a page
+                        // was ever opened for it. If it will not close it is a leaked
+                        // tab; the fresh one is owed either way, and making it wait on
+                        // a page that is refusing to die is how one stuck close turns
+                        // into a lease with no tab at all.
+                        // At most one, and empty when no page was ever opened for this
+                        // tab — in which case there is nothing to ask a browser about
+                        // and the row is already `closed`.
+                        if (pendingCloses.length > 0 && tab.driverTabId !== null) {
+                            try {
+                                await session.closeTab({ browser, driverTabId: tab.driverTabId });
+                            }
+                            catch {
+                                // Best effort (§2.4b). The row stays `closing`, which is
+                                // what the administrative clear-a-leaked-tab operation
+                                // selects on.
+                            }
+                        }
+                        const opened = await session.openTab();
+                        // Recorded on its own connection-free path: this runs after the
+                        // commit, so it opens its own short write rather than
+                        // reaching back into a transaction that is gone.
+                        recordTabOpened(scope.db, replacementId, opened.driverTabId);
+                        // Last, for the same reason it is last in `afterCommitWork`: a
+                        // throw above leaves this false, so a browser that failed
+                        // partway through reports the page as not driven.
+                        driven = true;
+                    }
+                    catch (error) {
+                        // Recorded and rethrown unchanged, so the runner's swallow
+                        // (§2.4b) still governs what a failure costs.
+                        notDrivenReason =
+                            error instanceof BrokerError
+                                ? `${error.rule}: ${error.message}`
+                                : error instanceof Error
+                                    ? error.message
+                                    : String(error);
+                        throw error;
+                    }
+                },
+            ],
+    };
+    return {
+        value: withPageDriven({
+            claimId: lease.claimId,
+            previousTabId: tab.tabId,
+            tabId: replacementId,
+            expiresAt,
+        }, work),
+        afterCommit: work.afterCommit,
+    };
+}