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

<!-- OPENWC_CLAIM:M03-RND-M2-RUNTIME-REBUILD-CLASSIFIER-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-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.

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-RUNTIME-REBUILD-CLASSIFIER-001:19ca8f4 -->