@@ -87,10 +87,9 @@ export async function resolveBatchRunOpsWriter(
     shards?: ReadonlyArray<{ key: string; writer: RunOpsPrismaClient }>;
   }
 ): Promise<RunOpsPrismaClient> {
-  // A gen-2 batch names its own shard in its id, so route by that and never probe. The
-  // probe below is binary — NEW, else assume LEGACY — so a gen-2 batch would fall through
-  // to a store that holds no such row, and the completion update would throw before the
-  // batch waitpoint could complete, leaving the parent run blocked with nothing logged.
+  // A gen-2 batch names its shard in its id. The probe below is binary, so without this a gen-2
+  // batch resolves to a store holding no such row and the update throws before the batch waitpoint
+  // completes, leaving the parent blocked with nothing logged.
   const shardKey = resolveShard(batchId);
   if (shardKey !== "new" && shardKey !== "legacy") {
     const shard = deps.shards?.find((s) => s.key === shardKey);
 
@@ -8,9 +8,8 @@ import {
 import { batchIdForMintKind } from "./mintBatchFriendlyId.server";
 import { resolveRunMintTarget } from "./resolveRunMintTarget.server";
 
-// The gate is off when RUN_OPS_SHARDS is unset OR runOpsMintShardSet is empty. Either way
-// resolveMintShard answers "new", so no shard char reaches a MintTarget. Every assertion
-// below is "the id is what it was before gen-2 existed".
+// The gate is off when RUN_OPS_SHARDS is unset or runOpsMintShardSet is empty; either way
+// resolveMintShard answers "new". Every assertion is "the id is what it was before gen-2".
 const offShard = vi.fn().mockResolvedValue("new" as const);
 const environment = { organizationId: "org_1", id: "env_1", orgFeatureFlags: {} };
 
@@ -42,8 +41,8 @@ describe("gate off — run mint paths", () => {
   });
 
   it("a child of a gen-1 parent keeps the caller's region char", async () => {
-    // The pre-split code passed the region on BOTH arms, so a child run stamped the
-    // requested region. Dropping it on the inherited arm would silently stamp the default.
+    // The pre-split code passed the region on both arms; dropping it on the inherited arm would
+    // silently stamp the default.
     const target = await resolveRunMintTarget({
       environment,
       parentRunFriendlyId: `run_${"a".repeat(24)}01`,
 
@@ -14,11 +14,8 @@ const defaultDeps: RunMintDeps = {
 };
 
 /**
- * Where one run mints. Two stages, and the second runs only for a ROOT run already on the
- * run-ops path: a child inherits its parent's shard by id-shape, so a tree never splits.
- *
- * Every run-mint path routes through here. The branch used to be duplicated per service,
- * and one copy had already drifted into minting gen-1 for a gen-2 parent.
+ * Where one run mints. The second stage runs only for a root run already on the run-ops path: a
+ * child inherits its parent's shard by id-shape, so a tree never splits across shards.
  */
 export async function resolveRunMintTarget(args: {
   environment: { organizationId: string; id: string; orgFeatureFlags?: unknown };
@@ -27,8 +24,8 @@ export async function resolveRunMintTarget(args: {
   deps?: Partial<RunMintDeps>;
 }): Promise<MintTarget> {
   if (args.parentRunFriendlyId) {
-    // The region still travels: it takes index 24 for an inherited gen-1 parent, exactly as
-    // it did before this branch. A gen-2 parent's shardChar outranks it.
+    // The region still travels: it takes index 24 for an inherited gen-1 parent, and a gen-2
+    // parent's shardChar outranks it.
     return { ...resolveInheritedMintKind(args.parentRunFriendlyId), region: args.region };
   }
 
@@ -49,8 +46,7 @@ export async function resolveRunMintTarget(args: {
     orgFeatureFlags: args.environment.orgFeatureFlags,
   });
 
-  // A reserved key means gen-1, which is the state of every deployment that has configured
-  // no shard. Only a single-char key names a gen-2 shard.
+  // A reserved key means gen-1, the state of every deployment with no shard configured.
   return shard === "new" || shard === "legacy"
     ? { kind, region: args.region }
     : { kind, shardChar: shard, region: args.region };
 
@@ -490,15 +490,11 @@ describe("runEngineHandlers batch completion", () => {
 });
 
 describe("runEngineHandlers batch residency routing", () => {
-  // A gen-2 batch lives on its own shard. The binary probe below it looks only on the
-  // NEW store and then assumes LEGACY, so without a shard arm the completion update runs
-  // on a database that has no such row: Prisma throws "no record was found for an
-  // update", the callback dies before tryCompleteBatch, the BATCH waitpoint stays
-  // PENDING and the parent run waits forever with nothing logged as a hang.
-  // Real clients on two real databases, so the assertion is where the rows landed rather
-  // than which object came back. The shard is prisma14 and BOTH gen-1 slots are prisma17:
-  // every wrong resolution therefore lands on a database that holds no such batch, which is
-  // the production failure this arm exists to prevent.
+  // See resolveBatchRunOpsWriter: without a shard arm a gen-2 batch resolves to a store holding
+  // no such row, and the parent waits forever with nothing logged.
+  // Real databases, so the assertion is where the rows landed rather than which object came back.
+  // The shard is prisma14 and both gen-1 slots are prisma17, so every wrong resolution lands on a
+  // database holding no such batch.
   heteroPostgresTest(
     "a gen-2 batch commits on its shard, and the gen-1 store stays empty",
     async ({ prisma14, prisma17 }) => {
@@ -541,26 +537,23 @@ describe("runEngineHandlers batch residency routing", () => {
         }
       );
 
-      // Committed on the shard, and the callback survived to run — the hang was the callback
-      // dying on "no record was found for an update" before it could reach this.
+      // The hang was the callback dying on "no record was found for an update" before this.
       const onShard = await prisma14.batchTaskRun.findFirstOrThrow({ where: { id: gen2BatchId } });
       expect(onShard.status).toBe("PARTIAL_FAILED");
       expect(
         await prisma14.batchTaskRunError.findMany({ where: { batchTaskRunId: gen2BatchId } })
       ).toHaveLength(1);
       expect(completed).toBe(gen2BatchId);
 
-      // Nothing for this batch reached the gen-1 database.
       expect(await prisma17.batchTaskRun.findMany({ where: { id: gen2BatchId } })).toHaveLength(0);
       expect(
         await prisma17.batchTaskRunError.findMany({ where: { batchTaskRunId: gen2BatchId } })
       ).toHaveLength(0);
     }
   );
 
-  // Kept on a throwing double deliberately: "the NEW store is never probed" is an assertion
-  // about a call that must not happen, and only a client that throws when touched can make
-  // that observable. A real client would simply return null and the test would still pass.
+  // A throwing double deliberately: this asserts a call that must NOT happen, and a real client
+  // would return null and pass either way.
   it("a gen-2 batch id never probes the gen-1 store", async () => {
     const shardWriter = {} as never;
 
 
@@ -1822,13 +1822,6 @@ export class RunEngine {
     tags?: string[];
     /** Standalone-token residency (no owning run) from the env mint kind; ignored when `runId` is set. */
     standaloneResidency?: "NEW" | "LEGACY";
-    /**
-     * The environment's mint shard, for a STANDALONE token with no owning run. It selects the
-     * shard the token's id is stamped for. When it names a gen-2 shard the implementation must
-     * IGNORE `standaloneResidency`: a residency hint outranks the id shape in the router and
-     * can only name a gen-1 store, so honouring it would land the row there while its
-     * completion routes to the shard. Only a Postgres implementation reads this.
-     */
     standaloneShardKey?: ShardKey;
   }): Promise<{ waitpoint: Waitpoint; isCached: boolean }> {
     return this.waitpointSystem.createManualWaitpoint({
@@ -1866,12 +1859,8 @@ export class RunEngine {
       const waitpoint = await this.runStore.createWaitpoint(
         {
           data: {
-            // Stamped from the BATCH, not the blocked run: this create passes only
-            // completedByBatchId, so the routing store resolves the owner from the batch and
-            // validates the stamp against the BATCH's shard. On the normal path the two are
-            // the same char anyway, because the batch inherited this run's shard. They differ
-            // only if a batch ever blocks a run from another shard -- and then this is the
-            // stamp that matches the owner the router actually checks.
+            // Stamped from the batch, not the blocked run: this create passes only
+            // completedByBatchId, so that is the owner the router validates the stamp against.
             ...mintWaitpointIdFor(batchId),
             type: "BATCH",
             idempotencyKey: batchId,
 
@@ -198,13 +198,6 @@ export class WaitpointSystem {
     // the token lands on the run-ops DB (NEW) in a fully-minted-new deployment instead of defaulting
     // to LEGACY by its cuid id-shape. Ignored when `runId` is set (co-location wins).
     standaloneResidency?: "NEW" | "LEGACY";
-    /**
-     * The environment's mint shard, for a STANDALONE token with no owning run. It selects the
-     * shard the token's id is stamped for. When it names a gen-2 shard the implementation must
-     * IGNORE `standaloneResidency`: a residency hint outranks the id shape in the router and
-     * can only name a gen-1 store, so honouring it would land the row there while its
-     * completion routes to the shard. Only a Postgres implementation reads this.
-     */
     standaloneShardKey?: ShardKey;
   }): Promise<{ waitpoint: Waitpoint; isCached: boolean }> {
     const result = await this.coordinator.createManualWaitpoint({
 
@@ -239,8 +239,7 @@ export class LegacyPostgresWaitpointCoordinator implements WaitpointCoordinator
     // The two `nanoid(24)` calls below are deliberately separate and produce DIFFERENT values:
     // the upsert `where` key must not match the `create` key, or a guaranteed-miss upsert becomes
     // a possible update. Do not hoist either to a shared constant.
-    // The id is stamped for the anchor run's shard, so the waitpoint's own row is routable
-    // and its completion write needs no probe. A gen-1 or legacy anchor keeps a cuid.
+    // Stamped for the anchor run's shard, so the row is routable and completion needs no probe.
     const upsertArgs = {
       where: {
         environmentId_idempotencyKey: {
@@ -282,8 +281,7 @@ export class LegacyPostgresWaitpointCoordinator implements WaitpointCoordinator
     // owner, blocked later by whichever run waits on it (possibly cross-DB, resolved by the
     // run-co-resident block edge + completion fan-out). With no owner it reads the env mint kind via
     // `standaloneResidency` so a minted-new env keeps its tokens on NEW; unset, it routes by id-shape. No tx here.
-    // A gen-2 standalone token carries its shard in its own id, so it passes NO hint and lets
-    // the id route: `residency` outranks the id shape and can only name a gen-1 store.
+    // A gen-2 standalone token carries its shard in its own id, so it passes no residency hint.
     const standaloneShard = runId ? undefined : standaloneShardKey;
     const isGen2Standalone =
       standaloneShard !== undefined && standaloneShard !== "new" && standaloneShard !== "legacy";
 
@@ -25,10 +25,7 @@ export type WaitpointCoordinator = {
   mintAssociatedWaitpointData(params: {
     projectId: string;
     environmentId: string;
-    /**
-     * The run this waitpoint belongs to. Its id names the shard the row must land on, and
-     * this write bypasses the routing store's stamp check, so an unstamped id is silent here.
-     */
+    /** Names the shard the row lands on. This write skips the router's stamp check. */
     anchorRunId: string;
   }): AssociatedWaitpointData;
   createAssociatedWaitpoint(params: {
@@ -117,13 +114,9 @@ export type CreateDateTimeWaitpointParams = {
   /**
    * When set, the waitpoint co-locates with this run's DB and the dedup probe targets it.
    *
-   * Optional in the type, but every production caller supplies it: the only entry point is the
-   * wait.duration route, which is keyed on a run friendly id. There is deliberately NO standalone
-   * arm here — unlike `createManualWaitpoint`, this type carries no `standaloneShardKey`, so a
-   * caller that omits `runId` on a gen-2 environment mints a cuid and routes by residency, landing
-   * the row on a gen-1 store while the run that waits on it lives on a shard. Nothing would fail at
-   * write time. Before adding a caller that omits `runId`, give this type a shard hint the way the
-   * MANUAL path has one.
+   * Every production caller supplies it, and there is deliberately no standalone arm. Omitting it
+   * on a gen-2 environment mints a cuid and lands the row on a gen-1 store, silently. A standalone
+   * caller needs a shard hint here first, as `createManualWaitpointParams` has.
    */
   runId?: string;
   projectId: string;
@@ -147,11 +140,8 @@ export type CreateManualWaitpointParams = {
    */
   standaloneResidency?: "NEW" | "LEGACY";
   /**
-   * The environment's mint shard, for a STANDALONE token with no owning run. It selects the
-   * shard the token's id is stamped for. When it names a gen-2 shard the implementation must
-   * IGNORE `standaloneResidency`: a residency hint outranks the id shape in the router and
-   * can only name a gen-1 store, so honouring it would land the row there while its
-   * completion routes to the shard. Only a Postgres implementation reads this.
+   * The environment's mint shard, for a standalone token with no owning run. When it names a gen-2
+   * shard the implementation must ignore `standaloneResidency`, which can only name a gen-1 store.
    */
   standaloneShardKey?: ShardKey;
 };
 
@@ -21,13 +21,8 @@ function count(source: string, pattern: RegExp): number {
   return (source.match(pattern) ?? []).length;
 }
 
-// Every production `.ts` under a root, walked rather than listed: a mint added in a new
-// file, or moved back into `systems/` where these all lived until the coordinator seam was
-// extracted, has to be visible here or the census is decorative.
-//
-// Test-support trees are excluded deliberately. A helper that writes a row through raw
-// Prisma never reaches the routing store, so it cannot misroute; requiring it to be
-// catalogued would fill the census with sites that carry no risk.
+// Walked rather than listed, so a mint added in a new file is still visible. Test-support trees
+// are excluded: a helper writing through raw Prisma never reaches the routing store.
 const TEST_SUPPORT_DIRS = new Set(["tests", "__tests__", "fixtures"]);
 
 function walk(relativeRoot: string): string[] {
@@ -76,9 +71,7 @@ describe("waitpoint mint census — the catalog matches the source", () => {
     expect(SCANNED).toContain("internal-packages/run-engine/src/engine/systems/waitpointSystem.ts");
   });
 
-  // Per EXPRESSION, not per file: this fails for a fifth mint added inside an
-  // already-catalogued file, AND for a swapped anchor — mintWaitpointIdFor(undefined) in
-  // place of the run id — which a bare call-count would wave through.
+  // Per expression, not per file, so a swapped anchor fails too and not just a new site.
   it.each(SCANNED)("%s has exactly the mint expressions the catalog claims", (file) => {
     const source = read(file);
     const expected = expectedMints(file);
@@ -90,20 +83,17 @@ describe("waitpoint mint census — the catalog matches the source", () => {
       });
     }
 
-    // No mint in the file beyond the ones the catalog accounts for.
     const accounted = [...expected.values()].reduce((a, b) => a + b, 0);
     expect(count(source, MINT_CALL)).toBe(accounted);
   });
 
   it.each(SCANNED)("%s mints no waitpoint id with the un-stamped helper", (file) => {
-    // The regex matches tokens inside comments too — deliberate. Any textual addition
-    // forces the census to be reconciled, so a new site cannot land unnoticed.
+    // Matches inside comments too, deliberately: any textual addition forces a reconcile.
     expect(count(read(file), UNSTAMPED_MINT)).toBe(0);
   });
 
   it.each(SCANNED)("%s writes a waitpoint row only if it is catalogued", (file) => {
-    // A create with NO id is the worst case: Prisma's @default(cuid()) then mints a cuid on
-    // a gen-2 shard after the write, which no stamp check can see.
+    // A create with no id is the worst case: @default(cuid()) then mints one after the write.
     const writes = count(read(file), WAITPOINT_WRITE);
     const catalogued = WAITPOINT_MINT_SITES.some((s) => s.site === file);
     expect(writes === 0 || catalogued).toBe(true);
 
@@ -1,26 +1,20 @@
-// If you add a site that creates a Postgres `Waitpoint` row, add a matching entry here or
-// `waitpointMint.proof.test.ts` fails. Entries are one per site, anchored by symbol name,
-// never by line number.
+// Add a site that creates a Postgres `Waitpoint` row and add an entry here, or
+// `waitpointMint.proof.test.ts` fails. One entry per site, anchored by symbol, never by line.
 //
-// Why: a site that mints a cuid for a gen-2 run writes a row the completion path cannot
-// find. Three of the sites below fail loudly, because the routing store refuses an
-// unstamped id on a gen-2 shard. The RUN row written through `createRun` does NOT — that
-// write happens inside the run store, which has no such check — so a missed site there
-// strands a parent run with no error.
+// A site that mints a cuid for a gen-2 run writes a row the completion path cannot find. Most
+// fail loudly, because the router refuses an unstamped id on a gen-2 shard. The RUN row written
+// through `createRun` does not: that write is inside the run store, which has no such check.
 //
-// PURE module — no engine import, no env, no Prisma.
+// Pure module: no engine import, no env, no Prisma.
 export type WaitpointMintSite = {
   id: string;
   type: "DATETIME" | "MANUAL" | "RUN" | "BATCH";
-  /** Repo-relative source path. */
   site: string;
   /** Enclosing method or symbol name — NEVER a line number. */
   symbol: string;
   /**
-   * The exact mint expressions this site contains, verbatim. The proof test counts each one
-   * per file, so both a new mint inside an already-catalogued file and a swapped anchor
-   * (`mintWaitpointIdFor(undefined)` in place of the run id) fail until reconciled here.
-   * Empty for a site that writes a row from an id minted elsewhere.
+   * Mint expressions this site contains, verbatim, counted per file, so a new mint and a swapped
+   * anchor both fail until reconciled. Empty for a site writing an id minted elsewhere.
    */
   mints: readonly string[];
 };