refactor: use the $transaction helper in removeTeamMember + document the rule

Author: nicktrn

apps/webapp/CLAUDE.md

@@ -125,6 +125,12 @@ The `triggerTask.server.ts` service is the **highest-throughput code path** in t
 
 - **Always use `findFirst` instead of `findUnique`.** Prisma's `findUnique` has an implicit DataLoader that batches concurrent calls into a single `IN` query. This batching cannot be disabled and has active bugs even in Prisma 6.x: uppercase UUIDs returning null (#25484, confirmed 6.4.1), composite key SQL correctness issues (#22202), and 5-10x worse performance than manual DataLoader (#6573, open since 2021). `findFirst` is never batched and avoids this entire class of issues.
 
+## Transactions
+
+- **Always use the `$transaction` helper from `~/db.server`, never `prisma.$transaction` (or `$replica.$transaction`) directly.** The helper wraps the raw call with tracing (an OTEL span + an `isolation_level` attribute) and boundary logging for infrastructure errors (e.g. `PrismaClientInitializationError`) that the raw client swallows. Signature: `$transaction(prisma, name?, async (tx) => { ... }, options?)`.
+- Pass the isolation level via options as a string: `{ isolationLevel: "Serializable" }`. Reach for `Serializable` when a read-then-write must be atomic against concurrent transactions (e.g. a count-then-delete invariant); the loser of a race fails and can retry, which is the right trade for rare, correctness-critical paths.
+- The helper returns `R | undefined` — guard the result (`if (!result) throw ...`) when callers need a definite value.
+
 ## React Patterns
 
 - Only use `useCallback`/`useMemo` for context provider values, expensive derived data that is a dependency elsewhere, or stable refs required by a dependency array. Don't wrap ordinary event handlers or trivial computations.

apps/webapp/app/models/member.server.ts

@@ -1,5 +1,5 @@
 import type { Organization, OrgMember, Project } from "@trigger.dev/database";
-import { Prisma as PrismaNamespace, type Prisma, prisma } from "~/db.server";
+import { Prisma as PrismaNamespace, type Prisma, prisma, $transaction } from "~/db.server";
 import { createEnvironment } from "./organization.server";
 import { customAlphabet } from "nanoid";
 import { logger } from "~/services/logger.server";
@@ -96,7 +96,9 @@ export async function removeTeamMember({
   // interleave with a concurrent removal, or two requests could each pass the
   // count and leave the org with zero members. Guard lives here (not per-caller)
   // so the dashboard and the management API both get it.
-  return prisma.$transaction(
+  const removed = await $transaction(
+    prisma,
+    "removeTeamMember",
     async (tx) => {
       // Scope the target to this org. A member id is a globally unique key, so
       // deleting by id alone would remove members of other orgs; bind it to the
@@ -122,8 +124,14 @@ export async function removeTeamMember({
 
       return member;
     },
-    { isolationLevel: PrismaNamespace.TransactionIsolationLevel.Serializable }
+    { isolationLevel: "Serializable" }
   );
+
+  if (!removed) {
+    throw new Error("removeTeamMember transaction did not return a member");
+  }
+
+  return removed;
 }
 
 export async function inviteMembers({