sindoring
1d94eace68
Work-Package: M03-RND-M2-RUNTIME-MESH-FINALIZER-001 Agent: sindo-main-codex Tests: post-merge finalizer, classifier, extractor, cache, pipeline, materials, shutdown, facade, internal-access, manifest, documentation and coordination gates pass Fidelity: preserves refresh version 2 and rebuild/fallback transitions; asset-backed visual parity remains unclaimed
111 lines
4.7 KiB
Markdown
111 lines
4.7 KiB
Markdown
# M03-RND-M2-RUNTIME-MESH-FINALIZER-001 — M2 runtime mesh finalizer
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-M2-RUNTIME-MESH-FINALIZER-001:sindo-main-codex:2026-07-20 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-m2-runtime-mesh-finalizer`
|
|
- Lease expires UTC: 2026-07-20
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract stale cached-Mesh refresh classification, metadata adoption,
|
|
M2Builder rebuild and fallback from `StreamingWorldLoader` into one runtime M2
|
|
Mesh finalizer while retaining raw-file I/O in the loader.
|
|
|
|
## Non-goals
|
|
|
|
- Load raw `.m2` files, call FileAccess/ClassDB M2Loader or choose cache paths.
|
|
- Own ResourceLoader requests, Mesh cache/missing state or MultiMesh builds.
|
|
- Change material refresh version `2`, classifier predicates or rebuild behavior.
|
|
- Change cache formats, profiles or visible output.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/m2/m2_runtime_mesh_finalizer.gd`,
|
|
`src/tools/verify_m2_runtime_mesh_finalizer.gd`,
|
|
`docs/modules/m2-runtime-mesh-finalizer.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`, M2
|
|
classifier/extractor/cache/pipeline/material/shutdown verifiers and module
|
|
specs, `docs/modules/world-renderer.md`, `docs/modules/README.md`, `RENDER.md`,
|
|
`targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated M2 resources, caches and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Refresh version remains `2`; already-current Meshes return unchanged without raw data.
|
|
- Stale Meshes require caller-supplied raw data only when refresh is necessary.
|
|
- Empty/ordinary raw data marks the original Mesh current and returns it.
|
|
- Billboard/UV-rotation data attempts M2Builder rebuild and returns the rebuilt
|
|
first Mesh; rebuild failure marks and returns the original Mesh.
|
|
- Classifier memoization retains both existing clear sites through finalizer clear.
|
|
|
|
## Dependencies
|
|
|
|
- Requires: accepted Mesh resource extractor package on master `dd8cfbf`
|
|
- Blocks: further M2 raw-data I/O/prototype state extraction
|
|
- External state: none; verification uses synthetic Mesh/raw-data fixtures
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated current/stale/ordinary/rebuild/fallback/clear/source/timing
|
|
verifier; classifier/extractor/cache/pipeline/material/shutdown/M2 build/facade/
|
|
internal-access/manifest, documentation and coordination gates
|
|
- Fixtures: ArrayMesh and one synthetic triangle/billboard M2 Dictionary
|
|
- Fidelity evidence: exact refresh version, predicate, rebuild and fallback transitions
|
|
- Performance budget: 100 cycles over 256 ordinary finalizations under 1 second
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs
|
|
- Module specification with inputs/outputs, ownership and source map
|
|
- Data-flow, lifecycle/state, sequence and dependency diagrams
|
|
- Classifier/extractor/cache/pipeline, world-renderer, registry and RENDER updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important name introduced: `M2RuntimeMeshFinalizer`
|
|
- Simplest solution: one service composing existing classifier/extractor and M2Builder
|
|
- Rejected complexity: callbacks for loader I/O, generic material pipeline,
|
|
cache ownership, signals or strategy framework
|
|
- Unavoidable complexity: two-phase raw-data request avoids loading raw files for current Meshes
|
|
- Measured optimization evidence: bounded synthetic ordinary finalization loop
|
|
|
|
## Status
|
|
|
|
- State: accepted
|
|
- Done: finalizer, loader/test adapters, transition/rebuild verifier and required documentation
|
|
- Next: further M2 raw-data I/O/prototype state extraction
|
|
- Blocked by:
|
|
|
|
## Handoff
|
|
|
|
- Commit: `ece7724`
|
|
- Results: finalizer passes current/stale/ordinary/synthetic-rebuild/fallback/
|
|
clear contracts and 100-by-256 finalizations in 53.719 ms; 37 headless
|
|
renderer/coordinate regressions pass; checkpoint dry-run passes 7/7;
|
|
documentation and coordination gates pass.
|
|
- Remaining risks: rebuild remains synchronous behind the existing permit; no
|
|
private M2 material/traversal/descriptor-pressure/leak/p95/p99 or original-
|
|
client comparison; raw `.m2` I/O remains loader-owned by design.
|
|
- Documentation updated: inline API; `m2-runtime-mesh-finalizer.md` with
|
|
data-flow, lifecycle, sequence and dependency diagrams; classifier/extractor/
|
|
cache/pipeline specs, module registry, `world-renderer.md` and `RENDER.md`.
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-M2-RUNTIME-MESH-FINALIZER-001:ece7724 -->
|
|
|
|
## Integration
|
|
|
|
- Merge commit: `1fafdde`
|
|
- Post-merge results: finalizer `cases=11 iterations=100
|
|
elapsed_ms=54.349`; classifier, extractor, cache, pipeline, materials,
|
|
shutdown, facade, internal-access `34`, manifest `7/7`, documentation and
|
|
coordination gates passed.
|
|
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-RUNTIME-MESH-FINALIZER-001:1fafdde -->
|