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.

326 KB
Raw Blame
import {
  afterAll,
  afterEach,
  beforeAll,
  beforeEach,
  describe,
  expect,
  test,
} from "bun:test";
import { randomUUID } from "node:crypto";
import { MCPMock, type MCPToolDefinition } from "@copilotkit/aimock/mcp";
import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
import { readConnectPrompt } from "@openbot/shared/connect-prompt";
import { and, asc, eq, gte, inArray, sql } from "drizzle-orm";
import { createAuditStore } from "../src/audit";
import type { ActionPolicy } from "../src/computer/policy";
import {
  type CredentialStoreValue,
  createCredentialStore,
  decryptSecret,
  encryptSecret,
} from "../src/credentials";
import { createDatabase, type Database } from "../src/db/client";
import {
  agents,
  auditEvents,
  brokeredConnections,
  credentials as credentialRows,
  credentials,
  mcpServers,
  mcpTools,
  mcpUserCredentials,
  pluginGrants,
  users,
} from "../src/db/schema";
import {
  accessFor,
  CatalogueTransportUnroutableError,
  ServerRowAmbiguousError,
} from "../src/plugins/access";
import type { BrokerConnection, ComposioBroker } from "../src/plugins/broker";
import type { CatalogueEntry } from "../src/plugins/catalogue";
import { catalogueEntry } from "../src/plugins/catalogue";
import {
  type ComposioResult,
  useComposioClient,
} from "../src/plugins/composio";
import { actionOf } from "../src/plugins/composio-vendor";
import { redirectUriFor } from "../src/plugins/oauth";
import type { AccountRef } from "../src/plugins/shared-accounts";
import {
  type AccessToken,
  CustomServerRefusedError,
  createPluginStore,
  exchangeRefreshTokenOverHttp,
  INVALID_CLIENT,
  isDeploymentFault,
  type OAuthClient,
  PluginInvariantError,
  PluginRefusedError,
  type PluginStore,
  TokenRefusedError,
  unlistedAdvertisedTools,
} from "../src/plugins/store";
import { grantedTools, REFUSAL_MARKER } from "../src/plugins/tools";
import fileActions from "./fixtures/composio-file-actions.json";
import { TEST_POOL, testDatabaseUrl } from "./support/database";

/**
 * The two questions a tool call has to pass, and the row each answer leaves behind.
 *
 * The refusals are the property under test. A call that succeeds proves the plumbing works; a call
 * that is refused proves the governance does. Both refusals here stop before any network call, which
 * is itself the property being asserted: a tool a Bot was never given must not reach the vault or
 * the vendor, so there is nothing to stub.
 */

const database = createDatabase(testDatabaseUrl(), TEST_POOL);

const suite = randomUUID().slice(0, 8);
const holderId = `agent_plugin_holder_${suite}`;
const strangerId = `agent_plugin_stranger_${suite}`;
const serverId = "google-drive";
const toolName = "search_files";
const ref = `${serverId}/${toolName}`;
/** A tool on the same server that nobody is granted. Suite-scoped, so it is never a real one. */
const siblingToolName = `not_granted_${suite}`;

let policy: ActionPolicy = { mode: "enforce", deny: [], allow: ["true"] };

/**
 * Whether THIS RUN is what put the server row there, and so is what should take it away.
 *
 * The id is a real catalogue key rather than a suite-scoped one, because what is under test includes
 * the vendor's own read/write classification. On a database somebody is using, that key is their
 * configured server, so it is removed only when the test is what created it.
 *
 * Which is why the flag counts creations rather than the absences it used to. `afterAll` runs even
 * when a `beforeAll` above it has thrown, and every flag is then still sitting at its initialiser —
 * so a teardown must not be authorised by a setup that never completed. Only a capture that ran and
 * found the row missing can write the value the delete needs; `false` covers both "the deployment
 * already had it" and "nobody ever looked", and neither of those is this suite's row to remove.
 */
let suiteCreatedServerRow = false;
/**
 * Whether THIS RUN is what advertised the tool, and so is what should stop advertising it.
 *
 * The vendor really does advertise `search_files`, so the row may be a refreshed fact about the
 * vendor rather than the suite's fixture. Deleting by name regardless would take a real one; leaving
 * it always would leave a fixture that reads on screen as a tool the vendor offers.
 *
 * Set the same way round as {@link suiteCreatedServerRow} and for the same reason: the delete waits
 * on evidence that this run inserted the row, not on the mere absence of evidence that somebody else
 * did.
 */
let suiteCreatedToolRow = false;

const revokedCredentialIds: string[] = [];
const issuedCredentialIds: string[] = [];
/*
 * The exact fixtures a removal test attempted, so `afterAll` can take them away without going
 * back through `removeServer` — which is itself under test, and so cannot be what teardown
 * depends on. Written at the attempt rather than at the success, because a setup that failed
 * partway leaves rows behind too.
 */
const removalServerIds = new Set<string>();
const removalUserIds = new Set<string>();

/**
 * The vault, stubbed, shared by every store in this file that does not need a real one.
 *
 * Named rather than inlined into the store below so that {@link freshStore} passes the SAME stub:
 * a second copy would be a second place for "no credential is read here" to stop being true, and the
 * refusals below are what make that claim worth anything.
 */
const credentialsStub = {
  // No credential is ever read in these tests, because every call is refused before the vault.
  readSecret: async () => null,
  // Nor written in place. Loud rather than absent: a call reaching either of these would mean
  // this file had started exercising something it does not claim to, and a silent no-op would
  // hide that.
  create: async () => {
    throw new Error("this suite does not write credentials");
  },
  updateSecret: async () => {
    throw new Error("this suite does not write credentials");
  },
  // `removeServer` does revoke: it retires the token the server was configured with so a re-add
  // does not collide on `credentials_active_key_idx`. The stamp goes to the real row, because
  // `removeServer` reads liveness from the table before deciding whether to revoke at all.
  revoke: async (id: string) => {
    const revokedAt = new Date();
    await database
      .update(credentialRows)
      .set({ revokedAt, updatedAt: revokedAt })
      .where(eq(credentialRows.id, id));
    revokedCredentialIds.push(id);
    return revokedAt;
  },
};

const store = createPluginStore({
  brokerProvider: "composio",
  database,
  auditStore: createAuditStore(database),
  credentials: credentialsStub,
  encryptionKey: "x".repeat(44),
  policy: () => policy,
});

/**
 * When this run began, by the DATABASE's clock, so every audit query can exclude what came before.
 *
 * The trail is the one table this file cannot tidy up after itself: `audit_events` is append-only,
 * and 0012 closed the last way around that, so every row every previous run wrote is still there and
 * still matches. The refusals are recorded against `google-drive/search_files` and named by rules
 * about `google-drive` — production spellings, forced for the same reason the fixtures are — so a
 * query narrowed only by target and rule matches nine hundred rows this run had nothing to do with,
 * and an assertion that one exists is answered by a run that finished yesterday. That is a test
 * which cannot fail: deleting the code that writes the row would leave it green.
 *
 * Postgres's clock rather than this process's, because the two are not the same clock and the
 * comparison happens against a column the server stamps.
 *
 * Read through {@link sinceThisRun}, which refuses rather than defaulting: a bound of "the beginning
 * of time" is the unscoped query back again, silently.
 */
let runStartedAt: Date | null = null;

function sinceThisRun() {
  if (!runStartedAt) {
    throw new Error(
      "the run's start was never recorded, so no audit query can be narrowed to it",
    );
  }
  return gte(auditEvents.createdAt, runStartedAt);
}

async function auditRowsFor(targetId: string, botId: string, actorId: string) {
  return database
    .select({
      eventType: auditEvents.eventType,
      payload: auditEvents.payload,
      initiatorKind: auditEvents.initiatorKind,
      initiatorId: auditEvents.initiatorId,
    })
    .from(auditEvents)
    .where(
      and(
        eq(auditEvents.targetType, "mcp_tool"),
        eq(auditEvents.targetId, targetId),
        sinceThisRun(),
        eq(sql<string>`${auditEvents.payload} ->> 'bot'`, botId),
        eq(sql<string>`${auditEvents.payload} ->> 'actor'`, actorId),
      ),
    );
}

/**
 * Whether the guard below cleared this run to own the ids the Composio fixtures insert at.
 *
 * Read by the `afterAll` that removes those rows. A run the guard refused must not delete the rows
 * it refused over, and `afterAll` still runs after a `beforeAll` has thrown.
 */
let ownsFixtureIds = false;

/*
 * Refuse to run at all against a database that already holds the ids this suite inserts at.
 *
 * The suites above own suite-scoped ids and only ever READ the deployment's own rows, so skipping a
 * delete is enough for them — that is what `suiteCreatedServerRow` and its siblings are for.
 * The fixtures in this file cannot do that: they INSERT at `gmail`, `notion`, `bot_helper` and
 * `user_asker`, and those ids are not a choice. `gmail` is the toolkit slug that gets sent to
 * Composio. `notion` is fixed twice over: the dynamic-registration suite pins `dynamicServerId` to
 * it because that is the catalogue entry which registers its own client, and the test for an action
 * listed before the effect columns existed inserts a `notion` server row directly, because a
 * first-party row is what it is about. A fixture that inserts at an id cannot coexist with a real
 * row at that id: skipping the delete would only turn the collision into a primary-key conflict,
 * and capture-and-restore would be a lot of machinery whose failure mode is destroying the thing
 * it protects, because the cascade has already run by the time it restores.
 *
 * What the cascade takes is why this is a refusal rather than a warning. `mcp_user_credentials`
 * references `mcp_servers.id`, so removing a real `notion` row takes every person's per-user
 * credential row with it and leaves their encrypted vault rows referenced by nothing — unreachable
 * from any screen and invisible to `retireConnectionsFor`, which exists to stop exactly that state.
 * Removing a real Bot takes six tables: its channel memberships, its agent profile, everyone's
 * preferences for it, its routines and all of their run history, its component exclusions and its
 * plugin grants. Removing a real PERSON takes ten: their sign-in accounts and live sessions, their
 * roles, their channel memberships and intelligence mappings, their per-Bot preferences and written
 * instructions, their skills, their routines, and every per-user connector credential they hold —
 * and nulls the owner off their agent profiles and SSO provider besides. The fixtures then re-insert
 * byte-identical look-alikes, so nothing on screen would say it happened.
 *
 * The list below is every table this file deletes from at an id it did not invent — an id spelled
 * the way production spells it, so a row already sitting at it belongs to somebody else. Each of
 * `mcp_servers`, `agents`, `composio_connections` and `users` is asked about here, and nothing else
 * needs to be: `mcp_tools` and `plugin_grants` are the two remaining unconditional deletes and both
 * are reached only by a key that references one of these four — `mcp_tools.server_id` names a
 * server, `plugin_grants.agent_id` names a Bot — so a row at either could not exist without the
 * guard having already refused over its parent. Every other delete in this file names an id
 * carrying {@link suite}, and the reads that touch the deployment's own `google-drive` row skip
 * their delete instead, on the {@link suiteCreatedServerRow} flags above.
 *
 * So the deletes in {@link freshDatabase} are authorised by {@link ownsFixtureIds} and this is what
 * makes them safe.
 */
/**
 * Every `composio_connections` row this file may claim, as one clause used by all three sites.
 *
 * CRITERION. The pair set is an app crossed with a person: `gmail` or `linear`, held by
 * `user_asker`, by `user_leaver` or by the anonymous actor. The refuse-to-run guard, the per-test
 * sweep and the teardown ask exactly that question and nothing wider, and a fixture written at a
 * pair outside the cross has to widen one clause rather than three.
 *
 * A CROSS RATHER THAN A LIST, so it is a little wider than what the fixtures actually write — no
 * test here connects `user_asker` to `linear`. That is deliberate and it is safe in this one
 * direction: the guard runs first and has already established that no row sits anywhere in the
 * cross, so every pair the sweep and the teardown delete is a pair this run put there.
 *
 * REASON. They disagreed. The guard and the sweep asked by person across every app; one test's
 * cleanup asked by the anonymous actor across every app; the pair `("gmail", "")` was in none of
 * them. So the file refused to run on rows it does not create, deleted rows it did not create, and
 * left behind one that it did — three faces of one confusion about what makes a row this file's.
 * The app is half the answer: every row here is at a real app, because a Composio app IS its
 * toolkit slug and this file asserts things about the real ones — so naming the person alone
 * claims that person's rows at every other app as well.
 */
function ownedConnections() {
  return and(
    inArray(brokeredConnections.app, ["gmail", "linear"]),
    inArray(brokeredConnections.userId, ["user_asker", "user_leaver", ""]),
  );
}

beforeAll(async () => {
  /*
   * Stamped here, in the first hook the file registers, so no row this run writes is older than it
   * and no row an earlier run wrote is newer.
   */
  const [clock] = await database.execute<{ now: Date }>(
    sql`select now() as now`,
  );
  if (!clock) throw new Error("the database would not say what time it is");
  runStartedAt = clock.now;

  /*
   * ONE AT A TIME RATHER THAN `Promise.all`, and the reason is the driver rather than the queries.
   *
   * {@link TEST_POOL} holds two connections, so four reads issued together are pipelined two to a
   * connection, and Bun's postgres client names its prepared statements from the query text it is
   * given. Two of these four collide on that name: the five-parameter `composio_connections` read
   * binds against the statement prepared for the one-parameter `agents` read and Postgres refuses
   * with `bind message supplies 5 parameters, but prepared statement ... requires 1`. The guard
   * then throws out of the file's first hook, which takes every test in the file with it and
   * reports as one unnamed failure with no test name in it.
   *
   * Nothing here is waiting on anything else and four sequential reads of four empty tables cost
   * milliseconds, so there was never anything to win by issuing them together.
   */
  const configuredServers = await database
    .select({ id: mcpServers.id })
    .from(mcpServers)
    .where(inArray(mcpServers.id, ["gmail", "notion"]));

  const existingBots = await database
    .select({ id: agents.id })
    .from(agents)
    .where(eq(agents.id, "bot_helper"));

  /*
   * Brokered connections, keyed on the PAIR rather than on the person.
   *
   * CRITERION. This guard refuses on {@link ownedConnections} — two real apps crossed with
   * three people — and on no other `composio_connections` row, because every pair this file
   * inserts and every pair it deletes is inside that cross.
   *
   * REASON. Every connection row this file writes is at a real app, `gmail` or `linear` — the
   * two people it invents and the anonymous actor alike — so the app is half of what makes a
   * row this file's, and asking by person alone claims rows at every other app as well. Both
   * spellings of that over-reach have already cost something. `user_id = ''` caught the
   * anonymous row `composio-connections.test.ts` writes against its own run-suffixed app, so a
   * run of that file killed before its cleanup refused every test here for good; `user_id IN
   * (asker, leaver)` claims a `("slack", "user_asker")` row the same way, and `freshDatabase`
   * would then DELETE it — a `composio_connections` row is the entire gate on a brokered
   * call, and nothing else can find it again.
   *
   * The anonymous actor is one of the three people because `user_id` is notNull and notNull
   * does not exclude the empty string, so `("gmail", "")` is a row a deployment can legally
   * hold, which is the whole point of the test that inserts one.
   */
  const existingConnections = await database
    .select({
      toolkit: brokeredConnections.app,
      userId: brokeredConnections.userId,
    })
    .from(brokeredConnections)
    .where(ownedConnections());

  /*
   * The person, who was missing from this guard entirely.
   *
   * `user_leaver` is inserted at and deleted at by the Composio fixtures, and the delete used to
   * run whatever the guard had decided — so a real row at that id was removed, with the ten
   * cascades above behind it, on a run the guard had already refused.
   */
  const existingPeople = await database
    .select({ id: users.id })
    .from(users)
    .where(eq(users.id, "user_leaver"));

  const found = [
    ...configuredServers.map((row) => `the mcp_servers row '${row.id}'`),
    ...existingBots.map((row) => `the Bot '${row.id}'`),
    ...existingConnections.map(
      (row) =>
        `the brokered_connections row ('${row.toolkit}', '${row.userId}')`,
    ),
    ...existingPeople.map((row) => `the person '${row.id}'`),
  ];

  if (found.length > 0) {
    throw new Error(
      `This suite owns ${found.join(", ")} outright — it inserts at those exact ids and deletes ` +
        "them before every test — and refuses to run against a database that already has them, " +
        "because deleting a real server row takes every person's per-user credentials with it, " +
        "deleting a real Bot takes the six tables behind it, and deleting a real person takes the " +
        "ten behind them. Point TEST_DATABASE_URL at a scratch database.",
    );
  }

  ownsFixtureIds = true;
});

beforeAll(async () => {
  for (const id of [holderId, strangerId]) {
    await database
      .insert(agents)
      .values({
        id,
        name: id,
        type: "remote_ag_ui",
        configuration: {},
      })
      .onConflictDoNothing();
  }

  suiteCreatedServerRow =
    (
      await database
        .select({ id: mcpServers.id })
        .from(mcpServers)
        .where(eq(mcpServers.id, serverId))
    ).length === 0;

  suiteCreatedToolRow =
    (
      await database
        .select({ name: mcpTools.name })
        .from(mcpTools)
        .where(
          and(eq(mcpTools.serverId, serverId), eq(mcpTools.name, toolName)),
        )
    ).length === 0;

  // The server row is written directly rather than through addServer, so the test needs no vendor
  // to be reachable. What is under test is the decision, not the listing.
  await database
    .insert(mcpServers)
    .values({
      id: serverId,
      title: "Google Drive",
      vendor: "Google",
      url: "https://www.googleapis.com/drive/v3",
      provenance: "first-party",
    })
    .onConflictDoNothing();
  await database
    .insert(mcpTools)
    .values({
      serverId,
      name: toolName,
      vendorName: toolName,
      description: "Search files.",
    })
    .onConflictDoNothing();
  /*
   * A second tool on the SAME server, granted to nobody.
   *
   * `listForAgent` narrows to the servers a Bot holds something from and then matches the exact ref,
   * and this is what makes the second half load-bearing: without it, holding one tool from a server
   * would offer every tool that server has. Suite-scoped, so it is unambiguously a fixture and
   * cannot collide with a name the vendor really advertises.
   */
  await database
    .insert(mcpTools)
    .values({
      serverId,
      name: siblingToolName,
      vendorName: siblingToolName,
      description: "A tool on the same server that nobody was granted.",
    })
    .onConflictDoNothing();
});

afterAll(async () => {
  // removeServer is under test, so teardown must not depend on it succeeding. Delete the exact
  // attempted fixtures before their credentials, including when setup failed partway through.
  if (removalServerIds.size > 0) {
    await database
      .delete(mcpServers)
      .where(inArray(mcpServers.id, [...removalServerIds]));
  }
  if (removalUserIds.size > 0) {
    await database.delete(users).where(inArray(users.id, [...removalUserIds]));
  }
  /*
   * Scoped to this suite's own Bots, never to the ref alone.
   *
   * `ref` names a REAL server and a real tool — `google-drive/search_files` — so a delete by ref
   * matches every grant in the deployment, including the ones an administrator made for a Bot people
   * use. This suite did exactly that once: it ran, and a Bot silently stopped being able to search
   * Drive, with an audit row showing the grant had been made and nothing showing it removed.
   *
   * The primary key is (kind, ref, agent_id). Two of the three are not a row.
   */
  await database
    .delete(pluginGrants)
    .where(
      and(
        eq(pluginGrants.ref, ref),
        inArray(pluginGrants.agentId, [holderId, strangerId]),
      ),
    );
  // Suite-scoped, so it is this suite's whatever else is true of the server.
  await database
    .delete(mcpTools)
    .where(
      and(eq(mcpTools.serverId, serverId), eq(mcpTools.name, siblingToolName)),
    );
  // A server row is deployment configuration, so it belongs to the deployment rather than here.
  // The fixture tool goes whether or not this suite owns the server, but only if it put it there.
  if (suiteCreatedToolRow) {
    await database
      .delete(mcpTools)
      .where(and(eq(mcpTools.serverId, serverId), eq(mcpTools.name, toolName)));
  }
  if (suiteCreatedServerRow) {
    await database.delete(mcpTools).where(eq(mcpTools.serverId, serverId));
    await database.delete(mcpServers).where(eq(mcpServers.id, serverId));
  }
  await database.delete(agents).where(eq(agents.id, holderId));
  await database.delete(agents).where(eq(agents.id, strangerId));
  for (const id of issuedCredentialIds) {
    await database.delete(credentialRows).where(eq(credentialRows.id, id));
  }
});

describe("a grant is the permission", () => {
  test("a Bot that was never granted a tool is refused, and the refusal is recorded", async () => {
    const actorId = `audit-call-${randomUUID()}@openbot.local`;
    await expect(
      store.callTool({
        ref,
        args: {},
        botId: strangerId,
        actorId,
      }),
    ).rejects.toBeInstanceOf(PluginRefusedError);

    const rows = await auditRowsFor(ref, strangerId, actorId);
    const rejected = rows.filter(
      (row) =>
        row.eventType === "mcp.call_rejected" &&
        (row.payload as { bot?: string }).bot === strangerId,
    );
    expect(rejected.length).toBe(1);
    expect((rejected[0].payload as { refusal?: string }).refusal).toBe(
      "not_granted",
    );
  });

  test("a refusal names the routine that asked, not only the person it ran as", async () => {
    const actorId = `audit-call-${randomUUID()}@openbot.local`;
    await expect(
      store.callTool({
        ref,
        args: {},
        botId: strangerId,
        actorId,
        initiator: { kind: "routine", id: "routine_standup" },
      }),
    ).rejects.toBeInstanceOf(PluginRefusedError);

    const rows = await auditRowsFor(ref, strangerId, actorId);
    const rejected = rows.filter(
      (row) =>
        row.eventType === "mcp.call_rejected" &&
        (row.payload as { bot?: string }).bot === strangerId &&
        row.initiatorKind === "routine",
    );
    expect(rejected.length).toBe(1);
    expect(rejected[0].initiatorId).toBe("routine_standup");
  });

  test("a call nobody said anything about is still filed as a person's", async () => {
    const actorId = `audit-call-${randomUUID()}@openbot.local`;
    await expect(
      store.callTool({
        ref,
        args: {},
        botId: strangerId,
        actorId,
      }),
    ).rejects.toBeInstanceOf(PluginRefusedError);

    const rows = await auditRowsFor(ref, strangerId, actorId);
    expect(
      rows.filter(
        (row) =>
          row.eventType === "mcp.call_rejected" &&
          row.initiatorKind === "person" &&
          row.initiatorId === null,
      ),
    ).toHaveLength(1);
  });

  test("granting lets the same Bot past the grant check", async () => {
    await store.grant("mcp", ref, holderId, "[email protected]");
    const decision = await store.decide("mcp", ref, holderId);
    expect(decision.allowed).toBe(true);
  });

  test("revoking takes it away again", async () => {
    await store.grant("mcp", ref, holderId, "[email protected]");
    await store.revoke("mcp", ref, holderId, "[email protected]");
    const decision = await store.decide("mcp", ref, holderId);
    expect(decision.allowed).toBe(false);
  });

  test("a Bot is offered exactly what it holds", async () => {
    await store.grant("mcp", ref, holderId, "[email protected]");
    const held = await store.listForAgent(holderId);
    expect(held.tools.map((tool) => tool.ref)).toEqual([ref]);
    // The name the model is offered, which may not contain a slash.
    expect(held.tools[0].toolName).toBe("mcp__google-drive__search_files");

    const nothing = await store.listForAgent(strangerId);
    expect(nothing.tools).toEqual([]);
    expect(nothing.skills).toEqual([]);
  });

  test("holding one tool from a server does not offer that server's others", async () => {
    /*
     * The property the exact-ref match protects, now that the query narrows by server rather than
     * reading the whole catalogue. Widening this to "every tool on a server you hold anything from"
     * would pass every other test in this file: the Bot would still be offered what it holds, and the
     * stranger would still be offered nothing.
     */
    await store.grant("mcp", ref, holderId, "[email protected]");
    const held = await store.listForAgent(holderId);

    expect(held.tools.map((tool) => tool.ref)).toEqual([ref]);
    expect(held.tools.map((tool) => tool.ref)).not.toContain(
      `${serverId}/${siblingToolName}`,
    );
  });
});

describe("the policy is asked as well as the grant", () => {
  test("credential material is refused and never copied into the audit trail", async () => {
    const actorId = `audit-call-${randomUUID()}@openbot.local`;
    await store.grant("mcp", ref, holderId, "[email protected]");
    const secret = `sk-${"z".repeat(32)}`;

    await expect(
      store.callTool({
        ref,
        args: { query: "quarterly report", nested: { apiKey: secret } },
        botId: holderId,
        actorId,
      }),
    ).rejects.toThrow("a password or key");

    const rows = await auditRowsFor(ref, holderId, actorId);
    const rejected = rows.filter(
      (row) =>
        row.eventType === "mcp.call_rejected" &&
        (row.payload as { bot?: string }).bot === holderId &&
        (row.payload as { refusal?: string }).refusal ===
          "sensitive_tool_arguments",
    );
    expect(rejected).toHaveLength(1);
    expect(rejected[0].payload).toMatchObject({
      bot: holderId,
      decision: { carriedOut: false },
      contentInspection: {
        reason: "sensitive_content",
        findings: [{ category: "credential_field", path: "$.nested.apiKey" }],
      },
    });
    expect(JSON.stringify(rejected)).not.toContain(secret);
  });

  test("a granted tool is still refused by a deny rule, and the rule is named", async () => {
    const actorId = `audit-call-${randomUUID()}@openbot.local`;
    await store.grant("mcp", ref, holderId, "[email protected]");
    policy = {
      mode: "enforce",
      deny: ['mcp.server == "google-drive"'],
      allow: ["true"],
    };

    let thrown: unknown;
    try {
      await store.callTool({
        ref,
        args: {},
        botId: holderId,
        actorId,
      });
    } catch (error) {
      thrown = error;
    } finally {
      policy = { mode: "enforce", deny: [], allow: ["true"] };
    }

    expect(thrown).toBeInstanceOf(PluginRefusedError);
    // The rule that decided it, so an operator reading the refusal knows what to edit.
    expect((thrown as PluginRefusedError).rule).toBe(
      'mcp.server == "google-drive"',
    );

    const rows = await auditRowsFor(ref, holderId, actorId);
    const refusedByPolicy = rows.filter(
      (row) =>
        row.eventType === "mcp.call_rejected" &&
        (row.payload as { decision?: { rule?: string } }).decision?.rule ===
          'mcp.server == "google-drive"',
    );
    expect(refusedByPolicy.length).toBe(1);
  });

  test("a rule can speak about effect rather than about tool names", async () => {
    await store.grant("mcp", ref, holderId, "[email protected]");
    // `search_files` is advertised and is not in the vendor's write list, so it is a read and
    // this deny rule must NOT catch it. The assertion is that the call gets past the policy, which
    // it proves by failing at the network instead of as a refusal.
    policy = {
      mode: "enforce",
      deny: ['intent == "write_tool"'],
      allow: ["true"],
    };

    let thrown: unknown;
    try {
      await store.callTool({
        ref,
        args: {},
        botId: holderId,
        actorId: "[email protected]",
      });
    } catch (error) {
      thrown = error;
    } finally {
      policy = { mode: "enforce", deny: [], allow: ["true"] };
    }

    /*
     * NOT REFUSED BY THE RULE. The call is still refused, because this vendor is reached as the
     * person asking and nobody has connected — but `rule` is null, which is the assertion: no
     * expression decided this. Asserting the absence of a refusal outright would only prove the
     * vendor was unreachable, which was always the weaker claim.
     */
    expect(thrown).toBeInstanceOf(PluginRefusedError);
    expect((thrown as PluginRefusedError).rule).toBeNull();
    expect((thrown as PluginRefusedError).message).toContain("connected");
  });

  test("a dry-run refusal is recorded, even though the call is let through", async () => {
    const actorId = `audit-call-${randomUUID()}@openbot.local`;
    await store.grant("mcp", ref, holderId, "[email protected]");
    /*
     * The mode an operator switches on to size a rule before enforcing it, and the only mode in
     * which the policy refuses and the call still goes out. Its whole value is the row: without one
     * the report reads "this rule would refuse nothing" about traffic it would refuse.
     */
    const rule = `mcp.tool == "${toolName}"`;
    policy = { mode: "dry-run", deny: [rule], allow: ["true"] };

    try {
      await store
        .callTool({
          ref,
          args: {},
          botId: holderId,
          actorId,
        })
        // Forwarded past the policy, so what happens next is the vendor's business and not this
        // test's: nobody has connected an account, so it fails there. Swallowed deliberately.
        .catch(() => undefined);
    } finally {
      policy = { mode: "enforce", deny: [], allow: ["true"] };
    }

    const rows = await auditRowsFor(ref, holderId, actorId);
    const recorded = rows.filter(
      (row) =>
        row.eventType === "mcp.call_rejected" &&
        (row.payload as { decision?: { rule?: string } }).decision?.rule ===
          rule,
    );
    // The one this call wrote. Exact, because the reads below are of `recorded[0]` and the list is
    // in no order: with the rows of every previous run in it, that index was whichever the planner
    // returned first, which is a row this code did not write.
    expect(recorded).toHaveLength(1);
    /*
     * What tells this row apart from a call this deployment actually stopped. `allowed` is the
     * policy's answer and `carriedOut` is what the mode did with it, so a reader counting what a
     * rule would have refused finds this one, and a reader counting what was refused does not.
     */
    const decision = (
      recorded[0].payload as {
        decision?: { allowed?: boolean; mode?: string; carriedOut?: boolean };
      }
    ).decision;
    expect(decision?.allowed).toBe(false);
    expect(decision?.mode).toBe("dry-run");
    expect(decision?.carriedOut).toBe(true);
  });
});

describe("the trail says what happened, not what was permitted", () => {
  /*
   * THE REGRESSION THIS EXISTS FOR. `mcp.call_succeeded` used to be written before the credential
   * was selected and before the network call, so a call that passed the grant and the policy and
   * then failed left a row asserting it had succeeded — and nothing at all saying it had not.
   *
   * That is the worst arrangement available. A trail with a gap makes somebody go and look; a trail
   * that is confidently wrong is used to rule the connector out and send the search elsewhere. It
   * did exactly that: a Bot that could not read Drive at all had `call_succeeded` rows behind it.
   *
   * `search_files` on `google-drive` is reached as the asker, and nobody here has connected, so this
   * call is permitted and then cannot be made — which is the shape of failure the row must show.
   */
  test("a call that is permitted and then fails is recorded as failed, not as succeeded", async () => {
    await store.grant("mcp", ref, holderId, "[email protected]");
    const actorId = `audit-call-${randomUUID()}@openbot.local`;

    await expect(
      store.callTool({ ref, args: {}, botId: holderId, actorId }),
    ).rejects.toBeInstanceOf(PluginRefusedError);

    const mine = await auditRowsFor(ref, holderId, actorId);

    const failed = mine.filter((row) => row.eventType === "mcp.call_failed");
    expect(failed.length).toBe(1);
    // The reason travels with the row. For a 403 this is where the vendor names the API that is not
    // enabled, which is the sentence that turns a guess into a fix.
    expect((failed[0].payload as { failure?: string }).failure).toContain(
      "connected",
    );

    // The point of the whole test: nothing claims this worked.
    expect(
      mine.filter((row) => row.eventType === "mcp.call_succeeded"),
    ).toEqual([]);
  });
});

describe("a boundary written about the browser does not refuse tool calls", () => {
  test("an unguarded rule about a page element does not refuse a tool call", async () => {
    await store.grant("mcp", ref, holderId, "[email protected]");
    /**
     * This engine treats an expression it cannot evaluate as a MATCH, which is right for a browser
     * action on an element the server could not resolve and catastrophic for a tool call: with
     * `element` absent from the context, ANY deny rule naming it is unevaluable, so it matches, so
     * every MCP call is refused for a reason about a submit button.
     *
     * The preset in `.env.example` happens to survive that, because it guards each clause with
     * `tool.name == "computer_click"` and CEL short-circuits before ever reaching `element`. That is
     * luck, not design, and a rule an operator writes by hand has no such guard. So the rule under
     * test is the unguarded one.
     */
    policy = {
      mode: "enforce",
      deny: ['contains(element.name, "submit")'],
      allow: ["true"],
    };

    let thrown: unknown;
    try {
      await store.callTool({
        ref,
        args: {},
        botId: holderId,
        actorId: "[email protected]",
      });
    } catch (error) {
      thrown = error;
    } finally {
      policy = { mode: "enforce", deny: [], allow: ["true"] };
    }

    // The rule did not decide this: `rule` is null. What refuses it is the missing connection for a
    // vendor reached as the person asking, which is a different sentence and a different cause.
    expect((thrown as PluginRefusedError).rule).toBeNull();
    expect((thrown as PluginRefusedError).message).toContain("connected");
  });
});

describe("removing an MCP server", () => {
  test("revokes the credential the server was configured with", async () => {
    // Without this, the credential row stays live after the server row is
    // gone, and re-adding the same server would unique-violate on
    // `credentials_active_key_idx`. The audit trail also carries the
    // revocation with `reason: mcp_server_removed`.
    const removalServerId = `removal-target-${suite}`;
    removalServerIds.add(removalServerId);
    revokedCredentialIds.length = 0;
    const [credentialRow] = await database
      .insert(credentialRows)
      .values({
        kind: "mcp",
        provider: removalServerId,
        keyId: `mcp-${removalServerId}`,
        encryptedValue: "{}",
        metadata: {},
      })
      .returning({ id: credentialRows.id });
    const credentialId = credentialRow?.id;
    if (!credentialId) throw new Error("credential row was not created");
    issuedCredentialIds.push(credentialId);
    await database.insert(mcpServers).values({
      id: removalServerId,
      title: "removal target",
      vendor: "test",
      url: "https://example.invalid/mcp",
      credentialId,
      provenance: "custom",
    });

    await store.removeServer(removalServerId, "[email protected]");

    expect(revokedCredentialIds).toEqual([credentialId]);
    const [row] = await database
      .select({ id: mcpServers.id })
      .from(mcpServers)
      .where(eq(mcpServers.id, removalServerId));
    expect(row).toBeUndefined();
    const audit = await database
      .select({
        eventType: auditEvents.eventType,
        payload: auditEvents.payload,
      })
      .from(auditEvents)
      .where(
        and(
          eq(auditEvents.targetType, "credential"),
          eq(auditEvents.targetId, credentialId),
        ),
      );
    expect(audit).toHaveLength(1);
    expect(audit[0]?.eventType).toBe("credential.revoked");
    expect((audit[0]?.payload as { reason?: string })?.reason).toBe(
      "mcp_server_removed",
    );
    // Audit is append-only in Postgres; leaving the row is fine because
    // `credentialId` is suite-scoped, so re-runs never collide.
  });

  /**
   * The people's grants go too, not only the server's own token.
   *
   * `mcp_user_credentials` cascades on the server row, so removing a `user-oauth` connector used to
   * delete every pointer and leave every refresh token in the vault live and unreferenced: reachable
   * from no screen, revoked by no operation, and still a usable grant at the vendor. "We removed the
   * connector" has to be true of the thing that matters, which is the token sitting at Notion.
   */
  test("revokes every person's grant for the server it removes", async () => {
    const removalServerId = `removal-target-people-${suite}`;
    const connectedUserId = `user_removal_${suite}`;
    removalServerIds.add(removalServerId);
    removalUserIds.add(connectedUserId);
    revokedCredentialIds.length = 0;

    await database
      .insert(users)
      .values({
        id: connectedUserId,
        email: `${connectedUserId}@openbot.test`,
        name: connectedUserId,
        emailVerified: false,
      })
      .onConflictDoNothing();

    const [grant] = await database
      .insert(credentialRows)
      .values({
        kind: "mcp_user_token",
        provider: removalServerId,
        keyId: connectedUserId,
        encryptedValue: "{}",
        metadata: {},
      })
      .returning({ id: credentialRows.id });
    const grantId = grant?.id;
    if (!grantId) throw new Error("grant row was not created");
    issuedCredentialIds.push(grantId);

    await database.insert(mcpServers).values({
      id: removalServerId,
      title: "removal target with people",
      vendor: "test",
      url: "https://example.invalid/mcp",
      provenance: "custom",
    });
    await database.insert(mcpUserCredentials).values({
      serverId: removalServerId,
      userId: connectedUserId,
      credentialId: grantId,
      scope: "",
    });

    try {
      await store.removeServer(removalServerId, "[email protected]");

      expect(revokedCredentialIds).toEqual([grantId]);
      const [row] = await database
        .select({ revokedAt: credentialRows.revokedAt })
        .from(credentialRows)
        .where(eq(credentialRows.id, grantId));
      expect(row?.revokedAt).not.toBeNull();

      // And the trail says whose access ended and why, which is the row an auditor reaches for.
      const trail = await database
        .select({
          eventType: auditEvents.eventType,
          owner: sql<string>`payload ->> 'owner'`,
          reason: sql<string>`payload ->> 'reason'`,
        })
        .from(auditEvents)
        .where(
          and(
            eq(auditEvents.targetType, "mcp_server"),
            eq(auditEvents.targetId, removalServerId),
            eq(auditEvents.eventType, "mcp.account_disconnected"),
          ),
        );
      expect(trail).toHaveLength(1);
      expect(trail[0]?.owner).toBe(connectedUserId);
      expect(trail[0]?.reason).toBe("mcp_server_removed");
    } finally {
      await database.delete(users).where(eq(users.id, connectedUserId));
    }
  });

  /**
   * A credential that was already retired, and the read that decides whether to retire it again.
   *
   * CRITERION. `removeServer` must not ask the vault to revoke a credential whose row already
   * carries a `revoked_at`, and must still remove the server row.
   *
   * REASON. It reads liveness from the table before deciding, and nothing asserted that. The test
   * above inserts a LIVE row and so takes the true branch; the one below has no credential at all
   * and so never runs the query. So `isNull(revoked_at)` could be dropped with the whole suite
   * green — and in production `credentials.revoke` throws "not found or already revoked", which
   * propagates before `delete(mcpServers)` and leaves a server row that cannot be removed by any
   * number of attempts, on a route with no `catch`. Two ordinary states produce the row: a
   * previous removal that failed after the revoke, and a key rotated by hand.
   *
   * ASSERTED AS "revoke was not called", not as the absence of a throw. The vault here is a stub
   * that is deliberately forgiving — it stamps whatever id it is handed — so a test waiting for it
   * to complain would pass with the clause gone. What the read decides is whether the call is made
   * at all, and that is what {@link revokedCredentialIds} records.
   */
  test("does not ask the vault to revoke a credential already revoked", async () => {
    const removalServerId = `removal-target-retired-${suite}`;
    revokedCredentialIds.length = 0;
    const revokedAt = new Date();
    const [credentialRow] = await database
      .insert(credentialRows)
      .values({
        kind: "mcp",
        provider: removalServerId,
        keyId: `mcp-${removalServerId}`,
        encryptedValue: "{}",
        metadata: {},
        revokedAt,
        updatedAt: revokedAt,
      })
      .returning({ id: credentialRows.id });
    const credentialId = credentialRow?.id;
    if (!credentialId) throw new Error("credential row was not created");
    issuedCredentialIds.push(credentialId);
    await database.insert(mcpServers).values({
      id: removalServerId,
      title: "removal target with a retired credential",
      vendor: "test",
      url: "https://example.invalid/mcp",
      credentialId,
      provenance: "custom",
    });

    await store.removeServer(removalServerId, "[email protected]");

    // Not asked, because the row already says it is retired.
    expect(revokedCredentialIds).toEqual([]);
    // And the server row is gone, which is the act an administrator asked for and the thing a
    // throw from the vault would have prevented.
    expect(
      await database
        .select({ id: mcpServers.id })
        .from(mcpServers)
        .where(eq(mcpServers.id, removalServerId)),
    ).toEqual([]);
    // No second revocation in the trail either: a row saying access ended twice is a row an
    // auditor has to reconcile against nothing having happened.
    expect(
      await database
        .select({ id: auditEvents.id })
        .from(auditEvents)
        .where(
          and(
            eq(auditEvents.eventType, "credential.revoked"),
            eq(auditEvents.targetId, credentialId),
          ),
        ),
    ).toEqual([]);
  });

  test("does not call revoke when the server had no credential", async () => {
    const removalServerId = `removal-target-nocred-${suite}`;
    removalServerIds.add(removalServerId);
    revokedCredentialIds.length = 0;
    await database.insert(mcpServers).values({
      id: removalServerId,
      title: "removal target no cred",
      vendor: "test",
      url: "https://example.invalid/mcp",
      provenance: "custom",
    });

    await store.removeServer(removalServerId, "[email protected]");

    expect(revokedCredentialIds).toEqual([]);
  });
});

describe("the trail can be read by a second reader", () => {
  test("a refusal names the bot, the server and the tool in queryable JSON", async () => {
    const actorId = `audit-payload-${randomUUID()}@openbot.local`;
    await expect(
      store.callTool({
        ref,
        args: {},
        botId: strangerId,
        actorId,
      }),
    ).rejects.toBeInstanceOf(PluginRefusedError);

    const rows = await database
      .select({
        bot: sql<string>`payload ->> 'bot'`,
        server: sql<string>`payload ->> 'server'`,
        tool: sql<string>`payload ->> 'tool'`,
        refusal: sql<string>`payload ->> 'refusal'`,
      })
      .from(auditEvents)
      .where(
        and(
          eq(auditEvents.targetType, "mcp_tool"),
          eq(auditEvents.eventType, "mcp.call_rejected"),
          eq(auditEvents.targetId, ref),
          sinceThisRun(),
          // The catalogue ref is shared; only this call used this actor and suite-owned Bot.
          eq(sql<string>`payload ->> 'actor'`, actorId),
          eq(sql<string>`payload ->> 'bot'`, strangerId),
        ),
      );

    // Asserted in SQL rather than through the application, because the stored payload shape is the
    // property under test.
    expect(rows).toHaveLength(1);
    const [row] = rows;
    expect(row?.server).toBe(serverId);
    expect(row?.tool).toBe(toolName);
    expect(row?.bot).toBe(strangerId);
    expect(row?.refusal).toBe("not_granted");
  });
});

/**
 * A grant outliving the tool it names.
 *
 * The runtime already handles it: `listForAgent` reads the grant against the tool list, so a tool the
 * vendor has stopped advertising reaches no model. What was missing is that nothing said so — the
 * plugins page derives its grant list from the advertised refs, so a grant on a withdrawn tool was
 * invisible on the one screen an administrator reads to answer "what may this Bot do".
 */
describe("a grant on a tool the vendor no longer lists", () => {
  const withdrawnName = `withdrawn_${suite}`;
  const withdrawnRef = `${serverId}/${withdrawnName}`;

  afterAll(async () => {
    await database
      .delete(pluginGrants)
      .where(
        and(
          eq(pluginGrants.ref, withdrawnRef),
          eq(pluginGrants.agentId, holderId),
        ),
      );
    await database
      .delete(mcpTools)
      .where(
        and(eq(mcpTools.serverId, serverId), eq(mcpTools.name, withdrawnName)),
      );
  });

  test("is reported as held and not offered, and still reaches no model", async () => {
    // Advertised once, which is how a grant comes to exist against it.
    await database
      .insert(mcpTools)
      .values({
        serverId,
        name: withdrawnName,
        vendorName: withdrawnName,
        description: "Listed by the vendor when the grant was made.",
      })
      .onConflictDoNothing();
    await store.grant("mcp", withdrawnRef, holderId, "[email protected]");

    // Then withdrawn. A refresh replaces the tool list wholesale, so this is what one does to a name
    // the vendor has stopped offering.
    await database
      .delete(mcpTools)
      .where(
        and(eq(mcpTools.serverId, serverId), eq(mcpTools.name, withdrawnName)),
      );

    const drive = (await store.listServers()).find(
      (server) => server.id === serverId,
    );

    // Not a tool: it is not in the list the vendor gave, so it must not be counted as one.
    expect(drive?.tools.map((tool) => tool.ref)).not.toContain(withdrawnRef);
    // But it is reported, with who holds it, which is the whole point.
    expect(drive?.withdrawn.map((held) => held.ref)).toContain(withdrawnRef);
    const held = drive?.withdrawn.find((row) => row.ref === withdrawnRef);
    expect(held?.name).toBe(withdrawnName);
    expect(held?.grantedTo).toContain(holderId);

    // And the property that made it inert in the first place is unchanged. This is the assertion that
    // would fail if reporting a grant had turned into honouring one.
    const offered = await store.listForAgent(holderId);
    expect(offered.tools.map((tool) => tool.ref)).not.toContain(withdrawnRef);
  });

  test("a healthy connector reports nothing withdrawn", async () => {
    // The empty case, because a field that is only ever exercised non-empty is a field whose empty
    // shape nobody has checked — and this one is read by a screen that hides itself when it is empty.
    const drive = (await store.listServers()).find(
      (server) => server.id === serverId,
    );
    expect(drive?.withdrawn.map((row) => row.ref)).not.toContain(ref);
  });
});

/**
 * A vendor that hands back a new refresh token every time it is asked for access.
 *
 * Notion does. The token it was shown is dead the moment it answers, so a deployment that keeps the
 * old one has spent somebody's connection on a single call: the next one presents a token the vendor
 * has already invalidated, and the person is told to connect again for no reason they can see. That
 * makes persisting the new token part of the exchange rather than bookkeeping after it, and it makes
 * two concurrent calls a problem — both would present the same token, and one of them would lose.
 *
 * This suite needs a REAL vault, unlike the store fixture above: rotation re-encrypts the row the
 * connection already points at, and a stub that throws cannot show that happening — nor show that
 * nothing else was written. So it builds its own store, with the vendor and its token endpoint
 * injected and everything else genuine.
 */
describe("refresh token rotation", () => {
  const rotationBotId = `agent_rotation_bot_${suite}`;
  const rotationUserId = `user_rotation_${suite}`;
  /** Notion, because it is the entry whose vendor actually rotates. */
  const rotationServerId = "notion";
  /** Suite-scoped, so it cannot collide with a name Notion really advertises. */
  const rotationToolName = `search_${suite}`;
  const rotationRef = `${rotationServerId}/${rotationToolName}`;
  /**
   * 32 zero bytes in base64.
   *
   * A real AES-256 key length, unlike the `"x".repeat(44)` the fixture above gets away with: every
   * call there is refused before the vault is opened, and every call here goes through it.
   */
  const ROTATION_KEY = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  const CLIENT = { clientId: "notion-client", clientSecret: "notion-secret" };
  /** Notion has no scope strings; the connection stores what the vendor said, which is nothing. */
  const SCOPE = "";

  /** Every vault row this suite created, so the cleanup can take exactly those. */
  const vaultRows: string[] = [];
  /** Every access token the store was about to send to the vendor, in order. */
  const sent: string[] = [];
  /**
   * The exchange, as a sequence of the moments it entered and left.
   *
   * Recorded as a log rather than as a count because the property under test is an ORDERING: two
   * exchanges for one connection must not overlap. A log makes an overlap visible without the test
   * having to guess when to look.
   */
  const log: string[] = [];
  /** What each exchange received and what it rotated to, which is the pairing rotation is about. */
  const exchanges: { received: string; returned?: string }[] = [];
  /** What the vendor's token endpoint does, installed per test. */
  let mint: (refreshToken: string) => Promise<AccessToken> = async () => {
    throw new Error("no exchange was installed for this test");
  };

  /**
   * The vault, wired once and shared by every store this describe builds.
   *
   * Shared deliberately: a second replica of this deployment reads and writes the same rows through
   * the same code, and a per-store copy of the wiring would be a second place for the fixture to
   * drift from what production does.
   */
  const vault = {
    readSecret: async (id: string) => {
      const [row] = await database
        .select({
          encryptedValue: credentials.encryptedValue,
          revokedAt: credentials.revokedAt,
        })
        .from(credentials)
        .where(eq(credentials.id, id));
      return row ?? null;
    },
    create: async (value: CredentialStoreValue) => {
      const [row] = await database
        .insert(credentials)
        .values(value)
        .returning({ id: credentials.id, revokedAt: credentials.revokedAt });
      if (!row) throw new Error("credential was not stored");
      vaultRows.push(row.id);
      return row;
    },
    /*
     * The vault's own in-place update, not a stand-in for it.
     *
     * This is the write rotation now performs, and the suite asserts the ROW it leaves behind: the
     * same id, re-encrypted, nothing added. A hand-rolled copy of the statement here would assert
     * the copy rather than the vault — and would not join the caller's transaction, which is the
     * whole of what keeps two replicas from spending one refresh token twice.
     */
    updateSecret: createCredentialStore(database).updateSecret,
    /*
     * The real swap and the real key lookup too: `credentials_active_key_idx` holds one live row
     * per key, so a reconnect in this suite replaces its previous token through the same
     * transaction production uses. A stand-in would dodge the index the test data must obey.
     */
    rotate: async (
      value: CredentialStoreValue & { previousCredentialId: string },
    ) => {
      const stored = await createCredentialStore(database).rotate(value);
      vaultRows.push(stored.id);
      return stored;
    },
    findLiveByKey: createCredentialStore(database).findLiveByKey,
    isLive: createCredentialStore(database).isLive,
    revoke: async (id: string) => {
      const [row] = await database
        .update(credentials)
        .set({ revokedAt: new Date() })
        .where(eq(credentials.id, id))
        .returning({ revokedAt: credentials.revokedAt });
      if (!row?.revokedAt) throw new Error("credential was not revoked");
      return row.revokedAt;
    },
  };

  const rotationStore = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore: createAuditStore(database),
    credentials: vault,
    encryptionKey: ROTATION_KEY,
    policy: () => policy,
    // Stops before the network, and records what the call would have gone out with.
    callVendor: async (connection) => {
      sent.push(connection.token ?? "<none>");
      return { text: "[vendor not reached in tests]", isError: false };
    },
    exchangeRefreshToken: async ({ client, refreshToken }) => {
      expect(client).toEqual(CLIENT);
      log.push(`start:${refreshToken}`);
      const minted = await mint(refreshToken);
      log.push(`end:${refreshToken}`);
      exchanges.push({ received: refreshToken, returned: minted.refreshToken });
      return minted;
    },
  });

  /**
   * A second replica of this deployment, over the same database.
   *
   * The point of building the store again rather than calling the same one twice is what is NOT
   * shared: the in-process map that queues one connection's exchanges belongs to a store instance,
   * so two instances are as unserialised as two containers behind a load balancer. Whatever keeps
   * them from spending one refresh token twice has to live in the database.
   */
  function replica(exchange: (refreshToken: string) => Promise<AccessToken>) {
    return createPluginStore({
      brokerProvider: "composio",
      database,
      auditStore: createAuditStore(database),
      credentials: vault,
      encryptionKey: ROTATION_KEY,
      policy: () => policy,
      callVendor: async () => ({
        text: "[vendor not reached in tests]",
        isError: false,
      }),
      exchangeRefreshToken: async ({ refreshToken }) => exchange(refreshToken),
    });
  }

  /** The deployment's OAuth client, which is what `mcp_servers.credential_id` holds. */
  async function registerClient() {
    const [credential] = await database
      .insert(credentials)
      .values({
        kind: "mcp_oauth_client",
        provider: rotationServerId,
        keyId: "oauth-client",
        metadata: { clientId: CLIENT.clientId },
        encryptedValue: await encryptSecret(
          ROTATION_KEY,
          JSON.stringify(CLIENT),
        ),
      })
      .returning({ id: credentials.id });
    if (!credential) throw new Error("client was not stored");
    vaultRows.push(credential.id);
    await database
      .update(mcpServers)
      .set({ credentialId: credential.id })
      .where(eq(mcpServers.id, rotationServerId));
  }

  /** Which vault row this person's connection points at, so a swap is observable. */
  async function connectionCredential() {
    const [row] = await database
      .select({ credentialId: mcpUserCredentials.credentialId })
      .from(mcpUserCredentials)
      .where(
        and(
          eq(mcpUserCredentials.serverId, rotationServerId),
          eq(mcpUserCredentials.userId, rotationUserId),
        ),
      );
    return row?.credentialId ?? null;
  }

  /**
   * Every vault row this person's connection has ever had, live or revoked.
   *
   * The count is the point. A rotating vendor issues a new refresh token on every exchange, so a
   * rotation that minted a row would leave one row per tool call here — which is invisible to any
   * assertion that only looks at where the connection currently points.
   */
  async function connectionVaultRows() {
    return (
      database
        .select({
          id: credentials.id,
          encryptedValue: credentials.encryptedValue,
          revokedAt: credentials.revokedAt,
        })
        .from(credentials)
        .where(
          and(
            eq(credentials.kind, "mcp_user_token"),
            eq(credentials.provider, rotationServerId),
            eq(credentials.keyId, rotationUserId),
          ),
        )
        // Ordered, so that comparing the whole list before and after is comparing the rows rather
        // than whatever order the database felt like returning them in.
        .orderBy(credentials.id)
    );
  }

  /** How many times this person is recorded as having connected their account. */
  async function connectedRows() {
    return (
      await database
        .select({ actor: sql<string>`payload ->> 'actor'` })
        .from(auditEvents)
        .where(
          and(
            eq(auditEvents.eventType, "mcp.account_connected"),
            eq(auditEvents.targetId, rotationServerId),
            sql`payload ->> 'actor' = ${rotationUserId}`,
          ),
        )
    ).length;
  }

  /** Waiting for something the other call does, rather than for a duration. */
  async function waitUntil(condition: () => boolean, what: string) {
    for (let attempt = 0; attempt < 300; attempt += 1) {
      if (condition()) return;
      await new Promise((resolve) => setTimeout(resolve, 10));
    }
    throw new Error(`timed out waiting for ${what}`);
  }

  /** A connection holding `rt-1`, written through the store so the vault is exercised. */
  async function connect() {
    await rotationStore.recordConnection({
      serverId: rotationServerId,
      userId: rotationUserId,
      refreshToken: "rt-1",
      scope: SCOPE,
    });
    log.length = 0;
    exchanges.length = 0;
    sent.length = 0;
  }

  /**
   * Whether THIS RUN is what put the `notion` row there, and so is what should take it away.
   *
   * Counting creations rather than absences, the same way round as {@link suiteCreatedServerRow} and
   * for the same reason: `afterAll` runs even when the `beforeAll` below it has thrown, and a flag
   * still sitting at its initialiser then authorised the delete. Only a capture that ran and found
   * the row missing can write the value the delete needs.
   */
  let suiteCreatedNotionRow = false;
  /**
   * The OAuth client this deployment had before the suite ran, restored afterwards.
   *
   * `mcp_servers.credential_id` is live configuration, and this suite repoints it. `undefined` is
   * "nobody looked", which is what the value is until the capture below runs and is what it is still
   * sitting at if that `beforeAll` threw first — and a restore that treated it as `null` would not be
   * restoring anything, it would be blanking a real deployment's client on the way out.
   */
  let clientBefore: string | null | undefined;

  beforeAll(async () => {
    await database
      .insert(agents)
      .values({
        id: rotationBotId,
        name: rotationBotId,
        type: "remote_ag_ui",
        configuration: {},
      })
      .onConflictDoNothing();
    await database
      .insert(users)
      .values({
        id: rotationUserId,
        email: `${rotationUserId}@openbot.test`,
        name: rotationUserId,
        emailVerified: false,
      })
      .onConflictDoNothing();

    const [existing] = await database
      .select({ id: mcpServers.id, credentialId: mcpServers.credentialId })
      .from(mcpServers)
      .where(eq(mcpServers.id, rotationServerId));
    suiteCreatedNotionRow = existing === undefined;
    clientBefore = existing?.credentialId ?? null;

    // Written directly, so the test needs no vendor to be reachable. What is under test is which
    // refresh token the next exchange presents, not the listing.
    await database
      .insert(mcpServers)
      .values({
        id: rotationServerId,
        title: "Notion",
        vendor: "Notion",
        url: "https://mcp.notion.com/mcp",
        provenance: "first-party",
      })
      .onConflictDoNothing();
    await database
      .insert(mcpTools)
      .values({
        serverId: rotationServerId,
        name: rotationToolName,
        vendorName: rotationToolName,
        description: "Search pages.",
      })
      .onConflictDoNothing();
    await rotationStore.grant(
      "mcp",
      rotationRef,
      rotationBotId,
      "[email protected]",
    );
    await registerClient();
  });

  afterAll(async () => {
    // This suite's own person, never every row for this vendor: the id carries the run's suffix.
    await database
      .delete(mcpUserCredentials)
      .where(
        and(
          eq(mcpUserCredentials.serverId, rotationServerId),
          eq(mcpUserCredentials.userId, rotationUserId),
        ),
      );
    // Before the deletes, because the column addresses one of the rows they remove. Only when the
    // capture actually ran: `undefined` is nobody having looked, and writing that back as null is
    // not a restore.
    if (clientBefore !== undefined) {
      await database
        .update(mcpServers)
        .set({ credentialId: clientBefore })
        .where(eq(mcpServers.id, rotationServerId));
    }
    for (const id of vaultRows) {
      await database.delete(credentials).where(eq(credentials.id, id));
    }
    await database
      .delete(pluginGrants)
      .where(
        and(
          eq(pluginGrants.ref, rotationRef),
          eq(pluginGrants.agentId, rotationBotId),
        ),
      );
    await database
      .delete(mcpTools)
      .where(
        and(
          eq(mcpTools.serverId, rotationServerId),
          eq(mcpTools.name, rotationToolName),
        ),
      );
    // A server row is deployment configuration, so it goes only if this suite is what added it.
    if (suiteCreatedNotionRow) {
      await database
        .delete(mcpTools)
        .where(eq(mcpTools.serverId, rotationServerId));
      await database
        .delete(mcpServers)
        .where(eq(mcpServers.id, rotationServerId));
    }
    await database.delete(agents).where(eq(agents.id, rotationBotId));
    await database.delete(users).where(eq(users.id, rotationUserId));
  });

  test("the list says which servers register their own OAuth client", async () => {
    // Notion is dynamic (RFC 7591, registered by this deployment on first connect); Google Drive
    // is not — an administrator pastes its client in, so the paste-a-client form still has a job
    // to do there. The field distinguishes the two so the admin screen can hide the form only
    // where it would otherwise be filled in with nothing to type.
    const servers = await store.listServers();
    const notion = servers.find((server) => server.id === rotationServerId);
    const drive = servers.find((server) => server.id === serverId);
    expect(notion?.dynamicClient).toBe(true);
    expect(drive?.dynamicClient).toBe(false);
  });

  test("the token the vendor rotated to is the one the next call presents", async () => {
    await connect();
    const before = await connectionCredential();
    const rowsBefore = await connectionVaultRows();
    const connectedBefore = await connectedRows();
    mint = async () => ({ accessToken: "at-1", refreshToken: "rt-2" });

    await rotationStore.callTool({
      ref: rotationRef,
      args: {},
      botId: rotationBotId,
      actorId: rotationUserId,
    });
    await rotationStore.callTool({
      ref: rotationRef,
      args: {},
      botId: rotationBotId,
      actorId: rotationUserId,
    });

    // The whole property: the second exchange presented what the first was given back.
    expect(exchanges.map((exchange) => exchange.received)).toEqual([
      "rt-1",
      "rt-2",
    ]);
    // Both calls went out with an access token, so neither was refused on the way.
    expect(sent).toEqual(["at-1", "at-1"]);

    /*
     * Two rotations, and the vault holds exactly what it held before: the same row, still live,
     * carrying the latest token.
     *
     * This is the whole reason rotation is in place rather than a swap. Every single call to a
     * rotating vendor rotates, so minting a row per rotation would grow the vault without bound on
     * the hottest path there is — and would revoke a grant the vendor had already killed itself the
     * moment it handed the new token back.
     */
    const after = await connectionCredential();
    expect(after).toBe(before);
    const rowsAfter = await connectionVaultRows();
    expect(rowsAfter.map((row) => row.id)).toEqual(
      rowsBefore.map((row) => row.id),
    );
    const live = rowsAfter.filter((row) => row.revokedAt === null);
    expect(live.map((row) => row.id)).toEqual([before]);
    // And the row that stayed is the one the vendor rotated to, not the one it replaced.
    expect(
      await decryptSecret(ROTATION_KEY, live[0]?.encryptedValue ?? ""),
    ).toBe("rt-2");

    // And nothing claims the person connected an account again. Rotation is the vendor's plumbing,
    // not somebody's act, and a trail that says otherwise is read as a re-consent that never
    // happened.
    expect(await connectedRows()).toBe(connectedBefore);
  });

  test("a vendor that does not rotate leaves the connection alone", async () => {
    await connect();
    const before = await connectionCredential();
    // Google's reply: an access token and nothing else. Repointing anything here would be inventing
    // a rotation the vendor did not perform.
    mint = async () => ({ accessToken: "at-1" });

    await rotationStore.callTool({
      ref: rotationRef,
      args: {},
      botId: rotationBotId,
      actorId: rotationUserId,
    });
    await rotationStore.callTool({
      ref: rotationRef,
      args: {},
      botId: rotationBotId,
      actorId: rotationUserId,
    });

    expect(exchanges.map((exchange) => exchange.received)).toEqual([
      "rt-1",
      "rt-1",
    ]);
    // Said explicitly, because it is the condition the store branches on: no refresh token came
    // back at all. A test that only checked the connection was untouched would pass just as well
    // against a store that rotated to the token it already held.
    expect(exchanges.map((exchange) => exchange.returned)).toEqual([
      undefined,
      undefined,
    ]);
    expect(await connectionCredential()).toBe(before);
  });

  test("a vendor that hands the same token back writes nothing", async () => {
    await connect();
    const before = await connectionVaultRows();
    // Notion's reply when the grant did not move: a fresh access token and the refresh token we
    // presented. Nothing rotated, so there is nothing to persist.
    mint = async () => ({ accessToken: "at-1", refreshToken: "rt-1" });

    await rotationStore.callTool({
      ref: rotationRef,
      args: {},
      botId: rotationBotId,
      actorId: rotationUserId,
    });

    /*
     * Byte-identical, which is a stronger claim than "same row".
     *
     * Encryption draws a fresh IV every time, so re-encrypting the very same token would leave a
     * different envelope in the same row. An untouched envelope is the only evidence that the write
     * did not happen at all.
     */
    expect(await connectionVaultRows()).toEqual(before);
    expect(sent).toEqual(["at-1"]);
  });

  test("two calls at once take turns, and the second spends what the first was given", async () => {
    await connect();
    let release: (minted: AccessToken) => void = () => {};
    const parked = new Promise<AccessToken>((resolve) => {
      release = resolve;
    });
    let asked = 0;
    mint = async () => {
      asked += 1;
      // The first exchange hangs until this test lets it finish. The second must not have started.
      return asked === 1
        ? parked
        : { accessToken: "at-2", refreshToken: "rt-3" };
    };

    const both = Promise.allSettled([
      rotationStore.callTool({
        ref: rotationRef,
        args: {},
        botId: rotationBotId,
        actorId: rotationUserId,
      }),
      rotationStore.callTool({
        ref: rotationRef,
        args: {},
        botId: rotationBotId,
        actorId: rotationUserId,
      }),
    ]);

    try {
      await waitUntil(() => log.length > 0, "the first exchange to start");
      /*
       * Long enough for a second, unserialised call to reach the vendor on its own. Its queries are
       * a few milliseconds against a local database, so an overlapping exchange would be in the log
       * by now — and with the exchanges serialised, waiting changes nothing at all.
       */
      await new Promise((resolve) => setTimeout(resolve, 250));
      expect(log).toEqual(["start:rt-1"]);
    } finally {
      release({ accessToken: "at-1", refreshToken: "rt-2" });
    }

    const results = await both;
    expect(results.map((result) => result.status)).toEqual([
      "fulfilled",
      "fulfilled",
    ]);
    // One after another, never interleaved, and the second presented the first's rotated token —
    // which is only possible because the first persisted it before answering.
    expect(log).toEqual(["start:rt-1", "end:rt-1", "start:rt-2", "end:rt-2"]);
    expect(exchanges).toEqual([
      { received: "rt-1", returned: "rt-2" },
      { received: "rt-2", returned: "rt-3" },
    ]);
  });

  /**
   * Two replicas, one connection, and the vendor shown each refresh token exactly once.
   *
   * This is the case the in-process queue cannot reach. Each replica has its own map, so both read
   * the stored token, both present it, and a vendor with refresh-token-reuse detection reads the
   * second presentation as a stolen token and revokes the whole family — bricking a connection that
   * nobody did anything wrong with. The row lock is what makes the second replica wait and then read
   * what the first rotated to.
   */
  test("two replicas take turns at the row, and neither spends a token twice", async () => {
    await connect();
    /** Every refresh token the vendor was shown, by either replica, in order. */
    const presented: string[] = [];
    let issued = 1;
    const exchange = async (refreshToken: string) => {
      presented.push(refreshToken);
      /*
       * Long enough that an unlocked second replica has read the vault and presented what it found
       * there before this exchange answers. With the lock held it changes nothing except how long
       * the other replica waits for its turn.
       */
      await new Promise((resolve) => setTimeout(resolve, 50));
      issued += 1;
      return { accessToken: `at-${issued}`, refreshToken: `rt-${issued}` };
    };
    const first = replica(exchange);
    const second = replica(exchange);

    const call = (store: ReturnType<typeof replica>) =>
      store.callTool({
        ref: rotationRef,
        args: {},
        botId: rotationBotId,
        actorId: rotationUserId,
      });
    const results = await Promise.all([call(first), call(second)]);

    expect(results.map((result) => result.isError)).toEqual([false, false]);
    // The whole property. `["rt-1", "rt-1"]` is the double-spend: two replicas presenting one token.
    expect(presented).toEqual(["rt-1", "rt-2"]);
    // And the row the connection points at carries the last token issued, so a third call would
    // present that rather than something either replica had already spent.
    const live = (await connectionVaultRows()).filter(
      (row) => row.revokedAt === null,
    );
    expect(
      await decryptSecret(ROTATION_KEY, live[0]?.encryptedValue ?? ""),
    ).toBe("rt-3");
  });

  /**
   * A stored OAuth client whose decrypted bytes are not a client at all.
   *
   * CRITERION: neither the decrypted plaintext nor a parser's account of it may reach
   * `audit_events` or `mcp_servers.last_error`. REASON: that plaintext IS the deployment's OAuth
   * client secret, and `JSON.parse` reports failure by quoting the input it choked on — so an
   * unguarded parse writes a fragment of the secret into two durable stores, both of which the
   * Plugins page draws for an administrator.
   *
   * A corrupted row is not hypothetical: a partially written value, a row encrypted under a key
   * this deployment no longer holds, or a hand-edited vault all produce bytes that decrypt and are
   * not JSON.
   *
   * The refusal is asserted alongside the absence, because an unreadable client that produced
   * nothing at all would be its own bug: the operator would see a connector failing with no reason
   * given, and the credential is the reason.
   */
  describe("a stored OAuth client that does not read back as one", () => {
    /*
     * A bare secret where a client object belongs — the shape a wrongly encrypted row really has,
     * and the worst case for the leak. It decrypts, so the vault is happy; it is not JSON, so the
     * parse fails; and it is a single identifier token, which is what the parser quotes back
     * WHOLE. Distinctive, so an assertion can look for the plaintext itself rather than a shape.
     */
    const UNREADABLE_PLAINTEXT = `secret_notJsonClient${suite}`;
    /** What the person and the trail are told instead, which is the operator's signal. */
    const UNUSABLE = "Notion needs connecting again.";

    /** The client the suite registered, restored after each test repoints the server. */
    let registeredClientId: string | null = null;

    /** Point the server at a vault row that decrypts to something that is not a client. */
    async function pointAtUnreadableClient() {
      const [server] = await database
        .select({ credentialId: mcpServers.credentialId })
        .from(mcpServers)
        .where(eq(mcpServers.id, rotationServerId));
      registeredClientId = server?.credentialId ?? null;

      const [credential] = await database
        .insert(credentials)
        .values({
          kind: "mcp_oauth_client",
          provider: rotationServerId,
          // Fresh per call, because `credentials_active_key_idx` holds one live row per
          // (kind, provider, key_id) and the row this leaves behind is never revoked.
          keyId: `oauth-client-unreadable-${randomUUID().slice(0, 8)}`,
          metadata: {},
          encryptedValue: await encryptSecret(
            ROTATION_KEY,
            UNREADABLE_PLAINTEXT,
          ),
        })
        .returning({ id: credentials.id });
      if (!credential) throw new Error("unreadable client was not stored");
      vaultRows.push(credential.id);

      await database
        .update(mcpServers)
        .set({ credentialId: credential.id })
        .where(eq(mcpServers.id, rotationServerId));
    }

    /** Put the readable client back, so the tests after this one still have one. */
    async function restoreClient() {
      await database
        .update(mcpServers)
        .set({ credentialId: registeredClientId })
        .where(eq(mcpServers.id, rotationServerId));
    }

    test("the trail of a refused call carries neither the plaintext nor the parser", async () => {
      await connect();
      await pointAtUnreadableClient();
      try {
        /*
         * The throw is held rather than asserted on first, because what this test is about is the
         * ROW. Asserting the thrown type up front would fail on the unguarded code before any
         * durable store had been read, and report the wrong thing.
         */
        const refusal = await rotationStore
          .callTool({
            ref: rotationRef,
            args: {},
            botId: rotationBotId,
            actorId: rotationUserId,
          })
          .then(
            () => null,
            (error: unknown) => error,
          );

        const failures = (
          await auditRowsFor(rotationRef, rotationBotId, rotationUserId)
        ).filter((row) => row.eventType === "mcp.call_failed");
        const written = JSON.stringify(failures);
        expect(written).not.toContain(UNREADABLE_PLAINTEXT);
        /*
         * The parser's vocabulary as well as the plaintext. A parser quotes only a window of its
         * input — how wide is the runtime's business, not ours — so a message could carry a
         * fragment the assertion above would miss, and any of these words reaching the trail means
         * a parse wrote it.
         */
        expect(written).not.toContain("JSON Parse error");
        expect(written).not.toContain("SyntaxError");
        expect(written).not.toContain("Unexpected");
        // And the operator is still told which thing is broken, in the trail and to the caller.
        expect(written).toContain(UNUSABLE);
        expect(refusal).toBeInstanceOf(PluginRefusedError);
      } finally {
        await restoreClient();
      }
    });

    test("a refresh leaves the same absence in the server's last error", async () => {
      await connect();
      const [before] = await database
        .select({ lastError: mcpServers.lastError })
        .from(mcpServers)
        .where(eq(mcpServers.id, rotationServerId));
      await pointAtUnreadableClient();
      try {
        // Refuses before the vendor is asked, so nothing here needs a reachable Notion.
        expect(
          await rotationStore.refreshTools(rotationServerId, rotationUserId),
        ).toEqual({ tools: 0 });

        const [after] = await database
          .select({ lastError: mcpServers.lastError })
          .from(mcpServers)
          .where(eq(mcpServers.id, rotationServerId));
        const written = after?.lastError ?? "";
        expect(written).not.toContain(UNREADABLE_PLAINTEXT);
        expect(written).not.toContain("JSON Parse error");
        expect(written).not.toContain("SyntaxError");
        expect(written).not.toContain("Unexpected");
        expect(written).toContain(UNUSABLE);
      } finally {
        await restoreClient();
        await database
          .update(mcpServers)
          .set({ lastError: before?.lastError ?? null })
          .where(eq(mcpServers.id, rotationServerId));
      }
    });
  });
});

/** Borrow a catalogue client's slot, then restore it after removing exactly our own vault rows. */
function oauthClientFixture(serverId: string) {
  const realVault = createCredentialStore(database);
  const owned = new Set<string>();
  const clientKey = and(
    eq(credentials.kind, "mcp_oauth_client"),
    eq(credentials.provider, serverId),
    eq(credentials.keyId, `oauth-client-${serverId}`),
  );
  let before:
    | {
        credentialId: string | null;
        updatedAt: string;
        clients: { id: string; revokedAt: string | null; updatedAt: string }[];
      }
    | undefined;

  return {
    track: (id: string) => owned.add(id),
    vault: {
      ...realVault,
      // Forward the caller's transaction: the credential and its pointer must commit together.
      create: async (
        value: Parameters<typeof realVault.create>[0],
        executor?: Parameters<typeof realVault.create>[1],
      ) => {
        const row = await realVault.create(value, executor);
        owned.add(row.id);
        return row;
      },
      // rotate inserts directly; wrapping create alone misses every replacement it mints.
      rotate: async (
        value: Parameters<typeof realVault.rotate>[0],
        executor?: Parameters<typeof realVault.rotate>[1],
      ) => {
        const row = await realVault.rotate(value, executor);
        owned.add(row.id);
        return row;
      },
    },
    start: async () => {
      before = await database.transaction(async (transaction) => {
        const [server] = await transaction
          .select({
            credentialId: mcpServers.credentialId,
            updatedAt: sql<string>`${mcpServers.updatedAt}::text`,
          })
          .from(mcpServers)
          .where(eq(mcpServers.id, serverId))
          .for("update");
        if (!server) throw new Error("fixture server was not stored");
        // Dates round PostgreSQL microseconds to milliseconds. Keep the exact stamps as text.
        const clients = await transaction
          .select({
            id: credentials.id,
            revokedAt: sql<string | null>`${credentials.revokedAt}::text`,
            updatedAt: sql<string>`${credentials.updatedAt}::text`,
          })
          .from(credentials)
          .where(and(clientKey, sql`${credentials.revokedAt} IS NULL`))
          .for("update");
        await transaction
          .update(mcpServers)
          .set({ credentialId: null })
          .where(eq(mcpServers.id, serverId));
        if (clients.length > 0) {
          await transaction
            .update(credentials)
            .set({ revokedAt: new Date(), updatedAt: new Date() })
            .where(
              inArray(
                credentials.id,
                clients.map((row) => row.id),
              ),
            );
        }
        return { ...server, clients };
      });
    },
    retireClients: async () => {
      if (owned.size === 0) return;
      await database
        .update(credentials)
        .set({ revokedAt: new Date(), updatedAt: new Date() })
        .where(
          and(
            clientKey,
            inArray(credentials.id, [...owned]),
            sql`${credentials.revokedAt} IS NULL`,
          ),
        );
    },
    restore: async () => {
      const snapshot = before;
      if (!snapshot) return;
      await database.transaction(async (transaction) => {
        await transaction
          .update(mcpServers)
          .set({ credentialId: null })
          .where(eq(mcpServers.id, serverId));
        if (owned.size > 0) {
          await transaction
            .delete(credentials)
            .where(inArray(credentials.id, [...owned]));
        }
        // Free the active key before reviving its original row, then restore the pointer atomically.
        for (const row of snapshot.clients) {
          await transaction
            .update(credentials)
            .set({
              revokedAt: sql`${row.revokedAt}::timestamptz`,
              updatedAt: sql`${row.updatedAt}::timestamptz`,
            })
            .where(eq(credentials.id, row.id));
        }
        await transaction
          .update(mcpServers)
          .set({
            credentialId: snapshot.credentialId,
            updatedAt: sql`${snapshot.updatedAt}::timestamptz`,
          })
          .where(eq(mcpServers.id, serverId));
      });
      before = undefined;
      owned.clear();
    },
  };
}

test.each(["success", "failure"])(
  "OAuth client fixture restores exact state after %s following create and rotate",
  async (outcome) => {
    const fixtureServerId = `oauth-fixture-${suite}-${outcome}`;
    const originalId = randomUUID();
    const sentinelId = randomUUID();
    const fixture = oauthClientFixture(fixtureServerId);
    const value: CredentialStoreValue = {
      kind: "mcp_oauth_client",
      provider: fixtureServerId,
      keyId: `oauth-client-${fixtureServerId}`,
      metadata: {},
      encryptedValue: "synthetic-fixture-value",
    };
    const state = async () => ({
      credentials: await database
        .select({ row: sql`to_jsonb(${credentials})` })
        .from(credentials)
        .where(
          inArray(credentials.provider, [
            fixtureServerId,
            `${fixtureServerId}-unrelated`,
          ]),
        )
        .orderBy(credentials.id),
      server: await database
        .select({ row: sql`to_jsonb(${mcpServers})` })
        .from(mcpServers)
        .where(eq(mcpServers.id, fixtureServerId)),
    });
    try {
      await database.insert(credentials).values([
        {
          ...value,
          id: originalId,
          updatedAt: sql`'2020-01-02 03:04:05.123456+00'::timestamptz`,
        },
        { ...value, id: sentinelId, provider: `${fixtureServerId}-unrelated` },
      ]);
      await database.insert(mcpServers).values({
        id: fixtureServerId,
        title: fixtureServerId,
        vendor: "Synthetic fixture",
        url: "https://fixture.invalid/mcp",
        credentialId: originalId,
      });
      const before = await state();
      const exercise = async () => {
        try {
          await fixture.start();
          await fixture.retireClients();
          const created = await database.transaction((transaction) =>
            fixture.vault.create(value, transaction),
          );
          const rotated = await database.transaction(async (transaction) => {
            const row = await fixture.vault.rotate(
              { ...value, previousCredentialId: created.id },
              transaction,
            );
            await transaction
              .update(mcpServers)
              .set({ credentialId: row.id })
              .where(eq(mcpServers.id, fixtureServerId));
            return row;
          });
          expect(await fixture.vault.isLive(created.id)).toBe(false);
          expect(await fixture.vault.isLive(rotated.id)).toBe(true);
          if (outcome === "failure") {
            throw new Error("fixture operation failed after rotation");
          }
        } finally {
          await fixture.restore();
        }
      };
      if (outcome === "failure") {
        await expect(exercise()).rejects.toThrow(
          "fixture operation failed after rotation",
        );
      } else {
        await exercise();
      }
      // Full PostgreSQL rows catch timestamp rounding, leaked replacements and sentinel damage.
      expect(await state()).toEqual(before);
      expect(await fixture.vault.isLive(originalId)).toBe(true);
    } finally {
      await fixture.restore();
      await database
        .delete(mcpServers)
        .where(eq(mcpServers.id, fixtureServerId));
      await database
        .delete(credentials)
        .where(inArray(credentials.id, [originalId, sentinelId]));
    }
  },
);

/**
 * A real MCP server on localhost answering as the pinned Notion host, and everything a refresh
 * against it overwrites put back afterwards.
 *
 * The seam is `fetch`: the host is pinned and nothing in the store will take a URL from a caller, so
 * pointing the pinned host at the mock is what lets a real listing over the real protocol happen.
 * What a refresh then overwrites is the deployment's own row — it replaces the advertised tool list
 * wholesale and stamps `toolsRefreshedAt` and `lastError` — so the list and both stamps are read
 * first and put back in a `finally`.
 *
 * A `finally` rather than a paragraph copied per test, because a restore is the part that a test
 * still passes without: skip it and the cost lands on whatever runs next, reading a tool list this
 * test invented.
 */
async function withMockedNotionListing(
  notionServerId: string,
  /*
   * The mock's own tool shape, plus the annotations a real server publishes.
   *
   * `MCPToolDefinition` names only name, description and schema, and the mock hands whatever it was
   * given straight back in its `tools/list` answer — so an annotation travels at runtime and is
   * simply unspellable in the type. Widened here rather than cast at each fixture, because the
   * hints are what `listTools` reads to decide an action's recorded effect, and a test about that
   * decision should not be the one place a cast hides a shape drifting.
   */
  tools: (MCPToolDefinition & { annotations?: ToolAnnotations })[],
  body: () => Promise<void>,
) {
  const mock = new MCPMock();
  for (const tool of tools) mock.addTool(tool);
  const mockUrl = await mock.start();

  const advertisedBefore = await database
    .select()
    .from(mcpTools)
    .where(eq(mcpTools.serverId, notionServerId));
  const [stampBefore] = await database
    .select({
      toolsRefreshedAt: mcpServers.toolsRefreshedAt,
      lastError: mcpServers.lastError,
    })
    .from(mcpServers)
    .where(eq(mcpServers.id, notionServerId));

  const realFetch = globalThis.fetch;
  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
    const target = String(input instanceof Request ? input.url : input);
    return realFetch(
      target.startsWith("https://mcp.notion.com") ? mockUrl : input,
      init,
    );
  }) as typeof fetch;

  try {
    await body();
  } finally {
    globalThis.fetch = realFetch;
    await mock.stop?.();
    await database
      .delete(mcpTools)
      .where(eq(mcpTools.serverId, notionServerId));
    if (advertisedBefore.length > 0) {
      await database.insert(mcpTools).values(advertisedBefore);
    }
    await database
      .update(mcpServers)
      .set({
        toolsRefreshedAt: stampBefore?.toolsRefreshedAt ?? null,
        lastError: stampBefore?.lastError ?? null,
      })
      .where(eq(mcpServers.id, notionServerId));
  }
}

/**
 * A client this deployment registered for itself, which the vendor has since forgotten.
 *
 * A dynamically registered client is nobody's paperwork: there is no console entry an administrator
 * could go and re-create, so a vendor that evicts one — a pruned test client, an expired
 * registration — would otherwise strand every connection to that server behind a refusal nobody in
 * the deployment can act on. The one thing the deployment CAN do is introduce itself again, which is
 * exactly what it did the first time, so it does that once and retries.
 *
 * Once, and only once. A retry that re-registered on every refusal would answer a vendor outage by
 * minting clients in a loop, and the second refusal is the honest signal that the problem is not the
 * client at all.
 */
describe("a dynamic client the vendor has evicted", () => {
  const dynamicBotId = `agent_dynamic_bot_${suite}`;
  const dynamicUserId = `user_dynamic_${suite}`;
  /** Notion, because it is the entry that registers itself. */
  const dynamicServerId = "notion";
  /** Suite-scoped, so it cannot collide with a name Notion really advertises. */
  const dynamicToolName = `search_dyn_${suite}`;
  const dynamicRef = `${dynamicServerId}/${dynamicToolName}`;
  /** 32 zero bytes in base64: a real AES-256 key, because every call here opens the vault. */
  const DYNAMIC_KEY = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  /** The client the deployment registered once and the vendor has stopped honouring. */
  const EVICTED: OAuthClient = { clientId: "dyn-1", clientSecret: "" };
  /** What registering again gets. No secret: a DCR client proves itself with PKCE. */
  const FRESH: OAuthClient = { clientId: "dyn-2", clientSecret: "" };
  /** Built the way the callback route builds it, so the vendor is offered the real thing. */
  const REDIRECT_URI = redirectUriFor("https://openbot.test");
  /** The pinned endpoint, read from the entry rather than copied, so the two cannot drift. */
  const REGISTRATION_URL = (() => {
    const entry = catalogueEntry(dynamicServerId);
    if (entry?.auth.kind !== "user-oauth" || !entry.auth.registrationUrl) {
      throw new Error(
        "notion is not a dynamically registered user-oauth entry",
      );
    }
    return entry.auth.registrationUrl;
  })();
  const SCOPE = "";

  const clientFixture = oauthClientFixture(dynamicServerId);
  const vault = clientFixture.vault;
  /** Which client each exchange was offered, in order. One entry per call, never two. */
  const offered: string[] = [];
  /**
   * Every exchange as the pair it really is: which client presented which grant.
   *
   * The pair is the property, not either half. A refresh token belongs to the client it was issued
   * to — RFC 6749 §6 has the token endpoint check exactly that, and §10.4 says why — so a pair
   * naming a token under a client it was never issued to is this deployment attempting to spend one
   * client's grant as another's. No call may ever produce one.
   */
  const exchanges: { clientId: string; refreshToken: string }[] = [];
  /** Which client the vendor issued each refresh token to, so the stub can enforce the binding. */
  const issuedTo = new Map<string, string>();
  /** Every registration the store asked the vendor for, with what it asked with. */
  const registrations: { registrationUrl: string; redirectUri: string }[] = [];
  /** Which client ids the vendor still honours. Anything else is answered `invalid_client`. */
  let accepted = new Set<string>();
  /** What the vendor's registration endpoint hands back, installed per test. */
  let issue: () => OAuthClient | null = () => {
    throw new Error("no registration was installed for this test");
  };

  /**
   * How the vendor refuses a client it no longer honours.
   *
   * Both halves of what `exchangeRefreshTokenOverHttp` builds for a reply carrying an `error` code:
   * the sentence a person reads, and the code as a FIELD. The field is the half the retry
   * reads, which is why it is set structurally here rather than spelled into the prose — two tests
   * below vary each half independently to prove which one is load-bearing.
   */
  const evictionRefusal = () =>
    new TokenRefusedError(
      "The vendor would not renew this access (401). (invalid_client)",
      INVALID_CLIENT,
    );
  /** The refusal in force, so a test can vary the sentence or the code. Reset before each. */
  let refuse: () => Error = evictionRefusal;

  /*
   * The exchange, standing in for the vendor's token endpoint.
   */
  const seams = {
    exchangeRefreshToken: async ({
      client,
      refreshToken,
    }: {
      tokenUrl: string;
      client: OAuthClient;
      refreshToken: string;
    }): Promise<AccessToken> => {
      offered.push(client.clientId);
      exchanges.push({ clientId: client.clientId, refreshToken });
      if (!accepted.has(client.clientId)) {
        throw refuse();
      }
      /*
       * A grant belongs to one client, and this stub enforces it.
       *
       * It did not, and that omission is what made the old "register again and re-present the same
       * refresh token" retry look like it worked. It only ever worked against a vendor that skipped
       * the check RFC 6749 §6 requires — so the mechanism was pinned by a fixture whose behaviour
       * would itself have been the vulnerability.
       */
      const owner = issuedTo.get(refreshToken);
      if (owner !== undefined && owner !== client.clientId) {
        throw new TokenRefusedError(
          "The vendor would not renew this access (400). (invalid_grant)",
          "invalid_grant",
        );
      }
      // The same token back, so nothing rotates: what this suite is about is the client.
      return { accessToken: `at-${client.clientId}`, refreshToken };
    },
    registerClient: async (input: {
      registrationUrl: string;
      redirectUri: string;
    }) => {
      registrations.push(input);
      return issue();
    },
  };

  const dynamicStore = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore: createAuditStore(database),
    credentials: vault,
    encryptionKey: DYNAMIC_KEY,
    policy: () => policy,
    callVendor: async () => ({
      text: "[vendor not reached in tests]",
      isError: false,
    }),
    ...seams,
    redirectUri: REDIRECT_URI,
  });

  /**
   * The same store, for a deployment with no public URL.
   *
   * There is nowhere for the vendor to send anybody back to, so there is nothing honest to register
   * — and registering a redirect URI that does not resolve would leave a client that can never
   * complete a consent flow.
   */
  const storeWithNoRedirect = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore: createAuditStore(database),
    credentials: vault,
    encryptionKey: DYNAMIC_KEY,
    policy: () => policy,
    ...seams,
  });

  /**
   * Point the server at a client, the way a registration does, without going through one.
   *
   * Aged an hour by default, because that is the client these tests are about: one the deployment
   * has been using for a while and the vendor has since evicted. A row written a moment ago is
   * inside the re-registration window and is deliberately not registered around, which is its own
   * test below rather than the state every other test starts from.
   */
  async function putClient(
    client: OAuthClient,
    registeredAt = new Date(Date.now() - 60 * 60 * 1000),
  ) {
    /*
     * One live client per key is law (`credentials_active_key_idx`), so planting a client the way a
     * registration would means retiring whatever live row the key still holds from an earlier test.
     */
    await clientFixture.retireClients();
    const [row] = await database
      .insert(credentials)
      .values({
        kind: "mcp_oauth_client",
        provider: dynamicServerId,
        keyId: `oauth-client-${dynamicServerId}`,
        metadata: { clientId: client.clientId },
        encryptedValue: await encryptSecret(
          DYNAMIC_KEY,
          JSON.stringify(client),
        ),
        createdAt: registeredAt,
      })
      .returning({ id: credentials.id });
    if (!row) throw new Error("client was not stored");
    clientFixture.track(row.id);
    await database
      .update(mcpServers)
      .set({ credentialId: row.id })
      .where(eq(mcpServers.id, dynamicServerId));
  }

  /** A deployment that holds no client for this server at all. */
  async function clearClient(serverId = dynamicServerId) {
    await database
      .update(mcpServers)
      .set({ credentialId: null })
      .where(eq(mcpServers.id, serverId));
  }

  /**
   * How many of those rows say a particular actor registered a particular client.
   *
   * Counted rather than "the most recent row", because these rows have no ordering finer than the
   * second they were written in and this suite writes several of them.
   */
  const registeredBy = (
    rows: { actor: string; clientId: string }[],
    actor: string,
    clientId: string,
  ) =>
    rows.filter((row) => row.actor === actor && row.clientId === clientId)
      .length;

  /** What the trail says about clients registered for this server, and by whom. */
  async function registeredRows() {
    return database
      .select({
        actor: sql<string>`payload ->> 'actor'`,
        clientId: sql<string>`payload ->> 'clientId'`,
      })
      .from(auditEvents)
      .where(
        and(
          eq(auditEvents.eventType, "mcp.oauth_client_registered"),
          eq(auditEvents.targetId, dynamicServerId),
          // `notion` and `dyn-1` are fixed spellings, so without this the count is every run's.
          sinceThisRun(),
        ),
      );
  }

  /**
   * A connection holding `rt-1`, written through the store so the vault is exercised.
   *
   * `issuedBy` is which client the vendor issued that grant to, which is the fact the stub above
   * enforces. It is the evicted one in every test here, because that is what an eviction means: the
   * grant somebody holds was obtained under the client the vendor has since stopped honouring.
   */
  async function connect(issuedBy: OAuthClient = EVICTED) {
    await dynamicStore.recordConnection({
      serverId: dynamicServerId,
      userId: dynamicUserId,
      refreshToken: "rt-1",
      scope: SCOPE,
    });
    issuedTo.set("rt-1", issuedBy.clientId);
    offered.length = 0;
    exchanges.length = 0;
    registrations.length = 0;
  }

  /** One tool call by the connected person, which is every call this suite makes. */
  const call = () =>
    dynamicStore.callTool({
      ref: dynamicRef,
      args: {},
      botId: dynamicBotId,
      actorId: dynamicUserId,
    });

  /** Whether THIS RUN put the `notion` row there. Counted, never inferred from an absence. */
  let suiteCreatedNotionRow = false;

  // The vendor refuses the ordinary way unless a test says otherwise, so a test that varies the
  // refusal cannot leave the next one asserting against somebody else's setup.
  beforeEach(() => {
    refuse = evictionRefusal;
  });

  beforeAll(async () => {
    await database
      .insert(agents)
      .values({
        id: dynamicBotId,
        name: dynamicBotId,
        type: "remote_ag_ui",
        configuration: {},
      })
      .onConflictDoNothing();
    await database
      .insert(users)
      .values({
        id: dynamicUserId,
        email: `${dynamicUserId}@openbot.test`,
        name: dynamicUserId,
        emailVerified: false,
      })
      .onConflictDoNothing();

    const [existing] = await database
      .select({ id: mcpServers.id })
      .from(mcpServers)
      .where(eq(mcpServers.id, dynamicServerId));
    suiteCreatedNotionRow = existing === undefined;

    await database
      .insert(mcpServers)
      .values({
        id: dynamicServerId,
        title: "Notion",
        vendor: "Notion",
        url: "https://mcp.notion.com/mcp",
        provenance: "first-party",
      })
      .onConflictDoNothing();
    await clientFixture.start();
    await database
      .insert(mcpTools)
      .values({
        serverId: dynamicServerId,
        name: dynamicToolName,
        vendorName: dynamicToolName,
        description: "Search pages.",
      })
      .onConflictDoNothing();
    await dynamicStore.grant(
      "mcp",
      dynamicRef,
      dynamicBotId,
      "[email protected]",
    );
  });

  afterAll(async () => {
    await database
      .delete(mcpUserCredentials)
      .where(
        and(
          eq(mcpUserCredentials.serverId, dynamicServerId),
          eq(mcpUserCredentials.userId, dynamicUserId),
        ),
      );
    await clientFixture.restore();
    await database
      .delete(pluginGrants)
      .where(
        and(
          eq(pluginGrants.ref, dynamicRef),
          eq(pluginGrants.agentId, dynamicBotId),
        ),
      );
    await database
      .delete(mcpTools)
      .where(
        and(
          eq(mcpTools.serverId, dynamicServerId),
          eq(mcpTools.name, dynamicToolName),
        ),
      );
    if (suiteCreatedNotionRow) {
      await database
        .delete(mcpTools)
        .where(eq(mcpTools.serverId, dynamicServerId));
      await database
        .delete(mcpServers)
        .where(eq(mcpServers.id, dynamicServerId));
    }
    await database.delete(agents).where(eq(agents.id, dynamicBotId));
    await database.delete(users).where(eq(users.id, dynamicUserId));
  });

  test("the deployment registers again, once, and refuses this call", async () => {
    await putClient(EVICTED);
    await connect();
    const registeredBefore = await registeredRows();
    // The vendor honours the fresh client, so a retry under it is exactly what would have LOOKED
    // like a recovery. The point of this test is that it is not attempted.
    accepted = new Set([FRESH.clientId]);
    issue = () => FRESH;

    /*
     * The person is told to connect again, because that is the only thing that can help them.
     *
     * Their refresh token was issued to the client the vendor has forgotten, and a grant belongs to
     * the client it was issued to. There is no arrangement of stored secrets that turns it into a
     * usable one — only a new consent under the client that now exists.
     */
    await expect(call()).rejects.toThrow(
      "Notion needs connecting again, so this wasn't done.",
    );

    /*
     * One exchange, on the client the deployment held. The old grant is never presented to the new
     * client: a conforming vendor refuses that (RFC 6749 §6), so the retry that used to be here
     * could only ever have succeeded against a vendor whose acceptance was itself the bug.
     */
    expect(offered).toEqual([EVICTED.clientId]);
    expect(exchanges).toEqual([
      { clientId: EVICTED.clientId, refreshToken: "rt-1" },
    ]);

    // Registered exactly once, with the pinned endpoint and the deployment's own redirect URI —
    // never a URL from the request, which is the property `redirectUriFor` exists for.
    expect(registrations).toEqual([
      { registrationUrl: REGISTRATION_URL, redirectUri: REDIRECT_URI },
    ]);

    // And kept, so the connect this refusal sends somebody to uses the client that works.
    expect(await dynamicStore.oauthClientFor(dynamicServerId)).toEqual(FRESH);

    /*
     * With a row in the trail saying the deployment did it to itself.
     *
     * `deployment` rather than the person whose call triggered it: they consented to nothing here,
     * and a trail naming them would read as an administrator having registered a client.
     */
    const registered = await registeredRows();
    expect(registered.length).toBe(registeredBefore.length + 1);
    expect(registeredBy(registered, "deployment", FRESH.clientId)).toBe(
      registeredBy(registeredBefore, "deployment", FRESH.clientId) + 1,
    );
  });

  test("a vendor refusing everything costs one registration, not one per call", async () => {
    await putClient(EVICTED);
    await connect();
    // The vendor honours nothing, which is what an outage looks like from here.
    accepted = new Set<string>();
    issue = () => ({ clientId: "dyn-3", clientSecret: "" });

    await expect(call()).rejects.toThrow(
      "Notion needs connecting again, so this wasn't done.",
    );
    expect(registrations.length).toBe(1);
    expect(exchanges).toEqual([
      { clientId: EVICTED.clientId, refreshToken: "rt-1" },
    ]);

    /*
     * The next call is a NEW call, not a retry: it reads the client the deployment now holds, offers
     * it once, and is refused. What it must not do is register a second one — dyn-3 was stored
     * moments ago, so it is inside the re-registration window and is left alone. That is the
     * difference between an outage costing one client and costing one per tool call.
     */
    exchanges.length = 0;
    await expect(call()).rejects.toThrow("invalid_client");
    expect(registrations.length).toBe(1);
    expect(exchanges).toEqual([{ clientId: "dyn-3", refreshToken: "rt-1" }]);
  });

  /**
   * A client minted moments ago is not registered around again.
   *
   * Once per call is right for one call and wrong for a deployment: a vendor answering every
   * exchange `invalid_client` — an outage, not an eviction — has every tool call anywhere in the
   * deployment mint a client of its own, because each of them is the first refusal it has seen.
   * The age of the stored client is the one piece of shared state that says otherwise, and a client
   * younger than the window is already the product of somebody's re-registration.
   */
  test("a client registered moments ago is refused rather than replaced", async () => {
    // Written now, the way a re-registration would have written it a moment ago.
    await putClient(EVICTED, new Date());
    await connect();
    accepted = new Set<string>();
    issue = () => FRESH;

    // The vendor's own refusal, surfaced as it stands: nothing here can improve on it.
    await expect(call()).rejects.toThrow("invalid_client");

    expect(registrations).toEqual([]);
    expect(offered).toEqual([EVICTED.clientId]);
    expect(exchanges).toEqual([
      { clientId: EVICTED.clientId, refreshToken: "rt-1" },
    ]);
  });

  /**
   * The code decides, not the sentence.
   *
   * The sentence is written for a person and will be reworded — shortened, translated, given a
   * different parenthesis. When the recovery hung on a substring of it, any of those edits would
   * have switched self-registration off with every test in this file still passing, and the symptom
   * would have been every Notion connection in the deployment stranded behind a refusal.
   */
  test("a refusal that words it differently still re-registers", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([FRESH.clientId]);
    issue = () => FRESH;
    // Not one character of the code anywhere in the prose.
    refuse = () =>
      new TokenRefusedError(
        "Le fournisseur a refusé de renouveler cet accès (401).",
        INVALID_CLIENT,
      );

    await expect(call()).rejects.toThrow(
      "Notion needs connecting again, so this wasn't done.",
    );

    expect(offered).toEqual([EVICTED.clientId]);
    expect(registrations.length).toBe(1);
    expect(await dynamicStore.oauthClientFor(dynamicServerId)).toEqual(FRESH);
  });

  /** And the other way round: prose that says the word, over a code that does not. */
  test("a refusal whose code is another one is not registered around", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set<string>();
    issue = () => FRESH;
    refuse = () =>
      new TokenRefusedError(
        "The vendor would not renew this access (400). (invalid_grant, not an invalid_client problem)",
        "invalid_grant",
      );

    // A withdrawn grant is the person's to fix by connecting again: the refusal draws the card that
    // says so, rather than folding the vendor's code into a tool error.
    const refusal = await call().catch((error: unknown) => error);
    expect(refusal).toBeInstanceOf(PluginRefusedError);
    expect(readConnectPrompt((refusal as Error).message)).toMatchObject({
      serverId: dynamicServerId,
      reason: "reconnect",
    });

    // Minting a client for it would leave a spare client behind and still refuse.
    expect(registrations).toEqual([]);
    expect(offered).toEqual([EVICTED.clientId]);

    // And the connection now reads as withdrawn, which is Reconnect on every screen.
    const [connection] = await dynamicStore.connectionsFor(dynamicUserId);
    expect(connection).toMatchObject({
      serverId: dynamicServerId,
      revoked: true,
    });
    // The next call is refused before anything is presented to the vendor again.
    offered.length = 0;
    await expect(call()).rejects.toBeInstanceOf(PluginRefusedError);
    expect(offered).toEqual([]);
  });

  /**
   * Two calls queued on one connection, and one registration between them.
   *
   * The client is read INSIDE the per-connection critical section, so the second call reads it after
   * the first has replaced it. Read before the queue instead, both calls would carry the evicted
   * client in, both would be refused, and both would register — a client minted per queued call, on
   * a deployment whose client the first call already replaced.
   *
   * Both calls fail, and they fail differently, which is the honest outcome. The first found the
   * client evicted; the second offered the client that now exists and was refused because the grant
   * it holds was issued to the old one. Only a new consent fixes that, and both refusals say so.
   */
  test("two calls queued on one connection register once between them", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([FRESH.clientId]);
    issue = () => FRESH;

    const results = await Promise.allSettled([call(), call()]);

    expect(results.map((result) => result.status)).toEqual([
      "rejected",
      "rejected",
    ]);
    // One exchange per call, and never a token offered twice inside one of them.
    expect(offered).toEqual([EVICTED.clientId, FRESH.clientId]);
    expect(registrations.length).toBe(1);
  });

  test("a client the deployment already holds is handed back untouched", async () => {
    await putClient(EVICTED);
    registrations.length = 0;

    expect(
      await dynamicStore.ensureOAuthClient(
        dynamicServerId,
        "[email protected]",
      ),
    ).toEqual(EVICTED);
    // Nothing was asked of the vendor: this is the path every connect takes once, and it must not
    // mint a client on top of the working one.
    expect(registrations).toEqual([]);
  });

  test("a dynamic entry with no client gets one, kept and recorded", async () => {
    await clearClient();
    registrations.length = 0;
    const registeredBefore = await registeredRows();
    issue = () => FRESH;

    expect(
      await dynamicStore.ensureOAuthClient(
        dynamicServerId,
        "[email protected]",
      ),
    ).toEqual(FRESH);
    expect(registrations).toEqual([
      { registrationUrl: REGISTRATION_URL, redirectUri: REDIRECT_URI },
    ]);
    expect(await dynamicStore.oauthClientFor(dynamicServerId)).toEqual(FRESH);

    const registered = await registeredRows();
    expect(registered.length).toBe(registeredBefore.length + 1);
    // Whoever pressed Connect, because for a first registration that IS the act that caused it.
    expect(
      registeredBy(registered, "[email protected]", FRESH.clientId),
    ).toBe(
      registeredBy(registeredBefore, "[email protected]", FRESH.clientId) +
        1,
    );
  });

  /**
   * The registration nothing stands in for.
   *
   * Every other test here injects `registerClient`, which is right for asserting what the store does
   * with an answer but means the real function is never the one answering. What it returns when the
   * vendor cannot be reached at all is exactly what the store's `null` branches were written for, so
   * once that path exists it is worth one test that lets the real code produce the value rather than
   * a stub asserting the value the real code is assumed to produce.
   */
  const storeWithRealRegistration = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore: createAuditStore(database),
    credentials: vault,
    encryptionKey: DYNAMIC_KEY,
    policy: () => policy,
    callVendor: async () => ({
      text: "[vendor not reached in tests]",
      isError: false,
    }),
    exchangeRefreshToken: seams.exchangeRefreshToken,
    redirectUri: REDIRECT_URI,
  });

  test("an unreachable registration endpoint leaves no client and no trail", async () => {
    await clearClient();
    const registeredBefore = await registeredRows();
    const said: string[] = [];
    const realError = console.error;
    const realFetch = globalThis.fetch;
    console.error = (...args: unknown[]) => {
      said.push(args.map(String).join(" "));
    };
    globalThis.fetch = (async () => {
      throw new TypeError("Unable to connect.");
    }) as unknown as typeof fetch;

    try {
      expect(
        await storeWithRealRegistration.ensureOAuthClient(
          dynamicServerId,
          "[email protected]",
        ),
      ).toBeNull();
    } finally {
      globalThis.fetch = realFetch;
      console.error = realError;
    }

    // Nothing kept, and nothing claimed. A trail row here would say this deployment registered
    // itself with a vendor that never answered.
    expect(
      await storeWithRealRegistration.oauthClientFor(dynamicServerId),
    ).toBe(null);
    expect((await registeredRows()).length).toBe(registeredBefore.length);
    expect(
      said.find((line) =>
        line.includes("oauth-registration-endpoint-unreachable"),
      ),
    ).toBeDefined();
  });

  test("an entry an administrator registers by hand is left alone", async () => {
    /*
     * Drive, whose client is pasted in from Google's console. Registering one for it would be
     * inventing a client at a vendor that never offered to issue one — the honest answer is none,
     * and the 409 an administrator sees is the instruction to go and paste one.
     */
    const [before] = await database
      .select({ credentialId: mcpServers.credentialId })
      .from(mcpServers)
      .where(eq(mcpServers.id, serverId));
    await clearClient(serverId);
    registrations.length = 0;

    try {
      expect(
        await dynamicStore.ensureOAuthClient(serverId, "[email protected]"),
      ).toBeNull();
      expect(registrations).toEqual([]);
    } finally {
      await database
        .update(mcpServers)
        .set({ credentialId: before?.credentialId ?? null })
        .where(eq(mcpServers.id, serverId));
    }
  });

  test("a deployment with no public URL registers nothing", async () => {
    await clearClient();
    registrations.length = 0;

    expect(
      await storeWithNoRedirect.ensureOAuthClient(
        dynamicServerId,
        "[email protected]",
      ),
    ).toBeNull();
    expect(registrations).toEqual([]);
  });

  /**
   * Two people pressing Connect at the same moment, on a deployment holding no client yet.
   *
   * `POST /connect` is `requireUser`, not `requireAdmin`, so this is not a rare interleaving — it is
   * the ordinary first hour of a connector nobody has used. Unserialised, the two runs read "no live
   * client" and then both write one: the second `create` meets the first on
   * `credentials_active_key_idx` as a raw 23505, which reaches the person as a 500 where a consent
   * URL belonged, and a `rotate` racing the same way fails with "Previous credential is already
   * revoked" instead.
   *
   * One client, not two, and that part is not only about the error. Two clients means one of the two
   * consent screens names a client the vault no longer holds, so that person consents and their
   * callback then redeems the code against the other client — a connect that fails after the vendor
   * said yes, which is the hardest possible place to fail.
   */
  test("two first connects race to one client, and both callers get it", async () => {
    await clearClient();
    // No live row for the key either, so this really is a deployment holding nothing: `clearClient`
    // only drops the pointer, and it is the KEY the index constrains.
    await clientFixture.retireClients();
    registrations.length = 0;
    // A distinct client per registration, so two registrations cannot be mistaken for one.
    let issued = 0;
    issue = () => {
      issued += 1;
      return { clientId: `dyn-race-${issued}`, clientSecret: "" };
    };

    const [first, second] = await Promise.all([
      dynamicStore.ensureOAuthClient(dynamicServerId, "[email protected]"),
      dynamicStore.ensureOAuthClient(dynamicServerId, "[email protected]"),
    ]);

    // Neither raised, and neither got null: both people can be sent to consent.
    expect(first).not.toBeNull();
    expect(second).not.toBeNull();
    // The same client, so both consent screens name the client the deployment actually holds.
    expect(first).toEqual(second);
    expect(registrations.length).toBe(1);

    /*
     * One live row for the key, and the server row naming exactly it.
     *
     * The pair is the assertion, not either half: the vault write and the pointer write are one
     * transaction now, so a reader can never see a live client the server row does not name, nor a
     * server row naming a client the vault retired.
     */
    const live = await database
      .select({ id: credentials.id })
      .from(credentials)
      .where(
        and(
          eq(credentials.kind, "mcp_oauth_client"),
          eq(credentials.provider, dynamicServerId),
          eq(credentials.keyId, `oauth-client-${dynamicServerId}`),
          sql`${credentials.revokedAt} IS NULL`,
        ),
      );
    expect(live.length).toBe(1);
    const [server] = await database
      .select({ credentialId: mcpServers.credentialId })
      .from(mcpServers)
      .where(eq(mcpServers.id, dynamicServerId));
    expect(server?.credentialId).toBe(live[0]?.id);
  });

  /**
   * A refresh naming the advertised tools this deployment's write list does not cover.
   *
   * Notion has no scope strings and no read-only scope: access is per-page, chosen on the consent
   * screen, so `writeTools` plus the action policy are the ENTIRE write barrier. The entry's own
   * comment says reconciling that list against the live tool list "is required, not cosmetic" — and
   * until this row existed, nothing mechanical did it. An advertised tool missing from the list
   * classifies as a READ ({@link classifyTool}), so under-inclusion is the failure mode and it is
   * silent.
   *
   * The vendor here is a real MCP server on localhost, reached by pointing the pinned host at it for
   * the length of this test — see {@link withMockedNotionListing}, which also puts back what the
   * refresh overwrites. What is under test is what a real listing over the real protocol produces.
   */
  test("a refresh names the advertised tools no write list covers", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([EVICTED.clientId]);

    /** Suite-scoped, so it cannot be a name Notion really advertises, nor a name in `writeTools`. */
    const unlistedName = `notion-invent-${suite}`;

    await withMockedNotionListing(
      dynamicServerId,
      [
        {
          name: "notion-create-pages",
          description: "A write the list already names.",
          inputSchema: { type: "object", properties: {} },
        },
        {
          name: unlistedName,
          description: "Advertised, and named by no write list.",
          inputSchema: { type: "object", properties: {} },
        },
      ],
      async () => {
        expect(
          await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
        ).toEqual({ tools: 2 });
      },
    );

    // Read after the restore, because the audit trail is what the refresh leaves that the restore
    // does not take back.
    const named = (
      await database
        .select({ payload: auditEvents.payload })
        .from(auditEvents)
        .where(
          and(
            eq(auditEvents.eventType, "configuration.changed"),
            eq(auditEvents.targetId, dynamicServerId),
            sql`payload ->> 'change' = 'unlisted_tools_advertised'`,
            /*
             * `named` is what THIS refresh recorded, not the union over every refresh there has
             * ever been. `notion` and `notion-create-pages` are both fixed spellings, so both
             * assertions below were being answered partly by rows older code wrote: the negative
             * one would report today's classification as wrong on the strength of a row from
             * before the write list covered that name.
             */
            sinceThisRun(),
          ),
        )
    ).flatMap((row) => (row.payload as { tools?: string[] }).tools ?? []);

    // The one the list does not name, and never the one it does.
    expect(named).toContain(unlistedName);
    expect(named).not.toContain("notion-create-pages");
  });

  /**
   * The classification an MCP server has always had, over a real listing that really happened.
   *
   * The three columns the refresh writes are the transports' to fill in, and an MCP server that
   * annotates nothing fills in none of them — which is what every fixture in THIS test does, and
   * so what it is about. It is no longer true of the transport in general: `listTools` reads
   * `annotations.destructiveHint` and writes both `effect` and `destructive` from it, which the
   * test below this one covers. `classifyTool` consults the reviewed `writeTools`
   * list BEFORE the recorded `effect` column, on the criterion that a recorded value may narrow what
   * a Bot is allowed and may never widen it — so a name the list covers stays a write whatever the
   * column says, and a value appearing here can no longer turn one of Notion's reviewed writes into a
   * read. The other direction is still open, which is what this test is for: a name the list does not
   * cover falls through to the column, where PRESENCE rather than truthiness decides, so an effect
   * recorded for Notion would silently reclassify every one of its reads as a write, on a connector
   * nobody touched. Only `null` and `undefined` are silence. Asserted on the rows AND on what the
   * Plugins page derives from them, because it is the second one that an administrator reads.
   *
   * It lives in this suite because this is the only place a `user-oauth` listing can actually be
   * made to happen: the refresh runs on the grant of whoever pressed the button, so a Notion row with
   * nobody connected records a refusal in `lastError` and writes no tools at all — which is a test
   * that passes by having nothing to check.
   */
  test("a refreshed MCP server records no effect, no marker and no version", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([EVICTED.clientId]);

    await withMockedNotionListing(
      dynamicServerId,
      [
        {
          name: "notion-fetch",
          description: "A read no write list names.",
          inputSchema: { type: "object", properties: {} },
        },
        {
          name: "notion-create-pages",
          description: "A write the list already names.",
          inputSchema: { type: "object", properties: {} },
        },
      ],
      async () => {
        // Two tools listed, so the assertions below have something to be about: `every` over an
        // empty list is true, and a refusal recorded in `lastError` would leave exactly that.
        expect(
          await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
        ).toEqual({ tools: 2 });

        const rows = await database
          .select({
            name: mcpTools.name,
            effect: mcpTools.effect,
            destructive: mcpTools.destructive,
            version: mcpTools.version,
          })
          .from(mcpTools)
          .where(eq(mcpTools.serverId, dynamicServerId))
          .orderBy(asc(mcpTools.name));

        expect(rows).toEqual([
          {
            name: "notion-create-pages",
            effect: null,
            destructive: false,
            version: null,
          },
          {
            name: "notion-fetch",
            effect: null,
            destructive: false,
            version: null,
          },
        ]);

        const listed = (await dynamicStore.listServers()).find(
          (server) => server.id === dynamicServerId,
        );

        // The reviewed write list, still deciding: the name it covers is a write and the name it
        // does not is a read. A recorded effect on either row is what would take this over.
        expect(
          listed?.tools.map((tool) => ({
            name: tool.name,
            effect: tool.effect,
          })),
        ).toEqual([
          { name: "notion-create-pages", effect: "write" },
          { name: "notion-fetch", effect: "read" },
        ]);
      },
    );
  });

  /**
   * The one annotation this deployment believes, and the two it declines to.
   *
   * CRITERION. `destructiveHint === true` is recorded as `effect: "write"` and `destructive: true`.
   * `readOnlyHint` is recorded as NOTHING AT ALL — not as `read`, not as a value overridden further
   * down — whether or not the reviewed write list already covers the name.
   *
   * REASON. The SDK warns where it declares these hints that a client must not make tool-use
   * decisions from annotations an untrusted server supplied, and the two hints are not symmetrical
   * against that warning. `destructiveHint` can only move an action from read to write, so a server
   * that lies with it restricts itself. `readOnlyHint` moves an action the other way, and it would
   * buy nothing in the two curated cases — a name on `writeTools` never reaches the column, and a
   * name absent from it already reads as a read — while opening the third: a server an
   * administrator added by URL has no reviewed list, and `classifyTool` returns on the recorded
   * column BEFORE its `if (!entry) return "write"`, so believing the hint would let an arbitrary
   * server declare its whole surface harmless and turn "no reviewed list means everything is a
   * write" into an opt-out.
   *
   * WHY NULL IS THE ASSERTION rather than a classification. Both `readOnlyHint` fixtures come out
   * of `listServers` correctly whatever the column holds — one is on the write list, the other is
   * not — so a classification assertion alone would pass with the hint written down and overruled
   * downstream. NULL in the column is what says it was never read.
   */
  test("a refresh records the effect an MCP server declares, and only the narrowing one", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([EVICTED.clientId]);

    /** Suite-scoped, so it is not a name Notion really advertises nor one `writeTools` covers. */
    const destructiveName = `notion-destroy-${suite}`;

    await withMockedNotionListing(
      dynamicServerId,
      [
        {
          name: "notion-fetch",
          description:
            "A read no write list names, declaring itself read-only.",
          inputSchema: { type: "object", properties: {} },
          annotations: { readOnlyHint: true },
        },
        {
          name: "notion-create-pages",
          description: "A reviewed write, declaring itself read-only.",
          inputSchema: { type: "object", properties: {} },
          annotations: { readOnlyHint: true },
        },
        {
          name: destructiveName,
          description: "Advertised, on no write list, declared destructive.",
          inputSchema: { type: "object", properties: {} },
          annotations: { destructiveHint: true },
        },
      ],
      async () => {
        expect(
          await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
        ).toEqual({ tools: 3 });

        const rows = await database
          .select({
            name: mcpTools.name,
            effect: mcpTools.effect,
            destructive: mcpTools.destructive,
          })
          .from(mcpTools)
          .where(eq(mcpTools.serverId, dynamicServerId))
          .orderBy(asc(mcpTools.name));

        expect(rows).toEqual([
          // The reviewed write, which said it was read-only. Nothing recorded, so nothing to
          // overrule: the write list is still the only thing that answers for this name.
          { name: "notion-create-pages", effect: null, destructive: false },
          // The declaration that narrows, taken at its word.
          { name: destructiveName, effect: "write", destructive: true },
          // The unreviewed read, which also said it was read-only, and is believed about nothing.
          { name: "notion-fetch", effect: null, destructive: false },
        ]);

        const listed = (await dynamicStore.listServers()).find(
          (server) => server.id === dynamicServerId,
        );

        // What the Plugins page derives, which is what an administrator actually reads: the
        // reviewed name is a write because review says so, the declared one is a write because the
        // vendor narrowed it, and the third is the read it was already classified as.
        expect(
          listed?.tools.map((tool) => ({
            name: tool.name,
            effect: tool.effect,
          })),
        ).toEqual([
          { name: "notion-create-pages", effect: "write" },
          { name: destructiveName, effect: "write" },
          { name: "notion-fetch", effect: "read" },
        ]);
      },
    );
  });

  /**
   * A name the model API would refuse costs that one action, not the whole listing.
   *
   * CRITERION. A listing with one dotted name among valid ones stores the valid ones, stamps the
   * refresh, and names the dotted one in `skippedTools`, which the app's page draws as a warning —
   * and NOT in `lastError`, which the Plugins list draws as a failure that, for a server that keeps
   * listing the name, would never clear.
   *
   * REASON. The MCP spec allows a dot in a tool name, and `storableTools` used to refuse the whole
   * listing over one. A custom server with a single such action then stored nothing on its add and
   * kept whatever it had on every refresh after, frozen, with the one sentence about it the only
   * sign anything had happened.
   */
  test("a dotted MCP tool name is skipped and named, and the rest are stored", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([EVICTED.clientId]);

    await withMockedNotionListing(
      dynamicServerId,
      [
        {
          name: "notion-fetch",
          description: "An ordinary name.",
          inputSchema: { type: "object", properties: {} },
        },
        {
          name: "notion.export",
          description: "A name the MCP spec allows and a model API refuses.",
          inputSchema: { type: "object", properties: {} },
        },
        {
          name: "notion-create-pages",
          description: "Another ordinary name.",
          inputSchema: { type: "object", properties: {} },
        },
      ],
      async () => {
        expect(
          await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
        ).toEqual({ tools: 2 });

        const rows = await database
          .select({ name: mcpTools.name })
          .from(mcpTools)
          .where(eq(mcpTools.serverId, dynamicServerId))
          .orderBy(asc(mcpTools.name));
        expect(rows.map((row) => row.name)).toEqual([
          "notion-create-pages",
          "notion-fetch",
        ]);

        const [server] = await database
          .select({
            lastError: mcpServers.lastError,
            skippedTools: mcpServers.skippedTools,
            toolsRefreshedAt: mcpServers.toolsRefreshedAt,
          })
          .from(mcpServers)
          .where(eq(mcpServers.id, dynamicServerId));
        // Something was learned, so the refresh is stamped and is no failure — and the one thing
        // not learned is said where the administrator who pressed Refresh will read it.
        expect(server?.toolsRefreshedAt).not.toBeNull();
        expect(server?.lastError).toBeNull();
        expect(server?.skippedTools).toEqual(["notion.export"]);

        // And the page's read hands it on.
        const listed = (await dynamicStore.listServers()).find(
          (entry) => entry.id === dynamicServerId,
        );
        expect(listed?.skippedTools).toEqual(["notion.export"]);
      },
    );
  });

  /**
   * The warning is about the last refresh, so a clean one takes it away.
   *
   * CRITERION. After a refresh that skipped a name, a refresh whose listing has no such name leaves
   * `skippedTools` empty, and the page's read hands on an empty list.
   *
   * REASON. The warning is drawn whenever the list is non-empty. A clean refresh that kept the old
   * names would leave the app's page warning about an action the vendor no longer lists, for good.
   */
  test("a clean refresh after one that skipped a name clears the warning", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([EVICTED.clientId]);

    const ordinary = {
      name: "notion-fetch",
      description: "An ordinary name.",
      inputSchema: { type: "object", properties: {} },
    };
    await withMockedNotionListing(
      dynamicServerId,
      [
        ordinary,
        {
          name: "notion.export",
          description: "A name the MCP spec allows and a model API refuses.",
          inputSchema: { type: "object", properties: {} },
        },
      ],
      async () => {
        await dynamicStore.refreshTools(dynamicServerId, dynamicUserId);
      },
    );
    await withMockedNotionListing(dynamicServerId, [ordinary], async () => {
      expect(
        await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
      ).toEqual({ tools: 1 });
    });

    const [server] = await database
      .select({ skippedTools: mcpServers.skippedTools })
      .from(mcpServers)
      .where(eq(mcpServers.id, dynamicServerId));
    expect(server?.skippedTools).toBeNull();
    const listed = (await dynamicStore.listServers()).find(
      (entry) => entry.id === dynamicServerId,
    );
    expect(listed?.skippedTools).toEqual([]);
  });

  /**
   * A listing where NOTHING survives is the empty answer by another route, and is kept like one.
   *
   * CRITERION. Held actions are not deleted when every name the vendor listed was skipped; the
   * skipped names are reported and the held count is returned.
   *
   * REASON. Before skipping, a wholly unofferable listing threw and kept what was held. Skipping
   * without this would turn that into a replace with nothing — the same deletion the empty-listing
   * guard exists to prevent, arriving through a vendor that renamed everything.
   */
  test("a listing whose every name is skipped keeps the actions already held", async () => {
    await putClient(EVICTED);
    await connect();
    accepted = new Set([EVICTED.clientId]);

    await withMockedNotionListing(
      dynamicServerId,
      [
        {
          name: "notion.fetch",
          description: "Renamed, and unofferable as renamed.",
          inputSchema: { type: "object", properties: {} },
        },
      ],
      async () => {
        await database
          .delete(mcpTools)
          .where(eq(mcpTools.serverId, dynamicServerId));
        await database.insert(mcpTools).values({
          serverId: dynamicServerId,
          name: "notion-fetch",
          vendorName: "notion-fetch",
          description: "Held from an earlier listing.",
        });

        expect(
          await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
        ).toEqual({ tools: 1 });

        const rows = await database
          .select({ name: mcpTools.name })
          .from(mcpTools)
          .where(eq(mcpTools.serverId, dynamicServerId));
        expect(rows.map((row) => row.name)).toEqual(["notion-fetch"]);

        const [server] = await database
          .select({ lastError: mcpServers.lastError })
          .from(mcpServers)
          .where(eq(mcpServers.id, dynamicServerId));
        expect(server?.lastError).toContain('"notion.fetch"');
        expect(server?.lastError).toContain("kept");
      },
    );
  });

  /**
   * What a failed refresh writes into `lastError`, and how much of it.
   *
   * The column is drawn on the admin page and parts of the sentence come from a vendor, so it is not
   * a promise about length — the same reasoning `callTool` already applies to the failure it records.
   * Capped at the same 400 characters, so the two agree.
   */
  test("a refusal written to lastError is capped like every other vendor sentence", async () => {
    await putClient(EVICTED);
    await connect();
    // A refusal the retry cannot act on — no code at all — so it arrives unedited and long.
    accepted = new Set<string>();
    refuse = () => new Error(`vendor said: ${"y".repeat(1_000)}`);

    const [before] = await database
      .select({ lastError: mcpServers.lastError })
      .from(mcpServers)
      .where(eq(mcpServers.id, dynamicServerId));

    try {
      // Zero tools and no throw: a refresh records its failure rather than raising it.
      expect(
        await dynamicStore.refreshTools(dynamicServerId, dynamicUserId),
      ).toEqual({ tools: 0 });

      const [row] = await database
        .select({ lastError: mcpServers.lastError })
        .from(mcpServers)
        .where(eq(mcpServers.id, dynamicServerId));
      expect(row?.lastError?.length).toBe(400);
      expect(row?.lastError?.startsWith("vendor said: ")).toBe(true);
    } finally {
      // The column is live configuration an operator reads, so this suite puts back what it found.
      await database
        .update(mcpServers)
        .set({ lastError: before?.lastError ?? null })
        .where(eq(mcpServers.id, dynamicServerId));
    }
  });

  /**
   * A stored client that parses cleanly and is not a client.
   *
   * The sibling of the unparseable row, and its worse half. Guarding the parse answers for SYNTAX
   * only, and the `as OAuthClient` cast behind it answers for nothing — so a row holding
   * snake_case keys, which is what a hand-repair or a half-written row leaves, yields a client
   * whose `clientId` is `undefined` and is handed on as usable.
   *
   * WHAT MAKES IT WORSE THAN A SYNTAX ERROR is where it ends. The unparseable row is refused before
   * the transaction; this one is not refused at all, so the `undefined` id goes to the vendor, the
   * vendor answers `invalid_client`, and {@link refuseAndReplaceEvictedClient} reads that as the
   * vendor having disowned this deployment's registration. A corrupt LOCAL row then buys a
   * DEPLOYMENT-WIDE remedy: the client every existing consent was granted against is replaced, and
   * the operator is told the vendor forgot us rather than which credential actually broke.
   */
  describe("a stored OAuth client whose shape is not a client's", () => {
    /** Snake_case where the type is camelCase, with a secret distinctive enough to search for. */
    const MISSHAPEN = JSON.stringify({
      client_id: "dyn-snake",
      client_secret: `shh_notAClient_${suite}`,
    });
    /** What the operator must be told instead: the credential named, and nothing else claimed. */
    const UNUSABLE =
      "Notion needs connecting again. Reconnect it on Connections and ask again.";

    /**
     * Plant arbitrary stored bytes as this server's client, the way {@link putClient} plants a real
     * one — aged an hour, so the re-registration window is not what refuses the call. A row younger
     * than the window would pass these tests for the wrong reason.
     */
    async function putStoredBytes(plaintext: string) {
      await database
        .update(credentials)
        .set({ revokedAt: new Date(), updatedAt: new Date() })
        .where(
          and(
            eq(credentials.kind, "mcp_oauth_client"),
            eq(credentials.provider, dynamicServerId),
            eq(credentials.keyId, `oauth-client-${dynamicServerId}`),
            sql`${credentials.revokedAt} IS NULL`,
          ),
        );
      const [row] = await database
        .insert(credentials)
        .values({
          kind: "mcp_oauth_client",
          provider: dynamicServerId,
          keyId: `oauth-client-${dynamicServerId}`,
          metadata: {},
          encryptedValue: await encryptSecret(DYNAMIC_KEY, plaintext),
          createdAt: new Date(Date.now() - 60 * 60 * 1000),
        })
        .returning({ id: credentials.id });
      if (!row) throw new Error("misshapen client was not stored");
      clientFixture.track(row.id);
      await database
        .update(mcpServers)
        .set({ credentialId: row.id })
        .where(eq(mcpServers.id, dynamicServerId));
      return row.id;
    }

    /**
     * This tool's failure rows with their ids, so one call's can be told from the suite's.
     *
     * Every test in this describe calls the SAME tool, and the ones above this deliberately produce
     * the eviction sentence — so an assertion that no failure row anywhere mentions it would be
     * about its siblings rather than about this call. The ids are what separate them; there is no
     * ordering finer than the millisecond these rows are written in.
     */
    async function failureRows() {
      return database
        .select({ id: auditEvents.id, payload: auditEvents.payload })
        .from(auditEvents)
        .where(
          and(
            eq(auditEvents.eventType, "mcp.call_failed"),
            eq(auditEvents.targetType, "mcp_tool"),
            eq(auditEvents.targetId, dynamicRef),
          ),
        );
    }

    /** Which credential the server row names, which is the thing a re-registration replaces. */
    async function pointedAt() {
      const [row] = await database
        .select({ credentialId: mcpServers.credentialId })
        .from(mcpServers)
        .where(eq(mcpServers.id, dynamicServerId));
      return row?.credentialId ?? null;
    }

    test("a call is refused, and the deployment's client is not replaced", async () => {
      const planted = await putStoredBytes(MISSHAPEN);
      await connect();
      const registeredBefore = await registeredRows();
      // The vendor would honour a fresh client, so registering is available here and would look
      // like a recovery. The point is that it is never reached: there is nothing in this row for a
      // vendor to refuse, so there is nothing to read as an eviction.
      accepted = new Set([FRESH.clientId]);
      issue = () => FRESH;

      await expect(call()).rejects.toThrow(UNUSABLE);

      // Refused before the exchange, so the vendor is never offered an `undefined` client id and
      // never gets to answer `invalid_client` about it.
      expect(offered).toEqual([]);
      // And so the destructive remedy never runs. These are the property: a corrupt local row costs
      // this one call, not every consent in the deployment.
      expect(registrations).toEqual([]);
      expect(await pointedAt()).toBe(planted);
      expect((await registeredRows()).length).toBe(registeredBefore.length);
    });

    test("the refusal names the credential rather than carrying it", async () => {
      await putStoredBytes(MISSHAPEN);
      await connect();
      accepted = new Set([FRESH.clientId]);
      issue = () => FRESH;

      const before = new Set((await failureRows()).map((row) => row.id));
      const refusal = await call().then(
        () => null,
        (error: unknown) => error,
      );
      const written = JSON.stringify(
        (await failureRows()).filter((row) => !before.has(row.id)),
      );
      // The same absence the unparseable row is held to: a misshapen value is still the decrypted
      // client, and half of this one IS a client secret.
      expect(written).not.toContain(`shh_notAClient_${suite}`);
      // Never the eviction sentence either. It would claim a re-registration that did not happen
      // and point the operator at the vendor instead of at the row.
      expect(written).not.toContain("no longer recognises");
      expect(written).toContain(UNUSABLE);
      expect(refusal).toBeInstanceOf(PluginRefusedError);
    });

    /**
     * The readers answer none, which is their existing contract for a value they cannot read.
     *
     * `ensureOAuthClient` consults the stored client first and then again under the lock, so both
     * reads are on this path. Unguarded, the first hands back the misshapen object and a consent
     * URL is built with an `undefined` client id — the person reaches a vendor screen for a client
     * that does not exist. None is the answer that instead gets them a client that works.
     */
    test("the consent flow reads it as none and obtains one that works", async () => {
      await putStoredBytes(MISSHAPEN);
      issue = () => FRESH;

      expect(await dynamicStore.oauthClientFor(dynamicServerId)).toBeNull();
      expect(
        await dynamicStore.ensureOAuthClient(
          dynamicServerId,
          "[email protected]",
        ),
      ).toEqual(FRESH);
    });
  });

  /**
   * The vault row and the pointer that names it commit together, or neither does.
   *
   * They were two transactions, so a failure between them left `mcp_user_credentials` naming a
   * credential that had just been revoked — a connection that reads as live on the settings page and
   * refuses every call. The pointer write is the one that can fail on its own: `user_id` is a real
   * foreign key, so a person who is no longer in `users` is a genuine 23503 at exactly that
   * statement, which is the injection this test uses rather than a spy.
   */
  test("a pointer write that fails leaves no live grant behind", async () => {
    const ghost = `user_ghost_${suite}`;

    await expect(
      dynamicStore.recordConnection({
        serverId: dynamicServerId,
        userId: ghost,
        refreshToken: "rt-ghost",
        scope: SCOPE,
      }),
    ).rejects.toThrow();

    // Nothing in the vault, live or otherwise: the insert that minted it was rolled back with the
    // pointer write that failed. Asked of the key, because that is what a later connect collides on.
    const rows = await database
      .select({ id: credentials.id })
      .from(credentials)
      .where(
        and(
          eq(credentials.kind, "mcp_user_token"),
          eq(credentials.provider, dynamicServerId),
          eq(credentials.keyId, ghost),
        ),
      );
    expect(rows).toEqual([]);
  });
});

/**
 * A custom server may not take a name the app directory already answers to.
 *
 * `/admin/plugins/composio` is a static route and `/admin/plugins/$key` is the one every server is
 * opened through, and a static route wins. So a server whose id is literally `composio` would be
 * listed, saved, refreshed and then never openable: the row for it would send the operator to the
 * Composio screen instead. Brokered ids are `composio-<slug>`, so this is only reachable by typing
 * the id into the custom-server form, which the id pattern otherwise allows.
 */
describe("a custom server may not be named after one of the app's own screens", () => {
  test("the id composio is refused, and no server is written", async () => {
    await expect(
      store.addCustomServer({
        id: "composio",
        title: "Collector",
        url: "https://collector.example/mcp",
        by: "[email protected]",
      }),
    ).rejects.toBeInstanceOf(CustomServerRefusedError);

    // Written-and-unopenable is the whole harm, so the refusal has to stop the write rather than
    // report on it afterwards.
    const rows = await database
      .select({ id: mcpServers.id })
      .from(mcpServers)
      .where(eq(mcpServers.id, "composio"));
    expect(rows).toHaveLength(0);
  });
});

/**
 * Which credential a custom server is allowed to be pointed at.
 *
 * `addCustomServer` takes the pointer from the request body, and the add itself dereferences it: the
 * refresh that follows decrypts whatever it names and sends it to the URL from the same request. So
 * the pointer is the whole control. An administrator naming somebody's `mcp_user_token` was enough
 * to have that person's decrypted token delivered to an address the administrator chose, before any
 * grant, policy check or Bot existed.
 *
 * `POST /api/admin/credentials` already refuses to *mint* a `mcp_user_token` by hand, and says why:
 * it would be "creating a credential attributed to a person who never agreed to it". Pointing at one
 * spends that credential on the same person's behalf, which is the same objection.
 */
describe("a custom server may only be pointed at its own kind of credential", () => {
  const suffix = randomUUID().slice(0, 8);
  const deploymentCredentialId = randomUUID();
  const personalCredentialId = randomUUID();
  const oauthClientCredentialId = randomUUID();
  /**
   * The upsert case gets its own token, because a credential names the server it was minted for and
   * that case adds a second server id. Sharing one row across two ids is a shape `storeMcpToken`
   * cannot produce: it sets the provider to the server it is minting for, every time.
   */
  const upsertCredentialId = randomUUID();
  const customServerId = `custom-cred-${suffix}`;
  const attemptedServerIds = new Set<string>();

  function addCustomFixture(
    input: Parameters<typeof store.addCustomServer>[0],
  ) {
    // Refusal tests may fail because the write succeeded. Track the attempt before calling it.
    attemptedServerIds.add(input.id);
    return store.addCustomServer(input);
  }

  beforeAll(async () => {
    const encrypted = await encryptSecret(
      `${"A".repeat(43)}=`,
      "not-read-here",
    );
    await database.insert(credentialRows).values([
      {
        id: deploymentCredentialId,
        kind: "mcp",
        provider: customServerId,
        keyId: customServerId,
        encryptedValue: encrypted,
        metadata: {},
      },
      {
        id: personalCredentialId,
        kind: "mcp_user_token",
        provider: "google-drive",
        // For a user token the key is the person, which is what makes one pickable by name from the
        // administrator's own credential list.
        keyId: `user_someone_else_${suffix}`,
        encryptedValue: encrypted,
        metadata: {},
      },
      {
        id: upsertCredentialId,
        kind: "mcp",
        provider: `${customServerId}-upsert`,
        keyId: `${customServerId}-upsert`,
        encryptedValue: encrypted,
        metadata: {},
      },
      {
        id: oauthClientCredentialId,
        kind: "mcp_oauth_client",
        provider: "google-drive",
        keyId: "google-drive",
        encryptedValue: encrypted,
        metadata: {},
      },
    ]);
  });

  afterAll(async () => {
    if (attemptedServerIds.size > 0) {
      await database
        .delete(mcpServers)
        .where(inArray(mcpServers.id, [...attemptedServerIds]));
    }
    await database
      .delete(credentialRows)
      .where(
        inArray(credentialRows.id, [
          deploymentCredentialId,
          personalCredentialId,
          upsertCredentialId,
          oauthClientCredentialId,
        ]),
      );
  });

  test("somebody else's connector token is refused, and no server is written", async () => {
    const id = `${customServerId}-personal`;
    await expect(
      addCustomFixture({
        id,
        title: "Collector",
        url: "https://collector.example/mcp",
        credentialId: personalCredentialId,
        by: "[email protected]",
      }),
    ).rejects.toBeInstanceOf(CustomServerRefusedError);

    // The refusal has to stop the write, not merely report on it: a row here is a pointer the next
    // refresh would dereference.
    const rows = await database
      .select({ id: mcpServers.id })
      .from(mcpServers)
      .where(eq(mcpServers.id, id));
    expect(rows).toHaveLength(0);
  });

  test("the deployment's OAuth client is refused too", async () => {
    // Not a per-person secret, but not this server's token either, and handing a vendor its own
    // client secret as a bearer token is the mistake `refreshTools` was already changed to avoid.
    const id = `${customServerId}-client`;
    await expect(
      addCustomFixture({
        id,
        title: "Collector",
        url: "https://collector.example/mcp",
        credentialId: oauthClientCredentialId,
        by: "[email protected]",
      }),
    ).rejects.toBeInstanceOf(CustomServerRefusedError);
  });

  test("a credential that does not exist is refused the same way", async () => {
    // Same message as the wrong-kind refusal on purpose. A caller who can tell "wrong kind" from
    // "no such row" can ask this endpoint which ids are real, which is a vault oracle.
    const id = `${customServerId}-missing`;
    const missing = addCustomFixture({
      id,
      title: "Collector",
      url: "https://collector.example/mcp",
      credentialId: randomUUID(),
      by: "[email protected]",
    });
    await expect(missing).rejects.toBeInstanceOf(CustomServerRefusedError);

    const wrongKind = addCustomFixture({
      id: `${customServerId}-kind-message`,
      title: "Collector",
      url: "https://collector.example/mcp",
      credentialId: personalCredentialId,
      by: "[email protected]",
    }).catch((error: Error) => error.message);
    const missingMessage = await missing.catch((error: Error) => error.message);
    expect(await wrongKind).toBe(missingMessage);
  });

  test("the server's own token still works", async () => {
    // The case that must keep passing, so the refusal above is a rule and not a wall. The URL is
    // unreachable and that is fine: a failed refresh is recorded on the row rather than thrown.
    const added = await addCustomFixture({
      id: customServerId,
      title: "Collector",
      url: "https://collector.example/mcp",
      credentialId: deploymentCredentialId,
      by: "[email protected]",
    });
    expect(added.id).toBe(customServerId);

    const [row] = await database
      .select({ credentialId: mcpServers.credentialId })
      .from(mcpServers)
      .where(eq(mcpServers.id, customServerId));
    expect(row?.credentialId).toBe(deploymentCredentialId);
  });

  test("a credential id that is not an id is refused, not a database error", async () => {
    // `credentials.id` is a uuid column, so an unshaped value makes the lookup itself fail. The
    // route passes the body field through untouched, so this is reachable with one curl.
    for (const notAnId of ["not-a-uuid", "' OR 1=1 --"]) {
      await expect(
        addCustomFixture({
          id: `${customServerId}-shape`,
          title: "Collector",
          url: "https://collector.example/mcp",
          credentialId: notAnId,
          by: "[email protected]",
        }),
      ).rejects.toBeInstanceOf(CustomServerRefusedError);
    }
  });

  test("an empty credential id reads as no credential", async () => {
    // Not the same as a wrong one. An empty string used to reach the insert and break the foreign
    // key; the honest reading is that the administrator named nothing.
    const id = `${customServerId}-empty`;
    const added = await addCustomFixture({
      id,
      title: "Collector",
      url: "https://collector.example/mcp",
      credentialId: "",
      by: "[email protected]",
    });
    expect(added.id).toBe(id);

    const [row] = await database
      .select({ credentialId: mcpServers.credentialId })
      .from(mcpServers)
      .where(eq(mcpServers.id, id));
    expect(row?.credentialId).toBeNull();
  });

  test("re-adding an existing server cannot repoint it at a refused credential", async () => {
    // The add is an upsert, so the dangerous shape is not only a new server: an existing one that
    // already holds its own token can be re-added naming somebody else's. The guard has to run
    // before the write, and the pointer already on the row has to survive the refusal.
    const id = `${customServerId}-upsert`;
    await addCustomFixture({
      id,
      title: "Collector",
      url: "https://collector.example/mcp",
      credentialId: upsertCredentialId,
      by: "[email protected]",
    });

    await expect(
      addCustomFixture({
        id,
        title: "Collector",
        url: "https://collector.example/mcp",
        credentialId: personalCredentialId,
        by: "[email protected]",
      }),
    ).rejects.toBeInstanceOf(CustomServerRefusedError);

    const [row] = await database
      .select({ credentialId: mcpServers.credentialId })
      .from(mcpServers)
      .where(eq(mcpServers.id, id));
    expect(row?.credentialId).toBe(upsertCredentialId);
  });

  test("a custom server with no credential at all still works", async () => {
    const id = `${customServerId}-none`;
    const added = await addCustomFixture({
      id,
      title: "Collector",
      url: "https://collector.example/mcp",
      by: "[email protected]",
    });
    expect(added.id).toBe(id);
  });
});

/**
 * Which advertised names a vendor's write list does not cover, as a rule on its own.
 *
 * Unit-tested here as well as through a refresh, because the rule is the part that decides whether
 * anybody ever hears about an under-inclusive write list, and it has two branches a live listing
 * cannot show side by side: a vendor whose consent screen is the whole barrier, and one whose own
 * scope is read-only. The entries are the real ones, so a catalogue edit that removed Drive's
 * read-only scope would fail here rather than start filing rows about Drive.
 */
describe("advertised tools a write list does not name", () => {
  test("a Notion tool absent from the write list is named, sorted", () => {
    expect(
      unlistedAdvertisedTools(catalogueEntry("notion"), [
        "notion-search",
        "notion-create-pages",
        "notion-fetch",
      ]),
    ).toEqual(["notion-fetch", "notion-search"]);
  });

  test("a write the list already names is not", () => {
    expect(
      unlistedAdvertisedTools(catalogueEntry("notion"), [
        "notion-create-pages",
      ]),
    ).toEqual([]);
  });

  /*
   * Drive's grant is `drive.readonly`, so a tool missing from its write list cannot write whatever
   * this deployment believes about it — the vendor refuses. Filing rows about it would be noise
   * standing between somebody and the vendor where it is the only barrier.
   */
  test("a vendor whose own scope is read-only is not reconciled here", () => {
    expect(
      unlistedAdvertisedTools(catalogueEntry("google-drive"), [
        "search_files",
        "made_up_tool",
      ]),
    ).toEqual([]);
  });

  /** A server an administrator added by URL: every tool of theirs is already a write. */
  test("a server nobody reviewed is not reconciled here either", () => {
    expect(unlistedAdvertisedTools(null, ["anything"])).toEqual([]);
  });
});

/**
 * What the real token endpoint said, read by the real exchange.
 *
 * Every other suite in this file injects `exchangeRefreshToken`, because what they are about is which
 * credential a call goes out with rather than how a reply is parsed. That leaves the parsing itself —
 * the one part that meets a vendor's actual bytes — with nothing exercising it, and the interesting
 * bytes are the dishonest ones: a 200 carrying a CDN interstitial rather than a token.
 */
describe("a vendor reply that is not a token", () => {
  const replyClient: OAuthClient = { clientId: "c-1", clientSecret: "" };

  test("a 200 that is not JSON is a refusal, not a thrown parse error", async () => {
    const realFetch = globalThis.fetch;
    globalThis.fetch = (async () =>
      new Response("<html>checking your browser</html>", {
        status: 200,
        headers: { "content-type": "text/html" },
      })) as unknown as typeof fetch;
    try {
      /*
       * The refusal this module already knows how to carry, rather than a SyntaxError.
       *
       * An unguarded parse throws out of here into `callTool`, which records it as `mcp.call_failed`
       * with the parser's message — and that message quotes the vendor's body, so an interstitial's
       * HTML ends up in an audit payload and in front of the person who asked.
       */
      await expect(
        exchangeRefreshTokenOverHttp({
          tokenUrl: "https://vendor.example/token",
          client: replyClient,
          refreshToken: "rt-1",
        }),
      ).rejects.toThrow(
        "The vendor answered this renewal with something other than a token.",
      );
    } finally {
      globalThis.fetch = realFetch;
    }
  });

  test("a 200 with JSON and no access token is still the refusal it always was", async () => {
    const realFetch = globalThis.fetch;
    globalThis.fetch = (async () =>
      new Response(JSON.stringify({ token_type: "bearer" }), {
        status: 200,
        headers: { "content-type": "application/json" },
      })) as unknown as typeof fetch;
    try {
      await expect(
        exchangeRefreshTokenOverHttp({
          tokenUrl: "https://vendor.example/token",
          client: replyClient,
          refreshToken: "rt-1",
        }),
      ).rejects.toThrow("The vendor renewed this access with no token.");
    } finally {
      globalThis.fetch = realFetch;
    }
  });

  /** The error branch, which already read defensively: the status survives an unparseable body. */
  test("a refusal that is not JSON keeps the status, which is the one fact there is", async () => {
    const realFetch = globalThis.fetch;
    globalThis.fetch = (async () =>
      new Response("<html>502</html>", {
        status: 502,
        headers: { "content-type": "text/html" },
      })) as unknown as typeof fetch;
    try {
      await expect(
        exchangeRefreshTokenOverHttp({
          tokenUrl: "https://vendor.example/token",
          client: replyClient,
          refreshToken: "rt-1",
        }),
      ).rejects.toThrow("The vendor would not renew this access (502).");
    } finally {
      globalThis.fetch = realFetch;
    }
  });
});

/**
 * What a brokered app needs before any of it can be asserted: a clean slate and a fixture.
 *
 * The suites above each own a suite-scoped id, because they run against a database somebody may be
 * using. These fixtures cannot: a Composio app IS its toolkit slug — `gmail` is both the row's id and
 * the name sent to Composio — so the rows have to be spelled the way production spells them, and
 * `bot_helper` and `user_asker` name them in every assertion.
 *
 * What replaces the suffix is the guard at the top of this file, not the ordering below. The deletes
 * here would be indefensible on their own — a real `notion` row cascades into every person's per-user
 * credentials, a real Bot into the six tables behind it, a real person into the ten behind them. They
 * are safe only because the guard has established that no row at any of these ids exists, which makes
 * every row they remove one of this file's own, and the first thing below is the check that it did.
 * Cleaning before each test rather than after is then just so a run that dies halfway leaves the next
 * one nothing to trip over; the `afterAll` below is what stops the last test's fixtures from outliving
 * the run.
 */
async function freshDatabase(): Promise<Database> {
  /*
   * The guard's answer, asked again rather than assumed.
   *
   * "Nothing gets this far unless the guard has established the ids are free" was the whole
   * justification for the deletes below, and it was an assumption about the runner: a `beforeAll`
   * that throws is supposed to stop every test under it. The rest of this file already declines to
   * rely on that — `afterAll` is documented as running anyway, which is why {@link ownsFixtureIds}
   * exists at all — and a delete cascading through a real person is not a thing to leave resting on
   * the difference. So the same positive evidence the teardown waits for authorises these too, and
   * a run that never got it fails loudly here instead of quietly emptying rows.
   */
  if (!ownsFixtureIds) {
    throw new Error(
      "the ownership guard has not cleared this run to own 'gmail', 'notion', 'bot_helper', " +
        "'user_asker' and 'user_leaver', so nothing may be deleted at those ids",
    );
  }
  /*
   * The Bot's own grants, never a delete by ref.
   *
   * The primary key is (kind, ref, agent_id), and `gmail/GMAIL_FETCH_EMAILS` is a real action of a
   * real app: a delete by ref alone would take an administrator's grant for a Bot people use. This
   * file has already done that once — the `afterAll` near the top of it says what that cost.
   */
  await database
    .delete(pluginGrants)
    .where(eq(pluginGrants.agentId, "bot_helper"));
  await database.delete(agents).where(eq(agents.id, "bot_helper"));
  // The actions before the servers. `mcp_tools` cascades on the server row anyway, so this is what
  // clears actions a previous run left against a server row it is not what created.
  await database
    .delete(mcpTools)
    .where(inArray(mcpTools.serverId, ["gmail", "notion"]));
  await database
    .delete(mcpServers)
    .where(inArray(mcpServers.id, ["gmail", "notion"]));
  /*
   * Brokered connections, by the pair and never by half of it.
   *
   * NEITHER HALF ALONE. By toolkit it would take every person's Gmail connection, leaving one
   * orphaned at the broker with no local row to find it by — the table has no foreign key to
   * `users`, which is the property the first test below is about, so nothing else would ever
   * remove it. By person it would take a `("slack", "user_asker")` row belonging to somebody else,
   * for the same reason and at the same cost. {@link ownedConnections} is what the guard at the
   * top of this file has already established nothing else holds.
   *
   * The anonymous pair is swept here as well as in the `finally` of the test that inserts it,
   * because that `finally` covers a failed assertion and not a killed process — and the row it
   * would leave is what the guard refuses on. A pair stranded earlier in this run is therefore
   * gone before the next test looks; a pair that was already there when the run started is still
   * the guard's to refuse, because at that point nothing has established it is ours.
   */
  await database.delete(brokeredConnections).where(ownedConnections());
  // The person the connection outlives, who is a row in `users` like anybody else. Reached only
  // through the check at the top of this function, because there is no suffix on this id to tell a
  // fixture apart from somebody's account and ten cascades sit behind the difference.
  await database.delete(users).where(eq(users.id, "user_leaver"));
  return database;
}

/**
 * A store over the clean database, recording every event it writes.
 *
 * `recorded()` alongside the real insert rather than instead of it: the payload is what these tests
 * assert about, and reading it back out of `audit_events` would assert what the column round-trips
 * rather than what the store said. The row is still written, because a store whose audit insert
 * never touched the database would not be exercising the one it has.
 *
 * NO `callVendor`. Whose account a call runs as and which transport a row resolves to are the
 * properties under test, and both are decided on the way to the vendor — so the real path has to
 * run, and the vendor is stubbed further out at {@link useComposioClient}.
 *
 * `options` is spread over the defaults rather than read field by field, so a test that needs one
 * more seam — a broker, today — adds it at the call and nothing here has to learn its name.
 */
async function freshStore(options: { broker?: ComposioBroker } = {}) {
  const database = await freshDatabase();
  const persisting = createAuditStore(database);
  const events: Parameters<typeof persisting.insert>[0][] = [];
  const auditStore = {
    insert: async (event: Parameters<typeof persisting.insert>[0]) => {
      events.push(event);
      await persisting.insert(event);
    },
    recorded: () => events,
  };

  const store = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore,
    credentials: credentialsStub,
    encryptionKey: "x".repeat(44),
    policy: () => policy,
    ...options,
  });

  return { store, database, auditStore };
}

/**
 * A Composio Gmail app, one granted read action, one Bot, and optionally a connected person.
 *
 * `version: null` is the action Composio listed without one — a granted, callable row whose version
 * column is null, which is a state the vendor's own optional field produces rather than a leftover
 * from before the column existed.
 *
 * `url` is an option because the id and the url are two fields and nothing holds them equal: a row
 * called `gmail` at `composio://slack` is the shape that used to pass the connection gate on one
 * spelling and run against the other. The connected person is still connected to `gmail`.
 *
 * `authScheme` is the vendor's own scheme literal, as it was recorded when somebody enabled the app,
 * and the call gate reads it to decide whether a connection row is required at all. Absent by
 * default, which is what every other test here wants: a row that is not `NO_AUTH` is a row the gate
 * still asks a connection for.
 *
 * `accountMode` defaults to `"personal"`, which is what `addBrokeredApp` itself records for any app
 * enabled with a real scheme — the one every test below was written against, back when the column
 * did not exist and every brokered call ran as the asker's own account unconditionally. Left null,
 * an app whose scheme is not `NO_AUTH` reads as `accountFor`'s ambiguous case instead: this
 * deployment does not yet know whether to call it as a person or as itself, and refuses rather than
 * guessing. Overridable for the one test that reads the column back as the row actually holds it.
 */
async function seedComposioGmail(
  database: Database,
  store: PluginStore,
  options: {
    connect?: boolean;
    version?: string | null;
    url?: string;
    authScheme?: string;
    accountMode?: "personal" | "shared" | null;
  } = {},
) {
  await database.insert(mcpServers).values({
    id: "gmail",
    title: "Gmail",
    vendor: "Composio",
    url: options.url ?? "composio://gmail",
    provenance: "composio",
    authScheme: options.authScheme ?? null,
    accountMode:
      options.accountMode === undefined ? "personal" : options.accountMode,
  });
  await database.insert(mcpTools).values({
    serverId: "gmail",
    name: "GMAIL_FETCH_EMAILS",
    vendorName: "GMAIL_FETCH_EMAILS",
    description: "Fetch emails.",
    effect: "read",
    version: options.version === undefined ? "20260903_00" : options.version,
  });
  await database.insert(agents).values({
    id: "bot_helper",
    name: "Helper",
    type: "built_in",
    configuration: {},
  });
  if (options.connect !== false) {
    await database.insert(brokeredConnections).values({
      provider: "composio",
      app: "gmail",
      holder: "person",
      userId: "user_asker",
      vendorUserId: "user_asker",
    });
  }
  await store.grant(
    "mcp",
    "gmail/GMAIL_FETCH_EMAILS",
    "bot_helper",
    "[email protected]",
  );
}

/**
 * What Composio answers a call that worked, in the shape its own schema requires.
 *
 * `ToolExecuteResponseSchema` in `@composio/core` 0.18.1 spells `data`, `error` and `successful`
 * REQUIRED. Every stub below used to answer `{}` or `{ messages: [] }`, which are shapes the vendor
 * cannot produce, and nothing flagged it: `server/tsconfig.json` excludes `tests`, so no typecheck
 * reads these files at all. They stayed green for a reason that is not the property under test —
 * an ABSENT `successful` is not `successful === false`, so the transport's failure branch was
 * simply never entered. A stub that can only answer things the vendor could actually say is what
 * makes the success path's greenness mean something.
 *
 * Typed as {@link ComposioResult} rather than left to inference, so a vendor shape that drifts is a
 * red squiggle here even though the suite is outside the typecheck's reach.
 */
const vendorAnswered = (
  data: Record<string, unknown> = {},
): ComposioResult => ({
  data,
  error: null,
  successful: true,
});

/**
 * What Composio answers when it ran nothing and says why, which is a 200 and not a throw.
 *
 * `successful: false` beside a sentence is the vendor reporting its own failure inside the
 * envelope, which is the case that used to come back from this transport as `isError: false`.
 */
const vendorRefused = (sentence: string): ComposioResult => ({
  data: {},
  error: sentence,
  successful: false,
});

// The vendor is a process-wide registry, so a stub outliving its test would be answering somebody
// else's calls.
afterEach(() => useComposioClient(null));

/*
 * The last test's fixtures, which nothing else would remove.
 *
 * {@link freshDatabase} cleans BEFORE each test, so without this the final test's rows are
 * permanent: a `notion` server row and a `notion-fetch` action nobody configured, which makes
 * whatever database this ran against advertise a connector nobody set up. Worse on the next run —
 * the rotation and dynamic-registration suites above read the leak as a row they did not create,
 * correctly decline to clean what looks like the deployment's own, and leave this delete as the only
 * thing that removes it.
 *
 * Exactly what this file created, and only when the guard cleared the run to own these ids.
 */
afterAll(async () => {
  if (!ownsFixtureIds) return;
  await database
    .delete(mcpTools)
    .where(inArray(mcpTools.serverId, ["gmail", "notion"]));
  await database
    .delete(mcpServers)
    .where(inArray(mcpServers.id, ["gmail", "notion"]));
  await database.delete(brokeredConnections).where(ownedConnections());
  /*
   * And the witness row, which is at neither `gmail` nor any person.
   *
   * CRITERION. Nothing at `sweep_witness_${suite}` outlives this run.
   *
   * REASON. It is removed in its own test's `finally`, which a killed process does not run — and
   * nothing else would reach it: `ownedConnections` names `gmail` and `linear`, and the anonymous
   * actor is precisely what `retireConnectionsFor` refuses to act on, so no operation in the
   * product could clear it either. Named exactly rather than by prefix, because another run's
   * witness is that run's to take back.
   */
  await database
    .delete(brokeredConnections)
    .where(eq(brokeredConnections.app, `sweep_witness_${suite}`));
  await database.delete(agents).where(eq(agents.id, "bot_helper"));
  await database.delete(users).where(eq(users.id, "user_leaver"));
});

test("a Composio connection row survives the person being deleted", async () => {
  const database = await freshDatabase();

  await database
    .insert(users)
    .values({ id: "user_leaver", email: "[email protected]", name: "Leaver" });
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: "gmail",
    holder: "person",
    userId: "user_leaver",
    vendorUserId: "user_leaver",
  });

  await database.delete(users).where(eq(users.id, "user_leaver"));

  /*
   * Asked at the app this test connected, not at every app this person might hold.
   *
   * The guard at the top of this file is keyed on the pair, so a `("slack", "user_leaver")` row
   * belonging to somebody else is deliberately allowed to exist — and asking by person alone would
   * then read it into this assertion and fail over a row that has nothing to do with the property
   * under test.
   */
  const rows = await database
    .select({ toolkit: brokeredConnections.app })
    .from(brokeredConnections)
    .where(
      and(
        eq(brokeredConnections.app, "gmail"),
        eq(brokeredConnections.userId, "user_leaver"),
      ),
    );

  // The whole reason this table exists rather than reusing mcp_user_credentials: offboarding has to
  // still find the connection and revoke it at Composio after the person is gone, and there is no
  // vault row to find it by, because Composio holds the account.
  expect(rows).toEqual([{ toolkit: "gmail" }]);
});

test("a Composio app is listed through the Composio transport, not dialled as MCP", async () => {
  const { store, database } = await freshStore();
  const asked: string[] = [];
  useComposioClient({
    listActions: async (toolkit) => {
      asked.push(toolkit);
      return [];
    },
    execute: async () => vendorAnswered(),
  });
  await database.insert(mcpServers).values({
    id: "gmail",
    title: "Gmail",
    vendor: "Composio",
    url: "composio://gmail",
    provenance: "composio",
  });

  await store.refreshTools("gmail", "admin_user");

  // The transport comes from the resolved kind, not from the absent entry. Derived from the entry,
  // this reached the MCP module instead and dialled `composio://gmail` as an HTTP server — which
  // `refreshTools` swallows into `lastError`, so nothing but this reaches the vendor stub.
  expect(asked).toEqual(["gmail"]);
});

test("a Composio call with nobody attributed is refused before it reaches the vendor", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store);

  // The empty string is what the actor resolves to when nobody could be identified. Reaching the
  // vendor with it would run in whatever account Composio has against "", or in nobody's, and either
  // way the run is unattributable — the state every identity defect in OpenTag started from.
  await expect(
    store.callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "",
    }),
  ).rejects.toThrow(/not attributed to anybody/i);

  expect(reached).toEqual([]);
});

/**
 * The same refusal, with a legal row sitting at the anonymous actor.
 *
 * `composio_connections.user_id` is text notNull with NO foreign key — the property that lets a
 * connection outlive its person, so offboarding can still find it and revoke it at the broker. And
 * `notNull` does not exclude the empty string, so a row at `("gmail", "")` is legal: without the
 * guard ahead of the lookup, that row IS the match, the connection gate passes, and the run goes
 * out in whatever account Composio holds against "". The sibling `user-oauth` path cannot reach
 * this state — `mcp_user_credentials.user_id` carries a foreign key to `users.id` — so its test
 * asserts only the sentence, and borrowing that shape here would leave this property untested.
 *
 * A rejection, not a failed result, and that is the assertion doing the work: the transport repeats
 * the refusal as its own last line, but it answers with `isError` rather than throwing. So a
 * `rejects` here is what separates this gate from its twin downstream of the lookup.
 */
test("a Composio call with nobody attributed is refused even when a connection row exists for the empty actor", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store);
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: "gmail",
    holder: "person",
    userId: "",
    vendorUserId: "",
  });
  /*
   * A second anonymous row, at an app this file has nothing to do with.
   *
   * CRITERION. Whatever removes the row above must leave this one exactly where it is.
   *
   * REASON. The cleanup below used to be `user_id = ''`, which is every app at once. That reached
   * the anonymous row `composio-connections.test.ts` writes against its own run-suffixed app —
   * deleting another file's fixture out from under it when the two run together — and it is the
   * other half of the same confusion the guard at the top of this file suffered from. Suffixed, so
   * this row is provably this run's to insert and to take away again, and so no real deployment
   * row can be what the assertion below is reading.
   */
  const unrelatedApp = `sweep_witness_${suite}`;
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: unrelatedApp,
    holder: "person",
    userId: "",
    vendorUserId: "",
  });

  try {
    await expect(
      store.callTool({
        ref: "gmail/GMAIL_FETCH_EMAILS",
        args: {},
        botId: "bot_helper",
        actorId: "",
      }),
    ).rejects.toThrow(/not attributed to anybody/i);

    expect(reached).toEqual([]);

    // Here rather than only in `freshDatabase`, so the row is gone the moment this test is done
    // with it and the assertion below has something to read. Keyed on the PAIR either way: the app
    // is what makes this row this file's, and the anonymous actor on its own names nobody's.
    await database
      .delete(brokeredConnections)
      .where(
        and(
          eq(brokeredConnections.app, "gmail"),
          eq(brokeredConnections.userId, ""),
        ),
      );

    // What the cleanup took, and what it did not. Asked as two facts about this list rather than
    // as the whole of it, deliberately: a third app's anonymous row is somebody else's business,
    // and a test that failed because one existed would be the same over-reach in assertion form.
    const anonymous = (
      await database
        .select({ toolkit: brokeredConnections.app })
        .from(brokeredConnections)
        .where(eq(brokeredConnections.userId, ""))
    ).map((row) => row.toolkit);
    expect(anonymous).not.toContain("gmail");
    expect(anonymous).toContain(unrelatedApp);
  } finally {
    // Both, so a failed assertion above still leaves the table as this test found it. Each is keyed
    // on an app this run named, which is what makes the deletes this run's to make.
    await database
      .delete(brokeredConnections)
      .where(eq(brokeredConnections.app, unrelatedApp));
    await database
      .delete(brokeredConnections)
      .where(
        and(
          eq(brokeredConnections.app, "gmail"),
          eq(brokeredConnections.userId, ""),
        ),
      );
  }
});

test("a Composio call by somebody who has not connected the app is refused with a sentence they can act on", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store, { connect: false });

  await expect(
    store.callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "user_asker",
    }),
  ).rejects.toThrow(/connect it and ask again/i);

  // Refused here rather than at Composio, so a person is told what to do instead of being shown
  // somebody else's error, and so no call is spent finding out.
  expect(reached).toEqual([]);
});

test("a refusal nobody but the asker can clear carries the app to connect", async () => {
  /*
   * THE CARD IS DRAWN FROM THIS STRING. The transcript turns this refusal into a Connect button
   * (see `app/src/components/channels/connect-app-card.tsx`), and the only thing telling it which
   * app to connect is the prompt inside the sentence. A refusal that stops carrying it degrades
   * silently: the English still reads correctly and the button quietly stops being offered.
   */
  const { store, database } = await freshStore();
  useComposioClient({
    listActions: async () => [],
    execute: async () => vendorAnswered(),
  });
  await seedComposioGmail(database, store, { connect: false });

  const refusal = await store
    .callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "user_asker",
    })
    .then(
      () => null,
      (error: unknown) =>
        error instanceof Error ? error.message : String(error),
    );

  expect(readConnectPrompt(refusal)).toEqual({
    serverId: "gmail",
    title: "Gmail",
    message:
      "You have not connected your Gmail account. Connect it and ask again.",
  });
});

/**
 * One person having connected the app is not the asking person having connected it.
 *
 * THE FAIL-OPEN THIS CLOSES. The gate reads `composio_connections` for `(toolkit, actorId)`, and
 * every test around it seeds a database where the app is connected by the asker or by nobody at
 * all — so dropping `eq(brokeredConnections.userId, actorId)` from that `where`, which turns the
 * question into "has ANYBODY connected Gmail", left the whole suite green. That single term is what
 * keeps one person's mailbox out of another's: with it gone, the first colleague to connect Gmail
 * makes the app callable by everybody, the broker is handed the stranger's id, and Composio answers
 * with whatever account it holds for them — or refuses in words that read as the connector being
 * broken.
 *
 * The stranger is never inserted anywhere. `composio_connections.user_id` is text with no foreign
 * key and the brokered path touches no vault row, so asking as somebody unknown writes nothing this
 * suite would have to clean up — which is the only reason a second person can appear here without
 * a fixture.
 */
test("a Composio call by somebody who has not connected the app is refused even though a colleague has", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  // `user_asker` is connected to Gmail. Nobody else is.
  await seedComposioGmail(database, store);

  await expect(
    store.callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "user_stranger",
    }),
  ).rejects.toThrow(/connect it and ask again/i);

  // Never dialled, which is the half that matters: a call let through here is spent at the broker
  // in a stranger's name, and the person asking sees somebody else's mailbox or somebody else's
  // error.
  expect(reached).toEqual([]);
});

test("a Composio call whose url names no app is refused rather than falling back to the row id", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  // Brokered by provenance, with a url that names no Composio app: `accessFor` answers
  // `{ credential: "brokered", toolkit: null }`, and falling back to the row id would check a
  // Gmail connection and then dial a hostname.
  await seedComposioGmail(database, store, { url: "https://example.com/mcp" });

  await expect(
    store.callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "user_asker",
    }),
  ).rejects.toThrow(/no Composio app in its url/i);

  expect(reached).toEqual([]);
});

test("a Composio call whose row id and url name different apps is refused", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  /*
   * The row is called `gmail` and the person has connected `gmail`; the url dials some OTHER app,
   * which is the one the call would actually run in.
   *
   * SUITE-SCOPED, and that is not cosmetic. Spelled `slack`, this test asserted a refusal on the
   * strength of `("slack", "user_asker")` not existing anywhere in the database — so it depended
   * on this file owning a production person id at every app in the world, and a real deployment
   * row at that pair would have turned the refusal into a completed call and read as this gate
   * being broken. An app nobody can have connected is what the property actually needs.
   */
  await seedComposioGmail(database, store, {
    url: `composio://unconnected_${suite}`,
  });

  await expect(
    store.callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "user_asker",
    }),
  ).rejects.toThrow(/connect it and ask again/i);

  // The gate keys on the app the url names, because that is the app the transport dials. Keyed on
  // the row id, this call completed: it ran a Slack action against a Gmail connection, sent the
  // version recorded for the Gmail action, and was audited as having reached the asker's own
  // account — a person granted one app and dialled into another with nothing noticing.
  expect(reached).toEqual([]);
});

/*
 * WHETHER A BROKERED CALL NEEDS A CONNECTION ROW AT ALL IS THE APP'S OWN QUESTION, AND THESE TWO
 * TESTS ARE ONE PAIR.
 *
 * The fixtures differ in exactly one field — the scheme recorded on the row when somebody enabled
 * the app — and otherwise dial the same app, at the same person, with no connection row anywhere.
 * So the opposite outcomes below cannot be caused by anything but the recorded scheme.
 *
 * SUITE-SCOPED APP, for the reason the test above is suite-scoped: `("unclaimed_<suite>",
 * "user_asker")` is a pair no deployment can be holding, so "nobody has connected this" is a
 * property of the run rather than a hope about the database. Spelled as a real app, a stray
 * connection row somebody else wrote would make the first test pass for the wrong reason and the
 * second one fail for it.
 */
test("a no-auth app runs without anybody having connected it", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store, {
    url: `composio://unclaimed_${suite}`,
    authScheme: "NO_AUTH",
    connect: false,
  });

  const result = await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  expect(result.isError).toBe(false);
  // Dialled, not merely un-refused. A no-auth app has no account to open, so the deployment's own
  // key is the entire credential the call goes out with, and reaching the vendor is what says the
  // gate returned rather than threw.
  expect(reached).toEqual(["GMAIL_FETCH_EMAILS"]);
});

test("an app whose accounts are somebody's still refuses without a row, and names the person's own step", async () => {
  const { store, database } = await freshStore();
  const reached: string[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug }) => {
      reached.push(slug);
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store, {
    url: `composio://unclaimed_${suite}`,
    authScheme: "OAUTH2",
    connect: false,
  });

  await expect(
    store.callTool({
      ref: "gmail/GMAIL_FETCH_EMAILS",
      args: {},
      botId: "bot_helper",
      actorId: "user_asker",
    }),
  ).rejects.toThrow(/connect it and ask again/i);

  // Never dialled. The refusal is local so the person is told their own next step instead of shown
  // the broker's error about an account it cannot find, and no call is spent finding that out.
  expect(reached).toEqual([]);
});

test("a Composio call sends the version recorded for that action", async () => {
  const { store, database } = await freshStore();
  const calls: { slug: string; version: string }[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug, version }) => {
      calls.push({ slug, version });
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store);

  await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  expect(calls).toEqual([
    { slug: "GMAIL_FETCH_EMAILS", version: "20260903_00" },
  ]);
});

/*
 * The composite end-to-end outcome: a model that supplies the reserved key itself does not change
 * which revision runs. What holds it is the unconditional strip above the merge in `store.ts`.
 *
 * This is not a mutation gate, and no single mutation isolates it: reverting the strip, keeping the
 * strip but falling back to the raw arguments, and reversing the spread all leave it green, and its
 * assertion is already covered by `a Composio call sends the version recorded for that action`. It
 * is kept because the property is one somebody will want to confirm, not because it guards it.
 */
test("a version a model supplied in its own arguments cannot beat the recorded one", async () => {
  const { store, database } = await freshStore();
  const calls: { slug: string; version: string }[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug, version }) => {
      calls.push({ slug, version });
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store);

  await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    // A model filling in the reserved key itself. Stripped unconditionally, non-empty value and
    // all, before the recorded version is merged — so it never reaches the vendor under either
    // spread order.
    args: { __version: "19700101_00" },
    botId: "bot_helper",
    actorId: "user_asker",
  });

  // The listed revision, not the one the model asked for: supplying the reserved key changed
  // nothing about which revision ran.
  expect(calls).toEqual([
    { slug: "GMAIL_FETCH_EMAILS", version: "20260903_00" },
  ]);
});

test("a version a model supplied cannot stand in for an action with none recorded", async () => {
  const { store, database } = await freshStore();
  const calls: { slug: string; version: string }[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug, version }) => {
      calls.push({ slug, version });
      return vendorAnswered();
    },
  });
  // The action with no recorded version, which is the branch the test above does not cover: there
  // is nothing to merge in, and because the model's key was stripped there is no version in the
  // arguments at all — which is what the transport refuses on.
  await seedComposioGmail(database, store, { version: null });

  const result = await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: { __version: "19700101_00" },
    botId: "bot_helper",
    actorId: "user_asker",
  });

  // Never dialled. Honoured, the model's version runs a granted action at a revision that was never
  // listed, never classified and never granted, and the audit row carries no version field to say
  // which revision that was.
  //
  // Asserted before the refusal, so a regression fails here and names the version that reached the
  // vendor, rather than failing on a boolean that names nothing.
  expect(calls).toEqual([]);

  // The transport's refusal, which is the advertised answer for an action with no recorded version,
  // rather than a call against a revision a model named. The sentence offers a refresh CONDITIONALLY
  // — it recovers the action only where Composio publishes a version for it — because where the
  // vendor publishes none, no number of refreshes will make the action callable, and promising a
  // one-click fix that cannot work sends an operator round a loop.
  expect(result.isError).toBe(true);
  expect(result.text).toMatch(
    /Refreshing this app's tools on its Plugins page recovers it only if/,
  );
  expect(result.text).toMatch(
    /Where Composio publishes none, no refresh will make it callable/,
  );
});

/*
 * WHOSE ACCOUNT THE CALL OPENS, OBSERVED AT THE VENDOR.
 *
 * This is the claim the whole brokered transport exists to make, and until these two tests it was
 * the one thing nothing looked at. The deployment holds ONE Composio key; which person's mailbox a
 * call opens is decided entirely by the id sent beside it. Every stub in this file took `_userId`
 * and threw it away, so a store that sent the Bot's id, or the empty string, or a constant, passed
 * all of them — the property held by construction and nothing would have noticed it stopping.
 *
 * `execute`'s SECOND positional argument is that id. Recorded here rather than counted, so a
 * regression fails naming the id that actually went out.
 */
test("a Composio call reaches the vendor as the person asking, not as the Bot", async () => {
  const { store, database } = await freshStore();
  const reached: { slug: string; userId: string }[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ slug, userId }) => {
      reached.push({ slug, userId });
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store);

  await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  // `user_asker`, not `bot_helper` and not "". The id comes off the connection the call path built
  // from the session — `app.ts` takes it from a credential assertion and `routes.ts` from the
  // session — and it is the only thing standing between this Bot and somebody else's mailbox.
  expect(reached).toEqual([
    { slug: "GMAIL_FETCH_EMAILS", userId: "user_asker" },
  ]);
});

/**
 * An identity a model wrote into its own arguments does not become the identity of the call.
 *
 * THE THREE KEYS ARE THE ONES THAT WOULD WORK IF ANYTHING READ THEM. `userId` is the parameter
 * name on the transport's own projection, `user_id` is how Composio spells arguments, and
 * `entityId` is what their SDK called this before it was renamed — so a model that guessed at any
 * of the three would be guessing well.
 *
 * FORWARDED, NOT STRIPPED, AND THAT IS THE CORRECT BEHAVIOUR. The identity is `execute`'s second
 * POSITIONAL argument, taken from `connection.actorId`; `args` is the fourth and reaches the vendor
 * as the action's own parameters. Nothing on that path reads `args` looking for an identity, which
 * is what makes this structural rather than checked. Stripping the keys instead would be a bug with
 * a real victim: Composio's schemas are snake_case, `user_id` is an ordinary parameter name on real
 * actions, and a transport that swallowed it would quietly drop an argument the person meant. So
 * this asserts BOTH halves — the vendor is handed the asker as the identity, and it is handed the
 * model's arguments untouched.
 *
 * The absent `__version` is the other half of the same statement: the reserved key is the ONLY
 * thing removed from what a model sent.
 */
test("an identity a model puts in the arguments does not change whose account the call opens", async () => {
  const { store, database } = await freshStore();
  const reached: { userId: string; args: Record<string, unknown> }[] = [];
  useComposioClient({
    listActions: async () => [],
    execute: async ({ userId }, args) => {
      reached.push({ userId, args });
      return vendorAnswered();
    },
  });
  await seedComposioGmail(database, store);

  await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    // A model naming somebody else, three ways, beside one argument it genuinely meant.
    args: {
      userId: "user_stranger",
      user_id: "user_stranger",
      entityId: "user_stranger",
      query: "is:unread",
    },
    botId: "bot_helper",
    actorId: "user_asker",
  });

  expect(reached).toEqual([
    {
      // The session's person. None of the three keys reached the identity, because the identity is
      // not read from arguments at all.
      userId: "user_asker",
      // Passed through whole, minus nothing: the reserved version key is the only thing the call
      // path removes, and the model sent none.
      args: {
        userId: "user_stranger",
        user_id: "user_stranger",
        entityId: "user_stranger",
        query: "is:unread",
      },
    },
  ]);
});

test("a Composio call is recorded as reaching the vendor as the person, not as the deployment", async () => {
  const { store, database, auditStore } = await freshStore();
  useComposioClient({
    listActions: async () => [],
    execute: async () => vendorAnswered({ messages: [] }),
  });
  await seedComposioGmail(database, store);

  await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  const call = auditStore
    .recorded()
    .find((event) => event.eventType === "mcp.call_succeeded");

  // The single question a per-person connector raises: whose account did this reach. Recorded as
  // "deployment", the trail is wrong about exactly the thing this connector exists for — two rows for
  // the same action and the same Bot can have touched two different mailboxes, and nothing else in
  // the row says which.
  expect(call?.payload).toMatchObject({ reachedAs: "user_asker" });
});

/**
 * Every call event this suite's store recorded against one tool, in order.
 *
 * Named because the assertions below are about WHICH event was written, and reading that off an
 * unfiltered list would also pick up the grant the fixture makes. `mcp.call_` is the prefix the
 * three outcomes share.
 */
function callEventsFor(
  auditStore: { recorded: () => { eventType: string; targetId?: string }[] },
  targetId: string,
) {
  return auditStore
    .recorded()
    .filter(
      (event) =>
        event.targetId === targetId && event.eventType.startsWith("mcp.call_"),
    );
}

/**
 * A vendor that reported its own failure is filed as a failure, not as a success.
 *
 * `mcp.call_failed` is derived from `result.isError` and nothing asserted the derivation: flipping
 * the two event names left the suite green, so the trail could have said `mcp.call_succeeded` about
 * every refused call and the only surface that counts successes would have agreed. That is the same
 * class of defect as the one the comment above the try block describes — a trail asserting the
 * opposite of what happened — and it was still open on this branch.
 *
 * The sentence matters as much as the name. `payload.failure` is the vendor's own words, and it is
 * the most useful thing an operator gets: it is what turned "the connector is broken" into "the
 * connection lapsed" on the Drive path.
 */
test("a call the vendor refused is filed as failed, with the vendor's own sentence", async () => {
  const { store, database, auditStore } = await freshStore();
  useComposioClient({
    listActions: async () => [],
    execute: async () =>
      vendorRefused("Gmail rejected the request: bad label."),
  });
  await seedComposioGmail(database, store);

  const result = await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  expect(result.isError).toBe(true);

  // Exactly one call row, and it is the failure. Asserted as the whole list rather than by finding
  // a failure in it, because a `find` passes just as happily when a `mcp.call_succeeded` row sits
  // beside it — and a success row for a refused call is the thing being ruled out.
  expect(callEventsFor(auditStore, "gmail/GMAIL_FETCH_EMAILS")).toMatchObject([
    {
      eventType: "mcp.call_failed",
      payload: {
        actor: "user_asker",
        bot: "bot_helper",
        failure: "Gmail rejected the request: bad label.",
      },
    },
  ]);
});

/**
 * Our own unreadable answer is filed under the SAME name as the vendor's refusal.
 *
 * GATED AS IT BEHAVES TODAY, AND THE CONFLATION IS THE FINDING. `callTool` in `composio.ts` is
 * careful to keep these two apart — the vendor's `try` holds the vendor's call and nothing else,
 * precisely so a `JSON.stringify` throw of ours is not reported as the action having failed — and
 * then `store.ts` collapses the distinction again on the way to the trail, because the event name
 * is derived from `isError` alone and both are `isError: true`. So the only thing telling an
 * operator "Composio refused" from "Composio answered and we could not read it" is the sentence in
 * `payload.failure`, which is prose and not a queryable field. A reader counting `mcp.call_failed`
 * to decide whether a connector is healthy cannot separate a vendor fault from a bug of ours.
 *
 * A circular `data` is the honest way to reach it: `resultOf` stringifies whatever the vendor sent,
 * and a structure that cannot be serialized is one of the three faults its comment names.
 */
test("an answer this deployment could not read is filed under the same name as a vendor refusal", async () => {
  const { store, database, auditStore } = await freshStore();
  const circular: Record<string, unknown> = {};
  circular.itself = circular;
  useComposioClient({
    listActions: async () => [],
    execute: async () => vendorAnswered(circular),
  });
  await seedComposioGmail(database, store);

  const result = await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  expect(result.isError).toBe(true);

  const [event] = callEventsFor(auditStore, "gmail/GMAIL_FETCH_EMAILS");
  // The same event name the vendor's own refusal gets, one test above.
  expect(event?.eventType).toBe("mcp.call_failed");
  // And the sentence is the only thing that says this one was ours.
  expect((event?.payload as { failure?: string } | undefined)?.failure).toMatch(
    /could not turn that answer into text/,
  );
});

test("an action's effect, destructive marker and version round-trip", async () => {
  const database = await freshDatabase();

  await database.insert(mcpServers).values({
    id: "gmail",
    title: "Gmail",
    vendor: "Composio",
    url: "composio://gmail",
    provenance: "composio",
  });

  await database.insert(mcpTools).values([
    {
      serverId: "gmail",
      name: "GMAIL_FETCH_EMAILS",
      vendorName: "GMAIL_FETCH_EMAILS",
      description: "Fetch emails.",
      effect: "read",
      destructive: false,
      version: "20260903_00",
    },
    {
      serverId: "gmail",
      name: "GMAIL_DELETE_MESSAGE",
      vendorName: "GMAIL_DELETE_MESSAGE",
      description: "Delete a message.",
      effect: "write",
      destructive: true,
      version: "20260903_00",
    },
  ]);

  const rows = await database
    .select({
      name: mcpTools.name,
      effect: mcpTools.effect,
      destructive: mcpTools.destructive,
      version: mcpTools.version,
    })
    .from(mcpTools)
    .where(eq(mcpTools.serverId, "gmail"))
    .orderBy(asc(mcpTools.name));

  expect(rows).toEqual([
    {
      name: "GMAIL_DELETE_MESSAGE",
      effect: "write",
      destructive: true,
      version: "20260903_00",
    },
    {
      name: "GMAIL_FETCH_EMAILS",
      effect: "read",
      destructive: false,
      version: "20260903_00",
    },
  ]);
});

test("an action listed before these columns existed reads as unclassified and unversioned", async () => {
  const database = await freshDatabase();

  await database.insert(mcpServers).values({
    id: "notion",
    title: "Notion",
    vendor: "Notion",
    url: "https://mcp.notion.com/mcp",
    provenance: "first-party",
  });
  await database.insert(mcpTools).values({
    serverId: "notion",
    name: "notion-fetch",
    vendorName: "notion-fetch",
    description: "Fetch a page.",
  });

  const [row] = await database
    .select({
      effect: mcpTools.effect,
      destructive: mcpTools.destructive,
      version: mcpTools.version,
    })
    .from(mcpTools)
    .where(eq(mcpTools.serverId, "notion"));

  // Null rather than a default: an existing row must keep meaning exactly what it meant, and the
  // classifier decides what an absent effect implies. A column default of "write" would silently
  // reclassify every already-listed Notion read as a write the moment the migration ran.
  expect(row).toEqual({ effect: null, destructive: false, version: null });
});

test("a brokered call is judged by the effect the vendor recorded, not by the absent catalogue entry", async () => {
  const { store, database, auditStore } = await freshStore();
  useComposioClient({
    listActions: async () => [],
    execute: async () => vendorAnswered(),
  });
  // `effect: "read"` on the seeded action, and no catalogue entry for `gmail` at all — so the two
  // sources disagree and the row records which one decided.
  expect(catalogueEntry("gmail")).toBeNull();
  await seedComposioGmail(database, store);

  const result = await store.callTool({
    ref: "gmail/GMAIL_FETCH_EMAILS",
    args: {},
    botId: "bot_helper",
    actorId: "user_asker",
  });

  // The call completes: the transport is handed the version this action was listed at. Irrelevant to
  // what is under test — `effect` is decided before the vendor is dialled and the row carries the
  // decision on either outcome, which is the whole point of holding `decided` rather than writing it.
  expect(result.isError).toBe(false);

  const call = auditStore
    .recorded()
    .find((event) => event.eventType === "mcp.call_succeeded");
  // "read", because Composio labelled the action and the classifier prefers that label. "write" is
  // what an unlisted-in-`writeTools` tool on a server with no entry behind it comes out as, and that
  // is what this row said while the recorded effect was being selected and never passed on: every
  // Gmail read gated as a write, and `intent` in the policy context reading `write_tool`.
  expect((call?.payload as { effect?: string } | undefined)?.effect).toBe(
    "read",
  );
});

test("the Plugins page shows a brokered action with the effect the vendor recorded", async () => {
  const { store, database } = await freshStore();
  await seedComposioGmail(database, store);

  const gmail = (await store.listServers()).find(
    (server) => server.id === "gmail",
  );

  // Same disagreement as the call path, on the surface an administrator reads: no catalogue entry
  // behind `gmail`, so the reviewed-list branch has nothing to say and would call every one of the
  // app's actions a write. Shown as a write, this page tells an administrator that granting a Bot
  // "fetch emails" grants it something that changes their mailbox.
  expect(
    gmail?.tools.map((tool) => ({ name: tool.name, effect: tool.effect })),
  ).toEqual([{ name: "GMAIL_FETCH_EMAILS", effect: "read" }]);
});

/**
 * The narrow read the brokered routes make, and the one thing it must not do.
 *
 * CRITERION. `serverAddress` answers the url the ROW holds, whatever the row is called.
 *
 * REASON. Everything brokered rests on the id and the url being allowed to differ: `addBrokeredApp`
 * writes `composio://<slug>` and names the row for it, and nothing afterwards holds the two equal.
 * The routes read the app out of the url for exactly that reason, so a read that answered them with
 * `composio://${id}` — composed, and always agreeing with the id — would put the mismatch back
 * underneath four call sites at once and read as correct on every row anybody had not renamed. The
 * fixture is seeded with the disagreement on purpose, which is what `seedComposioGmail`'s own `url`
 * option exists for.
 *
 * The url listing is asserted off this fixture rather than out of a case of its own: it answers the
 * directory's set question from the same column, and the property worth pinning is the same one.
 */
test("a server's address is the url the row holds, not one composed from its id", async () => {
  const { store, database } = await freshStore();
  // A row called `gmail` pointing at Slack, which is the shape the connection gate was once keyed
  // on the wrong half of. `accountMode: null` as well, so the read below is asserted against the
  // column exactly as this fixture leaves it rather than against `seedComposioGmail`'s own default.
  await seedComposioGmail(database, store, {
    url: "composio://slack",
    accountMode: null,
  });

  expect(await store.serverAddress("gmail")).toEqual({
    id: "gmail",
    title: "Gmail",
    // Not `composio://gmail`. That is what composing the url from the id would have answered, and
    // it is the app this row does not run against.
    url: "composio://slack",
    // Null, because a scheme is written down when an authorization config is CREATED and this
    // fixture creates none. The column holds nothing for a row nothing was created against rather
    // than a default standing in for one, so null here is the read passing the column through.
    authScheme: null,
    // Null for the same reason, and passed explicitly above: the column holds nothing for a row
    // nothing decided rather than a default standing in for a decision.
    accountMode: null,
  });
  /*
   * By membership rather than by equality, because this database is not only this test's: the
   * suite's own `google-drive` row is there, and on a deployment somebody is using so is whatever
   * they have added. What is being asserted is which of the two spellings of this row reaches the
   * directory, and that survives the company.
   */
  const urls = await store.serverUrls();
  expect(urls).toContain("composio://slack");
  expect(urls).not.toContain("composio://gmail");
});

test("a server id naming no row is answered with nothing", async () => {
  const { store, database } = await freshStore();
  await seedComposioGmail(database, store);

  // `undefined` rather than a throw or an empty row, because that is what the `.find` over the
  // whole server list answered before — and the routes turn it into the 400 that says this app is
  // not reached through a broker.
  expect(await store.serverAddress("composio-gmail")).toBeUndefined();
});

test("refreshing a Composio app records each action's effect, destructive marker and version", async () => {
  const { store, database } = await freshStore();
  useComposioClient({
    listActions: async () => [
      {
        slug: "GMAIL_FETCH_EMAILS",
        description: "Fetch emails.",
        inputParameters: { type: "object", properties: {} },
        tags: ["readOnlyHint"],
        version: "20260903_00",
      },
      {
        slug: "GMAIL_DELETE_MESSAGE",
        description: "Delete a message.",
        inputParameters: { type: "object", properties: {} },
        tags: ["destructiveHint"],
        version: "20260903_00",
      },
      {
        slug: "GMAIL_SEND_EMAIL",
        description: "Send an email.",
        inputParameters: { type: "object", properties: {} },
        tags: ["createHint"],
        version: "20260903_00",
      },
    ],
    execute: async () => vendorAnswered(),
  });

  await database.insert(mcpServers).values({
    id: "gmail",
    title: "Gmail",
    vendor: "Composio",
    url: "composio://gmail",
    provenance: "composio",
  });

  await store.refreshTools("gmail", "admin_user");

  const rows = await database
    .select({
      name: mcpTools.name,
      effect: mcpTools.effect,
      destructive: mcpTools.destructive,
      version: mcpTools.version,
    })
    .from(mcpTools)
    .where(eq(mcpTools.serverId, "gmail"))
    .orderBy(asc(mcpTools.name));

  // The vendor's own three answers, as the listing gave them: a label, a marker, and the version a
  // call is impossible without. `createHint` is a write with no marker — an ordinary write is not
  // dangerous, and marking it so teaches an approver to click through the colour.
  expect(rows).toEqual([
    {
      name: "GMAIL_DELETE_MESSAGE",
      effect: "write",
      destructive: true,
      version: "20260903_00",
    },
    {
      name: "GMAIL_FETCH_EMAILS",
      effect: "read",
      destructive: false,
      version: "20260903_00",
    },
    {
      name: "GMAIL_SEND_EMAIL",
      effect: "write",
      destructive: false,
      version: "20260903_00",
    },
  ]);
});

/**
 * A grant on a Composio action the vendor has stopped listing, still reported as held.
 *
 * Confirmed for a brokered row rather than built: `listServers` derives `withdrawn` from the grants
 * no advertised action covers, with no transport-specific branch, so the Drive suite above gates
 * the mechanism. What a Composio row adds is that it inherits it — the app's page lists what the
 * last refresh advertised, so with nothing reporting the gap a permission on an action Composio
 * dropped is invisible and the Bot loses a capability nobody revoked.
 *
 * The refreshed listing names a DIFFERENT action rather than none at all, because an empty list is
 * also what a refresh the vendor refused leaves behind: every grant would come out withdrawn and
 * this would hold for a reason that has nothing to do with the action being gone.
 */
test("a granted Composio action that the vendor withdrew is still shown as granted", async () => {
  const { store, database } = await freshStore();
  useComposioClient({
    listActions: async () => [
      {
        slug: "GMAIL_SEND_EMAIL",
        description: "Send an email.",
        inputParameters: { type: "object", properties: {} },
        tags: ["createHint"],
        version: "20260903_00",
      },
    ],
    execute: async () => vendorAnswered(),
  });
  await seedComposioGmail(database, store);

  // The granted action is absent from what the vendor now lists, and another action is not.
  await store.refreshTools("gmail", "admin_user");

  const gmail = (await store.listServers()).find(
    (server) => server.id === "gmail",
  );

  expect(gmail?.withdrawn).toEqual([
    {
      ref: "gmail/GMAIL_FETCH_EMAILS",
      name: "GMAIL_FETCH_EMAILS",
      grantedTo: ["bot_helper"],
    },
  ]);
  // The advertised action came through as a tool, which is what says the refresh actually listed
  // rather than failing into the empty list that would withdraw everything.
  expect(gmail?.tools.map((tool) => tool.ref)).toEqual([
    "gmail/GMAIL_SEND_EMAIL",
  ]);
});

/*
 * A refresh the transport REFUSED, on the path every real deployment takes.
 *
 * NOTHING IN THE SHIPPED PRODUCT CALLS `useComposioClient`, so `installed` is null on every live
 * install and `composio.listTools` throws for want of a client to ask with. The tests below install
 * no stub, which is that state exactly rather than a fiction about it.
 *
 * THE PREMISE THIS DESCRIBE USED TO STATE — that the transport answers `[]` rather than throwing —
 * WAS TRUE AND IS NOT. It was corrected at the seam, deliberately: a transport that could not ask
 * anybody must throw, because an empty answer is indistinguishable from an app that genuinely
 * publishes nothing. These three cases therefore land in `refreshTools`'s vendor `catch`, which
 * records the sentence and returns before the replace — and they say nothing whatever about the
 * empty-listing guard below it, which is what the describe after this one is for. Two suites
 * asserting the same three outcomes through different branches is how that guard came to be
 * deletable with every test still green.
 *
 * What is under test here is the catch branch's own promise: a listing that could not be made
 * leaves every recorded action where it is, stamps no refresh, and withdraws nothing.
 */
describe("a refresh whose transport refused to ask anybody", () => {
  test("leaves the actions the app already advertises, with what the vendor said about them", async () => {
    const { store, database } = await freshStore();
    await seedComposioGmail(database, store);

    await store.refreshTools("gmail", "admin_user");

    const rows = await database
      .select({
        name: mcpTools.name,
        effect: mcpTools.effect,
        version: mcpTools.version,
      })
      .from(mcpTools)
      .where(eq(mcpTools.serverId, "gmail"));

    // The version above all: it is what `callTool` sends, so losing it breaks every later call on
    // an app the refresh reported as fine.
    expect(rows).toEqual([
      { name: "GMAIL_FETCH_EMAILS", effect: "read", version: "20260903_00" },
    ]);
  });

  test("does not report the app as healthy", async () => {
    const { store, database } = await freshStore();
    await seedComposioGmail(database, store);
    await database
      .update(mcpServers)
      .set({ lastError: "The vendor would not answer." })
      .where(eq(mcpServers.id, "gmail"));

    await store.refreshTools("gmail", "admin_user");

    const [row] = await database
      .select({
        lastError: mcpServers.lastError,
        toolsRefreshedAt: mcpServers.toolsRefreshedAt,
      })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));

    /*
     * The transport's own sentence, named rather than merely counted as present.
     *
     * `not.toBeNull()` was what this asserted, and the refresh had in fact OVERWRITTEN the value
     * the test set up two lines earlier — so "not cleared" passed on a different string than the
     * one it was about, and would have gone on passing had the column been filled with anything at
     * all, the empty-listing guard's sentence included. Which sentence is here is the whole
     * difference between "nobody could be asked" and "the app was asked and offers nothing", and
     * those send an operator to different places.
     */
    expect(row?.lastError).toContain("Composio is not configured");
    expect(row?.lastError).not.toBe("The vendor would not answer.");
    // And no refresh stamp, because nothing was listed: the column says when this deployment last
    // learned what the app offers, and it did not learn it here.
    expect(row?.toolsRefreshedAt).toBeNull();
  });

  test("does not strand the grants the app is holding", async () => {
    const { store, database, auditStore } = await freshStore();
    await seedComposioGmail(database, store);

    await store.refreshTools("gmail", "admin_user");

    const gmail = (await store.listServers()).find(
      (server) => server.id === "gmail",
    );

    // Still offered and still not withdrawn.
    expect(gmail?.tools.map((tool) => tool.ref)).toEqual([
      "gmail/GMAIL_FETCH_EMAILS",
    ]);
    expect(gmail?.withdrawn).toEqual([]);
    // Nor filed as having stopped being offered, which would be the trail asserting a withdrawal
    // the vendor never made.
    expect(
      auditStore
        .recorded()
        .filter(
          (event) =>
            (event.payload as { change?: string }).change ===
            "grants_not_advertised",
        ),
    ).toEqual([]);
  });

  test("a brokered row whose url names no app raises rather than blaming the vendor", async () => {
    const { store, database } = await freshStore();
    // `accessFor` still answers `brokered` for any row whose provenance says composio, so this is
    // `{ credential: "brokered", toolkit: null }` — a row a hand edit or an old backup produces and
    // nothing in the product can. There is no app to ask, so an empty answer is not the vendor's.
    await seedComposioGmail(database, store, {
      url: "https://example.com/mcp",
    });

    await expect(store.refreshTools("gmail", "admin_user")).rejects.toThrow(
      PluginInvariantError,
    );

    const [row] = await database
      .select({ lastError: mcpServers.lastError })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));

    // The state is this deployment's own, so it must not be written down as something a vendor did.
    expect(row?.lastError).toBeNull();
  });
});

/**
 * THE VENDOR ITSELF ANSWERING NOTHING, which is the state the empty-listing guard exists for.
 *
 * WHAT THIS COVERS THAT NOTHING ELSE DOES. The guard sits after the vendor `catch` and before the
 * wholesale replace, and only a listing that was actually MADE and came back empty reaches it. The
 * describe above cannot: its transport throws, so it returns from the catch several lines earlier.
 * With those three cases routed around it, `if (listed.length === 0)` could be replaced by
 * `if (false)` — deleting the guard outright — and the whole suite stayed green. Everything below
 * reddens under that mutation, which is the only thing that makes the guard's presence a fact
 * about this codebase rather than a comment in it.
 *
 * WHY IT MATTERS. The replace is a delete and an insert, so committing an empty answer deletes
 * every `mcp_tools` row for the app and takes `effect`, `destructive` and `version` with it.
 * `version` cannot be reconstructed — `callTool` refuses an action without one — so a refresh that
 * reported success broke every later call, with the grants left pointing at rows that no longer
 * exist. A stub that answers `[]` is a vendor's honest answer and is exactly what an app that has
 * been emptied at the broker looks like; keeping what is held is the only reading that is
 * recoverable if it is wrong.
 */
describe("a refresh the vendor answered with no actions at all", () => {
  /** A client that answers, and answers nothing — which no throw can stand in for. */
  function useEmptyAnsweringClient() {
    useComposioClient({
      listActions: async () => [],
      execute: async () => vendorAnswered(),
    });
  }

  test("keeps every action already recorded, with what the vendor said about them", async () => {
    const { store, database } = await freshStore();
    useEmptyAnsweringClient();
    await seedComposioGmail(database, store);

    // The honest count is what is HELD, because nothing was replaced. Answering 0 here would tell
    // the page the app offers nothing while the rows are still there.
    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 1,
    });

    const rows = await database
      .select({
        name: mcpTools.name,
        effect: mcpTools.effect,
        version: mcpTools.version,
      })
      .from(mcpTools)
      .where(eq(mcpTools.serverId, "gmail"));

    // The version above all: it is what `callTool` sends, so losing it breaks every later call on
    // an app the refresh reported as fine.
    expect(rows).toEqual([
      { name: "GMAIL_FETCH_EMAILS", effect: "read", version: "20260903_00" },
    ]);
  });

  test("says the actions were kept, and does not stamp a refresh", async () => {
    const { store, database } = await freshStore();
    useEmptyAnsweringClient();
    await seedComposioGmail(database, store);

    await store.refreshTools("gmail", "admin_user");

    const [row] = await database
      .select({
        lastError: mcpServers.lastError,
        toolsRefreshedAt: mcpServers.toolsRefreshedAt,
      })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));

    /*
     * The sentence for THIS state and not the other one. The app answered, so nothing here may
     * send an operator to check their configuration — that is the refused transport's sentence,
     * and the describe above asserts that one. What this reader needs to know is that the app
     * listed nothing and that the actions it holds were not deleted over it.
     */
    expect(row?.lastError).not.toBeNull();
    expect(row?.lastError).toContain("kept rather than deleted");
    // No stamp: the column says when this deployment last learned what the app offers, and an
    // answer it declined to believe is not it.
    expect(row?.toolsRefreshedAt).toBeNull();
  });

  test("withdraws nothing and strands no grant", async () => {
    const { store, database, auditStore } = await freshStore();
    useEmptyAnsweringClient();
    await seedComposioGmail(database, store);

    await store.refreshTools("gmail", "admin_user");

    const gmail = (await store.listServers()).find(
      (server) => server.id === "gmail",
    );

    // Still offered and still not withdrawn.
    expect(gmail?.tools.map((tool) => tool.ref)).toEqual([
      "gmail/GMAIL_FETCH_EMAILS",
    ]);
    expect(gmail?.withdrawn).toEqual([]);
    // Nor filed as having stopped being offered. That row is written from the listing, so an empty
    // one committed would name every grant the app holds — the trail asserting a withdrawal on
    // exactly the answer this deployment decided not to believe.
    expect(
      auditStore
        .recorded()
        .filter(
          (event) =>
            (event.payload as { change?: string }).change ===
            "grants_not_advertised",
        ),
    ).toEqual([]);
  });
});

/**
 * WHO IS TOLD WHAT, when the row itself is the thing that cannot be resolved.
 *
 * `ServerRowAmbiguousError` refuses a row whose provenance says `composio` and whose id is a
 * curated catalogue slug: nothing in the row and the entry tells a tampered curated row apart from
 * a brokered app that took the name, so there is no answer that is not wrong in one of the two
 * worlds. It shipped caught NOWHERE. Every audience therefore got the wrong thing at once — the
 * admin page a bodiless 500 it renders as "That did not work", and a model the operator's own
 * sentence about correcting a provenance column, offered to an end user as the reason their tool
 * failed.
 *
 * The store's half is asserted here: it refuses, and it records nothing about a vendor while doing
 * so. What each audience then sees is asserted where that audience is — the model below, and the
 * administrator in `plugin-routes.test.ts`, which is the file that exists for that mapping.
 */
describe("a row that resolves to two servers at once", () => {
  /** A colliding row, spelled the way the collision actually occurs: a curated slug, brokered. */
  async function seedCollidingNotion(database: Database) {
    await database.insert(mcpServers).values({
      id: "notion",
      title: "Notion",
      vendor: "Composio",
      url: "composio://notion",
      provenance: "composio",
    });
  }

  test("a refresh refuses it, and writes nothing about a vendor", async () => {
    const { store, database } = await freshStore();
    await seedCollidingNotion(database);

    await expect(store.refreshTools("notion", "admin_user")).rejects.toThrow(
      ServerRowAmbiguousError,
    );

    const [row] = await database
      .select({
        lastError: mcpServers.lastError,
        toolsRefreshedAt: mcpServers.toolsRefreshedAt,
      })
      .from(mcpServers)
      .where(eq(mcpServers.id, "notion"));

    // Two of our columns disagreeing is not a vendor's answer, so it must not be written where the
    // page draws what the vendor said. Raised instead, which is what the route reads.
    expect(row?.lastError).toBeNull();
    expect(row?.toolsRefreshedAt).toBeNull();
  });

  test("the model is told the call did not happen, and nothing about our columns", async () => {
    const { store, database } = await freshStore();
    await seedCollidingNotion(database);
    await database.insert(mcpTools).values({
      serverId: "notion",
      name: "notion-fetch",
      vendorName: "notion-fetch",
      description: "Fetch a page.",
    });
    await database.insert(agents).values({
      id: "bot_helper",
      name: "Helper",
      type: "built_in",
      configuration: {},
    });
    await store.grant(
      "mcp",
      "notion/notion-fetch",
      "bot_helper",
      "[email protected]",
    );

    const [tool] = await grantedTools({
      store,
      botId: "bot_helper",
      actorId: "user_asker",
    });
    if (!tool) throw new Error("the Bot was offered no tool to call");

    const answer = await tool.execute({});

    /*
     * Every part of the operator's sentence, named rather than summarised.
     *
     * The message says the row is one the deployment ships an entry for, that its provenance says
     * composio, and that somebody should rename it or correct the column. Each of those is a fact
     * about our database and an instruction only an administrator can act on; a model handed any
     * of them can only relay or embroider it. Asserted piecewise so a reworded sentence that still
     * leaks cannot pass by not matching one long string.
     */
    expect(answer).not.toContain("provenance");
    expect(answer).not.toContain("rename");
    expect(answer).not.toContain("notion");
    // And not dressed as a refusal either: nothing was decided against, so the marker the
    // transcript draws as a boundary holding would be a lie about which of the two happened.
    expect(answer.startsWith(REFUSAL_MARKER)).toBe(false);
    expect(answer).toBe("That tool could not be called.");
  });

  /**
   * AND THE CURATED ADD WILL NOT WRITE THROUGH IT, which is the other end of the same collision.
   *
   * CRITERION. `addServer` refuses a catalogue key whose row is brokered, and leaves the row exactly
   * as it stood.
   *
   * REASON. The refusals above are at RESOLUTION — they stop a colliding row being dialled. This one
   * is at the WRITE, and it protects something resolution cannot. `addServer` puts the catalogue's
   * url over whatever is there, and for this row that url is the only record of which app the
   * `composio_connections` rows behind it belong to: `removeServer` reads the app out of
   * `accessFor`, deliberately with no entry, so that a row in exactly this state is still removable
   * and its accounts still end at Composio. Overwritten, the app is unnameable, the accounts are
   * unreachable by any operation in this deployment, and the row is a curated server nobody
   * reviewed the arrival of.
   *
   * Unreachable from the shipped product today — `addBrokeredApp` mints `composio-<slug>` and no
   * entry is spelled that way — which is what the whole of this `describe` is already about: the
   * colliding row arrives by hand edit, by restore, or by a build whose catalogue took a name a past
   * build brokered. The two above say what happens when one is READ. This says what happens when
   * somebody presses Add on it.
   */
  test("the curated add refuses it rather than writing the catalogue's url over it", async () => {
    const { store, database } = await freshStore();
    await seedCollidingNotion(database);

    await expect(
      store.addServer({ key: "notion", by: "admin_user" }),
    ).rejects.toThrow(CustomServerRefusedError);

    // Untouched, which is what keeps the app removable: the slug is still readable off the url, so
    // `removeServer` can still find the accounts to end at the vendor.
    const [row] = await database
      .select({ url: mcpServers.url, provenance: mcpServers.provenance })
      .from(mcpServers)
      .where(eq(mcpServers.id, "notion"));
    expect(row).toEqual({
      url: "composio://notion",
      provenance: "composio",
    });
  });

  test("it is on the same shelf the store already raises rather than records", async () => {
    /*
     * The distinction, asked the way every audience asks it.
     *
     * Both audiences above branch on `isDeploymentFault` rather than on a class list of their own,
     * so what makes them correct is this answer and not the two `catch` blocks. A class added to
     * the shelf and forgotten here is the defect being fixed, one round later.
     */
    expect(isDeploymentFault(new ServerRowAmbiguousError("x"))).toBe(true);
    expect(isDeploymentFault(new CatalogueTransportUnroutableError("x"))).toBe(
      true,
    );
    expect(isDeploymentFault(new PluginInvariantError("x"))).toBe(true);
    // And the refusal somebody CAN act on is not on it: its message is the one thing this codebase
    // relays verbatim, to a model and to a browser alike.
    expect(isDeploymentFault(new PluginRefusedError("x", null))).toBe(false);
    expect(isDeploymentFault(new Error("the vendor did not answer"))).toBe(
      false,
    );
  });
});

/**
 * A catalogue entry naming the broker's transport, which no entry can be reached over.
 *
 * NOT A LIVE BUG AND NOT MEANT TO BECOME ONE. No entry declares it, and `CuratedTransportKind` now
 * makes declaring it a compile error — which is the real fix, since entries are code. This is what
 * holds when the type is bypassed: a cast, a fixture like the one below, or a loader that ever
 * reads an entry from outside the build.
 *
 * WHAT THE UNREFUSED ANSWER WAS. `transport: "composio"` with `toolkit: null`, a credential taken
 * from the entry's auth kind rather than `brokered`, and `reachedAs` from the same table. So the
 * dial went to the broker while both gates that keep one person's brokered account out of
 * another's — the connection lookup in `connectionTokenFor` and the app-slug check in
 * `refreshTools` — were keyed on a null app and skipped, and the trail recorded whose account had
 * been reached from a field that had nothing to do with it. Refusing is the only answer that does
 * not assert something false.
 */
test("a catalogue entry declaring the broker's transport is refused, not dialled", () => {
  /*
   * Cast at the fixture, deliberately and in one place. The type is what keeps this out of the
   * catalogue, so a test about what happens when the type is bypassed has to bypass it — and doing
   * it here rather than in a helper keeps the bypass visible beside the thing it is testing.
   */
  const brokered = {
    key: "brokered-entry",
    title: "Brokered Entry",
    vendor: "Somebody",
    summary: "An entry that names a transport an entry cannot be reached over.",
    host: "https://mcp.example.com",
    path: "/mcp",
    auth: {
      kind: "user-oauth" as const,
      authorizationUrl: "https://example.com/auth",
      tokenUrl: "https://example.com/token",
      revokeUrl: "https://example.com/revoke",
      scopes: [],
    },
    writeTools: [],
    transport: "composio",
    docsUrl: "https://example.com/docs",
  } as unknown as CatalogueEntry;

  expect(() =>
    accessFor(
      { provenance: "first-party", url: "https://mcp.example.com/mcp" },
      brokered,
    ),
  ).toThrow(CatalogueTransportUnroutableError);

  // The same entry with the transport it is actually reached over resolves as any other curated
  // per-person vendor does, so what is refused is the value and not the fixture.
  expect(
    accessFor(
      { provenance: "first-party", url: "https://mcp.example.com/mcp" },
      { ...brokered, transport: undefined },
    ),
  ).toEqual({
    transport: "mcp",
    credential: "person-oauth",
    reachedAs: "person",
    toolkit: null,
  });
});

/**
 * A COMPOSIO ACTION WHOSE ONLY FILE IS OPTIONAL IS RECORDED, WITHOUT THE FILE.
 *
 * The listing used to drop every action with a `file_uploadable` parameter in it, so a refresh of
 * Gmail recorded 59 of its 63 actions and never GMAIL_SEND_EMAIL, GMAIL_CREATE_EMAIL_DRAFT,
 * GMAIL_REPLY_TO_THREAD or GMAIL_UPDATE_DRAFT: no row to grant, so no Bot could send, draft or
 * reply. The rows below are Composio's own (`fixtures/composio-file-actions.json`), mapped through
 * `actionOf` exactly as the adapter maps a page, and what is asserted is the row a grant points at
 * and a model is shown.
 */
describe("a Composio action whose only file is optional", () => {
  test("is recorded with its version and without the attachment a model cannot fill in", async () => {
    const { store, database } = await freshStore();
    useComposioClient({
      listActions: async () =>
        fileActions.gmail.map((row, position) =>
          actionOf(structuredClone(row), position, "gmail"),
        ),
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 5,
    });

    const stored = await database
      .select({
        name: mcpTools.name,
        inputSchema: mcpTools.inputSchema,
        version: mcpTools.version,
      })
      .from(mcpTools)
      .where(eq(mcpTools.serverId, "gmail"))
      .orderBy(asc(mcpTools.name));

    expect(stored.map((row) => row.name)).toEqual([
      "GMAIL_CREATE_EMAIL_DRAFT",
      "GMAIL_FETCH_EMAILS",
      "GMAIL_REPLY_TO_THREAD",
      "GMAIL_SEND_EMAIL",
      "GMAIL_UPDATE_DRAFT",
    ]);
    // Callable: the version Composio published, which a call has to send back.
    expect(new Set(stored.map((row) => row.version))).toEqual(
      new Set(["20261018_00"]),
    );
    const send = stored.find((row) => row.name === "GMAIL_SEND_EMAIL")
      ?.inputSchema as { properties?: Record<string, unknown> } | undefined;
    const properties = Object.keys(send?.properties ?? {});
    expect(properties).not.toContain("attachment");
    expect(properties).toContain("recipient_email");
    expect(properties).toContain("body");
    // No staging descriptor in any row a model is shown.
    expect(JSON.stringify(stored.map((row) => row.inputSchema))).not.toContain(
      "file_uploadable",
    );
  });
});

/**
 * WHAT A VENDOR SENT THAT THIS DATABASE WILL NOT TAKE, and what came out when it did not.
 *
 * Both of these aborted the wholesale replace from INSIDE its transaction, which sits OUTSIDE the
 * vendor `try` above it — so neither was recorded and neither was caught. What left `refreshTools`
 * was drizzle's `DrizzleQueryError`, whose message is `Failed query:` followed by the entire
 * statement and then `params:` and every value bound to it. A SQL dump on an error path is the
 * same disclosure shape as a credential leak one layer out, and it reached the logs and any caller
 * that prints an error, while `lastError` sat holding whatever it held before: stale, or null, on
 * a refresh that had failed outright.
 *
 * Both are now settled before a statement is built, which is why the assertions below are about
 * the rows rather than about a better error.
 */
describe("a listing this database would not have taken", () => {
  test("a vendor naming one action twice records it once", async () => {
    const { store, database } = await freshStore();
    /*
     * The same slug twice, with different text, which is what a paginated listing that overlaps
     * or a broker with two entries for one action produces. `(server_id, name)` is the primary
     * key, so as one multi-row insert this refused the whole statement and rolled the delete back
     * with it — leaving the app holding its old actions and the refresh throwing a dump.
     */
    useComposioClient({
      listActions: async () => [
        {
          slug: "GMAIL_SEND_EMAIL",
          description: "Send an email.",
          inputParameters: { type: "object", properties: {} },
          version: "20260903_00",
        },
        {
          slug: "GMAIL_SEND_EMAIL",
          description: "Send an email, listed again.",
          inputParameters: { type: "object", properties: {} },
          version: "20260903_00",
        },
      ],
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    // One action, because the vendor named one action. Not two rows, and not a refusal.
    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 1,
    });

    const rows = await database
      .select({
        name: mcpTools.name,
        description: mcpTools.description,
      })
      .from(mcpTools)
      .where(eq(mcpTools.serverId, "gmail"));

    // The first occurrence, because the order is the vendor's own and there is no rule that says
    // which of two identical names is the real one.
    expect(rows).toEqual([
      { name: "GMAIL_SEND_EMAIL", description: "Send an email." },
    ]);

    const [row] = await database
      .select({ lastError: mcpServers.lastError })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));
    // A healthy refresh, because that is what it was.
    expect(row?.lastError).toBeNull();
  });

  test("a U+0000 in what the vendor wrote is dropped rather than aborting the replace", async () => {
    const { store, database } = await freshStore();
    /*
     * In the name, in the description and inside the schema, because all three reach the insert
     * and the column types differ: `text` refuses the byte and `jsonb` refuses the escape, and
     * each aborts the same transaction from a different statement position.
     */
    useComposioClient({
      listActions: async () => [
        {
          slug: "GMAIL_SEND\u0000_EMAIL",
          description: "Send\u0000 an email.",
          inputParameters: {
            type: "object",
            properties: { subject: { description: "The\u0000 subject" } },
          },
          version: "2026\u00000903_00",
        },
      ],
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 1,
    });

    const [stored] = await database
      .select({
        name: mcpTools.name,
        description: mcpTools.description,
        inputSchema: mcpTools.inputSchema,
        version: mcpTools.version,
      })
      .from(mcpTools)
      .where(eq(mcpTools.serverId, "gmail"));

    expect(stored?.name).toBe("GMAIL_SEND_EMAIL");
    expect(stored?.description).toBe("Send an email.");
    expect(stored?.version).toBe("20260903_00");
    // Inside the schema too, and the rest of the schema rebuilt exactly as it arrived.
    expect(stored?.inputSchema).toEqual({
      type: "object",
      properties: { subject: { description: "The subject" } },
    });
  });

  test("a schema that SPELLS the escape keeps it, because the byte is what the column refuses", async () => {
    const { store, database } = await freshStore();
    /*
     * WHAT THE COLUMN REFUSES IS THE CHARACTER, NOT THE SIX LETTERS THAT NAME IT.
     *
     * The strip used to run over the SERIALISED schema and remove the six characters that spell
     * the escape from it, which is escape-blind: `JSON.stringify` writes a real backslash in a
     * string value as two of them, so a
     * pattern excluding control characters — the single most ordinary place those six letters
     * appear in a JSON Schema — serialised as `\\u0000` and had its TAIL eaten, leaving `\-`,
     * which is not a JSON escape. `JSON.parse` then threw a `SyntaxError` from a line that sits
     * outside both `try` blocks in `refreshTools`: a bodiless 500 on the refresh route, a
     * `lastError` still holding whatever it held before, and — on the add path, which refreshes
     * before answering — an abort AFTER the server row and its audit row had committed.
     *
     * So the assertion is that the schema is stored EXACTLY as the vendor wrote it. Nothing here
     * contains a U+0000; there is nothing for the strip to do.
     */
    const spellsTheEscape = {
      type: "object",
      properties: {
        subject: {
          type: "string",
          // Every control character excluded, which is what this pattern is for and why it is the
          // one a real vendor sends.
          pattern: "^[^\\u0000-\\u001f]+$",
          description: "No control characters, written as \\u0000 in the text.",
        },
      },
    };
    useComposioClient({
      listActions: async () => [
        {
          slug: "GMAIL_SEND_EMAIL",
          description: "Send an email.",
          inputParameters: spellsTheEscape,
          version: "20260903_00",
        },
      ],
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 1,
    });

    const [stored] = await database
      .select({ name: mcpTools.name, inputSchema: mcpTools.inputSchema })
      .from(mcpTools)
      .where(eq(mcpTools.serverId, "gmail"));

    expect(stored?.name).toBe("GMAIL_SEND_EMAIL");
    // Byte for byte what arrived, backslashes and all.
    expect(stored?.inputSchema).toEqual(spellsTheEscape);

    const [row] = await database
      .select({ lastError: mcpServers.lastError })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));
    // A healthy refresh, because that is what it was.
    expect(row?.lastError).toBeNull();
  });

  test("a schema this deployment cannot make storable is recorded rather than thrown out of the refresh", async () => {
    const { store, database } = await freshStore();
    /*
     * THE CONTAINMENT, asserted on the one shape that still cannot be made into a row.
     *
     * A schema that refers to itself cannot be written to a `jsonb` column and cannot be walked to
     * the end. No wire JSON produces one, which is the point: what is under test is that the line
     * turning a vendor's answer into rows is INSIDE a `try` at all, so that whatever it cannot do
     * leaves `refreshTools` the way every other thing a vendor sent leaves it — recorded in
     * `lastError`, with what the app already holds kept, and the add that called it completed.
     *
     * The cycle hangs off `examples`, which `stagesAFile` does not walk, so it arrives here rather
     * than being refused by the transport's own filter one module earlier.
     */
    const selfReferential: Record<string, unknown> = {
      type: "object",
      properties: {},
    };
    selfReferential.examples = selfReferential;

    useComposioClient({
      listActions: async () => [
        {
          slug: "GMAIL_SEND_EMAIL",
          description: "Send an email.",
          inputParameters: selfReferential,
          version: "20260903_00",
        },
      ],
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    // Not a throw, and not a count that claims anything was learned.
    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 0,
    });

    const [row] = await database
      .select({
        lastError: mcpServers.lastError,
        toolsRefreshedAt: mcpServers.toolsRefreshedAt,
      })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));
    // Named on the row an operator reads, rather than lost with the throw.
    expect(row?.lastError).toContain("could not be stored");
    // And no statement or bound value in it, on the path that records a failure.
    expect(row?.lastError).not.toContain("Failed query");
    expect(row?.lastError).not.toContain("params:");
    // Nothing was learned about the app, so nothing says otherwise.
    expect(row?.toolsRefreshedAt).toBeNull();

    // What the app already had is still there, because nothing was replaced.
    expect(
      await database
        .select({ name: mcpTools.name })
        .from(mcpTools)
        .where(eq(mcpTools.serverId, "gmail")),
    ).toEqual([{ name: "GMAIL_FETCH_EMAILS" }]);
  });

  test("a description that is not text is named as a description, not as a schema", async () => {
    /*
     * THE FAR END OF A FIELD NOBODY GUARDED, and the reason the guard went into the transport
     * rather than here.
     *
     * `storableTools` reads `(tool.description ?? "").replaceAll(NUL, "")`, and `??` answers for
     * absence and not for type. A number, an object or a list in the vendor's `description` reached
     * that line and threw the engine's own `replaceAll is not a function`, which the `try` around
     * `storableTools` catches — so what an administrator read on the Plugins page was "an action
     * whose schema could not be stored as it arrived" followed by that. BOTH HALVES WERE WRONG. It
     * was not the schema, nothing named the action, nothing named the field, and the whole app's
     * refresh failed on one malformed row out of sixty.
     *
     * `composio.listTools` now refuses the listing while a sentence can still name the action, so
     * this lands in the vendor `catch` instead — the app keeps what it holds, stamps no refresh,
     * and the row says which action and which field. The assertion is about that sentence, because
     * the sentence is the whole difference between the two paths.
     */
    const { store, database } = await freshStore();
    useComposioClient({
      listActions: async () =>
        [
          {
            slug: "GMAIL_SEND_EMAIL",
            description: 7,
            inputParameters: { type: "object", properties: {} },
            version: "20260903_00",
          },
        ] as never,
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    // Not a throw, and not a count that claims anything was learned.
    expect(await store.refreshTools("gmail", "admin_user")).toEqual({
      tools: 0,
    });

    const [row] = await database
      .select({
        lastError: mcpServers.lastError,
        toolsRefreshedAt: mcpServers.toolsRefreshedAt,
      })
      .from(mcpServers)
      .where(eq(mcpServers.id, "gmail"));
    // The action, so an administrator has one row to look at rather than the app's whole listing.
    expect(row?.lastError).toContain("GMAIL_SEND_EMAIL");
    // The field, in the vendor's own terms.
    expect(row?.lastError).toContain("description");
    // Not the engine's sentence, and not the wrong noun for the field that was unreadable.
    expect(row?.lastError).not.toMatch(/is not a function/i);
    expect(row?.lastError).not.toContain("schema could not be stored");
    // Nothing was learned about the app, so nothing says otherwise.
    expect(row?.toolsRefreshedAt).toBeNull();

    // What the app already had is still there, because nothing was replaced.
    expect(
      await database
        .select({ name: mcpTools.name })
        .from(mcpTools)
        .where(eq(mcpTools.serverId, "gmail")),
    ).toEqual([{ name: "GMAIL_FETCH_EMAILS" }]);
  });

  test("a replace this database still refuses raises without the statement", async () => {
    /*
     * A transaction forced to fail, because after the two cases above nothing a vendor can send
     * reaches this branch — and this branch is the one that used to publish the dump. What is
     * asserted is the SHAPE of what comes out: the driver's own complaint, and none of the
     * statement or the values bound to it.
     */
    const { store, database } = await freshStore();
    useComposioClient({
      listActions: async () => [
        {
          slug: "GMAIL_SEND_EMAIL",
          description: "Send an email.",
          inputParameters: { type: "object", properties: {} },
          version: "20260903_00",
        },
      ],
      execute: async () => vendorAnswered(),
    });
    await seedComposioGmail(database, store);

    /*
     * Derived from the real one rather than stubbed, so every other query the refresh makes is
     * the real query. The failure is spelled the way drizzle spells one: the statement and every
     * bound value in `message`, the driver's own error hung off `cause`. That message is what
     * used to escape.
     */
    const refusing: Database = Object.create(database);
    Object.defineProperty(refusing, "transaction", {
      value: async () => {
        throw Object.assign(
          new Error(
            'Failed query: insert into "mcp_tools" ("server_id", "name") values ($1, $2) params: gmail, GMAIL_SEND_EMAIL',
          ),
          {
            cause: new Error(
              'duplicate key value violates unique constraint "mcp_tools_pkey"',
            ),
          },
        );
      },
    });

    const failing = createPluginStore({
      brokerProvider: "composio",
      database: refusing,
      auditStore: { insert: async () => {} },
      credentials: credentialsStub,
      encryptionKey: "x".repeat(44),
      policy: () => policy,
    });

    let thrown: unknown;
    try {
      await failing.refreshTools("gmail", "admin_user");
    } catch (error) {
      thrown = error;
    }

    const message = thrown instanceof Error ? thrown.message : String(thrown);
    // The driver's complaint, which names what went wrong.
    expect(message).toContain("duplicate key value violates unique constraint");
    // And nothing of the statement or of what was bound to it.
    expect(message).not.toContain("Failed query");
    expect(message).not.toContain("insert into");
    expect(message).not.toContain("params:");
    // On the shelf that is raised rather than recorded and never relayed to a model, because a
    // transaction this database would not take is not something the vendor did.
    expect(isDeploymentFault(thrown)).toBe(true);

    // And what the app already had is still there, because nothing was committed.
    expect(
      await database
        .select({ name: mcpTools.name })
        .from(mcpTools)
        .where(eq(mcpTools.serverId, "gmail")),
    ).toEqual([{ name: "GMAIL_FETCH_EMAILS" }]);
  });
});

/**
 * A QUERY OF OURS THAT FAILED, on the two paths that copy a caught message onward.
 *
 * WHAT THE SHAPE IS. drizzle wraps every failure as a `DrizzleQueryError`: `message` is `Failed
 * query:` plus the whole statement, then `params:` and every value bound to it, with the driver's
 * own error on `cause`. On the tool-call path those values are credential ids, user ids and server
 * ids; on the refresh path they are the vendor's tool list.
 *
 * WHERE IT COMES FROM. A per-person MCP listing is the shape that runs a query of ours inside the
 * block that catches the vendor's failures: `connectionTokenFor` reads the asking person's stored
 * grant there. `composio` never gets that far — `listNeedsCredential` is false for it, the only
 * brokered transport — and a server added by URL reads its one token from the vault rather than
 * from a query. So the failure is injected at that one read and arrives exactly where it would in
 * production, rather than being handed to the `catch` from somewhere it could not come from.
 */
describe("a query of this deployment's own that failed", () => {
  /** The drizzle shape, spelled once: statement and bound values in `message`, driver on `cause`. */
  function queryFailure() {
    return Object.assign(
      new Error(
        'Failed query: select "credential_id" from "mcp_user_credentials" where "user_id" = $1 params: user_asker',
      ),
      {
        query: 'select "credential_id" from "mcp_user_credentials"',
        params: ["user_asker"],
        cause: new Error("canceling statement due to statement timeout"),
      },
    );
  }

  test("a refresh raises it rather than recording it as what the vendor said", async () => {
    const { database } = await freshStore();

    /*
     * Notion, because a per-person MCP listing is the only shape that runs a query of ours inside
     * the vendor `try`. `composio` never gets there — `listNeedsCredential` is false for it, so
     * `connectionTokenFor` is not called at all — and a server added by URL reads its one token
     * from the vault rather than from a query. Resolved from the catalogue rather than spelled, so
     * a renamed slug breaks this file instead of quietly emptying it.
     */
    const notion = catalogueEntry("notion");
    if (!notion) {
      throw new Error(
        "catalogue slug `notion` is gone, so nothing here reaches a per-person listing",
      );
    }

    // `user_leaver` rather than a new id: this file already owns a `users` row at it, so the
    // person, the connection and the server row are all cleaned by machinery that exists.
    await database.insert(users).values({
      id: "user_leaver",
      email: "[email protected]",
      name: "Leaver",
    });
    const [grant] = await database
      .insert(credentialRows)
      .values({
        kind: "mcp_user_token",
        provider: "notion",
        keyId: "user_leaver",
        encryptedValue: "{}",
        metadata: {},
      })
      .returning({ id: credentialRows.id });
    if (!grant) throw new Error("grant row was not created");
    await database.insert(mcpServers).values({
      id: "notion",
      title: notion.title,
      vendor: notion.vendor,
      url: `${notion.host}${notion.path}`,
      provenance: "first-party",
    });
    await database.insert(mcpUserCredentials).values({
      serverId: "notion",
      userId: "user_leaver",
      credentialId: grant.id,
      scope: "",
    });

    /*
     * The stored-grant read, failed — and nothing else.
     *
     * Derived from the real database so every other query the refresh makes is the real query.
     * The second `select` is the one: `requireServer` reads the server row first, outside the
     * block that catches vendor failures, and `connectionTokenFor`'s read of this person's grant
     * is the next one and is inside it. Counting is what makes the failure land there rather than
     * somewhere a blanket override would put it, and the assertions below distinguish the two —
     * the row id in the message is added only by the conversion in that `catch`, so a failure
     * escaping the earlier read would arrive as the raw dump and redden.
     */
    let selects = 0;
    const refusing: Database = Object.create(database);
    Object.defineProperty(refusing, "select", {
      value: (...args: never[]) => {
        selects += 1;
        if (selects === 2) throw queryFailure();
        return database.select(...args);
      },
    });
    const failing = createPluginStore({
      brokerProvider: "composio",
      database: refusing,
      auditStore: { insert: async () => {} },
      credentials: credentialsStub,
      encryptionKey: "x".repeat(44),
      policy: () => policy,
    });

    let thrown: unknown;
    try {
      await failing.refreshTools("notion", "user_leaver");
    } catch (error) {
      thrown = error;
    }

    try {
      const [row] = await database
        .select({
          lastError: mcpServers.lastError,
          toolsRefreshedAt: mcpServers.toolsRefreshedAt,
        })
        .from(mcpServers)
        .where(eq(mcpServers.id, "notion"));

      /*
       * Nothing in the column, asserted FIRST because it is the half that was actually broken and
       * because its failure prints what leaked.
       *
       * `lastError` is drawn on the Plugins page beside a refresh that looks merely to have
       * failed, and the narrowing meant to keep our own faults out of it tested for a class that
       * cannot arrive inside that `try` at all — so it could be deleted with every test green
       * while the statement and every value bound to it went into a column an operator reads and
       * an export carries.
       */
      expect(row?.lastError).toBeNull();
      expect(row?.toolsRefreshedAt).toBeNull();

      // Raised, because a query this database refused is not something the vendor did — the same
      // criterion the replace further down this method is held to.
      expect(isDeploymentFault(thrown)).toBe(true);
      const message = thrown instanceof Error ? thrown.message : String(thrown);
      expect(message).toContain("canceling statement due to statement timeout");
      expect(message).not.toContain("Failed query");
      expect(message).not.toContain("params:");
      expect(message).not.toContain("mcp_user_credentials");
      // Named by the conversion inside the refresh's own `catch`, which is how this asserts WHERE
      // the failure was classified and not merely that something was thrown.
      expect(message).toContain("notion:");
    } finally {
      /*
       * Locally, and in this order. `mcp_user_credentials.credential_id` is a real foreign key
       * that deliberately does not cascade, so the join row has to go before the vault row — and
       * the teardown that clears vault rows for this file runs before the one that clears server
       * rows, which is what would otherwise leave a delete refusing.
       */
      await database
        .delete(mcpUserCredentials)
        .where(
          and(
            eq(mcpUserCredentials.serverId, "notion"),
            eq(mcpUserCredentials.userId, "user_leaver"),
          ),
        );
      await database
        .delete(credentialRows)
        .where(eq(credentialRows.id, grant.id));
    }
  });

  test("the model is told the call did not happen, and none of the query", async () => {
    /*
     * At the seam that decides, which is where the leak was.
     *
     * `grantedTools` takes a store, and the question is what it hands the model when that store
     * throws — so the store is the thing stubbed and nothing else is. Every query on the call path
     * runs inside `callTool`'s own recording block and comes out of it unchanged, so this shape
     * arriving here is the production arrival, not an approximation of one.
     */
    const [tool] = await grantedTools({
      store: {
        listForAgent: async () => ({
          tools: [
            {
              ref: "gmail/GMAIL_FETCH_EMAILS",
              toolName: "gmail__GMAIL_FETCH_EMAILS",
              description: "Fetch emails.",
              inputSchema: { type: "object", properties: {} },
            },
          ],
          skills: [],
        }),
        callTool: async () => {
          throw queryFailure();
        },
      } as unknown as PluginStore,
      botId: "bot_helper",
      actorId: "user_asker",
    });
    if (!tool) throw new Error("the Bot was offered no tool to call");

    const answer = await tool.execute({});

    /*
     * What the model is handed, exactly.
     *
     * Not the statement and not the values bound to it — on this path those are credential ids,
     * user ids and server ids. Not a sentence blaming the vendor either: the call never reached
     * one, and `That tool could not be called: <our SQL>` is what the model used to be given to
     * explain the failure to the person asking.
     */
    expect(answer).toBe("That tool could not be called.");
    expect(answer).not.toContain("Failed query");
    expect(answer).not.toContain("params:");
    expect(answer).not.toContain("mcp_user_credentials");
  });

  test("the trail gets the reason and none of the query", async () => {
    const database = await freshDatabase();
    const events: { eventType: string; payload: unknown }[] = [];
    /*
     * Thrown at the vendor seam, and recorded by the block above it.
     *
     * WHERE THIS ARRIVES FROM IN PRODUCTION: `connectionTokenFor`, three lines earlier and inside
     * the same `try` — its connection gate read, its vault read and its locked credential swap
     * are all queries of ours. Reaching one of those and failing only it needs a counted override
     * of every `select` the call path makes, which pins a test to the order of queries rather than
     * to the property. `callVendor` is the one seam this store hands a caller, and a throw through
     * it lands in exactly the `catch` those queries land in; what that `catch` can do about a
     * throw is classify it, which is the property.
     */
    const failing = createPluginStore({
      brokerProvider: "composio",
      database,
      auditStore: {
        insert: async (event) => {
          events.push(event as (typeof events)[number]);
        },
      },
      credentials: credentialsStub,
      encryptionKey: "x".repeat(44),
      policy: () => policy,
      callVendor: async () => {
        throw queryFailure();
      },
    });
    await seedComposioGmail(database, failing);

    await expect(
      failing.callTool({
        ref: "gmail/GMAIL_FETCH_EMAILS",
        args: {},
        botId: "bot_helper",
        actorId: "user_asker",
      }),
    ).rejects.toThrow();

    const failed = events.filter(
      (event) => event.eventType === "mcp.call_failed",
    );
    expect(failed).toHaveLength(1);
    const failure =
      (failed[0]?.payload as { failure?: string } | undefined)?.failure ?? "";
    /*
     * The reason, because "is this connector working" is asked of this row and the driver's
     * complaint answers it. Not the statement and not the values bound to it: on this path those
     * are credential ids, user ids and server ids, and `audit_events` is read by an operator and
     * carried out of the deployment by an export.
     */
    expect(failure).toContain("canceling statement due to statement timeout");
    expect(failure).not.toContain("Failed query");
    expect(failure).not.toContain("params:");
    expect(failure).not.toContain("mcp_user_credentials");
  });
});

/**
 * The genuine empty listing, which has to stay recordable.
 *
 * The guard above must not turn "this app advertises nothing" into a state the deployment cannot
 * hold, or an app that really offers no actions would read as broken for good. An app with nothing
 * recorded against it has nothing to lose, so the empty answer commits: refreshed, no error and no
 * actions, which is the honest reading of an app that advertises none.
 */
test("an app with nothing recorded against it can be refreshed to no actions at all", async () => {
  const { store, database } = await freshStore();
  useComposioClient({
    listActions: async () => [],
    execute: async () => vendorAnswered(),
  });
  await database.insert(mcpServers).values({
    id: "gmail",
    title: "Gmail",
    vendor: "Composio",
    url: "composio://gmail",
    provenance: "composio",
    lastError: "Whatever was wrong last time.",
  });

  expect(await store.refreshTools("gmail", "admin_user")).toEqual({ tools: 0 });

  const [row] = await database
    .select({
      lastError: mcpServers.lastError,
      toolsRefreshedAt: mcpServers.toolsRefreshedAt,
    })
    .from(mcpServers)
    .where(eq(mcpServers.id, "gmail"));

  expect(row?.lastError).toBeNull();
  expect(row?.toolsRefreshedAt).not.toBeNull();
});

/**
 * An audit write that fails, which is not the vendor misbehaving.
 *
 * The refresh used to run the listing, the replace, the server-row update and both audit writes
 * inside one `catch` that recorded everything as `lastError` and answered `{ tools: 0 }`. So a
 * database that would not take an audit row reported a vendor which had in fact answered correctly,
 * and reported it against actions the refresh had already committed — sending whoever reads the
 * page to a vendor's status page over a fault in their own database.
 *
 * Its own store rather than {@link freshStore}, because the audit insert is the seam that has to
 * fail and that fixture's is deliberately a real one.
 */
test("an audit write that fails is not recorded as the vendor misbehaving", async () => {
  const database = await freshDatabase();
  const failing = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore: {
      insert: async (event) => {
        if (
          (event.payload as { change?: string }).change ===
          "grants_not_advertised"
        ) {
          throw new Error("audit_events would not take the row");
        }
      },
    },
    credentials: credentialsStub,
    encryptionKey: "x".repeat(44),
    policy: () => policy,
  });

  useComposioClient({
    listActions: async () => [
      {
        slug: "GMAIL_SEND_EMAIL",
        description: "Send an email.",
        inputParameters: { type: "object", properties: {} },
        tags: ["createHint"],
        version: "20260903_00",
      },
    ],
    execute: async () => vendorAnswered(),
  });
  // The granted action is absent from what the vendor now lists, so the refresh reaches the audit
  // write about grants nothing advertises — the one the stub above refuses.
  await seedComposioGmail(database, failing);

  await expect(failing.refreshTools("gmail", "admin_user")).rejects.toThrow(
    "audit_events would not take the row",
  );

  const [row] = await database
    .select({ lastError: mcpServers.lastError })
    .from(mcpServers)
    .where(eq(mcpServers.id, "gmail"));

  expect(row?.lastError).toBeNull();
});

/**
 * The moment a brokered app starts existing, which is an auth config before it is a row.
 *
 * The id and the url are different strings on purpose, and both are asserted. `composio-linear` is
 * what a grant and a policy rule are written against, and it carries a prefix so it cannot land on
 * a curated entry's slug or on one of the ids the fixtures above reserve; `composio://linear` is
 * what `accessFor` reads the app off, and that is the field the transport and the connection gate
 * both settle the app from. A test that asserted only one of them would pass on an implementation
 * that made them equal, which is the arrangement those two rules exist to keep apart.
 *
 * THE BROKER IS ASKED FIRST AND EXACTLY ONCE. First because a row whose auth config does not exist
 * is an app an administrator can see and nobody can connect to; once because `ensureAuthConfig` is
 * idempotent at the vendor and a second call here would be this deployment leaning on that. The
 * connection the caller resolved is asserted as it reaches the broker unchanged, because that kind
 * decides what config is created at the vendor: an enable path that re-derived it here rather than
 * passing the caller's through would be a second answer to the question this argument exists to
 * settle once.
 *
 * `composio-linear` is cleaned up in a `finally` rather than by {@link freshDatabase}, which knows
 * only the ids the guard at the top of this file cleared. The row is checked absent before the add
 * for the same reason every delete in this file is guarded: the id is spelled the way production
 * spells it, so a row already at it would be somebody's app rather than this test's.
 */
test("enabling an app writes a brokered row, and asks for its auth config first", async () => {
  const asked: {
    toolkit: string;
    name: string;
    connection: BrokerConnection;
  }[] = [];
  const rowsWhenAsked: string[] = [];
  const unasked = (what: string) => async (): Promise<never> => {
    throw new Error(`enabling an app asked the broker to ${what}`);
  };
  const broker: ComposioBroker = {
    // This stub stands in for Composio, whose grant is held locally; see `ConnectedAppBroker.grantIsLocal`.
    grantIsLocal: true,
    // Nothing here asks what auth provider a connection is held under.
    authProviderOf: async () => null,
    // Nothing here reads either member; both are declared because the seam requires a
    // broker to SAY what it runs — see `ConnectedAppBroker.authorizations`.
    authorizations: null,
    grantsFor: unasked("read grants"),
    listApps: unasked("list the catalogue"),
    ensureAuthConfig: async (config) => {
      asked.push(config);
      /*
       * What the table held at the moment the broker was asked, which is how "first" is asserted
       * rather than assumed. Counting the calls says nothing about the order, and the order is the
       * whole property: an implementation that wrote the row and then asked would leave an app on
       * the page that nobody can connect to whenever this call fails.
       */
      const rows = await database
        .select({ id: mcpServers.id })
        .from(mcpServers)
        .where(eq(mcpServers.id, "composio-linear"));
      rowsWhenAsked.push(...rows.map((row) => row.id));
      return "created";
    },
    deleteAuthConfig: unasked("delete an auth config"),
    authorize: unasked("begin somebody's connection"),
    isConnected: unasked("check somebody's connection"),
    revoke: unasked("withdraw somebody's grant"),
    // Enabling an app draws no connect form, connects nobody and undoes no account. All three are
    // declared so the stub is a `ConnectedAppBroker` rather than a partial one, and all three fail
    // if reached.
    connectionFields: unasked("read an app's connection fields"),
    connectWithFields: unasked("connect somebody with typed fields"),
    revokeAccount: unasked("undo one account"),
    accountName: async () => null,
  };

  const { store, database, auditStore } = await freshStore({ broker });
  useComposioClient({
    listActions: async () => [
      {
        slug: "LINEAR_CREATE_ISSUE",
        description: "Create an issue.",
        inputParameters: { type: "object", properties: {} },
        tags: ["createHint"],
        version: "20260903_00",
      },
    ],
    execute: async () => vendorAnswered(),
  });

  const [present] = await database
    .select({ id: mcpServers.id })
    .from(mcpServers)
    .where(eq(mcpServers.id, "composio-linear"));
  if (present) {
    throw new Error(
      "a row at 'composio-linear' was already here, so it is not this test's to write over",
    );
  }

  try {
    const record = await store.addBrokeredApp({
      slug: "linear",
      title: "Linear",
      logo: "https://example.com/linear.svg",
      by: "[email protected]",
      connection: { kind: "consent" },
    });

    expect(record.id).toBe("composio-linear");
    expect(record.logo).toBe("https://example.com/linear.svg");
    expect(record.url).toBe("composio://linear");
    expect(record.provenance).toBe("composio");
    // No credential of its own, and none to come: a brokered row is reached as the person asking,
    // on their connection at the vendor, so there is nothing on this row for a vault to hold.
    expect(record.hasCredential).toBe(false);

    expect(asked).toEqual([
      { toolkit: "linear", name: "Linear", connection: { kind: "consent" } },
    ]);
    expect(rowsWhenAsked).toEqual([]);

    const changes = auditStore
      .recorded()
      .filter((event) => event.eventType === "configuration.changed");
    expect(changes).toHaveLength(1);
    expect(changes[0]?.payload).toMatchObject({
      change: "mcp_server_added",
      provenance: "composio",
    });
  } finally {
    await database
      .delete(mcpTools)
      .where(eq(mcpTools.serverId, "composio-linear"));
    await database
      .delete(mcpServers)
      .where(eq(mcpServers.id, "composio-linear"));
  }
});

/**
 * The same call on a deployment that has no Composio key, which is the documented default.
 *
 * The refusal names the setting because the name is the whole remedy, and nothing else about a
 * deployment with no broker will tell an administrator what to set. Asserted on the message rather
 * than the class so that the sentence an operator actually reads is what this test is about.
 */
test("enabling an app with no broker says which setting is missing", async () => {
  const { store } = await freshStore();

  await expect(
    store.addBrokeredApp({
      slug: "linear",
      title: "Linear",
      by: "[email protected]",
    }),
  ).rejects.toThrow("COMPOSIO_API_KEY");
});

/**
 * A broker that answers only the methods a test names, in the order it was asked.
 *
 * WHAT IS NOT NAMED THROWS, which is the half that carries the assertions below. "The disconnect
 * asked the broker to revoke" is worth very little on its own; "and asked it nothing else" is the
 * property, because a connection path that also listed the catalogue or created an auth config
 * would be doing work on somebody's behalf that nobody here has reasoned about. A default stub
 * answering plausibly would let all of that pass unremarked.
 *
 * `order` records the calls rather than counting them, so a test can say which of two things
 * happened first. The state a call found the database in is NOT recorded here: the handlers are
 * the test's own functions, so a test that needs to know what a row looked like at the moment of
 * the call reads it inside its own handler — the same way the enablement test above establishes
 * that the auth config comes before the row.
 *
 * AND THE ENTRY NAMES WHOSE CALL IT WAS, where the call has an owner. A path that revokes for one
 * person is fully described by `revoke`; a path that revokes for everybody connected to an app is
 * not, because "two revokes happened" says nothing about who they were for and nothing about the
 * order they went out in — and the order is what makes a removal repeatable. So the request's
 * `userId` is appended where there is one, and calls that are about the deployment rather than a
 * person (`deleteAuthConfig`) stay bare.
 */
function brokerSpy(answers: {
  ensureAuthConfig?: (config: {
    toolkit: string;
    name: string;
  }) => Promise<void>;
  deleteAuthConfig?: (toolkit: string) => Promise<void>;
  isConnected?: (request: {
    account: AccountRef;
    toolkit: string;
  }) => Promise<boolean>;
  revoke?: (request: {
    account: AccountRef;
    toolkit: string;
  }) => Promise<boolean>;
}): { broker: ComposioBroker; order: string[] } {
  const order: string[] = [];
  const unasked = (what: string) => async (): Promise<never> => {
    throw new Error(`the connection path asked the broker to ${what}`);
  };
  const asked = <Request, Answer>(
    name: string,
    handler: ((request: Request) => Promise<Answer>) | undefined,
    what: string,
  ) => {
    return async (request: Request): Promise<Answer> => {
      const owner =
        typeof request === "object" &&
        request !== null &&
        "account" in request &&
        typeof request.account === "object" &&
        request.account !== null &&
        "vendorUserId" in request.account &&
        typeof request.account.vendorUserId === "string"
          ? `:${request.account.vendorUserId}`
          : "";
      order.push(`${name}${owner}`);
      if (!handler)
        throw new Error(`the connection path asked the broker to ${what}`);
      return await handler(request);
    };
  };

  return {
    order,
    broker: {
      // This stub stands in for Composio, whose grant is held locally; see `ConnectedAppBroker.grantIsLocal`.
      grantIsLocal: true,
      // A broker that does not say what auth provider a connection is held under, which is what
      // the sibling resolution has to treat as "we do not know" rather than as "none".
      authProviderOf: async () => null,
      // Nothing here reads either member; both are declared because the seam requires a
      // broker to SAY what it runs — see `ConnectedAppBroker.authorizations`.
      authorizations: null,
      grantsFor: unasked("read grants"),
      listApps: unasked("list the catalogue"),
      ensureAuthConfig: asked(
        "ensureAuthConfig",
        answers.ensureAuthConfig,
        "create an auth config",
      ),
      deleteAuthConfig: asked(
        "deleteAuthConfig",
        answers.deleteAuthConfig,
        "delete an auth config",
      ),
      authorize: unasked("begin somebody's connection"),
      isConnected: asked(
        "isConnected",
        answers.isConnected,
        "check somebody's connection",
      ),
      revoke: asked("revoke", answers.revoke, "withdraw somebody's grant"),
      accountName: async () => null,
    },
  };
}

/**
 * The row is the vendor's answer written down, and nothing else may write it.
 *
 * CRITERION. After a confirm the deployment says somebody is connected if and only if Composio
 * said so when asked.
 *
 * REASON. The return trip from consent is an ordinary redirect with nothing signed in it, so a
 * browser arriving back on the page is evidence of nothing at all — not that the flow finished,
 * and not that the account it finished with is the one this row would claim. A confirm that wrote
 * a row because somebody came back would hand every subsequent brokered call a gate that passes
 * for an account that may not exist, and the first thing anybody would see of the mistake is the
 * vendor's own error about a connection it cannot find.
 *
 * BOTH ANSWERS IN ONE TEST, over one store, because the second is what makes the first mean
 * something: a confirm that never wrote a row would pass the "not connected" assertion on its own.
 */
test("a brokered connection row is written only where the vendor says the account is live", async () => {
  let live = false;
  const { broker, order } = brokerSpy({ isConnected: async () => live });
  const { store, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };

  expect(
    await store.confirmBrokeredConnection({ toolkit, account, by: userId }),
  ).toEqual({
    connected: false,
  });
  // Nothing at all, which is the whole of the first half: the gate a brokered call is decided on
  // must not exist for somebody the vendor does not recognise.
  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();
  expect(auditStore.recorded()).toHaveLength(0);

  live = true;
  expect(
    await store.confirmBrokeredConnection({ toolkit, account, by: userId }),
  ).toEqual({
    connected: true,
  });
  const connection = await store.brokeredConnection({ toolkit, account });
  expect(connection?.connectedAt).toBeTruthy();

  expect(order).toEqual(["isConnected:user_asker", "isConnected:user_asker"]);
  const connected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_connected");
  expect(connected).toHaveLength(1);
  expect(connected[0]?.payload).toMatchObject({
    actor: "user_asker",
    server: "gmail",
    // Empty because Composio grants no scope this deployment is told about, and the field explains
    // a later refusal for want of one. A guess written here would be an explanation nobody gave.
    scope: "",
    reconnected: false,
  });
});

/**
 * An account ended in Composio's own dashboard is forgotten here the next time we ask.
 *
 * CRITERION. Where a row is already written down and the vendor says the account is not live, the
 * confirm removes the row, and it files nothing in the trail for having removed it.
 *
 * REASON. The row is a cache of the vendor's answer, and nothing tells this deployment when that
 * answer changes: a grant withdrawn at Composio ends the account with no callback arriving here.
 * A confirm that only ever wrote rows would leave the settings list drawing "Connected" for an
 * account nobody has, leave the gate every brokered call is decided on passing for it, and leave
 * the app's own detail page — which asks the vendor on mount — contradicting the list beside it.
 *
 * THE TRAIL STAYS EMPTY, which is asserted rather than assumed. Nobody disconnected anything: the
 * grant ended elsewhere and this is the record catching up, so an `mcp.account_disconnected` row
 * written here would credit a page load with an act it did not perform. `disconnectBrokered` is
 * what files that event, for the disconnect it actually carried out.
 */
test("confirming a brokered connection the vendor no longer has removes the row", async () => {
  const { broker, order } = brokerSpy({ isConnected: async () => false });
  const { store, database, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: toolkit,
    holder: "person",
    userId,
    vendorUserId: userId,
  });

  expect(
    await store.confirmBrokeredConnection({ toolkit, account, by: userId }),
  ).toEqual({
    connected: false,
  });

  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();
  expect(order).toEqual(["isConnected:user_asker"]);
  expect(auditStore.recorded()).toHaveLength(0);
});

/**
 * A confirm that healed a row nothing changed is a read, and the trail does not record reads.
 *
 * CRITERION. Confirming a connection that is already written down leaves exactly the one
 * `mcp.account_connected` row the first confirm filed, however many times it is called.
 *
 * REASON. This method runs on page load and not on a button: the connector page calls it once per
 * mount for every brokered app it draws. An event per yes from the vendor therefore writes ten
 * "account connected" rows for somebody who opened the page ten times having connected once, and
 * a trail padded with acts nobody performed cannot answer the only question it is kept for. It is
 * the failure the `reconnected` field is already written to avoid, arriving one level up at the
 * event itself.
 *
 * THE VENDOR IS STILL ASKED EVERY TIME, which is asserted here rather than assumed: the row is a
 * cache of Composio's answer and the re-asking is how a row that drifted heals. What stops on the
 * second call is the writing-down of the heal as somebody's act, not the heal.
 */
test("confirming a brokered connection already recorded writes no second trail row", async () => {
  const { broker, order } = brokerSpy({ isConnected: async () => true });
  const { store, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };

  expect(
    await store.confirmBrokeredConnection({ toolkit, account, by: userId }),
  ).toEqual({
    connected: true,
  });
  const first = await store.brokeredConnection({ toolkit, account });
  expect(first?.connectedAt).toBeTruthy();

  expect(
    await store.confirmBrokeredConnection({ toolkit, account, by: userId }),
  ).toEqual({
    connected: true,
  });
  expect(
    await store.confirmBrokeredConnection({ toolkit, account, by: userId }),
  ).toEqual({
    connected: true,
  });

  expect(order).toEqual([
    "isConnected:user_asker",
    "isConnected:user_asker",
    "isConnected:user_asker",
  ]);
  // Unmoved, because the person connected when they connected: the confirms above are page loads.
  expect(await store.brokeredConnection({ toolkit, account })).toEqual(first);
  expect(
    auditStore
      .recorded()
      .filter((event) => event.eventType === "mcp.account_connected"),
  ).toHaveLength(1);
});

/**
 * Disconnecting ends the account at the vendor BEFORE it forgets where the account was.
 *
 * CRITERION. The broker is asked to revoke while the row is still there, and the row goes only
 * after it answered.
 *
 * REASON. The row is the only thing in this deployment that names which app this person connected:
 * delete it first and a revoke that then fails leaves a live grant on somebody's mailbox that no
 * operation here can reach, because the toolkit it would have to be revoked under is readable off
 * a row that is by now gone. Ordering the other way is recoverable by definition — pressing
 * disconnect again asks again.
 *
 * ASSERTED ON WHAT THE REVOKE SAW, not on a call count, because a count says nothing about order
 * and the order is the entire property.
 */
test("disconnecting a brokered connection revokes at the vendor before the row goes", async () => {
  const rowsWhenRevoked: string[] = [];
  const { broker, order } = brokerSpy({
    revoke: async () => {
      const rows = await database
        .select({ userId: brokeredConnections.userId })
        .from(brokeredConnections)
        .where(ownedConnections());
      rowsWhenRevoked.push(...rows.map((row) => row.userId));
      return true;
    },
  });
  const { store, database, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: toolkit,
    holder: "person",
    userId,
    vendorUserId: userId,
  });

  const outcome = await store.disconnectBrokered({
    toolkit,
    account,
    by: userId,
    reason: "self",
  });

  expect(outcome).toEqual({ vendorRevocationRequested: true });
  expect(rowsWhenRevoked).toEqual(["user_asker"]);
  expect(order).toEqual(["revoke:user_asker"]);
  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();

  const disconnected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_disconnected");
  expect(disconnected).toHaveLength(1);
  expect(disconnected[0]?.payload).toMatchObject({
    actor: "user_asker",
    server: "gmail",
    owner: "user_asker",
    reason: "self",
    // What happened, not what was attempted. The broker said it withdrew a grant, so the trail
    // says so; a field that always said true would make the row a worse record than none.
    vendorRevocationRequested: true,
  });
});

/**
 * A revoke that throws leaves the connection exactly where it was, so pressing again finishes it.
 *
 * CRITERION. A failed disconnect removes nothing and records nothing, and the same call made again
 * against a broker that now answers completes the job.
 *
 * REASON. This is the payoff of the ordering above, stated as the behaviour somebody actually
 * meets: Composio is down for a minute, the person presses disconnect, and the alternative to
 * keeping the row is an account still live at the vendor with nothing left here that knows which
 * app it belongs to. Keeping it means the only cost of the failure is that they press the button
 * again.
 */
test("a brokered connection outlives a revoke that failed, and a second attempt ends it", async () => {
  let broken = true;
  const { broker } = brokerSpy({
    revoke: async () => {
      if (broken) throw new Error("Composio would not answer (502).");
      return true;
    },
  });
  const { store, database, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: toolkit,
    holder: "person",
    userId,
    vendorUserId: userId,
  });

  await expect(
    store.disconnectBrokered({
      toolkit,
      account,
      by: userId,
      reason: "self",
    }),
  ).rejects.toThrow("Composio would not answer (502).");

  expect(await store.brokeredConnection({ toolkit, account })).not.toBeNull();
  // No row in the trail either. "Their account was disconnected" is a claim about the vendor, and
  // nothing was disconnected anywhere.
  expect(auditStore.recorded()).toHaveLength(0);

  broken = false;
  expect(
    await store.disconnectBrokered({
      toolkit,
      account,
      by: userId,
      reason: "self",
    }),
  ).toEqual({ vendorRevocationRequested: true });
  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();
});

/**
 * A revoke that found nothing to withdraw says so, and the row goes all the same.
 *
 * CRITERION. Where the broker answers `false`, both the outcome and the trail carry
 * `vendorRevocationRequested: false`, and the `composio_connections` row is deleted regardless.
 *
 * REASON. This is the grant somebody already ended in Composio's own dashboard. The account is
 * gone at the vendor, so the local row is the stale half of a pair that has drifted and deleting
 * it is what makes the two agree again. What must not happen is the trail claiming this
 * deployment withdrew something: a row saying the grant was ended here when it was ended
 * somewhere else is a worse record than none, because whoever reads back for who ended it is
 * given the wrong answer in the same words as the right one.
 *
 * THE FALSE IS THE WHOLE TEST. `vendorRevocationRequested` is indistinguishable from a hardcoded
 * `true` until a revoke answers no, and no other test in this file exercises one.
 */
test("a brokered disconnect that withdrew no grant records that it withdrew none", async () => {
  const { broker, order } = brokerSpy({ revoke: async () => false });
  const { store, database, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: toolkit,
    holder: "person",
    userId,
    vendorUserId: userId,
  });

  expect(
    await store.disconnectBrokered({
      toolkit,
      account,
      by: userId,
      reason: "self",
    }),
  ).toEqual({ vendorRevocationRequested: false });

  expect(order).toEqual(["revoke:user_asker"]);
  // Gone, because there was nothing at the vendor and the row was therefore the half that had
  // drifted. Keeping it would leave the gate on every brokered call passing for an account that
  // no longer exists anywhere.
  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();

  const disconnected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_disconnected");
  expect(disconnected).toHaveLength(1);
  expect(disconnected[0]?.payload).toMatchObject({
    actor: "user_asker",
    server: "gmail",
    owner: "user_asker",
    reason: "self",
    vendorRevocationRequested: false,
  });
});

/**
 * A disconnect that found nothing to disconnect says nothing in the trail.
 *
 * CRITERION. With no `composio_connections` row for the pair, the call still asks the broker to
 * revoke, and files an `mcp.account_disconnected` event only where that ask withdrew a grant.
 * Nothing here and nothing at the vendor is nothing disconnected, and the trail stays empty.
 *
 * REASON. This is the second press of Disconnect. The screen that made it easy — a row still
 * reading "Connected" after a successful disconnect — has been fixed, but any caller can make the
 * same call twice, and an event filed for it would tell whoever reads the trail back that
 * somebody's account ended at a moment when nobody's did. A trail padded with acts nobody
 * performed cannot answer the one question it is kept for, which is the reasoning
 * `confirmBrokeredConnection` already files its connected event under.
 *
 * THE VENDOR IS ASKED ALL THE SAME, which is asserted and not assumed. The row is a cache of
 * Composio's answer and it drifts by construction — the confirm deletes it on any `false` from the
 * vendor — so an absence here is no evidence that the grant is gone, and this call is the only
 * operation in this deployment that can end one. What the missing row stops is the writing-down of
 * an act, not the ask.
 *
 * BOTH ANSWERS IN ONE TEST, because the second is what makes the first mean something: a guard
 * that filed nothing whenever the row was missing would pass the empty-trail assertion on its own,
 * and would lose the case that matters most — a live account ended for somebody whose local row
 * had already gone.
 */
test("a brokered disconnect with nothing to disconnect files nothing in the trail", async () => {
  let granted = false;
  const { broker, order } = brokerSpy({ revoke: async () => granted });
  const { store, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_asker";
  const account = { holder: "person" as const, userId, vendorUserId: userId };

  expect(
    await store.disconnectBrokered({
      toolkit,
      account,
      by: userId,
      reason: "self",
    }),
  ).toEqual({ vendorRevocationRequested: false });

  expect(order).toEqual(["revoke:user_asker"]);
  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();
  // Empty, which is the whole of the first half: no row went and no grant was withdrawn, so
  // nobody was disconnected and the trail has nothing to say about it.
  expect(auditStore.recorded()).toHaveLength(0);

  // The same absence locally, but this time the ask found a live account and ended it. That is an
  // act — the weightier of the two this method performs — and it is recorded.
  granted = true;
  expect(
    await store.disconnectBrokered({
      toolkit,
      account,
      by: userId,
      reason: "self",
    }),
  ).toEqual({ vendorRevocationRequested: true });

  const disconnected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_disconnected");
  expect(disconnected).toHaveLength(1);
  expect(disconnected[0]?.payload).toMatchObject({
    actor: "user_asker",
    server: "gmail",
    owner: "user_asker",
    reason: "self",
    vendorRevocationRequested: true,
  });
});

/**
 * A brokered connection is visible to the person who made it, under the server row's own id.
 *
 * CRITERION. `brokeredConnectionsFor` answers one row per app this person has connected, carrying
 * the `serverId`, `scope` and `connectedAt` that `connectionsFor` answers with — so one screen
 * draws both kinds of row — plus the `verified` and `verifiedAt` that only a brokered row has,
 * because only a brokered row is a thing this deployment can re-check. The `serverId` in it is the
 * id of the `mcp_servers` row whose url names that app.
 *
 * REASON. `connectionsFor` selects from the vault's join table alone, so a brokered connection was
 * invisible to the browser and the settings screen could not honestly say whether somebody was
 * connected. The id has to be joined rather than composed because the url is where the app is
 * recorded: `composio-${toolkit}` spelled by hand answers with whatever production happens to
 * spell today, and this fixture — a server row at `gmail`, not at `composio-gmail` — is the case
 * that tells a joined id from a guessed one.
 */
test("a brokered connection is listed for its owner under the server row's own id", async () => {
  const { store, database } = await freshStore();
  await seedComposioGmail(database, store);

  const connections = await store.brokeredConnectionsFor("user_asker");
  expect(connections).toHaveLength(1);
  expect(connections[0]).toMatchObject({
    serverId: "gmail",
    // Empty for the reason the confirm gives: Composio grants no scope it tells us about, and the
    // field is returned anyway so one settings screen can draw both kinds of connection.
    scope: "",
  });
  expect(connections[0]?.connectedAt).toBeTruthy();

  // Nobody else's, which is the only other thing this query promises.
  expect(await store.brokeredConnectionsFor("user_leaver")).toEqual([]);
});

/**
 * And it is the url that decides which server row a connection belongs to, not the id.
 *
 * CRITERION. A person connected to `gmail`, with the only Composio server row sitting at
 * `composio://slack`, is listed against nothing.
 *
 * REASON. The id and the url are two fields and nothing in the schema holds them equal — which is
 * the shape `seedComposioGmail` exists to reproduce. Reading the connection's app off the url is
 * the same thing the directory route does when it decides which apps are enabled, and it is what
 * stops this query telling somebody they have a Slack connection because a row called `gmail`
 * happened to be pointed somewhere else.
 */
test("a brokered connection is not listed against a server row whose url names another app", async () => {
  const { store, database } = await freshStore();
  await seedComposioGmail(database, store, { url: "composio://slack" });

  expect(await store.brokeredConnectionsFor("user_asker")).toEqual([]);
});

/**
 * Removing an app ends every account at the vendor, and only then forgets where they were.
 *
 * CRITERION. `removeServer` on a brokered row revokes at the broker for every connected person
 * while their rows are still standing, deletes the rows after that, and drops the deployment's
 * auth config last of all — and the trail says of each person that the grant was really withdrawn.
 *
 * REASON. Clearing `composio_connections` closes the gate this deployment owns and nothing else:
 * the account the person attached is still live at Composio, and an administrator who pressed
 * "remove" was not told they had left it there. So the removal ends the accounts too, and the
 * order is forced. A brokered row's toolkit is readable off nothing but the row, so delete-first
 * and a revoke that then fails leaves a live grant on somebody's mailbox with no value left here
 * to revoke it under; revoke-first and the same failure leaves the app present, every account
 * dead, and removing again finishes the job. Dead-and-reachable beats live-and-unreachable.
 *
 * THE AUTH CONFIG GOES LAST for the same reasoning one step out. An orphaned auth config grants
 * nobody anything — it is a shape this deployment holds at Composio, not an account — while a live
 * account whose config has already gone is access nobody here can end.
 *
 * ASSERTED ON WHAT EACH CALL SAW, not on a count. Counting says nothing about order, and the order
 * is the entire property: an implementation that deleted the rows first and revoked off what the
 * delete returned would make exactly the same calls in exactly the same sequence.
 *
 * THE PEOPLE CONNECT IN REVERSE, `user-b` before `user-a`, so that the sorted revoke is doing work
 * rather than agreeing with the insertion order by luck.
 */
test("removing an app revokes everybody, then clears rows, then drops the config", async () => {
  /** Who was still connected to `linear` at the moment of each broker call, in call order. */
  const connectedWhenAsked: string[][] = [];
  const stillConnected = async () =>
    (
      await database
        .select({ userId: brokeredConnections.userId })
        .from(brokeredConnections)
        .where(eq(brokeredConnections.app, "linear"))
        .orderBy(asc(brokeredConnections.userId))
    ).map((row) => row.userId);

  const { broker, order } = brokerSpy({
    ensureAuthConfig: async () => "created",
    isConnected: async () => true,
    revoke: async () => {
      connectedWhenAsked.push(await stillConnected());
      return true;
    },
    deleteAuthConfig: async () => {
      connectedWhenAsked.push(await stillConnected());
    },
  });
  const { store, database, auditStore } = await freshStore({ broker });
  useComposioClient({
    listActions: async () => [
      {
        slug: "LINEAR_CREATE_ISSUE",
        description: "Create an issue.",
        inputParameters: { type: "object", properties: {} },
        tags: ["createHint"],
        version: "20260903_00",
      },
    ],
    execute: async () => vendorAnswered(),
  });

  /*
   * This fixture's own ids, checked here because the guard at the top of the file does not cover
   * them: `composio-linear` and the pairs at `linear` are spelled the way production spells them,
   * so a row already sitting at one belongs to somebody else and the cleanup below would take it.
   */
  const [present] = await database
    .select({ id: mcpServers.id })
    .from(mcpServers)
    .where(eq(mcpServers.id, "composio-linear"));
  const strangers = await database
    .select({ userId: brokeredConnections.userId })
    .from(brokeredConnections)
    .where(
      and(
        eq(brokeredConnections.app, "linear"),
        inArray(brokeredConnections.userId, ["user-a", "user-b"]),
      ),
    );
  if (present || strangers.length > 0) {
    throw new Error(
      "a 'composio-linear' server row or a 'linear' connection for user-a or user-b was already " +
        "here, so it is not this test's to write over",
    );
  }

  try {
    await store.addBrokeredApp({
      slug: "linear",
      title: "Linear",
      by: "admin",
      connection: { kind: "consent" },
    });
    for (const userId of ["user-b", "user-a"]) {
      expect(
        await store.confirmBrokeredConnection({
          toolkit: "linear",
          account: { holder: "person", userId, vendorUserId: userId },
          by: userId,
        }),
      ).toEqual({ connected: true });
    }

    // The setup's own traffic, cleared so what follows is about the removal and nothing else.
    order.length = 0;
    connectedWhenAsked.length = 0;

    await store.removeServer("composio-linear", "admin");

    expect(order).toEqual([
      "revoke:user-a",
      "revoke:user-b",
      "deleteAuthConfig",
    ]);
    /*
     * Both revokes found both rows, and the auth config was dropped with none left. This is the
     * ordering the call list above cannot see: revoking off the rows a delete had already returned
     * would produce that same list while leaving nothing to revoke under if the broker refused.
     */
    expect(connectedWhenAsked).toEqual([
      ["user-a", "user-b"],
      ["user-a", "user-b"],
      [],
    ]);

    expect(
      await store.brokeredConnection({
        toolkit: "linear",
        account: {
          holder: "person",
          userId: "user-a",
          vendorUserId: "user-a",
        },
      }),
    ).toBeNull();
    expect(
      await store.brokeredConnection({
        toolkit: "linear",
        account: {
          holder: "person",
          userId: "user-b",
          vendorUserId: "user-b",
        },
      }),
    ).toBeNull();

    const disconnected = auditStore
      .recorded()
      .filter((event) => event.eventType === "mcp.account_disconnected");
    expect(disconnected).toHaveLength(2);
    expect(disconnected.map((event) => event.targetId)).toEqual([
      // The app, not the server row's id, because that is what a brokered connection is keyed on
      // and the id is gone by the time anybody reads back.
      "linear",
      "linear",
    ]);
    expect(disconnected.map((event) => event.payload)).toEqual([
      {
        actor: "admin",
        server: "linear",
        owner: "user-a",
        // Not "they disconnected" and not "they were removed": an administrator took the whole
        // app away and the person did nothing.
        reason: "mcp_server_removed",
        /*
         * True, and true because the broker said so rather than because the call returned. This
         * is the whole change: the row used to say `false` here whatever happened, which was
         * honest only while the removal left every account live at Composio.
         */
        vendorRevocationRequested: true,
      },
      {
        actor: "admin",
        server: "linear",
        owner: "user-b",
        reason: "mcp_server_removed",
        vendorRevocationRequested: true,
      },
    ]);
  } finally {
    await database
      .delete(mcpTools)
      .where(eq(mcpTools.serverId, "composio-linear"));
    await database
      .delete(mcpServers)
      .where(eq(mcpServers.id, "composio-linear"));
    await database
      .delete(brokeredConnections)
      .where(
        and(
          eq(brokeredConnections.app, "linear"),
          inArray(brokeredConnections.userId, ["user-a", "user-b"]),
        ),
      );
  }
});

/**
 * Offboarding somebody ends the accounts they connected, where they actually live.
 *
 * CRITERION. `retireConnectionsFor` on somebody holding two brokered connections revokes both at
 * the broker while their rows are still standing, deletes the rows after that, counts both, and
 * says in the trail of each that the grant was really withdrawn.
 *
 * REASON. A brokered connection holds no secret of ours, so deleting the row shuts the gate this
 * deployment owns and leaves the mailbox attached at Composio. "We removed their access" was then
 * untrue of the only thing that matters — the grant at the vendor — for the person it matters most
 * about, one who has been removed and cannot be asked to disconnect anything themselves.
 *
 * REVOKE BEFORE DELETE, and the order is forced by what the row is. It is the only place naming
 * which apps this person had, and it outlives the `users` row precisely so offboarding can still
 * find them; that was the table's whole justification and until now nothing exercised it. Delete
 * first and a broker that refuses leaves a live grant on a departed person's mailbox with nothing
 * left here to revoke it under. Revoke first and the same refusal leaves the rows standing and
 * offboarding repeatable. Dead-and-reachable beats live-and-unreachable.
 *
 * ASSERTED ON WHAT EACH CALL SAW, not on a count and not on the call list. Both revokes are for
 * one person, so the recorded sequence is identical whichever order the code uses — an
 * implementation revoking off what the delete returned would make the same two calls. Reading the
 * table from inside the stub is the only thing here that can tell the two apart.
 *
 * THE APPS ARE CONNECTED IN REVERSE, `linear` before `gmail`, so the sorted revoke is doing work
 * rather than agreeing with the insertion order by luck.
 */
test("removing a person revokes their brokered accounts at the broker", async () => {
  /** Which apps this person was still connected to at the moment of each revoke, in call order. */
  const connectedWhenAsked: string[][] = [];
  /** Which app each revoke was for, which the spy's own `revoke:user_leaver` entries cannot say. */
  const revoked: string[] = [];
  // Through the file's own handle, which is the one `freshStore` hands back: the rows this test
  // writes are swept by {@link freshDatabase} and the teardown, so nothing here needs a local name
  // for the database.
  const stillConnected = async () =>
    (
      await database
        .select({ toolkit: brokeredConnections.app })
        .from(brokeredConnections)
        .where(eq(brokeredConnections.userId, "user_leaver"))
        .orderBy(asc(brokeredConnections.app))
    ).map((row) => row.toolkit);

  const { broker, order } = brokerSpy({
    isConnected: async () => true,
    revoke: async ({ toolkit }) => {
      connectedWhenAsked.push(await stillConnected());
      revoked.push(toolkit);
      return true;
    },
  });
  const { store, auditStore } = await freshStore({ broker });

  for (const toolkit of ["linear", "gmail"]) {
    expect(
      await store.confirmBrokeredConnection({
        toolkit,
        account: {
          holder: "person",
          userId: "user_leaver",
          vendorUserId: "user_leaver",
        },
        by: "user_leaver",
      }),
    ).toEqual({ connected: true });
  }

  // The setup's own traffic, cleared so what follows is about the offboarding and nothing else.
  order.length = 0;

  expect(await store.retireConnectionsFor("user_leaver", "admin")).toEqual({
    // Both of them, because the number is what "we removed their access" claims.
    retired: 2,
  });

  expect(order).toEqual(["revoke:user_leaver", "revoke:user_leaver"]);
  expect(revoked).toEqual(["gmail", "linear"]);
  /*
   * Both revokes found both rows. This is the ordering neither list above can see: revoking off
   * the rows a delete had already returned would produce both of them unchanged while leaving
   * nothing to revoke under if the broker refused.
   */
  expect(connectedWhenAsked).toEqual([
    ["gmail", "linear"],
    ["gmail", "linear"],
  ]);

  expect(
    await store.brokeredConnection({
      toolkit: "gmail",
      account: {
        holder: "person",
        userId: "user_leaver",
        vendorUserId: "user_leaver",
      },
    }),
  ).toBeNull();
  expect(
    await store.brokeredConnection({
      toolkit: "linear",
      account: {
        holder: "person",
        userId: "user_leaver",
        vendorUserId: "user_leaver",
      },
    }),
  ).toBeNull();

  const disconnected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_disconnected");
  expect(disconnected).toHaveLength(2);
  // The app, which for a brokered connection is all the row records and all that is left once
  // the person is gone.
  expect(disconnected.map((event) => event.targetId)).toEqual([
    "gmail",
    "linear",
  ]);
  expect(disconnected.map((event) => event.payload)).toEqual([
    {
      actor: "admin",
      server: "gmail",
      owner: "user_leaver",
      // An administrator removing somebody, never somebody changing their own mind.
      reason: "person_removed",
      /*
       * True, and true because the broker said so rather than because the call returned. This
       * is the whole change: the row used to say `false` here whatever happened, which was
       * honest only while offboarding left every account live at Composio.
       */
      vendorRevocationRequested: true,
    },
    {
      actor: "admin",
      server: "linear",
      owner: "user_leaver",
      reason: "person_removed",
      vendorRevocationRequested: true,
    },
  ]);
});

/**
 * And where there was no grant left to withdraw, offboarding says so.
 *
 * CRITERION. A broker answering `false` leaves `vendorRevocationRequested: false` in the trail, and
 * the row is deleted and counted just the same.
 *
 * REASON. The account was already ended in Composio's own dashboard, so the local row is the stale
 * half of a pair that has drifted. What must not happen is the trail claiming this deployment
 * withdrew something: whoever reads back for who ended somebody's access is then given the wrong
 * answer in the same words as the right one.
 *
 * THE FALSE IS THE WHOLE TEST. A pass-through is indistinguishable from a hardcoded `true` until a
 * revoke answers no, and nothing else on this path exercises one.
 */
test("offboarding a brokered account nobody held any more withdraws nothing, and says so", async () => {
  const { broker, order } = brokerSpy({ revoke: async () => false });
  const { store, database, auditStore } = await freshStore({ broker });
  const toolkit = "gmail";
  const userId = "user_leaver";
  const account = { holder: "person" as const, userId, vendorUserId: userId };
  await database.insert(brokeredConnections).values({
    provider: "composio",
    app: toolkit,
    holder: "person",
    userId,
    vendorUserId: userId,
  });

  expect(await store.retireConnectionsFor("user_leaver", "admin")).toEqual({
    retired: 1,
  });

  expect(order).toEqual(["revoke:user_leaver"]);
  // Gone, because there was nothing at the vendor and the row was therefore the half that had
  // drifted. Keeping it would leave the gate passing for a person who no longer exists.
  expect(await store.brokeredConnection({ toolkit, account })).toBeNull();

  const disconnected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_disconnected");
  expect(disconnected).toHaveLength(1);
  expect(disconnected[0]?.payload).toMatchObject({
    actor: "admin",
    server: "gmail",
    owner: "user_leaver",
    reason: "person_removed",
    vendorRevocationRequested: false,
  });
});

/**
 * The same false, on the other act that ends a brokered connection.
 *
 * CRITERION. `removeServer` on a brokered row whose broker answers `false` records
 * `vendorRevocationRequested: false`, and still clears the row and drops the config.
 *
 * REASON. The removal test above pins the `true`, which a literal `true` in the store would pass
 * just as well — and one did, for the whole of this suite, until this test. A field whose only
 * purpose is to tell a grant this deployment ended from one that outlives it somewhere else is
 * worth nothing if it can only ever say one of the two.
 */
test("removing an app records the grant it did not withdraw as not withdrawn", async () => {
  const { broker, order } = brokerSpy({
    revoke: async () => false,
    deleteAuthConfig: async () => {},
  });
  const { store, database, auditStore } = await freshStore({ broker });
  await seedComposioGmail(database, store);

  await store.removeServer("gmail", "admin");

  expect(order).toEqual(["revoke:user_asker", "deleteAuthConfig"]);
  expect(
    await store.brokeredConnection({
      toolkit: "gmail",
      account: {
        holder: "person",
        userId: "user_asker",
        vendorUserId: "user_asker",
      },
    }),
  ).toBeNull();

  const disconnected = auditStore
    .recorded()
    .filter((event) => event.eventType === "mcp.account_disconnected");
  expect(disconnected).toHaveLength(1);
  expect(disconnected[0]?.payload).toMatchObject({
    actor: "admin",
    server: "gmail",
    owner: "user_asker",
    reason: "mcp_server_removed",
    vendorRevocationRequested: false,
  });
});

/**
 * The vendor's destructive label, carried out of the database to the screens that draw it.
 *
 * CRITERION. A `mcp_tools` row Composio labelled destructive reaches `listServers` as
 * `destructive: true`, and every tool in the list carries the field as a boolean.
 *
 * REASON. The column has been recorded since the brokered transport landed and reached nothing: the
 * store selected the row and then built a tool object without the field, so a delete read out
 * identically to any other write on every screen. The per-Bot grants screen already draws its danger
 * mark from `PluginTool.destructive`, which could only ever be false while the mapping was missing —
 * a mark that cannot turn on is worse than no mark, because it reads as an assurance. The second
 * assertion is the half a `true` alone would not hold: the field must be present on the ordinary read
 * beside it, not only on the row that happens to be dangerous.
 */
test("a destructive action says so in the list the screens read", async () => {
  const { store, database } = await freshStore();
  await seedComposioGmail(database, store);
  await database.insert(mcpTools).values({
    serverId: "gmail",
    name: "GMAIL_DELETE_MESSAGE",
    vendorName: "GMAIL_DELETE_MESSAGE",
    description: "Delete a message.",
    effect: "write",
    destructive: true,
  });

  const gmail = (await store.listServers()).find(
    (server) => server.id === "gmail",
  );

  const deletes = gmail?.tools.find(
    (tool) => tool.name === "GMAIL_DELETE_MESSAGE",
  );
  expect(deletes?.destructive).toBe(true);
  // Not only on the dangerous row: the reader asks every tool the same question, and an undefined
  // on the read beside it is a screen with nothing to draw rather than a screen drawing "safe".
  expect(gmail?.tools.map((tool) => typeof tool.destructive)).toEqual(
    gmail?.tools.map(() => "boolean"),
  );
});

/**
 * A database fault on the vault read, which is not a withdrawn credential.
 *
 * CRITERION. When the read that fetches a server's token fails on a query of this deployment's own,
 * the call is refused as a fault of ours — it is on the {@link isDeploymentFault} shelf, and it is
 * NOT a {@link PluginRefusedError}. Neither the sentence the caller gets nor the row the trail keeps
 * says a credential was withdrawn.
 *
 * REASON. `secretFor` used to tell a withdrawn credential from a broken query by looking for the
 * words "revoked" and "not found" inside `error.message`. drizzle reports every failure as a
 * `DrizzleQueryError` whose message opens `Failed query: select "encrypted_value", "revoked_at" from
 * "credentials" …` — so the column name matched the substring, and EVERY database fault on that read
 * became the one sentence that is certainly false about it: a Postgres that is down, an address that
 * names no database, a statement the server cancelled, each reported as an administrator having
 * taken the credential away.
 *
 * WHY THAT IS WORSE THAN A WRONG MESSAGE. The confident sentence is a {@link PluginRefusedError},
 * which is the one class this codebase relays VERBATIM. It reaches the model as the reason the tool
 * failed, a browser through the routes that pass a refusal straight out as a 400, and
 * `mcp_servers.last_error` for whoever operates the deployment — and the step it names, add the
 * credential again, is work against a credential that was never the problem while the real fault
 * goes unreported. Told apart by class, all three audiences get "that did not work" instead, which
 * is what a fault of ours is allowed to say.
 *
 * THE FAULT IS A REAL ONE, which is the point of the fixture. The production credential store
 * issues its production statement over an address that resolves to no database, so what arrives at
 * `secretFor` is drizzle's own wrapper around the driver's complaint. A hand-thrown `Error` would
 * prove nothing here: the message is exactly what the bug was reading, so the message has to come
 * from the same place production's does.
 */
describe("a vault read that fails on a query of this deployment's own", () => {
  const faultServerId = `vault-fault-${suite}`;
  const faultToolName = "do_something";
  const faultRef = `${faultServerId}/${faultToolName}`;
  const faultBotId = `agent_vault_fault_${suite}`;
  const faultActorId = "[email protected]";
  /** The sentence a withdrawn credential earns, and the one a query fault must never be given. */
  const WITHDRAWN = "An administrator has to add it again.";

  let faultCredentialId: string | null = null;

  /**
   * The suite's own address, pointed at a database that is not there.
   *
   * Derived rather than written out, so the fixture fails the way the deployment would on whatever
   * Postgres this run was given — including a scratch one — instead of only against localhost.
   */
  function unreachableVault() {
    const address = new URL(testDatabaseUrl());
    address.pathname = `/absent_vault_${suite}`;
    return address.toString();
  }

  /**
   * The vault on that address: `createCredentialStore`, unwrapped.
   *
   * Every other seam is the real one, because the fault under test is meant to arrive from the real
   * read. Its own policy rather than the file's mutable `policy`, so a describe that ran earlier and
   * left it somewhere else cannot decide whether this call gets as far as the vault.
   */
  const faultStore = createPluginStore({
    brokerProvider: "composio",
    database,
    auditStore: createAuditStore(database),
    credentials: createCredentialStore(
      createDatabase(unreachableVault(), TEST_POOL),
    ),
    encryptionKey: "x".repeat(44),
    policy: () => ({ mode: "enforce", deny: [], allow: ["true"] }),
    // Loud rather than silent: the token is read before the vendor is dialled, so a call that gets
    // this far means the vault read did not fail at all and the test is asserting nothing.
    callVendor: async () => {
      throw new Error(
        "the vendor must not be reached when the vault read fails",
      );
    },
  });

  beforeAll(async () => {
    await database
      .insert(agents)
      .values({
        id: faultBotId,
        name: faultBotId,
        type: "remote_ag_ui",
        configuration: {},
      })
      .onConflictDoNothing();

    // A real vault row, on the real database. What breaks is the READ, not the pointer: the server
    // is configured exactly as a working one is, which is what makes the fault a fault rather than
    // a missing credential wearing one's clothes.
    const [credential] = await database
      .insert(credentialRows)
      .values({
        kind: "mcp",
        provider: faultServerId,
        keyId: `mcp-${faultServerId}`,
        /*
         * A placeholder rather than a real envelope: the read is what fails, so nothing here is
         * ever decrypted, and an encrypted value would assert a step this test never reaches.
         */
        encryptedValue: "{}",
        metadata: {},
      })
      .returning({ id: credentialRows.id });
    if (!credential) throw new Error("the fixture credential was not stored");
    faultCredentialId = credential.id;

    /*
     * Custom provenance and a suite-scoped id, so `accessFor` resolves it to the deployment-token
     * path — which is the branch of `connectionTokenFor` that reads the vault for a server's own
     * token, and the one whose refusal names an administrator.
     */
    await database.insert(mcpServers).values({
      id: faultServerId,
      title: "a server whose vault is unreachable",
      vendor: "test",
      url: "https://example.invalid/mcp",
      credentialId: credential.id,
      provenance: "custom",
    });
    await database.insert(mcpTools).values({
      serverId: faultServerId,
      name: faultToolName,
      vendorName: faultToolName,
      description: "Do something.",
    });
    await faultStore.grant("mcp", faultRef, faultBotId, "[email protected]");
  });

  afterAll(async () => {
    await database
      .delete(pluginGrants)
      .where(
        and(
          eq(pluginGrants.ref, faultRef),
          eq(pluginGrants.agentId, faultBotId),
        ),
      );
    // The tools go with the server row, which cascades; both ids carry this run's suffix, so
    // neither can be a row the deployment configured.
    await database.delete(mcpServers).where(eq(mcpServers.id, faultServerId));
    await database.delete(agents).where(eq(agents.id, faultBotId));
    if (faultCredentialId) {
      await database
        .delete(credentialRows)
        .where(eq(credentialRows.id, faultCredentialId));
    }
  });

  test("is refused as this deployment's own fault, never as a withdrawn credential", async () => {
    const thrown = await faultStore
      .callTool({
        ref: faultRef,
        args: {},
        botId: faultBotId,
        actorId: faultActorId,
      })
      .then(
        () => null,
        (error: unknown) => error,
      );

    /*
     * The class is the assertion, not the wording. `PluginRefusedError` is what the relays key on:
     * `grantedTools` hands its message to the model, and four routes hand it to a browser as a 400.
     */
    expect(thrown).not.toBeInstanceOf(PluginRefusedError);
    expect(isDeploymentFault(thrown)).toBe(true);
    expect(
      thrown instanceof Error ? thrown.message : String(thrown),
    ).not.toContain(WITHDRAWN);
  });

  test("does not write a withdrawn credential into the trail a failed call leaves", async () => {
    await faultStore
      .callTool({
        ref: faultRef,
        args: {},
        botId: faultBotId,
        actorId: faultActorId,
      })
      .catch(() => {});

    const failures = (
      await auditRowsFor(faultRef, faultBotId, faultActorId)
    ).filter((row) => row.eventType === "mcp.call_failed");
    expect(failures.length).toBeGreaterThan(0);
    const written = JSON.stringify(failures);
    // The false accusation, which is what an operator would act on.
    expect(written).not.toContain(WITHDRAWN);
    expect(written).not.toContain("no longer holds");
    /*
     * And the true half is still recorded, without the statement or anything bound to it — the
     * driver's own complaint is what `withoutStatement` keeps, and a credential id is what it drops.
     */
    expect(written).toContain(`absent_vault_${suite}`);
    expect(written).not.toContain("Failed query:");
    expect(written).not.toContain(faultCredentialId ?? "<none>");
  });
});