# M03-RND-WMO-SCENE-INSTANCE-FACTORY-001

<!-- OPENWC_CLAIM:M03-RND-WMO-SCENE-INSTANCE-FACTORY-001:sindo-main-codex:2026-08-03 -->

## Owner

- Agent ID: `sindo-main-codex`
- Target: M03 Renderer Facade and Safe Extraction
- Branch: `work/sindo-main-codex/m03-wmo-scene-instance-factory`
- Worktree: `C:\Users\sindo\open-wc-worktrees\m03-wmo-scene-instance-factory`

## Outcome

Move WMO cached-scene instantiation/currentness validation and live-prototype
duplication with shared name/placement application into one main-thread factory.

## Non-goals

- Change cache lookup/admission, ResourceLoader or prototype construction.
- Change runtime Mesh/material/occluder/shadow preparation.
- Change attachment, placement registry, queues, permits or lifetime.
- Change scene cache version rules or placement formulas.

## Paths

- Exclusive: `src/render/wmo/wmo_scene_instance_factory.gd`,
  `src/tools/verify_wmo_scene_instance_factory.gd`,
  `docs/modules/wmo-scene-instance-factory.md`, this claim
- Shared: loader, adjacent WMO verifier/spec, renderer registry/specification,
  `RENDER.md`, M03 Evidence

## Contracts and data

- Null scenes/prototypes and non-Node3D instantiation/duplication return null.
- Cached instances failing the injected currentness validator are synchronously freed.
- Accepted instances retain exact descendant Resource identities.
- Both paths apply `relative_path.get_file().get_basename()` and the exact
  placement-resolver Transform3D.
- The factory returns detached roots and retains no Node or Resource.

## Dependencies

- Requires: accepted WMO placement resolver and runtime scene preparer
- Blocks: remaining loader-owned WMO cache/prototype orchestration cleanup

## Verification

- Synthetic cached/live type, validation, freeing, exact identity, name,
  transform, dependency/order, ownership, source and bounded-timing contracts;
  adjacent WMO/renderer gates and checkpoint dry-run.

## Documentation deliverables

- Inline API docs; module API/I/O/ownership; data-flow/sequence/dependency
  diagrams; adjacent renderer docs and M03 Evidence.

## Status

- State: ready
- Done: implementation, verification and documentation
- Next: integrator review and merge
- Blocked by:

## Handoff

- Commit: `7e97b19` (`render: extract WMO scene instance factory`)
- Results: factory PASS `cases=41 iterations=1000 elapsed_ms=5.297`;
  placement resolver dependency PASS `cases=10 iterations=20000
  elapsed_ms=28.740`; suite `65/66` with no unexpected failures and only the
  proprietary ADT placement probe unavailable; editor parse had zero script
  diagnostics; checkpoint dry-run retained `7/7`; documentation passed with
  `52` module specifications; coordination passed with `77` historical warnings.
- Fidelity: valid cached/live cache-validation distinction, basename, exact
  Transform3D and descendant Resource identity are unchanged. Invalid non-Node3D
  cached roots are now freed synchronously, fixing an error-path leak without
  changing valid visible output.
- Remaining risks: instantiation/duplication remains synchronous; no private WMO
  portal/room, visual, long-traversal, leak/GPU or p95/p99 evidence.
- Documentation: new full factory module specification; placement resolver
  consumers/sequence, renderer registry/source map and `RENDER.md` updated.

<!-- OPENWC_HANDOFF:READY:M03-RND-WMO-SCENE-INSTANCE-FACTORY-001:7e97b19 -->

<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-WMO-SCENE-INSTANCE-FACTORY-001:541279e -->

- Merge: `541279e` (`merge: WMO scene instance factory`)
- Post-merge: factory PASS `cases=41 iterations=1000 elapsed_ms=5.308`;
  placement resolver `cases=10`/`31.207ms`; runtime preparation/finalization,
  adjacent WMO services, shutdown, materials, facade, internal-access `30`,
  manifest `7/7`, documentation `52` and coordination passed.