pass 1

docs/ARCHITECTURE_RESILIENCE_REVIEW.md

@@ -4,7 +4,7 @@ This note summarizes the main architectural improvements that would make the app
 
 Phase checklist:
 
-- [ ] Define subsystem boundaries and target architecture
+- [x] Define subsystem boundaries and target architecture
 - [ ] Introduce an internal event model
 - [ ] Split `RuntimeHost`
 - [ ] Make the render thread the sole GL owner
@@ -13,6 +13,11 @@ Phase checklist:
 - [ ] Make DeckLink/backend lifecycle explicit with a state machine
 - [ ] Add structured health, telemetry, and operational reporting
 
+Checklist note:
+
+- The checked Phase 1 item means the subsystem vocabulary, dependency direction, state categories, and design package are in place.
+- It does not mean the target boundaries are fully extracted in code. The current implementation has Phase 1 compatibility seams, while the full ownership split continues through later phases.
+
 ## Timing Review
 
 The recent OSC work removed several control-path stalls, but the app still has a few deeper timing characteristics that matter for live resilience:
@@ -356,6 +361,12 @@ This roadmap is ordered by architectural dependency rather than by “quick wins
 
 Before changing major internals, formalize the target responsibilities for each major part of the app.
 
+Status:
+
+- Design deliverable: complete.
+- Compatibility seams in code: partially complete and expanding.
+- Target boundary extraction: not complete; remaining work is tracked by later phases, especially the event model, `RuntimeHost` split, render ownership, and persistence work.
+
 Target split:
 
 - `RuntimeStore`
@@ -402,6 +413,10 @@ Suggested deliverables:
 - a subsystem design bundle index:
   - [docs/subsystems/README.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/README.md)
 
+Current implementation note:
+
+The repo now has concrete classes for the Phase 1 subsystem names and several call paths already route through them. These classes should be treated as migration boundaries, not proof that the target architecture is fully extracted.
+
 ### Phase 2. Introduce an internal event model
 
 Once subsystem boundaries are defined, introduce a typed event pipeline between them. This should happen before large state splits so the app has a stable coordination model.

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.

docs/subsystems/README.md

@@ -15,6 +15,12 @@ Parent documents:
 - The notes in this directory expand each subsystem boundary without changing the parent Phase 1 design.
 - The subsystem notes are meant to be read as design companions, not as independent alternate architectures.
 
+Status note:
+
+- The Phase 1 design package is complete.
+- The codebase has compatibility seams for the named subsystems.
+- The target subsystem extraction is still in progress, so these notes describe the architecture the implementation is moving toward, not a claim that every boundary is already pure.
+
 ## Recommended Reading Order
 
 1. [PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md)
@@ -60,3 +66,5 @@ Phase 1 should leave the project with:
 - one agreed current-to-target migration story
 
 Phase 1 does not need to settle every later implementation detail. The subsystem notes intentionally leave some questions open where later phases need room to choose concrete mechanics.
+
+As of the current codebase, those design questions are settled well enough for later work to build against them. Remaining implementation work should be tracked as extraction progress under later phases, especially eventing, the `RuntimeHost` split, render-thread ownership, persistence, backend lifecycle, and telemetry.