docs: document director playback error handling

changelog.d/1014-director-callback-failures.md

@@ -0,0 +1 @@
+Director clock listeners, interaction observers and scene release failures no longer leave the director inconsistent, and a phase error is kept when cleanup also fails (deepeshbind, #1014).

docs/CURRENT-STATE.md

@@ -1,5 +1,9 @@
 # God's Eye View Current State
 
+Director clock listeners, interaction observers and scene release failures no
+longer leave the director inconsistent, and a phase error is kept when cleanup
+also fails.
+
 Vessel sources can report healthy empty coverage using a current, complete
 snapshot with zero raw rows, a healthy transport and a positive last-message
 time. This clears obsolete contacts and settles startup without manufacturing

src/director/playback.js

@@ -35,6 +35,7 @@ export function buildPlaybackQueue(
  * releaseScene(scene, token?) leaves a previously loaded scene before playback
  * (false refuses that initial handoff). Between scenes and during final cleanup
  * it receives no cancelled token, so resource release can finish after Stop.
+ * The first error wins when the final release also fails.
  * An empty/already-cancelled queue acquires and releases no resources.
  *
  * @param {Array<{scene:Object, shot:Object}>} queue Normalized, fixed shot queue.

src/director/playback.test.mjs

@@ -213,6 +213,7 @@ test('a phase failure is preserved when final scene release also throws', async
     (error) => error === phaseError,
   );
 });
+
 test('a failing inter-scene release releases the active scene only once', async () => {
   const releaseError = new Error('release failed');
   const released = [];