# 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 -->
