browser-broker 0.1.0

package/dist/src/store/schema/step-004-tab-never-opened.js

@@ -0,0 +1,100 @@
+/**
+ * Step four: a tab that ended without ever opening becomes representable.
+ *
+ * **A new step rather than an edit to step one**, per the rule that a step
+ * which has run somewhere is history (`CLAUDE.md`, `SCHEMA.md` §1.2d).
+ * SQLite cannot alter a check in place, so the table is rebuilt — which is
+ * why this step is longer than the change it makes.
+ *
+ * ── The defect, and why the constraint rather than the writer is wrong ───
+ *
+ * Step one carries `CHECK ((state = 'opening') = (driver_tab_id IS NULL))`,
+ * an **equivalence**: a null driver name is permitted on `opening` and
+ * nowhere else. Its own comment gives the reason it exists, and the reason is
+ * narrower than the rule it wrote:
+ *
+ * > A tab that has not opened has no driver name to be unique against, and
+ * > one that has opened does. **Without this the partial unique index below
+ * > would be satisfied by any number of live rows holding null.**
+ *
+ * That index is `one_row_per_physical_tab`, and it covers
+ * `state IN ('opening', 'open', 'closing')`. **`closed` and `failed` are
+ * outside it**, so a null driver name on a closed row cannot dilute a
+ * uniqueness rule that does not range over it. The equivalence constrains two
+ * states its own justification never reaches.
+ *
+ * ── What that cost, measured ────────────────────────────────────────────
+ *
+ * A lease ends in one of two ways and both have to write the tab row.
+ * A tab that never opened has no driver name, so **every** terminal state was
+ * refused for it: `closing` is dishonest (§1.4 — nothing was asked and no
+ * page may still exist), and `closed` was forbidden by the equivalence. The
+ * row could not leave `opening`, so the update threw.
+ *
+ * Because the sweep runs unconditionally before every handler (§1.0a, and
+ * that is correct), **one lapsed lease holding such a tab made every
+ * arbitration call by every caller throw, permanently and across spawns** —
+ * the lapsed row could never be swept, because sweeping it was the operation
+ * that threw. A lapsing lease is the ordinary case the lazy sweep exists to
+ * serve (§2.4), so this was the main line rather than an edge.
+ *
+ * ── The narrowing, stated exactly ───────────────────────────────────────
+ *
+ * | State | Driver name | Before | Now |
+ * |---|---|---|---|
+ * | `opening` | null | required | **required**, unchanged |
+ * | `open` · `closing` | present | required | **required**, unchanged |
+ * | `closed` · `failed` | either | null refused | **permitted** |
+ *
+ * The live states keep the rule exactly as it was, which is the whole of what
+ * the index needs. What becomes representable is the true fact the design had
+ * no way to record: **a tab whose lease ended before the tab ever opened.**
+ * Nothing is loosened while a tab is live.
+ */
+const REBUILD = [
+    `
+CREATE TABLE tabs_next (
+  id             TEXT PRIMARY KEY,
+  claim_id       TEXT NOT NULL,
+  browser_id     TEXT NOT NULL,
+  driver_tab_id  TEXT,
+  state          TEXT NOT NULL
+                 CHECK (state IN ('opening', 'open', 'closing', 'closed', 'failed')),
+  opened_at      TEXT,
+  closed_at      TEXT,
+  close_failed   INTEGER NOT NULL DEFAULT 0
+                 CHECK (close_failed IN (0, 1)),
+  close_attempts INTEGER NOT NULL DEFAULT 0
+                 CHECK (close_attempts >= 0),
+  created_at     TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at     TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  FOREIGN KEY (claim_id, browser_id) REFERENCES claims (id, browser_id),
+  -- Narrowed to the live states, which are the ones the partial unique index
+  -- ranges over. A tab still live must say whether it has a driver name; one
+  -- that has finished may have ended before it ever acquired one.
+  CHECK (
+    state NOT IN ('opening', 'open', 'closing')
+    OR (state = 'opening') = (driver_tab_id IS NULL)
+  )
+) STRICT
+`,
+    `INSERT INTO tabs_next SELECT * FROM tabs`,
+    `DROP TABLE tabs`,
+    `ALTER TABLE tabs_next RENAME TO tabs`,
+    // Rebuilt with the table, because dropping it took them with it. Identical
+    // to step one's, which is what keeps this a change to one constraint.
+    `CREATE UNIQUE INDEX one_row_per_physical_tab
+     ON tabs (browser_id, driver_tab_id) WHERE state IN ('opening', 'open', 'closing')`,
+    `CREATE INDEX tabs_claim ON tabs (claim_id)`,
+];
+/** Every statement this step runs, in order. */
+export const STEP_FOUR_SQL = REBUILD;
+export const stepFour = {
+    version: 4,
+    summary: 'A tab may end without ever having opened; the driver-name rule narrows to live states.',
+    apply: (db) => {
+        for (const statement of STEP_FOUR_SQL) {
+            db.exec(statement);
+        }
+    },
+};

package/dist/src/store/schema/step-005-storage-seed-event.js

@@ -0,0 +1,90 @@
+/**
+ * Step five: `storage_seeded` becomes a recordable event kind (row #65).
+ *
+ * **A new step rather than an edit to step one**, per the rule that a step
+ * which has run somewhere is history (`CLAUDE.md`, `SCHEMA.md` §1.2d). SQLite
+ * cannot alter a check in place, so the table is rebuilt — which is why this
+ * step is longer than the one value it adds.
+ *
+ * ── Why the seed needs a kind of its own ────────────────────────────────
+ *
+ * `SCHEMA.md` §3.2 asks a specific question of the ledger: *"which leases
+ * started life already holding a credential"*. That is a question about a
+ * category of lease, so it has to be answerable by selecting on one — and a
+ * seed folded into the `claim_granted` row's detail would only be findable by
+ * reading every grant's JSON and testing for a key. **A kind is what makes it
+ * a query rather than a scan**, which is the same argument §1.6 makes for the
+ * kind column being a fixed list at all.
+ *
+ * It is recorded as its own row rather than as a field on the grant for a
+ * second reason: the seed is applied **after** the arbitration transaction
+ * commits, because writing storage is browser work and browser work never
+ * happens inside the transaction (§2.4b). The grant row is written before the
+ * seeding has happened, so a field on it would be a claim about the future.
+ *
+ * ── What the row carries, and what it must never carry ──────────────────
+ *
+ * **Origins and keys, never values.** §3.2 states it outright and gives the
+ * reason §3.9 gives about cookie values: the question needs an answer and the
+ * answer does not need the credential in it. Nothing in the schema can
+ * enforce that — `detail` is text — so it is enforced where the row is built
+ * (`storage-seed.ts`) and asserted by a test that reads the ledger back and
+ * looks for the value it seeded.
+ */
+const REBUILD = [
+    `
+CREATE TABLE events_next (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  kind       TEXT NOT NULL
+             CHECK (kind IN (
+               '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',
+               -- Added by this step. The origins and the keys of a seeded
+               -- lease, and never the values.
+               'storage_seeded'
+             )),
+  outcome    TEXT NOT NULL
+             CHECK (outcome IN ('allow', 'deny')),
+  guard      TEXT,
+  claim_id   TEXT REFERENCES claims (id),
+  tab_id     TEXT REFERENCES tabs (id),
+  session_id TEXT,
+  adapter    TEXT NOT NULL
+             CHECK (adapter IN ('tool-stdio', 'tool-http', 'cli', 'internal')),
+  browser_id TEXT REFERENCES browsers (id),
+  detail     TEXT,
+  -- A guard names the rule that refused, so it belongs on a denial and means
+  -- nothing on an allow.
+  CHECK ((outcome = 'deny') = (guard IS NOT NULL))
+) STRICT
+`,
+    // The identifier is a cursor callers may already hold (§1.6), so the copy
+    // preserves it rather than letting AUTOINCREMENT reissue from one.
+    `INSERT INTO events_next SELECT * FROM events`,
+    `DROP TABLE events`,
+    `ALTER TABLE events_next RENAME TO events`,
+    // Rebuilt with the table, because dropping it took them with it. Identical
+    // to step one's, which is what keeps this a change to one check constraint
+    // and nothing else — a rebuild that quietly loses an index is a rebuild
+    // that changes the performance of every ledger read.
+    `CREATE INDEX events_at ON events (at)`,
+    `CREATE INDEX events_claim_id ON events (claim_id, id)`,
+    `CREATE INDEX events_kind_at ON events (kind, at)`,
+    `CREATE INDEX events_guard ON events (guard) WHERE guard IS NOT NULL`,
+];
+/** Every statement this step runs, in order. */
+export const STEP_FIVE_SQL = REBUILD;
+export const stepFive = {
+    version: 5,
+    summary: 'A seeded lease is recordable: the `storage_seeded` event kind (#65).',
+    apply: (db) => {
+        for (const statement of STEP_FIVE_SQL) {
+            db.exec(statement);
+        }
+    },
+};

package/dist/src/store/schema/step-006-signin-events.js

@@ -0,0 +1,104 @@
+/**
+ * Step six: signing in becomes recordable — `browser_signin_began` and
+ * `browser_signin_ended` (`SCHEMA.md` §5.5.1).
+ *
+ * **A new step rather than an edit to step five**, per the rule that a step
+ * which has run somewhere is history (`CLAUDE.md`, `SCHEMA.md` §1.2d). SQLite
+ * cannot alter a check in place, so the table is rebuilt — which is why this
+ * step is longer than the two values it adds.
+ *
+ * ── Why signing in needs kinds of its own ───────────────────────────────
+ *
+ * §5.5.1 makes signing in a **service operation** rather than something a
+ * person does to a browser directly, and the reason it gives is the one that
+ * makes these rows necessary: it *"refuses if any live lease holds a tab on
+ * that browser"*, and while it is in progress *"requests for it are refused
+ * with a retry hint"*. So the service spends a period deliberately turning
+ * callers away, and §1.6 requires **every decision, allowed and refused
+ * alike**.
+ *
+ * Without a kind for the two edges, that period is invisible in the ledger:
+ * a reader would see a run of `browser_unavailable` denials with nothing
+ * saying why the browser was unavailable, and the obvious reading of a
+ * cluster of denials is a fault. **These two rows are what make the
+ * difference between "the browser was broken" and "a person was signing in"
+ * a query rather than a guess** — which is the same argument §1.6 makes for
+ * the kind column being a fixed list at all.
+ *
+ * Two kinds rather than one with a direction field, because the pair brackets
+ * an interval and the questions asked of it are asked of the edges: when did
+ * this start, did it ever finish, is one open right now. A single kind would
+ * make "is a sign-in open" a scan that reads every row's JSON and counts,
+ * rather than a comparison of two counts.
+ *
+ * ── What the rows carry, and what they must never carry ─────────────────
+ *
+ * **Which browser, and when. Never anything a person typed.** A sign-in is
+ * the one moment where credentials are physically present at the machine, and
+ * the ledger is a file that gets read, copied and pasted into messages. What
+ * a sign-in produces lives in the browser's own profile directory (§1.2) and
+ * is written there by the browser; **nothing in this service ever sees it**,
+ * so there is nothing here to leak by accident — but the rule is stated
+ * because the row is built by hand and a well-meaning addition would be the
+ * way it stopped being true. Nothing in the schema can enforce it — `detail`
+ * is text — so it is enforced where the row is built (`sign-in.ts`) and
+ * asserted by a test that reads the ledger back.
+ */
+const REBUILD = [
+    `
+CREATE TABLE events_next (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  kind       TEXT NOT NULL
+             CHECK (kind IN (
+               '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',
+               -- Added by this step. The two edges of the one interval in
+               -- which this service turns callers away on purpose, so that
+               -- period is legible as a sign-in rather than as a fault.
+               'browser_signin_began', 'browser_signin_ended'
+             )),
+  outcome    TEXT NOT NULL
+             CHECK (outcome IN ('allow', 'deny')),
+  guard      TEXT,
+  claim_id   TEXT REFERENCES claims (id),
+  tab_id     TEXT REFERENCES tabs (id),
+  session_id TEXT,
+  adapter    TEXT NOT NULL
+             CHECK (adapter IN ('tool-stdio', 'tool-http', 'cli', 'internal')),
+  browser_id TEXT REFERENCES browsers (id),
+  detail     TEXT,
+  -- A guard names the rule that refused, so it belongs on a denial and means
+  -- nothing on an allow.
+  CHECK ((outcome = 'deny') = (guard IS NOT NULL))
+) STRICT
+`,
+    // The identifier is a cursor callers may already hold (§1.6), so the copy
+    // preserves it rather than letting AUTOINCREMENT reissue from one.
+    `INSERT INTO events_next SELECT * FROM events`,
+    `DROP TABLE events`,
+    `ALTER TABLE events_next RENAME TO events`,
+    // Rebuilt with the table, because dropping it took them with it. Identical
+    // to step one's, which is what keeps this a change to one check constraint
+    // and nothing else — a rebuild that quietly loses an index is a rebuild
+    // that changes the performance of every ledger read.
+    `CREATE INDEX events_at ON events (at)`,
+    `CREATE INDEX events_claim_id ON events (claim_id, id)`,
+    `CREATE INDEX events_kind_at ON events (kind, at)`,
+    `CREATE INDEX events_guard ON events (guard) WHERE guard IS NOT NULL`,
+];
+/** Every statement this step runs, in order. */
+export const STEP_SIX_SQL = REBUILD;
+export const stepSix = {
+    version: 6,
+    summary: 'Signing in is recordable: the two `browser_signin_*` event kinds (§5.5.1).',
+    apply: (db) => {
+        for (const statement of STEP_SIX_SQL) {
+            db.exec(statement);
+        }
+    },
+};

package/dist/src/store/schema/step-007-signin-without-process.js

@@ -0,0 +1,92 @@
+/**
+ * Step seven: a browser can be claimed for a person before it has a process.
+ *
+ * ── The constraint this widens, and why it was right to begin with ──────
+ *
+ * Step one states it as `(state = 'stopped') = (pid IS NULL)`, with the
+ * reason that *"a stopped browser has no process, and a running one has
+ * one"*, expressed as a constraint rather than a convention because the
+ * reclamation path branches on the process being absent. Every state that
+ * existed when it was written was either *stopped*, or *a process is doing
+ * something*, so the biconditional was exactly true.
+ *
+ * ── What `signing-in` turned out to be, which the constraint did not cover ──
+ *
+ * `SCHEMA.md` §5.5.1 makes signing in a claim over the **profile**, not over
+ * a process: *"What the command does is claim the browser for the person"*,
+ * and *"nothing is stopped and nothing is relaunched"*. The claim has to be
+ * taken **before** a window is handed over, because its whole purpose is to
+ * stop a caller opening a tab in a browser somebody is about to drive by
+ * hand — a claim taken after the window appeared would be a guard that
+ * announced itself once the race was already lost.
+ *
+ * So there is a real and ordinary state that constraint makes unwritable:
+ * **the browser is not running, and a person has claimed it in order to sign
+ * in.** That is what a first sign-in on a fresh installation *is* — nobody
+ * has started a browser, which is precisely why nobody is signed in. The
+ * store rejected it with a check-constraint failure, which is the correct
+ * behaviour of a constraint that had been told something narrower than the
+ * truth.
+ *
+ * ── What is kept, and it is the part that was load-bearing ──────────────
+ *
+ * The direction the reclamation path relies on is **unchanged and still
+ * total**: a row that says `stopped` still has no process, and a row with a
+ * process still does not say `stopped`. Nothing that branches on *is there a
+ * process to reclaim* sees a different answer than before.
+ *
+ * What is relaxed is only the other direction, and only for one state: a
+ * browser that is `signing-in` may have a process or may not, because a
+ * person can be signing into one that is already up or into one that is
+ * being started for them. Every other non-stopped state still requires a
+ * process, so this does not become "the constraint means nothing now" —
+ * `starting`, `running` and `failed` are each still tied to one.
+ *
+ * **A new step rather than an edit to step one**, per the rule that a step
+ * which has run somewhere is history. SQLite cannot alter a check in place,
+ * so the table is rebuilt.
+ */
+const REBUILD = [
+    `
+CREATE TABLE browsers_next (
+  id            TEXT PRIMARY KEY
+                CHECK (id IN ('regular', 'private')),
+  state         TEXT NOT NULL DEFAULT 'stopped'
+                CHECK (state IN ('stopped', 'starting', 'running', 'signing-in', 'failed')),
+  pid           INTEGER,
+  launched_at   TEXT,
+  endpoint      TEXT,
+  browser_uuid  TEXT,
+  restart_count INTEGER NOT NULL DEFAULT 0
+                CHECK (restart_count >= 0),
+  -- **The defaults are part of the column**, and a rebuild that omits them
+  -- silently changes what an INSERT that does not name them does: it stops
+  -- defaulting from the database's own clock and starts failing NOT NULL.
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- **A stopped browser has no process.** Unchanged from step one, total,
+  -- and it is the direction the reclamation path branches on.
+  CHECK (state != 'stopped' OR pid IS NULL),
+  -- **A browser with no process is stopped — unless a person has claimed it.**
+  -- Step one's other direction, with the single exception §5.5.1 requires:
+  -- signing in is a claim over the profile rather than over a process, taken
+  -- before a window is handed over, so it is the one state that may hold
+  -- either. Starting, running and failed each still require a process.
+  CHECK (pid IS NOT NULL OR state IN ('stopped', 'signing-in'))
+) STRICT
+`,
+    `INSERT INTO browsers_next SELECT * FROM browsers`,
+    `DROP TABLE browsers`,
+    `ALTER TABLE browsers_next RENAME TO browsers`,
+];
+/** Every statement this step runs, in order. */
+export const STEP_SEVEN_SQL = REBUILD;
+export const stepSeven = {
+    version: 7,
+    summary: 'A browser may be claimed for a person before it has a process (§5.5.1).',
+    apply: (db) => {
+        for (const statement of STEP_SEVEN_SQL) {
+            db.exec(statement);
+        }
+    },
+};

package/dist/src/store/schema/step-008-signin-owner.js

@@ -0,0 +1,76 @@
+/**
+ * Step eight: a sign-in records **which process is holding it**.
+ *
+ * ── The failure this exists to make recoverable ─────────────────────────
+ *
+ * `broker login` moves the browser to `signing-in` and gives it back in a
+ * `finally`. **A `finally` does not run when the process is signalled**, so a
+ * person who pressed Ctrl-C — the ordinary way anybody stops a command that is
+ * waiting — left the browser in `signing-in` with nothing able to move it out.
+ * Every caller was then refused `browser.serving` forever, and a second
+ * `broker login` was refused too, because §5.5.1 permits only one sign-in at a
+ * time. The state was reachable by one keystroke and escapable only by editing
+ * the database by hand.
+ *
+ * A signal handler is added alongside this step and covers the interruption
+ * case. **It cannot cover the rest**, and that is the whole reason this column
+ * exists: `SIGKILL` cannot be handled at all, a power cut runs nothing, and a
+ * process that dies in the kernel runs nothing either. Any mechanism that
+ * relies on the dying process doing something is a mechanism with a hole in
+ * exactly the cases nobody can rehearse.
+ *
+ * ── Why a new column rather than reusing `browsers.pid` ─────────────────
+ *
+ * **`browsers.pid` is the browser's process, not the sign-in's**, and the two
+ * are different processes with different lifetimes: the browser is adopted and
+ * deliberately outlives the command (`login-command.ts` detaches precisely so
+ * the person's window survives). Reading it as the owner would ask "is the
+ * browser still up" while meaning "is the person's command still running", and
+ * those answers diverge in both directions.
+ *
+ * Worse, step seven made `signing-in` the one state permitted a **null** pid,
+ * because a first sign-in on a fresh installation claims a browser that has
+ * never been started. That is the commonest sign-in there is, and it is
+ * precisely the one where `browsers.pid` carries nothing to test.
+ *
+ * ── Why not the lease sweep ─────────────────────────────────────────────
+ *
+ * The sweep expires **claims** whose `expires_at` has passed. A sign-in is not
+ * a claim: it takes no lease and no tab budget (§5.5.1), it is a state on the
+ * `browsers` row, and it has no expiry — deliberately, because a person
+ * signing in may take as long as they take and a sweep that timed them out
+ * would end a sign-in that was going fine. So there is no lapse for the sweep
+ * to notice, and extending it to notice one would mean inventing a deadline
+ * the design does not have.
+ *
+ * The question is settled by **evidence** instead: the owner is either running
+ * or it is not, which is a fact rather than a timer.
+ *
+ * ── Nullable, and what each value means ─────────────────────────────────
+ *
+ * - **Null while the browser is not signing in.** There is no owner, so
+ *   recording one would be a claim about a process that is not doing anything.
+ * - **Set for the duration of a sign-in**, to the process identifier of the
+ *   command that began it.
+ *
+ * It is deliberately **not** constrained to be non-null on `signing-in`. A
+ * store written by an older build carries `signing-in` rows with no owner, and
+ * a constraint would make this step fail on exactly the installations that hit
+ * the bug. Those rows read as "owner unknown", which the recovery path reports
+ * as such rather than reclaiming on a guess.
+ *
+ * **A new step rather than an edit to step seven**, per the rule in
+ * `steps.ts`: a step that has run somewhere is history.
+ */
+const ADD_COLUMN = `ALTER TABLE browsers ADD COLUMN signin_owner_pid INTEGER`;
+/** Every statement this step runs, in order. */
+export const STEP_EIGHT_SQL = [ADD_COLUMN];
+export const stepEight = {
+    version: 8,
+    summary: 'A sign-in records the process holding it, so an abandoned one is recoverable (§5.5.1).',
+    apply: (db) => {
+        for (const statement of STEP_EIGHT_SQL) {
+            db.exec(statement);
+        }
+    },
+};

package/dist/src/store/schema/step-009-named-browsers.js

@@ -0,0 +1,138 @@
+/**
+ * Step nine: a browser's name is free, and its kind is the column.
+ *
+ * ── What this drops, and it is a decision rather than a widening ────────
+ *
+ * Step one wrote `CHECK (id IN ('regular', 'private'))` and step seven
+ * repeated it through a rebuild. That check is the database's half of
+ * *"exactly two browsers, no exceptions, ever"* — the half that makes the
+ * sentence true from underneath, since the primary key caps the table at two
+ * and step one's seed floors it at two.
+ *
+ * **That sentence is overturned** (`DECISIONS.md` §13i): the configured
+ * browsers are a bounded list per kind rather than a fixed pair, so the set
+ * of legal names is not knowable when the schema is written. A check
+ * naming two literals cannot express *"a name somebody configured"*, and a
+ * check that tried would have to be rewritten every time a name changed —
+ * which is a schema step per configuration edit, on a table whose whole
+ * purpose is to be configured.
+ *
+ * ── What stands in its place, so nothing load-bearing is merely dropped ────
+ *
+ * **`kind` is a column with its own check.** What that constraint
+ * actually protects is not the two words: it is that every row is either a
+ * persistent signed-in browser or an ephemeral clean-room one, with no third
+ * thing and no row that is neither. That property is what the rest of
+ * the design branches on — a clean-room browser is launched with an
+ * ephemeral profile, a signed-in one is not, and `SCHEMA.md` §5.5.1's
+ * sign-in is a claim over a persistent profile.
+ *
+ * So the kind stays **database-enforced and total** while the name becomes
+ * free. This is the same trade §1.2 already made in the other direction:
+ * *"No `persistent` flag. Whether a browser uses a persistent profile is a
+ * property of which browser it is."* That reasoning held while the name was
+ * one of two literals and the word carried the kind. Once a name is
+ * `checkout` or `admin`, the word carries nothing, and the property has to
+ * be written down or it is not enforced anywhere. **The column exists
+ * because the name stopped implying it**, which is the condition §1.2's
+ * reasoning was conditional on all along.
+ *
+ * ── Backfill: the two existing rows are named by what they are ──────────
+ *
+ * A store stepped by an earlier build holds exactly the rows `regular` and
+ * `private`, because that is what the check permitted. Each is backfilled to
+ * its own kind by name, which is exact rather than a guess: those two names
+ * meant those two kinds, and no other name could exist to be ambiguous.
+ *
+ * The default is deliberately **absent**. A default would let a later insert
+ * that forgot the column produce a row whose kind is a guess, and the row
+ * creation this step enables (`DECISIONS.md` §13i — rows are created on
+ * first launch, not from configuration at startup) is exactly the writer
+ * that must state it.
+ *
+ * ── Rows are still not created from configuration here ──────────────────
+ *
+ * This step creates no rows and deletes none. It does not read the
+ * configured lists, and could not usefully: two processes on one machine may
+ * hold different configurations, and a step that seeded from one process's
+ * environment would write that process's beliefs into a store the other one
+ * shares. §1.2a already arbitrates the launch race through the same
+ * transaction as claims — *"one row, one winner"* — so a row appears when a
+ * browser is first launched, created by whichever caller won that race.
+ *
+ * The two rows step one seeded stay exactly where they are. They are the
+ * default configuration's two browsers, and a store that has them is a store
+ * that was stepped.
+ *
+ * **A new step rather than an edit to step one or step seven**, per the rule
+ * in `steps.ts`: a step that has run somewhere is history. SQLite cannot
+ * alter a check in place, so the table is rebuilt — the same shape step
+ * seven used, and for the same reason.
+ */
+const REBUILD = [
+    `
+CREATE TABLE browsers_next (
+  -- **No check on the name.** The legal names are the configured ones, which
+  -- the schema cannot know. What a name must satisfy is enforced where it is
+  -- read: 'src/config/environment.ts' refuses a name that is not a usable
+  -- word, once, at startup, naming the entry that was wrong.
+  id            TEXT PRIMARY KEY,
+  -- **The kind, and it is total.** Every row is a persistent signed-in
+  -- browser or an ephemeral clean-room one; there is no third and no row
+  -- that is neither. This is what the name used to carry.
+  kind          TEXT NOT NULL
+                CHECK (kind IN ('regular', 'private')),
+  state         TEXT NOT NULL DEFAULT 'stopped'
+                CHECK (state IN ('stopped', 'starting', 'running', 'signing-in', 'failed')),
+  pid           INTEGER,
+  launched_at   TEXT,
+  endpoint      TEXT,
+  browser_uuid  TEXT,
+  restart_count INTEGER NOT NULL DEFAULT 0
+                CHECK (restart_count >= 0),
+  -- **The defaults are part of the column**, and a rebuild that omits them
+  -- silently changes what an INSERT that does not name them does: it stops
+  -- defaulting from the database's own clock and starts failing NOT NULL.
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  signin_owner_pid INTEGER,
+  -- **A stopped browser has no process.** Unchanged from step one, total,
+  -- and it is the direction the reclamation path branches on.
+  CHECK (state != 'stopped' OR pid IS NULL),
+  -- **A browser with no process is stopped — unless a person has claimed it.**
+  -- Step seven's exception, carried forward unchanged: signing in is a claim
+  -- over the profile rather than over a process, so it is the one state that
+  -- may hold either.
+  CHECK (pid IS NOT NULL OR state IN ('stopped', 'signing-in'))
+) STRICT
+`,
+    // The columns are named on both sides rather than `SELECT *`, because the
+    // destination carries a column the source does not: a positional copy
+    // would shift every value one place to the left from `kind` onward.
+    `
+INSERT INTO browsers_next
+  (id, kind, state, pid, launched_at, endpoint, browser_uuid, restart_count,
+   created_at, updated_at, signin_owner_pid)
+SELECT
+  id,
+  -- Exact rather than a guess: the check this step drops permitted these two
+  -- names and no others, and each named its own kind.
+  CASE id WHEN 'private' THEN 'private' ELSE 'regular' END,
+  state, pid, launched_at, endpoint, browser_uuid, restart_count,
+  created_at, updated_at, signin_owner_pid
+FROM browsers
+`,
+    `DROP TABLE browsers`,
+    `ALTER TABLE browsers_next RENAME TO browsers`,
+];
+/** Every statement this step runs, in order. */
+export const STEP_NINE_SQL = REBUILD;
+export const stepNine = {
+    version: 9,
+    summary: "A browser's name is configured and its kind is a column (§1.2, DECISIONS.md §13i).",
+    apply: (db) => {
+        for (const statement of STEP_NINE_SQL) {
+            db.exec(statement);
+        }
+    },
+};