# M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001 — M2 mesh resource extractor

<!-- OPENWC_CLAIM:M03-RND-M2-MESH-RESOURCE-EXTRACTOR-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-mesh-resource-extractor`
- Lease expires UTC: 2026-07-20
- Integrator: M03 milestone integrator

## Outcome

Extract first-Mesh selection from loaded M2 Resources and Node subtrees,
including temporary PackedScene instance cleanup, from `StreamingWorldLoader`.

## Non-goals

- Call ResourceLoader or select/request cache paths.
- Refresh/rebuild materials or load raw M2 data.
- Own the Mesh cache, missing state, prototypes or MultiMesh materialization.
- Change traversal order, cache formats, profiles or visible behavior.

## Paths

- Exclusive: `src/render/m2/m2_mesh_resource_extractor.gd`,
  `src/tools/verify_m2_mesh_resource_extractor.gd`,
  `docs/modules/m2-mesh-resource-extractor.md`, this claim
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
  M2 pipeline/cache/material/shutdown verifiers, `docs/modules/world-renderer.md`,
  `docs/modules/README.md`, M2 module specs, `RENDER.md`,
  `targets/03-renderer-facade.md`
- Generated/ignored: `.godot`, native DLL, generated M2 resources, caches and
  proprietary renderer corpus

## Contracts and data

- A direct Mesh Resource returns the same Mesh reference.
- A PackedScene is instantiated once, searched depth-first in child order and
  its temporary root is freed before return.
- A Node subtree search returns the first MeshInstance3D Mesh in historical
  depth-first preorder without changing the tree.
- Null, unsupported Resources and subtrees without a Mesh return null.

## Dependencies

- Requires: accepted Mesh resource cache package on master `5e2afbc`
- Blocks: isolated material refresh/rebuild finalizer extraction
- External state: none; verification uses synthetic Mesh/Node/PackedScene fixtures

## Verification

- Commands: dedicated direct/PackedScene/subtree/order/lifetime/source/timing
  verifier; M2 pipeline/cache/classifier/material/shutdown/build/facade/internal-
  access/manifest, documentation and coordination gates
- Fixtures: ArrayMesh, MeshInstance3D subtrees and synthetic PackedScene
- Fidelity evidence: exact traversal order and temporary-node destruction
- Performance budget: 10,000 synthetic subtree lookups 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
- M2 cache/pipeline, world-renderer, registry and RENDER updates

## Simplicity and naming

- Important name introduced: `M2MeshResourceExtractor`
- Simplest solution: one stateless RefCounted with two explicit extraction APIs
- Rejected complexity: callback-driven finalizer, generic scene utility,
  cache ownership, signals or visitor framework
- Unavoidable complexity: temporary PackedScene instance must be freed while
  its referenced Mesh remains borrowed
- Measured optimization evidence: bounded synthetic depth-first traversal

## Status

- State: accepted
- Done: extractor, three loader/test adapters, contract verifier and required documentation
- Next: isolated M2 Mesh material preparation finalizer extraction
- Blocked by:

## Handoff

- Commit: `7b0e1ea`
- Results: extractor passes direct/PackedScene/subtree/order/lifetime contracts
  and 10,000 traversals in 39.243 ms; 36 headless renderer/coordinate
  regressions pass; checkpoint dry-run passes 7/7; documentation and
  coordination gates pass.
- Remaining risks: synchronous PackedScene instantiation remains behind the
  existing permit; no private M2 corrupt-scene/traversal/leak/p95/p99 or
  original-client comparison; material preparation remains loader-owned.
- Documentation updated: inline API; `m2-mesh-resource-extractor.md` with
  data-flow, lifecycle, sequence and dependency diagrams; cache/pipeline specs,
  module registry, `world-renderer.md` and `RENDER.md`.

<!-- OPENWC_HANDOFF:READY:M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001:7b0e1ea -->

## Integration

- Merge commit: `fa85985`
- Post-merge results: extractor `cases=10 iterations=10000
  elapsed_ms=38.172`; cache, pipeline, classifier, materials, shutdown, facade,
  internal-access `34`, manifest `7/7`, documentation and coordination gates passed.

<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-M2-MESH-RESOURCE-EXTRACTOR-001:fa85985 -->