browser-broker 0.1.0

package/dist/src/operations/addresses.js

@@ -0,0 +1,175 @@
+/**
+ * Where each leased tab actually is, asked of the browsers at generation time
+ * (`MILESTONES.md` #70, `SCHEMA.md` §4.2a).
+ *
+ * ── Why this is a live read and why no column caches it ─────────────────
+ *
+ * §1.4: **there is no column recording where a tab is**, and its absence is
+ * "the single largest privacy improvement in this design". A table of
+ * addresses kept over months is a browsing history — with a retention setting
+ * to get wrong and a clear-history command to build. §4.2a completes the
+ * argument from the other side: the process generating this document **is
+ * attached to both browsers**, so the one moment anybody wants the answer is
+ * a moment when the source is right there. Asking is strictly better than
+ * storing, and it leaves nothing behind.
+ *
+ * **Do not reintroduce a stored address column.** Nothing in this module
+ * writes, and there is no store handle in scope to write with.
+ *
+ * ── The two rules, and neither is optional ──────────────────────────────
+ *
+ * §4.2a states them as requirements rather than suggestions:
+ *
+ * 1. **Every read carries a timeout.** A browser can hang — it accepts the
+ *    request and never answers (§2.4b) — and a generator that inherits that
+ *    hang produces nothing at all, which is worse than an incomplete
+ *    document. The timeout is **per tab**, so one wedged page costs one entry
+ *    rather than the whole run.
+ * 2. **A browser that does not answer renders as an explicit word.** Not
+ *    blank, not omitted, not a placeholder address. "A missing address and an
+ *    unanswered one are different facts, and the second is the one that
+ *    indicates something wrong."
+ *
+ * The timeout is **not defaultable to absent**: {@link readAddresses} takes
+ * it as a required field on a required options object, so a caller cannot
+ * omit it and get an unbounded read. That is as far as a type can carry the
+ * rule; what it cannot prevent is somebody passing a number so large it is a
+ * timeout in name only, and saying so is better than implying otherwise.
+ *
+ * ── This is outside every transaction, and that is structural here ──────
+ *
+ * §2.4b: browser work never happens inside the arbitration transaction. This
+ * module is reachable only from the document generator, which runs it after
+ * the status read has returned and closed. Nothing in this file imports a
+ * store handle or a transaction, so there is no transaction in scope to be
+ * inside of.
+ */
+/**
+ * The word an unanswered read renders as (§4.2a).
+ *
+ * A constant rather than a literal at each use, so the document, the tests
+ * and any later reader all name the same string — and so the mutation that
+ * removes it has exactly one place to be removed from and is caught.
+ */
+export const UNREACHABLE = 'unreachable';
+/** The default timer, wrapped so the injected one and the real one are one shape. */
+function realTimer(fn, ms) {
+    const handle = setTimeout(fn, ms);
+    return {
+        cancel: () => {
+            clearTimeout(handle);
+        },
+    };
+}
+/**
+ * Race one read against the bound.
+ *
+ * `Promise.race` rather than an abort signal, because the seam's operations
+ * do not take one and inventing a parallel cancellation protocol here would
+ * be a change to somebody else's interface made from the outside. **The
+ * consequence is stated rather than hidden:** the underlying read is not
+ * cancelled, it is abandoned. A hung browser keeps whatever it was doing;
+ * this process stops waiting for it, which is the property the rule actually
+ * asks for — the generator must not inherit the hang. The abandoned promise's
+ * eventual rejection is swallowed so it cannot surface as an unhandled
+ * rejection long after the document was written.
+ */
+async function withTimeout(work, timeoutMs, setTimer) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimer(() => {
+            resolve({ ok: false, reason: `no answer within ${String(timeoutMs)}ms` });
+        }, timeoutMs);
+    });
+    const answered = work.then((value) => ({ ok: true, value }), (error) => ({
+        ok: false,
+        reason: error instanceof Error ? error.message : 'the read failed',
+    }));
+    try {
+        return await Promise.race([answered, timeout]);
+    }
+    finally {
+        timer?.cancel();
+    }
+}
+/**
+ * Read every requested tab's address, each under its own timeout.
+ *
+ * **Sequential rather than concurrent**, and the reason is the bound: run in
+ * parallel, one wedged tab still costs only its own timeout, but so does a
+ * browser that is merely slow for all of them at once, and the document's
+ * total generation time stops being predictable from the number of tabs. At a
+ * tab budget of fifteen (§6.2) the worst case is fifteen timeouts, which is a
+ * bounded and explainable wait. If that ever becomes the wrong trade, it is a
+ * change here and nowhere else.
+ *
+ * **Never throws.** Every failure becomes an `unreachable` entry, because the
+ * one outcome §4.2a rules out is producing nothing at all.
+ */
+export async function readAddresses(source, requests, options) {
+    const setTimer = options.setTimer ?? realTimer;
+    const addresses = new Map();
+    for (const request of requests) {
+        const result = await withTimeout(
+        // Invoked inside a promise rather than called directly, because a
+        // source that throws **synchronously** — before any promise exists —
+        // would otherwise escape this loop entirely and the run would produce
+        // no document at all. That is the one outcome §4.2a rules out, and a
+        // synchronous throw is an ordinary way for a driver to report a handle
+        // it does not recognise.
+        (async () => source.addressOf(request.handle))(), options.timeoutMs, setTimer);
+        addresses.set(request.tabId, result.ok
+            ? { kind: 'address', url: result.value.url, title: result.value.title }
+            : { kind: 'unreachable', reason: result.reason });
+    }
+    return addresses;
+}
+/**
+ * What the document prints for one tab.
+ *
+ * The single place the three outcomes become text, so the rule "never blank,
+ * never omitted, never a placeholder" is enforced at one point rather than at
+ * each use. A tab with no entry at all — which is what happens when the
+ * generator could not reach a browser to ask in the first place — renders as
+ * `unreachable` too: an address that was never obtained is not an address,
+ * and the absence of an entry is exactly the "omitted" case §4.2a forbids.
+ */
+export function renderAddress(address) {
+    if (address === undefined) {
+        return UNREACHABLE;
+    }
+    switch (address.kind) {
+        case 'address':
+            return address.url;
+        case 'unreachable':
+            return UNREACHABLE;
+        case 'none':
+            // A lease with no tab. Not an address and not a failure — the word is
+            // about the lease's state, and the document's queue section already
+            // says why there is no page.
+            return 'no tab';
+    }
+}
+/**
+ * Turn a browser session into an {@link AddressSource}.
+ *
+ * Kept here rather than in the generator so that the one expression evaluated
+ * against a page in order to build this document lives beside the rule that
+ * bounds it. It reads two properties and nothing else.
+ */
+export function addressSourceFromSession(session) {
+    return {
+        addressOf: async (tab) => {
+            const result = await session.evaluate(tab, '({ url: document.location.href, title: document.title })');
+            const value = result.value;
+            if (value === null || typeof value !== 'object') {
+                throw new Error('the page did not report an address');
+            }
+            const record = value;
+            return {
+                url: typeof record.url === 'string' ? record.url : '',
+                title: typeof record.title === 'string' ? record.title : '',
+            };
+        },
+    };
+}

package/dist/src/operations/derive.js

@@ -0,0 +1,109 @@
+/**
+ * The expiry derivation, on its own, so that everything reporting state
+ * applies the same one.
+ *
+ * ── Why this is a module and not three lines inlined at each reader ──────
+ *
+ * `SCHEMA.md` §2.4 states the standing rule this whole file exists to serve:
+ *
+ * > **Stored state is provisional, derived state is the truth.**
+ *
+ * Nothing expires on a timer, because there is nothing running to hold one
+ * (§1.0a). A row saying `active` whose expiry has elapsed is **not** an
+ * active lease — it is a lease that lapsed and has not been swept yet, and
+ * **the difference is invisible in the row.** So a reader that renders
+ * `claims.state` reports leases that do not exist, and does it *most* on the
+ * busiest installation, where the gap between lapsing and being noticed is
+ * exactly the interval somebody is looking at the document.
+ *
+ * §2.4 names this as "the rule most likely to be broken by a well-meaning
+ * addition, because reading a column is the obvious thing to do and it is
+ * wrong here", and §4.5 binds the generated operations document to it
+ * explicitly: it "is a reader like any other".
+ *
+ * Keeping the derivation in one named function is what makes that rule
+ * **checkable** rather than merely written down: a reader either calls
+ * {@link deriveClaimState} or it does not, and a test can delete this
+ * function's comparison and watch a rendering test fail.
+ *
+ * ── What this does not do, said plainly ─────────────────────────────────
+ *
+ * **It does not sweep, and it writes nothing.** Sweeping is the arbitration
+ * transaction's job (§2.4) and belongs to the service layer. This is the
+ * read-side half: given a row and an instant, say what is *true* about that
+ * row at that instant. The two must agree, and they agree because they apply
+ * the same comparison — but a document generator must never be the thing that
+ * expires somebody's lease as a side effect of being looked at.
+ *
+ * **It cannot stop a reader going around it.** Nothing in a type signature
+ * prevents a module selecting `state` and printing it. What this buys is that
+ * the correct path is one import away and named for what it does, and that
+ * the mutation tests over the document renderer have a single line to kill.
+ */
+/**
+ * Comparing two of the store's timestamps.
+ *
+ * `SCHEMA.md` §1.1: time is "stored in a single fixed textual form that sorts
+ * in chronological order, so a comparison is a comparison and needs no
+ * conversion". So this is a string comparison **on purpose** — parsing to a
+ * date here would introduce a second interpretation of the same column, and a
+ * time zone for it to be wrong in.
+ */
+function hasElapsed(expiresAt, at) {
+    return expiresAt <= at;
+}
+/**
+ * What a lease's state actually is at instant `at`.
+ *
+ * **A final state is final** (§2.1): released, expired and revoked are
+ * outcomes that already happened, and no passage of time changes one. Only
+ * the two live states — `queued` and `active` — can have lapsed without
+ * anybody noticing.
+ *
+ * The boundary is **inclusive**: a lease whose expiry is exactly now has
+ * elapsed. That matches the sweep, which selects the live rows at or past
+ * their expiry, and the two must not disagree by one instant — a document
+ * saying `active` for a lease the very next call will expire is the failure
+ * this module exists to prevent, in miniature.
+ */
+export function deriveClaimState(claim, at) {
+    if (claim.state !== 'queued' && claim.state !== 'active') {
+        return claim.state;
+    }
+    return hasElapsed(claim.expires_at, at) ? 'expired' : claim.state;
+}
+/**
+ * Whether a lease is live at instant `at` — holding a tab, or holding a
+ * place in the queue.
+ *
+ * This is the predicate the budget count is over, and it is derived for the
+ * same reason everything else here is: counting rows whose stored state is
+ * live would count leases that have lapsed, and would report an installation
+ * as fuller than it is.
+ */
+export function isLive(claim, at) {
+    const derived = deriveClaimState(claim, at);
+    return derived === 'queued' || derived === 'active';
+}
+/**
+ * Whole seconds between two of the store's timestamps, `later - earlier`.
+ *
+ * Negative when `later` is before `earlier`, which is not guarded against:
+ * the callers here are reporting how long something has been waiting or how
+ * long until it lapses, and a negative number is the honest answer to "how
+ * long until an expiry that has already passed". Clamping it would hide
+ * exactly the case §2.4 is about.
+ *
+ * Parsing is safe here in a way it is not in {@link hasElapsed}, because the
+ * question is arithmetic rather than ordering — but the values still come
+ * from one clock (the database's own, §1.1), so the subtraction is between
+ * two readings of the same clock and not across two machines'.
+ */
+export function secondsBetween(earlier, later) {
+    const from = Date.parse(earlier);
+    const to = Date.parse(later);
+    if (Number.isNaN(from) || Number.isNaN(to)) {
+        return 0;
+    }
+    return Math.round((to - from) / 1000);
+}

package/dist/src/operations/ledger.js

@@ -0,0 +1,194 @@
+/**
+ * A view of the ledger (`MILESTONES.md` #47, `SCHEMA.md` §1.6).
+ *
+ * **One query.** §1.6: "The ledger is one stream with a cursor, so a page
+ * over it is a page over one query" — and the table's shape is what keeps it
+ * that way. A column per kind would be a wide, mostly-empty table; a table
+ * per kind would turn every read into a fifteen-way union. So a slice is a
+ * `WHERE` over one table, and this module's whole job is to build that
+ * `WHERE` without ever building it out of caller-supplied SQL.
+ *
+ * ── The cursor is not invented here ─────────────────────────────────────
+ *
+ * §1.6: `events.id` is "**also** the 'everything since here' cursor for
+ * anything reading a slice of the ledger". It counts upward, so a reader that
+ * remembers the highest id it has seen can ask for everything after it, and
+ * the answer is stable regardless of what has been written in between. There
+ * is no separate cursor table, no opaque token to encode, and no offset —
+ * an offset re-reads rows when the earlier ones have grown, which is the
+ * failure a counter key exists to avoid.
+ *
+ * ── Read-only, and it does not sweep ────────────────────────────────────
+ *
+ * §5.2 records that "any command that goes through arbitration performs the
+ * lazy sweep", which is correct and surprising the first time a listing
+ * command closes somebody's tabs. **Reading the ledger is not an arbitration
+ * path**: it decides nothing, grants nothing and refuses nothing, so it
+ * neither needs the reconciled state nor is entitled to expire anybody's
+ * lease. It is a plain read over history — and history is the one thing in
+ * this store that is already settled.
+ *
+ * That is a narrower claim than it may look, and it is worth stating: the
+ * *ledger* needs no derivation because every row in it records a decision
+ * that was made at a moment that has passed. The **claims** do need one, and
+ * that is `derive.ts`'s job. Do not read this file as a precedent for
+ * reading `claims.state` directly.
+ */
+/** The event kinds, exactly as the schema's check constraint spells them (§1.6). */
+export const EVENT_KINDS = [
+    'claim_requested',
+    'claim_granted',
+    'claim_queued',
+    'claim_promoted',
+    'claim_renewed',
+    'claim_released',
+    'claim_expired',
+    'claim_revoked',
+    'tab_opening',
+    'tab_open_failed',
+    'tab_closing',
+    'navigate',
+    'act',
+    'read',
+    'evaluate',
+    'capture',
+    'compare',
+    'browser_launched',
+    'browser_adopted',
+    'browser_exited',
+    'launch_race_lost',
+    'sweep',
+];
+/** `allow` or `deny`, separate from the kind (§1.6). */
+export const EVENT_OUTCOMES = ['allow', 'deny'];
+/** The default page. Small enough to read, large enough to be a page. */
+export const DEFAULT_LEDGER_LIMIT = 20;
+/**
+ * The most rows one call will return.
+ *
+ * A bound rather than an unbounded read because the ledger is kept forever by
+ * default (§6.2) and one of its two callers is assembling a self-contained
+ * HTML file — a document that inlined a million rows would be unopenable, and
+ * the failure would arrive long after the decision that caused it.
+ */
+export const MAXIMUM_LEDGER_LIMIT = 500;
+/**
+ * Build the `WHERE` clause.
+ *
+ * **Every caller value is a bound parameter and none is interpolated.** The
+ * only strings that reach the SQL text are column names written in this file.
+ * That is not a general-purpose defence so much as a structural one: there is
+ * no code path here that concatenates a caller's string into a statement, so
+ * there is nothing to review for whether a particular value was escaped.
+ */
+function buildConditions(query) {
+    const clauses = [];
+    const parameters = [];
+    const kinds = query.kinds?.filter((kind) => kind !== '') ?? [];
+    if (kinds.length > 0) {
+        clauses.push(`kind IN (${kinds.map(() => '?').join(', ')})`);
+        parameters.push(...kinds);
+    }
+    if (query.outcome !== undefined) {
+        clauses.push('outcome = ?');
+        parameters.push(query.outcome);
+    }
+    if (query.guard !== undefined) {
+        clauses.push('guard = ?');
+        parameters.push(query.guard);
+    }
+    if (query.sessionId !== undefined) {
+        clauses.push('session_id = ?');
+        parameters.push(query.sessionId);
+    }
+    if (query.claimId !== undefined) {
+        clauses.push('claim_id = ?');
+        parameters.push(query.claimId);
+    }
+    if (query.since !== undefined) {
+        clauses.push('id > ?');
+        parameters.push(query.since);
+    }
+    if (query.before !== undefined) {
+        clauses.push('id < ?');
+        parameters.push(query.before);
+    }
+    return {
+        sql: clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`,
+        parameters,
+    };
+}
+function toEntry(row) {
+    return {
+        id: row.id,
+        at: row.at,
+        kind: row.kind,
+        outcome: row.outcome,
+        guard: row.guard,
+        claimId: row.claim_id,
+        tabId: row.tab_id,
+        sessionId: row.session_id,
+        adapter: row.adapter,
+        browserId: row.browser_id,
+        detail: row.detail,
+    };
+}
+/**
+ * Clamp the page size.
+ *
+ * A limit below one is a caller asking for nothing, which is almost always a
+ * mistake in arithmetic rather than an intention, so it becomes the default
+ * rather than an empty page that looks like an empty ledger. Above the
+ * maximum it is capped rather than refused: a slice is a convenience read and
+ * failing a report over a page size would be a poor trade.
+ */
+export function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit) || limit < 1) {
+        return DEFAULT_LEDGER_LIMIT;
+    }
+    return Math.min(Math.floor(limit), MAXIMUM_LEDGER_LIMIT);
+}
+/**
+ * Read a slice of the ledger.
+ *
+ * Two statements rather than one, and the second is the count. That is a
+ * deliberate departure from "one query" in the narrow sense and not in the
+ * sense §1.6 means it: the *slice* is one query over one table with no joins
+ * and no union, which is the property the table's shape was designed to buy.
+ * The count answers "how many matched" — which a page of twenty cannot say
+ * about a filter over a ledger kept forever — and it runs over the same
+ * predicate and the same indexes.
+ */
+export function readLedger(db, query = {}) {
+    const conditions = buildConditions(query);
+    const limit = clampLimit(query.limit);
+    const direction = query.order === 'oldest' ? 'ASC' : 'DESC';
+    const rows = db
+        .prepare(`SELECT id, at, kind, outcome, guard, claim_id, tab_id, session_id, adapter, browser_id, detail
+       FROM events${conditions.sql}
+       ORDER BY id ${direction}
+       LIMIT ?`)
+        .all(...conditions.parameters, limit);
+    const counted = db
+        .prepare(`SELECT COUNT(*) AS total FROM events${conditions.sql}`)
+        .get(...conditions.parameters);
+    const entries = rows.map(toEntry);
+    const cursor = entries.reduce((highest, entry) => (highest === null || entry.id > highest ? entry.id : highest), null);
+    return { entries, cursor, total: counted?.total ?? 0 };
+}
+/**
+ * How often each rule has refused something.
+ *
+ * §1.6: "the question that *is* asked — 'has this rule ever fired' — is
+ * answered by the refusals", and the partial index on `guard` exists for
+ * exactly this read. Denials are rare, so the index is small and this is
+ * cheap; that is why the ledger records allows and denials alike rather than
+ * only the interesting half.
+ */
+export function countByGuard(db, query = {}) {
+    const conditions = buildConditions({ ...query, guard: undefined });
+    const where = conditions.sql === '' ? ' WHERE guard IS NOT NULL' : `${conditions.sql} AND guard IS NOT NULL`;
+    return db
+        .prepare(`SELECT guard, COUNT(*) AS count FROM events${where} GROUP BY guard ORDER BY count DESC, guard ASC`)
+        .all(...conditions.parameters);
+}

package/dist/src/operations/status.js

@@ -0,0 +1,197 @@
+import { deriveClaimState, isLive, secondsBetween } from "./derive.js";
+import { countByGuard, readLedger } from "./ledger.js";
+/**
+ * Read the database's own clock in the same textual form every timestamp
+ * column defaults to.
+ *
+ * The format string is repeated from the schema step rather than imported
+ * from it, and that is a considered choice: the step is **history the moment
+ * it has run anywhere** and must never be edited, so importing a constant out
+ * of it would make a file that may not change a dependency of one that will.
+ * A test asserts the two agree, which is the check that keeps a repetition
+ * honest.
+ */
+export const STORE_CLOCK_SQL = "strftime('%Y-%m-%dT%H:%M:%fZ', 'now')";
+export function readStoreClock(db) {
+    const row = db.prepare(`SELECT ${STORE_CLOCK_SQL} AS now`).get();
+    if (row === undefined) {
+        throw new Error('The store returned no answer when asked for its own clock.');
+    }
+    return row.now;
+}
+/**
+ * Read the recorded tab budget, or null when nothing has recorded one.
+ *
+ * The row §1.10 describes is written by the first process to open the store —
+ * `agreeOnTabBudget`, on the spawn path — into the `tab_budget` table that
+ * `schema/step-002-tab-budget.ts` owns. Null means no process has opened this
+ * store yet, which the document renders as "not recorded".
+ *
+ * ── Why this names `tab_budget` and probes for nothing ──────────────────
+ *
+ * §1.10 **deletes** the settings table rather than giving the budget a key in
+ * one, so `tab_budget` is the only place the value lives and this is a direct
+ * read of it. A read pointed anywhere else is worse than wrong: it returns
+ * null, which this function's own contract renders as "nothing has recorded a
+ * budget", and that is a plausible sentence about a healthy store. It would
+ * silence two things without either looking broken — `broker doctor`'s
+ * `config.tab_budget_agrees` would answer `unknown` forever, so **the one
+ * check that exists to catch a budget disagreement could never catch one**,
+ * and `status.limit` below would report null instead of the ceiling in force.
+ *
+ * **The table's absence is deliberately not tolerated.** `tab_budget` arrives
+ * in `schema/step-002-tab-budget.ts` and every caller here holds a stepped
+ * store, so a missing table is a broken installation and this raises rather
+ * than answering null about it — an existence probe here converts that fault
+ * into the same believable "not recorded". An **empty** table does read as
+ * null, because a store nothing has opened yet is an ordinary state.
+ *
+ * A test for this has to let the product create the table. One that creates a
+ * budget table itself is a fixture seeding a state the product cannot reach,
+ * and it passes whether or not this read names the right one.
+ */
+export function readTabBudget(db) {
+    const row = db.prepare(`SELECT tabs FROM tab_budget WHERE only_row = 1`).get();
+    if (row === undefined) {
+        return null;
+    }
+    const value = Number(row.tabs);
+    return Number.isFinite(value) ? value : null;
+}
+/**
+ * Take the picture.
+ *
+ * Every claim-derived number in it goes through `derive.ts`. There is no
+ * branch in this file that reads `claims.state` and reports it, and that is
+ * the property the mutation tests are aimed at.
+ */
+export function readOperationsStatus(db, options = {}) {
+    const at = options.now ?? readStoreClock(db);
+    const browserRows = db
+        .prepare(`SELECT id, state, restart_count, pid, launched_at, endpoint, browser_uuid
+       FROM browsers ORDER BY id`)
+        .all();
+    // Every claim whose *stored* state is live. A claim whose stored state is
+    // final cannot become live again, so this is the complete candidate set —
+    // the derivation can only move a row out of the live set, never into it.
+    const claimRows = db
+        .prepare(`SELECT c.id, c.session_id, c.browser_id, c.state, c.purpose, c.expires_at,
+              c.renew_count, c.created_at, c.activated_at,
+              (SELECT t.id FROM tabs t
+                WHERE t.claim_id = c.id AND t.state IN ('opening', 'open', 'closing')
+                ORDER BY t.created_at LIMIT 1) AS tab_id
+         FROM claims c
+        WHERE c.state IN ('queued', 'active')
+        ORDER BY c.created_at, c.id`)
+        .all();
+    const live = claimRows.filter((claim) => isLive(claim, at));
+    const leases = live
+        .filter((claim) => deriveClaimState(claim, at) === 'active')
+        .map((claim) => ({
+        claimId: claim.id,
+        sessionId: claim.session_id,
+        browserId: claim.browser_id,
+        purpose: claim.purpose,
+        state: deriveClaimState(claim, at),
+        expiresAt: claim.expires_at,
+        secondsUntilExpiry: secondsBetween(at, claim.expires_at),
+        renewCount: claim.renew_count,
+        createdAt: claim.created_at,
+        activatedAt: claim.activated_at,
+        tabId: claim.tab_id,
+    }));
+    const sessions = groupBySession(leases);
+    // Ordered by created_at then id, which is §1.5's ordering exactly. The
+    // SELECT above already applies it, so position is the index in that order
+    // among the entries still queued once derived.
+    const queue = live
+        .filter((claim) => deriveClaimState(claim, at) === 'queued')
+        .map((claim, index) => ({
+        claimId: claim.id,
+        sessionId: claim.session_id,
+        browserId: claim.browser_id,
+        purpose: claim.purpose,
+        position: index + 1,
+        waitedSeconds: secondsBetween(claim.created_at, at),
+        expiresAt: claim.expires_at,
+        secondsUntilExpiry: secondsBetween(at, claim.expires_at),
+    }));
+    const liveTabsByBrowser = new Map();
+    for (const lease of leases) {
+        if (lease.tabId !== null) {
+            liveTabsByBrowser.set(lease.browserId, (liveTabsByBrowser.get(lease.browserId) ?? 0) + 1);
+        }
+    }
+    const browsers = browserRows.map((row) => ({
+        id: row.id,
+        state: row.state,
+        restartCount: row.restart_count,
+        pid: row.pid,
+        launchedAt: row.launched_at,
+        discoveryRecorded: row.endpoint !== null,
+        identityRecorded: row.browser_uuid !== null,
+        liveTabs: liveTabsByBrowser.get(row.id) ?? 0,
+    }));
+    const leakedRows = db
+        .prepare(`SELECT id, browser_id, claim_id, state, close_attempts, updated_at
+         FROM tabs WHERE close_failed = 1 ORDER BY updated_at DESC`)
+        .all();
+    const feedbackRows = db
+        .prepare(`SELECT id, at, session_id, rating, category, note, last_guard
+         FROM feedback ORDER BY at DESC, id DESC LIMIT ?`)
+        .all(options.feedbackLimit ?? 10);
+    return {
+        at,
+        browsers,
+        budget: {
+            limit: readTabBudget(db),
+            used: live.length,
+            active: leases.length,
+            queued: queue.length,
+            keeperTabsExpected: browserRows.length,
+        },
+        sessions,
+        queue,
+        leakedTabs: leakedRows.map((row) => ({
+            tabId: row.id,
+            browserId: row.browser_id,
+            claimId: row.claim_id,
+            state: row.state,
+            closeAttempts: row.close_attempts,
+            updatedAt: row.updated_at,
+        })),
+        recentEvents: readLedger(db, { limit: options.eventLimit ?? 20 }).entries,
+        refusalsByGuard: countByGuard(db),
+        feedback: feedbackRows.map((row) => ({
+            id: row.id,
+            at: row.at,
+            sessionId: row.session_id,
+            rating: row.rating,
+            category: row.category,
+            note: row.note,
+            lastGuard: row.last_guard,
+        })),
+    };
+}
+/**
+ * Group live leases by session, "so one caller holding several reads as one
+ * caller" (§4.2).
+ *
+ * Insertion order is preserved, which means sessions appear in the order
+ * their earliest lease was created — the same ordering the query applied.
+ * Sorting by session identity instead would order the document by a value
+ * another system minted, which carries no meaning to a reader.
+ */
+function groupBySession(leases) {
+    const grouped = new Map();
+    for (const lease of leases) {
+        const existing = grouped.get(lease.sessionId);
+        if (existing === undefined) {
+            grouped.set(lease.sessionId, [lease]);
+        }
+        else {
+            existing.push(lease);
+        }
+    }
+    return [...grouped].map(([sessionId, sessionLeases]) => ({ sessionId, leases: sessionLeases }));
+}