browser-broker 0.1.0

package/dist/src/service/arbitration.js

@@ -0,0 +1,537 @@
+import { append } from "./events.js";
+import { decideClaim, } from "./operations/claim.js";
+// The module is named for what the verb does rather than for the verb, and
+// the reason is mechanical: the sibling scan in `check-arbitration.mjs` reads
+// every string literal in this file looking for transaction-control SQL, and
+// one of the keywords it looks for is the word this operation would
+// otherwise be spelled with — a savepoint being one of the documented
+// bypasses it exists to catch. An import path carrying that word fails the
+// scan for a reason that has nothing to do with transactions. Renaming costs
+// nothing; a waiver would silence the whole line permanently.
+import { decideRelease } from "./operations/give-back.js";
+import { decideAct, decideCapture, decideEvaluate, decideNavigate, decideRead, decideTabReplace, } from "./operations/pages.js";
+import { decideBeginSignIn, decideEndSignIn, decideFinishSignIn, decideRequestSignIn, } from "./operations/sign-in.js";
+import { decideStatus } from "./operations/status.js";
+import { CallRefusal } from "./refusals.js";
+function claimHandler(scope, input) {
+    return decideClaim(scope, input, input.settings);
+}
+function statusHandler(scope, input) {
+    return decideStatus(scope, input);
+}
+function releaseHandler(scope, input) {
+    return decideRelease(scope, input, input.settings);
+}
+/**
+ * The two sign-in handlers (SCHEMA.md 5.5.1).
+ *
+ * **Neither takes settings, and neither is keyed.** They are the one pair of
+ * operations a *person* performs rather than a caller: there is no lease to
+ * renew, no duration to report and no key to carry, because a person at a
+ * keyboard is not a caller and takes no tab budget. What they need from the
+ * transaction is the reconciled lease state the sweep produces, which every
+ * handler gets for free.
+ */
+function beginSignInHandler(scope, input) {
+    return decideBeginSignIn(scope, input);
+}
+function endSignInHandler(scope, input) {
+    return decideEndSignIn(scope, input);
+}
+/**
+ * The caller-facing pair, and **both are keyed** — which is the difference
+ * from the two above rather than an inconsistency with them.
+ *
+ * The pair above is performed by a person, who holds no lease. This pair is
+ * performed by a caller on behalf of a person, and the lease is what makes
+ * that expressible: it is how the operation knows which lease to exempt from
+ * §5.5.1's live-lease refusal, and which lease is entitled to end the request
+ * it made. Take the key away and neither question has an answer.
+ */
+function requestSignInHandler(scope, input) {
+    return decideRequestSignIn(scope, input);
+}
+function finishSignInHandler(scope, input) {
+    return decideFinishSignIn(scope, input);
+}
+/**
+ * The six tab-addressed handlers.
+ *
+ * **None of them takes settings**, for the reason `decideStatus` gives about
+ * itself: every duration they report comes off the lease's own row, because
+ * each of these renews the lease it names and a renewal has to extend by the
+ * duration the caller was already told about. A settings argument they did
+ * not use would invite exactly the re-read §6.3 forbids.
+ */
+function navigateHandler(scope, input) {
+    return decideNavigate(scope, input);
+}
+function actHandler(scope, input) {
+    return decideAct(scope, input);
+}
+function readHandler(scope, input) {
+    return decideRead(scope, input);
+}
+function evaluateHandler(scope, input) {
+    return decideEvaluate(scope, input);
+}
+function captureHandler(scope, input) {
+    return decideCapture(scope, input);
+}
+function tabReplaceHandler(scope, input) {
+    return decideTabReplace(scope, input);
+}
+/**
+ * Every arbitration operation this build has.
+ *
+ * **This registry is the set `arbitration.no_read_only_path` walks**, and the
+ * reason it is one object in one file rather than a call to a `register()`
+ * function scattered across modules: a check that has to *find* the
+ * registrations can only find the ones written the way it expects, and the
+ * first one written differently is invisible to it. A single object literal
+ * is enumerable statically and at run time, and the two enumerations can be
+ * asserted equal.
+ *
+ * **Every operation here writes, without exception**, which is the property
+ * the registry exists to keep true. `claim` inserts a row; `release` updates
+ * one; `status` renews, which is row #14's point — a keyed call extends the
+ * lease it names, so the operation that looks read-only is a writer twice
+ * over, once for its own renewal and once for the sweep the runner ran
+ * before it.
+ *
+ * **The six tab-addressed operations are writers on the same grounds**, and
+ * it is worth being explicit because they are the ones that look least like
+ * it: `navigate`, `act`, `read`, `evaluate` and `capture` each read a page
+ * and change nothing about it, yet each is keyed, so each renews, and each
+ * records what it did. The browser work they cause is not part of the
+ * transaction at all — it is handed back as `afterCommit` and run once the
+ * commit is done (§2.4b), so what is inside the transaction is only ever the
+ * renewal, the ownership check and the ledger row.
+ *
+ * **The empty-registry exemption in `scripts/check-arbitration.mjs` is
+ * retired by this row**, which is what it named as the condition for its own
+ * removal. Every rule that check enforces is now an assertion over a
+ * non-empty set.
+ */
+export const ARBITRATION_OPERATIONS = {
+    claim: {
+        kind: 'claim_requested',
+        summary: 'Ask for a lease over one tab: granted if capacity allows, queued at the back if not.',
+        handler: claimHandler,
+    },
+    status: {
+        kind: 'claim_renewed',
+        summary: 'Where this lease stands, and — like every keyed call — an extension of it.',
+        handler: statusHandler,
+    },
+    release: {
+        kind: 'claim_released',
+        summary: 'Give back whatever this lease holds: a tab, or a place in the queue.',
+        handler: releaseHandler,
+    },
+    navigate: {
+        kind: 'navigate',
+        summary: 'Point an owned tab at an address, having checked the scheme is one of the two.',
+        handler: navigateHandler,
+    },
+    act: {
+        kind: 'act',
+        summary: 'One interaction against an owned tab, from the thirteen the seam names.',
+        handler: actHandler,
+    },
+    read: {
+        kind: 'read',
+        summary: 'Collect artifacts from an owned tab; the page state is always among them.',
+        handler: readHandler,
+    },
+    evaluate: {
+        kind: 'evaluate',
+        summary: 'Run a bounded expression in an owned tab and dispose of what it returned.',
+        handler: evaluateHandler,
+    },
+    capture: {
+        kind: 'capture',
+        summary: 'Take an image of an owned tab, of the viewport or of the whole page.',
+        handler: captureHandler,
+    },
+    begin_sign_in: {
+        kind: 'browser_signin_began',
+        summary: 'Claim the signed-in browser for a person, refusing if any live lease holds a tab.',
+        handler: beginSignInHandler,
+    },
+    end_sign_in: {
+        kind: 'browser_signin_ended',
+        summary: 'Give the browser back after a person has signed in; queued callers kept their places.',
+        handler: endSignInHandler,
+    },
+    sign_in: {
+        kind: 'browser_signin_began',
+        summary: 'Ask a person to sign in on the tab this lease already holds, exempting only that lease.',
+        handler: requestSignInHandler,
+    },
+    sign_in_done: {
+        kind: 'browser_signin_ended',
+        summary: 'The person confirmed: give the browser back, and keep the lease and its tab.',
+        handler: finishSignInHandler,
+    },
+    tab_replace: {
+        kind: 'tab_closing',
+        summary: 'Give up this lease’s tab and take a fresh one, without the count dipping.',
+        handler: tabReplaceHandler,
+    },
+};
+/** The registered names as data, for the registry test and the ledger. */
+export const ARBITRATION_NAMES = Object.keys(ARBITRATION_OPERATIONS);
+/**
+ * Expire every lapsed claim and every lapsed queue entry, across the whole
+ * store, and collect the tabs they held.
+ *
+ * **This is what makes even a question a write** (§1.0a, §2.4). It is not
+ * conditional, not skippable and not scoped to the caller, and those three
+ * properties are the standing invariant rather than three separate choices.
+ *
+ * ── Why the lapse time is computed rather than stamped ──────────────────
+ *
+ * §2.4a: `claims.expired_at` is when the lease *lapsed*, which is not when
+ * the sweep noticed. A lease whose caller stopped talking lapsed at its own
+ * expiry, whether the next caller arrived one second later or forty minutes
+ * later. Stamping the sweep's own moment produces a record in which leases
+ * expire in clusters at instants when nothing happened to them — an artifact
+ * of the observer, and a bad kind, because it is a strong, clean, entirely
+ * fictitious pattern.
+ *
+ * So `expired_at` is set to the row's own `expires_at`, which is the last
+ * renewal plus the duration that was in force. The ledger row carries the
+ * sweep's moment, and says so by being a ledger row.
+ */
+/**
+ * Give back a browser whose **requested** sign-in nobody answered.
+ *
+ * ── Why this is a second sweep and not a branch inside the first ────────
+ *
+ * The claim sweep reconciles leases: it reads `claims`, expires the lapsed
+ * ones and collects their tabs. This reconciles a **browser**, on a different
+ * table, against a different column, producing a different ledger kind. Folded
+ * into `sweep` it would make that function's contract two things — which is
+ * how its early return for `lapsed.length === 0` would have silently skipped
+ * this entirely, since a browser can be holding a stale sign-in on a store
+ * where no lease lapsed at all.
+ *
+ * ── Why it belongs in the transaction rather than on a timer ────────────
+ *
+ * §2.4's whole model: **capacity comes back lazily, globally, on every call.**
+ * Nothing here runs a scheduler, and there is no process to run one on — the
+ * service is spawned by its caller and exits with it (§1.0a). So a deadline is
+ * enforced the same way an expiry is: the next caller reconciles it, inside
+ * the transaction that has already opened, before any handler reads the row.
+ * That is what lets a handler read `state` directly and be right.
+ *
+ * ── What it will not do ─────────────────────────────────────────────────
+ *
+ * **It never touches a sign-in held by a process.** `signin_deadline` is null
+ * for every `broker login`, which is precisely the sign-in §5.5.1 says must
+ * not expire — *"a person takes as long as they take, and a timeout would end
+ * a sign-in that was going fine."* The column is the discriminator, and a
+ * sweep written against `state = 'signing-in'` alone would have ended exactly
+ * the sign-ins that rule protects.
+ *
+ * **And it never touches the asking lease.** A request that lapses gives the
+ * browser back and leaves the caller holding its tab, still live, still
+ * renewing. It has lost the request, not the work — the caller finds out by
+ * being refused the next time it tries to finish, and can ask again.
+ */
+function lapseUnansweredSignIns(db, now, adapter) {
+    const lapsed = db
+        .prepare(`UPDATE browsers
+          SET state = CASE WHEN pid IS NULL THEN 'stopped' ELSE 'running' END,
+              signin_deadline = NULL,
+              signin_claim_id = NULL,
+              updated_at = @now
+        WHERE state = 'signing-in'
+          -- **Not null, which is the whole guard.** A sign-in held by a
+          -- process has no deadline, and must not acquire one here.
+          AND signin_deadline IS NOT NULL
+          AND signin_deadline <= @now
+    RETURNING id AS browserId, state AS nextState, signin_claim_id AS claimId`)
+        .all({ now });
+    for (const row of lapsed) {
+        // One row per decision (§1.6), and it says it was a lapse rather than a
+        // person finishing — a run of these reads as requests nobody answered,
+        // which is exactly the pattern somebody tuning the deadline would want.
+        append(db, {
+            kind: 'browser_signin_ended',
+            outcome: 'allow',
+            adapter,
+            browserId: row.browserId,
+            detail: {
+                lapsed: true,
+                state: row.nextState,
+                claimId: row.claimId,
+                reason: 'the sign-in this caller asked for was not answered before its deadline',
+            },
+        });
+    }
+}
+function sweep(db) {
+    const sweptAt = db.prepare("SELECT strftime('%Y-%m-%dT%H:%M:%fZ', 'now') AS now").get();
+    const now = sweptAt.now;
+    // Read before writing, inside the transaction. Which tabs the lapsed claims
+    // held cannot be read after the update on the claims alone — the claims are
+    // still there — but reading first keeps the two statements over one set of
+    // rows rather than over whatever the second statement re-derives.
+    const lapsed = db
+        .prepare(`SELECT id FROM claims
+       WHERE state IN ('queued', 'active') AND expires_at <= @now
+       ORDER BY id`)
+        .all({ now });
+    if (lapsed.length === 0) {
+        return { expiredClaimIds: [], orphanedTabs: [], sweptAt: now };
+    }
+    const placeholders = lapsed.map(() => '?').join(', ');
+    const ids = lapsed.map((row) => row.id);
+    const orphanedTabs = db
+        .prepare(`SELECT id AS tabId, claim_id AS claimId, browser_id AS browserId
+       FROM tabs
+       WHERE claim_id IN (${placeholders}) AND state IN ('opening', 'open')
+       ORDER BY id`)
+        .all(...ids);
+    // Positional parameters throughout, not a mix. The driver refuses a
+    // statement that carries both spellings, and the list of identifiers has to
+    // be positional because its length varies per call.
+    db.prepare(`UPDATE claims
+     SET state = 'expired',
+         -- Section 2.4a: when it lapsed, not when this noticed.
+         expired_at = expires_at,
+         ended_at = expires_at,
+         updated_at = ?
+     WHERE id IN (${placeholders})`).run(now, ...ids);
+    // The tab rows follow their claims, and which state they follow into
+    // depends on whether there is anything to ask a browser about.
+    //
+    // §1.4 defines the two precisely, and the definition decides this rather
+    // than a preference: `closing` is "the honest representation of *the tool
+    // was asked and has not answered*", and it is what stops **a page that may
+    // still exist** being counted as free.
+    //
+    // - **A tab with a driver name was opened.** A page exists, the tool will be
+    //   asked to close it after the commit, and until it answers `closing` is
+    //   the only honest thing to say.
+    // - **A tab with no driver name was never opened.** Nothing was asked,
+    //   because there is nothing to ask about — no page exists and none ever
+    //   did. Calling that `closing` would assert an outstanding round trip that
+    //   is not outstanding, and would leave the row waiting forever for an
+    //   answer nobody is coming to give.
+    //
+    // So the second goes straight to `closed`, which is also what the schema
+    // requires: `CHECK ((state = 'opening') = (driver_tab_id IS NULL))` permits
+    // a null driver name only on `opening`, and a `closed` row with one is
+    // exactly as consistent as an `open` row with one. **The constraint is
+    // right and it caught a genuine error**, rather than being an obstacle to
+    // route around — a tab moved to `closing` with nothing to close is a claim
+    // about the world that is false.
+    // What comes back is the subset a browser still owes an answer about. The
+    // rest are already `closed`, so scheduling a close for them would ask the
+    // driver to shut a page that never existed.
+    const pendingCloses = updateSweptTabs(db, orphanedTabs, now);
+    return { expiredClaimIds: ids, orphanedTabs: pendingCloses, sweptAt: now };
+}
+/**
+ * Move tabs out of a lease that has ended, into the state that is true of
+ * each.
+ *
+ * **Exported because release needs exactly this rule** (§3.4) and two writers
+ * spelling it separately is how they come to disagree. The defect this
+ * function exists to make impossible was precisely that: the sweep and
+ * release each moved every tab to `closing`, and every tab this build creates
+ * has no driver name, so both violated the schema's own check on the ordinary
+ * path.
+ *
+ * Returns the tabs that still need a browser round trip — which is **not**
+ * every tab handed in. A tab that never opened has nothing to close, so
+ * scheduling one would be asking the driver to close a page that does not
+ * exist.
+ */
+export function updateSweptTabs(db, tabs, now) {
+    if (tabs.length === 0) {
+        return [];
+    }
+    const ids = tabs.map((tab) => tab.tabId);
+    const placeholders = ids.map(() => '?').join(', ');
+    // Opened, so a page exists and the tool has to be asked. `closing` until it
+    // answers.
+    db.prepare(`UPDATE tabs
+        SET state = 'closing', updated_at = ?
+      WHERE id IN (${placeholders})
+        AND state IN ('opening', 'open')
+        AND driver_tab_id IS NOT NULL`).run(now, ...ids);
+    // Never opened, so there is nothing to ask and nothing to wait for. The
+    // close time is this moment because the tab is over now, not when some
+    // round trip that will never happen would have returned.
+    db.prepare(`UPDATE tabs
+        SET state = 'closed', closed_at = ?, updated_at = ?
+      WHERE id IN (${placeholders})
+        AND state = 'opening'
+        AND driver_tab_id IS NULL`).run(now, now, ...ids);
+    // Only the ones a browser still owes an answer about.
+    const pending = db
+        .prepare(`SELECT id AS tabId, claim_id AS claimId, browser_id AS browserId
+         FROM tabs
+        WHERE id IN (${placeholders}) AND state = 'closing'
+        ORDER BY id`)
+        .all(...ids);
+    return pending;
+}
+/**
+ * Record what the sweep did, on the call that performed it.
+ *
+ * §1.6's `internal` adapter, and the reason it exists: "that last one is not a
+ * background job — with no long-lived process there is nothing running in the
+ * background — so a sweep is attributed to the call that performed it". The
+ * adapter recorded here is therefore the **caller's**, not `internal`; the
+ * kind is what says this was a sweep.
+ *
+ * **A sweep that found nothing writes no row.** The ledger records decisions,
+ * and finding nothing to expire is not one — a row per call on a quiet
+ * installation would be the ledger's largest category and would carry no
+ * information. What is recorded is each claim that actually expired, which is
+ * a decision about that lease.
+ */
+function recordSweep(scope, swept) {
+    for (const claimId of swept.expiredClaimIds) {
+        append(scope.db, {
+            kind: 'claim_expired',
+            outcome: 'allow',
+            adapter: scope.adapter,
+            claimId,
+            detail: {
+                sweptAt: swept.sweptAt,
+                orphanedTabs: swept.orphanedTabs.filter((tab) => tab.claimId === claimId).length,
+            },
+        });
+    }
+}
+/**
+ * Dispatch one arbitration operation: sweep, answer, commit, then close.
+ *
+ * **The only way an arbitration operation is invoked.** Everything in the
+ * shape that must not vary lives here rather than in the operations — the
+ * transaction, the sweep, the ledger row for what the sweep did, and the
+ * ordering of all three — so an operation cannot get the order wrong by
+ * writing it differently. What an operation supplies is step 2 alone.
+ *
+ * The transaction is opened by `immediate` from `transaction.ts` and by
+ * nothing else in this module. There is no second path, no fast path and no
+ * option that skips it, which is the whole of what
+ * `arbitration.immediate_transaction` can be enforced against on this side —
+ * the check itself explains what it can and cannot prove.
+ */
+export async function runArbitration(options) {
+    // Read as an untyped record so an unregistered name is a lookup returning
+    // nothing rather than a type error at this site: the refusal below is what
+    // handles it, and it has to be reachable at run time for a caller on a
+    // different build. The per-operation input types are preserved on the
+    // registry itself, which is what makes an internal call site type-safe.
+    const operation = ARBITRATION_OPERATIONS[options.name];
+    if (operation === undefined) {
+        // Refused before the transaction opens, deliberately. An unregistered
+        // name is not a decision about capacity and there is nothing to sweep on
+        // behalf of — opening a transaction to refuse it would serialise every
+        // caller on the machine behind a mistyped operation name.
+        throw new CallRefusal('unknown_operation', `There is no arbitration operation named ${JSON.stringify(options.name)}. This build registers ${ARBITRATION_NAMES.length === 0 ? 'none yet' : ARBITRATION_NAMES.join(', ')}.`, { detail: { requested: options.name, registered: ARBITRATION_NAMES } });
+    }
+    // Refusals collected inside the transaction and written after it rolls
+    // back. A refusal is a decision (§1.6) and it is the one thing about a
+    // refused call that was not undone, so it must outlive the rollback its own
+    // throw causes.
+    const refusals = [];
+    try {
+        return await options.store.immediate(async ({ db }) => {
+            // Step 1, always, before anything the operation does. Unconditional is
+            // the point: this is what makes the transaction a writer even when the
+            // operation only asks a question (section 1.0a).
+            const swept = sweep(db);
+            // And the second reconciliation, for the same reason and in the same
+            // place: a sign-in a caller asked for and nobody answered has lapsed,
+            // and a browser still reading `signing-in` because of it would refuse
+            // every caller over a person who is not coming. See its own header for
+            // why this is separate from the claim sweep rather than folded into it.
+            lapseUnansweredSignIns(db, swept.sweptAt, options.adapter);
+            // What the operation asks to have closed, collected inside and acted on
+            // outside. A list rather than a call: nothing here can reach a browser,
+            // so a handler cannot turn a schedule into a round trip.
+            const scheduled = [];
+            const scope = {
+                db,
+                swept,
+                adapter: options.adapter,
+                closeAfterCommit: (tab) => {
+                    scheduled.push(tab);
+                },
+                recordRefusal: (event) => {
+                    refusals.push(event);
+                },
+            };
+            recordSweep(scope, swept);
+            // Step 2: the operation answers from the reconciled state.
+            const outcome = (await operation.handler(scope, options.input));
+            // Step 3 is handed to the transaction helper, which runs it after the
+            // commit and outside every transaction. The sweep's own orphaned tabs
+            // are scheduled here rather than by the operation, because an operation
+            // that had to remember to close them is an operation that can forget —
+            // and the sweep is not its work in the first place.
+            //
+            // The sweep's closes go first: they are reclamation of capacity that
+            // has already come back, and an operation's own after-commit work may
+            // well be opening the tab that capacity is for.
+            const closeTab = options.closeTab;
+            const closes = closeTab === undefined
+                ? []
+                : [...swept.orphanedTabs, ...scheduled].map((tab) => () => closeTab(tab));
+            return {
+                value: outcome.value,
+                afterCommit: [...closes, ...(outcome.afterCommit ?? [])],
+            };
+        });
+    }
+    finally {
+        // **After the transaction, whichever way it went.** On the ordinary path
+        // this list is empty and the block does nothing. On a refusal the
+        // transaction has rolled back, so these rows are written on their own —
+        // which is what makes a refused decision recorded rather than erased by
+        // the very refusal it describes (§1.6).
+        //
+        // `finally` rather than a catch, because a guard is free to record a
+        // refusal and then let the call succeed anyway — the nudge is exactly
+        // that shape — and a catch would drop the row on the path that did not
+        // throw.
+        writeRefusals(options.store, refusals);
+    }
+}
+/**
+ * Write the collected refusal rows, outside the transaction that produced
+ * them.
+ *
+ * **Failure here is swallowed, deliberately, and this is a real trade rather
+ * than an oversight.** The caller is already receiving a refusal that names
+ * the rule and says what to do next; turning a failure to *record* that
+ * refusal into a second, different error would replace an actionable answer
+ * with an unactionable one, and the caller would be left unable to tell which
+ * of the two actually decided its call.
+ *
+ * **What that costs is a refusal missing from the ledger** under conditions
+ * that also lose ordinary writes. The alternative costs the caller its
+ * answer, which is worse.
+ */
+function writeRefusals(store, refusals) {
+    if (refusals.length === 0) {
+        return;
+    }
+    try {
+        for (const refusal of refusals) {
+            append(store.db, refusal);
+        }
+    }
+    catch {
+        // See above: the caller's refusal is the more useful of the two answers.
+    }
+}

package/dist/src/service/artifacts.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs/promises';
+import { findComparison } from "./comparison-store.js";
+/**
+ * The one sentence a caller gets for anything it is not entitled to see.
+ *
+ * §1.9: artifacts belonging to another lease are refused "with the same
+ * non-disclosing wording as an unknown tab (§7.1) **so probing cannot discover
+ * another lease's files**". §7.1 makes the same collapse for `tab.owned` and
+ * `tab.open` — two rules, one message — and the reason transfers exactly: a
+ * caller able to tell "not yours" from "does not exist" is a caller able to
+ * enumerate what exists.
+ *
+ * **So this string is used for both, and that is load-bearing rather than
+ * lazy.** A test asserts the two are byte-identical.
+ */
+export const ARTIFACT_NOT_FOUND_MESSAGE = 'No artifact with that identifier belongs to this lease.';
+function notFound() {
+    return { served: false, refusal: { reason: 'not_found', message: ARTIFACT_NOT_FOUND_MESSAGE } };
+}
+/**
+ * Resolve a request to the stored path it names, checking ownership.
+ *
+ * Split out from the read so the ownership check is a single expression per
+ * variant and visibly precedes every filesystem call — the `browser_read`
+ * shape §7.1 calls "the rejection asserts the physical side-effect": a path
+ * that is never resolved cannot be read by accident further down.
+ */
+function resolveRequest(options) {
+    const { db, claimId, request } = options;
+    if (request.kind === 'capture') {
+        const capture = options.captures.find(request.captureId);
+        if (capture === null || capture.claimId !== claimId) {
+            return null;
+        }
+        return capture.path;
+    }
+    const comparison = findComparison(db, request.comparisonId);
+    if (comparison === null || comparison.claimId !== claimId) {
+        return null;
+    }
+    if (request.kind === 'overlay') {
+        return comparison.overlayPath;
+    }
+    const region = comparison.regions[request.index];
+    if (region === undefined) {
+        return null;
+    }
+    return request.side === 'before' ? region.beforePath : region.afterPath;
+}
+/**
+ * Serve one artifact's bytes.
+ *
+ * Returns an outcome rather than throwing, because "you named something that
+ * is not yours or is not there" is an ordinary answer on this surface and a
+ * caller has to be able to branch on it without catching.
+ */
+export async function fetchArtifact(options) {
+    const stored = resolveRequest(options);
+    if (stored === null) {
+        return notFound();
+    }
+    // The one join of a stored path to a location in this file, and it goes
+    // through the artifact store so the containment assertion cannot be skipped
+    // and cannot be a second, weaker copy of itself. A throw from here is a
+    // constructed path that is wrong — our bug, not a caller's — and it is
+    // deliberately not caught.
+    const absolute = options.artifacts.resolve(stored);
+    try {
+        const bytes = await fs.readFile(absolute);
+        return { served: true, artifact: { bytes: new Uint8Array(bytes), path: stored } };
+    }
+    catch {
+        // A row exists and its file does not. §6.2 says nothing sweeps an image,
+        // so this is a tree somebody deleted by hand rather than an expiry — and
+        // it is worth a different sentence from "not found", because the caller
+        // named something real and there is nothing it can do differently.
+        return {
+            served: false,
+            refusal: {
+                reason: 'unreadable',
+                message: `The artifact at ${stored} is recorded but could not be read from the artifact root.`,
+            },
+        };
+    }
+}