From 073d655260b48f4e123aaeb3576faa175412fda2 Mon Sep 17 00:00:00 2001
From: Dan Sutton <dansutton@trigger.dev>
Date: Fri, 21 Aug 2026 14:09:25 +0100
Subject: [PATCH] refactor(run-engine): restore dropped residency comment
 clauses

---
 .../legacyPostgresCoordinator.ts              | 27 ++++++++++---------
 .../src/engine/waitpointCoordinator/types.ts  |  5 ++--
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/internal-packages/run-engine/src/engine/waitpointCoordinator/legacyPostgresCoordinator.ts b/internal-packages/run-engine/src/engine/waitpointCoordinator/legacyPostgresCoordinator.ts
index 97dc80554..d1e48fa4f 100644
--- a/internal-packages/run-engine/src/engine/waitpointCoordinator/legacyPostgresCoordinator.ts
+++ b/internal-packages/run-engine/src/engine/waitpointCoordinator/legacyPostgresCoordinator.ts
@@ -190,13 +190,14 @@ export class LegacyPostgresWaitpointCoordinator implements WaitpointCoordinator
     idempotencyKey,
     idempotencyKeyExpiresAt,
   }: CreateDateTimeWaitpointParams): Promise<CreateWaitpointResult> {
-    // Co-location invariant: a DATETIME wait waitpoint lives on the same run-ops DB as the run
-    // that blocks on it. The minted waitpoint id is always a cuid, so without `coLocateWithRunId`
-    // the upsert would always route to LEGACY and a run-ops run on NEW would hang. The
-    // (env,idempotencyKey) dedup is within the owning run/tree, so the dedup probe + rotation
-    // target the SAME store. With no run id the lookup falls back to a cross-DB NEW-then-LEGACY
-    // scan and the upsert routes by id-shape. Always routed through the run store (never a caller
-    // tx) so it can never bypass residency onto the wrong DB.
+    // Co-location invariant: a DATETIME wait waitpoint lives on the same run-ops DB as the run that
+    // blocks on it (so the block edge's local `Waitpoint` join resolves and completion/resume stay
+    // local). The minted waitpoint id is always a cuid, so without `coLocateWithRunId` the upsert
+    // would always route to LEGACY and a run-ops run on NEW would hang. The (env,idempotencyKey) dedup
+    // is within the owning run/tree (co-resident on one DB), so the dedup probe + rotation target the
+    // SAME store. With no run id (a standalone token has no owning run yet) the lookup falls back to
+    // a cross-DB NEW-then-LEGACY scan and the upsert routes by id-shape. Always routed through the
+    // run store (never a caller tx) so it can never bypass residency onto the wrong DB.
     const colocate = runId ? { coLocateWithRunId: runId } : undefined;
     const existingWaitpoint = idempotencyKey
       ? await this.runStore.findWaitpoint(
@@ -272,12 +273,12 @@ export class LegacyPostgresWaitpointCoordinator implements WaitpointCoordinator
     tags,
     standaloneResidency,
   }: CreateManualWaitpointParams): Promise<CreateWaitpointResult> {
-    // Co-location invariant (see createDateTimeWaitpoint): when a `runId` is supplied the
-    // waitpoint co-locates with that run's DB and the (env,idempotencyKey) dedup is per-run. A
-    // standalone token passes no run id — it is created without an 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.
+    // Co-location invariant (see createDateTimeWaitpoint): when a `runId` is supplied the waitpoint
+    // co-locates with that run's DB and the (env,idempotencyKey) dedup is per-run (co-resident). A
+    // standalone token (api.v1.waitpoints.tokens.ts) passes no run id — it is created without an
+    // 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.
     const colocate = runId
       ? { coLocateWithRunId: runId }
       : standaloneResidency
diff --git a/internal-packages/run-engine/src/engine/waitpointCoordinator/types.ts b/internal-packages/run-engine/src/engine/waitpointCoordinator/types.ts
index 36b0ea4b3..9b89a065c 100644
--- a/internal-packages/run-engine/src/engine/waitpointCoordinator/types.ts
+++ b/internal-packages/run-engine/src/engine/waitpointCoordinator/types.ts
@@ -126,9 +126,8 @@ export type CreateManualWaitpointParams = {
   timeout?: Date;
   tags?: string[];
   /**
-   * For a STANDALONE token (no owning `runId`): the residency the env's mint kind resolves
-   * to. Ignored when `runId` is set, because co-location wins. Only a Postgres
-   * implementation reads this.
+   * See the `standaloneResidency` param doc on `WaitpointSystem.createManualWaitpoint` for the
+   * full rationale. Only a Postgres implementation reads this.
    */
   standaloneResidency?: "NEW" | "LEGACY";
 };