pass 1

docs/PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md

@@ -4,6 +4,15 @@ This document expands Phase 1 of [ARCHITECTURE_RESILIENCE_REVIEW.md](/c:/Users/A
 
 The main goal of Phase 1 is not to immediately rewrite the app. It is to establish clear ownership boundaries so later refactors all move toward the same architecture instead of solving local problems in conflicting ways.
 
+## Status
+
+Phase 1 has two different meanings in this repo, and they should not be collapsed:
+
+- Phase 1 design package: complete.
+- Phase 1 target extraction in code: in progress.
+
+The completed design package includes the agreed subsystem names, responsibilities, dependency rules, state categories, and current-to-target migration map. The codebase also has concrete compatibility seams for those subsystems. That is different from saying every target boundary is fully extracted: several subsystems still delegate through compatibility helpers, and later roadmap phases are still responsible for the event model, remaining `RuntimeHost` split, sole-owner render thread, explicit live-state layering, background persistence, backend state machine, and fuller telemetry.
+
 ## Why Phase 1 Exists
 
 Today the app works, but too many responsibilities still converge in a few places:
@@ -112,17 +121,20 @@ The codebase now has an initial Phase 1 compatibility split in place:
   - [VideoBackend.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/videoio/VideoBackend.h)
   - [VideoBackend.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/videoio/VideoBackend.cpp)
 
-These are still compatibility seams, not a completed subsystem extraction. Most of them continue to delegate heavily to `RuntimeHost`, `OpenGLComposite`, `DeckLinkSession`, and the existing bridge/pipeline classes. Their purpose is to give later Phase 1 work real code boundaries that can be expanded in parallel:
+These are still compatibility seams, not a completed subsystem extraction. Some responsibilities have moved behind the new boundaries, while other paths still delegate through compatibility helpers, `OpenGLComposite`, `DeckLinkSession`, and the existing bridge/pipeline classes. Their purpose is to give later work real code boundaries that can be expanded without first inventing the names:
 
-- store-facing UI/runtime control calls in `OpenGLCompositeRuntimeControls.cpp` now route through `RuntimeStore`
+- UI/runtime control calls in `OpenGLCompositeRuntimeControls.cpp` now route through `RuntimeCoordinator`
 - runtime startup for path resolution, config load, persistent state load, and shader package scan now initializes through `RuntimeStore`
 - runtime/UI state JSON composition now lives in `RuntimeStore` instead of `RuntimeHost`
 - regular stored layer mutations and stack preset save/load now live in `RuntimeStore` instead of `RuntimeHost` public APIs
-- persisted OSC-by-control-key commits now apply through `RuntimeStore`, while `RuntimeHost` no longer exposes the old OSC smoothing/apply helper
+- persisted OSC-by-control-key commits now route through `RuntimeCoordinator` before applying store changes
 - mutation and reload policy now routes through `RuntimeCoordinator`
+- parameter target resolution, value normalization, trigger classification, and move no-op classification now live under `RuntimeCoordinator`
 - render-state and shader-build reads in `OpenGLComposite.cpp`, `OpenGLShaderPrograms.cpp`, and `ShaderBuildQueue.cpp` now route through `RuntimeSnapshotProvider`
-- render-state assembly, cached parameter refresh, and frame-context application now live in `RuntimeSnapshotProvider` instead of `RuntimeHost` public APIs
+- `RuntimeSnapshotProvider` now depends on `RuntimeStore` rather than sharing `RuntimeHost` directly
+- render-state assembly, cached parameter refresh, and frame-context application now flow through `RuntimeSnapshotProvider` and store-owned snapshot helpers instead of `RuntimeHost` public APIs
 - service ingress and polling coordination now route through `ControlServices`
+- `ControlServices` now queues coordinator results for OSC commit and file-poll outcomes instead of directly deciding runtime/store policy
 - timing and status writes now route through `HealthTelemetry`
 - `HealthTelemetry` now owns the live signal, video-I/O, and performance snapshots directly instead of `RuntimeHost` keeping those backing fields
 - render-side frame advancement and render-performance reporting now flow through `RuntimeSnapshotProvider` and `HealthTelemetry` instead of directly through `RuntimeHost`
@@ -131,7 +143,15 @@ These are still compatibility seams, not a completed subsystem extraction. Most
 - `OpenGLComposite` now owns a `VideoBackend` seam for device/session ownership and callback wiring
 - `OpenGLVideoIOBridge` now acts as an explicit compatibility adapter between `VideoBackend` and `RenderEngine`, instead of `OpenGLComposite` directly owning both sides
 
-That means the next parallel Phase 1 work can focus on moving responsibility behind these seams instead of first inventing them.
+That means the next extraction work can focus on moving responsibility behind these seams instead of first inventing them.
+
+Remaining extraction work includes:
+
+- replacing the compatibility `RuntimeHost` backing object still owned inside `RuntimeStore`
+- removing coordinator friendship/access to store-internal host data
+- publishing render snapshots as explicit immutable or near-immutable objects rather than building them from store internals on demand
+- moving persistence to an asynchronous writer in a later phase
+- replacing polling/shared-object coordination with the planned internal event model
 
 ## Subsystem Responsibilities
 
@@ -646,6 +666,8 @@ Phase 1 can reasonably be considered complete once the project has:
 - a current-to-target responsibility map for `RuntimeHost`, `RuntimeServices`, `OpenGLComposite`, and backend/render bridge code
 - a decision that later phases will build against this target rather than inventing new boundaries ad hoc
 
+By that definition, the Phase 1 design deliverable is complete. The implementation should still be described as partially extracted until the compatibility backing objects and cross-subsystem shims are removed.
+
 ## Open Questions For Later Phases
 
 These do not block Phase 1, but they should remain visible.