browser-broker 0.1.0

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

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+const INSERT = `
+INSERT INTO comparisons (
+  id, source_capture_id, target_capture_id, claim_id,
+  colour_tolerance, minimum_region_area, maximum_regions,
+  changed_pixels, changed_ratio, changed, regions, overlay_path, truncated
+) VALUES (
+  @id, @sourceCaptureId, @targetCaptureId, @claimId,
+  @colourTolerance, @minimumRegionArea, @maximumRegions,
+  @changedPixels, @changedRatio, @changed, @regions, @overlayPath, @truncated
+)
+`;
+/**
+ * Write one comparison and return its identifier.
+ *
+ * Synchronous, because the driver is, and because this is called from inside a
+ * transaction the caller opened — an `await` in there would let another
+ * operation interleave with a write that is meant to be one unit.
+ */
+export function insertComparison(db, row) {
+    const id = randomUUID();
+    db.prepare(INSERT).run({
+        id,
+        sourceCaptureId: row.sourceCaptureId,
+        targetCaptureId: row.targetCaptureId,
+        claimId: row.claimId,
+        colourTolerance: row.colourTolerance,
+        minimumRegionArea: row.minimumRegionArea,
+        maximumRegions: row.maximumRegions,
+        changedPixels: row.changedPixels,
+        changedRatio: row.changedRatio,
+        // The column is an integer with a check constraint on nought-or-one, per
+        // the schema's own convention for a boolean.
+        changed: row.changed ? 1 : 0,
+        regions: JSON.stringify(row.regions),
+        overlayPath: row.overlayPath,
+        truncated: row.truncated ? 1 : 0,
+    });
+    return id;
+}
+function hydrate(columns) {
+    return {
+        id: columns.id,
+        sourceCaptureId: columns.source_capture_id,
+        targetCaptureId: columns.target_capture_id,
+        claimId: columns.claim_id,
+        at: columns.at,
+        colourTolerance: columns.colour_tolerance,
+        minimumRegionArea: columns.minimum_region_area,
+        maximumRegions: columns.maximum_regions,
+        changedPixels: columns.changed_pixels,
+        changedRatio: columns.changed_ratio,
+        changed: columns.changed === 1,
+        regions: JSON.parse(columns.regions),
+        overlayPath: columns.overlay_path,
+        truncated: columns.truncated === 1,
+    };
+}
+const SELECT = `
+SELECT id, source_capture_id, target_capture_id, claim_id, at,
+       colour_tolerance, minimum_region_area, maximum_regions,
+       changed_pixels, changed_ratio, changed, regions, overlay_path, truncated
+  FROM comparisons
+`;
+/**
+ * List comparisons, most recent first.
+ *
+ * **Most recent first** because the reason this surface exists is tuning, and
+ * the question tuning asks is what the current numbers have been doing. The
+ * indexes on the table are `(source_capture_id, at DESC)` and
+ * `(target_capture_id)`, so the first ordering is the one already paid for.
+ */
+export function listComparisons(db, query = {}) {
+    const conditions = [];
+    const parameters = {};
+    if (query.sourceCaptureId !== undefined) {
+        conditions.push('source_capture_id = @sourceCaptureId');
+        parameters['sourceCaptureId'] = query.sourceCaptureId;
+    }
+    if (query.targetCaptureId !== undefined) {
+        conditions.push('target_capture_id = @targetCaptureId');
+        parameters['targetCaptureId'] = query.targetCaptureId;
+    }
+    if (query.claimId !== undefined) {
+        conditions.push('claim_id = @claimId');
+        parameters['claimId'] = query.claimId;
+    }
+    const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+    // The limit is interpolated as a validated integer rather than bound,
+    // because the driver does not accept a parameter in this position. Coerced
+    // through `Math.trunc` and a floor of one so nothing but a number reaches
+    // the statement.
+    const limit = query.limit === undefined ? '' : ` LIMIT ${String(Math.max(1, Math.trunc(query.limit)))}`;
+    const rows = db.prepare(`${SELECT}${where} ORDER BY at DESC, id DESC${limit}`).all(parameters);
+    return rows.map(hydrate);
+}
+/** One comparison by identifier, or `null`. */
+export function findComparison(db, id) {
+    const row = db.prepare(`${SELECT} WHERE id = @id`).get({ id });
+    return row === undefined ? null : hydrate(row);
+}

package/dist/src/service/comparison.js

@@ -0,0 +1,173 @@
+import { fileNameFrom, overlayFileName, regionCropFileName } from "../diff/artifact-path.js";
+import { cutRegionCrops, drawOverlay, paddedRectangle } from "../diff/crops.js";
+import { reconcileGeometry } from "../diff/geometry.js";
+import { decodePng, encodePng } from "../diff/image.js";
+import { computeMask } from "../diff/mask.js";
+import { extractRegions } from "../diff/regions.js";
+/** A result carrying no diff, with the sentence saying why. */
+function noDiff(settings, explanation, extra = {}) {
+    return {
+        diffed: false,
+        changed: false,
+        changedPixels: 0,
+        changedRatio: 0,
+        regions: [],
+        overlayPath: null,
+        truncated: false,
+        comparedAgainst: null,
+        settingsApplied: {
+            colourTolerance: settings.colourTolerance,
+            minimumRegionArea: settings.minimumRegionArea,
+            maximumRegions: settings.maximumRegions,
+        },
+        pageLengthChange: null,
+        widthMismatch: false,
+        explanation,
+        comparisonId: null,
+        ...extra,
+    };
+}
+/**
+ * Write a PNG into a lease's images directory and return its stored path.
+ *
+ * The store creates the directory, refuses a name that would land outside the
+ * root, and hands back the relative path — which is the only form that goes in
+ * a row (§1.7a).
+ */
+function writeImage(artifacts, claimId, fileName, image) {
+    return artifacts.write(claimId, 'images', fileName, encodePng(image)).relativePath;
+}
+/**
+ * Run the comparison.
+ *
+ * The order of the checks is the order of §1.9's own reasoning, and each one
+ * returns a picture with an explanation rather than a refusal.
+ */
+export async function runComparison(options) {
+    const { capture, targetCaptureId, source, settings, artifacts } = options;
+    // ── 1. The capture the caller named ───────────────────────────────────
+    const target = source.find(targetCaptureId);
+    if (target === null) {
+        return noDiff(settings, `No diff was produced: there is no capture with the identifier ${JSON.stringify(targetCaptureId)}, so there was nothing to compare against. The picture you asked for is above. Check the identifier — it is the one returned by the earlier capture you meant to compare with.`);
+    }
+    // ── 2. It has to belong to this lease ─────────────────────────────────
+    //
+    // §1.9 on the bytes surface: it "serves only artifacts belonging to the
+    // asking lease, checked the same way every other tab-addressed operation is
+    // checked, and refusing with the same non-disclosing wording as an unknown
+    // tab (§7.1) so probing cannot discover another lease's files".
+    //
+    // **The same non-disclosing wording is used here**, and that is the decision
+    // in this branch: a caller that named another lease's capture is told the
+    // identical sentence as a caller that named nothing at all. Distinguishing
+    // them would turn `diff_against` into a way to enumerate other leases'
+    // captures by watching which identifiers produce a different message.
+    if (target.claimId !== capture.claimId) {
+        return noDiff(settings, `No diff was produced: there is no capture with the identifier ${JSON.stringify(targetCaptureId)}, so there was nothing to compare against. The picture you asked for is above. Check the identifier — it is the one returned by the earlier capture you meant to compare with.`);
+    }
+    const comparedAgainst = { captureId: target.id, path: target.path };
+    // ── 3. Both files have to be readable and decodable ───────────────────
+    let earlier;
+    let current;
+    try {
+        earlier = decodePng(await source.readBytes(target));
+        current = decodePng(options.captureBytes);
+    }
+    catch (error) {
+        return noDiff(settings, `No diff was produced: the image for capture ${JSON.stringify(targetCaptureId)} could not be read (${error instanceof Error ? error.message : String(error)}). The picture you asked for is above.`, { comparedAgainst });
+    }
+    // ── 4. Geometry, reported rather than pre-empted (#40) ────────────────
+    const geometry = reconcileGeometry({ width: earlier.width, height: earlier.height }, { width: current.width, height: current.height }, capture.kind);
+    if (!geometry.comparable || geometry.width === null || geometry.comparableHeight === null) {
+        return noDiff(settings, geometry.explanation ?? 'No diff was produced.', {
+            comparedAgainst,
+            widthMismatch: geometry.widthMismatch,
+            pageLengthChange: geometry.pageLengthChange,
+        });
+    }
+    // ── 5. The comparison itself ──────────────────────────────────────────
+    const mask = computeMask(earlier, current, {
+        colourTolerance: settings.colourTolerance,
+        height: geometry.comparableHeight,
+    });
+    const allRegions = extractRegions(mask, {
+        mergeDistance: settings.regionMergeDistance,
+        minimumArea: settings.minimumRegionArea,
+    });
+    // The cap bites here, and only here. The list is ordered largest first, so
+    // taking the first N drops the smallest — which is what §1.9 promises, and
+    // `truncated` is what stops the shortened list being "a lie about
+    // completeness".
+    const truncated = allRegions.length > settings.maximumRegions;
+    const kept = truncated ? allRegions.slice(0, settings.maximumRegions) : allRegions;
+    // ── 6. The crops and the overlay (#42) ────────────────────────────────
+    const captureFileName = fileNameFrom(capture.path);
+    const regions = [];
+    for (const [index, region] of kept.entries()) {
+        // One rectangle, padded and clamped once, both crops cut from it. The
+        // clamp is against the *compared* geometry rather than either image's own,
+        // so the rectangle is guaranteed to fit both — which is what makes "from
+        // the same rectangle" true on a full page whose height changed.
+        const rectangle = paddedRectangle(region, settings.cropPadding, geometry.width, geometry.comparableHeight);
+        if (rectangle === null) {
+            continue;
+        }
+        const crops = cutRegionCrops(earlier, current, rectangle);
+        const beforePath = writeImage(artifacts, capture.claimId, regionCropFileName(captureFileName, index, 'before'), crops.before);
+        const afterPath = writeImage(artifacts, capture.claimId, regionCropFileName(captureFileName, index, 'after'), crops.after);
+        regions.push({
+            x: region.x,
+            y: region.y,
+            width: region.width,
+            height: region.height,
+            changedPixels: region.changedPixels,
+            beforePath,
+            afterPath,
+        });
+    }
+    const storedOverlayPath = writeImage(artifacts, capture.claimId, overlayFileName(captureFileName), drawOverlay(current, kept));
+    // ── 7. The row (§1.9) ─────────────────────────────────────────────────
+    //
+    // `changed` is written rather than derived, because §1.9 fixes its
+    // definition — "true when at least one region survives filtering, not when
+    // any pixel differs" — and it "has to have one answer rather than two".
+    const comparedPixels = geometry.width * geometry.comparableHeight;
+    const changedRatio = comparedPixels === 0 ? 0 : mask.changedPixels / comparedPixels;
+    const changed = regions.length > 0;
+    const comparisonId = options.writeRow({
+        sourceCaptureId: capture.id,
+        targetCaptureId: target.id,
+        claimId: capture.claimId,
+        colourTolerance: settings.colourTolerance,
+        minimumRegionArea: settings.minimumRegionArea,
+        maximumRegions: settings.maximumRegions,
+        changedPixels: mask.changedPixels,
+        changedRatio,
+        changed,
+        regions,
+        overlayPath: storedOverlayPath,
+        truncated,
+    });
+    return {
+        diffed: true,
+        changed,
+        changedPixels: mask.changedPixels,
+        changedRatio,
+        regions,
+        overlayPath: storedOverlayPath,
+        truncated,
+        comparedAgainst,
+        settingsApplied: {
+            colourTolerance: settings.colourTolerance,
+            minimumRegionArea: settings.minimumRegionArea,
+            maximumRegions: settings.maximumRegions,
+        },
+        pageLengthChange: geometry.pageLengthChange,
+        widthMismatch: false,
+        // Present on an ordinary comparison only when the page length changed —
+        // the one comparable case that still needs a sentence, because a length
+        // change the caller cannot see is one it will attribute to something else.
+        explanation: geometry.explanation,
+        comparisonId,
+    };
+}

package/dist/src/service/events.js

@@ -0,0 +1,93 @@
+/** The kinds as data, for the test that reconciles them with the store. */
+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',
+    'storage_seeded',
+    'browser_signin_began',
+    'browser_signin_ended',
+];
+/** The adapters as data, for the same reconciliation test. */
+export const EVENT_ADAPTERS = [
+    'tool-stdio',
+    'tool-http',
+    'cli',
+    'internal',
+];
+const INSERT = `
+INSERT INTO events (kind, outcome, guard, claim_id, tab_id, session_id, adapter, browser_id, detail)
+VALUES (@kind, @outcome, @guard, @claimId, @tabId, @sessionId, @adapter, @browserId, @detail)
+`;
+/**
+ * Append one row and return its identifier.
+ *
+ * **`at` is not a parameter and is never supplied by a caller.** It is left
+ * to the column default, which reads the database's own clock (§1.1): several
+ * processes are running by design (§1.0a), and two of them disagreeing by a
+ * second would put the ledger subtly out of order in a way nothing reproduces
+ * — the cursor would still count upward, so the disorder would be invisible
+ * to every query that reads it.
+ *
+ * §2.4a is the related fact worth not confusing with this one: for an expiry,
+ * `at` is when the sweep ran and `claims.expired_at` is when the lease
+ * actually lapsed. Two facts, two columns, and only one of them is about the
+ * lease.
+ */
+export function append(db, event) {
+    const result = db.prepare(INSERT).run({
+        kind: event.kind,
+        outcome: event.outcome,
+        guard: event.guard ?? null,
+        claimId: event.claimId ?? null,
+        tabId: event.tabId ?? null,
+        sessionId: event.sessionId ?? null,
+        adapter: event.adapter,
+        browserId: event.browserId ?? null,
+        detail: event.detail == null ? null : JSON.stringify(event.detail),
+    });
+    return Number(result.lastInsertRowid);
+}
+const SELECT_SINCE = `
+SELECT id, at, kind, outcome, guard,
+       claim_id AS claimId, tab_id AS tabId, session_id AS sessionId,
+       adapter, browser_id AS browserId, detail
+FROM events
+WHERE id > @after
+ORDER BY id
+LIMIT @limit
+`;
+/**
+ * Read a slice, oldest first, starting after a cursor.
+ *
+ * §1.6: "events are meant to be looked at, not merely written". The read is
+ * here rather than in whatever eventually displays it because the ledger is
+ * one stream with one cursor, and a second reader written against the table
+ * directly is a second place the ordering rule can be got wrong.
+ *
+ * **Ordered by `id`, not by `at`.** Two rows written in the same millisecond
+ * share a timestamp, and ordering by a column with ties makes a page over the
+ * ledger able to skip or repeat a row at the boundary. The counter has no
+ * ties by construction, which is why §1.6 makes it the cursor.
+ */
+export function readSince(db, after, limit) {
+    return db.prepare(SELECT_SINCE).all({ after, limit });
+}

package/dist/src/service/keys.js

@@ -0,0 +1,68 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * The lease key: minted once, returned once, and never stored.
+ *
+ * §1.3 states the property this module exists to keep: **the secret key is
+ * never stored** — the claims table holds a one-way hash of it, and every
+ * call that carries a key hashes what it was handed and looks the lease up by
+ * that value.
+ *
+ * ── The consequence, which is a price rather than an oversight ──────────
+ *
+ * §2.2: **a caller that loses the response to its own request cannot get that
+ * lease back.** It waits the lease out, or asks an operator to revoke it.
+ * There is no recovery path and there is deliberately no second copy to build
+ * one from — a stored key would be a credential this service holds on a
+ * caller's behalf, and the whole reason it does not is that it then cannot
+ * leak one.
+ *
+ * ── Why a plain hash and not a password-hashing function ────────────────
+ *
+ * The usual reason to make hashing slow is that the input is a human-chosen
+ * password with little entropy, so an attacker who takes the table can guess
+ * candidates faster than they can be checked. **Neither half applies here.**
+ * The input is {@link KEY_BYTES} bytes from the platform's own random source,
+ * so there is no candidate list to work through; and the hash is read inside
+ * the arbitration transaction, with every other caller on the machine
+ * serialised behind it (§1.0a), so a deliberately slow function would be a
+ * deliberately slow lock.
+ *
+ * **What that trade rests on is the entropy**, which is why it is a constant
+ * with a comment rather than a number somebody can lower to make a key
+ * prettier.
+ */
+/**
+ * How many random bytes a key carries.
+ *
+ * Thirty-two bytes from the platform's cryptographic source. This is the
+ * assumption the fast hash above rests on: lower it far enough and guessing
+ * becomes possible, at which point the reasoning for a plain hash stops
+ * holding and the change that broke it is one number in this file.
+ */
+export const KEY_BYTES = 32;
+/**
+ * Mint a key. The only place one is created.
+ *
+ * The value is a base64url string so it survives every transport this service
+ * has — a command line argument, an environment variable, a field in a
+ * structured message — without escaping, and so a caller copying one out of a
+ * terminal cannot pick up a character that was really formatting.
+ */
+export function mintKey() {
+    return randomBytes(KEY_BYTES).toString('base64url');
+}
+/**
+ * Hash a key for storage and for lookup.
+ *
+ * Unsalted, deliberately, and this is the one place that word should appear
+ * in this service. A salt exists to stop one precomputed table covering every
+ * row at once, which is a defence against low-entropy inputs; with a
+ * {@link KEY_BYTES}-byte random input there is nothing to precompute. And a
+ * per-row salt would make lookup impossible: finding the lease for a key
+ * means hashing the key and matching a column, and a salted scheme would have
+ * to read every row and hash against each one — inside the transaction every
+ * other caller is waiting behind.
+ */
+export function hashKey(key) {
+    return createHash('sha256').update(key, 'utf8').digest('hex');
+}

package/dist/src/service/leases.js

@@ -0,0 +1,147 @@
+import { append } from "./events.js";
+import { hashKey } from "./keys.js";
+import { CallRefusal } from "./refusals.js";
+/**
+ * Find the lease a key names, refusing when it does not name a live one.
+ *
+ * **Two refusals, deliberately separate** (§7.1). A key this store has never
+ * seen is `key.valid`; a key naming a lease that ended is `claim.live`, and
+ * that one **names the state and when** (§2.2) — a caller told only "no"
+ * cannot tell a revoke it should escalate from an expiry it should simply
+ * retry with a fresh lease.
+ *
+ * **It must be called inside the arbitration transaction, after the sweep.**
+ * Reading `state` directly is correct only there: outside it, a row saying
+ * `active` whose expiry has elapsed is not an active lease, it is one that
+ * lapsed and has not been swept yet (§2.4). The sweep has already run by the
+ * time any handler executes, so a lease this returns as live is one this call
+ * reconciled.
+ */
+export function resolveLease(db, key, options) {
+    const row = db
+        .prepare(`SELECT id AS claimId, session_id AS sessionId, browser_id AS browserId, state,
+              purpose, expires_at AS expiresAt, ttl_seconds AS ttlSeconds,
+              renew_count AS renewCount, ended_at AS endedAt, revoke_reason AS revokeReason
+         FROM claims
+         WHERE key_hash = @keyHash`)
+        .get({ keyHash: hashKey(key) });
+    if (row === undefined) {
+        options.recordRefusal({
+            kind: options.kind,
+            outcome: 'deny',
+            guard: 'key.valid',
+            adapter: options.adapter,
+        });
+        throw new CallRefusal('unrecognised_key', 'That key does not match any lease in this store. A key is returned once and is never recoverable, so a lost key cannot be looked up — wait for the lease to lapse, or ask an operator to revoke it.');
+    }
+    if (row.state !== 'queued' && row.state !== 'active') {
+        // Everything that is not live is final (§2.1), so this branch covers the
+        // three ended states and nothing else.
+        options.recordRefusal({
+            kind: options.kind,
+            outcome: 'deny',
+            guard: 'claim.live',
+            adapter: options.adapter,
+            claimId: row.claimId,
+            sessionId: row.sessionId,
+            browserId: row.browserId,
+            detail: { state: row.state, endedAt: row.endedAt },
+        });
+        throw new CallRefusal('lease_ended', endedSentence(row), {
+            detail: {
+                claimId: row.claimId,
+                state: row.state,
+                endedAt: row.endedAt,
+                ...(row.revokeReason === null ? {} : { revokeReason: row.revokeReason }),
+            },
+        });
+    }
+    // The two refusals above have eliminated every other value, so this is the
+    // narrowing the checks already performed, restated for the type system.
+    return { ...row, state: row.state === 'queued' ? 'queued' : 'active' };
+}
+/**
+ * The sentence a caller gets for a lease that has ended.
+ *
+ * **It names the state and when** (§2.2, §7.1 `claim.live`), because the
+ * three ended states call for three different responses: an expiry is retried
+ * with a fresh request, a release was the caller's own doing and usually
+ * means two code paths tidying up, and a revoke is an operator taking
+ * capacity back with a reason the caller is owed. A refusal that said only
+ * "that lease is not usable" would send all three to the same wrong place.
+ */
+function endedSentence(row) {
+    const when = row.endedAt === null ? 'at an unrecorded moment' : `at ${row.endedAt}`;
+    if (row.state === 'revoked') {
+        return `That lease was revoked ${when}: ${row.revokeReason ?? 'no reason was recorded'}. An operator took the capacity back; a fresh request is the way on.`;
+    }
+    if (row.state === 'expired') {
+        return `That lease expired ${when} — nobody called in before it lapsed, so its tab is gone. Ask for a fresh lease; there is no way to revive this one.`;
+    }
+    return `That lease was released ${when}, so its tab is closed. Releasing is final; ask for a fresh lease to work again.`;
+}
+/**
+ * Extend a lease by the duration in force for it.
+ *
+ * **This is row #14, and it is a function every keyed operation calls rather
+ * than an operation of its own.** `MILESTONES.md` #14: a dedicated verb would
+ * be a second name for an effect every call already has.
+ *
+ * ── The duration comes off the row, not out of the environment ──────────
+ *
+ * §1.3 is explicit, and the reasoning is the part worth keeping: `ttl_seconds`
+ * is "the duration in force for this lease, fixed when it entered its current
+ * state. Stored rather than read from settings on each renewal, **because a
+ * renewal has to extend by the duration the caller was told** — re-reading a
+ * setting mid-lease silently changes a promise the caller has already acted
+ * on."
+ *
+ * So a caller told ten minutes keeps getting ten minutes even after the
+ * environment moves, and the new number reaches it on its next lease.
+ *
+ * **The extension runs from the moment of the call.** A lease renewed with
+ * two minutes left gets a full duration from now rather than a duration
+ * stacked on the remainder — the promise is *keep calling in or lose
+ * it*, not *call in to accumulate*, and stacking would let a caller poll its
+ * way to an unbounded hold.
+ */
+export function extendLease(db, lease, options) {
+    const row = db
+        .prepare(`UPDATE claims
+          SET expires_at = strftime('%Y-%m-%dT%H:%M:%fZ', @now, @extend),
+              renew_count = renew_count + 1,
+              updated_at = @now
+        WHERE id = @id AND state IN ('queued', 'active')
+    RETURNING expires_at AS expiresAt, renew_count AS renewCount`)
+        .get({
+        id: lease.claimId,
+        now: options.now,
+        // Assembled from the row's own duration, which is a number this store
+        // wrote. Nothing a caller supplied reaches this modifier.
+        extend: `+${String(lease.ttlSeconds)} seconds`,
+    });
+    if (row === undefined) {
+        // The lease was live when it was resolved, moments ago, in this same
+        // transaction. Nothing else can have ended it, so this is a bug rather
+        // than a race — and returning an unchanged expiry would quietly report a
+        // renewal that did not happen.
+        throw new Error(`The lease ${lease.claimId} was live when it was resolved and is not live now, inside one transaction.`);
+    }
+    append(db, {
+        kind: 'claim_renewed',
+        outcome: 'allow',
+        adapter: options.adapter,
+        claimId: lease.claimId,
+        sessionId: lease.sessionId,
+        browserId: lease.browserId,
+        detail: {
+            expiresAt: row.expiresAt,
+            ttlSeconds: lease.ttlSeconds,
+            renewCount: row.renewCount,
+            // What distinguishes a caller doing work from one polling to hold
+            // capacity it is not using (§1.3). Nothing acts on it in this version.
+            state: lease.state,
+        },
+    });
+    return row.expiresAt;
+}

package/dist/src/service/nudge.js

@@ -0,0 +1,66 @@
+import { append } from "./events.js";
+/**
+ * The leases a session already holds, other than the one being decided.
+ *
+ * **One comparison over data already in hand** (§2.3a): the admission
+ * transaction already counts live claims and already knows the asking
+ * session. No new table, no new state, no second query outside the
+ * transaction — this is a filter, and it reads the index §1.11 keeps for
+ * exactly this query.
+ *
+ * `state` is read directly, which is correct **only** inside the arbitration
+ * transaction after the sweep (§2.4). A lease this reports as held is one the
+ * same call has just reconciled.
+ */
+export function liveLeasesOfSession(db, sessionId, excludingClaimId) {
+    return db
+        .prepare(`SELECT id AS claimId, state, purpose, browser_id AS browserId, expires_at AS expiresAt
+         FROM claims
+         WHERE session_id = @sessionId
+           AND state IN ('queued', 'active')
+           AND (@excluding IS NULL OR id <> @excluding)
+         ORDER BY created_at, id`)
+        .all({ sessionId, excluding: excludingClaimId ?? null });
+}
+/**
+ * Build the nudge, and record that it fired.
+ *
+ * Returns `undefined` when the session holds nothing — which is the ordinary
+ * case, and the case where the advice would be actively wrong: telling a
+ * caller holding nothing to start with what it holds is telling it to do
+ * nothing.
+ *
+ * **The ledger row is written here rather than by the caller**, so a surface
+ * cannot attach the advice and forget the evidence. The row is an `allow`,
+ * because the nudge is not itself a refusal — whatever refused or queued the
+ * claim wrote its own row, and this one records that the caller was told it
+ * was its own obstacle.
+ */
+export function nudgeIfOwnObstacle(db, options) {
+    const holding = liveLeasesOfSession(db, options.sessionId, options.claimId);
+    if (holding.length === 0) {
+        return undefined;
+    }
+    const active = holding.filter((lease) => lease.state === 'active').length;
+    append(db, {
+        kind: 'claim_queued',
+        outcome: 'allow',
+        adapter: options.adapter,
+        claimId: options.claimId,
+        sessionId: options.sessionId,
+        detail: {
+            nudge: 'own_obstacle',
+            outcome: options.outcome,
+            holding: holding.length,
+            holdingActive: active,
+            heldClaimIds: holding.map((lease) => lease.claimId),
+        },
+    });
+    return {
+        holding,
+        advice: `This session already holds ${String(holding.length)} live lease${holding.length === 1 ? '' : 's'}` +
+            `${active > 0 ? ` (${String(active)} holding a tab)` : ''}, so some of the capacity being waited for is capacity being held. ` +
+            'Start with what is already held: finishing work on a held tab frees capacity this same session can reuse, which unblocks by working rather than by waiting. ' +
+            'If the work genuinely cannot be serialised, release what is held and ask again.',
+    };
+}