docs update

docs/DECKLINK_OPENGL_LESSONS_LEARNED.md

@@ -115,6 +115,24 @@ Lesson:
 - keep synthetic counters only as diagnostics
 - do not infer device health from internal stream indexes alone
 
+### Schedule Cursor Recovery Must Be Conservative
+
+The DeckLink schedule cursor should normally advance as a continuous stream timeline. Continuously realigning the next scheduled stream time to the sampled playback cursor can create its own timing fault: output may look like low FPS even when render and scheduling counters average 59.94/60 fps.
+
+What worked better:
+
+- use the exact DeckLink frame duration for the render cadence
+- keep healthy scheduling on a continuous stream cursor
+- measure schedule lead from DeckLink playback time versus the next schedule time
+- realign only after real pressure, such as a late/drop report or dangerously low measured lead
+- re-arm proactive realignment only after lead has recovered
+
+Lesson:
+
+- schedule recovery is an output-edge safety valve, not a per-frame timing policy
+- if recovery increments continuously, the recovery path has become the problem
+- include schedule lead and realignment count in telemetry/logs so drift is visible before guessing
+
 ### More Buffer Is Not Automatically Smoother
 
 Increasing DeckLink scheduled frames sometimes made the reported device buffer look healthier while visible motion still stuttered.
@@ -196,7 +214,7 @@ Lesson:
 
 - system-memory slots are the contract between render and playout
 - scheduled slots must not be recycled early
-- completed-but-unscheduled slots can be latest-N cache entries
+- completed-but-unscheduled slots should form a bounded FIFO reserve for playout
 
 ### Startup Needs Real Preroll
 
@@ -222,18 +240,18 @@ Lesson:
 
 The app has at least two important frame stores:
 
-- system-memory completed/latest-N frames
+- system-memory completed FIFO reserve frames
 - DeckLink scheduled/device buffer
 
 They have different ownership rules.
 
-Completed-but-unscheduled frames are disposable if a newer frame is available and cadence needs the slot.
+Completed-but-unscheduled frames should be a bounded FIFO reserve for playout. If that reserve overflows, dropping the oldest completed frame is an app-side reserve policy and should be counted separately from DeckLink dropped frames.
 
 Scheduled frames are not disposable because DeckLink may still read them.
 
 Lesson:
 
-- latest-N completed frames are a cache
+- completed frames waiting for playout are a bounded FIFO reserve
 - scheduled frames are owned by DeckLink until completion
 - keep metrics for both
 
@@ -246,7 +264,8 @@ That couples the clocks again.
 Lesson:
 
 - render cadence should keep rendering at selected cadence
-- if completed cache is full, recycle/drop the oldest unscheduled completed frame
+- render acquire should not evict completed frames that are waiting for playout
+- if the completed reserve overflows, drop/count the oldest unscheduled completed frame
 - only scheduled/in-flight saturation should prevent rendering to a safe slot
 
 ## Render Thread Lessons
@@ -340,7 +359,7 @@ The current direction is still sound:
 ```text
 Render cadence loop
   renders at selected output cadence
-  writes latest-N completed system-memory frames
+  writes completed system-memory frames into a bounded FIFO reserve
   never sprints to refill DeckLink
 
 Frame store
@@ -387,7 +406,7 @@ A full rewrite becomes attractive only if the current GL ownership model cannot
 - Render cadence is time-driven, not completion-driven.
 - DeckLink scheduling is device-buffer-driven, not render-driven.
 - Completion callbacks release and report; they do not render.
-- System-memory completed frames are latest-N cache entries.
+- System-memory completed frames are a bounded FIFO reserve.
 - Scheduled frames are protected until DeckLink completion.
 - Startup uses real rendered warmup/preroll.
 - Black fallback is degraded/error behavior, not steady-state behavior.