browser-broker 0.1.0

package/dist/src/store/schema/step-010-signin-request.js

@@ -0,0 +1,135 @@
+/**
+ * Step ten: a sign-in can be **asked for by a caller**, and one asked for
+ * that way has a deadline and a lease behind it.
+ *
+ * ── The gap this closes, stated as the thing that happened ──────────────
+ *
+ * §1.2 records **25 sessions that hand-seeded authentication tokens into an
+ * isolated browser while the signed-in browser sat unused**. That measurement
+ * is usually read as a browser-choice problem, and `DECISIONS.md` §13i reads
+ * it that way when it makes `browser` optional. **It has a second half.** A
+ * caller that picked the right browser and still landed on a login page had
+ * no call available to it that asks a person to sign in: `broker login` is a
+ * command a person types, and the ten tools contain nothing that moves a
+ * browser into `signing-in`. So the only moves left to such a caller were to
+ * abandon the task or to fabricate a session — and fabricating a session is
+ * precisely what those 25 sessions did.
+ *
+ * ── Why the existing two columns do not cover this ──────────────────────
+ *
+ * Step eight added `signin_owner_pid` so that a sign-in whose *command*
+ * died is recoverable. That column answers **"is the person's command still
+ * running"**, and it is exactly right for `broker login`, where a person is
+ * sitting in front of a process that stays up for the duration.
+ *
+ * **A requested sign-in has no such process.** The caller that asked is a
+ * connected session which returns from the call immediately and goes back to
+ * polling; nothing on the machine is blocked on the person, so there is no
+ * identifier whose death means *nobody is signing in any more*. Recording the
+ * requesting service's own identifier would be worse than recording nothing,
+ * because that process stays alive for the whole session: the row would look
+ * permanently live, and the recovery step eight exists to provide would never
+ * fire for the one path that most needs it.
+ *
+ * So the two ways in are recorded differently on purpose, and the columns are
+ * separate rather than one column meaning two things:
+ *
+ * | Began by | Held by | Ends when |
+ * |---|---|---|
+ * | `broker login` | a process (`signin_owner_pid`) | the person closes the window, or the process dies |
+ * | a caller asking | a deadline (`signin_deadline`) and the asking lease (`signin_claim_id`) | the person confirms, or the deadline passes |
+ *
+ * ── Why a deadline at all, when §5.5.1 says a sign-in has no expiry ─────
+ *
+ * §5.5.1's *"a person takes as long as they take"* is a statement about a
+ * person **who is already at the keyboard**, and it is right for the command:
+ * a timeout there would end a sign-in that was going fine while somebody was
+ * halfway through a password, and the process holding it is evidence enough
+ * that somebody is still there.
+ *
+ * A requested sign-in has no such evidence, and the failure it makes possible
+ * is new. The request is relayed by an agent to a person **who may not be at
+ * the keyboard at all** — who may not read the message for an hour, or ever.
+ * Left unbounded, one such request holds the browser in `signing-in` against
+ * every other caller indefinitely, which is the same unrecoverable state step
+ * eight was written to remove, arriving through a door step eight cannot
+ * watch. **The deadline is the evidence-substitute**: no process to ask about,
+ * so a number instead.
+ *
+ * ── Why the deadline is a stored column rather than a computed one ──────
+ *
+ * §1.12's rule is that a value is stored when it cannot be derived from what
+ * is already there. `browsers.updated_at` moves on every write to the row, so
+ * *"when did this sign-in start"* is not recoverable from it after any other
+ * update, and a deadline computed from a moving column is a deadline that
+ * moves. The alternative — reading the last `browser_signin_began` ledger row
+ * — makes an operational decision depend on scanning an append-only log whose
+ * whole design is that it is written and never read back for control flow
+ * (§1.6). So the moment is written down once, at the instant it is decided.
+ *
+ * ── Why the asking lease is recorded ────────────────────────────────────
+ *
+ * Two reasons, and the second is the load-bearing one.
+ *
+ * 1. **So the requester is not refused by its own request.** §5.5.1's first
+ *    step refuses a sign-in while any live lease holds a tab on that browser,
+ *    and the requesting caller *is* such a lease — it is holding the very tab
+ *    sitting on the login page. Without knowing which lease asked, the
+ *    operation cannot tell the caller it is serving from the callers it is
+ *    protecting, and the request refuses itself every time.
+ * 2. **So the exemption is exactly one lease wide.** Recording the identifier
+ *    means the refusal still fires for every *other* live lease, which is the
+ *    property §5.5.1 calls "why signing in is a service operation": a person
+ *    driving a window by hand underneath somebody else's work corrupts it.
+ *    An exemption expressed as a flag — *"this sign-in was requested, so skip
+ *    the check"* — would be an exemption for all of them.
+ *
+ * ── Nullable, because the older path sets neither ───────────────────────
+ *
+ * Both columns are null for a `broker login` sign-in, and that is the shape
+ * rather than a gap: a null deadline means **this sign-in is held by a
+ * process, ask step eight's column about it**. The two are not made mutually
+ * exclusive by a check constraint, and the reason is worth recording rather
+ * than being discovered as an omission: a constraint spanning them would
+ * have to be rebuilt to change, and the invariant it would express — that a
+ * sign-in has exactly one kind of owner — is one the operations enforce by
+ * refusing a second sign-in at all. There is no path that writes both.
+ *
+ * ── A new step, and no rebuild ──────────────────────────────────────────
+ *
+ * Two `ALTER TABLE ... ADD COLUMN` statements, which SQLite performs in place.
+ * Step nine had to rebuild because it dropped a check; nothing here changes a
+ * constraint, so nothing here needs the table copied. Adding a step rather
+ * than editing step nine is the rule in `steps.ts`: a step that has run
+ * somewhere is history.
+ */
+const ADDITIONS = [
+    // When this sign-in stops being somebody's and starts being nobody's.
+    // ISO-8601 in the same spelling every other instant in this store uses, so
+    // the comparison against `strftime('%Y-%m-%dT%H:%M:%fZ', 'now')` that the
+    // sweep already runs against `claims.expires_at` compares like with like.
+    `ALTER TABLE browsers ADD COLUMN signin_deadline TEXT`,
+    // Which lease asked. **Deliberately not a foreign key**, and this is the one
+    // decision in the step that is not obvious.
+    //
+    // `claims` rows are never deleted — a lease ends by moving to a terminal
+    // state (§2.2) — so a reference would not dangle. What a foreign key would
+    // do is make the *order* of two writes load-bearing: clearing this column
+    // and ending the claim would have to happen in an order the constraint
+    // permits, on a path whose whole job is to run during a sweep that is
+    // already updating claims. The column is read for exactly one comparison —
+    // is this the lease that asked — and a value naming a claim absent from the
+    // table gives that comparison the same answer as a null would.
+    `ALTER TABLE browsers ADD COLUMN signin_claim_id TEXT`,
+];
+/** Every statement this step runs, in order. */
+export const STEP_TEN_SQL = ADDITIONS;
+export const stepTen = {
+    version: 10,
+    summary: 'A sign-in can be requested by a caller: a deadline and the asking lease (§5.5.2, DECISIONS.md §13j).',
+    apply: (db) => {
+        for (const statement of STEP_TEN_SQL) {
+            db.exec(statement);
+        }
+    },
+};

package/dist/src/store/schema/step.js

@@ -0,0 +1,172 @@
+import { StartupRefusal } from "../../errors.js";
+import { immediate } from "../transaction.js";
+import { EXPECTED_VERSION, STEPS } from "./steps.js";
+/**
+ * Step a store from whatever version it is at to the version this build
+ * expects.
+ *
+ * `SCHEMA.md` §1.2d: the schema is a version stepper the service applies to
+ * its own store **on every spawn**, rather than a migration tool somebody
+ * runs as a deployment step. There is no deployment moment at which "run the
+ * migrations" could be a separate act: a caller that has just upgraded and a
+ * caller that has not may both spawn within the same minute, so the check
+ * belongs on every spawn or it belongs nowhere. A store already at the right
+ * version is left untouched.
+ *
+ * The steps between the two versions are applied **in order, in one
+ * transaction**.
+ */
+/**
+ * `startup.schema_stepped` (§7.2): **a store at a version this build does not
+ * understand is a refusal, not an attempted downgrade.** Two callers on
+ * different builds against one store is an ordinary situation here, and
+ * guessing is how one of them corrupts it.
+ *
+ * This refusal lands before any step exists, deliberately. A stepper that
+ * only knows how to step *up* is the one somebody later extends with a
+ * well-meaning downgrade path; landing the refusal first makes that a change
+ * to existing behaviour rather than a gap somebody fills.
+ */
+export function readStoreVersion(db) {
+    const row = db.pragma('user_version', { simple: true });
+    return typeof row === 'number' ? row : 0;
+}
+export async function stepSchema(db, steps = STEPS, expected = EXPECTED_VERSION) {
+    // ── The version is read OUTSIDE the transaction only to decide whether to
+    //    open one, and is read AGAIN INSIDE it before anything is applied ────
+    //
+    // **This read decides nothing on its own.** It exists so that the ordinary
+    // case — a store already at the right version, which is every spawn after
+    // the first — costs a pragma rather than a transaction. Every decision that
+    // matters is taken again below, inside the transaction, against a version
+    // re-read there.
+    //
+    // A reader tempted to trust this value and delete the re-read should know
+    // what that costs: it is the defect this function was changed to fix.
+    const observed = readStoreVersion(db);
+    if (observed > expected) {
+        throw new StartupRefusal('startup.schema_stepped', `The store is at schema version ${String(observed)} and this build understands version ${String(expected)}. A store newer than the build is refused rather than downgraded: two callers on different builds against one store is ordinary here, and guessing is how one of them corrupts it. Upgrade this installation.`);
+    }
+    if (observed === expected) {
+        return { from: observed, to: expected, applied: [] };
+    }
+    // ── Foreign keys are suspended for the duration of the steps ────────────
+    //
+    // **This is SQLite's documented table-rebuild procedure, and it is required
+    // rather than convenient.** A step that changes a check constraint cannot
+    // alter it in place: the table has to be rebuilt, which means dropping a
+    // table that another table references — and that violates the reference
+    // *even when the rebuild is going to restore every row*.
+    //
+    // The failure this prevents is total and was reproduced on this path before
+    // the guard existed: `feedback.last_event_id` references `events (id)`, so
+    // rebuilding `events` failed with a foreign-key violation on **any store
+    // that had feedback naming an event**. `prepareStore` rethrows and there is
+    // no long-lived process, so every spawn failed — an installation
+    // permanently unable to start, and specifically the installations used
+    // enough to have collected feedback.
+    //
+    // **Why it is here rather than at the four call sites.** The pragma is a
+    // **no-op inside a transaction** — SQLite silently ignores it and it reads
+    // back unchanged — so it has to be set before `BEGIN`, which is inside this
+    // function. Putting it in the callers would mean four places to get right
+    // and a fifth caller that misses it; this function owns the transaction, so
+    // it owns the pragma that has to wrap it.
+    //
+    // **What is given up, stated plainly:** during the steps the database does
+    // not enforce references, so a step that orphaned a row would not be caught
+    // as it ran. That is why the integrity check below is not optional — it is
+    // the enforcement, re-applied in one pass before the version is stamped.
+    const foreignKeysWereOn = db.pragma('foreign_keys', { simple: true }) === 1;
+    if (foreignKeysWereOn) {
+        db.pragma('foreign_keys = OFF');
+    }
+    try {
+        // **Awaited, not returned.** `immediate` is asynchronous, so returning its
+        // promise would run the `finally` below — restoring the pragma — before
+        // the transaction had even begun, which puts enforcement back on for the
+        // rebuild it was suspended for. The await is what makes the restore
+        // happen after the steps rather than during them.
+        return await immediate(db, () => {
+            // ══════════════════════════════════════════════════════════════════
+            // THE VERSION IS READ AGAIN HERE, AND THIS READ IS THE ONE THAT COUNTS
+            // ══════════════════════════════════════════════════════════════════
+            //
+            // **The hazard this closes.** Reading the version once, outside the
+            // transaction, and deriving the steps from it lets two processes spawning
+            // simultaneously against an empty store both read zero, both decide step
+            // one is pending, and the loser run a `CREATE TABLE` the winner has
+            // already committed — `table browsers already exists`.
+            //
+            // That is not an exotic race here. The service is **spawned per session
+            // and exits with it**, so two callers starting at once is the ordinary
+            // case, and it is exactly what a fresh install hits: the first two
+            // agents to reach for a browser on a machine that has never run this.
+            //
+            // **Why re-reading inside is sufficient.** `immediate` issues
+            // `BEGIN IMMEDIATE`, which declares intent to write at the moment it
+            // opens, so the store serialises the two writers itself rather than
+            // letting both proceed and discovering the conflict at the end (§1.0a).
+            // The loser therefore does not enter this callback until the winner has
+            // committed, and the version it reads here is the version the winner
+            // stamped. It finds nothing pending and applies nothing.
+            //
+            // This is the same read-then-write window every arbitration path closes
+            // the same way. The stepper is not an arbitration path, but it has the
+            // identical shape of problem and takes the identical answer.
+            const from = readStoreVersion(db);
+            // The winner of the race stamped the expected version while this
+            // process waited to enter. §1.2d's promise — a store already at the
+            // right version is left untouched — now holds for the first two spawns
+            // as well as for every later one.
+            if (from === expected) {
+                return { value: { from, to: expected, applied: [] } };
+            }
+            // Re-checked inside as well, and not merely for symmetry: between the
+            // read above and this one another process may have stepped the store
+            // **past** what this build understands. Refusing here rather than
+            // stepping onto a store a newer build owns is the same refusal §7.2
+            // makes outside, applied to the version that is actually current.
+            if (from > expected) {
+                throw new StartupRefusal('startup.schema_stepped', `The store is at schema version ${String(from)} and this build understands version ${String(expected)}. A store newer than the build is refused rather than downgraded: two callers on different builds against one store is ordinary here, and guessing is how one of them corrupts it. Upgrade this installation.`);
+            }
+            // Derived from the version read **inside** the transaction, so the
+            // steps applied are the ones actually still pending rather than the
+            // ones that were pending when this process first looked.
+            const pending = steps
+                .filter((step) => step.version > from)
+                .sort((a, b) => a.version - b.version);
+            const applied = [];
+            for (const step of pending) {
+                step.apply(db);
+                applied.push(step.version);
+            }
+            // **The enforcement that was suspended, re-applied as a check before
+            // anything is committed.** `foreign_key_check` reports every row whose
+            // reference does not resolve, and it is read *inside* the transaction
+            // so a step that broke a reference rolls back rather than committing a
+            // store whose integrity nothing will re-examine.
+            //
+            // This is the assertion that makes suspending the pragma safe rather
+            // than merely quiet: without it, turning enforcement off would trade a
+            // loud failure for a silent one.
+            const violations = db.pragma('foreign_key_check');
+            if (violations.length > 0) {
+                throw new StartupRefusal('startup.schema_stepped', `Stepping the schema from version ${String(from)} to ${String(expected)} left ${String(violations.length)} row(s) naming something that does not exist. The store has been left at version ${String(from)} rather than committed in that state.`);
+            }
+            // `user_version` takes no parameter binding, and the value is a number
+            // this module computed rather than anything a caller supplied.
+            db.pragma(`user_version = ${String(expected)}`);
+            return { value: { from, to: expected, applied } };
+        });
+    }
+    finally {
+        // Restored on the way out whatever happened, including a step that threw:
+        // a caller that opened the store with references enforced gets a handle
+        // with them enforced, and a failed upgrade does not silently leave the
+        // connection weaker than the caller asked for.
+        if (foreignKeysWereOn) {
+            db.pragma('foreign_keys = ON');
+        }
+    }
+}

package/dist/src/store/schema/steps.js

@@ -0,0 +1,58 @@
+import { stepOne } from "./step-001-initial.js";
+import { stepEight } from "./step-008-signin-owner.js";
+import { stepFive } from "./step-005-storage-seed-event.js";
+import { stepNine } from "./step-009-named-browsers.js";
+import { stepSix } from "./step-006-signin-events.js";
+import { stepTen } from "./step-010-signin-request.js";
+import { stepSeven } from "./step-007-signin-without-process.js";
+import { stepFour } from "./step-004-tab-never-opened.js";
+import { stepThree } from "./step-003-queue-order.js";
+import { stepTwo } from "./step-002-tab-budget.js";
+export const STEPS = [
+    stepOne,
+    stepTwo,
+    stepThree,
+    stepFour,
+    stepFive,
+    stepSix,
+    stepSeven,
+    stepEight,
+    stepNine,
+    stepTen,
+];
+/**
+ * The version a store must be at for this build to use it.
+ *
+ * **Stamped, not counted.** A store's version is written into the file and is
+ * then compared against by every later build, so it is a fact about what has
+ * been applied rather than a fact about this array's shape. Deriving it from
+ * the length couples the two: a step deleted or a placeholder appended by
+ * somebody who has not read the rule above moves the number every installed
+ * store is compared against, and the refusal that protects a store from a
+ * build it does not understand starts firing — or stops firing — for a reason
+ * nobody wrote down.
+ *
+ * So the number is written here and the check below is what keeps it honest.
+ */
+export const EXPECTED_VERSION = 10;
+/**
+ * The list is consistent with the version above, asserted where the list is
+ * defined rather than in a test.
+ *
+ * A test would prove this on a machine running the tests. This proves it on
+ * every spawn, which is the only moment that matters for a store somebody is
+ * about to open — and it is the moment the mistake is cheapest to see, because
+ * nothing has been written yet.
+ */
+function assertStepsAreWellFormed(steps, expected) {
+    steps.forEach((step, index) => {
+        if (step.version !== index + 1) {
+            throw new Error(`Schema step ${String(index + 1)} declares version ${String(step.version)}. Steps are one-based and contiguous, in order, and a version is never reused.`);
+        }
+    });
+    const last = steps.at(-1)?.version ?? 0;
+    if (last !== expected) {
+        throw new Error(`The last schema step is version ${String(last)} and this build expects version ${String(expected)}. A step was added without stamping the version, or the version was stamped without the step.`);
+    }
+}
+assertStepsAreWellFormed(STEPS, EXPECTED_VERSION);

package/dist/src/store/transaction.js

@@ -0,0 +1,37 @@
+/**
+ * The statement that opens the transaction. Exported so a test can assert the
+ * mode by naming the literal rather than by trusting this comment.
+ */
+export const BEGIN_STATEMENT = 'BEGIN IMMEDIATE';
+/**
+ * Run `fn` inside an immediate transaction: commit on success, roll back and
+ * rethrow on a throw.
+ *
+ * After-commit actions run once the transaction has ended, and a failure in
+ * one does not undo the commit — the work is done and the store says so. They
+ * are best effort by design (§2.4b), not by oversight.
+ */
+export async function immediate(db, fn) {
+    db.prepare(BEGIN_STATEMENT).run();
+    let result;
+    try {
+        result = await fn({ db });
+    }
+    catch (error) {
+        // Rolling back is the point of this branch: the caller must not be able
+        // to leave a partial write behind by throwing.
+        db.prepare('ROLLBACK').run();
+        throw error;
+    }
+    db.prepare('COMMIT').run();
+    for (const action of result.afterCommit ?? []) {
+        try {
+            await action();
+        }
+        catch {
+            // Best effort, outside the transaction, after the commit. A tab that
+            // will not close is not a reason to report failed work that succeeded.
+        }
+    }
+    return result.value;
+}

package/dist/src/tool/adapter.js

@@ -0,0 +1,90 @@
+import { TOOLS_BY_NAME, TOOL_OPERATIONS } from "./tools.js";
+/**
+ * The tool surface as an adapter: a thin shell over one service call.
+ *
+ * ── This is the primary route ───────────────────────────────────────────
+ *
+ * `MILESTONES.md` #27: the service is **spawned by its caller**, serves that
+ * session, and exits with it. No port, no daemon, no container. This is the
+ * route real callers use, and the command line exists mainly as the second
+ * route that makes the parity claim assertable (§5.1).
+ *
+ * ── What this file may and may not do ───────────────────────────────────
+ *
+ * It resolves a tool call into arguments, calls **one** service operation,
+ * and shapes the outcome for the wire. It reaches no database and no guard:
+ * it is handed a {@link BrokerService} rather than finding one, so there is no
+ * store handle in scope to be tempted by. Every rule that decides whether an
+ * operation is allowed lives behind that seam, or it holds on this route and
+ * not the others (`CLAUDE.md`).
+ *
+ * **Stated honestly, because the seam cannot enforce it:** nothing structural
+ * stops a future edit adding a check here. `db.import_isolated` (§7.3) is a
+ * build rule precisely because a type cannot express "and you did not
+ * reimplement this". What this file does is keep the correct path the easy
+ * one — one call in, one outcome out, no branch between them that could
+ * decide anything.
+ */
+/**
+ * Every operation this route offers — all ten, from the tool table.
+ *
+ * Read from the table rather than written out again, so the tools a caller
+ * can see and the operations the parity suite drives cannot drift.
+ */
+export const TOOL_SURFACE_OPERATIONS = TOOL_OPERATIONS;
+/**
+ * Operations this route does not offer, with the reason each is absent.
+ *
+ * **Empty, and that is the claim.** §3.1 lists twelve tools and §5.3 lists twelve
+ * commands for them, so every operation is on both routes. The array exists
+ * so that a later row removing a tool has somewhere to write down why — and
+ * so the runner's waiver rule has something to check rather than an absence
+ * to interpret.
+ *
+ * Note what a waiver could *not* buy here: this route declares `readOnly:
+ * false`, and the runner refuses a write waiver from a route that is not
+ * read-only. Declaring it read-only to buy waivers would be the loophole, so
+ * the declaration is made honestly.
+ */
+export const TOOL_OPERATION_WAIVERS = [];
+/**
+ * The tool-surface adapter.
+ *
+ * Its `id` is `tool-stdio`, which is also the value §1.6 names for the
+ * ledger's `adapter` column — the column that turns "the same rules apply on
+ * every route" from a claim into a query. One spelling, used by the registry,
+ * the ledger and the conformance report alike.
+ */
+export const toolStdioAdapter = {
+    id: 'tool-stdio',
+    description: 'The tool surface over standard input and output. Spawned by its caller, serves that session, exits with it.',
+    readOnly: false,
+    operations: TOOL_SURFACE_OPERATIONS,
+    waivers: TOOL_OPERATION_WAIVERS,
+    invoke: async (service, operation, input) => {
+        // The route's own vocabulary is a tool-call object: a name and an
+        // arguments record. Anything else is a caller reaching past the
+        // transport, so it is refused rather than coerced.
+        if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+            throw new TypeError('the tool-surface adapter takes a tool-call object');
+        }
+        const call = input;
+        if (typeof call.name !== 'string') {
+            throw new TypeError('a tool call names the tool it is calling');
+        }
+        const tool = TOOLS_BY_NAME.get(call.name);
+        if (tool === undefined) {
+            throw new TypeError(`no tool named "${call.name}"`);
+        }
+        // A tool maps to exactly one operation, so a call naming a tool whose
+        // operation is not the one asked for is a wiring bug in the caller rather
+        // than something to reconcile silently.
+        if (tool.operation !== operation) {
+            throw new TypeError(`${call.name} performs "${tool.operation}", not "${String(operation)}"`);
+        }
+        const args = call.arguments === null || typeof call.arguments !== 'object' || Array.isArray(call.arguments)
+            ? {}
+            : call.arguments;
+        return service.perform({ operation, adapter: 'tool-stdio', arguments: args });
+    },
+};