Pass 3

docs/PHASE_1_SUBSYSTEM_BOUNDARIES_DESIGN.md

@@ -102,12 +102,21 @@ The codebase now has an initial Phase 1 compatibility split in place:
 - `RuntimeStore`
   - [RuntimeStore.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeStore.h)
   - [RuntimeStore.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeStore.cpp)
+- `RuntimeConfigStore`
+  - [RuntimeConfigStore.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeConfigStore.h)
+  - [RuntimeConfigStore.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeConfigStore.cpp)
+- `ShaderPackageCatalog`
+  - [ShaderPackageCatalog.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/ShaderPackageCatalog.h)
+  - [ShaderPackageCatalog.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/ShaderPackageCatalog.cpp)
 - `RuntimeCoordinator`
   - [RuntimeCoordinator.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeCoordinator.h)
   - [RuntimeCoordinator.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeCoordinator.cpp)
 - `RuntimeSnapshotProvider`
   - [RuntimeSnapshotProvider.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeSnapshotProvider.h)
   - [RuntimeSnapshotProvider.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RuntimeSnapshotProvider.cpp)
+- `RenderSnapshotBuilder`
+  - [RenderSnapshotBuilder.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RenderSnapshotBuilder.h)
+  - [RenderSnapshotBuilder.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/runtime/RenderSnapshotBuilder.cpp)
 - `ControlServices`
   - [ControlServices.h](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/control/ControlServices.h)
   - [ControlServices.cpp](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/apps/LoopThroughWithOpenGLCompositing/control/ControlServices.cpp)
@@ -124,15 +133,15 @@ The codebase now has an initial Phase 1 compatibility split in place:
 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:
 
 - 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
+- runtime startup now initializes path resolution and config loading through `RuntimeConfigStore`, with shader package scan and lookup delegated to `ShaderPackageCatalog`
+- runtime/UI state JSON composition now routes through `RuntimeStatePresenter` and `RuntimeStateJson` instead of living in `RuntimeHost` or `RuntimeStore`
+- regular stored layer mutations and stack preset save/load now route through `RuntimeStore` into `LayerStackStore` instead of `RuntimeHost` public APIs
 - 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`
-- `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
+- `RuntimeSnapshotProvider` now depends on `RenderSnapshotBuilder` rather than on `RuntimeStore` friendship or shared `RuntimeHost` access
+- render-state assembly, cached parameter refresh, dynamic frame-field application, and render snapshot versions now live in `RenderSnapshotBuilder` instead of `RuntimeStore`
 - `RuntimeSnapshotProvider` now publishes versioned render snapshot objects and serves matching consumers from the last published snapshot
 - 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
@@ -140,6 +149,10 @@ These are still compatibility seams, not a completed subsystem extraction. Some
 - `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`
 - `RuntimeStore` now owns its durable/session backing fields directly instead of wrapping a compatibility `RuntimeHost` object
+- `RuntimeConfigStore` now owns runtime config parsing, path resolution, configured ports/formats, runtime roots, and shader compiler paths instead of leaving those responsibilities inside `RuntimeStore`
+- `ShaderPackageCatalog` now owns shader package scanning, package status/order/lookup, and package asset/source change comparison instead of leaving those responsibilities inside `RuntimeStore`
+- `LayerStackStore` now owns durable layer state, layer CRUD/reorder, parameter persistence, and stack preset value serialization/load instead of leaving those responsibilities inside `RuntimeStore`
+- `RuntimeStatePresenter` and `RuntimeStateJson` now own runtime-state JSON assembly and layer-stack presentation serialization instead of leaving those responsibilities inside storage classes
 - `RuntimeCoordinator` now uses explicit `RuntimeStore` query APIs/read models instead of friendship or direct store-internal access
 - live OSC overlay state and smoothing/commit decisions now live under `RenderEngine` instead of `OpenGLComposite`
 - coordinator result application, shader-build requests, ready-build application, and runtime-state broadcasts now route through `RuntimeUpdateController` instead of being interpreted directly by `OpenGLComposite`
@@ -346,7 +359,8 @@ Allowed dependency directions:
 - `RuntimeCoordinator -> RuntimeStore`
 - `RuntimeCoordinator -> RuntimeSnapshotProvider`
 - `RuntimeCoordinator -> HealthTelemetry`
-- `RuntimeSnapshotProvider -> RuntimeStore`
+- `RuntimeSnapshotProvider -> RenderSnapshotBuilder`
+- `RenderSnapshotBuilder -> RuntimeStore`
 - `RenderEngine -> RuntimeSnapshotProvider`
 - `RenderEngine -> HealthTelemetry`
 - `VideoBackend -> RenderEngine`
@@ -574,7 +588,8 @@ Likely examples:
 
 - config loading/saving -> `RuntimeStore`
 - layer stack mutation validation -> `RuntimeCoordinator`
-- render state building/versioning -> `RuntimeSnapshotProvider`
+- render state building/versioning -> `RenderSnapshotBuilder`
+- render snapshot publication/cache -> `RuntimeSnapshotProvider`
 - timing/status setters -> `HealthTelemetry`
 
 ### Current `RuntimeServices`

docs/subsystems/README.md

@@ -42,11 +42,11 @@ That order mirrors the intended dependency story:
 ## Subsystem Notes
 
 - [RuntimeStore.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeStore.md)
-  Durable runtime config, persisted layer state, presets, and package metadata ownership.
+  Durable runtime-state facade over layer-stack, config, package-catalog, presentation, and persistence boundaries.
 - [RuntimeCoordinator.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeCoordinator.md)
   Mutation validation, state classification, reset/reload policy, and publication/persistence requests.
 - [RuntimeSnapshotProvider.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RuntimeSnapshotProvider.md)
-  Render-facing snapshot build, publication, and versioning boundaries.
+  Render-facing snapshot publication boundary backed by explicit render snapshot building/versioning.
 - [ControlServices.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/ControlServices.md)
   OSC, HTTP/WebSocket, and file-watch ingress plus normalization and service-local buffering.
 - [RenderEngine.md](/c:/Users/Aiden/Documents/GitHub/video-shader-toys/docs/subsystems/RenderEngine.md)

docs/subsystems/RuntimeSnapshotProvider.md

@@ -12,7 +12,7 @@ It exists to solve three current problems:
 
 - render state is still built directly out of `RuntimeHost` under a shared mutex
 - render reads and refreshes partially mutable cached layer state in more than one place
-- state publication, state versioning, and dynamic frame-field refresh are not yet explicit subsystems
+- state publication, state versioning, and dynamic frame-field refresh need explicit ownership
 
 Today the closest current behavior lives in:
 
@@ -29,13 +29,17 @@ Today the closest current behavior lives in:
 
 `RuntimeSnapshotProvider` is responsible for:
 
-- building render-facing snapshots from durable store state plus whatever committed-live state view the Phase 3 split ultimately exposes
 - publishing stable, versioned snapshots that can be consumed without large shared mutable locks
+- giving `RenderEngine` a cheap read path for the latest committed snapshot
+- making snapshot invalidation and publication rules explicit
+
+`RenderSnapshotBuilder` is responsible for:
+
+- building render-facing snapshots from durable store state plus whatever committed-live state view the Phase 3 split ultimately exposes
 - separating structural snapshot changes from dynamic frame fields
 - translating runtime layer state into render-ready layer descriptors
 - attaching immutable or near-immutable shader/package-derived data needed by render
-- giving `RenderEngine` a cheap read path for the latest committed snapshot
-- making snapshot invalidation and publication rules explicit
+- maintaining render snapshot version counters and frame advancement
 
 It is not responsible for:
 
@@ -75,7 +79,7 @@ The shape of render-facing layer state should remain consistent across phases ev
 
 ## Snapshot Inputs
 
-`RuntimeSnapshotProvider` should build from a read-oriented runtime view, not from direct mutation calls.
+`RenderSnapshotBuilder` should build from a read-oriented runtime view, not from direct mutation calls. `RuntimeSnapshotProvider` should consume the builder's output and own publication/cache behavior.
 
 That view will likely include:
 
@@ -87,7 +91,8 @@ That view will likely include:
 
 The important Phase 1 rule is not "the provider always reads one specific object." It is:
 
-- the provider consumes read-oriented committed runtime state
+- the builder consumes read-oriented committed runtime state
+- the provider consumes builder-published render snapshot data
 - the provider does not own mutation policy
 - render consumes the provider's published output instead of reaching back into whichever runtime object currently stores the truth
 
@@ -292,11 +297,11 @@ Notes:
 
 ### `RuntimeStore`
 
-`RuntimeSnapshotProvider` depends on store-owned durable data and package metadata through a read-oriented interface or view.
+`RenderSnapshotBuilder` depends on store-owned durable data and package metadata through a read-oriented interface or view. `RuntimeSnapshotProvider` depends on the builder rather than reaching into store internals directly.
 
-If committed live state remains physically co-located with the store during early migration, the provider may read it through the same view. If committed live state moves behind a coordinator-owned live-session model later, the provider should consume that through a similarly read-oriented view.
+If committed live state remains physically co-located with the store during early migration, the builder may read it through the same view. If committed live state moves behind a coordinator-owned live-session model later, the builder should consume that through a similarly read-oriented view.
 
-It should not mutate the store directly.
+Neither the builder nor provider should mutate the store directly.
 
 ### `RuntimeCoordinator`
 
@@ -337,7 +342,7 @@ This is especially important while migrating away from the current lock/fallback
 
 The current code suggests the following migration map.
 
-### Move into `RuntimeSnapshotProvider`
+### Move into `RenderSnapshotBuilder`
 
 From `RuntimeHost`:
 
@@ -346,6 +351,12 @@ From `RuntimeHost`:
 - explicit version composition for render-visible state
 - dynamic frame-context construction currently done in `RefreshDynamicRenderStateFields(...)`
 
+### Move into `RuntimeSnapshotProvider`
+
+- published snapshot cache ownership
+- version matching for already-published snapshots
+- render-facing compatibility API while render callers migrate
+
 ### Stop exposing directly from the host/store boundary
 
 Current methods that should become compatibility shims and later disappear:
@@ -357,9 +368,9 @@ Current methods that should become compatibility shims and later disappear:
 
 ### Render-side compatibility during migration
 
-The current `OpenGLComposite` cache path:
+The previous `OpenGLComposite` cache path:
 
-- reads versions from `RuntimeHost`
+- reads versions from `RuntimeHost`/store-owned counters
 - conditionally calls `TryRefreshCachedLayerStates(...)`
 - conditionally rebuilds full layer state
 - then reapplies render-local OSC overlay state
@@ -367,8 +378,8 @@ The current `OpenGLComposite` cache path:
 During migration, that should become:
 
 1. get latest published snapshot from provider
-2. compare snapshot versions against render-local cache
-3. rebuild only if needed
+2. compare snapshot versions produced by `RenderSnapshotBuilder`
+3. rebuild through `RenderSnapshotBuilder` only if needed
 4. apply render-local overlay state
 5. attach frame context
 

docs/subsystems/RuntimeStore.md

@@ -276,7 +276,7 @@ Per the Phase 1 subsystem design, `RuntimeStore` should sit low in the dependenc
 Allowed inbound dependencies:
 
 - `RuntimeCoordinator -> RuntimeStore`
-- `RuntimeSnapshotProvider -> RuntimeStore`
+- `RenderSnapshotBuilder -> RuntimeStore`
 - temporary migration shims from `ControlServices` only where explicitly tolerated
 
 Allowed outbound dependencies:
@@ -359,16 +359,33 @@ Those belong under other target subsystems.
 `RuntimeStore` does not need to be one monolithic class forever. A practical internal shape would be:
 
 - `RuntimeConfigStore`
-  - runtime host config load/save and resolved paths
-- `PersistentLayerStore`
+  - runtime host config load and resolved paths
+
+The current codebase has begun this split: `RuntimeConfigStore` owns config parsing, path resolution, configured ports/formats, runtime roots, and shader compiler paths, while `RuntimeStore` keeps compatibility delegates for existing callers.
+- `LayerStackStore`
   - durable layer stack and parameter values
-- `StackPresetStore`
-  - preset enumeration/load/save
-- `ShaderPackageCatalogStore`
+  - layer CRUD/reorder and shader selection
+  - stack preset value serialization/load
+- `RuntimeStatePresenter` / `RuntimeStateJson`
+  - runtime-state JSON assembly
+  - layer-stack presentation serialization
+- `RenderSnapshotBuilder`
+  - render-state assembly and parameter refresh
+  - dynamic frame-field refresh and render snapshot version counters
+- `ShaderPackageCatalog`
   - durable manifest/package metadata
+  - shader package scanning, status/order/lookup, and asset/source change comparison
 - `PersistenceWriter` helper
   - synchronous at first, async/debounced later
 
+The current codebase has begun the layer split: `LayerStackStore` owns durable layer state, layer CRUD/reorder, parameter persistence, and stack preset value serialization/load. `RuntimeStore` still owns locking, file IO, and compatibility delegates for existing callers.
+
+The current codebase has begun the render snapshot split: `RenderSnapshotBuilder` owns render-state assembly, cached parameter refresh, dynamic frame-field refresh, and render snapshot versions. `RuntimeSnapshotProvider` depends on this builder rather than on `RuntimeStore` friendship.
+
+The current codebase has also begun the presentation split: `RuntimeStatePresenter` owns top-level runtime-state JSON assembly, while `RuntimeStateJson` owns the layer-stack and parameter presentation shape used by runtime state clients.
+
+The current codebase has also begun the package split: `ShaderPackageCatalog` owns package scanning and registry comparison, while `RuntimeStore` uses it to keep layer state valid and to build compatibility read models.
+
 These can still be presented through one subsystem façade during migration.
 
 ## Persistence Model