Module ep_map 

Measured expert-placement map (MEMRA_EP_MAP; glm5 alias honored) — the fail-closed memra-ep-map-v1 reader every family’s EP shard builders consume (fleet-shared by design; glm5 is the first consumer). (LAW:coactivation-expert-placement; maps are minted by the shared fleet tool from MEMRA_MOE_WEIGHT_TRACE traces). No CUDA deps. Measured expert-placement map consumption (MEMRA_EP_MAP, lane/glm5-ep-place 2026-08-31, generalized lane/glm5-extract-general) — the fail-closed memra-ep-map-v1 reader the shard builders trust. FLEET-SHARED BY DESIGN: one flag, one parser, one validation law for every family that arms measured placement (glm5 today; hy3/qwen adopt the same seam). Family loaders add only their own geometry laws (rank count, entry rank, layer cover) on top of the parsed map.

LAW:coactivation-expert-placement (darklanes agent-knowledge/gpu/kernel-craft.md, owner directive 2026-08-31): expert placement is MEASURED, never even-split — (1) measure per-layer expert co-activation on real traffic, (2) partition experts into per-card bundles maximizing same-card top-k co-residency under VRAM balance, (3) pin the always-active set to a KNOWN card the token visits first. In the glm5 TP-2 seam that known first-hop card is rank 0 (root): the router runs there, the combine lands there, and the shared expert is already root-owned STRUCTURALLY (moe_shexp_add) — which is why the loader requires the map’s entry_rank to be 0.

DIVISION OF LABOR (fleet coordination 2026-08-31): maps are MINTED by the shared fleet tool — tools/build_expert_placement_map.py (stdlib-only; strategies coactivation/frequency/even; self-receipting per-layer stats vs the even control; spec + example receipts in research/ep-placement-map-20260831/REPORT.md) — from MEMRA_MOE_TRACE id lines (+ optional MEMRA_MOE_WEIGHT_TRACE hotness). This module is the ENGINE-SIDE reader: one parser, one validation law, plus the env seam ([ep_map_env]) that resolves the general flag and its family alias. First consumer: glm5_tp::prepare_glm5_tp_load / arm_moe_ep.

THE FROZEN FORMAT (memra-ep-map-v1, JSON — quoted from the tool’s REPORT):

{"format":"memra-ep-map-v1","strategy":"coactivation|frequency|even","ranks":N,
 "entry_rank":0,"expert_count":E,"traces":[...],"params":{...},
 "layers":[{"layer":L,"assignment":[rank per expert 0..E-1],"stats":{...}}]}

The reader consumes the LOAD-BEARING fields only (format, ranks, entry_rank, expert_count, layers[].layer, layers[].assignment); traces/params/stats are the mint’s self-receipt and ride along uninspected. Parsing uses the house minimal JSON reader (memra_gguf::config::JsonObj) — no serde dependency. Every refusal names the field and the law it broke; the LOADER additionally refuses maps whose layer set does not exactly match the EP-armed layers of the model being loaded (validate_layer_cover).

CORRECTNESS CONTRACT the engine holds regardless of this file’s content: the EP walk is placement-independent by construction — ownership only selects WHICH rank runs the identical per-expert dot program over identical (host-canonically fanned-out) input bytes, and the combine is slot-ordered on root either way. The map changes bytes MOVED, never bytes COMPUTED. glm5-tp-gate proves it with a deliberately skewed map against the even split (arm M) and bites the corrupted-map red (R4).

Structs

EpMap

One parsed placement map: per layer, owners[expert] = rank.

Constants

EP_MAP_ENV

The general fleet flag: MEMRA_EP_MAP=<path> points a family’s EP shard builders at a measured memra-ep-map-v1 placement map.

EP_MAP_ENV_GLM5

The family alias the glm5 lanes shipped with (lane/glm5-ep-place). Still honored — banked gate arms, box batteries and the in-flight lanes set it — never silently dead.

Functions

ep_map_env

Env-reading wrapper over resolve_ep_map_env.

resolve_ep_map_env

Pure resolution over the two names (env in production; plain values in the unit tests — the env-mutation-free co-refusal-test pattern). Returns the ARMED name with its value so every downstream refusal names the flag the operator actually set. Both set to the SAME value resolves to the general name; both set to DIFFERENT values refuses loudly (fail-closed: two flags disagreeing about which map arms a load is an operator error, never a precedence coin-flip). A set-but-empty value is returned as-is — the loader refuses it downstream by name (never a silent default).