-- Read-only mech health reader. No game writes, no native game calls.
-- Layout (same on game.dll 6AA96B14 and 6AB3B43F; authorized by native.lua code guards):
--   Health runtime record = [health+0x1058] + index*0x1B8
--     +0x14          hull current HP (same field DRIVER HUD uses as body HP)
--     +0xF8 + 4*i    zone i current HP
--   Health settings record (0x5650 bytes)
--     +0x000         hull maximum HP
--     +0x208 + i*0x228 + 0x60   zone i name hash
--     +0x208 + i*0x228 + 0xE8   zone i maximum HP
return function(N,Z)
 local R={}
 local MAX_ZONES=12
 local ZONE_SPAN=0x208+MAX_ZONES*0x228
 local function config_address(g,net,hm,d)
  local j=g:lookup(g:table(hm+0x1070),d.entity)
  if j~=nil then return N.ptr(g:watch(hm+0x10B0,8),0)+j*0x5650 end
  local t=N.ptr(g:watch(net+0xF12B78,8),0);local start=N.mod64hex(d.resource,1002)
  for step=0,63 do
   local row=g:watch(t+((start+step)%1002)*16,16);local key=N.hex64(row,0)
   if key==d.resource then
    local k=N.u32(row,8);if k>=1002 then error('Health settings index',0) end
    return t+0x3EA0+k*0x5650
   elseif key=='0000000000000000' then break end
  end
  error('no identity-linked Health configuration',0)
 end
 local function read_span(g,p,n)
  local parts={};local off=0
  while off<n do local k=math.min(4096,n-off);parts[#parts+1]=g:read(p+off,k);off=off+k end
  return table.concat(parts)
 end
 -- Returns table on success, or nil,reason,kind where kind is
 -- NOT_SEATED | NOT_MECH | UNVERIFIED | TRANSIENT | INVALID | UNAVAILABLE.
 function R.sample(avatar,now)
  local ok,why=N.ensure(now)
  if not ok then return nil,why,'UNAVAILABLE' end
  local g=N.sample_graph()
  local good,result,reason,kind=pcall(function()
   local rel=g:relation(avatar)
   if rel.status~='VEHICLE' then return nil,rel.status,'NOT_SEATED' end
   local d=rel.vehicle;local model=Z.models[d.resource]
   if not model then return nil,'resource '..tostring(d.resource),'NOT_MECH' end
   local net,hm=g:root('network'),g:root('health')
   g:roundtrip(net,d)
   local hi,hd=g:component(hm,d.entity,0x1030,0x1048)
   if hi==nil or not N.same(hd,d) then error('no matching mech Health owner',0) end
   local data=g:read(N.ptr(g:watch(hm+0x1058,8),0)+hi*0x1B8,0x1B8)
   local cfg=read_span(g,config_address(g,net,hm,d),ZONE_SPAN)
   local hull_max=N.i32(cfg,0);local hull=N.i32(data,0x14)
   if hull<0 and hull>-1000000 then hull=0 end
   if hull_max<=0 or hull_max>1000000 then error('invalid hull maximum',0) end
   local zones,unknown,unk={},0,{}
   for i=0,MAX_ZONES-1 do
    local z=0x208+i*0x228
    local h=string.format('%08x',N.u32(cfg,z+0x60))
    if h=='00000000' then break end
    local mx=N.i32(cfg,z+0xE8)
    if mx<=0 or mx>1000000 then error('invalid zone maximum',0) end
    local info=Z.names[h];if not info then unknown=unknown+1;unk[#unk+1]=h..':'..mx end
    local hp=N.i32(data,0xF8+4*i)
    if hp<0 and hp>-1000000 then hp=0 end
    zones[#zones+1]={index=i,hash=h,info=info,hp=hp,max=mx,valid=hp>=0 and hp<=mx}
   end
   -- Recheck every identity/table watch after the value reads.
   g:validate()
   if unknown>0 or #zones==0 then
    return nil,string.format('%s zones=%d unknown=%d [%s]',model.name,#zones,unknown,table.concat(unk,' ')),'UNVERIFIED'
   end
   return {model=model,vehicle=d,hull=hull,hull_max=hull_max,hull_valid=hull>=0 and hull<=hull_max,zones=zones,
    calls=g.calls,bytes=g.bytes}
  end)
  if good then return result,reason,kind end
  local msg=tostring(result)
  if msg=='incomplete native read' then return nil,msg,'TRANSIENT' end
  return nil,msg,'INVALID'
 end
 return R
end