sindoring/open-wc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor(M03): extract M2 runtime mesh finalizer

Browse Source 
Work-Package: M03-RND-M2-RUNTIME-MESH-FINALIZER-001
Agent: sindo-main-codex
Tests: 37 headless renderer/coordinate contracts pass; checkpoint dry-run 7/7; documentation and coordination gates pass
Fidelity: preserves refresh version 2, classifier, rebuild and fallback transitions; no visual parity claim
This commit is contained in:
sindoring
2026-07-17 15:01:52 +04:00
parent 951bd54fff
commit ece7724a28
15 changed files with 626 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/modules/m2-mesh-resource-cache-state.md
+14 -12
View File
@@ -13,8 +13,8 @@
## Purpose
Own the runtime cache of prepared static M2 `Mesh` references outside
`StreamingWorldLoader`. The loader remains responsible for finding, loading,
extracting, refreshing and materializing each Mesh.
`StreamingWorldLoader`. Dedicated services extract and prepare each Mesh; the
loader remains responsible for finding, loading, adopting and materializing it.
## Non-goals
@@ -34,7 +34,7 @@ flowchart LR
Loader --> Pipeline[M2MeshLoadPipelineState]
Pipeline --> IO[ResourceLoader]
IO --> Extract[M2MeshResourceExtractor]
Extract --> Prepare[Loader runtime preparation]
Extract --> Prepare[M2RuntimeMeshFinalizer]
Prepare --> Cache
Loader --> Build[M2 MultiMesh materialization]
```
@@ -74,7 +74,7 @@ flowchart TD
Cached -->|no| Missing{Shared missing state?}
Missing -->|yes| Null[Return null]
Missing -->|no| Load[Loader request or synchronous fallback]
Load --> Prepare[Loader extracts and prepares Mesh]
Load --> Prepare[Extractor and runtime finalizer prepare Mesh]
Prepare --> Valid{Prepared Mesh valid?}
Valid -->|yes| Store[Store or replace cache entry]
Valid -->|no| MarkMissing[Loader updates shared missing state]
@@ -104,7 +104,7 @@ sequenceDiagram
Loader->>Cache: find/has normalized path
alt cache miss
Loader->>Pipeline: request/poll/finalize record
Loader->>Loader: ResourceLoader get + extract + prepare
Loader->>Loader: ResourceLoader get; delegate extract + prepare
Loader->>Cache: store_mesh(path, prepared Mesh)
end
Cache-->>Loader: exact retained Mesh
@@ -117,7 +117,7 @@ sequenceDiagram
flowchart TB
Loader[StreamingWorldLoader] --> Cache[M2MeshResourceCacheState]
Loader --> Pipeline[M2MeshLoadPipelineState]
Loader --> Classifier[M2RuntimeMeshRebuildClassifier]
Loader --> Finalizer[M2RuntimeMeshFinalizer]
Loader --> Builder[M2Builder and MultiMesh]
Cache --> Mesh[Godot Mesh Resource]
Cache -. no dependency .-> Pipeline
@@ -146,8 +146,9 @@ flowchart TB
## Configuration and capabilities
The module adds no setting, budget or profile branch. Cache path order,
`M2_MATERIAL_REFRESH_VERSION`, finalize permits and batching remain loader-owned.
The module adds no setting, budget or profile branch. Cache path order, finalize
permits and batching remain loader-owned; refresh version `2` belongs to
`M2RuntimeMeshFinalizer`.
## Persistence, cache and migration
@@ -173,8 +174,8 @@ the historical Mesh cache had no queue contribution or log site.
## Extension points
- A separate M2 Mesh resource finalizer may later return a prepared Mesh for
`store_mesh` without changing cache ownership.
- `M2RuntimeMeshFinalizer` returns a prepared Mesh for `store_mesh` without
changing cache ownership.
- Eviction requires measured memory pressure and explicit lifetime semantics.
## Capability status
@@ -184,7 +185,7 @@ the historical Mesh cache had no queue contribution or log site.
| Prepared static M2 Mesh cache | Implemented extraction | Contract/source/timing verifier | Asset-backed memory/leak run pending |
| M2 Mesh request lifecycle | Implemented extraction | Pipeline state verifier | ResourceLoader I/O remains loader-owned |
| M2 Mesh extraction | Implemented extraction | Resource/order/lifetime verifier | Asset-backed corrupt-scene fixture pending |
| M2 Mesh preparation | Existing loader-owned | Material/classifier regressions | Separate finalizer extraction next |
| M2 Mesh preparation | Implemented extraction | Runtime finalizer transition/rebuild verifier | Asset-backed material comparison pending |
## Known gaps and risks
@@ -200,7 +201,8 @@ the historical Mesh cache had no queue contribution or log site.
|---|---|
| `src/render/m2/m2_mesh_resource_cache_state.gd` | Prepared Mesh references and final clear |
| `src/render/m2/m2_mesh_resource_extractor.gd` | First-Mesh selection and temporary PackedScene lifetime |
| `src/scenes/streaming/streaming_world_loader.gd` | Normalization, I/O, preparation, missing state and materialization |
| `src/scenes/streaming/streaming_world_loader.gd` | Normalization, raw/resource I/O, missing state and materialization |
| `src/render/m2/m2_runtime_mesh_finalizer.gd` | Refresh/rebuild/fallback preparation |
| `src/render/m2/m2_mesh_load_pipeline_state.gd` | Pending request and terminal finalize records |
| `src/tools/verify_m2_mesh_resource_cache_state.gd` | Cache ownership/lifetime/boundary/timing regression |