[core] Fix systemId cleanup for nested children on stopChild

.changeset/six-trees-hide.md

@@ -0,0 +1,5 @@
+---
+'xstate': patch
+---
+
+Fix `systemId` cleanup for nested children on `stopChild`

packages/core/src/actions/stopChild.ts

@@ -52,6 +52,22 @@ function resolveStop(
     undefined
   ];
 }
+function unregisterRecursively(
+  actorScope: AnyActorScope,
+  actorRef: AnyActorRef
+) {
+  // unregister children first (depth-first)
+  const snapshot = actorRef.getSnapshot();
+  if (snapshot && 'children' in snapshot) {
+    for (const child of Object.values(
+      snapshot.children as Record<string, AnyActorRef>
+    )) {
+      unregisterRecursively(actorScope, child);
+    }
+  }
+  actorScope.system._unregister(actorRef);
+}
+
 function executeStop(
   actorScope: AnyActorScope,
   actorRef: AnyActorRef | undefined
@@ -63,7 +79,8 @@ function executeStop(
   // we need to eagerly unregister it here so a new actor with the same systemId can be registered immediately
   // since we defer actual stopping of the actor but we don't defer actor creations (and we can't do that)
   // this could throw on `systemId` collision, for example, when dealing with reentering transitions
-  actorScope.system._unregister(actorRef);
+  // we also need to recursively unregister all nested children's systemIds
+  unregisterRecursively(actorScope, actorRef);
 
   // this allows us to prevent an actor from being started if it gets stopped within the same macrostep
   // this can happen, for example, when the invoking state is being exited immediately by an always transition

packages/core/test/system.test.ts

@@ -15,6 +15,7 @@ import {
   fromPromise,
   fromTransition,
   sendTo,
+  setup,
   spawnChild,
   stopChild
 } from '../src/index.ts';
@@ -584,4 +585,43 @@ describe('system', () => {
 
     expect(actor.system.getAll()).toEqual({});
   });
+
+  it('should unregister nested child systemIds when stopping a parent actor', () => {
+    const subchild = createMachine({});
+
+    const child = setup({
+      actors: {
+        subchild
+      }
+    }).createMachine({
+      id: 'childSystem',
+      invoke: {
+        src: 'subchild',
+        systemId: 'subchild'
+      }
+    });
+
+    const parent = setup({
+      actors: { child }
+    }).createMachine({
+      entry: spawnChild('child', { id: 'childId' }),
+      on: {
+        restart: {
+          actions: [
+            stopChild('childId'),
+            spawnChild('child', { id: 'childId' })
+          ]
+        }
+      }
+    });
+
+    const root = createActor(parent).start();
+
+    expect(root.system.get('subchild')).toBeDefined();
+
+    // This should not throw "Actor with system ID 'subchild' already exists"
+    expect(() => root.send({ type: 'restart' })).not.toThrow();
+
+    expect(root.system.get('subchild')).toBeDefined();
+  });
 });