docs update

apps/RenderCadenceCompositor/README.md

@@ -26,7 +26,7 @@ InputFrameMailbox
 
 SystemFrameExchange
   owns Free / Rendering / Completed / Scheduled slots
-  preserves completed output frames once they are waiting for playout
+  preserves completed output frames as a bounded FIFO reserve once they are waiting for playout
   protects scheduled frames until DeckLink completion
 
 DeckLinkOutputThread
@@ -52,8 +52,9 @@ Included now:
 - bounded three-frame input warmup before render cadence starts
 - render-thread-owned input texture upload
 - async PBO readback
-- latest-N system-memory frame exchange
+- bounded FIFO system-memory frame exchange
 - bounded completed-frame output preroll reserve before DeckLink playback, with DeckLink scheduled depth still targeted at four
+- conservative DeckLink schedule-lead telemetry and recovery
 - background Slang compile of `shaders/happy-accident`
 - app-owned display/render layer model for shader build readiness
 - app-owned submission of a completed shader artifact
@@ -266,7 +267,7 @@ The app samples telemetry once per second.
 
 Normal cadence samples are available through `GET /api/state` and are not printed to the console. The telemetry monitor only logs health events:
 
-- warning when DeckLink late/dropped-frame counters increase
+- warning when DeckLink late/dropped-frame counters increase, including schedule lead and recovery count
 - warning when schedule failures increase
 - error when the app/DeckLink output buffer is starved
 
@@ -285,8 +286,14 @@ Input telemetry:
 - `renderFrameMaxMs`: maximum observed render-thread draw duration for this process
 - `readbackQueueMs`: time spent queueing the most recent async BGRA8 PBO readback
 - `completedReadbackCopyMs`: time spent mapping/copying the most recent completed readback into system-memory frame storage
-- `completedDrops`: completed unscheduled system-memory frames dropped; expected to stay flat in the cadence compositor output path
+- `completedDrops`: oldest completed unscheduled system-memory frames dropped because the bounded completed reserve overflowed; this is an app-side reserve drop, not a DeckLink dropped-frame report
 - `acquireMisses`: times render/readback could not acquire a writable system-memory frame slot; completed frames waiting for playout are preserved instead of being displaced
+- `deckLinkScheduleLeadAvailable`: whether DeckLink schedule-lead telemetry was available for the latest sample
+- `deckLinkScheduleLeadFrames`: estimated distance between the DeckLink playback cursor and the next scheduled stream time
+- `deckLinkPlaybackFrameIndex`: latest sampled DeckLink playback frame index
+- `deckLinkNextScheduleFrameIndex`: next stream frame index the app intends to schedule
+- `deckLinkPlaybackStreamTime`: latest sampled DeckLink playback stream time in DeckLink time units
+- `deckLinkScheduleRealignments`: conservative schedule-cursor recoveries triggered by late/drop pressure or dangerously low lead
 - `inputConsumeMisses`: render ticks where no ready input frame was available to upload
 - `inputUploadMisses`: input texture upload attempts that reused the previous GL input texture
 - `inputReadyFrames`: ready input frames currently queued in `InputFrameMailbox`
@@ -303,7 +310,7 @@ Input telemetry:
 - `inputUnsupportedFrames`: input frames rejected before mailbox submission
 - `inputSubmitMisses`: input frames that could not be submitted to the mailbox
 
-Runtime shaders continue rendering when input is missing. If no mailbox frame has been uploaded yet, shader samplers use the runtime fallback source texture; once DeckLink input is flowing, shaders such as CRT and trigger-ripple sample the real/latest input through `gVideoInput`.
+Runtime shaders continue rendering when input is missing. If no mailbox frame has been uploaded yet, shader samplers use the runtime fallback source texture; once DeckLink input is flowing, shaders such as CRT and trigger-ripple sample the current input through `gVideoInput`.
 
 Healthy first-run signs:
 
@@ -312,6 +319,8 @@ Healthy first-run signs:
 - `scheduleFps` is close to the selected cadence after warmup
 - `scheduled` stays near 4
 - `decklinkBuffered` stays near 4 when available
+- `deckLinkScheduleLeadFrames` remains positive and stable when available
+- `deckLinkScheduleRealignments` does not increase continuously
 - `late` and `dropped` do not increase continuously
 - `scheduleFailures` does not increase
 - `shaderCommitted` becomes `1` after the background Happy Accident compile completes
@@ -386,6 +395,7 @@ Read:
 - render cadence and DeckLink schedule cadence both held roughly 60 fps
 - app scheduled depth stayed at 4
 - actual DeckLink buffered depth stayed at 4
+- DeckLink schedule lead remained positive during healthy playback
 - no late frames, dropped frames, or schedule failures were observed
 - completed poll misses were benign because playout remained fully fed
 
@@ -406,7 +416,7 @@ This app keeps the same core behavior but splits it into modules that can grow:
 - `platform/`: COM/Win32/hidden GL context support
 - `render/`: cadence thread, clock, and simple renderer
 - `frames/InputFrameMailbox`: non-blocking bounded FIFO CPU input handoff with contiguous-copy fast path for matching row strides
-- `render/InputFrameTexture`: render-thread-owned upload of the latest CPU input frame into GL, including raw UYVY8 decode into the shader-visible input texture
+- `render/InputFrameTexture`: render-thread-owned upload of the currently acquired CPU input frame into GL, including raw UYVY8 decode into the shader-visible input texture
 - `render/readback/`: PBO-backed BGRA8 readback and completed-frame publication
 - `render/runtime/RuntimeRenderScene`: render-thread-owned GL scene for ready runtime shader layers
 - `render/runtime/RuntimeShaderPrepareWorker`: shared-context runtime shader program compile/link worker