browser-broker 0.1.0

package/dist/src/doctor/report.js

@@ -0,0 +1,152 @@
+import { SIGNABLE_BROWSER } from "../service/operations/sign-in.js";
+import { readTabBudget } from "../operations/status.js";
+import { classifySignIn } from "../service/signin-recovery.js";
+import { readStoreVersion } from "../store/schema/step.js";
+import { inspectProfileSession } from "./session.js";
+import { checkAbandonedSignIn, checkAutomation, checkCaptureSurface, checkDiscoveryRecord, checkKeeperTab, checkRootWritable, checkSchemaVersion, checkSignInSession, checkStoreLocation, checkStorePresent, checkTabBudget, exitCodeFor, } from "./checks.js";
+/**
+ * Run the preconditions.
+ *
+ * `db` is optional because a store that does not exist yet is a legitimate
+ * state to ask about — arguably the state where the answer is most useful,
+ * since it is the one somebody has just installed into. Every store-derived
+ * check reports `unknown` rather than failing when there is nothing to read.
+ *
+ * **Nothing here writes to the store.** The only write anywhere in this
+ * command is the write probe on each root, which removes what it wrote and is
+ * named in `checks.ts`'s header.
+ */
+export function runDoctor(environment, db, probes = {}) {
+    const version = db === undefined ? null : readStoreVersion(db);
+    const storedBudget = db === undefined ? null : readTabBudget(db);
+    const checks = [
+        checkStoreLocation(environment, probes.networkChecks),
+        checkStorePresent(environment),
+        checkSchemaVersion(version),
+        checkAutomation(probes.automation ?? { present: undefined }),
+        checkRootWritable('roots.artifacts_writable', 'The artifact root is writable', environment.artifactsRoot),
+        checkRootWritable('roots.profiles_writable', 'The profile root is writable', environment.profileRoot),
+    ];
+    // **Every configured browser, not the default pair.** `DEFAULT_BROWSER_IDS`
+    // is "the default set, never the permitted set" (see its own comment); an
+    // installation that names a third browser has three to report on, and a
+    // doctor that walked the constant would silently answer about two of them.
+    // A health report that is quietly partial is worse than one that is absent,
+    // because nothing in its output says which browsers it did not look at.
+    //
+    // Order is regular-then-private, each in configured order, which is the
+    // order `environment.ts` records and the order a person reading `.env`
+    // wrote them in.
+    const configuredBrowsers = [
+        ...environment.regularBrowsers,
+        ...environment.privateBrowsers,
+    ];
+    for (const browser of configuredBrowsers) {
+        checks.push(checkDiscoveryRecord(browser, probes.discovery?.[browser] ?? { recorded: false }));
+    }
+    checks.push(checkCaptureSurface(probes.captureSurface));
+    for (const browser of configuredBrowsers) {
+        checks.push(checkKeeperTab(browser, probes.keeperTabs?.[browser]));
+    }
+    // The sign-in check, for the one browser that has a profile to sign into.
+    // Not run for the private browser: its profile is ephemeral, so the
+    // question does not apply and an entry saying `unknown` about a browser
+    // that can never be signed in would read as a gap rather than as a
+    // non-question.
+    //
+    // **Whether a browser is running changes what a zero count means**, so the
+    // discovery probe's answer is passed through rather than re-derived. See
+    // `session.ts`: a live browser has not necessarily flushed its cookies.
+    const signInBrowser = SIGNABLE_BROWSER;
+    const discoveryProbe = probes.discovery?.[signInBrowser];
+    const browserRunning = discoveryProbe?.recorded === true && discoveryProbe.answered === true;
+    checks.push(checkSignInSession(signInBrowser, inspectProfileSession(environment.profileRoot, signInBrowser, {
+        ...(probes.cookieReader === undefined ? {} : { reader: probes.cookieReader }),
+        browserRunning,
+    })));
+    // **Whether a sign-in has been abandoned**, which is the one thing on this
+    // report that can be actively refusing every caller right now. Read from the
+    // store rather than probed, because the two facts it needs — the state and
+    // the owning process — are both rows.
+    //
+    // A store that is absent, or one written by a build older than the owner
+    // column, yields no row to classify; both come back as *not signing in*,
+    // which is the honest answer when there is nothing recorded to say
+    // otherwise.
+    checks.push(checkAbandonedSignIn(signInBrowser, classifySignIn(db === undefined ? undefined : readSignInOwner(db, signInBrowser), probes.processIsRunning)));
+    checks.push(checkTabBudget(storedBudget, probes.configuredTabBudget ?? null));
+    return {
+        checks,
+        exitCode: exitCodeFor(checks),
+        storeLocation: environment.databasePath,
+    };
+}
+/**
+ * Read each browser's discovery record out of the store, so the caller has
+ * something to probe.
+ *
+ * **This reads the record and does not check it.** §1.2c: the record is a
+ * claim, not a proof — it survives the browser it names. Turning these into
+ * probe results means reaching the endpoint, which needs a driver, which is
+ * the row that will supply {@link DoctorProbes.discovery}.
+ */
+export function readDiscoveryRecords(db) {
+    const rows = db.prepare('SELECT id, endpoint, browser_uuid FROM browsers').all();
+    const records = {};
+    for (const row of rows) {
+        records[row.id] = { endpoint: row.endpoint, browserUuid: row.browser_uuid };
+    }
+    return records;
+}
+/**
+ * Read the sign-in state and its owning process for one browser.
+ *
+ * **Tolerant of a store that predates the owner column**, because `doctor` is
+ * the command most likely to be pointed at an old installation — that is
+ * largely what it is for. A store without the column answers as though nothing
+ * is signing in, which is the honest reading: there is no record to conclude
+ * anything from.
+ */
+export function readSignInOwner(db, browser) {
+    try {
+        return db.prepare('SELECT state, signin_owner_pid FROM browsers WHERE id = ?').get(browser);
+    }
+    catch {
+        return undefined;
+    }
+}
+const SYMBOL = { ok: 'ok  ', failed: 'FAIL', unknown: '--  ' };
+/**
+ * The report as lines for a terminal.
+ *
+ * One line per precondition with its own status, then the failures repeated
+ * with what to do about them. **No summary verdict** — §4.4 is explicit that
+ * collapsing preconditions into one word is the thing this declines to do,
+ * and a "3 of 12 healthy" line at the bottom is that word with arithmetic.
+ * What the bottom carries instead is the exit code, which is the machine's
+ * answer and names which group failed.
+ */
+export function formatReport(report) {
+    const lines = [`store: ${report.storeLocation}`, ''];
+    for (const check of report.checks) {
+        lines.push(`[${SYMBOL[check.status] ?? '?   '}] ${check.title}`);
+        lines.push(`         ${check.detail}`);
+    }
+    const failures = report.checks.filter((check) => check.status === 'failed');
+    if (failures.length > 0) {
+        lines.push('', 'What to do:');
+        for (const failure of failures) {
+            lines.push(`  ${failure.id}: ${failure.remedy ?? 'No remedy recorded for this check.'}`);
+        }
+    }
+    const unknown = report.checks.filter((check) => check.status === 'unknown');
+    if (unknown.length > 0) {
+        lines.push('', 
+        // Said rather than left to be inferred: an unknown is not a failure and
+        // does not affect the exit code, and a reader who assumed otherwise
+        // would treat a fresh install as broken.
+        `${String(unknown.length)} precondition(s) could not be evaluated. That is not a failure — a check with nothing to examine has not found a fault — and none of them affects the exit code.`);
+    }
+    lines.push('', `exit code: ${String(report.exitCode)}`);
+    return lines;
+}

package/dist/src/doctor/session.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { profileDirectory } from "../browser/discovery.js";
+/**
+ * Whether the signed-in browser's profile **looks** signed in.
+ *
+ * ── The question, and why it is worth answering without a browser ───────
+ *
+ * A person signs in by hand exactly once (`SCHEMA.md` §5.5.1) and then has no
+ * way to confirm it took. Opening a browser to look is the obvious answer and
+ * is a bad one: `broker doctor` **reports and changes nothing**, and a check
+ * that launched a browser against the profile would be a check that could
+ * itself take the profile's lock — reporting a fault it had just caused, on
+ * an installation that was fine a moment earlier.
+ *
+ * So this reads files, and the whole design problem is that **the obvious
+ * observable does not work**.
+ *
+ * ── What was measured, because the obvious check always passes ──────────
+ *
+ * Two profiles were built with a real browser: one where nothing was ever
+ * visited, and one where a session cookie was set and the browser was closed
+ * cleanly. Then every candidate observable was compared.
+ *
+ * | Observable | Fresh profile | Signed-in profile | Distinguishes? |
+ * |---|---|---|---|
+ * | `Default/Network/Cookies` exists | **yes** | yes | **no** |
+ * | its size on disk | **20480 bytes** | 20480 bytes | **no** |
+ * | rows in its `cookies` table | **0** | **1** | **yes** |
+ *
+ * **The file is created on first run whether or not anything is stored in
+ * it.** So `existsSync` — the check anyone reaches for first, and the one this
+ * module would have shipped without the measurement — is a check that
+ * **cannot fail**. It would report every fresh install as signed in, which is
+ * the exact failure the house standard names: a check that claims what it
+ * cannot see. The size is no better, because SQLite allocates its pages up
+ * front.
+ *
+ * The row count is the observable that carries the fact, so it is the one
+ * this reads.
+ *
+ * ── The two things this deliberately does not claim ─────────────────────
+ *
+ * Both are reported as `unknown` with the reason rather than being guessed
+ * at, because an `unknown` that says why beats a confident wrong answer.
+ *
+ * 1. **A running browser has not necessarily written its cookies down.**
+ *    Measured: with the browser ended abruptly, the signed-in profile read
+ *    **zero rows** — identical to the fresh one. The store is flushed on a
+ *    clean shutdown, so a count taken while a browser is live is a count of
+ *    what has been flushed so far and not of what the session holds. Reading
+ *    zero in that state means *cannot tell yet*, never *not signed in*.
+ * 2. **Cookies are one carrier of a session, not the only one.** A site that
+ *    keeps its session in local storage or a token in IndexedDB leaves this
+ *    table empty while being perfectly signed in. So a positive result is
+ *    strong and a zero result is weak, and they are reported asymmetrically
+ *    for that reason.
+ *
+ * **This is positive-evidence-only, in exactly the way `profileLockLooksHeld`
+ * is**, and for the same reason: finding rows means a session was stored;
+ * finding none means no evidence was found, which is not the same as evidence
+ * of absence.
+ */
+/**
+ * Where a Chromium profile keeps its cookies.
+ *
+ * **Measured rather than assumed, and the obvious guess is wrong.** It is not
+ * `Default/Cookies` — that path does not exist in a profile this service
+ * creates. The store sits under the network directory, and a check pointed at
+ * the wrong path would report every profile as unreadable.
+ */
+export const COOKIE_STORE_RELATIVE = ['Default', 'Network', 'Cookies'];
+/**
+ * The real reader: opens the store **read-only** and counts.
+ *
+ * Read-only is not a precaution, it is the contract — `checks.ts` promises
+ * the doctor changes nothing, and a cookie store opened for writing can be
+ * migrated by the opening process. Opening a browser's own store read-write
+ * to ask a question would be able to damage the one thing this whole command
+ * exists to protect.
+ */
+export function realCookieStoreReader() {
+    return {
+        countCookies: (file) => {
+            try {
+                const db = new Database(file, { readonly: true, fileMustExist: true });
+                try {
+                    const row = db.prepare('SELECT COUNT(*) AS n FROM cookies').get();
+                    return { count: row?.n ?? 0 };
+                }
+                finally {
+                    db.close();
+                }
+            }
+            catch (error) {
+                return { error: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    };
+}
+/**
+ * Inspect one profile and say what the evidence supports.
+ *
+ * Every branch that cannot answer says so and says why. There is no branch
+ * that returns `no-session-found` on evidence that would also be produced by
+ * a signed-in profile.
+ */
+export function inspectProfileSession(profileRoot, browser, options = {}) {
+    const directory = profileDirectory(profileRoot, browser);
+    let profilePresent;
+    try {
+        profilePresent = fs.statSync(directory).isDirectory();
+    }
+    catch {
+        profilePresent = false;
+    }
+    if (!profilePresent) {
+        return {
+            evidence: 'no-profile',
+            reason: 'No profile directory. It is created by the setup handshake on the next spawn, and nobody has signed in against it.',
+        };
+    }
+    const store = path.join(directory, ...COOKIE_STORE_RELATIVE);
+    if (!fs.existsSync(store)) {
+        return {
+            evidence: 'no-session-found',
+            cookieCount: 0,
+            reason: 'The profile exists but the browser has never written a cookie store into it, so no browser has run against it yet.',
+        };
+    }
+    const reader = options.reader ?? realCookieStoreReader();
+    const outcome = reader.countCookies(store);
+    if ('error' in outcome) {
+        return {
+            evidence: 'undetermined',
+            reason: `The cookie store could not be read (${outcome.error}). A store held open by a running browser is the ordinary cause; nothing is concluded from a read that did not happen.`,
+        };
+    }
+    if (outcome.count > 0) {
+        return {
+            evidence: 'session-present',
+            cookieCount: outcome.count,
+        };
+    }
+    // Zero. The one branch where the honest answer depends on something else,
+    // because a live browser has not necessarily flushed yet — measured, and
+    // the reason this parameter exists.
+    if (options.browserRunning === true) {
+        return {
+            evidence: 'undetermined',
+            cookieCount: 0,
+            reason: 'The stored cookie count is zero and a browser is running against this profile. A browser writes its cookies down when it shuts down cleanly, so a zero read while one is live means the store has nothing flushed yet rather than that nobody is signed in. Close the browser and ask again.',
+        };
+    }
+    return {
+        evidence: 'no-session-found',
+        cookieCount: 0,
+        reason: 'The profile has a cookie store and it holds no cookies. That is what a profile nobody has signed into looks like — though a site that keeps its session only in local storage would look the same, so this is the absence of evidence rather than evidence of absence.',
+    };
+}

package/dist/src/errors.js

@@ -0,0 +1,36 @@
+/**
+ * The base every refusal in this service is thrown as.
+ *
+ * `SCHEMA.md` §7 is organised around refusals — "a rule that never refuses
+ * anything protects nothing, so the refusals are the specification" — and a
+ * refusal has to be distinguishable from a programming mistake at the point
+ * something decides what to print and what exit code to use. A thrown
+ * `TypeError` is a bug in this service; a thrown `BrokerError` is this
+ * service declining to run, and the difference is the whole of the entry
+ * point's error handling.
+ *
+ * Row #10 grows this into the rejection taxonomy every guard draws from.
+ * Row #3 ships only the base and the two refusals it actually has, because
+ * a taxonomy with no cases is a shape nobody has tested.
+ */
+export class BrokerError extends Error {
+    /**
+     * The rule that refused, spelled as `SCHEMA.md` §7 spells it — for
+     * example `store.not_on_network_filesystem`. Carried as data rather than
+     * baked into the message so a caller can branch on the rule without
+     * matching on English.
+     */
+    rule;
+    constructor(rule, message, options) {
+        super(message, options);
+        this.name = 'BrokerError';
+        this.rule = rule;
+    }
+}
+/** A refusal from §7.2 — checked on every spawn, and the service does not run. */
+export class StartupRefusal extends BrokerError {
+    constructor(rule, message, options) {
+        super(rule, message, options);
+        this.name = 'StartupRefusal';
+    }
+}

package/dist/src/feedback/read.js

@@ -0,0 +1,119 @@
+import { FEEDBACK_CATEGORY_NAMES, isFeedbackCategory, RATING_MAXIMUM, RATING_MINIMUM, } from "./record.js";
+export const DEFAULT_LIMIT = 50;
+/**
+ * Check the filters a person typed.
+ *
+ * A filter naming a category that does not exist would silently return no
+ * rows, and **no rows is the reading this whole mechanism's exit condition
+ * turns on** — silence means "nothing to report". A typo that produced
+ * silence would be read as the success condition, so it is refused with the
+ * list instead.
+ */
+export function refuseFilters(filters) {
+    if (filters.rating !== undefined) {
+        const { rating } = filters;
+        if (typeof rating !== 'number' ||
+            !Number.isInteger(rating) ||
+            rating < RATING_MINIMUM ||
+            rating > RATING_MAXIMUM) {
+            return {
+                code: 'rating_out_of_range',
+                message: `--rating takes a whole number from ${String(RATING_MINIMUM)} to ${String(RATING_MAXIMUM)}.`,
+            };
+        }
+    }
+    if (filters.category !== undefined) {
+        const { category } = filters;
+        if (typeof category !== 'string' || !isFeedbackCategory(category)) {
+            return {
+                code: 'unknown_category',
+                message: `--category takes one of these five: ${FEEDBACK_CATEGORY_NAMES.join(', ')}. An unrecognised one is refused rather than matching nothing, because no rows is also what "nothing to report" looks like.`,
+            };
+        }
+    }
+    if (filters.limit !== undefined) {
+        const { limit } = filters;
+        if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1) {
+            return { code: 'bad_limit', message: '--limit takes a whole number of at least 1.' };
+        }
+    }
+    return undefined;
+}
+/**
+ * Read the rows back, **most recent first**.
+ *
+ * Ordered by the counter rather than by the timestamp: two rows written in
+ * the same second are ordered by the counter and are not ordered by the
+ * clock, so "most recent first" is a claim about order that only the counter
+ * can actually make.
+ */
+export function readFeedback(db, filters = {}) {
+    const where = [];
+    const parameters = [];
+    if (filters.rating !== undefined) {
+        where.push('rating = ?');
+        parameters.push(filters.rating);
+    }
+    if (filters.category !== undefined) {
+        where.push('category = ?');
+        parameters.push(filters.category);
+    }
+    const clause = where.length === 0 ? '' : ` WHERE ${where.join(' AND ')}`;
+    parameters.push(filters.limit ?? DEFAULT_LIMIT);
+    const rows = db
+        .prepare(`SELECT id, at, session_id, claim_id, last_event_id, last_guard, rating, category, note
+       FROM feedback${clause}
+       ORDER BY id DESC
+       LIMIT ?`)
+        .all(...parameters);
+    return rows.map((row) => ({
+        id: row.id,
+        at: row.at,
+        sessionId: row.session_id,
+        claimId: row.claim_id,
+        lastEventId: row.last_event_id,
+        lastGuard: row.last_guard,
+        rating: row.rating,
+        category: row.category,
+        note: row.note,
+    }));
+}
+/**
+ * Render the rows for a terminal.
+ *
+ * **Silence is reported as silence, in words.** An empty reading is the exit
+ * condition this mechanism is built around, so it says so rather than
+ * printing nothing — a blank screen reads as a broken command, and the one
+ * reading that must not be mistaken for a malfunction is the one that means
+ * the tool has done its job.
+ */
+export function renderFeedback(rows, filtered) {
+    if (rows.length === 0) {
+        return filtered
+            ? 'No feedback matches those filters.'
+            : [
+                'No feedback has been recorded.',
+                '',
+                'This tool is v0 scaffolding and silence is its success condition: a long',
+                'stretch with nothing logged is the signal to remove it. Removing it is a',
+                'deletion — the tool, the command, this reader, the writer and the table.',
+            ].join('\n');
+    }
+    return rows
+        .map((row) => {
+        const context = [
+            row.sessionId === null ? undefined : `session ${row.sessionId}`,
+            row.claimId === null ? undefined : `lease ${row.claimId}`,
+            row.lastEventId === null ? undefined : `last operation #${String(row.lastEventId)}`,
+            row.lastGuard === null ? undefined : `refused by ${row.lastGuard}`,
+        ].filter((part) => part !== undefined);
+        return [
+            `#${String(row.id)}  ${row.at}  ${String(row.rating)}/5  ${row.category}`,
+            context.length === 0
+                ? '  (no context was captured — no lease and no prior event)'
+                : `  ${context.join(' · ')}`,
+            `  ${row.note}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+}

package/dist/src/feedback/record.js

@@ -0,0 +1,199 @@
+import { immediate } from "../store/transaction.js";
+/**
+ * `browser_feedback` — the tenth tool's write, and the one built to be
+ * removed.
+ *
+ * ── ITS EXIT CONDITION, WRITTEN DOWN, BECAUSE THAT IS PART OF THE ROW ────
+ *
+ * **This is v0 scaffolding. The signal to remove it is a long stretch in
+ * which nothing is logged** (`SCHEMA.md` §3.16). Silence is the success
+ * condition, not a failure to collect: once callers have stopped finding
+ * things to report, a channel for reporting them has nothing left to carry
+ * and it goes.
+ *
+ * Three consequences the implementation has to honour, and does:
+ *
+ * 1. **No migration story is owed.** Nothing later is expected to read these
+ *    rows, so this table does not have to be one anybody would want to keep.
+ * 2. **It does not have to be beautiful.** Trivially callable, trivially
+ *    readable, and nothing else. That is why this file is short and why there
+ *    is no abstraction over it.
+ * 3. **Removing it stays a DELETION, not an extraction.** Nothing else reads
+ *    this table, no operation depends on a row existing, and no refusal
+ *    changes shape when it goes. **Whoever removes this deletes this file,
+ *    the reader beside it, the tool, the command and the table — and nothing
+ *    else moves.** That property is worth protecting deliberately as the rest
+ *    of the service grows, so: do not join anything to this table, and do not
+ *    make any operation's behaviour depend on a row in it.
+ *
+ * It is its own table rather than an event kind precisely to keep that true
+ * (§3.16): the ledger records what the service *did*, this records what a
+ * caller *thought*, and folding it in would make every count over `events`
+ * start by excluding a kind that is not an event.
+ *
+ * ── It is local, and it has no route out ────────────────────────────────
+ *
+ * The store is the installation's own file. **There is no outbound path in
+ * this module and there must never be one.** Nothing else in this design
+ * opens an outbound connection and nothing listens, so a feedback channel
+ * that transmitted would be the only component with a reason to reach the
+ * network — carrying prose written by a caller about a page it was looking
+ * at, next to a lease identifier and a session identity. The consequence is
+ * accepted: feedback is per-installation and read by somebody with access to
+ * the machine.
+ */
+/**
+ * The five categories, and the reason the set is exactly this.
+ *
+ * **Small, fixed, disjoint, and one of them is positive.** A category list
+ * with no positive value collects only complaints, and a channel that can
+ * only ever report problems produces a picture in which nothing works. The
+ * exit condition above depends on being able to tell *nothing to report*
+ * apart from *nobody bothered*, and `worked-well` is the entry that makes
+ * that distinction possible.
+ *
+ * Two categories that overlap get chosen by coin-flip and their counts mean
+ * nothing, which is why these are disjoint rather than merely different.
+ */
+export const FEEDBACK_CATEGORIES = {
+    'refusal-unclear': 'The service refused, and the message did not say what to do next',
+    'no-path': 'The task could not be accomplished at all with the tools available',
+    'worked-around': 'The caller got there, but by an awkward or indirect route',
+    'surprised-me': 'It worked — but not the way the caller expected',
+    'worked-well': 'Positive. Something helped, and it is worth knowing which thing',
+};
+/** Every category, in a stable order. */
+export const FEEDBACK_CATEGORY_NAMES = Object.keys(FEEDBACK_CATEGORIES);
+export function isFeedbackCategory(value) {
+    return Object.prototype.hasOwnProperty.call(FEEDBACK_CATEGORIES, value);
+}
+/**
+ * The rating scale, with both ends and the middle written out.
+ *
+ * **An unanchored scale is used differently by every caller and produces
+ * numbers that cannot be compared** — which defeats the only reason to have a
+ * number at all. So the anchors live here, in code, and are what the tool
+ * description and the reader both quote.
+ *
+ * **The axis is not satisfaction.** It is not whether the caller liked the
+ * service. It is whether the service moved the caller's actual work forward
+ * or got in its way.
+ */
+export const RATING_ANCHORS = {
+    1: 'It stalled the work — could not do what it came to do, or spent more effort working around this service than on the task',
+    2: 'Substantial friction — the work got done, but the detour was a significant part of the effort',
+    3: 'Neutral — neither sped the work up nor got in its way',
+    4: 'It helped — the work went faster, with a rough edge worth mentioning',
+    5: 'It made the work faster — got where it was going quicker than by any other available route',
+};
+export const RATING_MINIMUM = 1;
+export const RATING_MAXIMUM = 5;
+/**
+ * The note's bounds. **The floor is deliberate** — twenty characters is
+ * roughly the shortest useful sentence, and it stops a reflexive one-word row.
+ */
+export const NOTE_MINIMUM = 20;
+export const NOTE_MAXIMUM = 2000;
+/**
+ * Read the three auto-captured columns from what the store already knows.
+ *
+ * **The caller's last operation is read from the ledger**, so it names what
+ * was actually attempted rather than what the caller remembers attempting —
+ * and `last_guard` comes off that same row rather than being asked for, so
+ * the refusal recorded is the refusal that happened.
+ *
+ * Resolution order, and it matters: a lease key identifies one claim exactly,
+ * so it is preferred. Failing that, a session identity finds that session's
+ * most recent event. Failing both, the row carries prose and a rating and
+ * nothing else, which is still a row worth having — a caller whose very first
+ * call was refused before any lease existed is exactly the population §3.16
+ * exists to hear from.
+ */
+export function captureContext(db, submission) {
+    let claimId = null;
+    if (submission.leaseKeyHash !== undefined) {
+        // Looked up by hash, because the key itself is never stored (§1.4).
+        const claim = db
+            .prepare('SELECT id FROM claims WHERE key_hash = ? ORDER BY created_at DESC LIMIT 1')
+            .get(submission.leaseKeyHash);
+        claimId = claim?.id ?? null;
+    }
+    // The most recent event this caller produced. Ordered by the ledger's own
+    // counter rather than by its timestamp: two rows written in the same second
+    // are ordered by the counter and are not ordered by the clock, and "the
+    // caller's LAST operation" is a claim about order.
+    const lastEvent = (claimId !== null
+        ? db
+            .prepare('SELECT id, guard FROM events WHERE claim_id = ? ORDER BY id DESC LIMIT 1')
+            .get(claimId)
+        : submission.sessionId !== undefined
+            ? db
+                .prepare('SELECT id, guard FROM events WHERE session_id = ? ORDER BY id DESC LIMIT 1')
+                .get(submission.sessionId)
+            : undefined);
+    return {
+        claimId,
+        lastEventId: lastEvent?.id ?? null,
+        // Null when the last event was an allow: `guard` is null on an allow by
+        // the table's own constraint, so this carries "the refusal it hit" and
+        // not "the last rule that happened to be mentioned".
+        lastGuard: lastEvent?.guard ?? null,
+    };
+}
+/**
+ * Check a submission, returning the refusal or nothing.
+ *
+ * Every refusal names the way forward (§3.14) — which matters more here than
+ * anywhere, because this is the tool whose whole purpose is learning that a
+ * refusal failed to guide. A refusal from *this* tool that did not guide
+ * would be the one nobody could report.
+ */
+export function refuseSubmission(submission) {
+    const { rating } = submission;
+    if (typeof rating !== 'number' ||
+        !Number.isInteger(rating) ||
+        rating < RATING_MINIMUM ||
+        rating > RATING_MAXIMUM) {
+        return {
+            code: 'rating_out_of_range',
+            rule: 'feedback.rating_in_scale',
+            message: `The rating is a whole number from ${String(RATING_MINIMUM)} to ${String(RATING_MAXIMUM)}, on a help-versus-hinder axis rather than a satisfaction one. ${RATING_MINIMUM}: ${RATING_ANCHORS[RATING_MINIMUM] ?? ''}. 3: ${RATING_ANCHORS[3] ?? ''}. ${RATING_MAXIMUM}: ${RATING_ANCHORS[RATING_MAXIMUM] ?? ''}.`,
+        };
+    }
+    const { category } = submission;
+    if (typeof category !== 'string' || !isFeedbackCategory(category)) {
+        // Refused with the full list (§3.16), because a caller that guessed wrong
+        // cannot guess better without seeing the set.
+        return {
+            code: 'unknown_category',
+            rule: 'feedback.category_known',
+            message: `The category is one of these five: ${FEEDBACK_CATEGORY_NAMES.map((name) => `${name} (${FEEDBACK_CATEGORIES[name]})`).join('; ')}.`,
+        };
+    }
+    const { note } = submission;
+    if (typeof note !== 'string' || note.length < NOTE_MINIMUM || note.length > NOTE_MAXIMUM) {
+        return {
+            code: 'note_out_of_bounds',
+            rule: 'feedback.note_bounded',
+            message: `The note is ${String(NOTE_MINIMUM)} to ${String(NOTE_MAXIMUM)} characters. Say what you were trying to achieve, what you expected to happen, and what you did instead. Do not supply the lease id, the operation or the rule that refused — all three are captured for you.`,
+        };
+    }
+    return undefined;
+}
+/**
+ * Write one feedback row.
+ *
+ * **Nothing about it is rate-limited or gated** (§3.16). It writes a row and
+ * returns. The worst case is a noisy caller writing many rows into a table
+ * nothing depends on, in a store that gets deleted when the tool does.
+ */
+export async function recordFeedback(db, submission) {
+    return immediate(db, (scope) => {
+        const captured = captureContext(scope.db, submission);
+        const inserted = scope.db
+            .prepare(`INSERT INTO feedback (session_id, claim_id, last_event_id, last_guard, rating, category, note)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(submission.sessionId ?? null, captured.claimId, captured.lastEventId, captured.lastGuard, submission.rating, submission.category, submission.note);
+        return { value: { id: Number(inserted.lastInsertRowid), captured } };
+    });
+}