open-wc/coordination/claims/M03-RND-M2-RUNTIME-REBUILD-CLASSIFIER-001.md

M03-RND-M2-RUNTIME-REBUILD-CLASSIFIER-001 — M2 runtime rebuild classifier

Ownership

• Target: M03
• Program: RND
• Owner/Agent ID: sindo-main-codex
• Branch: work/sindo-main-codex/m03-m2-runtime-rebuild-classifier
• Lease expires UTC: 2026-07-20
• Integrator: M03 milestone integrator

Outcome

Extract the memoized decision that stale cached M2 meshes require an in-memory runtime rebuild because raw batches contain billboard vertices or referenced UV rotation transforms.

Non-goals

• Load raw M2 files or cache Resources.
• Build, replace or mutate Meshes, materials, Nodes or RIDs.
• Change M2_MATERIAL_REFRESH_VERSION or cache formats.
• Interpret animation, particles, ribbons or general M2 shader fidelity.
• Change path normalization, ResourceLoader transitions or finalize budgets.

Paths

• Exclusive: src/render/m2/m2_runtime_mesh_rebuild_classifier.gd, src/tools/verify_m2_runtime_mesh_rebuild_classifier.gd, docs/modules/m2-runtime-mesh-rebuild-classifier.md, this claim
• Shared/hotspots: src/scenes/streaming/streaming_world_loader.gd, docs/modules/world-renderer.md, docs/modules/README.md, RENDER.md, targets/03-renderer-facade.md
• Generated/ignored: .godot, native DLL, generated ADT/M2 resources, caches and proprietary renderer corpus

Contracts and data

• Billboard metadata requires rebuild when has_billboard is true or billboard_vertex_count is positive in any Dictionary batch.
• UV rotation requires non-empty transforms and combos plus a referenced non-identity Vector4 rotation or absolute rotation speed above 0.000001.
• Only up to four texture stages per batch are inspected; invalid variants and out-of-range combo/transform indices are skipped.
• The first decision for a normalized path is memoized until clear, matching the existing loader cache lifetime.

Dependencies

• Requires: current accepted master 90b1dac
• Blocks: further M2 mesh request/cache/finalization extraction
• External state: none; verification uses synthetic raw M2 Dictionaries

Verification

• Commands: dedicated billboard/UV/index/stage/cache/clear/source/timing verifier; M2 builder/grouper/transform/registry, materials, shutdown, facade, internal-access, manifest, documentation and coordination gates
• Fixtures: synthetic batches, transform combos and rotation dictionaries
• Fidelity evidence: exact existing predicate thresholds, stage cap and cache lifetime preserved
• Performance budget: 100 classifications over 256 paths 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
• World-renderer, module registry and RENDER status updates

Simplicity and naming

• Important names introduced: M2RuntimeMeshRebuildClassifier
• Simplest considered solution: one RefCounted with one memoized query and clear
• Rejected complexity/abstractions: generic predicate cache, strategy interface, ResourceLoader wrapper, signals or typed rewrite of raw parser Dictionaries
• Unavoidable complexity and justification: four-stage combo indirection is the existing build-12340 M2 material boundary
• Measured optimization evidence: bounded synthetic classification loop

Status

• State: ready for integration
• Done: classifier/cache implemented; loader query and both clear sites migrated; synthetic predicate/cache verifier and required documentation added
• Next: integrate and run post-merge smoke on master
• Blocked by:

Handoff

• Commit: 19ca8f4
• Results: classifier PASS (cases=12, iterations=100, elapsed_ms=64.585; initial 35.461ms); billboard flag/count, invalid variants/indices, UV rotation/speed/epsilon, four-stage cap, memoization, detached diagnostics and clear contracts PASS; 33 M2/WMO/liquid/terrain/ facade/scheduler/streaming/coordinate/material/shutdown regressions PASS; internal-access decreased to 35; documentation and coordination gates PASS; checkpoint dry-run PASS 7/7.
• Remaining risks: raw parser data remains Dictionary-based; the first decision for a path remains authoritative until clear; classification covers the current four-stage material implementation only; private asset descriptor-pressure, traversal, p95/p99 and paired original-client evidence remain absent.
• Documentation updated: inline public API; new docs/modules/m2-runtime-mesh-rebuild-classifier.md; module registry, world renderer and RENDER.md; data-flow/state/sequence/dependency diagrams, ownership, failure/recovery, thresholds, cache lifetime and source map included.