-- Network synchronizer or source-backed tagged-reference test bridge. Never synthesize Unit handles.
-- World.unit_by_id and Unit.id are EDITOR identifiers, not our native unit key.
-- Unit.is_child has an unverified game-specific contract and is NOT called.
return function(sr,N,Z,policy,Reference,MountPolicy)
 local M={}
 local function required(t,k)
  -- Engine math constructors may be functions with a namespace __index, not tables.
  local ok,f=pcall(function()return t and t[k]end)
  if not ok or type(f)~='function'then error('SPATIAL_API_MISSING:'..k,0)end
  return f
 end
 local function valid_id(n)return type(n)=='number'and n%1==0 and n>0 and n<32767 end
 function M.resolve(vehicle,meta,context)
  local detail={heuristic=true,status='START',stage='API_CHECK',positions={},module='UnitSynchronizer',vector_reader='Vector3.to_elements',sample_clock=context.clock,seated_goid=vehicle and vehicle.goid}
  local ok,list,status,validate=pcall(function()
   local GS,US,U,V,App,Net=sr.GameSession,sr.UnitSynchronizer,sr.Unit,sr.Vector3,sr.Application,sr.Network
   local sync_get=required(GS,'unit_synchronizer');local exists=required(GS,'game_object_exists')
   local to_unit,to_id
   local alive=required(U,'alive');local position=required(U,'world_position');local nodes=required(U,'num_scene_graph_items')
   local elements=required(V,'to_elements');local session_get=required(Net,'game_session');local peer_get=required(Net,'peer_id');local world_get=required(App,'main_world')
   local function scope()
    if session_get()~=context.session or peer_get()~=context.peer or world_get()~=context.world then error('SPATIAL_CONTEXT_CHANGED',0)end
   end
   detail.stage='CONTEXT_CHECK';scope()
   local bodies=meta and meta.mech_descriptors or {};local candidates=meta and meta.candidate_descriptors or {}
   if #bodies<1 or #bodies>policy.max_mechs or #candidates<1 or #candidates>policy.max_arms then error('SPATIAL_COUNT_BOUND',0)end
   detail.stage='SYNCHRONIZER_GET'
   local sync=sync_get(context.session);local tagged=false
   if sync==nil then
    if not Reference or context.allow_tagged==false then error('SPATIAL_NO_SYNCHRONIZER',0)end
    detail.stage='REF_INDEX';detail.module='WorldUnitTaggedReference';detail.reference_matches={};detail.node_matches={}
    local ready,why,ref_info=Reference.prepare(context);detail.reference=ref_info
    if not ready then
     if why=='SPATIAL_INDEX_PENDING'then return nil,why end
     detail.error=why;return nil,'SPATIAL_UNAVAILABLE'
    end
    tagged=true
   else to_unit=required(US,'game_object_id_to_unit');to_id=required(US,'unit_to_game_object_id')end
   detail.stage='NATIVE_IDENTITY'
   N.win.begin_sample();local g=N.graph(N.win.read,N.base)
   local rel=g:relation(context.avatar)
   if rel.status~='VEHICLE'or not N.same(rel.vehicle,vehicle)then error('SPATIAL_SEAT_CHANGED',0)end
   local net,hm=g:root('network'),g:root('health');local units,seen={},{}
   local function linked(d)
    if not valid_id(d.goid)or seen[d.entity]then error('SPATIAL_IDENTITY_INVALID',0)end;seen[d.entity]=true
    g:roundtrip(net,d)
    local i,owner=g:component(hm,d.entity,0x1030,0x1048)
    if i==nil or not N.same(owner,d)then error('SPATIAL_HEALTH_OWNER_CHANGED',0)end
    if exists(context.session,d.goid)~=true then error('SPATIAL_OBJECT_GONE',0)end
    detail.stage=tagged and'TAGGED_REFERENCE_TO_UNIT'or'GOID_TO_UNIT';detail.current_goid=d.goid
    local u
    if tagged then
     local evidence;u,evidence=Reference.lookup(d,context);detail.reference_matches[#detail.reference_matches+1]=evidence
    else u=to_unit(sync,d.goid)end
    if u==nil or alive(u)~=true then error('SPATIAL_NO_LIVE_UNIT:'..d.goid,0)end
    if not tagged and to_id(sync,u)~=d.goid then error('SPATIAL_UNIT_ROUNDTRIP',0)end
    for _,v in ipairs(units)do if v.unit==u then error('SPATIAL_UNIT_ALIAS',0)end end
    local n=nodes(u);if type(n)~='number'or n%1~=0 or n<1 or n>65536 then error('SPATIAL_NODE_BOUND',0)end
    local node,name=1,nil
    if tagged then
     detail.stage='UNIT_ROOT_NODE';node,name=Reference.root_node(u,d)
     detail.node_matches[#detail.node_matches+1]=Reference.last_node_check
    end
    local entry={descriptor=d,unit=u,node=node,node_name=name};units[#units+1]=entry;return entry
   end
   local bs,as={},{}
   for _,d in ipairs(bodies)do bs[#bs+1]=linked(d)end
   for _,d in ipairs(candidates)do if not vehicle or not Z.models[vehicle.resource].arms[d.resource]then error('SPATIAL_RESOURCE_NOT_ALLOWED',0)end;as[#as+1]=linked(d)end
   local function sample(entries,record)
    local out={}
    for _,entry in ipairs(entries)do
     local d,u=entry.descriptor,entry.unit
     if exists(context.session,d.goid)~=true or alive(u)~=true then error('SPATIAL_UNIT_CHANGED',0)end
     if tagged then
      Reference.validate(u,d,context)
      local node,name=Reference.root_node(u,d)
      if node~=entry.node or name~=entry.node_name then error('REF_NODE_CHANGED',0)end
     elseif to_id(sync,u)~=d.goid then error('SPATIAL_UNIT_CHANGED',0)end
     local x,y,z=elements(position(u,entry.node))
     for _,v in ipairs({x,y,z})do if type(v)~='number'or v~=v or math.abs(v)>1000000 then error('SPATIAL_POSITION_INVALID',0)end end
     if x==nil or y==nil or z==nil then error('SPATIAL_POSITION_MISSING',0)end
     out[#out+1]={descriptor=d,position={x,y,z}}
     if record then detail.positions[#detail.positions+1]={entity=d.entity,goid=d.goid,position={x,y,z},node=entry.node,node_name=entry.node_name}end
    end
    return out
   end
   local function mount_sample(record)
    local out={};local has=required(U,'has_node');local node=required(U,'node')
    if record then detail.mount_nodes={}end
    for _,entry in ipairs(bs)do
     local d,u=entry.descriptor,entry.unit;detail.current_goid=d.goid
     Reference.validate(u,d,context)
     local specs=MountPolicy.specs(d);if not specs then error('MOUNT_SCHEMA_MISSING',0)end
     local row={descriptor=d,mounts={}};entry.mount_indices=entry.mount_indices or {}
     for _,side in ipairs({'L','R'})do
      local spec=specs[side];local check={entity=d.entity,goid=d.goid,side=side,name=spec.name,resource=spec.resource}
      detail.mount_check=check
      if record then detail.mount_nodes[#detail.mount_nodes+1]=check end
      check.exists=has(u,spec.name)==true;if not check.exists then error('MOUNT_NAMED_NODE_MISSING',0)end
      local i=node(u,spec.name);check.index_type=type(i)
      if type(i)~='number'or i~=i or i%1~=0 or i<0 or i>65535 then error('MOUNT_NODE_INDEX_INVALID',0)end
      check.node=i
      if record then entry.mount_indices[side]=i elseif entry.mount_indices[side]~=i then error('MOUNT_NODE_CHANGED',0)end
      local x,y,z=elements(position(u,i))
      for _,v in ipairs({x,y,z})do if type(v)~='number'or v~=v or math.abs(v)>1000000 then error('MOUNT_POSITION_INVALID',0)end end
      if x==nil or y==nil or z==nil then error('MOUNT_POSITION_MISSING',0)end
      check.position={x,y,z};check.passed=true
      row.mounts[side]={name=spec.name,resource=spec.resource,node=i,position={x,y,z}}
     end
     out[#out+1]=row
    end
    scope();return out
   end
   detail.stage='POSITIONS'
   local before_b,before_a=sample(bs,true),sample(as,true)
   detail.stage='GEOMETRY'
   local chosen,why,selection=policy.select(vehicle,before_b,before_a,Z.side_by_resource)
   detail.selection=selection;detail.match_method='BODY_ROOT_MARGIN'
   local mount_before,mount_used
   if not chosen and tagged and MountPolicy and context.allow_mounts~=false and (why=='SPATIAL_COMPETING_MECH'or why=='SPATIAL_DUPLICATE_SIDE'or why=='SPATIAL_NO_CLOSE_ARM')then
    detail.root_selection=selection;detail.root_reason=why;detail.match_method='MOUNT_POINT_TEST';detail.stage='MOUNT_ANCHORS'
    mount_before=mount_sample(true);detail.stage='MOUNT_GEOMETRY'
    chosen,why,selection=MountPolicy.select(vehicle,mount_before,before_a,policy.key,policy.distance)
    detail.selection=selection;mount_used=true
   end
   scope();g:validate()
   if not chosen then return nil,why end
   local signature=selection.signature;detail.signature=signature
   -- Recheck AFTER Health reads. No positional match is retained for a later poll.
   local function stable()
    local good,err=pcall(function()
     scope()
     local after_b,after_a=sample(bs,false),sample(as,false)
     for i,row in ipairs(after_b)do if policy.distance(row.position,before_b[i].position)>.5 then error('SPATIAL_MOVED_DURING_SAMPLE',0)end end
     for i,row in ipairs(after_a)do if policy.distance(row.position,before_a[i].position)>.5 then error('SPATIAL_MOVED_DURING_SAMPLE',0)end end
     local again,reason,info
     if mount_used then
      local mount_after=mount_sample(false)
      for i,row in ipairs(mount_after)do for _,side in ipairs({'L','R'})do
       if policy.distance(row.mounts[side].position,mount_before[i].mounts[side].position)>.5 then error('MOUNT_MOVED_DURING_SAMPLE',0)end
      end end
      again,reason,info=MountPolicy.select(vehicle,mount_after,after_a,policy.key,policy.distance)
      detail.mount_revalidation=info
     else again,reason,info=policy.select(vehicle,after_b,after_a,Z.side_by_resource)end
     if not again then error(reason or 'SPATIAL_SELECTION_CHANGED',0)end
     if info.signature~=signature then error('SPATIAL_SELECTION_CHANGED',0)end
     -- A fresh relation prevents a mid-sample seat switch from retaining the old body's arms.
     local now=N.graph(N.win.read,N.base);local r=now:relation(context.avatar)
     if r.status~='VEHICLE'or not N.same(r.vehicle,vehicle)then error('SPATIAL_SEAT_CHANGED',0)end
     g:validate();now:validate();scope()
    end)
    if tagged then detail.revalidation_resource_check=Reference.last_validation;detail.revalidation_node_check=Reference.last_node_check end
    return good,good and 'SPATIAL_REVALIDATED'or tostring(err)
   end
   return chosen,why,stable
  end)
  if detail.module=='WorldUnitTaggedReference'and Reference then detail.resource_check=Reference.last_validation;detail.node_check=Reference.last_node_check end
  if not ok then detail.status='SPATIAL_UNAVAILABLE';detail.error=tostring(list);return nil,'SPATIAL_UNAVAILABLE',detail end
  detail.status=status
  return list,status,detail,validate
 end
 return M
end