test(people): pin the same-batch manager tie-break and document it

Author: waleedlatif1

apps/sim/lib/people/sync/stage.integration.ts

@@ -104,7 +104,7 @@ it('resumes relationship pages from stored continuations, refuses incomplete Gra
     .update(peopleDirectorySync)
     .set({ source: 'entra' })
     .where(eq(peopleDirectorySync.organizationId, run.organizationId))
-  await writeUsers(null, [person('lead'), person('worker'), person('other')])
+  await writeUsers(null, [person('lead'), person('worker'), person('other'), person('peer')])
   await expect(db.transaction((tx) => publishStagedSnapshot(tx, run, 'entra'))).rejects.toThrow(
     /relationship|report/i
   )
@@ -124,12 +124,17 @@ it('resumes relationship pages from stored continuations, refuses incomplete Gra
   })
   await record('lead', 'continuation', ['worker'], null)
   await record('other', null, ['worker'], null)
-  await record('worker', null, [], null)
+  await db.transaction((tx) =>
+    stageRelationships(tx, run, [
+      { managerId: 'worker', cursor: null, reportIds: ['other'], nextCursor: null },
+      { managerId: 'peer', cursor: null, reportIds: ['other'], nextCursor: null },
+    ])
+  )
   expect(await pendingManagers(db, run)).toEqual([])
   await db.transaction((tx) => publishStagedSnapshot(tx, run, 'entra'))
-  expect((await published()).find((r) => r.externalId === 'worker')?.managerExternalId).toBe(
-    'other'
-  )
+  const managers = new Map((await published()).map((r) => [r.externalId, r.managerExternalId]))
+  expect(managers.get('worker')).toBe('other')
+  expect(managers.get('other')).toBe('peer')
 })
 it('refuses to publish a replaced generation', async () => {
   await writeUsers(null, [person('live')])

apps/sim/lib/people/sync/stage.ts

@@ -103,8 +103,10 @@ export async function pendingManagers(executor: DbOrTx, run: StageRun) {
 
 /**
  * Commits only completed subrequests and rejects a cursor replay. Graph gives a person one
- * manager, so a person claimed again was moved during a read that spans many slices: the
- * latest read wins, and publication's cycle check still guards the finished graph.
+ * manager, so a person claimed again was moved during a read that spans many slices: a later
+ * batch overwrites an earlier one, and publication's cycle check still guards the finished
+ * graph. Reads inside one batch are concurrent, so a claim repeated there resolves to the
+ * lowest manager ID, independent of response order.
  */
 export async function stageRelationships(
   tx: DbTransaction,