code wiki / (root) / nx_nxa_retarget.nx
`nx_nxa_retarget.nx` source

↩ module page · 1091 lines · 51459 B
1// nx_nxa_retarget.nx -- DONOR RETARGET: drive a rigged NXA that carries NO authored clips from a
2// SOURCE rig's POSE, preserving the TARGET's OWN bone lengths BY CONSTRUCTION.
3//
4// WHY (measured 2026-08-23): all five donors report poses_in_library=0 -- they carry rigs but no
5// authored motion, so the visiting cast on /world/beach stand as statues while every other piece
6// of the character stack ships. This organ is the missing leg.
7//
8// THE NAIVE RETARGET IS PROVABLY WRONG, AND THAT PROOF IS WHY THIS FILE EXISTS. In the NXA
9// normative form M x = D(x-b) + b + dt, applying joint j's transform to its own bind position
10// gives M_j b_j = b_j + dt_j. So a posed joint sits at b_j + dt_j and POSED BONE LENGTH IS A PURE
11// FUNCTION OF dt. Copying source dt -- or scaling it by a height ratio -- therefore cannot preserve
12// the target's bone lengths unless the two skeletons are proportionally identical, and ours are
13// emphatically not (104 joints at 1.715 m against 370 joints on a differently-proportioned donor).
14// A dt-transfer retarget stretches and shears limbs on every donor: the exact defect the operator
15// named as awful motion. It is not shipped here.
16//
17// THE ALGORITHM (four lines, and limb length is preserved BY CONSTRUCTION, not by tolerance):
18//   A_j   = conj(D_parent) . D_j                     source: world delta -> local articulation
19//   W_j   = W_parent . A_j                           target: parent-first composition
20//   P_j   = P_parent + W_parent (x) (b'_j - b'_p)    the TARGET's OWN bone vector, ROTATED ONLY
21//   dt'_j = P_j - b'_j
22// The target bone vector is only ever rotated -- never scaled, never replaced -- so no pose this
23// organ can emit is able to change a target bone's length. The limb-length tooth in the gate is a
24// REGRESSION GUARD on that property, not the thing that establishes it.
25//
26// The general form needs a similarity conjugation by each joint's bind orientation. It collapses
27// to the four lines above because NXA bind orientation is IDENTITY BY CONSTRUCTION -- nx_nxa_skin
28// emits SKEL quats as identity and states the reason in its own header (delta-LBS convention:
29// animation is applied RELATIVE to bind). VERIFY THAT BEFORE TRUSTING IT: the `bindquats` verb
30// measures it per asset and is the reason this organ has three verbs instead of one.
31//
32// JOINT MAPPING IS BY TOPOLOGY AND NORMALIZED BIND POSITION, NEVER BY NAME. SKEL carries no names
33// by design, and the donors come from different authoring tools -- a name map would be the
34// classifier-keys-on-a-string defect. The normalized space is the same one nx_nxa_joints uses:
35// every axis divided by the rig's OWN stature extent, so a taller or differently-scaled rig lands
36// in the same space. The stature axis is DERIVED as the largest bind extent, never assumed z-up:
37// the FBX/VRM donors arrive Y-up, which is the axis-convention defect a sibling lane measured in
38// the renderer on the same day.
39//
40// usage: nx_nxa_retarget bindquats <file.nxa>
41//        nx_nxa_retarget map <src.nxa> <dst.nxa>
42//        nx_nxa_retarget retarget <src.nxa> <pose_id> <dst.nxa> [out.nxa] [weight_permil] [emit=pose]
43//        emit=pose (anywhere after <dst.nxa>): publish the POSE LIBRARY entry (W quat + dt per target joint) instead of a
44//        baked VERT, so the output stays a RIG the player can replay, hold and sequence, and nx_nxa_play becomes an
45//        independent witness of the motion this organ measured (2026-09-05, /compare/modding MD3; measured: every baked
46//        donor read poses_in_library=0 joints_posed=0 under nx_nxa_play while the house rig read 104/104). The writer is
47//        nx_nxa_posewrite_lib -- the estate's ONE POSE-section writer, shared with nx_nxa_pose freeze.
48// license_tier: ORIGINAL  expect_exit: 0
49import "nx_syscalls.nx"
50import "nx_nxa.nx"
51import "nx_nxa_fk.nx"
52import "nx_skeleton.nx"
53import "nx_nxa_posewrite_lib.nx"
54
55const NR_Q12: i64 = 4096            // quaternion fixed-point unit (NXA v1 spec)
56const NR_WJ: i64 = 8                // words per SKEL joint (spec: parent,tx,ty,tz,qx,qy,qz,qw)
57const NR_WPE: i64 = 8               // words per POSE entry (spec: joint,qx,qy,qz,qw,dtx,dty,dtz)
58const NR_PERMIL: i64 = 1000
59const NR_INF: i64 = 4               // SKIN influences per vertex, fixed by the format
60const NR_WQ: i64 = 4096             // SKIN weight scale q12, sum = 4096 (spec)
61const NR_FX: i64 = 256              // nx_skeleton weight scale fx256, sum = 256
62// POSE dt lanes are already MODEL units (0.01 mm), not mm: the x100 is applied inside
63// nx_nxa_pose at freeze. The spec paragraph claiming mm is stale -- settled from the record
64// (eaten row 1785380029) by the player lane, and nx_nxa_play ships the same NP_DT_MODEL=1.
65const NR_DT_MODEL: i64 = 1
66const NR_WFULL: i64 = 1000
67const NR_MODE: i64 = 0x1a4          // 0644, matching every sibling NXA writer
68const NR_EXIT_USAGE: i64 = 2
69const NR_EXIT_REFUSE: i64 = 3
70const NR_EXIT_NOSEC: i64 = 5
71const NR_EXIT_NONIDENT: i64 = 1     // bindquats: a measurement outcome, not an error
72
73func nrw(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
74func nrerr(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(2, s, n); return 0 }
75func nrn(v: i64) -> i64 {
  let b: *u8 = sys_mmap(32)
  var x: i64 = v
  if x < 0 { b[0] = 45 as u8; sys_write(1, b, 1); x = 0 - x }
  if x == 0 { b[0] = 48 as u8; sys_write(1, b, 1); return 0 }
  var d: i64 = 0
  var y: i64 = x
  while y > 0 { d = d + 1; y = y / 10 }
  var i: i64 = d
  while i > 0 { i = i - 1; b[i] = ((x % 10) + 48) as u8; x = x / 10 }
  sys_write(1, b, d)
  return 0
87}
88func nr_atoi(s: *u8) -> i64 {
  var v: i64 = 0
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      if c >= 48 { if c <= 57 { v = v * 10 + (c - 48) } }
      i = i + 1
  }
  return v
97}
98func nr_streq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) {
      if a[i] != b[i] { return 0 }
      i = i + 1
  }
  if b[i] != (0 as u8) { return 0 }
  return 1
106}
107func nr_q(p: *i64, i: i64) -> *i64 { return ((p as i64) + i * 32) as *i64 }
108
109// Normalize a bind set into a scale-invariant space and RETURN THE STATURE EXTENT.
110// Every axis is divided by the rig's own largest extent, so proportion is preserved and a
111// differently-scaled rig lands in the same space. Returns -1 if the rig is degenerate.
112func nr_norm(bind: *i64, n: i64, out: *i64) -> i64 {
  if n < 1 { return 0 - 1 }
  let mn: *i64 = sys_mmap(64)
  let mx: *i64 = sys_mmap(64)
  var k: i64 = 0
  while k < 3 { mn[k] = bind[k]; mx[k] = bind[k]; k = k + 1 }
  var j: i64 = 1
  while j < n {
      k = 0
      while k < 3 {
          let v: i64 = bind[j*3+k]
          if v < mn[k] { mn[k] = v }
          if v > mx[k] { mx[k] = v }
          k = k + 1
      }
      j = j + 1
  }
  var se: i64 = mx[0] - mn[0]
  k = 1
  while k < 3 {
      let e: i64 = mx[k] - mn[k]
      if e > se { se = e }
      k = k + 1
  }
  if se <= 0 { return 0 - 1 }
  // Anchor on the ROOT -- joint 0, since parent-first ordering is enforced before this is called,
  // so joint 0 IS the root -- rather than on the per-axis bounding box. A BOUNDING BOX IS
  // POSE-DEPENDENT: a T-posed rig and an A-posed rig have different lateral extents, so
  // box-anchored coordinates shift EVERY joint when only the arms moved. The root does not move
  // with the pose, so anchoring there compares anatomy instead of comparing posture.
  j = 0
  while j < n {
      k = 0
      while k < 3 { out[j*3+k] = (bind[j*3+k] - bind[k]) * NR_PERMIL / se; k = k + 1 }
      j = j + 1
  }
  return se
149}
150func nr_d2(a: *i64, ai: i64, b: *i64, bi: i64) -> i64 {
  let dx: i64 = a[ai*3] - b[bi*3]
  let dy: i64 = a[ai*3+1] - b[bi*3+1]
  let dz: i64 = a[ai*3+2] - b[bi*3+2]
  return dx*dx + dy*dy + dz*dz
155}
156// The admission bound is DERIVED from the target's own geometry: the mean nearest-neighbour
157// spacing between its joints. If the best source match for a joint is farther away than the
158// target's own typical joint spacing, the source rig cannot resolve that joint and the mapping
159// is unreliable -- so it is refused rather than silently producing a plausible-looking pose.
160func nr_mean_nn(nrm: *i64, n: i64) -> i64 {
  if n < 2 { return 0 - 1 }
  var tot: i64 = 0
  var j: i64 = 0
  while j < n {
      var best: i64 = 0 - 1
      var i: i64 = 0
      while i < n {
          if i != j {
              let d: i64 = nr_d2(nrm, j, nrm, i)
              if best < 0 { best = d }
              if d < best { best = d }
          }
          i = i + 1
      }
      tot = tot + nf_isqrt(best)
      j = j + 1
  }
  return tot / n
179}
180func nr_load(path: *u8, lp: *i64) -> *u8 {
  // sys_read_file sizes from the file itself and cannot short-read: the banked law against a
  // hand-picked cap on a file read, which silently truncates its own subject.
  return sys_read_file(path, lp)
184}
185
186// Derive the rig's OWN anatomical frame rather than assuming one. THE DONORS ARRIVE Y-UP WHILE OUR
187// GENERATED RIGS ARE Z-UP -- the same axis-convention defect a sibling lane measured in the renderer
188// (a donor rendering lying flat) and another measured in the soft-tissue solver (refusing donors for
189// having no left-side front vertices in the bust band) on this same day. Assuming largest-extent-is-
190// stature is ALSO wrong here: a T-posed rig's arm span can exceed its height, and these donors are
191// T/A-posed. So the LATERAL axis is identified by BILATERAL SYMMETRY -- a humanoid rig mirrors
192// left-to-right about that axis and about no other -- and of the two remaining axes the taller one is
193// stature. The match tolerance is the rig's OWN mean joint spacing, never a picked fraction.
194func nr_sym(bind: *i64, n: i64, k: i64, tol: i64) -> i64 {
  var mn: i64 = bind[k]
  var mx: i64 = bind[k]
  var j: i64 = 1
  while j < n {
      let v: i64 = bind[j*3+k]
      if v < mn { mn = v }
      if v > mx { mx = v }
      j = j + 1
  }
  let mid2: i64 = mn + mx
  var hit: i64 = 0
  j = 0
  while j < n {
      let want: i64 = mid2 - bind[j*3+k]
      var found: i64 = 0
      var i: i64 = 0
      while i < n {
          var d: i64 = bind[i*3+k] - want
          if d < 0 { d = 0 - d }
          if d <= tol {
              var ok: i64 = 1
              var o: i64 = 0
              while o < 3 {
                  if o != k {
                      var d2: i64 = bind[i*3+o] - bind[j*3+o]
                      if d2 < 0 { d2 = 0 - d2 }
                      if d2 > tol { ok = 0 }
                  }
                  o = o + 1
              }
              if ok == 1 { found = 1 }
          }
          i = i + 1
      }
      hit = hit + found
      j = j + 1
  }
  return hit * NR_PERMIL / n
233}
234func nr_frame(bind: *i64, n: i64, ax: *i64) -> i64 {
  let tol: i64 = nr_mean_nn(bind, n)
  let ext: *i64 = sys_mmap(64)
  var k: i64 = 0
  while k < 3 {
      var mn: i64 = bind[k]
      var mx: i64 = bind[k]
      var j: i64 = 1
      while j < n {
          let v: i64 = bind[j*3+k]
          if v < mn { mn = v }
          if v > mx { mx = v }
          j = j + 1
      }
      ext[k] = mx - mn
      k = k + 1
  }
  var lat: i64 = 0
  var bests: i64 = 0 - 1
  k = 0
  while k < 3 {
      let s: i64 = nr_sym(bind, n, k, tol)
      if s > bests { bests = s; lat = k }
      k = k + 1
  }
  var a1: i64 = 0 - 1
  var a2: i64 = 0 - 1
  k = 0
  while k < 3 {
      if k != lat {
          if a1 < 0 { a1 = k }
          if a1 != k { a2 = k }
      }
      k = k + 1
  }
  var up: i64 = a1
  var dep: i64 = a2
  if ext[a2] > ext[a1] { up = a2; dep = a1 }
  ax[0] = up; ax[1] = lat; ax[2] = dep
  return bests
274}
275func nr_permute(bind: *i64, n: i64, ax: *i64, sg: *i64, out: *i64) -> i64 {
  var j: i64 = 0
  while j < n {
      var k: i64 = 0
      while k < 3 { out[j*3+k] = bind[j*3+ax[k]] * sg[k]; k = k + 1 }
      j = j + 1
  }
  return 0
283}
284// The signed permutation carrying SOURCE raw coordinates into TARGET raw coordinates. A rotation's
285// axis is an AXIAL vector: under a frame change of determinant -1 it picks up that sign, otherwise
286// a mirrored frame would silently reverse every rotation direction.
287func nr_reframe_v(v: *i64, out: *i64, sax: *i64, ssg: *i64, tax: *i64, tsg: *i64) -> i64 {
  var c: i64 = 0
  while c < 3 { out[tax[c]] = v[sax[c]] * ssg[c] * tsg[c]; c = c + 1 }
  return 0
291}
292func nr_frame_det(sax: *i64, ssg: *i64, tax: *i64, tsg: *i64) -> i64 {
  let m: *i64 = sys_mmap(128)
  var i: i64 = 0
  while i < 9 { m[i] = 0; i = i + 1 }
  var c: i64 = 0
  while c < 3 { m[tax[c]*3 + sax[c]] = ssg[c] * tsg[c]; c = c + 1 }
  return m[0]*(m[4]*m[8]-m[5]*m[7]) - m[1]*(m[3]*m[8]-m[5]*m[6]) + m[2]*(m[3]*m[7]-m[4]*m[6])
299}
300
301// Permutation parity of the derived axis triple. Once UP and ANTERIOR are both pinned, handedness
302// is no longer free: the lateral sign is whatever makes the frame's determinant +1, so it is DERIVED
303// rather than searched. That is the whole reason the ambiguity below can be closed.
304func nr_parity(ax: *i64) -> i64 {
  let p: i64 = (ax[1]-ax[0]) * (ax[2]-ax[0]) * (ax[2]-ax[1])
  if p < 0 { return 0 - 1 }
  return 1
308}
309// ANTERIOR DIRECTION FROM THE MESH -- the cue that handedness actually needs.
310// MEASURED, NOT ASSUMED: a bilaterally symmetric point set is near-ISOMETRIC under mirroring, so a
311// symmetric cue (joint positions, mapping distance) cannot carry handedness at all -- every rig here
312// scores sym_permil=1000 and the argmin between mirrored options picked arbitrarily, which posed two
313// of four donors MIRRORED while every limb-length tooth passed (a mirror preserves every length it
314// checks). The asymmetry a humanoid actually has is FRONT/BACK, and it lives in the MESH, not in the
315// skeleton: at the FOOT band the toes extend anteriorly far past the heel, and at the HEAD band the
316// face extends anteriorly past the back of the skull. Both bands are measured INDEPENDENTLY and must
317// AGREE; when they disagree the cue is ambiguous and this returns 0 so the caller abstains BY NAME.
318// An arbitrary pick that is right half the time is worse than a refusal: it produces confident wrong
319// output. The band height is the rig's OWN mean joint spacing, never a picked fraction of stature.
320// The band height at an extremity is that extremity's OWN BONE LENGTH -- the local anatomical
321// scale, taken where the measurement is actually made. A GLOBAL mean joint spacing was the defect:
322// it averages dense finger clusters together with long limb bones, so on a ~110-joint rig the band
323// grew tall enough that BOTH bands covered the ENTIRE MESH and the two-witness test became vacuous
324// (measured: paladin foot=head=2184, dark_knight foot=head=-140 -- byte-identical, i.e. the same
325// vertex set answering twice).
326func nr_extremity_band(bind: *i64, par: *i64, n: i64, upax: i64, want_max: i64) -> i64 {
  if n < 2 { return 0 }
  var je: i64 = 0
  var ve: i64 = bind[upax]
  var j: i64 = 1
  while j < n {
      let v: i64 = bind[j*3+upax]
      if want_max == 1 { if v > ve { ve = v; je = j } }
      if want_max == 0 { if v < ve { ve = v; je = j } }
      j = j + 1
  }
  let pj: i64 = par[je]
  if pj >= 0 {
      let ax2: i64 = bind[pj*3] - bind[je*3]
      let ay2: i64 = bind[pj*3+1] - bind[je*3+1]
      let az2: i64 = bind[pj*3+2] - bind[je*3+2]
      let l: i64 = nf_isqrt(ax2*ax2 + ay2*ay2 + az2*az2)
      if l > 0 { return l }
  }
  // the extremity is the root (or a zero-length bone): fall back to its nearest neighbour joint
  var best: i64 = 0 - 1
  var i: i64 = 0
  while i < n {
      if i != je {
          let dx: i64 = bind[i*3] - bind[je*3]
          let dy: i64 = bind[i*3+1] - bind[je*3+1]
          let dz: i64 = bind[i*3+2] - bind[je*3+2]
          let d: i64 = dx*dx + dy*dy + dz*dz
          if best < 0 { best = d }
          if d < best { best = d }
      }
      i = i + 1
  }
  if best < 0 { return 0 }
  return nf_isqrt(best)
361}
362// THE BAND IS DERIVED FROM THE MESH ITSELF: the SMALLEST vertical window at an extremity that holds
363// enough vertices to be a witness. No picked fraction of stature -- the population requirement sizes
364// it and the mesh's own density decides how tall that is, so a dense rig gets a tight band and a
365// sparse one gets a wider band automatically.
366//
367// THIS REPLACES BONE LENGTH, AND THAT SUBSTITUTION IS ALSO A DIAGNOSTIC. Bone length is a property of
368// the SKELETON, so a single mis-placed joint makes the extremity bone enormous and the band nonsense:
369// dark_knight and paladin measured 48,293 and 74,484-unit extremity bones and were refused for
370// overlap. If a mesh-derived band resolves them, the bone was the defect; if it does not, the
371// geometry is, and that is the same root cause as the fragmented render on the same asset.
372func nr_band_for_pop(vert: *i64, nv: i64, upax: i64, want_max: i64, minpop: i64, ulo: i64, uhi: i64) -> i64 {
  var lo: i64 = 0
  var hi: i64 = uhi - ulo
  if hi < 1 { return 0 }
  while lo < hi {
      let mid: i64 = (lo + hi) / 2
      var c: i64 = 0
      var i: i64 = 0
      while i < nv {
          let u: i64 = vert[i*3+upax]
          if want_max == 0 { if u <= ulo + mid { c = c + 1 } }
          if want_max == 1 { if u >= uhi - mid { c = c + 1 } }
          i = i + 1
      }
      if c >= minpop { hi = mid }
      if c < minpop { lo = mid + 1 }
  }
  return lo
390}
391func nr_anterior(vert: *i64, nv: i64, ax: *i64, blo: i64, bhi: i64, minpop: i64, ev: *i64) -> i64 {
  ev[4] = 0
  if nv < 1 { return 0 }
  if blo < 1 { return 0 }
  if bhi < 1 { return 0 }
  var umin: i64 = vert[ax[0]]
  var umax: i64 = umin
  var dmin: i64 = vert[ax[2]]
  var dmax: i64 = dmin
  var i: i64 = 1
  while i < nv {
      let u: i64 = vert[i*3+ax[0]]
      let d: i64 = vert[i*3+ax[2]]
      if u < umin { umin = u }
      if u > umax { umax = u }
      if d < dmin { dmin = d }
      if d > dmax { dmax = d }
      i = i + 1
  }
  // TWO WITNESSES THAT ARE SECRETLY THE SAME WITNESS AGREE ONE HUNDRED PERCENT OF THE TIME.
  // The bands must be DISJOINT before their agreement means anything -- this is the shared-
  // failure-mode law arriving inside one organ. Overlap is reported (ev[4]) so the caller can
  // abstain BY NAME on THIS cause rather than on a generic ambiguity.
  // Bands sized from the MESH (see nr_band_for_pop). The bone-derived values are still reported in
  // ev[5]/ev[6] beside them, because the COMPARISON is the diagnostic: a bone band far larger than
  // the mesh band means that extremity's joint is mis-placed, not that the rig is unusual.
  let mblo: i64 = nr_band_for_pop(vert, nv, ax[0], 0, minpop, umin, umax)
  let mbhi: i64 = nr_band_for_pop(vert, nv, ax[0], 1, minpop, umin, umax)
  ev[5] = blo
  ev[6] = bhi
  ev[7] = mblo
  ev[8] = mbhi
  if mblo < 1 { ev[4] = 2; return 0 }
  if mbhi < 1 { ev[4] = 2; return 0 }
  if umin + mblo >= umax - mbhi { ev[4] = 1; return 0 }
  let mid: i64 = (dmin + dmax) / 2
  var lo_s: i64 = 0
  var lo_n: i64 = 0
  var hi_s: i64 = 0
  var hi_n: i64 = 0
  i = 0
  while i < nv {
      let u: i64 = vert[i*3+ax[0]]
      let d: i64 = vert[i*3+ax[2]] - mid
      if u <= umin + mblo { lo_s = lo_s + d; lo_n = lo_n + 1 }
      if u >= umax - mbhi { hi_s = hi_s + d; hi_n = hi_n + 1 }
      i = i + 1
  }
  // DISJOINTNESS IS NECESSARY BUT NOT SUFFICIENT: a band can be disjoint and still be too thin to
  // be a witness. Measured on toon3d8: its toe-tip bone is 1 unit long, so the foot band held
  // exactly 2 VERTICES and a whole handedness verdict rested on them. A band must therefore also
  // be POPULATED, and the floor is derived from the asset itself -- a mesh region holding fewer
  // points than the rig has JOINTS is a few stray vertices, not a shape.
  if lo_n < minpop { ev[4] = 2; return 0 }
  if hi_n < minpop { ev[4] = 2; return 0 }
  if lo_n < 1 { return 0 }
  if hi_n < 1 { return 0 }
  let lo: i64 = lo_s / lo_n
  let hi: i64 = hi_s / hi_n
  ev[0] = lo; ev[1] = hi; ev[2] = lo_n; ev[3] = hi_n
  if lo > 0 { if hi >= 0 { return 1 } }
  if lo < 0 { if hi <= 0 { return 0 - 1 } }
  // The bands CONTRADICT. They are not equally trustworthy, and the reason is anatomical rather
  // than convenient: TOES project anteriorly on every standing humanoid, while the HEAD band is
  // contaminated by HAIR AND HEADWEAR, which hang POSTERIORLY. Measured on the real corpus:
  // toon3d8's long back-hair drove its head band to -2925 against a foot band of +11638, and
  // ref9d's head band read only +1475 against a foot band of -9493 -- in both cases the head is
  // the weaker and the dirtier signal. So a contradicting head vote overrides the foot ONLY when
  // it is STRICTLY STRONGER; when it is, the shape is not a standing humanoid and we abstain
  // rather than guess. dark_witch needs none of this: +62699 foot and +88153 head both agree.
  var alo: i64 = lo
  if alo < 0 { alo = 0 - alo }
  var ahi: i64 = hi
  if ahi < 0 { ahi = 0 - ahi }
  if ahi > alo { return 0 }
  if lo > 0 { return 1 }
  if lo < 0 { return 0 - 1 }
  return 0
469}
470
471// ---- verb: bindquats -- MEASURE the identity-bind convention this organ's math depends on ------
472func nr_bindquats(path: *u8) -> i64 {
  let lp: *i64 = sys_mmap(64)
  let b: *u8 = nr_load(path, lp)
  if b as i64 == 0 { nrerr("NXA-RETARGET-REFUSE cannot read input\n" as *u8); return NR_EXIT_REFUSE }
  let flen: i64 = lp[0]
  let w: *i64 = b as *i64
  let swo: i64 = nxa_find(b, flen, nxa_tag4("SKEL" as *u8))
  if swo < 0 { nrerr("NXA-RETARGET-REFUSE no valid SKEL section\n" as *u8); return NR_EXIT_NOSEC }
  let nj: i64 = w[swo]
  var nonid: i64 = 0
  var j: i64 = 0
  while j < nj {
      let so: i64 = swo + 1 + j * NR_WJ
      var bad: i64 = 0
      if w[so+4] != 0 { bad = 1 }
      if w[so+5] != 0 { bad = 1 }
      if w[so+6] != 0 { bad = 1 }
      if w[so+7] != NR_Q12 { bad = 1 }
      if bad == 1 { nonid = nonid + 1 }
      j = j + 1
  }
  nrw("  joints=" as *u8); nrn(nj)
  nrw(" nonidentity_bind_quats=" as *u8); nrn(nonid)
  nrw(" identity_bind_convention=" as *u8)
  if nonid == 0 { nrw("HOLDS\n" as *u8) }
  if nonid != 0 { nrw("VIOLATED\n" as *u8) }
  if nonid != 0 { return NR_EXIT_NONIDENT }
  return 0
500}
501
502func main(argc: i64, argv: *i64) -> i64 {
  if argc < 3 {
      nrerr("usage: nx_nxa_retarget bindquats <file.nxa>\n" as *u8)
      nrerr("       nx_nxa_retarget map <src.nxa> <dst.nxa>\n" as *u8)
      nrerr("       nx_nxa_retarget retarget <src.nxa> <pose_id> <dst.nxa> [out.nxa] [weight_permil] [emit=pose]\n" as *u8)
      return NR_EXIT_USAGE
  }
  let verb: *u8 = argv[1] as *u8
  if nr_streq(verb, "bindquats" as *u8) == 1 { return nr_bindquats(argv[2] as *u8) }
511
  let ismap: i64 = nr_streq(verb, "map" as *u8)
  let isret: i64 = nr_streq(verb, "retarget" as *u8)
  if ismap == 0 { if isret == 0 {
      nrerr("NXA-RETARGET-REFUSE unknown verb\n" as *u8)
      return NR_EXIT_USAGE
  } }
  // <out.nxa> is OPTIONAL: with it the posed asset is published, without it the run MEASURES ONLY.
  // A gate must be able to exercise this organ without writing artifacts as a side effect, and the
  // shared subprocess primitive (gk_run_capture) carries four arguments -- so the measuring form
  // has to fit in four. Publishing is the extra, not the baseline.
  if isret == 1 { if argc < 5 {
      nrerr("usage: nx_nxa_retarget retarget <src.nxa> <pose_id> <dst.nxa> [out.nxa] [weight_permil] [emit=pose]\n" as *u8)
      return NR_EXIT_USAGE
  } }
526
  let spath: *u8 = argv[2] as *u8
  var pose_id: i64 = 0
  var dpath: *u8 = argv[3] as *u8
  var outp: *u8 = 0 as *u8
  var wpm: i64 = NR_WFULL
  var emitpose: i64 = 0
  if isret == 1 {
      pose_id = nr_atoi(argv[3] as *u8)
      dpath = argv[4] as *u8
      // trailing args are SCANNED, not slotted: `emit=pose` may sit anywhere after <dst.nxa>, so the positional
      // [out.nxa] [weight_permil] contract every existing caller holds is untouched.
      var ai: i64 = 5
      var slot: i64 = 0
      while ai < argc {
          let a: *u8 = argv[ai] as *u8
          if nr_streq(a, "emit=pose" as *u8) == 1 { emitpose = 1 }
          if nr_streq(a, "emit=pose" as *u8) == 0 {
              if slot == 0 { outp = a }
              if slot == 1 { wpm = nr_atoi(a) }
              slot = slot + 1
          }
          ai = ai + 1
      }
      if wpm < 0 { wpm = 0 }
      if wpm > NR_WFULL { wpm = NR_WFULL }
  }
553
  // ---- load source ----------------------------------------------------------------------
  let slp: *i64 = sys_mmap(64)
  let sb: *u8 = nr_load(spath, slp)
  if sb as i64 == 0 { nrerr("NXA-RETARGET-REFUSE cannot read source\n" as *u8); return NR_EXIT_REFUSE }
  let sflen: i64 = slp[0]
  let sw: *i64 = sb as *i64
  let sswo: i64 = nxa_find(sb, sflen, nxa_tag4("SKEL" as *u8))
  if sswo < 0 { nrerr("NXA-RETARGET-REFUSE source has no valid SKEL\n" as *u8); return NR_EXIT_NOSEC }
  let ns: i64 = sw[sswo]
  if ns < 1 { nrerr("NXA-RETARGET-REFUSE source SKEL is empty\n" as *u8); return NR_EXIT_REFUSE }
564
  // ---- load target ----------------------------------------------------------------------
  let dlp: *i64 = sys_mmap(64)
  let db: *u8 = nr_load(dpath, dlp)
  if db as i64 == 0 { nrerr("NXA-RETARGET-REFUSE cannot read target\n" as *u8); return NR_EXIT_REFUSE }
  let dflen: i64 = dlp[0]
  let dw: *i64 = db as *i64
  let dswo: i64 = nxa_find(db, dflen, nxa_tag4("SKEL" as *u8))
  if dswo < 0 { nrerr("NXA-RETARGET-REFUSE target has no valid SKEL (asset is not rigged)\n" as *u8); return NR_EXIT_NOSEC }
  let nt: i64 = dw[dswo]
  if nt < 1 { nrerr("NXA-RETARGET-REFUSE target SKEL is empty\n" as *u8); return NR_EXIT_REFUSE }
575
  // ---- unpack binds + parents -----------------------------------------------------------
  let sbind: *i64 = sys_mmap(ns * 3 * 8)
  let spar: *i64 = sys_mmap(ns * 8)
  var j: i64 = 0
  while j < ns {
      let so: i64 = sswo + 1 + j * NR_WJ
      spar[j] = sw[so]
      sbind[j*3] = sw[so+1]; sbind[j*3+1] = sw[so+2]; sbind[j*3+2] = sw[so+3]
      j = j + 1
  }
  let tbind: *i64 = sys_mmap(nt * 3 * 8)
  let tpar: *i64 = sys_mmap(nt * 8)
  j = 0
  var order_bad: i64 = 0
  while j < nt {
      let so: i64 = dswo + 1 + j * NR_WJ
      tpar[j] = dw[so]
      if tpar[j] >= j { order_bad = order_bad + 1 }
      tbind[j*3] = dw[so+1]; tbind[j*3+1] = dw[so+2]; tbind[j*3+2] = dw[so+3]
      j = j + 1
  }
  // The four-line composition is parent-first and cannot be evaluated out of order. A SKEL whose
  // parents are not emitted before their children is REFUSED BY NAME rather than composed against
  // an unwritten parent, which would read as a plausible but wrong pose.
  if order_bad != 0 {
      nrerr("NXA-RETARGET-REFUSE target SKEL is not parent-first ordered\n" as *u8)
      return NR_EXIT_REFUSE
  }
604
  // ---- canonical anatomical frames, DERIVED per rig ---------------------------------------
  let sax: *i64 = sys_mmap(64)
  let tax: *i64 = sys_mmap(64)
  let ssym: i64 = nr_frame(sbind, ns, sax)
  let tsym: i64 = nr_frame(tbind, nt, tax)
  let ssg: *i64 = sys_mmap(64)
  let tsg: *i64 = sys_mmap(64)
  ssg[0] = 1; ssg[1] = 1; ssg[2] = 1
  let scan: *i64 = sys_mmap(ns * 3 * 8)
  nr_permute(sbind, ns, sax, ssg, scan)
  let snrm: *i64 = sys_mmap(ns * 3 * 8)
  let sse: i64 = nr_norm(scan, ns, snrm)
  if sse < 0 { nrerr("NXA-RETARGET-REFUSE source rig has zero extent\n" as *u8); return NR_EXIT_REFUSE }
618
  // Lateral and depth SIGN are searched rather than guessed: all four combinations are mapped and
  // the lowest total mapping distance is taken.
  // *** MEASURED LIMITATION, AND A CORRECTION TO THIS ORGAN'S OWN FIRST CLAIM. ***
  // v1 of this comment said the search RESOLVES HANDEDNESS FROM THE DATA. IT DOES NOT, and the
  // live run proved it: every rig here measures sym_permil=1000, i.e. BILATERALLY SYMMETRIC, and a
  // symmetric point set is very nearly ISOMETRIC UNDER MIRRORING -- so both handedness options
  // score almost the same total distance and the argmin picks between near-ties essentially
  // arbitrarily. The evidence is in the numbers: frame_det came out +1 for toon3d8 and
  // dark_knight but -1 for dark_witch and paladin, on four ordinary humanoids that should all
  // agree. A mirrored frame swaps left and right, which is a wrong pose no limb-length tooth can
  // catch -- exactly the awful-motion class.
  // THE FIX IS NAMED, NOT GUESSED: handedness has to come from an ASYMMETRIC cue, because a
  // symmetric one cannot carry the information. Front/back is that cue (a face, a nose, a chest
  // are forward and do not mirror), and it lives in the MESH, not in the joint positions this
  // search sees. Until that lands, the lateral sign on any given donor is UNPROVEN and the pose
  // it produces may be mirrored; frame_det is printed on every run so a reader can see which.
  let tcan: *i64 = sys_mmap(nt * 3 * 8)
  let bnrm: *i64 = sys_mmap(nt * 3 * 8)
  let map: *i64 = sys_mmap(nt * 8)
  // HANDEDNESS IS DERIVED, NOT SEARCHED. The mesh carries the front/back asymmetry the skeleton
  // cannot; once UP and ANTERIOR are pinned the lateral sign is forced to whatever makes the
  // frame determinant +1, so both rigs land in the SAME handed frame by construction.
  let svwo: i64 = nxa_find(sb, sflen, nxa_tag4("VERT" as *u8))
  let tvwo: i64 = nxa_find(db, dflen, nxa_tag4("VERT" as *u8))
  if svwo < 0 { nrerr("NXA-RETARGET-REFUSE source has no valid VERT to derive anterior from\n" as *u8); return NR_EXIT_NOSEC }
  if tvwo < 0 { nrerr("NXA-RETARGET-REFUSE target has no valid VERT to derive anterior from\n" as *u8); return NR_EXIT_NOSEC }
  let svp: *i64 = ((sw as i64) + (svwo+1)*8) as *i64
  let tvp: *i64 = ((dw as i64) + (tvwo+1)*8) as *i64
  // 16 words: the evidence block now carries ev[0..8] -- foot, head, both counts, the abstain
  // cause, and BOTH band sources. A 64-byte (8-word) allocation was one word short and the arena
  // canary caught it as ARENA-OVERRUN on the very first run. Sized with headroom and NAMED, so the
  // next field added does not silently walk off the end.
  let sev: *i64 = sys_mmap(128)
  let tev: *i64 = sys_mmap(128)
  let sblo: i64 = nr_extremity_band(sbind, spar, ns, sax[0], 0)
  let sbhi: i64 = nr_extremity_band(sbind, spar, ns, sax[0], 1)
  let tblo: i64 = nr_extremity_band(tbind, tpar, nt, tax[0], 0)
  let tbhi: i64 = nr_extremity_band(tbind, tpar, nt, tax[0], 1)
  let sant: i64 = nr_anterior(svp, sw[svwo], sax, sblo, sbhi, ns, sev)
  let tant: i64 = nr_anterior(tvp, dw[tvwo], tax, tblo, tbhi, nt, tev)
  nrw("  src_anterior=" as *u8); nrn(sant)
  nrw(" foot=" as *u8); nrn(sev[0]); nrw(" head=" as *u8); nrn(sev[1])
  nrw(" bands=" as *u8); nrn(sblo); nrw("/" as *u8); nrn(sbhi)
  nrw(" nverts=" as *u8); nrn(sev[2]); nrw("/" as *u8); nrn(sev[3])
  nrw(" overlap=" as *u8); nrn(sev[4]); nrw("\n" as *u8)
  nrw("  tgt_anterior=" as *u8); nrn(tant)
  nrw(" foot=" as *u8); nrn(tev[0]); nrw(" head=" as *u8); nrn(tev[1])
  nrw(" meshband=" as *u8); nrn(tev[7]); nrw("/" as *u8); nrn(tev[8])
  nrw(" boneband=" as *u8); nrn(tev[5]); nrw("/" as *u8); nrn(tev[6])
  nrw(" nverts=" as *u8); nrn(tev[2]); nrw("/" as *u8); nrn(tev[3])
  nrw(" overlap=" as *u8); nrn(tev[4]); nrw("\n" as *u8)
  if sant == 0 {
      if sev[4] == 1 { nrerr("NXA-RETARGET-REFUSE source foot and head bands OVERLAP -- they are the same witness twice, so their agreement proves nothing\n" as *u8) }
      if sev[4] == 2 { nrerr("NXA-RETARGET-REFUSE source anterior band holds fewer vertices than the rig has joints -- too thin to be a witness\n" as *u8) }
      if sev[4] == 0 { nrerr("NXA-RETARGET-REFUSE source anterior is AMBIGUOUS (a stronger head vote contradicts the foot) -- abstaining rather than picking a handedness\n" as *u8) }
      return NR_EXIT_REFUSE
  }
  if tant == 0 {
      if tev[4] == 1 { nrerr("NXA-RETARGET-REFUSE target foot and head bands OVERLAP -- they are the same witness twice, so their agreement proves nothing\n" as *u8) }
      if tev[4] == 2 { nrerr("NXA-RETARGET-REFUSE target anterior band holds fewer vertices than the rig has joints -- too thin to be a witness\n" as *u8) }
      if tev[4] == 0 { nrerr("NXA-RETARGET-REFUSE target anterior is AMBIGUOUS (a stronger head vote contradicts the foot) -- abstaining rather than picking a handedness\n" as *u8) }
      return NR_EXIT_REFUSE
  }
  ssg[2] = sant; ssg[1] = nr_parity(sax) * sant
  tsg[0] = 1; tsg[2] = tant; tsg[1] = nr_parity(tax) * tant
  let bslat: i64 = tsg[1]
  let bsdep: i64 = tsg[2]
  nr_permute(sbind, ns, sax, ssg, scan)
  if nr_norm(scan, ns, snrm) < 0 { nrerr("NXA-RETARGET-REFUSE source rig has zero extent\n" as *u8); return NR_EXIT_REFUSE }
  nr_permute(tbind, nt, tax, tsg, tcan)
  let tse: i64 = nr_norm(tcan, nt, bnrm)
  if tse < 0 { nrerr("NXA-RETARGET-REFUSE target rig has zero extent\n" as *u8); return NR_EXIT_REFUSE }
  var maxd: i64 = 0
  var totd: i64 = 0
  j = 0
  while j < nt {
      var best: i64 = 0 - 1
      var bi: i64 = 0
      var i: i64 = 0
      while i < ns {
          let d: i64 = nr_d2(bnrm, j, snrm, i)
          if best < 0 { best = d; bi = i }
          if d < best { best = d; bi = i }
          i = i + 1
      }
      map[j] = bi
      let dd: i64 = nf_isqrt(best)
      if dd > maxd { maxd = dd }
      totd = totd + dd
      j = j + 1
  }
  let bdst: *i64 = sys_mmap(nt * 8)
  j = 0
  while j < nt { bdst[j] = nf_isqrt(nr_d2(bnrm, j, snrm, map[j])); j = j + 1 }
  // THE ADMISSION BOUND IS THE SOURCE'S OWN JOINT SPACING, NOT THE TARGET'S. The question a
  // mapping has to answer is whether the SOURCE can resolve a given joint, so the scale that
  // decides it belongs to the source. Deriving it from the target was measured wrong on the first
  // live run: a 370-joint donor packs its joints 3 permil apart, so every match from a 104-joint
  // source read as LOOSE and the whole retarget refused -- a bound that indicted the source rig
  // for the target's density. A target joint the source genuinely cannot resolve (a finger, a
  // facial bone) is not an error either: it INHERITS its parent's articulation and rides along,
  // which is what a rigid sub-chain should do, instead of fabricating motion for it.
  let bound: i64 = nr_mean_nn(snrm, ns)
  nrw("  src_frame up=" as *u8); nrn(sax[0]); nrw(" lat=" as *u8); nrn(sax[1]); nrw(" dep=" as *u8); nrn(sax[2])
  nrw(" sym_permil=" as *u8); nrn(ssym); nrw("\n" as *u8)
  nrw("  tgt_frame up=" as *u8); nrn(tax[0]); nrw(" lat=" as *u8); nrn(tax[1]); nrw(" dep=" as *u8); nrn(tax[2])
  nrw(" sym_permil=" as *u8); nrn(tsym)
  nrw(" lat_sign=" as *u8); nrn(bslat); nrw(" dep_sign=" as *u8); nrn(bsdep); nrw("\n" as *u8)
  nrw("  src_joints=" as *u8); nrn(ns)
  nrw(" tgt_joints=" as *u8); nrn(nt)
  nrw(" map_max_permil=" as *u8); nrn(maxd)
  nrw(" map_mean_permil=" as *u8); nrn(totd / nt)
  nrw(" admit_bound_permil=" as *u8); nrn(bound)
  nrw("\n" as *u8)
  var nmapped: i64 = 0
  var ninherit: i64 = 0
  j = 0
  while j < nt {
      if bdst[j] <= bound { nmapped = nmapped + 1 }
      if bdst[j] > bound { ninherit = ninherit + 1 }
      j = j + 1
  }
  nrw("  mapped=" as *u8); nrn(nmapped)
  nrw(" inherited=" as *u8); nrn(ninherit)
  nrw(" of=" as *u8); nrn(nt)
  nrw("\n" as *u8)
  // A partition that does not sum is a leak, so it is asserted rather than assumed.
  if nmapped + ninherit != nt {
      nrerr("NXA-RETARGET-REFUSE mapped/inherited partition does not sum to the joint count\n" as *u8)
      return NR_EXIT_REFUSE
  }
  // Refused only when the source can resolve NOTHING: then there is no articulation to transfer
  // and any output would be the bind pose wearing a retarget's name.
  if nmapped == 0 {
      nrerr("NXA-RETARGET-REFUSE source rig resolves no target joint within its own joint spacing\n" as *u8)
      return NR_EXIT_REFUSE
  }
  if ismap == 1 {
      nrw("  verdict=ADMITTED\n" as *u8)
      return 0
  }
760
  // ---- source pose ----------------------------------------------------------------------
  let sD: *i64 = sys_mmap(ns * 4 * 8)
  let sdt: *i64 = sys_mmap(ns * 3 * 8)
  j = 0
  while j < ns {
      sD[j*4] = 0; sD[j*4+1] = 0; sD[j*4+2] = 0; sD[j*4+3] = NR_Q12
      sdt[j*3] = 0; sdt[j*3+1] = 0; sdt[j*3+2] = 0
      j = j + 1
  }
  var applied: i64 = 0
  let pwo: i64 = nxa_find(sb, sflen, nxa_tag4("POSE" as *u8))
  if pwo < 0 {
      nrerr("NXA-RETARGET-REFUSE source carries no POSE library to retarget from\n" as *u8)
      return NR_EXIT_NOSEC
  }
  let np: i64 = sw[pwo]
  var cur: i64 = pwo + 1
  var p: i64 = 0
  while p < np {
      let pid: i64 = sw[cur]
      let ne: i64 = sw[cur+1]
      if pid == pose_id {
          var e: i64 = 0
          while e < ne {
              let eo: i64 = cur + 2 + e * NR_WPE
              let jj: i64 = sw[eo]
              if jj >= 0 { if jj < ns {
                  sD[jj*4] = sw[eo+1]; sD[jj*4+1] = sw[eo+2]
                  sD[jj*4+2] = sw[eo+3]; sD[jj*4+3] = sw[eo+4]
                  sdt[jj*3] = sw[eo+5]; sdt[jj*3+1] = sw[eo+6]; sdt[jj*3+2] = sw[eo+7]
                  applied = applied + 1
              } }
              e = e + 1
          }
      }
      cur = cur + 2 + ne * NR_WPE
      p = p + 1
  }
  if applied == 0 {
      nrerr("NXA-RETARGET-REFUSE source POSE library has no entries for that pose_id\n" as *u8)
      return NR_EXIT_REFUSE
  }
803
  // Reframe the source pose into the TARGET's raw axis convention BEFORE composing. Without this
  // a rotation about the source's stature axis would be applied about the target's depth axis --
  // the mapping would be geometrically correct and the motion still wrong.
  let det: i64 = nr_frame_det(sax, ssg, tax, tsg)
  let tmpv: *i64 = sys_mmap(64)
  let tmpo: *i64 = sys_mmap(64)
  j = 0
  while j < ns {
      tmpv[0] = sD[j*4]; tmpv[1] = sD[j*4+1]; tmpv[2] = sD[j*4+2]
      nr_reframe_v(tmpv, tmpo, sax, ssg, tax, tsg)
      sD[j*4] = tmpo[0] * det; sD[j*4+1] = tmpo[1] * det; sD[j*4+2] = tmpo[2] * det
      tmpv[0] = sdt[j*3]; tmpv[1] = sdt[j*3+1]; tmpv[2] = sdt[j*3+2]
      nr_reframe_v(tmpv, tmpo, sax, ssg, tax, tsg)
      sdt[j*3] = tmpo[0]; sdt[j*3+1] = tmpo[1]; sdt[j*3+2] = tmpo[2]
      j = j + 1
  }
  nrw("  frame_det=" as *u8); nrn(det); nrw("\n" as *u8)
821
  // ---- the four lines -------------------------------------------------------------------
  let W: *i64 = sys_mmap(nt * 4 * 8)
  let P: *i64 = sys_mmap(nt * 3 * 8)
  let tdt: *i64 = sys_mmap(nt * 3 * 8)
  let cq: *i64 = sys_mmap(64)
  let aq: *i64 = sys_mmap(64)
  let o3: *i64 = sys_mmap(64)
  let scr: *i64 = sys_mmap(256)
  j = 0
  while j < nt {
      let s: i64 = map[j]
      let pj: i64 = tpar[j]
      if pj < 0 {
          // root: no parent to conjugate against, so A = D. Root translation is the ONE quantity
          // that must cross skeletons by size, so it is scaled by the ratio of the two rigs' own
          // measured stature extents -- derived from the assets, never a picked factor.
          W[j*4] = sD[s*4]; W[j*4+1] = sD[s*4+1]; W[j*4+2] = sD[s*4+2]; W[j*4+3] = sD[s*4+3]
          P[j*3]   = tbind[j*3]   + sdt[s*3]   * tse / sse
          P[j*3+1] = tbind[j*3+1] + sdt[s*3+1] * tse / sse
          P[j*3+2] = tbind[j*3+2] + sdt[s*3+2] * tse / sse
      }
      if pj >= 0 {
          let sp: i64 = map[pj]
          // A joint the source cannot resolve within its OWN joint spacing gets IDENTITY local
          // articulation, so it rides its parent rigidly instead of being handed a rotation
          // borrowed from whatever joint happened to be nearest. Fabricated articulation on an
          // unresolvable joint is exactly the awful-motion class: it looks like animation and is
          // not derived from anything.
          aq[0] = 0; aq[1] = 0; aq[2] = 0; aq[3] = NR_Q12
          if bdst[j] <= bound {
              nf_qconj(nr_q(sD, sp), cq)
              nf_qmul(cq, nr_q(sD, s), aq)
          }
          nf_qmul(nr_q(W, pj), aq, nr_q(W, j))
          nf_qrotv(nr_q(W, pj), tbind[j*3] - tbind[pj*3], tbind[j*3+1] - tbind[pj*3+1], tbind[j*3+2] - tbind[pj*3+2], o3, scr)
          P[j*3]   = P[pj*3]   + o3[0]
          P[j*3+1] = P[pj*3+1] + o3[1]
          P[j*3+2] = P[pj*3+2] + o3[2]
      }
      tdt[j*3]   = P[j*3]   - tbind[j*3]
      tdt[j*3+1] = P[j*3+1] - tbind[j*3+1]
      tdt[j*3+2] = P[j*3+2] - tbind[j*3+2]
      j = j + 1
  }
866
  // ---- hold at wpm/1000 so a SEQUENCE can be emitted -------------------------------------
  // nlerp from identity with the spec's shortest-path sign flip: a delta whose w is negative sits
  // on the far side of the quaternion double cover, and blending toward it without the flip takes
  // the long way round, which renders as a limb rotating the wrong way.
  if wpm < NR_WFULL {
      j = 0
      while j < nt {
          var qx: i64 = W[j*4]
          var qy: i64 = W[j*4+1]
          var qz: i64 = W[j*4+2]
          var qw: i64 = W[j*4+3]
          if qw < 0 { qx = 0 - qx; qy = 0 - qy; qz = 0 - qz; qw = 0 - qw }
          W[j*4]   = qx * wpm / NR_WFULL
          W[j*4+1] = qy * wpm / NR_WFULL
          W[j*4+2] = qz * wpm / NR_WFULL
          W[j*4+3] = (NR_Q12 * (NR_WFULL - wpm) + qw * wpm) / NR_WFULL
          nf_qnorm(nr_q(W, j))
          tdt[j*3]   = tdt[j*3]   * wpm / NR_WFULL
          tdt[j*3+1] = tdt[j*3+1] * wpm / NR_WFULL
          tdt[j*3+2] = tdt[j*3+2] * wpm / NR_WFULL
          j = j + 1
      }
  }
890
  // ---- limb-length residual: the property the algorithm preserves BY CONSTRUCTION ---------
  // Reported, not merely asserted, so a regression is visible as a number rather than a verdict.
  var maxlen: i64 = 0
  j = 0
  while j < nt {
      let pj: i64 = tpar[j]
      if pj >= 0 {
          let ax: i64 = tbind[j*3] - tbind[pj*3]
          let ay: i64 = tbind[j*3+1] - tbind[pj*3+1]
          let az: i64 = tbind[j*3+2] - tbind[pj*3+2]
          let bx: i64 = P[j*3] - P[pj*3]
          let by: i64 = P[j*3+1] - P[pj*3+1]
          let bz: i64 = P[j*3+2] - P[pj*3+2]
          let la: i64 = nf_isqrt(ax*ax + ay*ay + az*az)
          let lb: i64 = nf_isqrt(bx*bx + by*by + bz*bz)
          var dl: i64 = lb - la
          if dl < 0 { dl = 0 - dl }
          if dl > maxlen { maxlen = dl }
      }
      j = j + 1
  }
  nrw("  pose_entries_applied=" as *u8); nrn(applied)
  nrw(" weight_permil=" as *u8); nrn(wpm)
  nrw(" limb_len_residual_max=" as *u8); nrn(maxlen)
  nrw("\n" as *u8)
916
  // ---- skin the target through the SHARED evaluator ---------------------------------------
  let vwo: i64 = nxa_find(db, dflen, nxa_tag4("VERT" as *u8))
  let kwo: i64 = nxa_find(db, dflen, nxa_tag4("SKIN" as *u8))
  if vwo < 0 { nrerr("NXA-RETARGET-REFUSE target has no valid VERT\n" as *u8); return NR_EXIT_NOSEC }
  if kwo < 0 { nrerr("NXA-RETARGET-REFUSE target has no valid SKIN\n" as *u8); return NR_EXIT_NOSEC }
  let nv: i64 = dw[vwo]
  let nsk: i64 = dw[kwo]
  if nsk != nv {
      nrerr("NXA-RETARGET-REFUSE target SKIN vertex count does not match VERT count\n" as *u8)
      return NR_EXIT_REFUSE
  }
  let abytes: i64 = sk_bytes_for(nt, nv, NR_INF)
  let base: i64 = sys_mmap(abytes) as i64
  if base == 0 { nrerr("NXA-RETARGET-REFUSE arena allocation failed\n" as *u8); return NR_EXIT_REFUSE }
  if sk_init_cap(base, nt, nv, NR_INF) < 0 {
      nrerr("NXA-RETARGET-REFUSE evaluator rejected the declared capacity\n" as *u8)
      return NR_EXIT_REFUSE
  }
  let mm: *i64 = sys_mmap(128)
  let tv: *i64 = sys_mmap(64)
  j = 0
  while j < nt {
      let bx: i64 = tbind[j*3]
      let by: i64 = tbind[j*3+1]
      let bz: i64 = tbind[j*3+2]
      let bi: i64 = sk_add_bone(base, tpar[j], bx, by, bz)
      if bi < 0 { nrerr("NXA-RETARGET-REFUSE bone capacity exceeded\n" as *u8); return NR_EXIT_REFUSE }
      // D -> 3x3 fx256 by rotating the fx256 basis: column k = D e_k (the sibling player's form).
      var k: i64 = 0
      while k < 3 {
          var ex: i64 = 0
          var ey: i64 = 0
          var ez: i64 = 0
          if k == 0 { ex = NR_FX }
          if k == 1 { ey = NR_FX }
          if k == 2 { ez = NR_FX }
          nf_qrotv(nr_q(W, j), ex, ey, ez, o3, scr)
          mm[k] = o3[0]; mm[3+k] = o3[1]; mm[6+k] = o3[2]
          k = k + 1
      }
      let bp: *i64 = sk_bone(base, bi)
      k = 0
      while k < 9 { bp[6+k] = mm[k]; k = k + 1 }
      sk_matvec(mm, bx, by, bz, tv)
      bp[15] = bx - tv[0] + tdt[j*3]   * NR_DT_MODEL
      bp[16] = by - tv[1] + tdt[j*3+1] * NR_DT_MODEL
      bp[17] = bz - tv[2] + tdt[j*3+2] * NR_DT_MODEL
      bp[18] = 1
      j = j + 1
  }
  let bs: *i64 = sys_mmap(64)
  let ws: *i64 = sys_mmap(64)
  var i2: i64 = 0
  while i2 < nv {
      let ko: i64 = kwo + 1 + i2 * NR_WJ
      var tot: i64 = 0
      var bigk: i64 = 0
      var bigw: i64 = 0 - 1
      var k2: i64 = 0
      while k2 < NR_INF {
          let jw: i64 = dw[ko + 4 + k2]
          let cw: i64 = jw * NR_FX / NR_WQ
          bs[k2] = dw[ko + k2]
          ws[k2] = cw
          tot = tot + cw
          if jw > bigw { bigw = jw; bigk = k2 }
          k2 = k2 + 1
      }
      // residual folded into the largest influence so the sum is EXACTLY fx256: an under-sum
      // shrinks the vertex toward the origin, which is silent volume loss.
      if tot > 0 { ws[bigk] = ws[bigk] + (NR_FX - tot) }
      let vo: i64 = vwo + 1 + i2 * 3
      if sk_add_vert_n(base, bs, ws, NR_INF, dw[vo], dw[vo+1], dw[vo+2]) < 0 {
          nrerr("NXA-RETARGET-REFUSE vertex capacity exceeded\n" as *u8)
          return NR_EXIT_REFUSE
      }
      i2 = i2 + 1
  }
  sk_skin(base)
996
  // ---- measure BEFORE publishing ----------------------------------------------------------
  // A WRITER MUST NOT MUTATE A READER'S INPUT. The publish below overwrites the VERT payload in
  // place -- the very buffer this loop compares the skinned output against -- so the measurement
  // is taken first, and the publish writes into its OWN copy. The sibling player shipped a v1
  // that reversed this and printed max_disp=0 for six correctly-posed assets: a silent,
  // self-inflicted false negative that reads exactly like broken skinning.
  var maxd2: i64 = 0
  var mind2: i64 = 0 - 1
  i2 = 0
  while i2 < nv {
      let vo: i64 = vwo + 1 + i2 * 3
      let op: *i64 = sk_out(base, i2)
      let ddx: i64 = op[0] - dw[vo]
      let ddy: i64 = op[1] - dw[vo+1]
      let ddz: i64 = op[2] - dw[vo+2]
      let dd: i64 = nf_isqrt(ddx*ddx + ddy*ddy + ddz*ddz)
      if dd > maxd2 { maxd2 = dd }
      if mind2 < 0 { mind2 = dd }
      if dd < mind2 { mind2 = dd }
      i2 = i2 + 1
  }
  nrw("  verts=" as *u8); nrn(nv)
  nrw(" max_disp=" as *u8); nrn(maxd2)
  nrw(" min_disp=" as *u8); nrn(mind2)
  nrw(" spread=" as *u8); nrn(maxd2 - mind2)
  nrw("\n" as *u8)
1023
  if outp as i64 != 0 { if emitpose == 1 {
      // emit=pose: publish the POSE LIBRARY, not a baked mesh. W and tdt per target joint ARE the spec's POSE entry
      // (world-delta quat about bind + dt in model units -- the same pair the skinning above consumed), so a player
      // replays this file with the exact LBS the ANIM path proves and nx_nxa_play becomes an INDEPENDENT witness of
      // the motion measured above. VERT stays at bind, so the asset is still a rig and not a statue; a second run with
      // another pose id ADDS to the library, the same id REPLACES. MEASURED 2026-09-05: the baked form read
      // poses_in_library=0 joints_posed=0 on every donor while the house rig read 104/104.
      let jl: *i64 = sys_mmap(nt * 8)
      let pst: *i64 = sys_mmap(64)
      var jj2: i64 = 0
      while jj2 < nt { jl[jj2] = jj2; jj2 = jj2 + 1 }
      let pwb: i64 = npw_write(db, dflen, pose_id, jl, W, tdt, nt, outp, pst)
      if pwb < 0 {
          nrerr("NXA-RETARGET-REFUSE POSE publish failed (nx_nxa_posewrite_lib code below)\n" as *u8)
          nrw("  posewrite_code=" as *u8); nrn(pwb); nrw("\n" as *u8)
          return NR_EXIT_REFUSE
      }
      nrw("  published=" as *u8); nrn(pwb)
      nrw(" of=" as *u8); nrn(pwb)
      nrw(" mode=pose pose_id=" as *u8); nrn(pose_id)
      nrw(" entries=" as *u8); nrn(pst[NPW_ST_N])
      nrw(" kept_poses=" as *u8); nrn(pst[NPW_ST_KEPT])
      nrw(" sections=" as *u8); nrn(pst[NPW_ST_SECTIONS])
      nrw("\n" as *u8)
      return 0
  } }
  if outp as i64 != 0 {
      // Publish posed VERT IN PLACE into our OWN copy: the payload keeps its word length, so only
      // the VERT section checksum and the TOC checksum are recomputed. No TOC surgery, no section
      // insertion -- the same publish shape the player already ships and proves.
      let olp: *i64 = sys_mmap(64)
      let ob: *u8 = nr_load(dpath, olp)
      if ob as i64 == 0 { nrerr("NXA-RETARGET-REFUSE cannot re-read target for publish\n" as *u8); return NR_EXIT_REFUSE }
      let oflen: i64 = olp[0]
      let ow: *i64 = ob as *i64
      let ovwo: i64 = nxa_find(ob, oflen, nxa_tag4("VERT" as *u8))
      if ovwo < 0 { nrerr("NXA-RETARGET-REFUSE publish copy lost VERT\n" as *u8); return NR_EXIT_REFUSE }
      i2 = 0
      while i2 < nv {
          let vo: i64 = ovwo + 1 + i2 * 3
          let op: *i64 = sk_out(base, i2)
          ow[vo] = op[0]; ow[vo+1] = op[1]; ow[vo+2] = op[2]
          i2 = i2 + 1
      }
      let ns2: i64 = ow[2]
      let tb2: *i64 = ((ob as i64) + 32) as *i64
      var s2: i64 = 0
      while s2 < ns2 {
          if tb2[s2*4] == nxa_tag4("VERT" as *u8) {
              let off: i64 = tb2[s2*4+1]
              let wl: i64 = tb2[s2*4+2]
              let pw: *i64 = ((ob as i64) + off) as *i64
              tb2[s2*4+3] = nxa_check2(1, pw, wl)
          }
          s2 = s2 + 1
      }
      ow[3] = nxa_check2(1, tb2, ns2*4)
      let fd: i64 = sys_openat_wr(outp, NR_MODE)
      if fd < 0 { nrerr("NXA-RETARGET-REFUSE cannot open output\n" as *u8); return NR_EXIT_REFUSE }
      let wrote: i64 = sys_write(fd, ob, oflen)
      sys_close(fd)
      nrw("  published=" as *u8); nrn(wrote)
      nrw(" of=" as *u8); nrn(oflen)
      nrw("\n" as *u8)
      if wrote != oflen { nrerr("NXA-RETARGET-REFUSE short write on publish\n" as *u8); return NR_EXIT_REFUSE }
  }
  return 0
1091}
nx_nxa_retarget.nx source

`nx_nxa_retarget.nx` source
