coord(M03): claim M2 animation load pipeline

coordination/claims/M03-RND-M2-ANIMATION-LOAD-PIPELINE-001.md

@@ -0,0 +1,92 @@
+# M03-RND-M2-ANIMATION-LOAD-PIPELINE-001 — M2 animation load pipeline state
+
+<!-- OPENWC_CLAIM:M03-RND-M2-ANIMATION-LOAD-PIPELINE-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-animation-load-pipeline`
+- Lease expires UTC: 2026-07-20
+- Integrator: M03 milestone integrator
+
+## Outcome
+
+Extract threaded animated-M2 pending request records and completion-order
+finalize FIFO from `StreamingWorldLoader` into an explicit state service.
+
+## Non-goals
+
+- Call ResourceLoader, select/validate GLB paths or interpret status values.
+- Instantiate/repair/cache animated Nodes or own prototype outcomes.
+- Change animation allow/deny/candidate policy, permits or visible behavior.
+- Add cancellation, persistence, retries, dependencies or cache-format changes.
+
+## Paths
+
+- Exclusive: `src/render/m2/m2_animation_load_pipeline_state.gd`,
+  `src/tools/verify_m2_animation_load_pipeline_state.gd`,
+  `docs/modules/m2-animation-load-pipeline-state.md`, this claim
+- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`, M2
+  prototype/shutdown/material/build/facade/internal-access/manifest 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
+
+- One non-empty normalized path has at most one pending cache path.
+- Pending snapshots preserve Dictionary insertion order and detach records.
+- Completing a known request moves one copied record with opaque status into a
+  completion-order FIFO; unknown/duplicate completion is rejected.
+- Defensive discard removes pending state without creating a finalize record.
+- Total work remains pending plus finalize count at all three historical metrics.
+- Map reset and shutdown retain the same two clear sites; shutdown still drains
+  ResourceLoader paths before clear.
+
+## Dependencies
+
+- Requires: accepted prototype cache package on master `20a64b5`
+- Blocks: animated M2 finalization/materialization service extraction
+- External state: ResourceLoader request statuses remain loader-owned
+
+## Verification
+
+- Commands: dedicated validation/dedupe/order/transition/discard/snapshot/clear/
+  source/timing verifier; prototype/shutdown/material/M2 build/facade/internal-
+  access/manifest and adjacent M2 regressions; docs/coordination/dry-run gates
+- Fixtures: synthetic normalized/cache paths and opaque integer statuses
+- Fidelity evidence: request insertion, terminal FIFO, metrics and clear transitions
+- Performance budget: 100 cycles over 256 request completions 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
+- Adjacent M2/world-renderer/module-registry/RENDER updates
+
+## Simplicity and naming
+
+- Important name introduced: `M2AnimationLoadPipelineState`
+- Simplest solution: one main-thread RefCounted with pending map and finalize FIFO
+- Rejected complexity: generic Resource pipeline, signals, callbacks, typed
+  ResourceLoader enum wrapper, Node ownership or async abstraction
+- Unavoidable complexity: pending insertion order and terminal completion order differ
+- Measured optimization evidence: bounded synthetic transition loop
+
+## Status
+
+- State: claimed
+- Done: request/finalize fields, three metrics, two clear sites and shutdown drain identified
+- Next: implement state, migrate adapters, verify and document
+- Blocked by:
+
+## Handoff
+
+- Commit:
+- Results:
+- Remaining risks:
+- Documentation updated: