From caa0db4692729525808e531f4ee180c4aa27705c Mon Sep 17 00:00:00 2001 From: Tonio Date: Sat, 8 Aug 2026 10:00:55 -0700 Subject: [PATCH] docs(server): explain why the seed's issue idempotency key is not revision-scoped Cloud's reconcile runs off portfolio fetches, which can overlap, so two pushes of the same revision can race. The idempotency key on the first task is what makes that safe. It is deliberately company-scoped rather than revision-scoped, so that a later revision still dedupes against whatever the first push created if the recorded issue id is lost. That reasoning was not obvious from the call site. Co-authored-by: Paperclip Co-Authored-By: Claude Opus 5 (1M context) --- server/src/services/onboarding-seed.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/server/src/services/onboarding-seed.ts b/server/src/services/onboarding-seed.ts index b8650d11515..9e3b5ee958c 100644 --- a/server/src/services/onboarding-seed.ts +++ b/server/src/services/onboarding-seed.ts @@ -233,6 +233,11 @@ export function onboardingSeedService(db: Db) { }); } else { const projectId = await resolveOnboardingProjectId(companyId, goalId); + // The idempotency key is what protects two pushes that arrive at once + // — Cloud's reconcile runs off portfolio fetches, which can overlap. + // It is deliberately not revision-scoped: if the recorded issue is + // lost, a later revision should still dedupe against whatever the + // first push created. const created = await issueSvc.create(companyId, { title: firstTaskTitle, ...(firstTaskDetails ? { description: firstTaskDetails } : {}),