Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

202 KB
Raw Blame
import { and, asc, eq, inArray, isNull, sql } from "drizzle-orm";
import { createAuditStore, recordAuditEvent } from "../../audit";
import type { Database } from "../../db/client";
import {
  brokeredConnections,
  credentials as credentialRows,
  mcpServers,
  mcpTools,
  mcpUserCredentials,
  pendingAuthorizations,
  users,
  vendorNameOf,
} from "../../db/schema";
import { BROKERED_PROFILE, toolkitOfFor } from "../access";
import {
  BrokerRefusalError,
  BrokerUnconfiguredError,
  type Decides,
  isFieldScheme,
  type SchemeKind,
} from "../broker";
import {
  asksForArguments,
  askAction as composioAskAction,
  VERSION_ARG,
} from "../composio";
import { type AccountRef, personAccount } from "../shared-accounts";
import type { StoreContext } from "./context";
import {
  attemptNamed,
  type BrokeredProbe,
  IDENTITY_ACTION,
  iso,
  type OAuthClient,
  type PendingAuthorization,
  PluginRefusedError,
  pendingAuthorizationFromRow,
} from "./model";

/** OAuth clients and a person's connections, including every brokered (Composio) connection flow. */
export function connectionMethods(context: StoreContext) {
  const {
    options,
    database,
    auditStore,
    credentials,
    registerClient,
    broker,
    accountRow,
    swapUserCredential,
    withOAuthClientLock,
    heldOAuthClient,
    writeOAuthClient,
    recordClientRegistered,
    persistOAuthClient,
    storedOAuthClient,
    requireServer,
    brokeredAppRow,
    brokeredAppRowsAt,
    brokeredAppScheme,
    brokeredAppKind,
    brokerProvider,
    closeAuthorizationAttempt,
    resolveSiblings,
    consentRevokeReaches,
    vendorRevocationClaim,
    siblingsEndedBy,
    clearEndedSiblings,
  } = context;
  return {
    /**
     * Register the deployment's OAuth client for a `user-oauth` server.
     *
     * An administrator pasting in what they created at the vendor. The work itself is
     * {@link persistOAuthClient}, which self-registration goes through too — one path, so a client
     * this deployment issued itself is stored, revoked and recorded exactly like a pasted one.
     */
    registerOAuthClient: persistOAuthClient,

    /**
     * The client to send somebody to the vendor with, registering one first if that is this
     * vendor's way of getting one.
     *
     * A dynamically registered client is not paperwork anybody did: there is no console entry to
     * paste, so "none yet" is the ordinary state of a server nobody has connected — and the answer
     * is for the deployment to introduce itself, which is what it would have to do eventually
     * anyway. Where an administrator registers by hand instead, and where the deployment has no
     * public URL to be sent back to, the answer stays null: inventing a client at a vendor that
     * never offered to issue one, or registering a redirect URI that resolves to nothing, would
     * both leave behind a client that can never complete a consent flow.
     *
     * ONE CLIENT PER DEPLOYMENT EVEN WHEN TWO PEOPLE ASK AT ONCE. This is `requireUser`'s handler, so
     * two first connects racing is the ordinary first hour of a connector. Registering twice is not
     * merely wasteful: the loser's consent screen names a client the vault no longer holds, so that
     * person consents and their callback then redeems the code against the client that replaced it —
     * a connect that fails after the vendor already said yes. So the registration happens under
     * {@link withOAuthClientLock}, with the "do we hold one" question asked AGAIN inside it, and the
     * second caller finds the first one's client and is handed the same one.
     *
     * The lock is held across the registration request to the vendor, deliberately. It is one round
     * trip with its own timeout, and a lock released before it would serialise nothing.
     */
    async ensureOAuthClient(
      serverId: string,
      by: string,
    ): Promise<OAuthClient | null> {
      const stored = await storedOAuthClient(serverId);
      if (stored) return stored;

      const { entry } = await requireServer(serverId);
      if (
        entry?.auth.kind !== "user-oauth" ||
        entry.auth.clientRegistration !== "dynamic" ||
        !entry.auth.registrationUrl ||
        !options.redirectUri
      ) {
        return null;
      }
      // Held before the lock, because narrowing does not survive into the closure below.
      const { registrationUrl } = entry.auth;
      const { redirectUri } = options;

      const outcome = await withOAuthClientLock(
        serverId,
        async (transaction) => {
          /*
           * Asked again, under the lock. The read above was a fast path taken without one, and by now
           * the caller we were racing has committed a client of its own — which is the one this
           * deployment holds, so it is the one to consent against.
           */
          const held = await heldOAuthClient(transaction, serverId);
          if (held) return { client: held, registered: false, replaced: false };

          const registered = await registerClient({
            registrationUrl,
            redirectUri,
          });
          if (!registered) return null;

          const { replaced } = await writeOAuthClient(
            { serverId, client: registered },
            transaction,
          );
          return { client: registered, registered: true, replaced };
        },
      );

      if (!outcome) return null;
      // Only what this call actually did. A trail row for handing back somebody else's client would
      // claim a registration that never happened.
      if (outcome.registered) {
        await recordClientRegistered(
          { serverId, client: outcome.client, by },
          outcome.replaced,
        );
      }
      return outcome.client;
    },

    /**
     * Record that one person connected their own account to one server.
     *
     * The credential swap is {@link swapUserCredential}, and this is its only caller: a person
     * connecting or reconnecting is exactly when there is an older grant to revoke. Rotation writes
     * the same connection in place instead ({@link rotateConnectionToken}). What is only here is the
     * audit row: this one IS somebody's act, and the trail should say so.
     */
    async recordConnection(input: {
      serverId: string;
      userId: string;
      refreshToken: string;
      scope: string;
    }): Promise<void> {
      const { replaced } = await swapUserCredential(input);

      await recordAuditEvent(auditStore, {
        eventType: "mcp.account_connected",
        targetType: "mcp_server",
        targetId: input.serverId,
        payload: {
          actor: input.userId,
          server: input.serverId,
          // What the vendor granted, so a later refusal for want of a scope can be explained.
          scope: input.scope,
          reconnected: replaced,
        },
      });
    },

    /**
     * The deployment's OAuth client for a server, or null if none is registered.
     *
     * Reads only. {@link ensureOAuthClient} is the one that will go and get one.
     */
    oauthClientFor: storedOAuthClient,

    /** Which `user-oauth` servers this person has connected, for their own settings page. */
    async connectionsFor(userId: string): Promise<
      {
        serverId: string;
        scope: string;
        connectedAt: string;
        /**
         * Whether the credential this row points at has been withdrawn.
         *
         * THE ROW OUTLIVES THE SECRET, and until this field existed the two were impossible to tell
         * apart from outside. Revoking a credential sets `revoked_at` on the credential; it does not
         * delete the row here, which goes on pointing at it — so "this person has a row for Notion"
         * and "this person can use Notion" are different facts, and every reader of this list was
         * getting the first while asking the second. A reconnection does not settle it either: the
         * upsert moves `credential_id` and `updated_at` and leaves `connected_at` where it was, so
         * nothing in the shape this used to return changes when access comes back.
         *
         * Reported rather than filtered. A caller that wants "connected" asks for a row that is not
         * revoked; one that wants to draw every app somebody has ever connected still can, and
         * memory ingestion's existence check keeps the behaviour it had.
         */
        revoked: boolean;
      }[]
    > {
      const rows = await database
        .select({
          serverId: mcpUserCredentials.serverId,
          scope: mcpUserCredentials.scope,
          connectedAt: mcpUserCredentials.connectedAt,
          revokedAt: credentialRows.revokedAt,
        })
        .from(mcpUserCredentials)
        /*
         * Inner, and total because of the foreign key: `credential_id` is a real reference that
         * does not cascade, so a join row cannot outlive the credential it points at — a deletion
         * is refused while the row is there. That is why there is no "the credential is gone" case
         * to report here, and why a revoked credential is the only way this answer goes false.
         */
        .innerJoin(
          credentialRows,
          eq(credentialRows.id, mcpUserCredentials.credentialId),
        )
        .where(eq(mcpUserCredentials.userId, userId))
        .orderBy(asc(mcpUserCredentials.serverId));

      return rows.map((row) => ({
        serverId: row.serverId,
        scope: row.scope,
        connectedAt: iso(row.connectedAt) ?? "",
        revoked: row.revokedAt !== null,
      }));
    },

    /**
     * Which brokered apps this person has connected, for the same settings page.
     *
     * A SECOND METHOD RATHER THAN A WIDER {@link connectionsFor}, because the two answer out of
     * different tables for a reason the schema is built on: a `user-oauth` connection is a pointer
     * into the vault, and a brokered one holds no secret at all because Composio keeps the account
     * (see {@link brokeredConnection}). Reading only the vault side is what left a brokered
     * connection invisible to the browser, so the settings screen could not honestly say whether
     * somebody was connected.
     *
     * THE SERVER ID IS JOINED, NOT SPELLED. `addBrokeredApp` writes the app into the url, and every
     * later call resolves against that url — so matching on it asks the row what it is, where
     * composing `composio-${toolkit}` by hand would re-derive the id from a convention nothing
     * holds it to. It is the reasoning the directory route already uses when it reads a row's
     * toolkit off its url rather than off its id. An app this deployment has since removed
     * therefore drops out of the answer, which is the honest result: there is no server row left
     * for a page to name.
     *
     * `scope` IS EMPTY for the reason {@link confirmBrokeredConnection} sets out: Composio grants
     * none that it tells us about, and the field exists to record what the vendor said it granted
     * rather than what we suppose. It is returned all the same, so the fields this shares with
     * {@link connectionsFor} — `serverId`, `scope`, `connectedAt` — line up and one screen can draw
     * both kinds of row. What comes back here is a SUPERSET of that shape rather than the same one:
     * `verified` and `verifiedAt` ride along too, and only on a brokered row, because only a
     * brokered row is a thing this deployment can re-check.
     *
     * `verified` AND `verifiedAt` COME ALONG BECAUSE "connected" IS NOT A PRESENT TENSE HERE.
     * Composio never re-checks a key somebody typed in: it answers ACTIVE for as long as the row
     * exists, whatever the vendor on the other side now thinks of that credential. So a page drawn
     * off `connectedAt` alone would assert something this deployment has not known since the day it
     * was written. These two fields are what lets it say when the claim was last earned instead —
     * "connected with a key you provided, last checked 13 Sep". What the pair separates is a
     * CHECKED key connection from an unchecked one, and nothing more: which KIND of connection a
     * row is comes from the app's recorded {@link ServerRecord.authScheme}, which the page branches
     * on first, and not from anything answered here.
     *
     * `probe` IS THE ACTION THE LAST CHECK SPENT, READ OUT OF THE ROW. The pair above says whether a
     * key connection was ever checked; it cannot say WHY one was not, and three different
     * situations share the one word `false`. Until this field, only the answer to a connect or a
     * re-check could tell them apart — so a page reload lost the distinction, and the worst of the
     * three degraded into the mildest: a row saying the key was accepted without being checked, over
     * an account whose key the vendor had actually REFUSED.
     *
     * IT IS STORED BECAUSE IT IS A FACT ABOUT A MOMENT, NOT ABOUT TODAY'S METADATA. This field was
     * once derived here, by asking {@link probeActionFor} which action this deployment WOULD check
     * the app with; the argument for that was that the chooser holds every condition the probe
     * itself runs on, so the two could not disagree. They cannot disagree AT AN INSTANT, and that is
     * all it establishes. `verified` records a check made against the app's action listing as it
     * stood THEN, and the chooser answers from the listing as it stands NOW — and `POST
     * /servers/:id/refresh` is a generic administrator's route keyed on a server id, of which
     * `composio-<slug>` is one, so an ordinary press of Refresh moves the second without touching
     * the first. It is the very press the Composio transport tells an operator to make when an
     * action appears or gains the version that makes it callable. So: somebody connects a key to an
     * app that publishes nothing safe to try it on, and the row honestly says the key was accepted
     * unchecked. An administrator presses Refresh. From that page load on, the derivation named an
     * action, and the row drew the sentence written for a REFUSED key — your key was checked against
     * this app and rejected, the account it was checked in still stands, so disconnect it. Every
     * clause of that is false for somebody whose key was never tried, it tells them to take down a
     * connection that works, and it persists: it is what every page load says until they press
     * Re-check.
     *
     * SO THE WRITER RECORDS WHAT IT SPENT AND THIS READS IT BACK. {@link recordBrokeredConnection}
     * is the single writer, every path into it knows the action it spent or that it spent none, and
     * {@link composioConnections.probeAction} is where that goes. Read together with `verified`, the
     * column tells four states apart, and no inference is made in any of them:
     *
     *   no probe, not verified   — nothing was tried: at the time of the check the app published
     *                              nothing safe to spend a key on. A fact about the app, not the
     *                              key. A key row written before the column existed reads this way
     *                              too, for the reason that column gives.
     *   no probe, verified       — a CONSENT connection. The vendor's own yes at its own screen is
     *                              the evidence, no call was ever made against the account, and so
     *                              there is no action to name.
     *   a probe, verified        — it ran in this person's account and the vendor took the key.
     *   a probe, NOT verified    — it ran and the vendor refused the key, and the account it ran in
     *                              is still standing. A live account with a bad key behind it.
     *
     * AND THE LAST LINE IS A RECORD RATHER THAN AN INFERENCE, which is the whole of what changed.
     * The caveat that stood here used to argue the state into existence: a key connection is ALWAYS
     * probed at connect time, a probe that fails withdraws the account it just made, so an
     * unverified row under an app that HAS a probe must be a refusal whose withdrawal failed — or
     * else a re-check the vendor refused, which leaves the person's own older account alone. That
     * reasoning was sound about the rows it described and said nothing about the row a refresh had
     * quietly moved underneath it. What the row now warrants, it warrants by having been written:
     * the check ran, it spent this action, and the vendor refused.
     *
     * WHICH PATH WROTE IT IS STILL NOT RECOVERABLE, and a reader must not invent one. The column
     * records what was spent, not who spent it, and the two writers of that pair end differently: a
     * connect withdraws the account it had just made and only leaves the row where Composio refused
     * to take it back, while a re-check never withdraws anything, because the account predates the
     * press and is the person's own. So a page may say the key was refused and the account stands;
     * a page that goes on to blame a failed withdrawal is right on the connect path and FALSE on the
     * re-check, where nothing ever tried to remove anything.
     *
     * `checkable` IS THE OTHER QUESTION, AND IT TRAVELS SEPARATELY BECAUSE COLLAPSING THE TWO IS
     * WHAT DEADLOCKED THE SETTINGS SCREEN. "What did the check SPEND" is a fact about the past, and
     * `probe` answers it. "Does this app have anything to check with TODAY" is a fact about the
     * present, and this answers that — out of {@link probeActionFor}, asked of the APP rather than
     * of the connection. The two agreed for as long as `probe` was derived: one field, one moment,
     * two questions nobody ever had to tell apart. They part company the instant it became a
     * record, which is the same instant it started being right about the past.
     *
     * THE DEADLOCK IN FULL, BECAUSE IT DOES NOT SELF-HEAL. The page gates its Re-check button on
     * whether there is anything to check with, and it read `probe` for that. Somebody connects a
     * key to an app that publishes nothing safe to spend it on: the check spends nothing, the row
     * records null, and both of those are correct and permanent. An administrator presses Refresh,
     * the app gains a safe versioned read, and the button is STILL withheld — because the record
     * still says, truthfully, that nothing was spent. And pressing that button is the only thing in
     * this product that can ever put an action into the record. The state is stable, wrong, and
     * unreachable from inside itself: the single act that would end it is the act being withheld.
     *
     * SO A CALLER TAKES THE PAST FROM ONE AND THE PRESENT FROM THE OTHER, and must take neither out
     * of the other one. A screen drawing its SENTENCE off `checkable` would accuse a key nobody
     * tried, which is the defect the recorded column was made for; a screen gating its BUTTON on
     * `probe` is the deadlock above. Neither field is a weaker spelling of the other, and the
     * moment one is asked to answer both questions the two failures simply trade places.
     *
     * WHICH COSTS ONE QUERY PER CONNECTED APP, AND THAT IS THE RIGHT PRICE. Making `probe` a stored
     * column took the per-row call out and left a listing that was one query; this puts it back —
     * on top of the two the rows themselves now take, which the body below says why.
     * The alternative is to fold the chooser's rule into the join — vendor-labelled read, not
     * destructive, no required inputs, a recorded version — and that rule has no honest spelling in
     * SQL: `required` is the vendor's own JSON Schema stored unchanged, and deciding whether it is
     * a non-empty list of names is a thing JavaScript does and a `json` operator does badly. So
     * folding it in means writing the rule a SECOND time, in a second language, over the same rows,
     * and this file already records what a rule in two places costs: while the version condition
     * sat in one of them, an app whose chosen action had no version connected honestly as "nothing
     * was tried" and reloaded as "your key was checked and rejected". {@link probeActionFor} is the
     * one authority on what can be checked, and a listing that asks it N times cannot disagree with
     * the probe that asks it once. N is the apps ONE person has connected — a handful of indexed
     * reads by server id, made in parallel — behind a settings page and not on any hot path.
     *
     * `verifiedAt` STAYS NULL WHERE IT IS NULL, unlike `connectedAt`, which collapses to `""`
     * because a row cannot exist without one and the fallback is unreachable. Null here is
     * reachable and it means something: never checked. Folding it into `""` would hand the page a
     * row that was checked at a time nobody recorded, which is a different fact and not one this
     * table ever holds. Note also what {@link composioConnections.verified} sets out about the rows
     * migration 0038 backfilled: their `verifiedAt` is the moment of consent, not the moment of a
     * probe, so a caller must not read every timestamp here as "this connection answered then".
     */
    async brokeredConnectionsFor(userId: string): Promise<
      {
        serverId: string;
        scope: string;
        connectedAt: string;
        verified: boolean;
        verifiedAt: string | null;
        probe: string | null;
        checkable: boolean;
      }[]
    > {
      /*
       * THIS PERSON'S OWN ACCOUNTS AND NOTHING ELSE. `holder = 'person'` is said out loud rather
       * than left to the user id, because a settings page listing "your connections" must never
       * draw the deployment's shared account as one of them — a deployment row has no `user_id`,
       * and the filter keeps that a fact this query states rather than one it happens to rely on.
       */
      /*
       * NO PROVIDER PREDICATE HERE, DELIBERATELY, AND THAT IS NOT AN OVERSIGHT. Each row is resolved
       * below at the ACTIVE provider's canonical url, so another provider's row would be silently
       * dropped from the page. What keeps that unreachable is the startup activation refusal
       * (`assertActivatable`, called from `server/src/index.ts`): it will not boot when the
       * configured provider differs from the one on the existing rows. No flow relaxes that refusal
       * today; whoever builds one must add the `brokerProvider` predicate here.
       */
      const connections = await database
        .select({
          toolkit: brokeredConnections.app,
          connectedAt: brokeredConnections.connectedAt,
          verified: brokeredConnections.verified,
          verifiedAt: brokeredConnections.verifiedAt,
          probeAction: brokeredConnections.probeAction,
        })
        .from(brokeredConnections)
        .where(
          and(
            eq(brokeredConnections.holder, "person"),
            eq(brokeredConnections.userId, userId),
          ),
        );

      /*
       * THE APP IS RESOLVED PER CONNECTION, NOT JOINED TO IT, BECAUSE THE URL IS NOT A KEY.
       *
       * CRITERION. One connection is one row out of here, whatever `mcp_servers` holds.
       *
       * REASON. This read used to be an inner join on `mcp_servers.url = 'composio://' || toolkit`,
       * and nothing in the schema makes that column unique — the one `uniqueIndex` in
       * `db/schema/plugins.ts` is `skills_slug_key` on `skills.slug`. A join answers one row per
       * PAIR, so a second row at an app's url listed the same account twice: two rows on the
       * settings page saying the same app under two different server ids, each offering to
       * disconnect the single connection standing behind both. And it is not an exotic state — it
       * is what any database looks like the moment a row at `gmail` sits beside the
       * `composio-gmail` an administrator really added, which is how a development database
       * routinely looks.
       *
       * A UNIQUE INDEX WOULD BE THE OTHER FIX AND IS THE WRONG ONE. Two rows at one address is a
       * state this product means to allow — a deployment holding two accounts at one vendor adds
       * the same URL twice under two ids with two credentials, and `addCustomServer` refuses only a
       * re-add that MOVES an existing id's address. Constraining the column would forbid that for
       * everybody to tidy a display defect, and the migration that added it would fail outright on
       * any deployment already holding a duplicate, taking the whole boot with it.
       *
       * SO THE LOWER ID ANSWERS FOR THE APP, and it is a rule rather than whatever the scan met
       * first: a page that redrew under a different `serverId` each load would be offering buttons
       * keyed on a value moving underneath it. The same rule decides the scheme reads — see
       * {@link brokeredAppScheme} — so nothing in this file can name one row for an app while
       * something else names another.
       *
       * AND "LOWER" IS THE DATABASE'S OWN WORD FOR IT, WHICH IS WHY THE ORDER IS IN THE QUERY. This
       * read took its rows unordered and picked the smallest with a JavaScript `<`, which compares
       * UTF-16 code units and nothing else, while {@link brokeredAppRow} asks for `order by id`
       * under whatever collation the deployment's database runs. Those two agree for ASCII on a `C`
       * database and are free to disagree everywhere else — a linguistic collation reorders case and
       * punctuation, and byte order and code-unit order part company above the BMP. One rule spelled
       * in two languages is two rules, and where they parted the page drew an app under one server
       * id while the Re-check button beside it, the probe behind that button and the scheme that
       * decides whether the button appears at all were about the other row: the same defect the
       * single read was written to end, reached through the collation instead of through the query.
       * So the resolution is {@link brokeredAppRowsAt} and not a rule spelled again here: it is the
       * same function {@link brokeredAppRow} answers one app out of, which is what makes the row
       * this page draws an app under the row every read behind its buttons is about.
       *
       * A CONNECTION WITH NO ROW AT ITS URL IS STILL LISTED BY NOTHING, which is what the inner
       * join answered and what the missing `serverId` below drops. A person can hold an account at
       * an app this deployment has since removed, and the settings page has no row to draw for it.
       */
      /*
       * AT THE ACTIVE BROKER'S SCHEME, which is the one {@link brokeredAppRow} resolves every other
       * url against. Spelled `composio://` here, this read answered an empty map on any other
       * broker — every `serverId` undefined, every connection dropped, and the connected-accounts
       * page drawn empty for somebody holding accounts. Fail-closed and visible, and total.
       */
      const canonical = (toolkit: string) =>
        `${BROKERED_PROFILE[brokerProvider].scheme}${toolkit}`;
      const named = await brokeredAppRowsAt(
        connections.map((row) => canonical(row.toolkit)),
      );

      const rows = connections
        .flatMap((row) => {
          const serverId = named.get(canonical(row.toolkit))?.id;
          return serverId === undefined ? [] : [{ ...row, serverId }];
        })
        // By server id, as the join's own `order by` was, so this read and `connectionsFor` hand the
        // route two lists ordered alike. Compared as plain strings rather than through a collation,
        // for the reason the route gives where it merges them: the order only has to be the same
        // one every time.
        .sort((left, right) => {
          if (left.serverId < right.serverId) return -1;
          return left.serverId > right.serverId ? 1 : 0;
        });

      return await Promise.all(
        rows.map(async (row) => ({
          serverId: row.serverId,
          scope: "",
          connectedAt: iso(row.connectedAt) ?? "",
          verified: row.verified,
          verifiedAt: iso(row.verifiedAt),
          // The name alone, because that is what the four states are told apart by; the version the
          // check was made at is the caller-of-the-call's business, and this read makes none.
          probe: row.probeAction,
          /*
           * WHETHER, NOT WHICH. The chooser names an action and this keeps only the yes or no,
           * because the yes or no is the whole of the question being asked: is there anything to
           * spend a key on. Carrying the name would put a second action name on a row that already
           * has one, inches from the field that records what was actually spent — and the first
           * reader to draw a sentence off the wrong one re-opens the defect that made `probe` a
           * record. A boolean cannot be mistaken for a record of anything.
           */
          checkable: (await this.probeActionFor(row.serverId)) !== null,
        })),
      );
    },

    /**
     * The deployment's one account at a brokered app, as the admin page draws it; null where none
     * is connected, and null for a server that is not brokered at all.
     *
     * `connectedBy` IS THE ADMINISTRATOR'S EMAIL, because an id is not something a page can show
     * anybody. It falls back to the stored id when that person has since been removed, so the row
     * still says somebody connected it rather than claiming nobody did.
     *
     * `displayName` IS ASKED OF THE BROKER AND NEVER FAILS THE READ. It is the vendor's name for
     * the account — the one thing that tells an administrator WHICH team account is behind the app
     * — and a vendor that will not say is a page missing a label, not a page that cannot load.
     */
    async deploymentConnectionFor(serverId: string): Promise<{
      connectedAt: string;
      connectedBy: string | null;
      verified: boolean;
      verifiedAt: string | null;
      probe: string | null;
      displayName: string | null;
    } | null> {
      const [server] = await database
        .select({ url: mcpServers.url })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId))
        .limit(1);
      const toolkit = server ? toolkitOfFor(brokerProvider, server.url) : null;
      if (!toolkit) return null;

      const [row] = await database
        .select({
          vendorUserId: brokeredConnections.vendorUserId,
          connectedBy: brokeredConnections.connectedBy,
          connectedByEmail: users.email,
          connectedAt: brokeredConnections.connectedAt,
          verified: brokeredConnections.verified,
          verifiedAt: brokeredConnections.verifiedAt,
          probeAction: brokeredConnections.probeAction,
        })
        .from(brokeredConnections)
        .leftJoin(users, eq(users.id, brokeredConnections.connectedBy))
        .where(
          and(
            eq(brokeredConnections.provider, brokerProvider),
            eq(brokeredConnections.app, toolkit),
            eq(brokeredConnections.holder, "deployment"),
          ),
        )
        .limit(1);
      if (!row) return null;

      const displayName = broker
        ? await broker
            .accountName({
              account: { holder: "deployment", vendorUserId: row.vendorUserId },
              toolkit,
            })
            .catch(() => null)
        : null;

      return {
        connectedAt: iso(row.connectedAt) ?? "",
        connectedBy: row.connectedByEmail ?? row.connectedBy,
        verified: row.verified,
        verifiedAt: iso(row.verifiedAt),
        probe: row.probeAction,
        displayName,
      };
    },

    /**
     * Every Shared app, connected or not, as `GET /connections` lists it beside a person's own.
     *
     * A SHARED APP WITH NOTHING CONNECTED IS STILL LISTED, as `connected: false`. Its absence would
     * read as "this app needs nothing", when it is the one state an administrator has to act on —
     * the page offers its Connect action off exactly this entry.
     *
     * `checkable` IS TRUE ONLY WHEN AN ACCOUNT IS CONNECTED AND THE APP IS A KEY APP WITH A PROBE
     * ACTION, because a re-check spends a key on a safe read and there is no key to spend without
     * a connected account, nor on a consent app, which has no key at all. Where it is a connected
     * key app the answer is {@link probeActionFor}'s, asked of the app, for the reason
     * {@link brokeredConnectionsFor} gives for keeping `checkable` apart from `probe`.
     */
    async sharedConnections(): Promise<
      {
        serverId: string;
        scope: "";
        holder: "deployment";
        connected: boolean;
        connectedAt: string | null;
        connectedBy: string | null;
        verified: boolean;
        verifiedAt: string | null;
        probe: string | null;
        checkable: boolean;
        displayName: string | null;
      }[]
    > {
      /*
       * ONE ENTRY PER SHARED APP, under the row that answers for it. A row marked `shared` that is
       * a duplicate at some app's url is not the app — the app is Shared only if its answering row
       * says so — and listing it would offer a Connect for an account no call would use.
       */
      const marked = await database
        .select({ id: mcpServers.id, url: mcpServers.url })
        .from(mcpServers)
        .where(eq(mcpServers.accountMode, "shared"))
        .orderBy(asc(mcpServers.id));
      const answering = await brokeredAppRowsAt(
        marked
          .filter((row) => toolkitOfFor(brokerProvider, row.url) !== null)
          .map((row) => row.url),
      );
      const shared = marked.filter(
        (row) => answering.get(row.url)?.id === row.id,
      );

      return await Promise.all(
        shared.map(async (server) => {
          const toolkit = toolkitOfFor(brokerProvider, server.url);
          const [connection, kind] = await Promise.all([
            this.deploymentConnectionFor(server.id),
            toolkit ? brokeredAppKind(toolkit) : null,
          ]);
          return {
            serverId: server.id,
            scope: "" as const,
            holder: "deployment" as const,
            connected: connection !== null,
            connectedAt: connection?.connectedAt ?? null,
            connectedBy: connection?.connectedBy ?? null,
            verified: connection?.verified ?? false,
            verifiedAt: connection?.verifiedAt ?? null,
            probe: connection?.probe ?? null,
            checkable:
              connection !== null &&
              kind === "key" &&
              (await this.probeActionFor(server.id)) !== null,
            displayName: connection?.displayName ?? null,
          };
        }),
      );
    },

    /**
     * Whether this person has one brokered app connected, and since when.
     *
     * THE ROW IS A CACHE OF COMPOSIO'S ANSWER, not a record of a flow this deployment watched
     * finish. Nothing here holds a secret for a brokered app: the vendor keeps the account, and
     * what {@link brokeredConnections} holds is the sentence "Composio said yes when we asked",
     * written down so that every later call can be gated without a round trip. That makes drift
     * possible by construction — somebody can end the connection in Composio's own dashboard, and
     * this row would go on saying yes — and it is why {@link confirmBrokeredConnection} asks the
     * vendor again rather than trusting what is here. Calling confirm on any page load is
     * therefore how a row that drifted heals.
     *
     * Read by the pair, because the pair is what the partial unique indexes enforce one row per:
     * (provider, app) among deployment rows and (provider, app, user_id) among person rows —
     * `holder` is each partial index's WHERE predicate, not a key column, so an ON CONFLICT
     * target must name exactly those columns with the matching WHERE. An app has many people's
     * connections and a person has many apps, and the only question anybody asks is about one of
     * each.
     */
    async brokeredConnection(input: {
      toolkit: string;
      account: AccountRef;
    }): Promise<{ connectedAt: string } | null> {
      const [row] = await database
        .select({ connectedAt: brokeredConnections.connectedAt })
        .from(brokeredConnections)
        .where(accountRow(input.toolkit, input.account))
        .limit(1);

      if (!row) return null;
      return { connectedAt: iso(row.connectedAt) ?? "" };
    },

    /**
     * The action a key verification should call against this app, and the version to call it at.
     *
     * THIS CHOOSES THE ONE ACTION THAT WILL BE CALLED WITH SOMEBODY'S JUST-TYPED API KEY, which is
     * what makes it the most dangerous line in the verification: whatever comes back from here runs
     * against a stranger's account, once, purely to find out whether their key works. So the two
     * safety conditions below are BOTH non-negotiable, and neither is a stricter spelling of the
     * other.
     *
     * READ EFFECT, because a probe must not change anything. The label is the vendor's own and not
     * a guess of ours: `effectOf` answers `read` only where Composio sent `readOnlyHint`, and
     * everything unlabelled was already recorded as a write, so `read` here means Stripe or Linear
     * or Notion said so. `destructive` is checked beside it rather than trusted to be implied — the
     * two are separate columns precisely so a vendor can say both things, and a row that somehow
     * says read AND destructive is a row this deployment has no business calling unasked.
     *
     * ZERO REQUIRED INPUTS, because there is nothing to invent an argument from. A probe happens
     * before this deployment knows anything about the account beyond the key, so a required customer
     * id or query has no honest value to carry, and a made-up one turns "is this key good" into
     * "does this identifier exist" — which fails for a perfectly good key.
     *
     * BOTH, NEVER EITHER, and the live catalogue is why this sentence is here rather than a comment
     * saying the checks are belt-and-braces. The first argument-less action on Stripe's own list is
     * `STRIPE_CREATE_BILLING_METER_EVENT_SESSION`. A probe chosen on "takes no arguments" alone —
     * the condition that looks sufficient, because it is the one that makes a call possible at all —
     * would therefore write to somebody's account to find out whether their key works. The read
     * effect is the whole of what stands between those two names.
     *
     * AND A RECORDED VERSION, WHICH IS PART OF "CAN THIS BE CALLED AT ALL" AND NOT A DETAIL OF THE
     * CALLER. Composio refuses an execution without a specific version and rejects `latest`, so the
     * transport refuses before dialling where none travels with the call — and Composio publishes
     * some actions with no version at all. An action this deployment recorded without one is
     * therefore an action nothing here can spend a key on, which is the same kind of fact as a
     * required input: not unsafe, just not callable. The version is SELECTED AND RETURNED for the
     * caller that has to send it, so the choice and the call cannot come apart.
     *
     * THE CONDITION LIVES IN THE FILTER RATHER THAN AFTER THE CHOICE, so there is ONE predicate for
     * one question. While it sat downstream — read by the probe, unknown to everything else — there
     * were two, and the weaker of them was what the connections listing derived its `probe` field
     * from: an app whose chosen action had no version connected honestly as "nothing was tried",
     * then reloaded as "your key was checked and rejected". That listing no longer derives that
     * field from here — {@link brokeredConnectionsFor} reads what the check RECORDED, because no
     * derivation from today's metadata can be right about yesterday's check. It still asks this
     * function a question, but a present-tense one: whether the app has anything to check with now,
     * kept as a yes or no beside the record. A split predicate would therefore no longer put a
     * false sentence on a settings page; it would show up in two worse places — a probe that chose
     * an action it then refused to send, and a button offered over an app nothing can be spent on.
     * A filter also lets the search CONTINUE: a versionless
     * candidate is passed over for the next safe read rather than short-circuiting the whole app to
     * "nothing to try", so an app that can be checked is.
     *
     * NULL IS AN ANSWER AND NOT A FAILURE. Of fifteen key-based apps sampled, most publish some safe
     * argument-less read and PostHog publishes none at all, so an app that cannot be probed is an
     * ordinary app rather than a broken one. What a caller does about it — and running the probe at
     * all — belongs to the verification path; this function only chooses.
     */
    async probeActionFor(
      serverId: string,
    ): Promise<{ name: string; version: string } | null> {
      // Ordered, because the fallback below is "the first candidate" and Postgres promises no order
      // without one: an unordered read would make which action gets called with somebody's key a
      // property of whichever plan the server happened to pick.
      const actions = await database
        .select({
          /*
           * THE VENDOR'S SPELLING, BECAUSE THIS NAME IS CALLED RATHER THAN DISPLAYED. The pair this
           * answers goes to the transport directly (see `probeConnection`), and a transport answers
           * only to the name its own listing gave. {@link IDENTITY_ACTION} is written in that same
           * vocabulary — `_GET_ME`, `_WHOAMI` — so it is matched against this for the same reason.
           * Identical to `name` on every transport this path actually reaches. See
           * {@link mcpTools.vendorName}.
           */
          name: vendorNameOf(),
          inputSchema: mcpTools.inputSchema,
          effect: mcpTools.effect,
          destructive: mcpTools.destructive,
          version: mcpTools.version,
        })
        .from(mcpTools)
        .where(eq(mcpTools.serverId, serverId))
        .orderBy(asc(mcpTools.name));

      // One pass, and it yields the pair rather than the row: an action that survives every
      // condition below has a version by definition, and building the answer here is what carries
      // that fact into the type instead of leaving the caller to re-check it.
      const safe = actions.flatMap((action) => {
        if (action.effect !== "read" || action.destructive) return [];
        // Null in the column and blank in the data are the same nothing, and neither is a version
        // the transport can put on a call.
        const version = action.version?.trim();
        if (!version) return [];
        /*
         * THE WHOLE SCHEMA IS ASKED, NOT ITS TOP-LEVEL `required`. This read `schema?.required` and
         * passed over the action only for a non-empty list there — so an action whose required
         * arguments are published under `allOf`/`anyOf`/`$ref`, which is how a generated toolkit
         * ordinarily writes them, was selected as argument-less, called with `{}`, and answered with
         * the vendor's validation error. That arrives at `probeConnection` as `answered: true,
         * isError: true`, which is the `refused` verdict — a valid key declared bad, and on connect
         * the account created seconds earlier deleted behind it. See {@link asksForArguments} for
         * which keywords bear on an empty object and why the unreadable shapes answer yes.
         */
        if (asksForArguments(action.inputSchema)) return [];
        return [{ name: action.name, version }];
      });

      const identity = safe.find((action) => IDENTITY_ACTION.test(action.name));
      return identity ?? safe[0] ?? null;
    },

    /**
     * Write down that this person holds this brokered app, and how well that is known.
     *
     * ONE WRITER SO THE VERIFIED AND UNVERIFIED PATHS CANNOT DRIFT INTO TWO ROW SHAPES. What says
     * how well a connection is known is a SET of fields and not a column: `verified` is meaningless
     * without the moment it was earned, and `verified_at` without the flag is a date on a claim
     * nobody made. Every path that records a connection therefore comes through here rather than
     * spelling that set for itself — {@link confirmBrokeredConnection} with `true` today, and the
     * verify path, which is the caller `false` exists for, when a probe against a key connection
     * comes back unanswered. Two call sites each writing the set by hand is how one of them comes
     * to set the flag and leave the timestamp null, or to move `connected_at` on a confirm that
     * healed a row nothing changed; spelled once, a reader asking what shape a connection row takes
     * has one answer and every path takes it.
     *
     * `verified` IS THE CALLER'S CLAIM AND `verifiedAt` FOLLOWS FROM IT, never the other way round.
     * True means the caller has evidence as of now — the vendor's own yes at the end of a consent
     * screen, or a call that went out and came back — so the timestamp is stamped here rather than
     * passed in, and it is the moment of the write because that is the moment the evidence was in
     * hand. False takes the timestamp back to null rather than leaving the old one standing: a row
     * that has stopped being verified must not keep a date saying when it last was, because the one
     * sentence the page builds out of the pair — "last checked 13 Sep" — would then be drawn for a
     * connection this deployment is no longer claiming anything about.
     *
     * `connected_at` IS LEFT ALONE, which is the whole reason this is an upsert with an explicit
     * `set` rather than a delete and an insert. The person connected when they connected; a write
     * that moved it would make every page load look like a fresh connection on their own settings
     * page, and would erase the one date the row holds that nothing else in this deployment knows.
     *
     * AND THE STAMP IT WROTE IS WHAT IT ANSWERS, for the same reason the caller does not pass one
     * in. A caller that needs the moment — {@link recheckBrokeredConnection}, which hands it to the
     * browser as the date the row's sentence is drawn from — would otherwise have to read the row
     * back and hope it was reading its own write. The timestamp is still this writer's; what
     * changed is that it is no longer thrown away.
     *
     * `only` IS WHETHER THIS WRITE MAY CREATE A CONNECTION, AND ONE CALLER MUST SAY NO.
     *
     * CRITERION. With `only: "a row that is still there"` this method never inserts. It updates a
     * row that exists and answers `wrote: false` for one that does not, and the caller decides what
     * to do about that.
     *
     * REASON. {@link recheckBrokeredConnection} reads the row first, deliberately, "because the
     * writer below is an upsert, so a re-check that probed first would INSERT a connection for
     * somebody who has none". That read and this write straddle a LIVE VENDOR CALL of several
     * seconds, and nothing held the row still across it. A person pressing Re-check and then
     * Disconnect in another tab — or a concurrent {@link confirmBrokeredConnection} getting `false`
     * from Composio and deleting the row — had the revoke complete at Composio and the row deleted,
     * and then this in-flight upsert PUT IT BACK. `brokered_connections` is the whole of the
     * permission a brokered call is decided on, so what the re-insert restores is access to an
     * account the person has just disconnected, drawn on every screen as connected.
     *
     * THE GUARD IS ON THE WRITE RATHER THAN A LOCK ACROSS THE CALL, because the call is somebody
     * else's and may take as long as it likes. A connection this write did not find is one nothing
     * happened to: the probe's answer is about an account the person no longer has here.
     *
     * `probeAction` IS PASSED IN, UNLIKE THE TIMESTAMP, BECAUSE ONLY THE CALLER KNOWS IT. It is the
     * action this check SPENT — the probe's name, or null where none was spent — and it is required
     * rather than optional so that a new path cannot record a connection while staying silent about
     * what it tried. Every existing caller knows the answer without looking anything up: a consent
     * confirm spent nothing and passes null, and both probing paths pass the name the probe returned
     * them, which is null there too when the app published nothing safe to call.
     *
     * IT IS PART OF THE SAME SET AS THE FLAG AND THE STAMP, which is the reason it is written here
     * and nowhere else. `verified` alone says a check did not pass and cannot say what it was; this
     * column is what separates "the app published nothing to try" from "it ran and the vendor said
     * no", and a row carrying one of the three without the others is a shape no reader downstream
     * has reasoned about. It used to be derived on read instead, from the app's action listing as
     * that listing stood at the moment of the read — see {@link brokeredConnectionsFor}, where the
     * refresh that broke the derivation is written out.
     */
    async recordBrokeredConnection(input: {
      toolkit: string;
      account: AccountRef;
      connectedBy?: string;
      verified: boolean;
      probeAction: string | null;
      /** See the paragraph on `only` above. Absent is the ordinary upsert. */
      only?: "a row that is still there";
    }): Promise<{ verifiedAt: Date | null; wrote: boolean }> {
      const verifiedAt = input.verified ? new Date() : null;
      // The one set, spelled once, so the conditional write below and the upsert cannot drift into
      // two row shapes. `probeAction` is overwritten rather than left standing, for `verifiedAt`'s
      // reason: the pair describes ONE check, and a row keeping the action an earlier check spent
      // beside the verdict of a later one would name a call this row's own state did not come from.
      const set = {
        verified: input.verified,
        verifiedAt,
        probeAction: input.probeAction,
        updatedAt: new Date(),
      };

      if (input.only === "a row that is still there") {
        /*
         * AN UPDATE AND NEVER AN INSERT, and `returning` is how "there was a row" is ANSWERED rather
         * than assumed. An update that matches nothing is not a failure — it is the row having been
         * deleted while the vendor was being asked — and the caller has a sentence for that.
         *
         * `vendor_user_id` IS DELIBERATELY NOT IN THIS `set`. This branch records a CHECK of a
         * connection that already exists, never a connection; it may not re-point the row at a
         * different vendor identity, because only a connect or a confirm (the upsert below) is
         * evidence of a grant held under the identity it names.
         */
        const written = await database
          .update(brokeredConnections)
          .set(set)
          .where(accountRow(input.toolkit, input.account))
          .returning({ vendorUserId: brokeredConnections.vendorUserId });
        return { verifiedAt, wrote: written.length > 0 };
      }

      /*
       * THE VENDOR IDENTITY THIS WRITE'S EVIDENCE IS ABOUT, WRITTEN ON BOTH BRANCHES OF THE UPSERT.
       *
       * CRITERION. After this upsert the row names `input.account.vendorUserId`, whatever it named
       * before.
       *
       * REASON. Every caller of the upsert has just heard from the vendor about the account held
       * under THIS id — a consent, or the vendor confirming it holds an account — and
       * `connectionTokenFor` sends calls out under the ROW's `vendor_user_id`, never a recomputed
       * one. A conflict arm that rewrote `verified`/`verified_at` and left the old id standing
       * wrote a verdict about one account onto a row naming another, and every later call landed
       * in the account the evidence was not about. The insert always set it; the arms did not.
       */
      const connectedAs = input.account.vendorUserId;
      await database
        .insert(brokeredConnections)
        .values({
          /*
           * THE BROKER THIS ROW WAS ACTUALLY MINTED AT, which is this store's own, because this
           * insert only ever runs behind a connection just made at the broker this store holds.
           *
           * CRITERION. A row inserted here carries the provider whose grant it stands for, so the
           * reads keyed on `provider` above find exactly the rows this writer wrote.
           *
           * REASON. The literal `composio` here was the one line that could not fail loudly. An
           * Arcade deployment writing it would read its own rows back through a `composio` filter
           * and APPEAR TO WORK, while the refusal that is supposed to fire when the other provider
           * holds rows never fired — nothing would ever be filed under the other name — and the
           * offboarding sweep, keyed the same way, would sweep a slice of the table that was not
           * this deployment's. Every symptom of that is silence.
           */
          provider: brokerProvider,
          app: input.toolkit,
          holder: input.account.holder,
          userId:
            input.account.holder === "person" ? input.account.userId : null,
          vendorUserId: input.account.vendorUserId,
          connectedBy:
            input.account.holder === "deployment"
              ? (input.connectedBy ?? null)
              : null,
          verified: input.verified,
          verifiedAt,
          probeAction: input.probeAction,
        })
        .onConflictDoUpdate(
          input.account.holder === "person"
            ? {
                target: [
                  brokeredConnections.provider,
                  brokeredConnections.app,
                  brokeredConnections.userId,
                ],
                targetWhere: sql`${brokeredConnections.holder} = 'person'`,
                set: { ...set, vendorUserId: connectedAs },
              }
            : {
                target: [brokeredConnections.provider, brokeredConnections.app],
                targetWhere: sql`${brokeredConnections.holder} = 'deployment'`,
                // WHO CONNECTED IT MEANS THE LATEST CONNECTION. A deployment account is
                // shared, so a second administrator reconnecting it supersedes the first —
                // which `set` otherwise never said, leaving the row crediting whoever
                // connected it the first time. Added only when this call names a
                // `connectedBy` at all, so a re-check or a confirm that passes none does not
                // blank out the administrator an earlier connect already recorded. That
                // condition is the point: do NOT make this unconditional.
                set: input.connectedBy
                  ? {
                      ...set,
                      vendorUserId: connectedAs,
                      connectedBy: input.connectedBy,
                    }
                  : { ...set, vendorUserId: connectedAs },
              },
        );
      return { verifiedAt, wrote: true };
    },

    /**
     * The other apps this deployment holds a connection for that share THIS app's connection: the
     * apps on the same vendor identity AND the same AUTH PROVIDER, never the provider alone. The
     * reason is written out on {@link connectionSiblings}; this is that computation over the rows
     * this deployment actually holds under the active provider.
     *
     * THE BROKER THIS STORE WAS BUILT WITH ANSWERS IT, AND NO CALLER SUPPLIES A RESOLVER. The auth
     * provider is the vendor's fact and this store keeps no copy of it, so it is asked for — of
     * {@link ConnectedAppBroker.authProviderOf}, which both providers implement. A resolver taken as
     * a parameter would be a question every caller had to answer identically or see a different
     * sibling set; with the store calling its own broker there is ONE answer by construction and
     * nothing to keep in step. A deployment with no broker answers `[]` — a presence test on a
     * declared value, and correct, because such a deployment holds no brokered rows at all.
     *
     * THE SCAN IS PRE-FILTERED ON THE ASKING IDENTITY, IN THE `WHERE`. Resolving the auth provider
     * is a vendor call per app, on a screen somebody is waiting on; resolving it for every brokered
     * row of the whole deployment and only then discarding the rows on other identities is unbounded
     * in the one dimension that grows. `vendor_user_id` is a column, so the filter is free — and
     * semantically identical, because {@link connectionSiblings} discards exactly those rows.
     *
     * An app the broker cannot answer for (`null`) is left out rather than guessed at: claiming a
     * sibling that is not one is the failure D26 exists to prevent. If the asking app itself is
     * unanswered the list is empty.
     *
     * `unanswered` IS HOW MANY OTHER APPS ON THE ASKING IDENTITY WERE LEFT OUT FOR THAT REASON — an
     * integer, never names; see {@link resolveSiblings} for why it is surfaced.
     *
     * IT ANSWERS A FACT AND ACTS ON NOTHING: no revocation, no deletion, no audit write. Returns the
     * sibling toolkits, sorted, never including `toolkit`, and the unanswered count.
     */
    async siblingApps(input: {
      toolkit: string;
      account: AccountRef;
    }): Promise<{ siblings: string[]; unanswered: number }> {
      return resolveSiblings(input);
    },

    /**
     * Start an Arcade authorization attempt for one person: take the key if it is free, expired or
     * completed, and refuse if a LIVE attempt holds it. ONE STATEMENT.
     *
     * `actorId` IS THE SESSION SUBJECT (`users.id`), NEVER `credentialActorId`. This file reads
     * `input.credentialActorId ?? input.actorId`, and on a Team Bot those differ, and neither is the
     * person holding the browser. The verifier finds the attempt from the returning browser's
     * session, so any other key writes attempts a browser can never match.
     *
     * ONE STATEMENT BECAUSE A READ-THEN-WRITE LETS TWO REQUESTS BOTH SEE "NO LIVE ATTEMPT" AND BOTH
     * INSERT. The conditional `ON CONFLICT ... DO UPDATE ... WHERE` is what makes the claim atomic:
     * the second request waits on the first's row and then evaluates the WHERE against it. The
     * live row is answered by the same statement, in a branch that only produces rows when the
     * claim produced none. It can be null: a rival that committed after this statement took its
     * snapshot is live but not yet visible to it, and the caller's 409 then names nothing.
     *
     * `created_at` is truncated to milliseconds so the `Date` handed back names the stored value
     * exactly — a microsecond no `Date` can carry would otherwise sit in the row unreachable.
     * {@link recordAuthorizationMint} and {@link discardAuthorizationAttempt} do not RELY on that:
     * they truncate the column in the comparison too, so a row written by anything else — the
     * column's own `defaultNow()`, say — is still reachable. See {@link attemptNamed}.
     */
    async claimAuthorizationAttempt(input: {
      actorId: string;
      serverId: string;
      action: string;
      account: AccountRef;
    }): Promise<
      | { claimed: true; attempt: PendingAuthorization }
      | { claimed: false; live: PendingAuthorization | null }
    > {
      const rows = await database.execute(sql`
        WITH claimed AS (
          INSERT INTO pending_authorizations
            (actor_id, server_id, action, holder, user_id, vendor_user_id, created_at)
          VALUES (
            ${input.actorId}, ${input.serverId}, ${input.action}, ${input.account.holder},
            ${input.account.holder === "person" ? input.account.userId : null},
            ${input.account.vendorUserId}, date_trunc('milliseconds', now())
          )
          ON CONFLICT (actor_id) DO UPDATE SET
            server_id = EXCLUDED.server_id,
            action = EXCLUDED.action,
            holder = EXCLUDED.holder,
            user_id = EXCLUDED.user_id,
            vendor_user_id = EXCLUDED.vendor_user_id,
            auth_id = NULL,
            created_at = EXCLUDED.created_at,
            completed_at = NULL,
            outcome = NULL
          WHERE pending_authorizations.created_at < now() - interval '15 minutes'
            OR pending_authorizations.completed_at IS NOT NULL
          RETURNING *
        )
        SELECT true AS claimed, claimed.* FROM claimed
        UNION ALL
        SELECT false AS claimed, p.* FROM pending_authorizations p
        WHERE p.actor_id = ${input.actorId}
          AND NOT EXISTS (SELECT 1 FROM claimed)
      `);
      const row = rows[0] as Record<string, unknown> | undefined;
      if (!row) return { claimed: false, live: null };
      const attempt = pendingAuthorizationFromRow(row);
      return row.claimed === true
        ? { claimed: true, attempt }
        : { claimed: false, live: attempt };
    },

    /**
     * Write the `ar_...` the vendor minted onto the attempt, matched on `(actor_id, created_at)`
     * through {@link attemptNamed}, which is where the precision of that match is argued.
     *
     * WRITE-ONCE, AND NEVER AFTER SETTLEMENT: the UPDATE also requires `auth_id IS NULL` and
     * `completed_at IS NULL`. `auth_id` is what binds the attempt to the authorization the person
     * was actually sent to consent to, and both conditions are needed to keep that binding fixed.
     *
     * `completed_at IS NULL` is {@link closeAuthorizationAttempt}'s rule, for the same reason: a
     * settled attempt is a record, not a draft. Without it, a late or duplicated mint rewrote a
     * completed attempt's `ar_...`, even to NULL, and the row no longer named the authorization
     * the person consented to.
     *
     * `auth_id IS NULL` is needed because `completed_at IS NULL` alone still lets a duplicated mint
     * rebind a LIVE attempt. Once the person has the first id's consent URL, writing a second id
     * (or NULL) makes their return leg match nothing. A NULL `auth_id` is never valid after
     * settlement: every settling write (`completeAuthorizationAttempt` and the three verdicts
     * through `closeAuthorizationAttempt`) matches `auth_id = $1`, which NULL never satisfies.
     * So `auth_id IS NULL` alone would already rule out any row the store settled. `completed_at
     * IS NULL` is kept anyway, so the guard does not depend on every future writer settling
     * through those paths.
     *
     * The first write is the only one, and it can be NULL: a vendor that answered with no id
     * leaves the attempt null, and it expires. Answers whether it wrote. False means the attempt
     * was discarded, replaced, already minted or already settled. The authorize route acts on it:
     * on false it does not hand out the consent url, because nothing here records that flow.
     */
    async recordAuthorizationMint(input: {
      actorId: string;
      /** A `Date`, or the ISO string one becomes through JSON; see {@link attemptInstant}. */
      createdAt: Date | string;
      /** Null when the vendor answered with no id: the attempt then can never complete. */
      authId: string | null;
    }): Promise<boolean> {
      const written = await database
        .update(pendingAuthorizations)
        .set({ authId: input.authId })
        .where(
          and(
            attemptNamed(input.actorId, input.createdAt),
            isNull(pendingAuthorizations.authId),
            isNull(pendingAuthorizations.completedAt),
          ),
        )
        .returning({ actorId: pendingAuthorizations.actorId });
      return written.length > 0;
    },

    /**
     * Delete one attempt, matched on `(actor_id, created_at)` SO IT CAN NEVER DELETE A NEWER
     * ATTEMPT BY THE SAME ACTOR. Matching on `auth_id` would be wrong: an attempt whose mint never
     * completed has none, and that is exactly the one most worth cancelling.
     *
     * CONDITIONAL ON `completed_at IS NULL`, THE SAME RULE {@link closeAuthorizationAttempt} AND
     * THE COMPLETION HOLD, BECAUSE A SETTLED ATTEMPT IS A RECORD AND NOT A DRAFT. `(actor_id,
     * created_at)` does not stop naming a row when the row settles, and every caller of this reads
     * the attempt FIRST and deletes it AFTER. Unconditional, a completion committing in that gap
     * was erased outright — the one row saying this person's consent went through, with the grant
     * live at the vendor, the `brokered_connections` row written and `mcp.account_connected` on
     * the trail — and the cancel route then answered `{ cancelled: true }` for a consent that had
     * succeeded. The DELETE waits on the completion's row lock and re-evaluates this condition
     * against the committed row, so the guard holds under the race and not merely before it.
     *
     * `false` therefore means one of three things — no row under that key, a row under a different
     * `created_at`, or a row that has settled — and all three are "nothing was discarded". A caller
     * that must tell the third apart asks {@link settledAuthorizationOutcome}.
     */
    async discardAuthorizationAttempt(input: {
      actorId: string;
      /** A `Date`, or the ISO string one becomes through JSON; see {@link attemptInstant}. */
      createdAt: Date | string;
    }): Promise<boolean> {
      const deleted = await database
        .delete(pendingAuthorizations)
        .where(
          and(
            attemptNamed(input.actorId, input.createdAt),
            isNull(pendingAuthorizations.completedAt),
          ),
        )
        .returning({ actorId: pendingAuthorizations.actorId });
      return deleted.length > 0;
    },

    /**
     * How the attempt named by `(actor_id, created_at)` ended, or null while it has not ended, or
     * when no row carries that key.
     *
     * FOR THE ONE CALLER THAT HAS TO SAY WHY A DISCARD REFUSED: the cancel route, which must not
     * answer a person whose consent COMPLETED while they were cancelling it as though nothing had
     * happened. Named through {@link attemptNamed} like the discard it explains, so it can only
     * report the attempt that discard was aimed at and never a newer one by the same actor. Once
     * settled, a row keeps that `created_at` until a new claim takes the key and rewrites it, so a
     * reading after the refused DELETE answers for the same attempt the DELETE refused.
     */
    async settledAuthorizationOutcome(input: {
      actorId: string;
      createdAt: Date | string;
    }): Promise<PendingAuthorization["outcome"]> {
      const [row] = await database
        .select({ outcome: pendingAuthorizations.outcome })
        .from(pendingAuthorizations)
        .where(attemptNamed(input.actorId, input.createdAt));
      return row?.outcome ?? null;
    },

    /**
     * Finish one Arcade authorization: consume the attempt, record the connection and file the
     * trail, ALL THREE IN ONE TRANSACTION OR NONE OF THEM.
     *
     * THE ATTEMPT ROW IS THE SERIALIZATION POINT AND THE DATABASE ENFORCES IT. The first statement
     * is a conditional `UPDATE ... WHERE actor_id = $1 AND auth_id = $2 AND completed_at IS NULL
     * RETURNING`, and it is what makes completion happen exactly once. A read of the attempt
     * followed by a write would not: two callbacks can both read the row before either consumes it,
     * and both would then write a connection and a second `mcp.account_connected`. The second
     * caller's UPDATE instead waits on the first's row lock, re-evaluates `completed_at IS NULL`
     * against the committed row, and matches nothing.
     *
     * AN `auth_id` IN AN AUDIT PAYLOAD ENFORCES NOTHING, which is the shape this replaces.
     * {@link auditEvents.id} is `uuid().defaultRandom()`, so the trail has no key a second callback
     * could collide with — it would simply hold two rows for one connection, and the connection
     * upsert would have run twice on the way there.
     *
     * ZERO ROWS MEANS STOP, AND THE CALLER IS TOLD SO: `{ claimed: false }`, with nothing written.
     * It is still not an error — a replayed callback is a no-op rather than something somebody has
     * to explain — but it is no longer silent, because zero rows is not one fact. It is somebody
     * else completing this attempt first, where the account IS connected; or the attempt having
     * ended some other way underneath the caller — most sharply the person's own Cancel, whose
     * DELETE can land after the vendor confirmed the return and before this UPDATE, leaving a grant
     * live at the vendor that the person asked not to have. This used to answer the same for all
     * of them, and the verifier then told a person who had just cancelled that they were
     * connected. Which one it was is not this method's to decide: a caller holding `false` asks
     * {@link authorizationAttemptCompleted} whether the row says `completed`.
     *
     * THE CONNECTION AND THE AUDIT ROW ARE IN THE SAME TRANSACTION AS THAT UPDATE and not merely
     * after it. A failure between them used to leave the attempt consumed and nothing recording
     * what it was consumed FOR: the person's account is live at the vendor, this deployment holds
     * no `brokered_connections` row — which is the whole of the permission a brokered call is
     * decided on — and the attempt can never be completed again. The audit insert is bound to the
     * transaction for the same reason, through {@link createAuditStore} over the transaction handle
     * rather than the store's own `auditStore`, which holds the pool and would commit on its own.
     *
     * `scopes` IS WHAT THE VENDOR GRANTED, AND IT IS THE ONLY THING FROM THAT ANSWER THAT IS
     * WRITTEN ANYWHERE. Arcade's `auth.status` carries a live provider access token and an
     * authorization URL beside it; neither reaches this row, this method's arguments, a log line or
     * an error. What the trail gets is the action the attempt was for and the scopes that came
     * back, which is exactly what is needed later to explain a tool call refused for want of a
     * scope — the question {@link mcpUserCredentials.scope} exists to answer for a `user-oauth`
     * grant. `authProvider` is the authorization provider this deployment ASKED for (`google`, say, as
     * distinct from the broker, `brokered_connections.provider`). The caller resolves it from the
     * app's own row at freshness-revalidation time and passes it in; the attempt row has no
     * provider column to carry it. It is never read back out of a vendor reply, and the narrowed
     * `status` return of D31 makes that structurally impossible.
     */
    async completeAuthorizationAttempt(input: {
      actorId: string;
      authId: string;
      toolkit: string;
      account: AccountRef;
      action: string;
      scopes: string[];
      authProvider: string;
    }): Promise<{ claimed: boolean }> {
      return await database.transaction(async (transaction) => {
        /*
         * ONE STATEMENT, AND THE FIRST ONE. `completed_at` is truncated to milliseconds for the
         * reason `claimAuthorizationAttempt` truncates `created_at`: a `Date` carries only
         * milliseconds, and a column this deployment writes at microsecond precision is one no
         * later `Date`-valued filter can ever match. Nothing matches on this column today; writing
         * it the same way is what keeps that true if something does.
         */
        const claimed = await transaction.execute(sql`
          UPDATE pending_authorizations
             SET completed_at = date_trunc('milliseconds', now()),
                 outcome = 'completed'
           WHERE actor_id = ${input.actorId}
             AND auth_id = ${input.authId}
             AND completed_at IS NULL
          RETURNING actor_id
        `);
        if (claimed.length === 0) return { claimed: false };

        // Read inside the transaction, under the attempt's lock, so the answer the audit row
        // carries is the one this very write acted on rather than one a rival moved underneath it.
        const [existing] = await transaction
          .select({ app: brokeredConnections.app })
          .from(brokeredConnections)
          .where(accountRow(input.toolkit, input.account));

        const verifiedAt = new Date();
        const set = {
          verified: true,
          verifiedAt,
          // NOTHING WAS SPENT TO EARN THAT FLAG. A consent screen is the vendor's own yes, and no
          // action of the app's is ever called against it; see `confirmBrokeredConnection`, which
          // writes the same pair for the same reason.
          probeAction: null,
          updatedAt: verifiedAt,
        };
        /*
         * WHO CONNECTED THE TEAM ACCOUNT, WRITTEN HERE FOR THE SAME REASON EVERY OTHER WRITER
         * WRITES IT. `connectedBy` is only ever a deployment-held row's column — a person's row is
         * attributed by `user_id` already — and for a Shared app it is the attribution an
         * administrator reads off `deploymentConnectionFor` to decide whether a team connection is
         * legitimate and who to ask about it. This writer held `actorId`, the session subject
         * (`users.id`) the attempt is keyed on and the id the admin read joins `users` on, and
         * recorded none of it: an Arcade-consented Shared app's row was permanently null, and the
         * page then said nobody connected it. The null is a real state for rows written before
         * this, which is why both readers keep answering `null` rather than inventing a name.
         *
         * AND THE RE-CONSENT SUPERSEDES, which is `recordBrokeredConnection`'s rule spelled the
         * same way: a deployment account is shared, so the administrator who most recently
         * completed a consent for it is the one the row credits. Unconditional here, unlike there,
         * because this path always holds an actor — there is no caller that passes none.
         */
        const connectedBy =
          input.account.holder === "deployment" ? input.actorId : null;
        await transaction
          .insert(brokeredConnections)
          .values({
            // The broker this row was actually minted at, which is this store's own — never a
            // literal, for the reason `recordBrokeredConnection` sets out at length.
            provider: brokerProvider,
            app: input.toolkit,
            holder: input.account.holder,
            userId:
              input.account.holder === "person" ? input.account.userId : null,
            vendorUserId: input.account.vendorUserId,
            connectedBy,
            ...set,
          })
          .onConflictDoUpdate(
            input.account.holder === "person"
              ? {
                  target: [
                    brokeredConnections.provider,
                    brokeredConnections.app,
                    brokeredConnections.userId,
                  ],
                  targetWhere: sql`${brokeredConnections.holder} = 'person'`,
                  // The identity the grant was just made under, for `recordBrokeredConnection`'s
                  // reason: calls go out under the row's id, so a re-consent that left the old one
                  // standing sent them to an account this consent says nothing about.
                  set: { ...set, vendorUserId: input.account.vendorUserId },
                }
              : {
                  target: [
                    brokeredConnections.provider,
                    brokeredConnections.app,
                  ],
                  targetWhere: sql`${brokeredConnections.holder} = 'deployment'`,
                  set: {
                    ...set,
                    vendorUserId: input.account.vendorUserId,
                    connectedBy,
                  },
                },
          );

        await recordAuditEvent(
          createAuditStore(transaction as unknown as Database),
          {
            eventType: "mcp.account_connected",
            targetType: "mcp_server",
            // The app, the id every other writer of this event files a brokered connection under,
            // so one query answers what happened to one person's access to one app however it
            // began and however it ended.
            targetId: input.toolkit,
            payload: {
              actor: input.actorId,
              server: input.toolkit,
              /*
               * WHAT THE VENDOR GRANTED, WHICH A BROKERED ROW HAS NEVER BEEN ABLE TO SAY BEFORE.
               * Both Composio writers carry `""` because Composio holds the grant and never tells
               * this deployment what it covers; Arcade does tell us, on the key all four writers
               * already agree on, so the same query reads both.
               */
              scope: input.scopes.join(" "),
              // The action the attempt was for: what this grant was obtained in order to call.
              action: input.action,
              authProvider: input.authProvider,
              reconnected: Boolean(existing),
              holder: input.account.holder,
            },
          },
        );
        return { claimed: true };
      });
    },

    /**
     * Close an attempt as `failed` or `unreconciled`, matched on `(actor_id, auth_id)`.
     *
     * ON THE PAIR AND NOT ON `created_at`, unlike {@link recordAuthorizationMint} and
     * {@link discardAuthorizationAttempt}, because the caller here is the returning callback and
     * all it holds is the `ar_...`. An attempt with no `auth_id` matches nothing, which is correct:
     * no callback can be about an attempt that never minted one.
     *
     * CONDITIONAL ON `completed_at IS NULL`, exactly as the completion above is: an attempt that
     * has settled — completed, failed, unreconciled or withdrawn — is not reopened by a later
     * callback, and `false` says so. See {@link closeAuthorizationAttempt} for what the asymmetry
     * used to be and what it cost.
     */
    async failAuthorizationAttempt(input: {
      actorId: string;
      authId: string;
    }): Promise<boolean> {
      return await closeAuthorizationAttempt(input, "failed");
    },

    /**
     * Mark an attempt whose outcome this deployment could not settle — the vendor answered, and
     * what it answered could not be reconciled with the attempt. Kept apart from `failed` so an
     * operator can tell "the person declined" from "we do not know what happened".
     */
    async markAuthorizationUnreconciled(input: {
      actorId: string;
      authId: string;
    }): Promise<boolean> {
      return await closeAuthorizationAttempt(input, "unreconciled");
    },

    /**
     * Mark an attempt whose consent completed at the vendor and which this deployment then refused
     * and ended by withdrawing the grant — neither a decline nor an unknown. An operator seeing a
     * run of these is seeing apps whose mode is being switched inside a consent window, which is a
     * different problem from people declining.
     */
    async markAuthorizationWithdrawn(input: {
      actorId: string;
      authId: string;
    }): Promise<boolean> {
      return await closeAuthorizationAttempt(input, "withdrawn");
    },

    /**
     * The live attempt for a session subject (`users.id`, never `credentialActorId`), or null when
     * there is none, it is past the 15-minute TTL, or it has completed.
     */
    /**
     * Whether this attempt's completion COMMITTED — asked of the row the transaction serializes on.
     *
     * FOR ONE CALLER AND ONE QUESTION: `/arcade/verify`'s completion rejected, and "the call threw"
     * is not "the work rolled back". A connection lost on the way back from a COMMIT the server had
     * already applied rejects at the client over a grant that is written down, and the verifier
     * telling that person `not-recorded` sends them to mint a second consent at the vendor against
     * a connection they already hold. The attempt row is the one place that can say which happened:
     * {@link createPluginStore}'s `completeAuthorizationAttempt` stamps `outcome = 'completed'` in
     * the first statement of the transaction, so the stamp exists exactly when the transaction did.
     *
     * NOT {@link authorizationAttemptFor}, which cannot answer this. It filters on `completed_at IS
     * NULL` AND on the fifteen-minute TTL, so it answers `null` for a completed attempt and for an
     * expired one alike — and a verifier that read "no live attempt" as "it committed" would
     * report a grant that is not there for any completion that ran long enough to age out.
     *
     * MATCHED ON `(actor_id, auth_id)` like the closers above and never on `created_at`, because
     * what the caller holds at this point is the `ar_...`. A rival callback having completed the
     * same attempt first answers `true` here, which is correct: the grant is recorded either way,
     * and this deployment has never been able or willing to tell the winner from the loser.
     */
    async authorizationAttemptCompleted(input: {
      actorId: string;
      authId: string;
    }): Promise<boolean> {
      const [row] = await database
        .select({ actorId: pendingAuthorizations.actorId })
        .from(pendingAuthorizations)
        .where(
          and(
            eq(pendingAuthorizations.actorId, input.actorId),
            eq(pendingAuthorizations.authId, input.authId),
            eq(pendingAuthorizations.outcome, "completed"),
          ),
        );
      return row !== undefined;
    },

    async authorizationAttemptFor(
      actorId: string,
    ): Promise<PendingAuthorization | null> {
      const [row] = await database
        .select()
        .from(pendingAuthorizations)
        .where(
          and(
            eq(pendingAuthorizations.actorId, actorId),
            isNull(pendingAuthorizations.completedAt),
            sql`${pendingAuthorizations.createdAt} >= now() - interval '15 minutes'`,
          ),
        );
      return row ?? null;
    },

    /**
     * File `mcp.authorization_cancelled` for an attempt its own person has just retracted.
     *
     * CALLED ONLY AFTER {@link discardAuthorizationAttempt} ANSWERED TRUE, by the cancel route and by
     * nothing else. The same deletion also tidies up after a refused or unrecorded mint, and those
     * are this deployment cleaning up after itself, not a person withdrawing consent — so the row is
     * filed here, for the one caller whose act it describes, and not inside the deletion.
     *
     * TARGETED AT THE APP'S SLUG, read off the attempt's server row with {@link toolkitOfFor}, which
     * is the id `mcp.account_connected` and `mcp.account_disconnected` file a brokered app under, so
     * one query on the target answers every ending of one app's consent. An attempt OUTLIVES what
     * its row's url says — an administrator can re-point the row while a consent is in flight, and
     * the cancel route deliberately still lets the person retract it — and once the url names no
     * app the row's own id is the only name left for what was cancelled, so that is what the row is
     * filed under; `serverId` is in the payload either way.
     *
     * WHO DID IT GOES IN THE PAYLOAD, as on every writer here, never in `actorUserId`. And the
     * payload carries NEITHER the consent url NOR the attempt's `auth_id`: the attempt row never held
     * the url, and the vendor's handle is not needed to say what a person withdrew. `minted` is
     * whether a flow had been started at the vendor at all.
     */
    async recordAuthorizationCancelled(input: {
      actorId: string;
      attempt: PendingAuthorization;
    }): Promise<void> {
      const [row] = await database
        .select({ url: mcpServers.url })
        .from(mcpServers)
        .where(eq(mcpServers.id, input.attempt.serverId))
        .limit(1);
      const toolkit = row ? toolkitOfFor(brokerProvider, row.url) : null;
      await recordAuditEvent(auditStore, {
        eventType: "mcp.authorization_cancelled",
        targetType: "mcp_server",
        targetId: toolkit ?? input.attempt.serverId,
        payload: {
          actor: input.actorId,
          server: toolkit,
          serverId: input.attempt.serverId,
          action: input.attempt.action,
          holder: input.attempt.holder,
          minted: input.attempt.authId !== null,
        },
      });
    },

    /**
     * A cancelled consent whose grant was left live at the vendor. See `mcp.cancelled_grant_left_live`.
     * Filed under the app's slug, beside the `mcp.authorization_cancelled` row the cancel filed.
     */
    async recordCancelledGrantLeftLive(input: {
      actorId: string;
      attempt: PendingAuthorization;
      toolkit: string;
      why: string;
      siblings: readonly string[];
    }): Promise<void> {
      await recordAuditEvent(auditStore, {
        eventType: "mcp.cancelled_grant_left_live",
        targetType: "mcp_server",
        targetId: input.toolkit,
        payload: {
          actor: input.actorId,
          server: input.toolkit,
          serverId: input.attempt.serverId,
          action: input.attempt.action,
          holder: input.attempt.holder,
          why: input.why,
          siblings: [...input.siblings],
        },
      });
    },

    /**
     * Spend one call on this person's key, and say what the vendor made of it.
     *
     * ONE PROBE, TWO CALLERS, AND THE ANSWER TO "WHAT DOES A FAILED PROBE MEAN" LIVES HERE ONCE.
     * {@link connectBrokeredWithFields} probes a key somebody has just typed;
     * {@link recheckBrokeredConnection} probes one this deployment has held for days. Both have to
     * choose the action the same way, send it the same way, and read the vendor's answer the same
     * way — and a second copy of that reading is how one of them comes to treat a rejected key as a
     * connection that merely could not be checked. What the two callers do NEXT is all that differs,
     * and it is all either of them keeps for itself: one withdraws the account it just made, the
     * other leaves an account it did not make alone.
     *
     * FOUR ANSWERS AND NOT A BOOLEAN, because `verified: false` means several different things
     * about somebody's key and the flag separates none of them. They are enumerated on
     * {@link BrokeredProbe}, which is where a reader should go; the one worth repeating at the call
     * this method makes is the fourth.
     *
     * A VENDOR THAT WAS NOT REACHED IS NOT A VENDOR THAT SAID NO, and this is the one place that
     * can tell. `callTool` answers with a result rather than throwing, and `isError` is true for all
     * three of the failures it documents — so read as a verdict here, a Composio outage, a socket
     * that closed, a `@composio/core` that cannot parse what came back and a run attributed to
     * nobody were every one of them "the vendor refused this key". What that cost is at the callers
     * and it was the worst thing this feature did: on connect the account somebody had just made
     * was deleted at the vendor and they were told what they entered did not work; on re-check a
     * live, working connection was stripped of its verification and marked as holding a bad key.
     * {@link ActionAnswer} is what the transport now answers beside the result, and this method
     * asks for it by calling `askAction` rather than `callTool`.
     *
     * A FAILURE IS RETURNED RATHER THAN THROWN, which is the one thing this function does not
     * decide. Its two callers end a bad key differently — one undoes an account and refuses, the
     * other writes the row unverified and refuses — so a throw here would force the undo on both or
     * neither. What it owes them is the vendor's sentence and the name of what was tried.
     *
     * NOTHING IS WRITTEN, NOTHING IS AUDITED, AND NO ACCOUNT IS TOUCHED. This is a question asked of
     * the vendor; recording the answer belongs to whoever asked it.
     */
    async probeBrokeredConnection(input: {
      toolkit: string;
      account: AccountRef;
      /**
       * THE ACCOUNT TO SPEND IT IN, where the caller has one in mind.
       *
       * {@link connectBrokeredWithFields} has just made an account and is asking about THAT key; a
       * person and an app do not name it, because one person may hold several accounts for one app
       * and the vendor picks which a call runs in. Unpinned, a bad key was verified by the person's
       * other, working account — and the same defect the other way round condemned a good key, and
       * deleted the account it made, on the strength of some other account of theirs being broken.
       *
       * ABSENT FOR A RE-CHECK, AND THAT IS A GAP RATHER THAN A CHOICE. `brokered_connections`
       * records no account id — a person's row is keyed on the person and the app, a deployment
       * row on the app alone — so a press of Re-check has nothing to pin to and asks the vendor
       * the same app-level question it always did. It is
       * the milder half: a re-check writes a verdict but takes nothing away, and its refusal tells
       * the person their key is wrong rather than removing anything they hold.
       */
      accountId?: string;
    }): Promise<BrokeredProbe> {
      /*
       * THE ONE ACTION THIS DEPLOYMENT WILL SPEND THE KEY ON, chosen from what the app published.
       *
       * Composio accepts a key without ever trying it, so "connected" at the vendor is not evidence
       * that the credential works — and a row written on that acceptance is a gate every later
       * brokered call passes for a key that cannot answer. {@link probeActionFor} is what keeps the
       * call safe: the vendor must have labelled the action a read and it must take no arguments,
       * and both matter because the first argument-less action on Stripe's own list creates a
       * billing session. It answers the VERSION beside the name, because Composio refuses an
       * execution without a specific one — so an action recorded without a version is one the
       * chooser passes over rather than one this method discovers it cannot call. Null is an
       * ordinary answer — see that method — and it is the FIRST of the three states above.
       *
       * NOTHING IS ASKED A SECOND TIME HERE, AND THAT IS THE POINT. Every condition on whether an
       * action can be spent on a key lives in the chooser, so the action this method sends is the
       * action the chooser said was sendable, whole. A version re-read here would be a second
       * predicate for one question, and the weaker of two predicates is what once had a reloaded
       * page tell somebody their untried key had been rejected — in the days when the connections
       * listing answered by asking the chooser too. It no longer does: what a page says about a
       * check is what the check recorded, and what it recorded is the name this method returns.
       *
       * AND THE APP IS RESOLVED BY ITS URL, THE WAY EVERY OTHER BROKERED LOOKUP HERE IS — through
       * {@link brokeredAppRow}, which is the one read that decides it. The url is where a brokered
       * row records which app it is; `mcp_servers.id` is a display name and nothing holds the two
       * equal — which is exactly why {@link connectBrokeredWithFields}, {@link
       * recheckBrokeredConnection} and {@link disconnectBrokered} all key on the url, and why {@link
       * brokeredConnectionsFor} resolves on it rather than spelling `composio-${toolkit}` by hand.
       * Composing it here made this method the one place that re-derived the id from a convention,
       * and it put the two halves of the `checkable`/`probe` split back into disagreement on any
       * row where they differ: the listing answered `checkable` off the app's real row while this
       * answered off an id addressing nothing, so the button was offered and the press could never
       * find anything to spend — the Re-check deadlock the split exists to prevent, reached from
       * the other end. Worse where the composed id DID hit something: a row called `composio-gmail`
       * at `composio://slack` would have this choose a stranger's probe off another app's listing
       * and spend their key on it. A row this deployment has since removed drops out here as null,
       * which is the same honest answer the listing gives for it: there is no app left to check.
       *
       * AND THE SHARED READ RATHER THAN A URL QUERY OF ITS OWN, because `mcp_servers.url` has no
       * unique index and an unordered `limit(1)` over it is not an answer. A second row at the app's
       * url — the ordinary state of any database where a fixture sits beside the `composio-` row an
       * administrator really added — had this resolve to whichever row the scan met first while the
       * listing named the app by the lower id, which is the SAME deadlock one step along: Re-check
       * offered off the app's own row, and the press landing on a row that publishes no action and
       * reporting there was nothing to try. One function decides which row answers for an app, so
       * nothing here can name one row while something else names another.
       */
      const app = await brokeredAppRow(input.toolkit);

      const candidate = app ? await this.probeActionFor(app.id) : null;
      if (candidate === null) {
        return { outcome: "nothing", probe: null };
      }

      /*
       * THE TRANSPORT DIRECTLY, AND NOT `callTool` ABOVE. This deployment's own `callTool` checks a
       * grant, evaluates the policy and writes an `mcp.call_*` row, and there is no Bot here to
       * check a grant for, no policy context to evaluate and no Bot to attribute a row to. What
       * holds this narrow is structural rather than disciplinary: no endpoint, no arguments, and an
       * action chosen from recorded metadata rather than from anything a request said. See
       * `mcp.connection_verified` in `./audit`, which records the same three properties as the
       * reason this call may skip the checks the ordinary path cannot — and which names both of
       * this function's callers as the whole of who may make it.
       *
       * THE VERSION IS NOT AN ARGUMENT. It travels under the transport's reserved key, which the
       * Composio transport strips before anything reaches the vendor and asserts that it did, so
       * what Composio is handed is the action and an empty argument object.
       */
      /*
       * AND ON ANY OTHER BROKER THIS REFUSES RATHER THAN DIALS, because `composioAskAction` is
       * Composio's own `askAction` and no counterpart has been written for a second broker.
       *
       * CRITERION. A deployment whose broker is not Composio gets a stated refusal here, and no
       * request leaves this process.
       *
       * REASON. The url this used to compose was `composio://<toolkit>` whatever the broker was, so
       * an Arcade deployment's check was sent to Composio with a Composio-shaped url. On a
       * deployment holding no Composio key that fails at a vendor it has no business talking to and
       * the person is told their connection could not be checked — an outage reported where there
       * was none. Where a Composio key IS present it is worse: the slug is a plain app name, so the
       * call lands on an UNRELATED app of the same name at the wrong vendor and succeeds, and the
       * row records a verified check of an account nobody holds.
       *
       * `unreachable` IS THE HONEST OUTCOME, not `nothing`. Nothing was learned about the key and
       * nothing is recorded about it — `probe` is null, so {@link _ProbeOutcomeLeaves} leaves the
       * row untouched and `probe_action` unwritten — and `attempted` is what WOULD have been spent,
       * which is the fact about this deployment's intent that field exists to carry. The sentence
       * names the state rather than blaming the connection, because the gap is ours.
       *
       * TODO: delete this once a probe is designed for the second broker. Until then a refusal that
       * says so is the only answer that is not a claim about somebody's account.
       */
      if (brokerProvider !== "composio") {
        return {
          outcome: "unreachable",
          probe: null,
          attempted: candidate.name,
          sentence: `This deployment brokers its apps through ${BROKERED_PROFILE[brokerProvider].vendor}, and the only connection check this deployment knows how to make is Composio's. Nothing was asked about this connection, so nothing is recorded about it.`,
        };
      }

      const { result, answered } = await composioAskAction(
        {
          url: `${BROKERED_PROFILE.composio.scheme}${input.toolkit}`,
          actorId: input.account.vendorUserId,
          // Spread rather than passed as `undefined`, so "any account of theirs" reaches the wire
          // as a body with no such key. See {@link ComposioActions.execute}.
          ...(input.accountId === undefined
            ? {}
            : { accountId: input.accountId }),
        },
        candidate.name,
        { [VERSION_ARG]: candidate.version },
      );

      /*
       * THE READING, AND IT IS THE WHOLE OF WHAT THIS METHOD DECIDES. `answered` is the transport's
       * own statement that Composio ran the action in the account and said how it went; `isError`
       * then says what it said. Anything else is an outage or an answer this deployment could not
       * read, and neither is evidence about a key — so the action's NAME is withheld from those,
       * because the name beside `verified: false` is the accusation and only a call that can be
       * shown to have run may make it.
       */
      if (!answered) {
        return {
          outcome: "unreachable",
          probe: null,
          attempted: candidate.name,
          sentence: result.text,
        };
      }

      /*
       * AND `isError` SAYS THAT THE CALL WENT BADLY, NOT THAT THE KEY IS BAD. The envelope this is
       * read out of is `{ data, error, successful }` and nothing more: a 429, a scope this one
       * action needs and the key legitimately lacks, and a 404 for a resource the read action names
       * all arrive here identically to a credential the vendor rejected. So the outcome is named
       * for what was observed — the app complained — and the two readings that treated it as a
       * verdict about the credential are gone from both callers. See {@link BrokeredProbe}.
       */
      return result.isError
        ? {
            outcome: "complained",
            probe: candidate.name,
            sentence: result.text,
          }
        : { outcome: "answered", probe: candidate.name };
    },

    /**
     * Ask Composio whether this person's account is really attached, and write down the answer.
     *
     * THE VENDOR IS ASKED, NOT THE BROWSER. The return trip from a consent screen is an ordinary
     * redirect carrying nothing signed, so a person arriving back on the page is not evidence that
     * they finished the flow, nor that the account they finished it with is the one a row would
     * claim. A confirm that wrote a row because somebody came back would hand every later brokered
     * call a gate that passes for an account nobody has — and the first anyone would hear of it is
     * the vendor's own error about a connection it cannot find, at the moment a Bot was asked to do
     * something.
     *
     * SO THE ANSWER NO LEAVES NO ROW BEHIND. `false` from {@link ComposioBroker.isConnected} is a
     * positive claim that there is no account, and the honest local state for that claim is an
     * absence — so a row already sitting here is deleted rather than left standing. Leaving it
     * would have the settings list go on drawing "Connected" for an account nobody has, and would
     * go on passing the gate every later brokered call is decided on, while the app's own detail
     * page asks the vendor and says the opposite.
     *
     * AND THAT DELETION FILES NO TRAIL ENTRY. Nobody disconnected anything here: the grant ended
     * somewhere else, and this is our record catching up with a fact. {@link disconnectBrokered}
     * owns `mcp.account_disconnected` and files it for the act it performed; a second filer here
     * would have the trail claim an act that did not happen, credited to whichever page load
     * happened to notice.
     *
     * UPSERT RATHER THAN INSERT, keyed on the pair the table itself is keyed on. This is safe to
     * call repeatedly and is meant to be: because the row is only a cache of the vendor's answer
     * (see {@link brokeredConnection}), a row that drifted out of step — an account ended in
     * Composio's own dashboard, a connect this deployment missed the callback for — is healed by
     * the next confirm on any page load, in whichever direction it drifted: by the upsert here
     * where the vendor says yes, and by the delete above where it says no.
     *
     * AND THE YES WRITES A VERDICT ONLY WHERE CONSENT IS THE CHECK, which is the one thing a reader
     * of this method has to carry away. `verified: true` beside a null `probeAction` is not a
     * neutral heal: it is a NAMED one of the four states {@link composioConnections.probeAction}
     * enumerates — the consent state — and this method runs from an effect on mount, so writing it
     * unconditionally meant every page load restated it over whatever a real check had recorded.
     * For a key connection that erased the record, worst of all over "a named probe beside
     * `verified: false`", the live account with a bad key behind it that is the one state somebody
     * must act on; and it re-dated `verified_at` to the page load, so the row claimed a check on a
     * day nothing was checked. The yes itself does not bear on a key: {@link
     * ComposioBroker.isConnected} says an account is attached, Composio takes a key when it is
     * typed and never tests it again, so for a key app that answer is what the row's existence
     * already said. The branch is on the scheme recorded on the app's row, classified through {@link
     * brokeredAppKind} as {@link connectBrokeredWithFields} and {@link recheckBrokeredConnection}
     * classify theirs, and a key row already here is left untouched — the evidence about a key is a
     * call, and those two are the only writers of this row's verdict. A key app the vendor holds an
     * account for with no row here still gets one, written UNCHECKED, because the row is the gate
     * every later brokered call passes through and the only thing Disconnect works off.
     *
     * AND THE FLAG IS WRITTEN FOR A CONSENT APP RATHER THAN FOR ANYTHING THAT IS NOT A KEY APP. A
     * scheme this deployment cannot read — a null, or a literal nothing here writes — is neither
     * kind, and it takes the key app's treatment: nothing recorded is overwritten, and a person the
     * vendor holds an account for still gets the row that is their permission. See {@link
     * SchemeKind} for why that third answer has to travel rather than be flattened into the second.
     *
     * `scope` IS EMPTY BECAUSE COMPOSIO GRANTS NONE THAT IT TELLS US ABOUT. The field exists so a
     * later refusal for want of a permission can be explained by what the vendor actually granted,
     * and Composio's connection answer is a boolean with no scope in it. Writing a plausible claim
     * there — the app's full access, say — would put words in the vendor's mouth in the one field
     * whose whole job is to say what it said.
     *
     * `reconnected` IS FALSE FOR THE SAME REASON, and trivially so. The flag distinguishes somebody
     * replacing a grant from somebody making one, and the only confirms that reach the trail are
     * the ones that found no row at all — so there was nothing here to replace.
     *
     * AND THE EVENT IS WRITTEN ONLY WHERE THE ROW IS NEW. This method runs on every page load
     * rather than only when a person acts, so an event per yes from the vendor would file ten
     * "account connected" rows for somebody who opened the connector page ten times having
     * connected once. A confirm that heals a row nothing changed is a read, and the trail records
     * acts: where a row was already there the connection has been recorded once already, by the
     * confirm that first found none.
     */
    async confirmBrokeredConnection(input: {
      toolkit: string;
      account: AccountRef;
      by: string;
    }): Promise<{ connected: boolean }> {
      // Before anything, and for the reason `addBrokeredApp` says it first too: a deployment with
      // no key has no broker to have connected anybody at, so there is nothing here to ask.
      if (!broker) throw new BrokerUnconfiguredError(brokerProvider, "person");

      const connected = await broker.isConnected({
        account: input.account,
        toolkit: input.toolkit,
      });
      if (!connected) {
        // Deleted rather than left alone, because the row is only the vendor's last answer: an
        // account ended in Composio's own dashboard reaches this deployment as the no above and
        // as nothing else, and a row that outlived it would go on saying yes about an account the
        // vendor has just denied.
        await database
          .delete(brokeredConnections)
          .where(accountRow(input.toolkit, input.account));
        return { connected: false };
      }

      /*
       * READ BEFORE THE WRITE, because the upsert leaves nothing behind that tells the two cases
       * apart, and whether a row was already here is the whole of what decides if anybody acted.
       *
       * AND THE VERDICT IS READ BESIDE THE ROW'S EXISTENCE, which is the consent arm's business.
       * `verified` here is the difference between "this deployment has already recorded the
       * vendor's yes" and "it has not", and the write below is conditioned on it so that a mount
       * cannot re-date a consent that was recorded days ago. The column is read directly rather
       * than through {@link brokeredConnection}, which answers with the connection date alone.
       */
      const [held] = await database
        .select({ verified: brokeredConnections.verified })
        .from(brokeredConnections)
        .where(accountRow(input.toolkit, input.account))
        .limit(1);
      const existing = held !== undefined;

      /*
       * THE SCHEME ON THE APP'S ROW, WHICH IS WHAT DECIDES WHETHER THE YES ABOVE IS A CHECK.
       *
       * Keyed on the url and on the one row that answers for it — see {@link brokeredAppRow} — which
       * is the read {@link connectBrokeredWithFields} and {@link recheckBrokeredConnection} both
       * make: `mcp_servers.id` is a display name and nothing holds the two equal, so a row called
       * `gmail` at `composio://slack` would decide a Slack confirm on Gmail's scheme, and a second
       * row at the app's own url would have this confirm branch on a scheme the re-check beside it
       * disagrees with. Asked through {@link brokeredAppKind} rather than compared as a string, so
       * the schemes this branches on cannot drift from the schemes that have a key behind them.
       *
       * AND THE QUESTION IS "IS THIS A CONSENT APP", NOT "IS THIS NOT A KEY APP", which are the same
       * question only if the column can always be read.
       *
       * CRITERION. `verified: true` is written here for an app this deployment KNOWS connects by
       * consent, and for no other.
       *
       * REASON. This branched on {@link isFieldScheme} alone, so every other answer — a consent
       * scheme, a literal from a deployment that knew other names, a NULL — fell into the consent
       * arm by elimination. A null is not a consent app: it is a column this deployment cannot read,
       * which {@link mcpServers.authScheme} calls a row that is not brokered and which the row that
       * ANSWERS for an app is perfectly free to carry — no unique index stands behind that url, so
       * the row an enable wrote its scheme onto is not always the row found here. Confirm runs from
       * an effect on mount, so the elimination wrote `verified: true` with a fresh `verified_at` and
       * a null probe over that row on every page load: a verdict about evidence nobody has, dated to
       * the day somebody opened a page, over whatever a real check had recorded. The other two
       * readers of this column already fail closed on the null — {@link recheckBrokeredConnection}
       * refuses the press, {@link disconnectBrokered} claims no revocation — so the one caller that
       * could not survive being wrong was the only one failing open.
       *
       * SO AN UNREADABLE SCHEME IS TREATED AS A KEY APP IS, and that is the cautious half in both
       * directions: nothing already recorded is overwritten, and the row that is the gate is still
       * written where the vendor holds an account nothing here has a row for.
       */
      const kind = await brokeredAppKind(input.toolkit);

      /**
       * WHAT THIS CONFIRM ANSWERS FOR EACH KIND OF APP, WRITTEN DOWN BECAUSE THE CHAIN CANNOT BE.
       *
       * Type-only and erased; see {@link Decides}. The chain below tests ONE member and then tests
       * something else — `kind === "none"`, `kind === "consent"`, then `!existing` — so there is no
       * position where the compiler has this vocabulary narrowed away and nothing here would fail
       * for a fifth member.
       * This is the caller that WRITES, and it is the one that could not survive being wrong: it
       * runs from an effect on mount, so whatever it decides for a member nobody named is decided
       * again on every page load.
       *
       * EVERY CELL IS NOW ASSERTED RATHER THAN DECLARED. `consent` used to be written as what the
       * code did rather than as what it should do — the re-stamp of `verified_at` on an
       * already-consented row was a live finding — and `none` did not exist as a member at all, so
       * a no-auth app was classified `consent` and got that same write on every mount. See the
       * table in `tests/composio-connection-kinds.test.ts`, which drives each of these four against
       * the running code.
       */
      type _ConfirmDecides = Decides<
        SchemeKind,
        {
          key: "leaves an existing row exactly as it is; records a new one as unchecked";
          consent: "records the vendor's yes as a verification the first time, and leaves an already-consented row alone";
          none: "writes nothing and files nothing — there is no account here for a row to be about";
          unreadable: "treated as a key app is — nothing already recorded is overwritten";
        }
      >;

      /*
       * AND THE CONSENT WRITE HAPPENS ONCE, WHICH IS THE OTHER HALF OF "A MOUNT DOES NOT RE-DECIDE".
       *
       * CRITERION. `verified: true` is written for a consent app only where this deployment has not
       * already recorded it. A row already carrying that verdict is left exactly as it is, its
       * `verified_at` included.
       *
       * REASON. The arm was unconditional, and this method runs from an effect on mount — so every
       * page load re-stamped `verified_at` to the moment of the load. The flag never changed, so
       * nothing looked wrong; what was destroyed was the DATE, which for a consent connection is
       * the day somebody finished at the vendor's own screen and is a fact nothing else in this
       * deployment records. The row's own sentence, "last checked 1 Sep", became "last checked
       * today" on a day nothing was checked, and the real date could not be recovered from anywhere.
       * {@link recheckBrokeredConnection} refuses to probe a consent app in order to protect exactly
       * that date; a confirm that re-stamped it on every mount destroyed from the inside what that
       * refusal protects from the outside. Two earlier fixes made this arm conditional for the key
       * case and then for the unreadable case and left the consent case — the one the arm is
       * actually FOR — writing on every load.
       *
       * AND A ROW NOT YET CARRYING THE VERDICT IS STILL HEALED, once. A consent app whose row was
       * written by some other path — a key-era connect, an enable that changed the app's scheme
       * afterwards — reads `false` with a null date, which is the pair "nobody has checked" and is
       * not true of a consented account. The vendor's yes above is the check for this kind of app,
       * so it is recorded, with the stamp of the moment it was first recorded here, and the next
       * mount finds the verdict already present and writes nothing.
       */
      /*
       * AN APP THERE IS NOTHING TO CONNECT TO GETS NO ROW, WHICH IS THE OTHER TABLE'S RULE APPLIED
       * HERE FOR THE FIRST TIME.
       *
       * CRITERION. Nothing is written and nothing is filed for a `none` app, whatever the vendor
       * answered about it.
       *
       * REASON. `NO_AUTH` used to be a member of the CONSENT list, so the classifier called it
       * consent and the arm below wrote `verified: true` with a fresh `verified_at` for it — on
       * every page load, because this runs from an effect on mount. That is precisely the row the
       * connect route refuses to create for these apps and the row the per-person gate is written to
       * do without: `composio_connections` is the whole of the permission for a brokered call, and
       * every row in it means one thing, that this person granted this deployment access to their
       * account at this app. There is no account — Composio refuses even to hold an authorization
       * config for a no-auth toolkit — and there is no grant, so a year on, offboarding, the trail
       * and the Disconnect button could not tell those rows from ones somebody really made.
       *
       * THE NEGATIVE HEAL ABOVE STILL RAN, and deliberately: a row left behind by the version that
       * wrote them is removed by the first mount that finds the vendor holding no account, which is
       * every mount for an app like this.
       */
      if (kind === "none") return { connected: true };

      if (kind === "consent" && !held?.verified) {
        // VERIFIED, BECAUSE A CONSENT SCREEN IS A VERIFICATION AND NOT A LESSER KIND OF ONE. The
        // vendor has just answered that this person's account is attached, which is the same
        // question a probe goes and asks; that the evidence arrived through a consent flow rather
        // than through a call this deployment made does not make it weaker. Writing on the column
        // defaults instead left every consent connection reading `false` with a null `verified_at` —
        // the pair a key somebody typed in and nobody ever checked reads — so the settings page could
        // not tell the two apart. Written through the single writer above rather than here, so this
        // path and the verify path cannot come to write two different row shapes; see
        // {@link composioConnections.verified}.
        await this.recordBrokeredConnection({
          toolkit: input.toolkit,
          account: input.account,
          connectedBy: input.by,
          verified: true,
          // NOTHING WAS SPENT TO EARN THAT FLAG, and that is what the null records rather than an
          // absence of information. A consent connection is verified by the vendor's own yes at its
          // own screen; no action of the app's is ever called against it, here or later, so there is
          // no name to write and there never will be. The derived field could not say so — it
          // answered with whatever the app happened to publish — and a consent row was listed as
          // having been checked with an action nothing had called.
          probeAction: null,
        });
      } else if (kind !== "consent" && !existing) {
        /*
         * A KEY APP THE VENDOR HOLDS AN ACCOUNT FOR AND NOTHING HERE HAS A ROW FOR: recorded as
         * UNCHECKED, which is the honest one of the four states for it. The account was made
         * somewhere this deployment did not watch — in Composio's own dashboard, or by a connect
         * whose row was lost — so no key of theirs has ever been tried from here, and null beside
         * `false` is exactly "nothing was spent". The row still has to exist: it is the gate every
         * later brokered call passes through, and the only thing Disconnect works off.
         *
         * AND AN APP WHOSE SCHEME CANNOT BE READ IS WRITTEN THE SAME WAY, for the same sentence
         * one word weaker: nothing here has ever checked this account, and nothing here knows what
         * checking it would even mean. `false` beside a null claims neither a check nor a refusal,
         * which is the only pair that is true of it — and the row is still the permission, so a
         * person whose account Composio holds does not lose their access to a column nobody wrote.
         */
        await this.recordBrokeredConnection({
          toolkit: input.toolkit,
          account: input.account,
          connectedBy: input.by,
          verified: false,
          probeAction: null,
        });
      }
      /*
       * AND AN EXISTING KEY ROW IS LEFT EXACTLY AS IT IS, which is the whole of what this branch
       * does and the reason there is a branch at all.
       *
       * THIS RUNS FROM AN EFFECT ON MOUNT. Both brokered account screens confirm on every page
       * load, so whatever is written here is written again every time somebody opens the page —
       * and `verified: true` beside a null `probeAction` is not a neutral heal. It is one of the
       * four states {@link composioConnections.probeAction} enumerates, and specifically the
       * CONSENT one: "the vendor's own yes is the evidence and no call was ever made against the
       * account". Written over a key row it erased the record of the last check and replaced it
       * with that sentence, including over the worst state this feature has — a named probe beside
       * `verified: false`, "it ran, the vendor refused the key, and the account is still standing"
       * — which is the one state an operator has to act on. It also moved `verified_at` to the
       * moment of the page load, so the row's own sentence, "last checked 13 Sep", named a day on
       * which nothing was checked.
       *
       * BECAUSE THE YES IS NOT EVIDENCE ABOUT A KEY. {@link ComposioBroker.isConnected} answers
       * that an account is attached, which for a key app is what the row's existence already said:
       * Composio takes a key when it is typed and never tests it again — the whole reason the probe
       * exists — so nothing in that answer bears on whether the key still works. Consent is the one
       * scheme where the vendor's yes IS the check, and it earns the flag above for that reason
       * alone. The evidence about a key is a call, and the two places that make one — {@link
       * connectBrokeredWithFields} and {@link recheckBrokeredConnection} — are the only writers of
       * this row's verdict. This one records what it learned by not writing.
       *
       * THE NEGATIVE HEAL IS UNTOUCHED, for all three kinds. A vendor answering NO still deletes the
       * row above, which is what a confirm on a key app is still worth running for.
       *
       * AND AN EXISTING ROW UNDER AN UNREADABLE SCHEME IS LEFT ALONE FOR A STRICTLY WIDER REASON.
       * For a key app the yes is not evidence; for an app whose scheme nothing here can read, it is
       * not known WHAT the yes is evidence of. Both answers are the same act — write nothing — and
       * it is the only act available that cannot claim more than was learned.
       */

      if (!existing) {
        await recordAuditEvent(auditStore, {
          eventType: "mcp.account_connected",
          targetType: "mcp_server",
          // The app, which is all a brokered connection is keyed on — the same id
          // `retireConnectionsFor` files its rows under, so one query answers what happened to one
          // person's access to one app however it ended.
          targetId: input.toolkit,
          payload: {
            actor: input.by,
            server: input.toolkit,
            scope: "",
            reconnected: false,
            holder: input.account.holder,
          },
        });
      }

      return { connected: true };
    },

    /**
     * Connect this person with the secret they typed, and write down everything except the secret.
     *
     * THE VALUES TRAVEL IN ONE DIRECTION AND THE WHOLE METHOD IS BUILT AROUND THAT. They arrive on
     * the request, they are handed to {@link ComposioBroker.connectWithFields}, and they reach
     * Composio. Nothing else here is given them: not the row, not the audit payload, not a log
     * line, not a thrown error — the broker's own doc comment is where that promise is kept on the
     * far side, and it is the one call in this tree that rethrows with no `cause` precisely because
     * the vendor's error object holds the key. Every other participant in this method is a
     * long-lived, widely-readable record, so a credential landing in one is not a leak somebody can
     * clean up afterwards; it is a leak with a retention schedule.
     *
     * THE SCHEME IS THE ONE RECORDED ON THE APP'S ROW, never a fresh read of the catalogue and
     * never a value a caller passed. It is what this deployment's authorization config was created
     * AS, and a connection is attached to that config: a second derivation is a second answer — a
     * key sent as `BASIC` against a config made for `API_KEY` — which is the reasoning {@link
     * ComposioBroker.connectionFields} gives for taking the scheme rather than resolving it, one
     * step earlier in the same flow.
     *
     * AND AN APP WHOSE SCHEME IS NOT A FIELD SCHEME IS REFUSED BEFORE THE KEY TRAVELS. A consent
     * app, a `NO_AUTH` app and an app this deployment could not resolve at all have no form and
     * nothing to attach typed values to, so sending them on would spend somebody's credential on a
     * config that cannot hold it — and would do it having already taken the secret out of the
     * request. {@link isFieldScheme} is asked rather than the string compared, for the reason it
     * exists: one list, read by the guard and by the type, so the schemes this admits cannot come
     * apart from the schemes the broker's signature takes.
     *
     * `connected` IS THE LITERAL `true` BECAUSE THERE IS NO OTHER WAY OUT OF HERE. Unlike {@link
     * confirmBrokeredConnection}, which asks a question the vendor may answer no to, this performs
     * an act: it either made the connection or it threw. A `boolean` would invite a caller to
     * branch on a `false` this method cannot produce.
     *
     * `probe` IS RETURNED BESIDE `verified` BECAUSE THE FLAG ALONE NOW MEANS THREE DIFFERENT THINGS,
     * AND THE BROWSER READS THIS FIELD TO CHOOSE ITS SENTENCE. While the row was written `false`
     * unconditionally the flag had one meaning — nobody has checked — and a screen could say so from
     * the flag alone. With a probe that can fail there are three states, and two of them share the
     * flag:
     *
     *   null probe, `verified: false`   — nothing was tried, so nothing is known about the key.
     *                                     Either this app publishes nothing safe to call, or the
     *                                     check could not be made — Composio unreachable, or an
     *                                     answer this deployment could not read. "It was accepted
     *                                     without being checked" is true of both, which is why
     *                                     they share the state; `checkable` on the listing is what
     *                                     tells the person whether pressing Re-check can ever help,
     *                                     and the trail carries the outage under `unreachable`.
     *   named probe, `verified: true`   — the action ran in this person's account and answered.
     *   named probe, `verified: false`  — it ran, the vendor said no, and the account could not be
     *                                     withdrawn. The key is BAD and the row exists anyway.
     *
     * That last one is the worst state this feature has, and under the old wording a person in it
     * would be told their key was never checked — when it was checked, the vendor rejected it, and
     * this deployment failed to undo the account it made. INFERRING THE STATE CLIENT-SIDE FROM
     * `verified` IS EXACTLY WHAT THIS FIELD EXISTS TO PREVENT: there is nothing in the flag that
     * separates "nothing to try" from "tried and failed", so a browser deriving a sentence from it
     * would tell one of those two people the opposite of what happened. The audit row carries the
     * same distinction under `action`, for a reader of the trail rather than of the screen.
     */
    async connectBrokeredWithFields(input: {
      toolkit: string;
      account: AccountRef;
      by: string;
      values: Record<string, string>;
    }): Promise<{ connected: true; verified: boolean; probe: string | null }> {
      // First, and for `confirmBrokeredConnection`'s reason: a deployment with no key has nobody to
      // connect anybody at, and the refusal must happen before the values are touched at all.
      if (!broker) throw new BrokerUnconfiguredError(brokerProvider, "person");

      // Keyed on the url and on the one row that answers for it — see `brokeredAppScheme`. It is
      // the same reasoning the connection gate in `connectionTokenFor` is keyed on, and for the
      // sharper version of the same stake: a row called `gmail` at `composio://slack` would have
      // somebody's Slack key attached to a scheme read off Gmail's row.
      /**
       * WHAT THIS CONNECT ANSWERS FOR EACH KIND OF APP, AND FOR EACH OUTCOME OF ITS OWN CHECK.
       *
       * Type-only and erased; see {@link Decides}. Two vocabularies meet in this one method — the
       * scheme decides whether it will run at all, and {@link BrokeredProbe} decides what the run
       * leaves behind — and each is read here by an equality test that a new member would sail
       * past. `isFieldScheme` is asked rather than {@link schemeKind}, so the two answers that are
       * not `key` reach one refusal by elimination; the roster is what says so out loud.
       */
      type _ConnectWithFieldsDecides = Decides<
        SchemeKind,
        {
          key: "connects, then checks the key it was just handed";
          consent: "refuses — not an app this deployment connects with values somebody types";
          none: "the same refusal — an app that needs no credential has nowhere to put one";
          unreadable: "the same refusal, reached by elimination rather than by decision";
        }
      >;
      type _ConnectWithFieldsRecords = Decides<
        BrokeredProbe["outcome"],
        {
          nothing: "the account stands, recorded unchecked with a null probe";
          answered: "the account stands, recorded verified under the probe's name";
          complained: "the account stands, recorded unchecked under the probe's name, and the press reports what the app said";
          unreachable: "the account stands, recorded unchecked, with the attempt on the trail";
        }
      >;
      const authScheme = await brokeredAppScheme(input.toolkit);
      if (!isFieldScheme(authScheme)) {
        throw new BrokerRefusalError(
          `${input.toolkit} is not an app this deployment connects with values somebody types, so nothing was sent. Open the app on the Plugins page and connect it the way it asks for; if it is not listed there at all, an administrator has to enable it first.`,
        );
      }

      const { accountId } = await broker.connectWithFields({
        account: input.account,
        toolkit: input.toolkit,
        authScheme,
        values: input.values,
      });

      /*
       * THE CHECK, WHICH IS THE SAME ONE A RE-CHECK MAKES AND IS SPELLED ONCE FOR THAT REASON.
       *
       * {@link probeBrokeredConnection} chooses the action out of what the app published — with the
       * version the listing recorded for it, which is part of what makes it choosable — calls it
       * with no arguments and reads what came back.
       * What belongs to THIS path and to no other is what happens next: an account this call has
       * just made, which a key the vendor rejects must not be allowed to leave standing. A re-check
       * runs the identical probe against an account that already existed and leaves it alone, and
       * those two undo behaviours are exactly why the shared part stops where it does.
       *
       * `probe: null` IS THE FIRST OF THE THREE STATES THIS METHOD REPORTS — the app published
       * nothing safe to call, or nothing at a version this deployment recorded, so the key was
       * never tried. It is an ordinary answer and not a failure; see that method.
       */
      const probed = await this.probeBrokeredConnection({
        toolkit: input.toolkit,
        account: input.account,
        /*
         * THE ACCOUNT THIS CALL JUST MADE, which is the only account this check is about. A person
         * and an app do not name one: Composio takes an account per key, somebody may hold several
         * for one app, and the vendor picks which a call runs in. So an unpinned probe verified a
         * key that does not work against the person's OTHER account — writing `verified` on the
         * strength of a call the new key never touched — and, the same defect pointing the other
         * way, condemned a perfectly good key and deleted the account it had just made because
         * some older account of theirs was broken. The undo below has always been keyed on this id;
         * this is what makes the check about the same account as the withdrawal.
         */
        accountId,
      });

      // Read before the write, for `confirmBrokeredConnection`'s reason: the record below is an
      // upsert, so it leaves nothing behind that tells a first key from a replacement, and whether
      // a row was already here is the whole of what `reconnected` says. The route that reaches
      // this today refuses a second account for the same app, which makes a constant `false`
      // accidentally true — but the guard lives in another file and this method is callable
      // without it, so the trail would be claiming, on that guard's word, something it never
      // checked.
      const existing = await this.brokeredConnection({
        toolkit: input.toolkit,
        account: input.account,
      });

      /*
       * THE CONNECT IS ON THE TRAIL BEFORE THE OUTCOME IS READ, AND THAT IS WHAT MOVING IT BUYS.
       *
       * The account exists by this line — `connectWithFields` above either made it or threw — and
       * from here the method has four ways out, one of which is the throw in the branch below.
       * Filed after that branch, this row was written on three of the four: a `complained` check
       * left a live account at Composio, a `composio_connections` row, and an
       * `mcp.connection_verified` row saying a check did not come back clean, with NOTHING saying
       * the account had ever been connected. `complained` is the ordinary outcome of a rate limit
       * or of one refused scope rather than an exotic one, so the trail lost the connect on the
       * path most likely to be walked — and the `mcp.account_disconnected` row filed when that
       * person later presses Disconnect had no counterpart to pair against.
       *
       * ABOVE `recordBrokeredConnection` RATHER THAN BELOW IT, because what this row asserts is
       * that the ACCOUNT was made, which the broker call above has already established, and not
       * that this deployment finished writing its own row about it. The two arms below disagree
       * about what that row says and agree about this.
       */
      await recordAuditEvent(auditStore, {
        eventType: "mcp.account_connected",
        targetType: "mcp_server",
        // The app, the same id `confirmBrokeredConnection` and `retireConnectionsFor` file under,
        // so one query answers what happened to one person's access to one app however it began
        // and however it ended.
        targetId: input.toolkit,
        payload: {
          actor: input.by,
          server: input.toolkit,
          /*
           * EMPTY, AND PRESENT, which is the whole of what this field does on a brokered row.
           *
           * All three writers of `mcp.account_connected` now agree on the key. {@link
           * recordConnection} carries what a vendor granted a `user-oauth` grant, and both brokered
           * writers carry `""` — a brokered connection has no scopes at all, because Composio holds
           * the grant and never tells this deployment what it covers.
           *
           * WRITING NOTHING IS NOT THE SAME AS WRITING THAT. This one wrote no key, so the same app
           * connected by two people came back as `''` from {@link confirmBrokeredConnection} and as
           * NULL from here, in a table whose entire purpose is being queried — and with nothing in
           * either row saying which writer made it, a reader cannot tell an absent scope from an
           * empty one, or either from a row written before the field existed.
           */
          scope: "",
          reconnected: existing !== null,
          holder: input.account.holder,
          /*
           * THE NAMES AND NEVER THE VALUES. What a reader of the trail needs is which app somebody
           * connected and what it asked them for; the values are the credential itself, and an
           * audit row is exactly the kind of long-lived, widely-readable record they must never
           * reach.
           */
          fields: Object.keys(input.values).sort(),
        },
      });

      if (probed.outcome === "complained") {
        /*
         * THE ACCOUNT THIS CALL MADE IS LEFT STANDING, AND THAT REVERSES WHAT THIS BRANCH USED TO DO.
         *
         * It read the outcome as "the vendor refused the key" and acted on it: `revokeAccount` on
         * the id just created, then a refusal telling the person what they entered did not work.
         * The premise was that nothing should be left behind on a key that does not work — which is
         * a good rule for the fact it names and was being applied to a fact nobody had established.
         * A complaint is Composio saying the CALL failed, out of an envelope with no status and no
         * error code in it (see {@link BrokeredProbe}), so a 429 on the identity read, a scope this
         * one action wants, or a 404 for a resource it names all arrived here as "your key is wrong"
         * and destroyed a connection that had just been made correctly.
         *
         * THE TWO MISTAKES DO NOT COST THE SAME, WHICH IS WHAT SETTLES IT. Keeping the account of a
         * genuinely bad key leaves a live row at Composio that can do nothing, that every screen
         * here draws as unverified with the app's own words beside it, and that Disconnect ends in
         * one press. Deleting the account of a good key costs the person the key itself: it is gone
         * from Composio, it was never stored here, and getting back is fetching it from the vendor
         * and typing it again. One is a press, the other is an errand — so the recoverable mistake
         * is the one this branch is willing to make.
         *
         * SO THE STATE THIS WRITES IS THE ONE THE `probe` FIELD WAS ADDED FOR, reached now by the
         * ordinary path rather than only by a failed undo: the row exists, it is unverified, it
         * names the action the check was spent on, and the sentence carries what the app said. What
         * it no longer carries is a verdict about the credential, here or on any screen that draws
         * it.
         */
        await this.recordBrokeredConnection({
          toolkit: input.toolkit,
          account: input.account,
          connectedBy: input.by,
          verified: false,
          // THE ACTION THAT WAS TRIED, which is the half of this state the flag cannot hold. It is
          // the whole of what separates this row on a later page load from a key nobody ever tried,
          // and it is the same name the audit row below carries under `action`, for a reader of the
          // trail rather than of a screen.
          probeAction: probed.probe,
        });

        /*
         * AND THE TRAIL SAYS SO TOO, WHICH IS THE HALF THE SENTENCE BELOW CANNOT REACH. The refusal
         * is told to one person in one moment; what outlives it is an unverified row and a live
         * account at the vendor, and the person who most needs to know both exist is an operator
         * reading this trail a week later. Filed BEFORE the throw for the only reason that matters
         * here: every way out of this branch is that throw, so a row written after it is a row
         * never written.
         *
         * `action` IS THE PROBE THAT WAS TRIED, and it is what tells this row from the unchecked
         * one. Both say `verified: false`; only the name separates "this app published nothing safe
         * to call" from "it ran and the app answered with a failure".
         */
        await recordAuditEvent(auditStore, {
          eventType: "mcp.connection_verified",
          targetType: "mcp_server",
          targetId: input.toolkit,
          payload: {
            actor: input.by,
            holder: input.account.holder,
            action: probed.probe,
            verified: false,
          },
        });

        /*
         * AND THE SENTENCE REPORTS RATHER THAN ACCUSES. It said "what you entered did not work",
         * which is the one thing this branch cannot know. What it can say is all true: a check was
         * spent, here is what the app answered, the account is still there, and here are the two
         * presses that end it either way.
         */
        throw new PluginRefusedError(
          `${input.toolkit} was connected, and the check this deployment then ran against it did not come back clean: ${probed.sentence} That may be the key, and it may be the app — what came back does not say which — so the account is left standing and recorded as unchecked. Re-check it on the Plugins page once, and if it still will not answer, disconnect it and connect it again with a fresh key.`,
          null,
        );
      }

      /*
       * ONE OUTCOME EARNS THE FLAG AND THE OTHER TWO REACHING HERE DO NOT, which is the whole of
       * what is decided below. A probe that ran and answered is evidence the key works, exactly as
       * the vendor's yes at the end of a consent screen is evidence for {@link
       * confirmBrokeredConnection}. An app that published nothing safe to call is the honest
       * unchecked state {@link composioConnections.verified} documents. And a vendor that could
       * not be reached is the SAME unchecked state, arrived at a different way — which is the one
       * thing a reader of this branch has to take away, so it is written out rather than left to
       * the union.
       *
       * AN OUTAGE IS AN ABSENCE OF EVIDENCE AND THE ROW HAS A STATE FOR THAT. It is not a fourth
       * thing to store: `probe_action` records the action a check SPENT, and a call that reached
       * nobody spent none, so null beside `verified: false` says exactly what is true — this key
       * has not been checked. What it must never become is the other `verified: false`, the one
       * with a name beside it, because that pair is the accusation "it ran and the vendor refused
       * your key" and the settings page draws it as such. {@link BrokeredProbe} withholds the name
       * from this outcome so the writer below cannot record it even by accident.
       *
       * AND THE ACCOUNT STAYS, which is the half the person would not get back. The undo above is
       * for a key the vendor REFUSED; a key nobody could ask about is very probably fine, and
       * deleting somebody's account because Composio was down destroys the thing they just made to
       * tell them something that was never established. The Re-check button is what settles it
       * afterwards — the app publishes an action, so the settings page offers one — and this is why
       * the connect answers rather than refusing: nothing went wrong with what they typed.
       *
       * Written through the single writer below rather than spelled here, so this path and the
       * confirm path cannot drift into two row shapes — `verified_at` follows from the flag there
       * and is not passed in.
       */
      const probe = probed.probe;
      const verified = probed.outcome === "answered";

      await this.recordBrokeredConnection({
        toolkit: input.toolkit,
        account: input.account,
        connectedBy: input.by,
        verified,
        // What was spent, which is the name on a probe that ran and the null that IS the first of
        // the three states: this app published nothing safe to try the key on. `verified` is
        // derived from this same value a few lines above, so the row cannot claim a check with an
        // action beside a flag that says nothing checked it, or the other way about.
        probeAction: probe,
      });

      /*
       * THE CHECK ITSELF, ON THE TRAIL, WHETHER OR NOT ONE HAPPENED.
       *
       * Filed on every connection rather than only where a probe ran, because "this app published
       * nothing safe to call, so the key was never tried" is the fact a reader most needs and the
       * one nothing else records. `action` is the null the response field is: it separates an
       * unchecked connection from a checked one, which `verified: false` alone cannot.
       *
       * THE FAILED UNDO ABOVE FILES THE SAME ROW BEFORE IT THROWS, so the worst state this feature
       * has — a live account, an unverified row, and a withdrawal the vendor refused — is no longer
       * named only in a sentence one person read once. The clean undo files nothing, and the reason
       * is written out at that branch: this trail records state that persists, and a row there
       * would cost the failed-undo row the one meaning that makes it worth reading.
       *
       * UNDER THE APP SLUG, which is the id `mcp.account_connected` above, {@link
       * confirmBrokeredConnection}, {@link disconnectBrokered} and {@link retireConnectionsFor} all
       * file under — so the two rows this method can write about one person's access to one app
       * come back in ONE query, however that access began and however it ended. This row was filed
       * under the SERVER row's id instead, on the reasoning that it is about an ACTION of a server
       * rather than about access; that is true and it cost the reader the only question anybody
       * asks this trail, which was answered half by one id and half by the other. Nothing goes with
       * the change: the server id is `composio-` and the slug, and the action is in the payload.
       *
       * AND THE OUTAGE IS NAMED HERE BECAUSE THE ROW CANNOT NAME IT. Two different things leave
       * this method with a null `action` — an app that publishes nothing safe to call, and a check
       * that could not be made — and on `composio_connections` they are one state, correctly: both
       * mean the key is unchecked, and neither says anything about the key. A reader of the TRAIL
       * is asking a different question, "was a check attempted and what became of it", and
       * `unreachable` is the whole of the difference, in Composio's own words. Present only on the
       * outage, so its absence is as informative as its value.
       *
       * AND CAPPED WHERE EVERY OTHER QUOTED FOREIGN STRING IN THIS FILE IS CAPPED, which this one
       * alone was not. `passableSentence` decides whether a candidate is worth repeating and says
       * nothing whatever about length; `askAction` then caps at `MAX_RESULT_CHARS`, which is 20_000
       * and is a bound written for a model's context window rather than for a row. So the sentence
       * arriving here can be fifty times what `refreshTools`' two `lastError` writes, the failed
       * undo's own reason a hundred lines up, and `callTool`'s two `failure` fields each allow
       * themselves — and `@composio/client` builds an `APIError` message out of an entire response
       * body, so a multi-kilobyte one is the ordinary arrival and not a contrived one.
       *
       * WHY THIS ROW AND NOT ANOTHER. `audit_events` is append-only by trigger, it is exported, and
       * it is kept for the deployment's whole retention window: a `lastError` written too long is
       * overwritten by the next refresh, and this is not. Whatever lands here cannot be cleaned up
       * afterwards, which makes the one uncapped write in the file the one that could least afford
       * to be.
       */
      await recordAuditEvent(auditStore, {
        eventType: "mcp.connection_verified",
        targetType: "mcp_server",
        targetId: input.toolkit,
        payload: {
          actor: input.by,
          holder: input.account.holder,
          action: probe,
          verified,
          ...(probed.outcome === "unreachable"
            ? { unreachable: probed.sentence.slice(0, 400) }
            : {}),
        },
      });

      return { connected: true, verified, probe };
    },

    /**
     * Try a key this deployment already holds, because somebody pressed the button that asks.
     *
     * A BUTTON, AND NEVER A PAGE-LOAD EFFECT. Composio never re-checks a key: it accepts one when it
     * is typed and says nothing about it again, so a row that was verified in March goes on saying
     * so after the key behind it was rotated, revoked or let expire. Nothing but this can correct
     * that — which is exactly the argument somebody will use for calling it from an effect when the
     * settings page mounts, and it is the wrong conclusion. The call this makes is spent against the
     * PERSON'S OWN rate limit at the vendor, on their account, so verifying on every render would
     * burn somebody's quota at Linear to redraw one word on a page they were only passing through.
     * {@link confirmBrokeredConnection} is the one that runs on mount, and it asks Composio a
     * question about its own records; this one goes out to the app.
     *
     * A RE-CHECK IS NOT A CONNECT, AND THE DIFFERENCE IS THE WHOLE METHOD. It runs against an
     * account that already exists: it must not create one, it must not withdraw one when the probe
     * fails — the person's account stays, it is their KEY that is wrong — and it must change
     * nothing here but the verification and its timestamp. {@link connectBrokeredWithFields} does
     * undo its account on a bad key, and it is right to: the account is a thing it had just made,
     * seconds earlier, for a key that turned out not to work. Here the account predates the press by
     * days, the person asked to have it CHECKED, and taking it away to tell them their key is wrong
     * would destroy the thing they are trying to repair. The shared probe stops short of both
     * behaviours for that reason.
     *
     * A PROBE THAT RAN AND FAILED RAISES, AND DOES NOT COME BACK AS `verified: false`. Those two
     * answers are not different spellings of one outcome. `false` is also what an app that publishes
     * nothing safe to call produces, and a row handed the flag alone cannot tell "the vendor
     * rejected your key" from "there was nothing here to try" — so it would draw the unchecked
     * sentence, and drop the Re-check button, for the one person who most needs it: somebody who has
     * just fixed their key and pressed it. The refusal carries Composio's own sentence, which is the
     * whole of what they can act on. The ONLY legitimate `verified: false` from here is the one that
     * arrives with `probe: null` saying there was nothing to check with.
     *
     * NOTHING TO PROBE WRITES NOTHING AT ALL, and answers with the row as it stands. A check that
     * could try nothing has learned nothing, and writing `false` on that would take the date off a
     * connection verified at a consent screen — a fact nothing else in this deployment records,
     * erased by a button that claims to check one. So the answer is what the row says after the
     * press, and `probe` is what says whether the press was able to try anything.
     *
     * THE ROW IS READ BEFORE THE VENDOR IS CALLED, and its absence is a refusal. The writer below is
     * an upsert, so a re-check that probed first and recorded the answer would INSERT a connection
     * for somebody who has none — the row that is the whole of the gate every later brokered call
     * passes through, created by a button that only asks a question. The probe itself would be spent
     * on an account the vendor does not hold, and would come back "no connected account found": this
     * deployment's own state, shown to somebody as though their key had been rejected.
     *
     * NO BROKER IS REFUSED BEFORE ANY OF IT, though nothing here calls the broker. The broker and the
     * transport are built from the same key, so a deployment without one has neither — and the probe
     * would come back as the transport's "Composio is not configured for this deployment", which
     * this method would otherwise report as the vendor rejecting a perfectly good key, and would
     * write the row unverified on the strength of it.
     *
     * AND A CONNECTION WITH NO KEY BEHIND IT IS REFUSED HERE RATHER THAN IN THE BROWSER. There is
     * nothing to re-check on a consent connection: the person authenticated at the vendor's own
     * screen, this deployment holds no credential of theirs, and the row's `verified_at` is the
     * date that screen earned — a fact nothing else here records. A probe spent on it would be a
     * call against their account that this method then reads as evidence about a key that does not
     * exist, and the likely failure would write `verified: false` with a null timestamp: a button
     * that claims to CHECK a connection, destroying the only record that one was ever checked. That
     * is precisely what the nothing-to-probe branch above is written to protect, and an app that
     * happens to publish a safe action walks straight past it. The screen does not offer the button
     * for a consent app, but a route takes POSTs and not only button presses, so the refusal
     * belongs where {@link connectBrokeredWithFields} puts its own: on the SCHEME RECORDED ON THE
     * APP'S ROW, asked through {@link isFieldScheme} so the schemes this admits cannot drift from
     * the schemes that have a key to admit.
     */
    async recheckBrokeredConnection(input: {
      toolkit: string;
      account: AccountRef;
      by: string;
    }): Promise<{
      verified: boolean;
      verifiedAt: string | null;
      probe: string | null;
    }> {
      if (!broker) throw new BrokerUnconfiguredError(brokerProvider, "person");

      // Keyed on the url and on the one row that answers for it — see `brokeredAppKind`. It is the
      // read `connectBrokeredWithFields`, `confirmBrokeredConnection` and `disconnectBrokered` all
      // make, for the same stake: a row called `gmail` at `composio://slack` would decide a Slack
      // re-check on Gmail's scheme. Anything but a key refuses, a scheme nothing here can read
      // included — there is no key recorded to re-check, and the sentence below is the same one
      // either way.
      /**
       * WHAT THIS RE-CHECK ANSWERS FOR EACH KIND OF APP, AND FOR EACH OUTCOME OF THE CHECK.
       *
       * Type-only and erased; see {@link Decides}. `!== "key"` is a boolean read of a three-member
       * vocabulary: it happens to fail closed for both of the other two today, which is why nothing
       * has gone wrong here yet and also why a fourth member would inherit that answer without
       * anybody choosing it. The probe roster below is the vocabulary this method reads FOUR ways,
       * and it is the one that has already been added to once.
       */
      type _RecheckDecides = Decides<
        SchemeKind,
        {
          key: "spends a call against the key this deployment holds";
          consent: "refuses — there is no key here to re-check";
          none: "the same refusal — there is no account, let alone a key, to check";
          unreadable: "the same refusal, which is the closed direction";
        }
      >;
      type _RecheckRecords = Decides<
        BrokeredProbe["outcome"],
        {
          nothing: "writes nothing and files nothing; answers the held row beside a null probe";
          answered: "records verified under the probe's name, and files the check";
          complained: "records unchecked under the probe's name, files the check, then reports what the app said";
          unreachable: "writes nothing and files nothing; refuses with Composio's own sentence";
        }
      >;
      if ((await brokeredAppKind(input.toolkit)) !== "key") {
        throw new PluginRefusedError(
          `${input.toolkit} is not an app this deployment holds a key for, so there is nothing here to re-check. It was connected at ${input.toolkit}'s own sign-in screen, and if it has stopped working, disconnecting it on the Plugins page and connecting it again is what fixes it.`,
          null,
        );
      }

      const [held] = await database
        .select({
          verified: brokeredConnections.verified,
          verifiedAt: brokeredConnections.verifiedAt,
        })
        .from(brokeredConnections)
        .where(accountRow(input.toolkit, input.account))
        .limit(1);

      if (!held) {
        throw new PluginRefusedError(
          `You have no connection to ${input.toolkit} here, so there is nothing to re-check. Connect it on the Plugins page and it will be checked as it is made.`,
          null,
        );
      }

      const probed = await this.probeBrokeredConnection({
        toolkit: input.toolkit,
        account: input.account,
      });

      /*
       * THE VENDOR WAS NOT REACHED, SO THE RECORD OF THE LAST CHECK IS LEFT EXACTLY WHERE IT IS.
       *
       * This is the branch the whole four-state reading exists for on this path. A failed probe
       * used to mean one thing here — "the vendor rejected the key it is holding" — so an outage,
       * a socket that closed, or a `@composio/core` that could not parse an answer cleared
       * `verified`, dropped `verified_at` (the only record anywhere that this connection was ever
       * checked, and the date the page prints) and wrote the named probe beside the `false`, which
       * is the accusation. Every person who pressed the button while Composio was down was told
       * their key had been refused, over a row that had been verified minutes earlier.
       *
       * NOTHING IS WRITTEN, WHICH IS STRONGER THAN WRITING SOMETHING HONEST. A press that learned
       * nothing may not move a record: there is no state for "we could not ask" on the row, and
       * there should not be — the row says what is known about the key, and an outage changes
       * nothing about that. It is the same restraint as the nothing-to-probe branch below, and
       * nothing is filed on the trail for the same reason it gives.
       *
       * AND IT RAISES RATHER THAN ANSWERING, which is where it parts from that branch. Somebody
       * pressed a button and is owed the truth about what happened to their press: the check did
       * not happen, and here is Composio's own sentence about why. Answering with the held row
       * instead would report the state as though the press had confirmed it.
       */
      if (probed.outcome === "unreachable") {
        throw new PluginRefusedError(
          `${input.toolkit} could not be checked just now: ${probed.sentence} Nothing here changed — your connection is still recorded exactly as the last check left it — so pressing Re-check again when ${BROKERED_PROFILE[brokerProvider].vendor} is answering is the whole of the retry.`,
          null,
        );
      }

      /*
       * NOTHING WAS TRIED, SO NOTHING IS WRITTEN AND NOTHING IS FILED. The row keeps whatever it
       * held — a consent verification and its date, or the honest unchecked pair — and the answer
       * reports that state beside the null probe that says why this press could not improve on it.
       * `mcp.connection_verified` records an account exercised with a REAL CALL; a row filed here
       * would make the one event that means "a key was tried" also mean "somebody pressed a button".
       */
      if (probed.outcome === "nothing") {
        return {
          verified: held.verified,
          verifiedAt: iso(held.verifiedAt),
          probe: null,
        };
      }

      // What the press spent, which from here on is a name: both outcomes left are a call that ran
      // and a vendor that answered about it.
      const probe = probed.probe;

      /*
       * THE ANSWER IS WRITTEN FOR BOTH OUTCOMES, and through the single writer for its reason: the
       * flag and its timestamp are one set, and a second hand spelling that set is how one of them
       * comes to leave a date standing on a claim nobody is making any more. A key the vendor has
       * just rejected stops being verified HERE — that is the state this button exists to correct,
       * in the direction nothing else in the product can move it.
       */
      const verified = probed.outcome === "answered";
      const { verifiedAt, wrote } = await this.recordBrokeredConnection({
        toolkit: input.toolkit,
        account: input.account,
        verified,
        // The action this press spent. Never null on this path: the nothing-to-probe branch above
        // returns before reaching the writer, precisely so that a check which could try nothing
        // writes nothing at all.
        probeAction: probe,
        /*
         * AND IT MAY NOT CREATE THE CONNECTION IT IS RECORDING A CHECK OF. The read at the top of
         * this method refuses a person with no row, deliberately, because this writer is an upsert —
         * but that read and this write straddle the vendor call above, which is live and takes
         * seconds. A Disconnect landing in that window revoked the grant at Composio and deleted the
         * row, and this upsert then put the row back: `composio_connections` is the whole of the
         * permission a brokered call is decided on, so the re-insert restored access to an account
         * the person had just ended, and drew the app as connected again.
         */
        only: "a row that is still there",
      });

      /*
       * THE ROW WENT WHILE COMPOSIO WAS BEING ASKED, SO NOTHING IS RECORDED AND NOTHING IS FILED.
       *
       * The two ways here are a Disconnect in another tab and a concurrent confirm that Composio
       * answered `false` for and which deleted the row. Both are somebody or something ENDING this
       * connection, and a verification row filed afterwards would be the trail recording a check of
       * an account that no longer exists — beside `mcp.account_disconnected` for the same app, in
       * whichever order the two happened to land.
       *
       * AND IT SAYS SO RATHER THAN ANSWERING QUIETLY, for the reason the outage branch above does:
       * somebody pressed a button and is owed the truth about their press. The answer is not the
       * probe's verdict, because the thing it was a verdict about is gone.
       */
      if (!wrote) {
        throw new PluginRefusedError(
          `Your connection to ${input.toolkit} was disconnected while this check was still running, so nothing was recorded about it: what the check found is about an account you no longer have here. Connect ${input.toolkit} again on the Plugins page if that was not what you meant.`,
          null,
        );
      }

      /*
       * AND THE TRAIL CARRIES THE CHECK, whichever way it went, filed BEFORE the refusal below for
       * the reason the connect path files its own row before its throw: every way out of a failure
       * is that throw, so a row written after it is a row never written. `action` is the probe that
       * ran, which is what separates this from a connection nothing was ever tried on.
       *
       * FILED UNDER THE APP'S BARE SLUG, as every row in this family is — the same id
       * `confirmBrokeredConnection`, `connectBrokeredWithFields` and `retireConnectionsFor` file
       * under — so one query still answers what happened to one person's access to one app.
       *
       * THE ROW NAMES A PERSON AND NO BOT, because none ran: this is somebody checking their own
       * account. See `mcp.connection_verified` in `./audit`, whose safety argument names a person
       * re-checking their own connection as one of the two callers this call may ever have.
       */
      await recordAuditEvent(auditStore, {
        eventType: "mcp.connection_verified",
        targetType: "mcp_server",
        targetId: input.toolkit,
        payload: {
          actor: input.by,
          holder: input.account.holder,
          action: probe,
          verified,
        },
      });

      if (probed.outcome === "complained") {
        /*
         * THE APP'S OWN SENTENCE, AND THE TWO FACTS AROUND IT: the row here now says unchecked, and
         * their account was left exactly as it was. The second half is what makes the retry one step
         * rather than three — there is nothing to disconnect and nothing to reconnect, only this
         * button to press again once whatever the sentence names has passed.
         *
         * AND IT REPORTS WHAT CAME BACK RATHER THAN RULING ON THE KEY. This said "would not answer
         * with the key it is holding", which reads as the vendor having rejected the credential —
         * and the envelope the outcome is decided from carries no status and no error code, so a
         * rate limit and a bad key are the same answer here. See {@link BrokeredProbe}. Moving the
         * row to unchecked is still right and is still the thing this button exists to do: whatever
         * the failure was, the check did not come back clean, so a standing `verified: true` is no
         * longer supported and must not keep standing.
         */
        throw new PluginRefusedError(
          `The check this deployment ran against ${input.toolkit} did not come back clean: ${probed.sentence} That may be the key and it may be the app — what came back does not say which — so your connection here is recorded as unchecked until a check does come back clean. Nothing was disconnected: press Re-check again in a few minutes, and fix the key at ${input.toolkit} if it keeps answering the same way.`,
          null,
        );
      }

      return { verified: true, verifiedAt: iso(verifiedAt), probe };
    },

    /**
     * End this person's brokered account at the vendor, and then forget where it was.
     *
     * REVOKE BEFORE DELETE, AND THAT ORDER IS THE WHOLE METHOD. The row is the only thing in this
     * deployment that says which app this person connected: the app is read off
     * `composio_connections`, and a revoke needs it. Delete first and a revoke that then fails
     * leaves a live grant on somebody's mailbox that no operation here can reach, because the one
     * value it would have to be revoked under is gone. The other order costs nothing by
     * comparison — a revoke that throws leaves the row standing, the person presses disconnect
     * again, and the second attempt has everything the first one had.
     *
     * WHICH ALSO MEANS THE FAILURE IS LOUD. Nothing is caught here: a broker that will not answer
     * ends this call, and no row and no trail entry claims an account was disconnected when the
     * account is still live.
     *
     * `vendorRevocationRequested` IS WHAT WAS ASKED FOR, NOT THAT A CALL WAS MADE — {@link
     * ComposioBroker.revoke}'s own answer, passed through. True where an account was found and its
     * withdrawal asked for, false where there was none to withdraw, and the value of the field is
     * exactly that a reader can tell an account this deployment acted on from one that outlives it
     * somewhere else.
     *
     * IT SAYS "REQUESTED" BECAUSE THE VENDOR'S ANSWER SUPPORTS NOTHING STRONGER, and the field was
     * renamed from `vendorRevoked` when that turned out to be false in the plainest way: the
     * adapter behind it was soft-deleting the account and asking for no upstream revocation at all,
     * so every row saying a grant had been withdrawn described one still live at Google. The ask is
     * now made; what a broker can promise synchronously is that the account is gone at Composio and
     * that the provider has been asked, because the withdrawal itself runs as a background job with
     * no supported way to poll it.
     *
     * EXCEPT WHERE THE APP IS ONE SOMEBODY TYPED A KEY INTO, AND THERE IT IS FALSE BY CONSTRUCTION
     * RATHER THAN BY WHAT THE VENDOR FOUND. `revoke_on_delete` asks the PROVIDER to end a grant,
     * which is a real request for a consent account — Google or Slack acts on it — and a
     * meaningless one for an API key. There is no grant behind a key to withdraw: the value is
     * still valid at the app and still works for anyone holding it, so the account ends at Composio
     * and nothing was asked of anybody else. Saying otherwise would be the one row in this trail
     * nobody could rely on, which is the failure the paragraph above describes arriving a second
     * time by a different road — a withdrawal recorded for something that was never granted. So the
     * scheme recorded on the app's row decides this field for a field connection, and the broker's
     * own answer decides it for every other.
     *
     * THE SCHEME IS THE ONE ON THE APP'S ROW, for {@link connectBrokeredWithFields}' reason: it is
     * what this deployment's authorization config was created AS and what the account was attached
     * to, and a fresh read of the catalogue is a second answer — a key connection described as
     * consent because the vendor has since started publishing managed OAuth for the app. The
     * person's half of this fact is already written on the disconnect row they are shown: their key
     * still works at the app, and rotating it there is what ends it. This is the trail's half of
     * the same sentence.
     *
     * THE VENDOR IS ASKED WHETHER OR NOT A ROW IS HERE. The row is a cache of Composio's answer
     * and never the account itself (see {@link brokeredConnection}), so its absence is not
     * evidence that the grant is gone: the confirm above deletes it on any `false` from the
     * vendor, and a person whose row was cleared that way can still be holding a live account at
     * Composio with nothing left here pointing at it. Asking anyway is the only operation in this
     * deployment that can end such a grant, and it costs nothing where there is genuinely nothing
     * to withdraw — the broker answers `false` and says so. Skipping the revoke for want of a
     * local row would make the safe half of disconnect unreachable for exactly the person who
     * needs it, on the strength of a cache we already know drifts.
     *
     * BUT THE TRAIL RECORDS ONLY A DISCONNECT THAT HAPPENED. The event is filed where something
     * actually ended — a row deleted here, or a grant withdrawn at the vendor — and not otherwise.
     * A call that found no row and withdrew no grant disconnected nothing, and an
     * `mcp.account_disconnected` row for it tells whoever reads the trail that somebody's account
     * ended at a moment when nobody's did. It is the criterion
     * {@link confirmBrokeredConnection} files its own event under, one act the other way round:
     * the trail records acts, and a call that changed nothing performed none.
     *
     * WHICH IS NOT THE SAME QUESTION AS `vendorRevocationRequested`. A row here with no grant at
     * the vendor is a disconnect — the gate this deployment decides every brokered call on was
     * open, and this call closed it — so the event is filed, saying
     * `vendorRevocationRequested: false`. A grant at the vendor
     * with no row here is a disconnect too, and the weightier of the two, because somebody's live
     * account was ended; the event is filed for that as well. Only where both are absent is there
     * no act to record, and the two cases stay legible in the trail because the field still says
     * which of them happened.
     *
     * SO THE FILING IS DECIDED ON THE BROKER'S OWN ANSWER AND NOT ON THE FIELD, because for a field
     * connection the two part company on purpose. A key account the vendor found and ended with no
     * row here is an act — somebody's live connection stopped existing — and gating the event on a
     * value that is false by construction would leave exactly that act unrecorded. The field
     * answers what was asked of the provider; `ended` answers whether anything was there.
     */
    async disconnectBrokered(input: {
      toolkit: string;
      /** Whose account ends — a person's own, or the one the deployment holds for a Shared app. */
      account: AccountRef;
      by: string;
      /**
       * Why the account ended, which is a closed set and not free text. A brokered account ends
       * in exactly four ways — the person disconnecting their own; the person being removed from
       * the People screen, which is the word {@link retireConnectionsFor} already files its own
       * rows under; an administrator disconnecting the deployment's account for a Shared app; and
       * the app being switched between Personal and Shared, which retires the accounts the old
       * mode held. A reader asking the trail which of them happened can be answered only if it is
       * the same word every time, so the type is the set rather than whatever sentence a caller
       * happened to spell.
       */
      reason: "self" | "person_removed" | "admin" | "mode_switched";
    }): Promise<{ vendorRevocationRequested: boolean }> {
      if (!broker) throw new BrokerUnconfiguredError(brokerProvider, "person");

      /*
       * Keyed on the url and on the one row that answers for it — see {@link brokeredAppKind}.
       * It is the read {@link connectBrokeredWithFields} makes, for the same stake: a row called
       * `gmail` at `composio://slack` would have this disconnect reading Gmail's scheme to describe
       * what happened to a Slack account.
       *
       * AN APP WITH NO ROW HERE IS NOT A FIELD APP, AND NEITHER IS ONE WHOSE SCHEME CANNOT BE READ.
       * A person can hold an account at Composio for an app this deployment has since removed — the
       * row is a cache and the removal takes no grant with it — and the revoke below is the one
       * operation that can still end it. Nothing names the scheme it was connected under any more,
       * so the honest reading is the broker's own answer, which is what both of those fall through
       * to: the field below is a claim that this deployment asked the vendor to withdraw something,
       * and an app it cannot say holds a key is one whose withdrawal it has to report as asked.
       */
      /**
       * WHAT THIS DISCONNECT CLAIMS ON THE TRAIL FOR THE ASKED APP, BY KIND. What it does about a
       * SIBLING of each kind is a different decision and is written down where it is made — see
       * rule 1 on {@link clearEndedSiblings}, which for a key DELETES NOTHING AND CLAIMS NOTHING
       * rather than claiming no revocation about a row it removed.
       *
       * Type-only and erased; see {@link Decides}. `=== "key"` collapses three answers into two,
       * and the collapse is deliberate here rather than accidental: the field below is a claim that
       * this deployment asked the VENDOR to withdraw something, and an app it cannot say holds a key
       * is one whose withdrawal it has to report as asked. That is a decision about `unreadable`,
       * and this roster is where it is written down as one.
       */
      type _DisconnectDecides = Decides<
        SchemeKind,
        {
          key: "claims no vendor revocation — nothing at the vendor holds this key";
          consent: "reports the vendor's own withdrawal as asked for";
          none: "reports whatever the vendor says it ended, which for an app with no account is nothing";
          unreadable: "reports it as asked for too, which is the claim that cannot be too weak";
        }
      >;
      /*
       * THE APPS THIS REVOCATION ENDS BESIDES THE ONE ASKED ABOUT, read BEFORE anything is revoked.
       * Where a connection is keyed `(identity, auth provider)` — Arcade — withdrawing one app's
       * connection ends every app that shares it, so a local row left for one of them claims an
       * account the vendor no longer holds, which is the other way to lie. Where each app is its
       * own auth provider — Composio — this is always empty and nothing below differs from a
       * disconnect of one. The question is {@link resolveSiblings}' and none of it is derived here.
       */
      const { siblings, unanswered } = await resolveSiblings({
        toolkit: input.toolkit,
        account: input.account,
      });

      /*
       * WHETHER THE ASKED APP IS ONE THIS DEPLOYMENT HOLDS A KEY FOR, which decides WHAT THE TRAIL
       * CLAIMS about it and nothing else. Its row goes either way: the person pressed Disconnect on
       * THIS app, the row is the whole of what Disconnect works off, and leaving it would be
       * refusing the act. The siblings are the opposite question — nobody asked about them — and
       * {@link clearEndedSiblings} answers it, rule 1 included.
       *
       * This was one `keyApps` set spanning the asked app and its siblings, and the set only ever
       * weakened the trail claim: a KEY sibling's row was deleted anyway, by the single OAuth
       * revoke that never ended it, leaving a live account at the vendor with no local row to
       * reach it.
       *
       * The claim is {@link vendorRevocationClaim}'s, which {@link removeServer} and
       * {@link retireConnectionsFor} make for their own asked apps: this method was the one of the
       * three that said `false` for a key, and now none of them says it for itself.
       */
      const claim = await vendorRevocationClaim(input.toolkit);

      // Whether there was an account to end at all, which is what decides if anybody was
      // disconnected. Named apart from the field below because for a key the two differ: something
      // ended, and nothing was asked of the provider.
      //
      // REVOKE BEFORE ANY LOCAL DELETE, and ONE ask: it ends the siblings with it. It THROWS on a
      // partial ask, which is the partial failure — the throw leaves this method before a single
      // row is deleted or written, every app's row standing, so pressing Disconnect again is the
      // recovery.
      const ended = await broker.revoke({
        account: input.account,
        toolkit: input.toolkit,
      });

      const asked = claim(ended);

      /*
       * THE ASKED APP FIRST, and on its own terms — this is the act, not a cascade of it.
       *
       * `deleted || ended` RATHER THAN RULE 3, deliberately and only here: a disconnect of an app
       * whose row this deployment never held is still a withdrawal the vendor made, and the trail
       * has to carry it. A SIBLING has no such act of its own to record, which is why
       * {@link clearEndedSiblings} files nothing without a row.
       *
       * `returning` because whether a row was here is half of what decides if anybody was
       * disconnected, and a delete that answered nothing would leave the two cases
       * indistinguishable.
       */
      const [deleted] = await database
        .delete(brokeredConnections)
        .where(accountRow(input.toolkit, input.account))
        .returning({ app: brokeredConnections.app });

      if (deleted || ended) {
        await recordAuditEvent(auditStore, {
          eventType: "mcp.account_disconnected",
          targetType: "mcp_server",
          targetId: input.toolkit,
          payload: {
            actor: input.by,
            server: input.toolkit,
            // Whose account this was, which is not always who ended it: an administrator
            // offboarding somebody and a person disconnecting themselves write the same shape of
            // row, and only these two fields tell them apart. The deployment's own account has
            // no person behind it, so it is named as the deployment rather than as whoever
            // pressed.
            owner:
              input.account.holder === "person"
                ? input.account.userId
                : "deployment",
            reason: input.reason,
            ...asked,
            /*
             * HOW MANY apps on this identity could not be asked about and so were left out of
             * the set below, never their names. An integer, so an operator can see that "we did
             * not know" happened; see {@link resolveSiblings}.
             */
            unansweredSiblings: unanswered,
          },
        });
      }

      // Then the apps that went with it, each naming the disconnect that ended it, by the three
      // rules that are written down once; see {@link clearEndedSiblings}.
      await clearEndedSiblings({
        siblings,
        account: input.account,
        endedWith: input.toolkit,
        revoked: ended,
        unanswered,
        by: input.by,
        reason: input.reason,
      });

      return asked;
    },

    /**
     * THE LOCAL SIDE OF A WITHDRAWAL SOMEBODY ELSE ALREADY MADE AT THE VENDOR: the rows this
     * deployment holds for an account a revoke has just ended, and the trail that says why they
     * went.
     *
     * WHO THIS IS FOR. The verifier refuses a consent whose context moved on and withdraws the
     * RETIRED identity's app at the vendor — a revoke it issues itself, outside this store,
     * because the decision is the route's and the attempt row is what records it. On Arcade that
     * one revoke ends the whole `(identity, auth provider)` connection and so every app sharing
     * it, and the rows here for those apps would otherwise be left standing: this deployment's own
     * records claiming live connections for apps the vendor has already disconnected. A person
     * then sees apps listed as connected that fail on first use, and nothing tells them otherwise.
     * This is the write that stops that, and it is a STORE method rather than route code for the
     * reason every other row write is: `brokered_connections` and the trail are this file's.
     *
     * IT ASKS NOTHING OF ANY VENDOR AND DECIDES NOTHING BUT WHAT A LOCAL ROW SAYS. The caller
     * resolved the siblings — of
     * {@link siblingApps}, BEFORE its revoke went out, which is the ordering {@link
     * disconnectBrokered} and {@link removeServer} both keep — and the caller watched its revoke
     * ANSWER TRUE. Called on anything less, it would be claiming an account gone on the strength
     * of an answer nobody got; that rule is {@link removeServer}'s and this one is its other half.
     *
     * ONLY A ROW THAT WAS ACTUALLY HERE GETS A TRAIL ROW, which is again {@link removeServer}'s
     * rule. The act itself is already recorded — on the attempt row, as `withdrawn` — so these
     * rows exist to explain why an app's connection VANISHED from this deployment's records, and
     * an app that had no row here had nothing to explain.
     *
     * THAT RULE AND THE TWO BESIDE IT NOW LIVE IN {@link clearEndedSiblings}, which this method
     * hands its siblings to and which {@link disconnectBrokered} and {@link removeServer} hand
     * their own to. They were spelled three times and the spellings disagreed about every one of
     * them.
     *
     * `reason` IS ONE WORD AND IT IS THIS ONE. "The consent's context moved on" is not any of the
     * four {@link disconnectBrokered} takes — nobody disconnected anything, nobody was offboarded,
     * and a mode switch is only one of the several ways the context can move — so the trail gets
     * its own word rather than the nearest-looking lie. Fixed in the type so there is no second
     * caller spelling it differently.
     */
    async clearWithdrawnAccount(input: {
      toolkit: string;
      account: AccountRef;
      /** The apps the caller's revoke ended besides `toolkit`; {@link siblingApps} answers it. */
      siblings: string[];
      /**
       * How many apps on this identity could not be asked about, an integer and never names, which
       * qualifies the `endedWith` claim and goes beside it and nowhere else; see
       * {@link resolveSiblings}.
       */
      unanswered: number;
      by: string;
      reason: "context_changed";
    }): Promise<{ cleared: string[] }> {
      const cleared: string[] = [];
      /*
       * THE ASKED APP FIRST, then the apps that went with it, so the trail reads in the order the
       * withdrawal happened. The asked app's own row names no other app beside it — it was ended
       * by its own ask — and a sibling's names the app that asked, which is the only thing that
       * tells a reader why a connection they never touched is gone.
       *
       * THE ASKED APP TAKES THE SAME THREE RULES, which is this method's whole difference from
       * {@link disconnectBrokered}'s asked app and is right for the same reason the rules are:
       * nobody here pressed anything about this app either. A caller's revoke ended an OAuth
       * connection for a RETIRED identity, so an app this deployment holds a key for was not in
       * it (rule 1); the caller watched that revoke answer true, which is the contract above and
       * is rule 2 discharged at the door; and a row that was not here had nothing to explain
       * (rule 3). The act itself is already recorded on the attempt row, as `withdrawn`.
       *
       * Rule 1 is asked of {@link consentRevokeReaches}, its one spelling, rather than of the kind
       * directly — this was the one site that compared the kind for itself (round 2, K5).
       */
      if (await consentRevokeReaches(input.toolkit)) {
        const [deleted] = await database
          .delete(brokeredConnections)
          .where(accountRow(input.toolkit, input.account))
          .returning({ app: brokeredConnections.app });
        if (deleted) {
          cleared.push(input.toolkit);
          await recordAuditEvent(auditStore, {
            eventType: "mcp.account_disconnected",
            targetType: "mcp_server",
            targetId: input.toolkit,
            payload: {
              actor: input.by,
              server: input.toolkit,
              owner:
                input.account.holder === "person"
                  ? input.account.userId
                  : "deployment",
              reason: input.reason,
              /*
               * TRUE FOR EVERY ROW HERE, AND IT IS NOT A GUESS: this method is reached only from a
               * revoke that answered true, and on Arcade that ask ended the siblings with the app
               * it named. `vendorRevocationRequested: false` means "no vendor was asked", which is
               * the one thing none of these rows may say.
               */
              vendorRevocationRequested: true,
            },
          });
        }
      }

      cleared.push(
        ...(await clearEndedSiblings({
          siblings: input.siblings,
          account: input.account,
          endedWith: input.toolkit,
          // The contract above: the caller watched its revoke answer true before calling this.
          revoked: true,
          unanswered: input.unanswered,
          by: input.by,
          reason: input.reason,
        })),
      );
      return { cleared };
    },

    /**
     * Retire every connector credential belonging to one person.
     *
     * WHAT THIS IS FOR. "We removed their access" has to be true of the thing that matters, which is
     * the refresh token sitting at the vendor. Removing somebody from the People screen used to end
     * their sessions and add them to the deny list, and leave their Google grant entirely intact in
     * this deployment's vault. They could not exercise it — the actor comes from a session they no
     * longer get — but the deployment still held a usable secret for a person who had been removed,
     * which is not what an administrator was told they did, and is the first thing a customer asks
     * about a per-person connector.
     *
     * LOOKED UP IN THE VAULT, NOT THROUGH THE JOIN TABLE. `mcp_user_credentials.user_id` cascades on
     * a user row being deleted, so by the time somebody is gone the join row can be gone too and the
     * credential is orphaned: unrevoked, referenced by nothing, reachable from no screen and by no
     * code path. `credentials.key_id` holds the user id for an `mcp_user_token`, so the vault can
     * still be asked directly — which makes this work for the person who was removed and for the one
     * whose row was deleted underneath it.
     *
     * The join rows go too, so the account pages stop claiming a connection this deployment can no
     * longer use.
     *
     * AND THE BROKERED CONNECTIONS, which are neither a credential nor a join row. Composio holds
     * the account, so there is no secret in the vault to find and the person's `brokered_connections`
     * row is itself the permission — the only thing deciding whether a call may go out as this person.
     * Sweeping the vault alone therefore left that gate passing for somebody who had been removed.
     *
     * NOT VENDOR-SIDE REVOCATION FOR THE VAULT HALF. That needs the OAuth client and the vendor's
     * revoke endpoint, and it belongs with disconnect. Those rows are the half that stops us
     * holding the secret; the grant at Google outlives it until somebody revokes it there. Said
     * plainly rather than implied, because the difference matters to whoever has to answer for it.
     *
     * THE BROKERED HALF DOES END IT AT THE VENDOR, because there is no secret of ours to stop
     * holding: clearing the row alone would shut the gate this deployment owns and leave the
     * mailbox attached at Composio, which is "we removed their access" being untrue of the only
     * thing that matters, for the person it matters most about. So every app this person connected
     * is revoked through the broker, exactly as {@link disconnectBrokered} revokes for one and
     * {@link removeServer} for a whole app.
     *
     * REVOKE BEFORE DELETE, ALWAYS. The row is the only thing that names which apps this person
     * had, and it outlives the `users` row precisely so offboarding can still find them — which
     * was the table's whole justification and until now was theoretical. A delete that ran first
     * would leave a failed revoke with nothing to revoke under: a live grant on a departed
     * person's mailbox that no operation in this deployment can reach. The other order costs a
     * repeat of an act nobody minds repeating. Nothing is caught around the revokes either, so a
     * broker that will not answer ends this method with the rows still standing rather than
     * letting it report an ending that did not happen.
     */
    async retireConnectionsFor(
      userId: string,
      by: string,
    ): Promise<{ retired: number }> {
      if (!userId) return { retired: 0 };

      const owned = await database
        .select({
          id: credentialRows.id,
          provider: credentialRows.provider,
          revokedAt: credentialRows.revokedAt,
        })
        .from(credentialRows)
        .where(
          and(
            eq(credentialRows.kind, "mcp_user_token"),
            eq(credentialRows.keyId, userId),
          ),
        );

      let retired = 0;
      for (const credential of owned) {
        // Already revoked is not a failure. Retiring twice is something an administrator can
        // legitimately do, and the second time should be quiet rather than an error.
        if (credential.revokedAt) continue;
        await credentials.revoke(credential.id);
        retired += 1;
        await recordAuditEvent(auditStore, {
          eventType: "mcp.account_disconnected",
          targetType: "mcp_server",
          targetId: credential.provider,
          payload: {
            actor: by,
            server: credential.provider,
            owner: userId,
            /*
             * Why, because the two reasons are not the same event to a reader. Somebody disconnecting
             * their own account is a person changing their mind; an administrator removing somebody
             * is an offboarding, and an auditor asking "what happened to their access" wants to see
             * which one this was.
             */
            reason: "person_removed",
            vendorRevocationRequested: false,
          },
        });
      }

      await database
        .delete(mcpUserCredentials)
        .where(eq(mcpUserCredentials.userId, userId));

      /*
       * Every app this person connected at the broker, where there is no secret to scan the vault
       * for.
       *
       * CRITERION. After this returns, no brokered call may go out on this person's behalf.
       *
       * REASON. A brokered connection is not a credential: Composio holds the account and this
       * deployment sends a user id, so the vault sweep above finds nothing and the person's
       * `brokered_connections` row is the entire gate. Reading only the vault therefore retired nothing for somebody whose only
       * connector was brokered, reported that as a retirement, and left the `(toolkit, user_id)` gate
       * passing for a person who no longer exists — their access outliving them, which is the first
       * thing anybody asks about a per-person connector. The table's own docblock justifies its shape
       * by this path, so the shape was carrying a promise nothing kept.
       *
       * FOUND HERE AND NOWHERE ELSE, which is what the missing foreign key buys. The row survives the
       * `users` row precisely so this can still name what the person had after they are gone — the
       * same argument the vault lookup above makes, from the side that has no vault row. It is also
       * why the guard at the top of this method is load-bearing rather than defensive: `not null`
       * admits the empty string, so a row at `(toolkit, "")` is legal, and retiring "nobody" must not
       * be what deletes it.
       *
       * COUNTED, because the number is what "we removed their access" claims. Retiring twice stays
       * quiet on its own: the rows are gone, so the second call finds none.
       *
       * READ BEFORE ANYTHING IS DELETED, because the revokes below need the apps and the rows are
       * where the apps are — the reason the docblock gives for revoking first. Sorted, so two
       * retirements of the same person revoke in the same order and write their rows in the same
       * order.
       */
      /*
       * NO PROVIDER PREDICATE HERE, DELIBERATELY, AND THAT IS NOT AN OVERSIGHT. The sweep below
       * revokes through the ACTIVE broker, so a row filed under another provider would be a
       * revocation requested at the wrong vendor, which would not recognise the connection, and an
       * audit row claiming `vendorRevocationRequested` about access that was never removed. What
       * keeps that unreachable is the startup activation refusal (`assertActivatable`, called from
       * `server/src/index.ts`): a deployment holding both providers' rows cannot boot. No flow relaxes
       * that refusal today; whoever builds one must add the `brokerProvider` predicate here.
       */
      const brokered = await database
        .select({ toolkit: brokeredConnections.app })
        .from(brokeredConnections)
        .where(
          and(
            eq(brokeredConnections.holder, "person"),
            eq(brokeredConnections.userId, userId),
          ),
        )
        .orderBy(asc(brokeredConnections.app));

      /*
       * THE APPS EACH OF THIS PERSON'S REVOCATIONS ENDS BESIDES THE ONE ASKED ABOUT, read BEFORE a
       * single revoke goes out and through {@link resolveSiblings}, the one place that answers it.
       *
       * WHY THIS LOOP NEEDS IT AT ALL, when it already asks about every app the person holds.
       * Where a connection is keyed `(identity, auth provider)` — Arcade — the FIRST app's revoke
       * ends the connection and every app sharing it, so the ask for a sibling that follows finds
       * nothing left and answers `false`. Passed through, that is `vendorRevocationRequested:
       * false` on the trail for a grant this deployment asked for and got, which is the one
       * reading of that field that must never be written: it says "no vendor was asked" about an
       * account that was withdrawn, to whoever later checks that an offboarding completed. The
       * order the rows come back in decides which app gets the truthful row and which gets the
       * false one, which is to say nothing decides it.
       *
       * Where each app is its own auth provider — Composio — every set here is empty by
       * construction, each ask stands alone, and nothing below differs from what this method
       * always did.
       *
       * RESOLVED AGAINST THE PERSON'S OWN IDENTITY, the same `account` the revokes below are asked
       * with. MEMOIZED ACROSS THE WHOLE OFFBOARDING for the reason {@link removeServer} gives:
       * `authProviderOf` is a live vendor call on Arcade, and the bound is then the number of
       * DISTINCT TOOLKITS this person holds rather than that number squared. Empty with no broker
       * configured, where nothing is asked of anybody and the `false` below is the whole truth.
       */
      const account = personAccount(userId);
      const authProviders = new Map<string, Promise<string | null>>();
      const endedBesides = new Map<
        string,
        { siblings: string[]; unanswered: number }
      >();
      if (broker) {
        for (const connection of brokered) {
          endedBesides.set(
            connection.toolkit,
            await resolveSiblings(
              { toolkit: connection.toolkit, account },
              authProviders,
            ),
          );
        }
      }

      /*
       * WHAT THE TRAIL MAY CLAIM WAS ASKED OF THE VENDOR FOR EACH APP, read before a single revoke
       * goes out, as {@link disconnectBrokered} reads its own. A KEY app's row says `false` whatever
       * the vendor answered — see {@link vendorRevocationClaim}, which all three writers of an asked
       * app's row now ask. This one used to pass the vendor's answer through for a key (round 2,
       * L5-a), the same divergence {@link removeServer} had (A5c).
       */
      const toRetire: {
        toolkit: string;
        claim: Awaited<ReturnType<typeof vendorRevocationClaim>>;
      }[] = [];
      for (const connection of brokered) {
        toRetire.push({
          toolkit: connection.toolkit,
          claim: await vendorRevocationClaim(connection.toolkit),
        });
      }

      /*
       * What the broker was actually asked for each app, kept so the trail below records the answer
       * rather than the call. False where there is no broker at all: a deployment whose key has
       * since been unset can still offboard somebody, and it could not have been calling Composio
       * either way — but nothing was asked there and the row must not claim otherwise.
       *
       * ONE APP'S REFUSAL IS ONE APP'S REFUSAL, and until now it was everybody's. A throw out of
       * `revoke` left this loop before the delete and before the trail, so three accounts already
       * withdrawn at Composio kept their rows and got no row on the trail. That was survivable while
       * repeating the act did nothing — and #574 made repeating it the documented recovery, so the
       * second pass asks again for those three, Composio answers `false` because the accounts are
       * gone, and each writes `vendorRevocationRequested: false` about a withdrawal this deployment
       * asked for and got. That field exists to tell an account we acted on from one that outlives
       * us somewhere else; those three rows say the wrong one.
       *
       * So the answer is kept per app and the refusal is held rather than thrown. Every app is still
       * asked — a later one is not punished for an earlier one — and the first refusal is rethrown
       * below, so the act still fails loudly and the administrator still gets a 500.
       */
      const withdrawn: {
        toolkit: string;
        requested: boolean;
        claim: Awaited<ReturnType<typeof vendorRevocationClaim>>;
      }[] = [];
      const refusals: unknown[] = [];
      for (const connection of toRetire) {
        try {
          withdrawn.push({
            toolkit: connection.toolkit,
            claim: connection.claim,
            requested: broker
              ? await broker.revoke({
                  /*
                   * THE PERSON'S OWN ACCOUNT, NAMED AS ONE. Offboarding somebody ends what they
                   * held and never the deployment's shared account, whoever connected it — so the
                   * holder is fixed above rather than read off anything, and the vendor id is the
                   * person's own, which is what a personal account is filed under at Composio. The
                   * SAME value the siblings were resolved against, because an answer about one
                   * identity describing a revocation on another is the whole of what that set is
                   * for.
                   */
                  account,
                  toolkit: connection.toolkit,
                })
              : false,
          });
        } catch (error) {
          /*
           * Held, and the row deliberately left standing.
           *
           * "An offboarding the vendor refuses leaves the connection standing" is the existing
           * criterion and it is unchanged: the row is the only thing naming which app this person
           * connected, repeating the act is the recovery, and repeating it is only possible while
           * the row is there. What changes is that the rule now applies to the app it is about
           * rather than to every app in the same act.
           */
          refusals.push(error);
        }
      }

      /*
       * Only the apps that answered, which is the other half of the same correction.
       *
       * Deleting by user id would take the rows of apps that were refused or never reached, and
       * those are exactly the rows the recovery needs. Deleting none — what a throw used to do —
       * leaves a row and an open `(toolkit, user_id)` gate for an account that is already gone at
       * Composio, so the table claims a connection this person does not have.
       */
      if (withdrawn.length > 0) {
        await database.delete(brokeredConnections).where(
          and(
            eq(brokeredConnections.holder, "person"),
            eq(brokeredConnections.userId, userId),
            inArray(
              brokeredConnections.app,
              withdrawn.map((entry) => entry.toolkit),
            ),
          ),
        );
      }

      /*
       * WHICH OF THIS PERSON'S APPS WERE ENDED BY ANOTHER APP'S REVOCATION, and by which one.
       *
       * Only from a revoke that ANSWERED TRUE: `false` means nothing was found to withdraw or the
       * auth provider could not be resolved, and the vendor was not shown to have ended anything,
       * so nothing is claimed on the strength of it — the rule {@link removeServer} files its
       * siblings by. The asked app is skipped in favour of its own answer, and the first ender
       * wins, which is deterministic because the rows are walked in app order.
       *
       * APPS THIS PERSON HOLDS ARE ALL THIS CAN SPEAK FOR. A sibling resolved on the same identity
       * but held by the deployment, or an app whose own revoke threw and so has no row here, is
       * left alone: this map only corrects what the loop below is already about to write.
       *
       * WHICH SIBLINGS A REVOKE ENDED IS {@link siblingsEndedBy}'S ANSWER, the one
       * {@link clearEndedSiblings} deletes on — rules 1 and 2 — and not a walk of this method's
       * own. It was one: rule 2 without rule 1, so a KEY app whose own ask answered false was filed
       * as ended by an OAuth sibling's revoke that never reached it (round 2, A5b). What differs
       * here is only what is DONE with the answer: this method deletes its own rows as its own acts
       * above, so it takes the judgement without the delete and files `endedWith` from it.
       */
      const endedWith = new Map<string, string>();
      for (const entry of withdrawn) {
        const ended = await siblingsEndedBy({
          siblings: endedBesides.get(entry.toolkit)?.siblings ?? [],
          endedWith: entry.toolkit,
          revoked: entry.requested,
        });
        for (const app of ended) {
          if (!endedWith.has(app)) endedWith.set(app, entry.toolkit);
        }
      }

      for (const connection of withdrawn) {
        retired += 1;
        /*
         * The app whose revocation ended this one, where this one's own ask came back empty
         * because that revocation had already taken it. Absent for an app that was ended by its
         * own ask, which needs no other grant named beside it.
         */
        const endedBy = connection.requested
          ? undefined
          : endedWith.get(connection.toolkit);
        const resolved = endedBesides.get(connection.toolkit);
        await recordAuditEvent(auditStore, {
          eventType: "mcp.account_disconnected",
          targetType: "mcp_server",
          // The app, which for a brokered connection is all the row records. The `mcp_servers` row
          // it belongs to may have been removed already, and the connection outlives that too.
          targetId: connection.toolkit,
          payload: {
            actor: by,
            server: connection.toolkit,
            owner: userId,
            reason: "person_removed",
            /*
             * What was asked of the vendor, not that a call was made — {@link
             * ComposioBroker.revoke}'s own answer, passed through, and the one place this half
             * differs from the vault loop above. There the grant at Google outlives our copy of
             * the secret and nothing was asked of anybody, so the field can only say false; here
             * there was no secret of ours and the account itself was deleted at Composio with its
             * withdrawal asked for, or there was nothing to ask about, or there was no broker to
             * ask. The value of the field is exactly that a reader can tell those apart, so a
             * constant here would be worse than none.
             *
             * OR WHAT WAS ASKED ABOUT THE CONNECTION THIS APP SHARES, which is the same claim
             * made about the same grant. On Arcade the ask that ended this app may have been
             * spelled with a sibling's name, and `revoke`'s `false` here then means "already
             * gone", not "nobody asked" — `endedWith` beside it names the app that asked.
             *
             * AND NEVER FOR A KEY: {@link vendorRevocationClaim} makes the claim from that
             * reading, and for a key app it is `false` whatever the vendor answered.
             */
            ...connection.claim(connection.requested || Boolean(endedBy)),
            /*
             * AND WHERE A SIBLING RELATIONSHIP IS BEING CLAIMED, HOW MANY apps on this identity
             * could not be asked about and so could not be ruled siblings either way — an
             * integer, never their names; see {@link resolveSiblings}. Beside `endedWith` and
             * nowhere else, which is where {@link removeServer} puts it and for its reason: the
             * count qualifies a claim about which apps went together, and a row making no such
             * claim would be carrying a number about nothing.
             */
            ...(endedBy
              ? {
                  endedWith: endedBy,
                  unansweredSiblings: resolved?.unanswered ?? 0,
                }
              : {}),
          },
        });
      }

      /*
       * Loud, after every app has been asked and every answer recorded.
       *
       * The first, because the route turns this into a 500 and one sentence is what reaches the
       * administrator; the rest are the same act failing more than once, and the trail above already
       * says which apps did not end. Thrown last rather than first so a refusal on one app cannot
       * cost the record of another — which is the whole of this change.
       */
      if (refusals.length > 0) throw refusals[0];

      return { retired };
    },
  };
}