Pass 3

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