[E3][Progress] Unified routing schema and static diagnostics for MoE/MoT/Latent

[Ricky-7-Yan]

E3 Progress Summary

This issue reports the first reproducible P0 loop for E3: unified routing observability across real MoE, MoT, and Latent YOLO-Master model forwards.

The current work focuses on a non-invasive observation layer:

• no modification to the core model forward;
• no training-quality or detection-accuracy claim;
• no upstream PR has been opened yet;
• this issue records the first experimental results, mechanism findings, and current progress.

Public work package:

• Repository: https://github.com/Ricky-7-Yan/YOLO-Master-E3-P0
• Current commit: Ricky-7-Yan/YOLO-Master-E3-P0@268b881
• Design: https://github.com/Ricky-7-Yan/YOLO-Master-E3-P0/blob/main/docs/DESIGN.md
• Result summary: https://github.com/Ricky-7-Yan/YOLO-Master-E3-P0/blob/main/artifacts/p0/p0-20260829-cpu/summary.json

Completed Work

• Locked the tested YOLO-Master runtime to commit
  07d330325b5a26b75aabfc75389f9bcbc0d40245.
• Added a versioned routing event schema:
  e3.routing/v1.0.0.
• Added leaf-only routed-module discovery to avoid parent/child double counting.
• Added adapters for real MoE, MoT, and Latent modules.
• Added explicit observed / derived / unavailable field states.
• Added normalized expert load, routing entropy, normalized entropy, load Gini, dominant expert share, mixing-weight state, and auxiliary-loss state.
• Added per-family JSONL logs and static diagnostic plots.
• Added a cross-family summary plot.
• Added environment metadata, input hash, resolved configuration, full log, and SHA-256 manifest evidence.
• Added contract and collector tests covering metric invariants, schema validation, hook transparency, hook cleanup, family discovery, leaf selection, missing-field semantics, and the MoE eval fallback path.
• Added run-id path-safety and reproduction overwrite-protection tests.
• Current regression result: all 11 tests passed.

Experiment Setup

• Dataset: coco8 val[0]
• Input image SHA-256:
  4c28394898302bef227834d63498a0fc54e4295f11c590c8a8ebcba51347bc03
• Input size: 64 × 64
• Seed: 0
• Device: CPU
• Models: randomly initialized
• Execution mode: eval with torch.inference_mode()

The experiment is intentionally small. It validates the observation pipeline and schema, not trained-model routing quality.

First P0 Results

Family	Model parameters	Leaf routed modules	Captured events	Normalized entropy range	Load Gini range	Main transport
MoE	5,115,336	6	6	0.250–0.500	0.500–0.875	Nested router forward hook
MoT	2,927,512	4	4	0.000–0.631	0.333–0.667	Official detached routing snapshot
Latent	5,478,423	3	3	1.000–1.000	0.000–0.000	Official detached routing snapshot

A total of 13 routing events were captured. All events passed the e3.routing/v1.0.0 JSON Schema validation.

Mechanism Analysis

1. Leaf-only routed-module discovery

YOLO-Master already provides the common is_routed_module protocol, but both a routed wrapper and its routed child may satisfy the protocol.

Registering hooks on both levels can count the same routing decision twice.

The current collector therefore:

1. discovers protocol-compatible candidates;
2. matches the requested routing family;
3. removes candidates that contain another routed child;
4. registers hooks only on leaf routing producers.

A dedicated test constructs a routed parent and routed child and verifies that only the child is selected.

2. MoE eval observability gap

The first real MoE preflight discovered 6 routed modules but captured 0 events.

Source inspection showed that OptimizedMOEImproved still executes its router during eval and obtains routing_weights and routing_indices, but _record_moe_snapshot(...) is only called when:

if self.training and loss_dict:

Switching the model to training mode only for diagnostics was rejected because it can change progressive sparsity, expert dropout, Top-K scheduling, and loss behavior.

The current P0 implementation instead registers a temporary hook on the nested router return point:

• routing_indices are counted and normalized into expert load;
• routing_weights are averaged across routing positions;
• tensors are immediately detached and moved to CPU;
• the outer module hook converts the cached data into the unified event;
• all hook handles and temporary caches are removed in finally.

This recovered 6/6 MoE events without modifying the core forward or changing the model from eval mode.

The diagnostic source is explicitly recorded as:

nested_router_forward_hook

3. Missing auxiliary loss is not silently converted to zero

MoE eval does not expose a real training auxiliary loss.

The schema therefore records:

{
  "state": "unavailable",
  "source": null,
  "value": null
}

This avoids treating “not observed in this execution path” as “observed and equal to zero.”

4. Cross-family semantics

The three families expose different routing granularities:

• MoE: module-defined sparse Top-K routing;
• MoT: spatial-token routing;
• Latent: image- or scale-level routing.

The unified schema standardizes the observation fields while preserving granularity, source metadata, and the detached original snapshot.

The current cross-family plot should therefore be interpreted as evidence that one observer can process all three families, not as a claim that their routing mechanisms are directly equivalent.

Difficulties and Findings

1. The main MoE difficulty was not routing execution, but the absence of an eval snapshot in the tested OptimizedMOEImproved path.
2. Forcing training mode would make the diagnostic result semantically incorrect, so the collection path must remain external and eval-safe.
3. MoE, MoT, and Latent cannot be fully unified without preserving routing granularity and source provenance.
4. Latent produced uniform routing in this random-initialization cold-start run. This is pipeline evidence, not a claim that trained Latent routing remains uniform.
5. A single coco8 image is sufficient for a CPU Smoke test but not for dataset-level collapse or expert-specialization conclusions.
6. The recorded single-forward durations are observations only. A valid observer-overhead benchmark still requires warmup, repeated paired runs, and hook-off/hook-on comparison.
7. The current machine has no NVIDIA CUDA device, so no GPU result is claimed.

Current Status

• Admission Smoke: completed.
• P0 unified schema and static three-family diagnostics: completed in the standalone public work package.
• JSON Schema validation: passed for all 13 events.
• Unit and contract tests: all 11 passed.
• Ruff: passed.
• Clean one-command reproduction: fixed and verified.
• Upstream integration PR: not opened yet.
• Realtime dashboard: not yet implemented.
• Paired hook-off/hook-on overhead benchmark: not yet implemented.
• Original-image token-routing overlay: not yet implemented.

Next Steps

1. Continue refining the unified schema and the MoE eval diagnostic design.
2. Prepare a minimal, reviewable upstream integration design.
3. Add a paired hook-off/hook-on benchmark with warmup and repeated measurements.
4. Build a realtime view only after the event contract and overhead methodology are stable.