docs(mollifier): strip internal planning labels from comments

Remove plan-tracking shorthand (Phase N, Q#, B6a) from mollifier comments and reword to plain English. Comment/test-only; no behaviour change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: d-cs

apps/webapp/app/runEngine/services/triggerTask.server.ts

@@ -374,13 +374,13 @@ export class RunEngineTriggerTaskService {
 
             const payloadPacket = await this.payloadProcessor.process(triggerRequest);
 
-            // Phase 1 dual-write: if the org has the mollifier feature flag
+            // Dual-write: if the org has the mollifier feature flag
             // enabled and the per-env trip evaluator says divert, write the
             // canonical replay payload to the buffer AND continue through
             // engine.trigger as normal. The buffer entry is an audit/preview
             // copy; the drainer's no-op handler consumes it to prove the
-            // dequeue mechanism works. Phase 2 will replace engine.trigger
-            // (below) with a synthesised 200 response and rely on the
+            // dequeue mechanism works. A later change replaces engine.trigger
+            // (below) with a synthesised 200 response and relies on the
             // drainer to perform the Postgres write via replay.
             if (mollifierOutcome?.action === "mollify") {
               const buffer = this.getMollifierBuffer();
@@ -430,8 +430,8 @@ export class RunEngineTriggerTaskService {
                   });
                 } catch (err) {
                   // Fail-open: buffer write must never block the customer's
-                  // trigger. engine.trigger below is the primary write path
-                  // in Phase 1 — the customer still gets a valid run.
+                  // trigger. engine.trigger below is still the primary write
+                  // path here — the customer still gets a valid run.
                   logger.error("mollifier.buffer_accept_failed", {
                     runId: runFriendlyId,
                     envId: environment.id,

apps/webapp/app/v3/mollifier/bufferedTriggerPayload.server.ts

@@ -2,17 +2,17 @@ import type { TriggerTaskRequestBody } from "@trigger.dev/core/v3";
 import type { TriggerTaskServiceOptions } from "~/v3/services/triggerTask.server";
 
 // Canonical payload shape written to the mollifier buffer when the gate
-// decides to mollify a trigger. Phase 1 ALSO calls engine.trigger directly
-// (dual-write) so this is currently an audit/preview record. Phase 2 will
-// make the buffer the primary write path: the drainer's handler will read
-// this payload and replay it through engine.trigger to create the run in
-// Postgres, and read-fallback endpoints will synthesise a Run view from it
-// while it is still QUEUED.
+// decides to mollify a trigger. At this stage the call site ALSO calls
+// engine.trigger directly (dual-write), so this is currently an
+// audit/preview record. A later change makes the buffer the primary write
+// path: the drainer's handler reads this payload and replays it through
+// engine.trigger to create the run in Postgres, and read-fallback
+// endpoints synthesise a Run view from it while it is still QUEUED.
 //
-// CONTRACT: this shape must contain everything needed for Phase 2's
-// drainer-replay to reconstruct an equivalent engine.trigger call. Phase 1
-// emits it to logs; Phase 2 will serialise it into Redis and rebuild it on
-// the drain side. Keep it serialisable — no functions, no class instances.
+// CONTRACT: this shape must contain everything the drainer-replay needs to
+// reconstruct an equivalent engine.trigger call. Today it is emitted to
+// logs; later it is serialised into Redis and rebuilt on the drain side.
+// Keep it serialisable — no functions, no class instances.
 export type BufferedTriggerPayload = {
   runFriendlyId: string;
 

apps/webapp/app/v3/mollifier/mollifierDrainer.server.ts

@@ -68,11 +68,11 @@ function initializeMollifierDrainer(): MollifierDrainer<BufferedTriggerPayload>
     maxAttempts: env.TRIGGER_MOLLIFIER_DRAIN_MAX_ATTEMPTS,
   });
 
-  // Phase 1 handler: no-op ack. The trigger has ALREADY been written to
-  // Postgres via engine.trigger (dual-write at the call site). Popping +
-  // acking here proves the dequeue mechanism works end-to-end without
-  // duplicating the work. Phase 2 will replace this with an engine.trigger
-  // replay that performs the actual Postgres write.
+  // No-op ack handler: the trigger has ALREADY been written to Postgres
+  // via engine.trigger (dual-write at the call site). Popping + acking
+  // here proves the dequeue mechanism works end-to-end without duplicating
+  // the work. A later change replaces this with an engine.trigger replay
+  // that performs the actual Postgres write.
   const drainer = new MollifierDrainer<BufferedTriggerPayload>({
     buffer,
     handler: async (input) => {

apps/webapp/app/v3/mollifier/mollifierGate.server.ts

@@ -73,7 +73,7 @@ export type GateDependencies = {
 };
 
 // `options` is a thunk so env reads happen per-evaluation, not at module load.
-// Don't "simplify" to a plain object — Phase 2 dynamic config relies on the
+// Don't "simplify" to a plain object — dynamic config relies on the
 // gate observing whichever env values are live at trigger time.
 const defaultEvaluator = createRealTripEvaluator({
   getBuffer: () => getMollifierBuffer(),

apps/webapp/app/v3/mollifier/mollifierTripEvaluator.server.ts

@@ -35,8 +35,8 @@ export function createRealTripEvaluator(deps: CreateRealTripEvaluatorDeps): Trip
     } catch (err) {
       // Deliberate: no error counter here. Shadow mode means a silent miss is
       // harmless — fail-open is the safe direction. The error log + Sentry
-      // capture is sufficient operability for Phase 1. Revisit in Phase 2
-      // when buffer writes are the primary path and a missed evaluation has cost.
+      // capture is sufficient operability while this runs in shadow mode. Revisit
+      // once buffer writes are the primary path and a missed evaluation has cost.
       logger.error("mollifier trip evaluator: fail-open on error", {
         envId: inputs.envId,
         err: err instanceof Error ? err.message : String(err),

apps/webapp/app/v3/mollifierDrainerWorker.server.ts

@@ -97,8 +97,8 @@ export function initMollifierDrainerWorker(
     // Deterministic misconfig (shutdown-timeout vs GRACEFUL_SHUTDOWN_TIMEOUT,
     // missing buffer client) is a deploy-time mistake the operator must
     // see immediately — rethrow so the process crashes, health checks
-    // fail, and the orchestrator rolls the deploy back. Phase 1 is
-    // monitoring-only and the silent-fallback was tempting, but Phase 2/3
+    // fail, and the orchestrator rolls the deploy back. The drainer is currently
+    // monitoring-only and the silent-fallback was tempting, but later phases
     // make the drainer the source of truth for diverted triggers, where a
     // silently-disabled drainer means data loss. Better to fail loud now
     // than retrofit later.

apps/webapp/test/engine/triggerTask.test.ts

@@ -1404,7 +1404,7 @@ describe("RunEngineTriggerTaskService", () => {
       // SCENARIO: dual-write where buffer.accept succeeds but engine.trigger
       // throws. The throw propagates to the caller (correct: customer sees
       // the same 4xx as today), and the buffer entry remains as an "orphan"
-      // — Phase 1's no-op drainer will pop+ack it on its next poll, so the
+      // — the no-op drainer will pop+ack it on its next poll, so the
       // orphan is bounded (~drainer pollIntervalMs) but observable in the
       // audit trail (mollifier.buffered with no matching TaskRun).
       //
@@ -1416,11 +1416,11 @@ describe("RunEngineTriggerTaskService", () => {
       //   - RunOneTimeUseTokenError (Prisma P2002 on oneTimeUseToken).
       //   - Transient Prisma errors (FK constraint, connection drop, etc.).
       //
-      // Why we don't "fix" this race in Phase 1:
+      // Why we don't "fix" this race now:
       //   The customer correctly gets the error. State eventually converges
       //   (drainer pops the orphan). The audit-trail explicitly surfaces
       //   "buffered without TaskRun" entries to operators. A real fix is
-      //   Phase 2's responsibility once the buffer becomes the primary write
+      //   a later change's responsibility once the buffer becomes the primary write
       //   — at that point we add the mollifier-specific idempotency index.
       //
       // This test pins the current ordering: buffer.accept fires synchronously
@@ -1491,7 +1491,7 @@ describe("RunEngineTriggerTaskService", () => {
 
       // The buffer write happened BEFORE engine.trigger threw. The orphan
       // remains; the audit-trail will surface it (mollifier.buffered with
-      // no matching TaskRun row). Phase 1's no-op drainer cleans it up.
+      // no matching TaskRun row). The no-op drainer cleans it up.
       expect(buffer.accepted).toHaveLength(1);
       const orphanPayload = JSON.parse(buffer.accepted[0]!.payload);
       expect(orphanPayload.taskId).toBe(taskIdentifier);
@@ -1617,22 +1617,22 @@ describe("RunEngineTriggerTaskService", () => {
       // service correctly returns the existing run id to the customer, but
       // the buffer is left with an orphan entry for the new friendlyId.
       //
-      // Why this is acceptable in Phase 1:
+      // Why this is acceptable now:
       //   - Customer-facing behaviour is unchanged from today: they receive
       //     the existing run id, same as the non-mollified path.
       //   - The orphan is bounded — the drainer's no-op-ack handler pops
       //     and acks it on its next poll.
       //   - The audit-trail surfaces it: a `mollifier.buffered` log line
       //     with `runId` that has no matching TaskRun in Postgres.
       //
-      // Why Phase 2 cares:
+      // Why a later change cares:
       //   - When the buffer becomes the primary write path, debounce can
       //     no longer be allowed to run AFTER buffer.accept. The drainer's
       //     engine.trigger replay would observe "existing" and skip the
       //     persist — the customer's synthesised 200 (with the new
       //     friendlyId) would never get a TaskRun, and the audit-trail
       //     divergence becomes a real data-loss bug.
-      //   - Phase 2 must lift `handleDebounce` into the call site BEFORE
+      //   - A later change must lift `handleDebounce` into the call site BEFORE
       //     buffer.accept:
       //       1. handleDebounce → if existing, return existing run; do NOT
       //          touch the buffer.

packages/redis-worker/src/mollifier/buffer.test.ts

@@ -1074,7 +1074,7 @@ describe("MollifierBuffer.accept idempotency", () => {
     { timeout: 20_000 },
     async ({ redisContainer }) => {
       // After ack, the entry hash persists for the grace window as a
-      // read-fallback safety net (Q1 D2). RunIds are server-generated and
+      // read-fallback safety net. RunIds are server-generated and
       // never collide in practice, but defense-in-depth: accept refuses
       // while *any* entry exists for the runId, including materialised
       // ones. The entry hash's TTL is now ~30s instead of the original

packages/redis-worker/src/mollifier/buffer.ts

@@ -15,7 +15,7 @@ export type MollifierBufferOptions = {
 
 // Grace TTL applied to the entry hash on drainer ack. The entry survives
 // this long after materialisation so direct reads (retrieve, trace, etc.)
-// have a safety net while PG replica lag settles. Q1 D2.
+// have a safety net while PG replica lag settles.
 const ACK_GRACE_TTL_SECONDS = 30;
 
 // ioredis reconnect backoff for the mollifier buffer client. The base
@@ -80,7 +80,7 @@ export function idempotencyLookupKeyFor(input: IdempotencyLookupInput): string {
 }
 
 // Pre-gate claim key namespace, distinct from `mollifier:idempotency` so the
-// existing B6a buffer-side dedup stays isolated. The claim is the
+// existing buffer-side dedup stays isolated. The claim is the
 // authoritative cross-store "this idempotency key is in flight or
 // resolved" pointer used by the trigger hot path. Values:
 //   "pending:<token>"  → claimed by a trigger pipeline; `<token>` is the
@@ -143,7 +143,7 @@ export class MollifierBuffer {
     // SETNX a Redis lookup at `mollifier:idempotency:{env}:{task}:{key}`
     // pointing at the runId so trigger-time dedup during the buffered
     // window resolves the same way PG's unique constraint resolves it
-    // post-materialisation (Q5).
+    // post-materialisation.
     idempotencyKey?: string;
     taskIdentifier?: string;
   }): Promise<AcceptResult> {
@@ -277,7 +277,7 @@ export class MollifierBuffer {
   //   - "not_found": no entry hash exists for this runId — including a
   //     FAILED entry, whose hash the drainer-terminal `fail` path DELs.
   //   - "busy": entry is DRAINING or materialised. The API
-  //     wait-and-bounces through PG (Q3 design).
+  //     wait-and-bounces through PG.
   async mutateSnapshot(runId: string, patch: SnapshotPatch): Promise<MutateSnapshotResult> {
     const result = (await this.redis.mutateMollifierSnapshot(
       `mollifier:entries:${runId}`,
@@ -325,7 +325,7 @@ export class MollifierBuffer {
 
   // Atomic pre-gate claim on a (env, task, idempotencyKey) tuple. One
   // call across both PG and buffer paths serialises through this claim;
-  // closes the race the buffer-side B6a SETNX leaves open during the
+  // closes the race the buffer-side SETNX leaves open during the
   // gate-transition burst window.
   //
   // The caller supplies an opaque `token` (UUID) on claim. The same token
@@ -443,8 +443,8 @@ export class MollifierBuffer {
   // Marks the entry as materialised (PG row written) and resets its TTL to
   // the grace window. Entry hash persists past ack as a read-fallback
   // safety net for the brief PG replica-lag window between drainer-side
-  // write and reader-side visibility (Q1 D2). Also clears the associated
-  // idempotency lookup if one was set on accept (Q5).
+  // write and reader-side visibility. Also clears the associated
+  // idempotency lookup if one was set on accept.
   async ack(runId: string): Promise<void> {
     await this.redis.ackMollifierEntry(
       `mollifier:entries:${runId}`,
@@ -531,7 +531,7 @@ export class MollifierBuffer {
           return 0
         end
 
-        -- Idempotency-key dedup (Q5). If the caller passed a lookup key
+        -- Idempotency-key dedup. If the caller passed a lookup key
         -- and it's already bound to another buffered run, return the
         -- winner's runId so the loser's API response can echo it as a
         -- cached hit. Otherwise SET the lookup (no TTL — lifecycle is
@@ -606,7 +606,7 @@ export class MollifierBuffer {
         -- Requeue RPUSHes to the tail (the RPOP end) so a transiently
         -- failed entry pops next rather than going to the back of the
         -- line behind a fresh backlog. createdAt is immutable across
-        -- retries (Phase 3b decision); the drainer's maxAttempts caps the
+        -- retries; the drainer's maxAttempts caps the
         -- retry loop so a poisoned entry doesn't head-of-line forever.
         redis.call('RPUSH', queuePrefix .. envId, runId)
         -- Re-track the org/env: pop may have SREM'd them when the queue
@@ -920,7 +920,7 @@ export class MollifierBuffer {
 
         -- If the entry was accepted with an idempotency key, the lookup
         -- string was stored on the hash at accept time. Clear it now —
-        -- PG becomes canonical for the key post-materialisation (Q5).
+        -- PG becomes canonical for the key post-materialisation.
         local lookupKey = redis.call('HGET', entryKey, 'idempotencyLookupKey')
         if lookupKey and lookupKey ~= '' then
           redis.call('DEL', lookupKey)

packages/redis-worker/src/mollifier/drainer.test.ts

@@ -87,7 +87,7 @@ describe("MollifierDrainer.runOnce", () => {
       });
 
       // After ack the entry persists as a read-fallback safety net with
-      // materialised=true and a fresh grace TTL (Q1 D2 / Phase B2).
+      // materialised=true and a fresh grace TTL.
       const entry = await buffer.getEntry("run_1");
       expect(entry).not.toBeNull();
       expect(entry!.materialised).toBe(true);
@@ -981,7 +981,7 @@ describe("MollifierDrainer additional coverage", () => {
     // ack() lives inside the same try as the handler call, so if the
     // handler succeeds but ack throws (e.g. transient Redis blip), the
     // entry is routed through the retry/terminal path even though the
-    // handler-side work completed. Phase 2's engine-replay handler will
+    // handler-side work completed. A later engine-replay handler will
     // need idempotency to absorb the re-execution this implies on retry,
     // OR ack should be lifted out of the try block.
     let handlerCalls = 0;