browser-broker 0.1.0

package/dist/src/report/document.js

@@ -0,0 +1,419 @@
+import { renderAddress } from "../operations/addresses.js";
+import { secondsBetween } from "../operations/derive.js";
+import { escapeHtml, escapeValue } from "./escape.js";
+/**
+ * The styling, inlined.
+ *
+ * Plain CSS with no custom fonts and no imports, so the file needs nothing
+ * from a network to render. The colour choices carry meaning that is also
+ * carried in words — an expired lease says "expired" as well as being
+ * coloured — because a document sent to somebody may be read by a person who
+ * does not see the colours, or printed.
+ */
+const STYLE = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body {
+  margin: 0; padding: 2rem 1.5rem 4rem;
+  font: 15px/1.55 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  background: #fbfbfc; color: #1c1e21;
+}
+main { max-width: 76rem; margin: 0 auto; }
+h1 { font-size: 1.5rem; margin: 0 0 .25rem; }
+h2 { font-size: 1.05rem; margin: 2.25rem 0 .5rem; letter-spacing: .01em; }
+p { margin: .35rem 0; }
+.taken {
+  margin: 1rem 0 1.75rem; padding: .85rem 1rem;
+  border: 1px solid #d8b74a; border-left-width: 5px; border-radius: 4px;
+  background: #fdf7e3;
+}
+.taken .moment { font-size: 1.15rem; font-weight: 650; }
+.taken .warning { margin-top: .3rem; color: #6b5312; }
+table { width: 100%; border-collapse: collapse; margin: .4rem 0 .5rem; font-size: 14px; }
+th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #e6e7ea; vertical-align: top; }
+th { font-weight: 600; color: #4a4d52; background: #f2f3f5; border-bottom-color: #d9dadd; }
+td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+code, .mono { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 13px; }
+.empty { color: #6b6e73; font-style: italic; }
+.tag { display: inline-block; padding: .05rem .4rem; border-radius: 3px; font-size: 12px; font-weight: 600; }
+.tag-ok { background: #dcf0dc; color: #1d4620; }
+.tag-warn { background: #fbecd0; color: #6b4a06; }
+.tag-bad { background: #f7dada; color: #6d1f1f; }
+.tag-idle { background: #e6e7ea; color: #43464b; }
+.unreachable { font-weight: 650; color: #8a2020; }
+.counts { display: flex; flex-wrap: wrap; gap: 1.5rem; margin: .5rem 0 0; padding: 0; list-style: none; }
+.counts li { min-width: 7rem; }
+.counts .label { display: block; font-size: 12px; color: #5c5f64; text-transform: uppercase; letter-spacing: .04em; }
+.counts .value { font-size: 1.5rem; font-weight: 650; font-variant-numeric: tabular-nums; }
+footer { margin-top: 3rem; padding-top: 1rem; border-top: 1px solid #e6e7ea; color: #5c5f64; font-size: 13px; }
+@media (prefers-color-scheme: dark) {
+  body { background: #17181b; color: #e6e7ea; }
+  .taken { background: #2c2612; border-color: #7d6a24; }
+  .taken .warning { color: #d9c684; }
+  th { background: #212327; color: #b9bcc2; border-bottom-color: #33363b; }
+  th, td { border-bottom-color: #26282c; }
+  .empty, .counts .label, footer { color: #9c9fa5; }
+  .tag-ok { background: #1d3a1f; color: #b9e2bb; }
+  .tag-warn { background: #40320f; color: #eccf8e; }
+  .tag-bad { background: #451c1c; color: #efb5b5; }
+  .tag-idle { background: #2b2d31; color: #b9bcc2; }
+  .unreachable { color: #f08b8b; }
+  footer { border-top-color: #33363b; }
+}
+`.trim();
+/**
+ * The behaviour, inlined — and there is deliberately almost none.
+ *
+ * §4.1 forbids polling, a countdown and a live indicator, so what is left is
+ * one thing that makes the document *more* honest rather than less: it reads
+ * the moment already written into the page and says how long ago that was,
+ * **once, at open time.** It never repeats, so nothing in the page changes
+ * after it has been read — which is the property the rule protects.
+ *
+ * The value it computes is the reader's own clock against a moment from
+ * another machine's, so it is rounded to a coarse unit and labelled
+ * approximate. A precise figure would imply the two clocks agree.
+ *
+ * If it does not run — scripts disabled, or a viewer that strips them — the
+ * document is unaffected: the timestamp is already in the markup, and this
+ * only appends to it.
+ */
+const SCRIPT = `
+(function () {
+  var node = document.getElementById('age');
+  if (!node) { return; }
+  var taken = Date.parse(node.getAttribute('data-taken') || '');
+  if (isNaN(taken)) { return; }
+  var seconds = Math.max(0, Math.round((Date.now() - taken) / 1000));
+  var text;
+  if (seconds < 90) { text = 'moments ago'; }
+  else if (seconds < 5400) { text = 'about ' + Math.round(seconds / 60) + ' minutes ago'; }
+  else if (seconds < 172800) { text = 'about ' + Math.round(seconds / 3600) + ' hours ago'; }
+  else { text = 'about ' + Math.round(seconds / 86400) + ' days ago'; }
+  node.textContent = ' — taken ' + text + ' (approximate: your clock, not the store\\u2019s)';
+})();
+`.trim();
+/** Seconds as something a person reads, e.g. `4m 12s`. */
+export function humaniseSeconds(seconds) {
+    const negative = seconds < 0;
+    const total = Math.abs(Math.round(seconds));
+    const parts = total < 60
+        ? `${String(total)}s`
+        : total < 3600
+            ? `${String(Math.floor(total / 60))}m ${String(total % 60)}s`
+            : `${String(Math.floor(total / 3600))}h ${String(Math.floor((total % 3600) / 60))}m`;
+    return negative ? `${parts} ago` : parts;
+}
+/** How an expiry is shown: the remaining time, or that it has passed. */
+function expiryCell(secondsUntilExpiry) {
+    if (secondsUntilExpiry <= 0) {
+        // Reachable only in the window between a lease lapsing and this document
+        // deriving it — which the derivation closes. Kept because a lease with a
+        // renewal in flight can land here, and because a cell that could only
+        // ever be positive would be a claim this module cannot make.
+        return `<span class="tag tag-bad">lapsed ${escapeHtml(humaniseSeconds(secondsUntilExpiry))}</span>`;
+    }
+    const urgent = secondsUntilExpiry < 60;
+    return `<span class="tag ${urgent ? 'tag-warn' : 'tag-ok'}">${escapeHtml(humaniseSeconds(secondsUntilExpiry))}</span>`;
+}
+function browserStateTag(state) {
+    const className = state === 'running'
+        ? 'tag-ok'
+        : state === 'failed'
+            ? 'tag-bad'
+            : state === 'starting' || state === 'signing-in'
+                ? 'tag-warn'
+                : 'tag-idle';
+    return `<span class="tag ${className}">${escapeHtml(state)}</span>`;
+}
+/** A table, or an italic sentence when there is nothing in it. */
+function table(headers, rows, empty) {
+    if (rows.length === 0) {
+        return `<p class="empty">${escapeHtml(empty)}</p>`;
+    }
+    const head = headers.map((header) => `<th>${escapeHtml(header)}</th>`).join('');
+    return `<table><thead><tr>${head}</tr></thead><tbody>${rows.join('')}</tbody></table>`;
+}
+/**
+ * The address cell (§4.2a).
+ *
+ * The **only** place a live-read address becomes markup, and it goes through
+ * {@link renderAddress} so the three outcomes are decided in one place. The
+ * `unreachable` word carries a class so it is visually distinct, but the word
+ * itself is the signal — a reader who cannot see the colour still reads it.
+ */
+function addressCell(tabId, addresses) {
+    if (tabId === null) {
+        return `<td class="empty">no tab</td>`;
+    }
+    const address = addresses.get(tabId);
+    const text = renderAddress(address);
+    const unreachable = address === undefined || address.kind === 'unreachable';
+    const reason = address !== undefined && address.kind === 'unreachable' ? address.reason : '';
+    return unreachable
+        ? `<td><span class="unreachable" title="${escapeHtml(reason)}">${escapeHtml(text)}</span></td>`
+        : `<td class="mono">${escapeHtml(text)}</td>`;
+}
+function leaseRow(lease, addresses, showSession) {
+    const session = showSession ? `<td class="mono">${escapeValue(lease.sessionId)}</td>` : '';
+    return [
+        '<tr>',
+        session,
+        `<td class="mono">${escapeValue(lease.claimId)}</td>`,
+        `<td>${escapeValue(lease.browserId)}</td>`,
+        `<td>${escapeValue(lease.purpose)}</td>`,
+        // Derived, never stored. `LeaseView.state` is the output of
+        // `deriveClaimState` and the type carries no stored column to print.
+        `<td><span class="tag tag-ok">${escapeValue(lease.state)}</span></td>`,
+        `<td>${expiryCell(lease.secondsUntilExpiry)}</td>`,
+        `<td class="num">${escapeValue(lease.renewCount)}</td>`,
+        addressCell(lease.tabId, addresses),
+        '</tr>',
+    ].join('');
+}
+function queueRow(entry) {
+    return [
+        '<tr>',
+        `<td class="num">${escapeValue(entry.position)}</td>`,
+        `<td class="mono">${escapeValue(entry.sessionId)}</td>`,
+        `<td>${escapeValue(entry.browserId)}</td>`,
+        `<td>${escapeValue(entry.purpose)}</td>`,
+        `<td>${escapeHtml(humaniseSeconds(entry.waitedSeconds))}</td>`,
+        `<td>${expiryCell(entry.secondsUntilExpiry)}</td>`,
+        '</tr>',
+    ].join('');
+}
+/**
+ * The moment, prominently and in the document (§4.1).
+ *
+ * Both halves are here on purpose. The timestamp answers *when*; the sentence
+ * beside it answers *what that means* — that nothing on the page will change,
+ * that the numbers are as they were at that instant, and that a queue may
+ * have drained since. §4.1's rule is that the document must not pretend to be
+ * a window, and a timestamp on its own does not say that.
+ */
+function takenBanner(at) {
+    return [
+        '<div class="taken" role="note">',
+        `<div class="moment">Snapshot taken at <span class="mono">${escapeHtml(at)}</span><span id="age" data-taken="${escapeHtml(at)}"></span></div>`,
+        '<p class="warning">This is a photograph, not a window. <strong>Nothing on this page refreshes</strong> — every',
+        'lease, expiry and queue position is as it was at the moment above, and may have changed since.',
+        'Generate a new snapshot to see the current picture.</p>',
+        '</div>',
+    ].join('\n');
+}
+function browsersSection(status) {
+    const rows = status.browsers.map((browser) => {
+        const record = browser.discoveryRecorded
+            ? browser.identityRecorded
+                ? '<span class="tag tag-idle">address and identity recorded</span>'
+                : '<span class="tag tag-warn">address only</span>'
+            : '<span class="tag tag-idle">none recorded</span>';
+        return [
+            '<tr>',
+            `<td>${escapeValue(browser.id)}</td>`,
+            `<td>${browserStateTag(browser.state)}</td>`,
+            `<td class="num">${escapeValue(browser.restartCount)}</td>`,
+            `<td class="num">${escapeValue(browser.pid)}</td>`,
+            `<td class="mono">${escapeValue(browser.launchedAt)}</td>`,
+            `<td>${record}</td>`,
+            `<td class="num">${escapeValue(browser.liveTabs)}</td>`,
+            '</tr>',
+        ].join('');
+    });
+    return [
+        '<h2>Browsers</h2>',
+        table(['Browser', 'State', 'Restarts', 'Process', 'Launched', 'Discovery record', 'Leased tabs'], rows, 'No browsers are recorded, which should not happen — the schema seeds two.'),
+        // §1.2c: the record is a claim, not a proof. The document reports what the
+        // store holds; only `broker doctor` reaches the endpoint and can say
+        // whether it checks out. Saying so here is what stops a reader taking
+        // "recorded" for "working".
+        '<p class="empty">A discovery record is a claim, not a proof — it survives the browser it names.',
+        'Whether one actually answers, and answers as the expected browser, is what <code>broker doctor</code> checks.</p>',
+    ].join('\n');
+}
+function budgetSection(status) {
+    const { budget } = status;
+    const limit = budget.limit === null ? 'not recorded' : String(budget.limit);
+    return [
+        '<h2>Budget</h2>',
+        '<ul class="counts">',
+        `<li><span class="label">Tab budget</span><span class="value">${escapeHtml(limit)}</span></li>`,
+        `<li><span class="label">Live leases</span><span class="value">${escapeValue(budget.used)}</span></li>`,
+        `<li><span class="label">Holding a tab</span><span class="value">${escapeValue(budget.active)}</span></li>`,
+        `<li><span class="label">Queued</span><span class="value">${escapeValue(budget.queued)}</span></li>`,
+        `<li><span class="label">Keeper tabs</span><span class="value">${escapeValue(budget.keeperTabsExpected)}</span></li>`,
+        '</ul>',
+        // §3.15: the keeper tab is not capacity and is not counted against the
+        // budget, and it is "reported wherever pages are counted" precisely so a
+        // person looking at a browser window can reconcile what they see.
+        '<p class="empty">Keeper tabs are one blank page per browser. They are never leased and never counted against the',
+        'budget, so a browser window shows one more tab than the budget accounts for. Counted here so the two reconcile.',
+        budget.limit === null
+            ? 'The budget has not been recorded in this store yet, so there is no bound to compare against.'
+            : '',
+        '</p>',
+    ].join('\n');
+}
+function leasesSection(status, addresses) {
+    const headers = ['Lease', 'Browser', 'Purpose', 'State', 'Expires in', 'Renewals', 'Address'];
+    const groups = status.sessions.map((session) => {
+        const rows = session.leases.map((lease) => leaseRow(lease, addresses, false));
+        return [
+            `<h3 class="mono">${escapeValue(session.sessionId)} — ${String(session.leases.length)} lease(s)</h3>`,
+            table(headers, rows, 'No live leases for this session.'),
+        ].join('\n');
+    });
+    return [
+        '<h2>Live leases</h2>',
+        // §2.4's standing rule, said in the document rather than only in the code,
+        // because a reader comparing this against a direct table read deserves to
+        // know which one is right.
+        '<p class="empty">Grouped by session, so one caller holding several tabs reads as one caller.',
+        'Every lease here had the expiry derivation applied at the moment above — a lease that had lapsed but',
+        'had not yet been swept is not shown as live.</p>',
+        groups.length === 0 ? '<p class="empty">Nothing holds a tab.</p>' : groups.join('\n'),
+    ].join('\n');
+}
+function queueSection(status) {
+    const front = status.queue[0];
+    const depth = status.queue.length;
+    return [
+        '<h2>Queue</h2>',
+        `<p>Depth <strong>${String(depth)}</strong>${front === undefined
+            ? '. Nobody is waiting.'
+            : `. The caller at the front has waited <strong>${escapeHtml(humaniseSeconds(front.waitedSeconds))}</strong>.`}</p>`,
+        table(['#', 'Session', 'Browser', 'Purpose', 'Waited', 'Place expires in'], status.queue.map((entry) => queueRow(entry)), 'Nobody is waiting.'),
+    ].join('\n');
+}
+function leakedSection(status) {
+    const rows = status.leakedTabs.map((tab) => [
+        '<tr>',
+        `<td class="mono">${escapeValue(tab.tabId)}</td>`,
+        `<td>${escapeValue(tab.browserId)}</td>`,
+        `<td class="mono">${escapeValue(tab.claimId)}</td>`,
+        `<td>${escapeValue(tab.state)}</td>`,
+        `<td class="num">${escapeValue(tab.closeAttempts)}</td>`,
+        `<td class="mono">${escapeValue(tab.updatedAt)}</td>`,
+        '</tr>',
+    ].join(''));
+    return [
+        '<h2>Leaked tabs</h2>',
+        // §2.4b: a leaked tab is not a leaked lease. The capacity is already back;
+        // what is left is a page nobody owns. Saying so stops a reader treating
+        // this section as a capacity problem.
+        '<p class="empty">A tab that would not close after its lease ended. The capacity came back when the lease did —',
+        'what is left is a page nobody owns, which costs memory and not budget.</p>',
+        table(['Tab', 'Browser', 'Was leased by', 'State', 'Close attempts', 'Last seen'], rows, 'No tabs have leaked.'),
+    ].join('\n');
+}
+function ledgerSection(status) {
+    const rows = status.recentEvents.map((entry) => [
+        '<tr>',
+        `<td class="num">${escapeValue(entry.id)}</td>`,
+        `<td class="mono">${escapeValue(entry.at)}</td>`,
+        `<td>${escapeValue(entry.kind)}</td>`,
+        `<td>${entry.outcome === 'deny'
+            ? `<span class="tag tag-bad">deny</span>`
+            : `<span class="tag tag-ok">allow</span>`}</td>`,
+        `<td>${escapeValue(entry.guard)}</td>`,
+        `<td>${escapeValue(entry.adapter)}</td>`,
+        `<td class="mono">${escapeValue(entry.sessionId)}</td>`,
+        '</tr>',
+    ].join(''));
+    const refusals = status.refusalsByGuard.map((guard) => [
+        '<tr>',
+        `<td class="mono">${escapeValue(guard.guard)}</td>`,
+        `<td class="num">${escapeValue(guard.count)}</td>`,
+        '</tr>',
+    ].join(''));
+    const highest = status.recentEvents.reduce((best, entry) => (best === null || entry.id > best ? entry.id : best), null);
+    return [
+        '<h2>Recent ledger entries</h2>',
+        table(['#', 'At', 'Kind', 'Outcome', 'Rule', 'Route', 'Session'], rows, 'The ledger is empty.'),
+        highest === null
+            ? ''
+            : `<p class="empty">Most recent entry is <code>#${String(highest)}</code>. Read on with <code>broker events --since ${String(highest)}</code>.</p>`,
+        '<h2>Refusals by rule</h2>',
+        // §1.6: an allowed row does not record which rules passed, so "has this
+        // rule ever fired" is answered by the refusals and by nothing else.
+        '<p class="empty">Only refusals name a rule, so this is the whole of what the ledger can say about which rules have fired.</p>',
+        table(['Rule', 'Times refused'], refusals, 'Nothing has been refused.'),
+    ].join('\n');
+}
+function feedbackSection(status) {
+    const rows = status.feedback.map((entry) => [
+        '<tr>',
+        `<td class="mono">${escapeValue(entry.at)}</td>`,
+        `<td class="num">${escapeValue(entry.rating)}</td>`,
+        `<td>${escapeValue(entry.category)}</td>`,
+        `<td class="mono">${escapeValue(entry.sessionId)}</td>`,
+        `<td>${escapeValue(entry.lastGuard)}</td>`,
+        `<td>${escapeValue(entry.note)}</td>`,
+        '</tr>',
+    ].join(''));
+    return [
+        '<h2>What callers reported</h2>',
+        // §3.16 and §4.2: the tool has a planned removal, and "this section
+        // disappearing entirely is the signal that tool has done its job". An
+        // empty section is therefore not a defect and the document says so.
+        '<p class="empty">The rating is not satisfaction — it is whether this service moved the caller’s work forward',
+        'or got in its way. This section emptying out permanently is the signal that the feedback tool has done its job.</p>',
+        table(['At', 'Rating', 'Category', 'Session', 'Rule hit', 'Note'], rows, 'No caller has reported anything.'),
+    ].join('\n');
+}
+/**
+ * Assemble the document.
+ *
+ * Returns the string rather than writing it, so the whole of it is assertable
+ * from a test without a filesystem — and so the command that writes it has
+ * one job, which is writing it.
+ */
+export function renderDocument(input) {
+    const { status } = input;
+    const addressNote = input.addressNote === undefined ? '' : `<p class="empty">${escapeHtml(input.addressNote)}</p>`;
+    return [
+        '<!doctype html>',
+        '<html lang="en">',
+        '<head>',
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        // Not a refresh directive, and its absence is the point (§4.1). Nothing
+        // in this head reloads, polls or redirects.
+        `<title>Browser Broker — snapshot ${escapeHtml(status.at)}</title>`,
+        `<style>${STYLE}</style>`,
+        '</head>',
+        '<body>',
+        '<main>',
+        '<h1>Browser Broker — operations snapshot</h1>',
+        takenBanner(status.at),
+        browsersSection(status),
+        budgetSection(status),
+        leasesSection(status, input.addresses),
+        addressNote,
+        // §4.2a, said where the addresses are: they were asked for, live, under a
+        // per-tab timeout, and `unreachable` means the question went unanswered.
+        '<p class="empty">Addresses were read from the browsers at the moment above, each under its own timeout.',
+        `<strong>${escapeHtml('unreachable')}</strong> means the browser was asked and did not answer — which is a different fact from a lease having no tab.</p>`,
+        queueSection(status),
+        leakedSection(status),
+        ledgerSection(status),
+        feedbackSection(status),
+        '<footer>',
+        `<p>Generated by Browser Broker${input.version === undefined ? '' : ` ${escapeHtml(input.version)}`} at <span class="mono">${escapeHtml(status.at)}</span>.`,
+        'Read-only: this document has no controls, and nothing here acts on the service.',
+        'To act on the service as it is now, run a command against it.</p>',
+        '</footer>',
+        '</main>',
+        `<script>${SCRIPT}</script>`,
+        '</body>',
+        '</html>',
+        '',
+    ].join('\n');
+}
+/**
+ * The instant a lease has left, for a caller that wants the number without
+ * the markup. Exported because the doctor report uses the same arithmetic and
+ * two copies of it would drift.
+ */
+export { secondsBetween };

package/dist/src/report/escape.js

@@ -0,0 +1,68 @@
+/**
+ * Escaping, on its own, because a document assembled by concatenation has
+ * exactly one way to go wrong and this is it.
+ *
+ * Everything in the operations document comes from somewhere this service
+ * does not control: a session identity another system minted (`SCHEMA.md`
+ * §1.3), a free-text purpose a caller wrote, a free-text feedback note
+ * (§3.16), an error message from a browser, and — via §4.2a — **a page
+ * address read live from a browser**. Any of those can contain the characters
+ * that end an attribute or open a tag.
+ *
+ * The document is also **shared**: §4's whole argument for a file is that it
+ * "can be sent to somebody, kept beside a report, or opened on a machine that
+ * has never run this service". So the person who opens it is frequently not
+ * the person who generated it, and markup that came in from a page address is
+ * markup that runs in their browser.
+ *
+ * There is no templating engine here and there will not be one — the binding
+ * is no runtime dependencies, and a self-contained file with a build step
+ * behind it would contradict the reason it is self-contained. So escaping is
+ * a function that is called, and the check is that everything which
+ * interpolates calls it.
+ */
+/**
+ * Escape text for HTML, covering both element content and attribute values.
+ *
+ * Five characters rather than three: the two quote forms are included so one
+ * function is correct in both positions. A separate attribute escaper is a
+ * second function to remember to call, and the one anybody forgets is
+ * whichever they use less.
+ *
+ * The ampersand is replaced first, and the order is load-bearing rather than
+ * stylistic: doing it later would re-escape the ampersands the other
+ * replacements have just introduced, turning `<` into `&amp;lt;`.
+ */
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Escape a value of unknown type for HTML.
+ *
+ * Null and undefined become an em dash rather than the words "null" or
+ * "undefined", because the document is read by a person and those two words
+ * are this language's, not this service's. **This is not the `unreachable`
+ * case** — that is a different fact with its own explicit word (§4.2a), and
+ * it is decided in `addresses.ts` before anything reaches here.
+ *
+ * **Only the four primitive shapes a cell can honestly hold are rendered**,
+ * and anything else becomes the em dash too. That is not defensiveness: a
+ * value that reached a table cell as an object or an array is a mistake in
+ * the caller, and stringifying it would print the language's own placeholder
+ * for "I could not do this" into a document a person reads as a fact. An
+ * em dash says the cell has nothing in it, which is at least true.
+ */
+export function escapeValue(value) {
+    if (typeof value === 'string') {
+        return escapeHtml(value);
+    }
+    if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') {
+        return escapeHtml(value.toString());
+    }
+    return '—';
+}

package/dist/src/report/snapshot.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readAddresses, } from "../operations/addresses.js";
+import { readOperationsStatus } from "../operations/status.js";
+import { renderDocument } from "./document.js";
+/**
+ * `broker snapshot` — write the operations document to a path and exit
+ * (`SCHEMA.md` §4.5, §5.5).
+ *
+ * **One command, one file. It writes the document wherever it is told,
+ * reports the path, and exits. It leaves nothing behind and holds nothing
+ * open.**
+ *
+ * ── The order of operations here is the design ──────────────────────────
+ *
+ * 1. Read the status. One statement set, derived (§2.4), and it finishes.
+ * 2. **Then** ask the browsers where their tabs are (§4.2a), each under its
+ *    own timeout.
+ * 3. Render, and write.
+ *
+ * Step 2 is after step 1 and outside everything, which is what keeps §2.4b's
+ * hard rule true here: **browser work never happens inside the arbitration
+ * transaction.** The status read is over by the time a browser is asked
+ * anything, and nothing in this file opens a transaction around either.
+ * `MILESTONES.md` #70 says the same thing from the other direction —
+ * "generation happens outside any transaction, so this does not violate the
+ * never-do-browser-I/O-inside-the-arbitration-transaction rule — but it MUST
+ * carry a timeout".
+ *
+ * ── Failing to reach the browsers is not failing to produce a document ───
+ *
+ * §4.2a: a generator that inherits a browser's hang "produces nothing at all,
+ * which is a worse outcome than an incomplete document". So there is no path
+ * through this function that throws because a browser was unavailable. Every
+ * such outcome becomes `unreachable` in the document, which is the explicit
+ * word the rule requires.
+ */
+/** How long one tab's address read may take, in milliseconds. */
+export const DEFAULT_ADDRESS_TIMEOUT_MS = 2000;
+/**
+ * Generate the document and write it.
+ *
+ * The directory is created if it is absent, which is the one filesystem
+ * liberty this takes and it is the same one every writer of a named output
+ * path takes: a person naming a path inside a directory that does not exist
+ * meant the path, and refusing would be pedantry rather than safety.
+ */
+export async function writeSnapshot(db, options) {
+    // Step 1: the derived status read. Finishes before any browser is touched.
+    const status = readOperationsStatus(db, {
+        eventLimit: options.eventLimit,
+        feedbackLimit: options.feedbackLimit,
+        now: options.now,
+    });
+    // Step 2: the live address read, outside everything.
+    let addresses = new Map();
+    let addressNote;
+    let tabsAsked = 0;
+    const liveTabIds = status.sessions
+        .flatMap((session) => session.leases)
+        .map((lease) => lease.tabId)
+        .filter((tabId) => tabId !== null);
+    if (options.addresses === undefined) {
+        if (liveTabIds.length > 0) {
+            addressNote =
+                'No browser connection was available when this snapshot was taken, so no address could be read. Every address below reads as unreachable for that one reason rather than because fifteen separate reads failed.';
+        }
+    }
+    else {
+        // Only ask about tabs the document is actually going to show. A request
+        // for a tab no live lease holds would be a read of a page nobody owns,
+        // which is exactly the browsing-history shape §1.4 deletes the column to
+        // avoid.
+        const shown = new Set(liveTabIds);
+        const requests = options.addresses.requests.filter((request) => shown.has(request.tabId));
+        tabsAsked = requests.length;
+        addresses = await readAddresses(options.addresses.source, requests, {
+            timeoutMs: options.addresses.timeoutMs ?? DEFAULT_ADDRESS_TIMEOUT_MS,
+        });
+    }
+    // Step 3: render and write.
+    const html = renderDocument({ status, addresses, addressNote, version: options.version });
+    const resolved = path.resolve(options.outputPath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, html, 'utf8');
+    const unreachable = [...addresses.values()].filter((address) => address.kind === 'unreachable').length;
+    return {
+        path: resolved,
+        bytes: Buffer.byteLength(html, 'utf8'),
+        at: status.at,
+        tabsAsked,
+        // Tabs that were never asked about count as unreachable, because that is
+        // how the document renders them — a number that disagreed with the
+        // document would be worse than no number.
+        tabsUnreachable: unreachable + (liveTabIds.length - tabsAsked),
+    };
+}