`nx_handcheck.nx` source

↩ module page · 734 lines · 33646 B
1// nx_handcheck.nx -- THE HAND STRUCTURE JUDGE over an NXA SKEL (operator 2026-09-01: "the hands are
2// bad"). It is the SIBLING OF nx_footcheck and deliberately mirrors its contract -- check / selftest,
3// one measured report, one predicate made of things a hand IS rather than a blended score -- because
4// two judges for two ends of the same limb must not have two different shapes.
5//
6// WHY IT EXISTS: the hands were the ONE named character defect in this estate with NO instrument at
7// all. nx_clipcheck measures limb-vs-torso and limb-vs-floor; nx_footcheck measures the distal foot;
8// nothing measured a hand. Grading therefore depended entirely on the operator's eye.
9//
10// THE STRUCTURAL PROBLEM, AND WHY THIS IS NOT NAME MATCHING: NXA's SKEL carries NO JOINT NAMES, by
11// design (nx_nxa_joints.nx states it and quotes nx_nxa_rig_emit: "SKEL carries no names by design").
12// So a hand cannot be looked up -- it must be DERIVED FROM TOPOLOGY. A hand is the only place on a
13// humanoid where three or more TERMINAL SIMPLE CHAINS hang off one attachment. That is what this
14// organ finds. Nothing here knows a joint index, so the judge keeps working when joints are added or
15// reordered ahead of it -- the same structural stance nx_footcheck takes with its rotation.
16//
17// THE ANATOMICAL CANON IS CITED, NOT DIALLED. Buryanov and Kotiuk, "Proportions of Hand Segments",
18// Int. J. Morphol. 28(3):755-758, 2010 (open access; mirror
19// knowledge/fetched/cmp_handcheck_buryanov2010.pdf, sha256 ec2a49be..., 66 adult hands by X-ray with
20// a radiopaque ruler and no scaling error). Their Table I lengths in mm, reconstructed and then
21// INDEPENDENTLY CONFIRMED by their own Table II ratio row for every one of the five rays -- two
22// instruments inside one document agreeing:
23//     ray  distal  medial  proximal  metacarpal      Tab.II ratio (pd:pm:pp:m)
24//     I    21.67     --      31.57     46.22         1 : --  : 1.5 : 2.1
25//     II   15.82   22.38     39.78     68.12         1 : 1.4 : 2.5 : 4.3
26//     III  17.40   26.33     44.63     64.60         1 : 1.5 : 2.6 : 3.7
27//     IV   17.30   25.65     41.37     58.00         1 : 1.5 : 2.4 : 3.4
28//     V    15.96   18.11     32.74     53.69         1 : 1.1 : 2.1 : 3.4
29// TWO LAWS FALL OUT OF THAT TABLE AND BOTH ARE ENFORCED HERE:
30//  (1) MONOTONIC DISTAL SHORTENING -- proximal > medial > distal holds in ALL FIVE rays without
31//      exception. It is dimensionless, so it survives any stylisation of hand size. It is the STRICT
32//      clause here and it needs no tolerance at all.
33//  (2) PHALANX COUNT -- four fingers carry THREE phalanges and the thumb carries TWO (the paper's
34//      medial column is empty for ray I, and its text names "even different phalanges numbers").
35//      In a rig a chain of L joints spans L-1 bones, so a finger is a 4-joint chain and a thumb a
36//      3-joint chain.
37//
38// DECLARED IMPRECISION -- name it or the next reader trusts it as exact:
39//  - v1 measures the BIND SKELETON. It does NOT read SKIN weights, so it cannot yet say whether the
40//    hand is a distinct skinned region or fused to the forearm; and it does NOT read POSE or ANIM, so
41//    it says nothing about a hand during motion. Both are named gaps, not silent ones.
42//  - digit interpenetration is measured JOINT-TO-JOINT, not mesh-to-mesh. It catches the fused-mitten
43//    class (two digits occupying one another) and will miss a thin surface graze.
44//  - the up axis is derived as the rig's LONGEST extent, exactly as nx_nxa_joints.nx derives it.
45//    THAT IS A DUPLICATE RULER AND IT IS NAMED HERE RATHER THAN LEFT SILENT: nx_nxa_joints is a
46//    PROGRAM with a main(), so there is no importable function today. The correct fix is to extract
47//    its axis derivation into a lib and have both organs compose it; this organ is written so that
48//    swap is one function body.
49//  - one intermediate bone between the attachment and the digits (a palm or carpal bone) is merged,
50//    so wrist{thumb} plus palm{4 fingers} reads as one five-digit hand. Deeper nesting is NOT merged
51//    and is reported as separate hubs rather than guessed at.
52//
53//   nx_handcheck check <file.nxa>   -> the measured report and verdict for a real asset
54//   nx_handcheck dump  <file.nxa>   -> the joint tree and every digit chain found (measurement aid)
55//   nx_handcheck selftest           -> gv gate: proves the JUDGE discriminates, on fixtures
56// exit: 0 GREEN | 1 RED | 2 usage | 3 unreadable | 4 UNOBSERVABLE no hand chain (abstain, never pass)
57// license_tier: ORIGINAL  expect_exit: 0  No hw writes (Rule 26).
58import "nx_syscalls.nx"
59import "nx_nxa.nx"
60import "nx_gate_verdict.nx"
61
62const HC_WPJ: i64 = 8              // SKEL record: [parent][x][y][z][qx][qy][qz][qw]
63const HC_MAXJ: i64 = 4096
64const HC_MAXD: i64 = 24            // digit chains tracked per hub
65const HC_MAXH: i64 = 8             // hubs tracked
66const HC_MAXCH: i64 = 24           // joints tracked per digit chain
67const HC_Q: i64 = 1000
68const HC_BIG: i64 = 1000000000
69// a digit is a terminal chain of at least this many JOINTS (2 joints = 1 bone = a stub digit).
70const HC_MIN_CHAIN: i64 = 2
71// three terminal chains on one attachment is the smallest thing that is a hand rather than a fork.
72const HC_MIN_HUB_DIGITS: i64 = 3
73// CITED (Buryanov and Kotiuk Tab. I and II): five rays, four of them with three phalanges.
74const HC_DIGITS_CANON: i64 = 5
75const HC_FINGER_BONES: i64 = 3
76const HC_THUMB_BONES: i64 = 2
77const HC_MIN_3BONE: i64 = 4
78// UPPER bounds only. The LOWER bound is monotonicity, which is enforced by its own clause -- one
79// invariant must not get two rulers. Measured envelope: proximal/medial 1613..1808 permil and
80// medial/distal 1135..1513 permil. These ceilings are those maxima widened for stylisation and are
81// PICKED, not derived, so they are wrong in the direction of ACCEPTING a hand rather than rejecting.
82const HC_R_PPPM_MAX: i64 = 2600
83const HC_R_PMPD_MAX: i64 = 2600
84// PICKED, wrong-toward-accept: a thumb opposed by less than this reads as a rake, not a hand.
85// 150 permil of cosine deviation is about 32 degrees; a human thumb sits far past it.
86const HC_THUMB_OPP_MIN: i64 = 150
87// PICKED, wrong-toward-accept: two joints of DIFFERENT digits closer than this fraction of the mean
88// bone length are occupying one another. 100 permil of a mean phalanx is about 3 mm on an adult hand.
89const HC_FUSE_PERMIL: i64 = 100
90// hands sit above the hip; a multi-chain hub below this fraction of rig height is a FOOT, not a hand.
91// Relative to the rig's own extent, so it carries across scales.
92const HC_HAND_MIN_H01: i64 = 150
93const HC_OUT: i64 = 32
94const HC_NEWTON: i64 = 64
95const HC_SQRTCAP: i64 = 65536
96
97func hc_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
98func hc_puts(s: *u8) -> i64 { sys_write(1, s, hc_slen(s)); return 0 }
99func hc_pn(v: i64) -> i64 {
  if v == 0 { sys_write(1, "0" as *u8, 1); return 0 }
  var m: i64 = v
  if m < 0 { sys_write(1, "-" as *u8, 1); m = 0 - m }
  let t: *u8 = sys_mmap(32)
  var k: i64 = 0
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  let o: *u8 = sys_mmap(32)
  var i: i64 = 0
  while i < k { o[i] = t[k - 1 - i]; i = i + 1 }
  sys_write(1, o, k)
  return 0
111}
112func hc_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
117}
118// integer square root, Newton then exact correction. Distances here are in the SKEL's own units
119// (0.01 mm on the shipped rigs) and every published figure is a RATIO, so the unit never leaves here.
120func hc_isqrt(v: i64) -> i64 {
  if v <= 0 { return 0 }
  var g: i64 = v
  if g > HC_SQRTCAP { g = HC_SQRTCAP }
  var i: i64 = 0
  while i < HC_NEWTON {
      let ng: i64 = (g + v / g) / 2
      if ng == g { i = HC_NEWTON } else { g = ng; i = i + 1 }
  }
  if g < 1 { g = 1 }
  while g * g > v { g = g - 1 }
  while (g + 1) * (g + 1) <= v { g = g + 1 }
  return g
133}
134func hc_dist(W: *i64, sw: i64, a: i64, b: i64) -> i64 {
  let pa: i64 = sw + 1 + a * HC_WPJ
  let pb: i64 = sw + 1 + b * HC_WPJ
  let dx: i64 = W[pa+1] - W[pb+1]
  let dy: i64 = W[pa+2] - W[pb+2]
  let dz: i64 = W[pa+3] - W[pb+3]
  return hc_isqrt(dx*dx + dy*dy + dz*dz)
141}
142
143// ---- topology --------------------------------------------------------------------------------
144// NC[j] = number of children of j. A parent field outside [0,nj) or equal to j is a ROOT.
145func hc_children(W: *i64, sw: i64, nj: i64, NC: *i64) -> i64 {
  var j: i64 = 0
  while j < nj { NC[j] = 0; j = j + 1 }
  j = 0
  while j < nj {
      let p: i64 = W[sw + 1 + j * HC_WPJ]
      if p >= 0 { if p < nj { if p != j { NC[p] = NC[p] + 1 } } }
      j = j + 1
  }
  return 0
155}
156// the only child of j, or -1. Used to walk a simple path without building an adjacency list.
157func hc_only_child(W: *i64, sw: i64, nj: i64, j: i64) -> i64 {
  var found: i64 = 0 - 1
  var c: i64 = 0
  while c < nj {
      let p: i64 = W[sw + 1 + c * HC_WPJ]
      if p == j { if c != j { found = c } }
      c = c + 1
  }
  return found
166}
167// If the subtree rooted at d is a SIMPLE PATH, write its joints into CH and return the joint count.
168// Otherwise return 0 -- a branching subtree is an arm or a spine, never a digit.
169func hc_chain(W: *i64, sw: i64, nj: i64, NC: *i64, d: i64, CH: *i64) -> i64 {
  var n: i64 = 0
  var cur: i64 = d
  var go: i64 = 1
  while go == 1 {
      if n >= HC_MAXCH { return 0 }
      CH[n] = cur
      n = n + 1
      if NC[cur] == 0 { go = 0 } else {
          if NC[cur] > 1 { return 0 }
          cur = hc_only_child(W, sw, nj, cur)
          if cur < 0 { return 0 }
      }
  }
  return n
184}
185// count the terminal chains attached to j that are long enough to be a digit
186func hc_hub_digits(W: *i64, sw: i64, nj: i64, NC: *i64, j: i64, CH: *i64) -> i64 {
  var n: i64 = 0
  var c: i64 = 0
  while c < nj {
      let p: i64 = W[sw + 1 + c * HC_WPJ]
      if p == j { if c != j {
          if hc_chain(W, sw, nj, NC, c, CH) >= HC_MIN_CHAIN { n = n + 1 }
      } }
      c = c + 1
  }
  return n
197}
198
199// ---- the measurement -------------------------------------------------------------------------
200// out[0]=joints [1]=live_hubs [2]=hub_joint [3]=digits [4]=bones_total [5]=digits_3bone
201// out[6]=digits_2bone [7]=mono_violations [8]=fused_pairs [9]=thumb_opp_permil
202// out[10]=taper_violations [11]=hub_h01_permil [12]=mean_bone [13]=up_axis [14]=min_chain
203// out[15]=max_chain [16]=hand_hubs [17]=worst_taper_permil
204// RETURNS 0 measured | -1 no SKEL joints | -2 NO DIGIT HUB AT ALL | -3 hubs exist but none above the
205// hand band (a foot). Every negative is an ABSTENTION, never a pass.
206func hc_measure(W: *i64, sw: i64, nj: i64, out: *i64) -> i64 {
  var z: i64 = 0
  while z < HC_OUT { out[z] = 0; z = z + 1 }
  out[0] = nj
  if nj <= 0 { return 0 - 1 }
  if nj > HC_MAXJ { return 0 - 1 }
  let NC: *i64 = sys_mmap(HC_MAXJ*8) as *i64
  hc_children(W, sw, nj, NC)
  // up axis = the rig's LONGEST extent (see the duplicate-ruler note in the header)
  let mn: *i64 = sys_mmap(32) as *i64
  let mx: *i64 = sys_mmap(32) as *i64
  var a: i64 = 0
  while a < 3 { mn[a] = HC_BIG; mx[a] = 0 - HC_BIG; a = a + 1 }
  var j: i64 = 0
  while j < nj {
      let base: i64 = sw + 1 + j * HC_WPJ
      a = 0
      while a < 3 {
          let v: i64 = W[base + 1 + a]
          if v < mn[a] { mn[a] = v }
          if v > mx[a] { mx[a] = v }
          a = a + 1
      }
      j = j + 1
  }
  var up: i64 = 0
  var span: i64 = mx[0] - mn[0]
  a = 1
  while a < 3 { if mx[a] - mn[a] > span { span = mx[a] - mn[a]; up = a } a = a + 1 }
  out[13] = up
  // hubs: every joint hosting HC_MIN_HUB_DIGITS or more terminal chains
  let CH: *i64 = sys_mmap(HC_MAXCH*8) as *i64
  let HUB: *i64 = sys_mmap(HC_MAXH*8) as *i64
  let HUBN: *i64 = sys_mmap(HC_MAXH*8) as *i64
  var nhub: i64 = 0
  j = 0
  while j < nj {
      let d: i64 = hc_hub_digits(W, sw, nj, NC, j, CH)
      if d >= HC_MIN_HUB_DIGITS { if nhub < HC_MAXH { HUB[nhub] = j; HUBN[nhub] = d; nhub = nhub + 1 } }
      j = j + 1
  }
  // ONE-LEVEL MERGE: a hub whose PARENT is also a hub is a palm under a wrist. Fold the child hub
  // into the parent so wrist{thumb} plus palm{4 fingers} reads as one five-digit hand. Deeper
  // nesting is deliberately NOT folded -- it is reported as separate hubs rather than guessed at.
  var h: i64 = 0
  while h < nhub {
      let pj: i64 = W[sw + 1 + HUB[h] * HC_WPJ]
      var k: i64 = 0
      while k < nhub {
          if HUB[k] == pj { if HUBN[h] > 0 { HUBN[k] = HUBN[k] + HUBN[h]; HUBN[h] = 0 } }
          k = k + 1
      }
      h = h + 1
  }
  var live: i64 = 0
  h = 0
  while h < nhub { if HUBN[h] > 0 { live = live + 1 } h = h + 1 }
  out[1] = live
  if live == 0 { return 0 - 2 }
  // pick the hand: the LIVE hub with the most digits that sits above HC_HAND_MIN_H01. Height is
  // normalised to the rig's own extent, so a toe hub (h01 near zero) can never be graded as a hand.
  var best: i64 = 0 - 1
  var bestn: i64 = 0
  var hands: i64 = 0
  h = 0
  while h < nhub {
      if HUBN[h] > 0 {
          let y: i64 = W[sw + 1 + HUB[h] * HC_WPJ + 1 + up]
          var h01: i64 = 0
          if span > 0 { h01 = (y - mn[up]) * HC_Q / span }
          if h01 >= HC_HAND_MIN_H01 {
              hands = hands + 1
              if HUBN[h] > bestn { bestn = HUBN[h]; best = h; out[11] = h01 }
          }
      }
      h = h + 1
  }
  out[16] = hands
  if best < 0 { return 0 - 3 }
  let hub: i64 = HUB[best]
  out[2] = hub
  // walk every digit on the chosen hub -- and on a child hub if one was folded into it
  let DR: *i64 = sys_mmap(HC_MAXD*8) as *i64            // digit chain roots
  let DL: *i64 = sys_mmap(HC_MAXD*8) as *i64            // joints in each chain
  let DJ: *i64 = sys_mmap(HC_MAXD*HC_MAXCH*8) as *i64   // the joints themselves
  var nd: i64 = 0
  var host: i64 = 0
  while host < nj {
      var is_host: i64 = 0
      if host == hub { is_host = 1 }
      if W[sw + 1 + host * HC_WPJ] == hub {
          if hc_hub_digits(W, sw, nj, NC, host, CH) >= HC_MIN_HUB_DIGITS { is_host = 1 }
      }
      if is_host == 1 {
          var c: i64 = 0
          while c < nj {
              if W[sw + 1 + c * HC_WPJ] == host { if c != host {
                  let L: i64 = hc_chain(W, sw, nj, NC, c, CH)
                  if L >= HC_MIN_CHAIN { if nd < HC_MAXD {
                      DR[nd] = c
                      DL[nd] = L
                      var q: i64 = 0
                      while q < L { DJ[nd*HC_MAXCH + q] = CH[q]; q = q + 1 }
                      nd = nd + 1
                  } }
              } }
              c = c + 1
          }
      }
      host = host + 1
  }
  out[3] = nd
  if nd == 0 { return 0 - 2 }
  // bones, monotonicity, taper ratios
  var bones_total: i64 = 0
  var bone_sum: i64 = 0
  var d3: i64 = 0
  var d2: i64 = 0
  var mono: i64 = 0
  var rv: i64 = 0
  var worst: i64 = 0
  var minc: i64 = HC_BIG
  var maxc: i64 = 0
  var di: i64 = 0
  while di < nd {
      let L: i64 = DL[di]
      if L < minc { minc = L }
      if L > maxc { maxc = L }
      let nb: i64 = L - 1
      bones_total = bones_total + nb
      if nb == HC_FINGER_BONES { d3 = d3 + 1 }
      if nb == HC_THUMB_BONES { d2 = d2 + 1 }
      var bi: i64 = 0
      while bi < nb {
          let bl: i64 = hc_dist(W, sw, DJ[di*HC_MAXCH + bi], DJ[di*HC_MAXCH + bi + 1])
          bone_sum = bone_sum + bl
          if bi + 1 < nb {
              let nxt: i64 = hc_dist(W, sw, DJ[di*HC_MAXCH + bi + 1], DJ[di*HC_MAXCH + bi + 2])
              // (1) MONOTONIC DISTAL SHORTENING -- cited, strict, no tolerance
              if nxt >= bl { mono = mono + 1 }
              // taper CEILING only; the floor is the clause above
              if nxt > 0 {
                  let r: i64 = bl * HC_Q / nxt
                  if r > worst { worst = r }
                  var lim: i64 = HC_R_PMPD_MAX
                  if bi == 0 { lim = HC_R_PPPM_MAX }
                  if r > lim { rv = rv + 1 }
              }
          }
          bi = bi + 1
      }
      di = di + 1
  }
  out[4] = bones_total
  out[5] = d3
  out[6] = d2
  out[7] = mono
  out[10] = rv
  out[14] = minc
  out[15] = maxc
  out[17] = worst
  var meanb: i64 = 0
  if bones_total > 0 { meanb = bone_sum / bones_total }
  out[12] = meanb
  // FUSION: any two joints of DIFFERENT digits closer than HC_FUSE_PERMIL of the mean bone length
  // are occupying one another. This is the fused-mitten class the eye reports as "bad hands".
  let fuse: i64 = meanb * HC_FUSE_PERMIL / HC_Q
  var fused: i64 = 0
  var ai: i64 = 0
  while ai < nd {
      var bj: i64 = ai + 1
      while bj < nd {
          var hit: i64 = 0
          var p: i64 = 0
          while p < DL[ai] {
              var q2: i64 = 0
              while q2 < DL[bj] {
                  if hc_dist(W, sw, DJ[ai*HC_MAXCH + p], DJ[bj*HC_MAXCH + q2]) <= fuse { hit = 1 }
                  q2 = q2 + 1
              }
              p = p + 1
          }
          if hit == 1 { fused = fused + 1 }
          bj = bj + 1
      }
      ai = ai + 1
  }
  out[8] = fused
  // THUMB OPPOSITION: each digit's root-to-tip direction, compared pairwise by cosine in permil.
  // The opposed digit is the one whose WORST agreement with another digit is lowest. A mitten has
  // every digit parallel, so its opposition collapses to zero -- which is exactly the defect.
  var opp: i64 = 0
  if nd >= 2 {
      var worst_pair: i64 = HC_Q
      ai = 0
      while ai < nd {
          let ra: i64 = sw + 1 + DR[ai] * HC_WPJ
          let ta: i64 = sw + 1 + DJ[ai*HC_MAXCH + DL[ai] - 1] * HC_WPJ
          let ax2: i64 = W[ta+1] - W[ra+1]
          let ay2: i64 = W[ta+2] - W[ra+2]
          let az2: i64 = W[ta+3] - W[ra+3]
          let la: i64 = hc_isqrt(ax2*ax2 + ay2*ay2 + az2*az2)
          var bj2: i64 = ai + 1
          while bj2 < nd {
              let rb: i64 = sw + 1 + DR[bj2] * HC_WPJ
              let tb: i64 = sw + 1 + DJ[bj2*HC_MAXCH + DL[bj2] - 1] * HC_WPJ
              let bx: i64 = W[tb+1] - W[rb+1]
              let by: i64 = W[tb+2] - W[rb+2]
              let bz: i64 = W[tb+3] - W[rb+3]
              let lb: i64 = hc_isqrt(bx*bx + by*by + bz*bz)
              if la > 0 { if lb > 0 {
                  let cs: i64 = (ax2*bx + ay2*by + az2*bz) * HC_Q / (la * lb)
                  if cs < worst_pair { worst_pair = cs }
              } }
              bj2 = bj2 + 1
          }
          ai = ai + 1
      }
      opp = HC_Q - worst_pair
      if opp < 0 { opp = 0 }
  }
  out[9] = opp
  return 0
429}
430
431// THE PREDICATE. Every clause is a thing a hand IS. No weights, no blended number.
432func hc_ok(out: *i64) -> i64 {
  if out[3] != HC_DIGITS_CANON { return 0 }
  if out[5] < HC_MIN_3BONE { return 0 }
  if out[7] > 0 { return 0 }
  if out[8] > 0 { return 0 }
  if out[10] > 0 { return 0 }
  if out[9] < HC_THUMB_OPP_MIN { return 0 }
  return 1
440}
441func hc_report(out: *i64) -> i64 {
  hc_puts("{\x22organ\x22:\x22nx_handcheck\x22,\x22v\x22:1" as *u8)
  hc_puts(",\x22joints\x22:" as *u8); hc_pn(out[0])
  hc_puts(",\x22digit_hubs\x22:" as *u8); hc_pn(out[1])
  hc_puts(",\x22hand_hubs\x22:" as *u8); hc_pn(out[16])
  hc_puts(",\x22hub_joint\x22:" as *u8); hc_pn(out[2])
  hc_puts(",\x22hub_h01_permil\x22:" as *u8); hc_pn(out[11])
  hc_puts(",\x22up_axis\x22:" as *u8); hc_pn(out[13])
  hc_puts(",\x22digits\x22:" as *u8); hc_pn(out[3])
  hc_puts(",\x22bones_total\x22:" as *u8); hc_pn(out[4])
  hc_puts(",\x22digits_3bone\x22:" as *u8); hc_pn(out[5])
  hc_puts(",\x22digits_2bone\x22:" as *u8); hc_pn(out[6])
  hc_puts(",\x22chain_joints_min\x22:" as *u8); hc_pn(out[14])
  hc_puts(",\x22chain_joints_max\x22:" as *u8); hc_pn(out[15])
  hc_puts(",\x22mean_bone\x22:" as *u8); hc_pn(out[12])
  hc_puts(",\x22mono_violations\x22:" as *u8); hc_pn(out[7])
  hc_puts(",\x22taper_violations\x22:" as *u8); hc_pn(out[10])
  hc_puts(",\x22worst_taper_permil\x22:" as *u8); hc_pn(out[17])
  hc_puts(",\x22fused_digit_pairs\x22:" as *u8); hc_pn(out[8])
  hc_puts(",\x22thumb_opposition_permil\x22:" as *u8); hc_pn(out[9])
  hc_puts(",\x22verdict\x22:\x22" as *u8)
  if hc_ok(out) == 1 { hc_puts("GREEN" as *u8) } else { hc_puts("RED" as *u8) }
  hc_puts("\x22,\x22canon\x22:\x22Buryanov+Kotiuk Int.J.Morphol. 28(3):755-758 2010 Tab.I and II: five rays, four with three phalanges, proximal greater than medial greater than distal in every ray\x22" as *u8)
  hc_puts(",\x22unmeasured_in_v1\x22:\x22SKIN weights (hand-vs-forearm region), POSE and ANIM (clipping during motion), mesh-level interpenetration\x22}\n" as *u8)
  return 0
466}
467
468// ---- fixtures: SKEL word images built in memory, so the gate needs no file and no /tmp ----------
469// layout is exactly the shipped one: W[sw]=nj then per joint [parent][x][y][z][qx][qy][qz][qw].
470func hc_setj(W: *i64, sw: i64, j: i64, p: i64, x: i64, y: i64, z: i64) -> i64 {
  let b: i64 = sw + 1 + j * HC_WPJ
  W[b] = p
  W[b+1] = x
  W[b+2] = y
  W[b+3] = z
  W[b+4] = 0
  W[b+5] = 0
  W[b+6] = 0
  W[b+7] = HC_Q
  return 0
481}
482// A GOOD HAND: a 300-unit-tall stub rig (root, head, wrist at 60 percent height) plus five digits.
483// Four fingers of 4 joints (3 phalanges) cut to the CITED taper 44:26:17, and a thumb of 3 joints
484// swung across the palm so it OPPOSES.
485func hc_fx_good(nout: *i64) -> *i64 {
  let W: *i64 = sys_mmap((HC_MAXJ*HC_WPJ + 8)*8) as *i64
  hc_setj(W, 0, 0, 0-1, 0, 0, 0)          // root
  hc_setj(W, 0, 1, 0, 0, 0, 300)          // head: sets the rig extent to 300 on axis 2
  hc_setj(W, 0, 2, 0, 100, 0, 180)        // wrist, h01 = 600
  var d: i64 = 0
  var jn: i64 = 3
  while d < 4 {
      let y0: i64 = d * 20 - 30
      hc_setj(W, 0, jn,   2, 110, y0, 180)
      hc_setj(W, 0, jn+1, jn, 154, y0, 180)
      hc_setj(W, 0, jn+2, jn+1, 180, y0, 180)
      hc_setj(W, 0, jn+3, jn+2, 197, y0, 180)
      jn = jn + 4
      d = d + 1
  }
  hc_setj(W, 0, jn,   2, 104, 0-50, 180)
  hc_setj(W, 0, jn+1, jn, 122, 0-88, 148)
  hc_setj(W, 0, jn+2, jn+1, 134, 0-112, 128)
  jn = jn + 3
  W[0] = jn
  nout[0] = jn
  return W
508}
509// A BAD HAND -- the shape the operator reported. Same wrist, same five stubs, but each digit is ONE
510// bone, they all point the same way, and two of them share a position: a rake fused into a mitten.
511func hc_fx_bad(nout: *i64) -> *i64 {
  let W: *i64 = sys_mmap((HC_MAXJ*HC_WPJ + 8)*8) as *i64
  hc_setj(W, 0, 0, 0-1, 0, 0, 0)
  hc_setj(W, 0, 1, 0, 0, 0, 300)
  hc_setj(W, 0, 2, 0, 100, 0, 180)
  var d: i64 = 0
  var jn: i64 = 3
  while d < 5 {
      var y0: i64 = d * 20 - 40
      if d == 4 { y0 = 20 }               // digit 4 lands on digit 3 -> a fused pair
      hc_setj(W, 0, jn,   2, 110, y0, 180)
      hc_setj(W, 0, jn+1, jn, 180, y0, 180)
      jn = jn + 2
      d = d + 1
  }
  W[0] = jn
  nout[0] = jn
  return W
529}
530// A LEG, not a hand: one straight chain. Nothing on it is a hub, so the judge must ABSTAIN.
531func hc_fx_leg(nout: *i64) -> *i64 {
  let W: *i64 = sys_mmap((HC_MAXJ*HC_WPJ + 8)*8) as *i64
  hc_setj(W, 0, 0, 0-1, 0, 0, 300)
  hc_setj(W, 0, 1, 0, 0, 0, 200)
  hc_setj(W, 0, 2, 1, 0, 0, 100)
  hc_setj(W, 0, 3, 2, 0, 0, 0)
  W[0] = 4
  nout[0] = 4
  return W
540}
541// A FOOT: the SAME five-chain topology as a good hand, planted at the BOTTOM of the rig. This is the
542// control that proves the height band is doing work -- a toe hub must never be graded as a hand.
543func hc_fx_foot(nout: *i64) -> *i64 {
  let W: *i64 = sys_mmap((HC_MAXJ*HC_WPJ + 8)*8) as *i64
  hc_setj(W, 0, 0, 0-1, 0, 0, 300)
  hc_setj(W, 0, 1, 0, 0, 0, 0)            // ankle at the very bottom, h01 = 0
  var d: i64 = 0
  var jn: i64 = 2
  while d < 5 {
      let y0: i64 = d * 20 - 40
      hc_setj(W, 0, jn,   1, 10, y0, 0)
      hc_setj(W, 0, jn+1, jn, 54, y0, 0)
      hc_setj(W, 0, jn+2, jn+1, 80, y0, 0)
      hc_setj(W, 0, jn+3, jn+2, 97, y0, 0)
      jn = jn + 4
      d = d + 1
  }
  W[0] = jn
  nout[0] = jn
  return W
561}
562
563func hc_dump(W: *i64, sw: i64, nj: i64) -> i64 {
  if nj <= 0 { hc_puts("HANDCHECK-DUMP REFUSED: SKEL carries no joints\n" as *u8); return 4 }
  if nj > HC_MAXJ { hc_puts("HANDCHECK-DUMP REFUSED: implausible joint count\n" as *u8); return 4 }
  let NC: *i64 = sys_mmap(HC_MAXJ*8) as *i64
  hc_children(W, sw, nj, NC)
  let CH: *i64 = sys_mmap(HC_MAXCH*8) as *i64
  hc_puts("HANDCHECK-DUMP joints=" as *u8); hc_pn(nj); hc_puts("\n" as *u8)
  var j: i64 = 0
  while j < nj {
      let b: i64 = sw + 1 + j * HC_WPJ
      hc_puts("J " as *u8); hc_pn(j)
      hc_puts(" parent=" as *u8); hc_pn(W[b])
      hc_puts(" xyz=" as *u8); hc_pn(W[b+1]); hc_puts(" " as *u8); hc_pn(W[b+2]); hc_puts(" " as *u8); hc_pn(W[b+3])
      hc_puts(" children=" as *u8); hc_pn(NC[j])
      hc_puts(" chainlen=" as *u8); hc_pn(hc_chain(W, sw, nj, NC, j, CH))
      hc_puts(" hubdigits=" as *u8); hc_pn(hc_hub_digits(W, sw, nj, NC, j, CH))
      hc_puts("\n" as *u8)
      j = j + 1
  }
  return 0
583}
584
585// THE TEETH LIVE HERE AND NOWHERE ELSE. Both entry points -- the `selftest` VERB below and the roster
586// surface nx_handcheck_gate -- pass their OWN counter into this one function, so the two can never
587// disagree about what was checked and a tooth added later cannot land in only one of them.
588func hc_teeth(ctr: *i64) -> i64 {
  let n: *i64 = sys_mmap(16) as *i64
  let good: *i64 = sys_mmap(HC_OUT*8) as *i64
  let bad: *i64 = sys_mmap(HC_OUT*8) as *i64
  let leg: *i64 = sys_mmap(HC_OUT*8) as *i64
  let foot: *i64 = sys_mmap(HC_OUT*8) as *i64
  let Wg: *i64 = hc_fx_good(n)
  let njg: i64 = n[0]
  let rg: i64 = hc_measure(Wg, 0, njg, good)
  let Wb: *i64 = hc_fx_bad(n)
  let njb: i64 = n[0]
  let rb: i64 = hc_measure(Wb, 0, njb, bad)
  let Wl: *i64 = hc_fx_leg(n)
  let rl: i64 = hc_measure(Wl, 0, n[0], leg)
  let Wf: *i64 = hc_fx_foot(n)
  let rf: i64 = hc_measure(Wf, 0, n[0], foot)
604
  // T1 FIXTURE REACHED THE CONDITION. Assert the topology walk actually ran before asserting any
  // outcome -- a fixture the measurement never examined proves nothing about the measurement.
  var t1: i64 = 0
  if rg == 0 { if njg == 22 { if good[0] == 22 { t1 = 1 } } }
  gv_check("T1 fixture-reached-the-condition: the good hand parses as 22 joints and MEASURES" as *u8, t1, ctr)
610
  // T2 the hand is FOUND STRUCTURALLY -- five terminal chains on one attachment, no names, no index
  var t2: i64 = 0
  if good[3] == HC_DIGITS_CANON { if good[2] == 2 { t2 = 1 } }
  gv_check("T2 finds the hand by TOPOLOGY: 5 digit chains on joint 2, with no joint names anywhere" as *u8, t2, ctr)
615
  // T3 the CITED phalanx count: four fingers of three bones, one thumb of two
  var t3: i64 = 0
  if good[5] == 4 { if good[6] == 1 { if good[4] == 14 { t3 = 1 } } }
  gv_check("T3 phalanx count matches the cited canon: 4 digits x 3 bones plus 1 thumb x 2 = 14" as *u8, t3, ctr)
620
  // T4 MONOTONIC DISTAL SHORTENING is measured, and it is clean on a hand cut to the cited table
  var t4: i64 = 0
  if good[7] == 0 { if good[12] > 0 { t4 = 1 } }
  gv_check("T4 monotonic distal shortening: zero violations on a hand cut to the cited 44:26:17 taper" as *u8, t4, ctr)
625
  // T5 DISCRIMINATION, which is the whole job of a judge. The rake is one bone per digit.
  var t5: i64 = 0
  if rb == 0 { if bad[5] == 0 { if bad[4] == 5 { t5 = 1 } } }
  gv_check("T5 DISCRIMINATES: the rake reports 5 bones total and ZERO three-boned digits" as *u8, t5, ctr)
630
  // T6 the fused pair is COUNTED, not merely flagged -- one pair planted, one pair found
  var t6: i64 = 0
  if bad[8] == 1 { if good[8] == 0 { t6 = 1 } }
  gv_check("T6 fusion is COUNTED: exactly the one planted overlapping digit pair, none on the good hand" as *u8, t6, ctr)
635
  // T7 thumb opposition separates a hand from a rake by construction
  var t7: i64 = 0
  if bad[9] < HC_THUMB_OPP_MIN { if good[9] >= HC_THUMB_OPP_MIN { t7 = 1 } }
  gv_check("T7 opposition: the all-parallel rake falls under the floor, the opposed thumb clears it" as *u8, t7, ctr)
640
  // T8 ANTI-VACUITY. A judge that passes everything is not a judge.
  var t8: i64 = 0
  if hc_ok(good) == 1 { if hc_ok(bad) == 0 { t8 = 1 } }
  gv_check("T8 anti-vacuity: verdict GREEN on the built hand, RED on the rake" as *u8, t8, ctr)
645
  // T9 ABSTAIN, NEVER ACQUIT. A rig with no digit chain must be REFUSED with its own return code,
  // and its verdict must not be readable as a pass.
  var t9: i64 = 0
  if rl == 0 - 2 { if hc_ok(leg) == 0 { if leg[1] == 0 { t9 = 1 } } }
  gv_check("T9 neg-control-abstain-on-no-hand: a chain with no hub returns -2 and never reads GREEN" as *u8, t9, ctr)
651
  // T10 the SAME five-chain topology at the bottom of the rig must be refused by the height band.
  // Without this the judge would grade a toe cluster as a hand and report a clean pass about a
  // part it never looked at.
  var t10: i64 = 0
  if rf == 0 - 3 { if foot[1] > 0 { if foot[16] == 0 { t10 = 1 } } }
  gv_check("T10 neg-control-foot-is-not-a-hand: an identical hub at h01 zero is FOUND but NOT graded" as *u8, t10, ctr)
658
  // T11 the taper CEILING fires only above its bound, and the good hand sits under it
  var t11: i64 = 0
  if good[10] == 0 { if good[17] > 0 { if good[17] < HC_R_PPPM_MAX { t11 = 1 } } }
  gv_check("T11 taper ceiling: the cited hand measures a real worst taper and stays under the bound" as *u8, t11, ctr)
663
  // T12 the ruler is not vacuous on the empty set: zero joints must refuse, not report a clean hand
  let emp: *i64 = sys_mmap(HC_OUT*8) as *i64
  let We: *i64 = sys_mmap(64*8) as *i64
  We[0] = 0
  let re: i64 = hc_measure(We, 0, 0, emp)
  var t12: i64 = 0
  if re == 0 - 1 { if hc_ok(emp) == 0 { t12 = 1 } }
  gv_check("T12 neg-control-empty-skel: zero joints is REFUSED -- a tooth that passes on the empty set is not a tooth" as *u8, t12, ctr)
672
  return 0
674}
675// The VERB entry point. nx_handcheck_gate is the ROSTER entry point and builds its OWN counter over
676// these SAME teeth -- see that organ header for why a roster row must never be this judge forked bare.
677func hc_gate() -> i64 {
  let ctr: *i64 = gv_ctr()
  gv_head("nx_handcheck selftest -- the hand structure judge, proven to SEPARATE a rake from a hand" as *u8)
  hc_teeth(ctr)
  return gv_verdict("HANDCHECK-GATE" as *u8, ctr, "hand structure judge: topological digit discovery, cited phalanx count and monotonic taper, fusion, opposition, abstain on no-hand and on a foot" as *u8)
682}
683
684
685func hc_load(path: *u8, lp: *i64, swp: *i64, njp: *i64) -> *u8 {
  let b: *u8 = sys_read_file(path, lp)
  if (b as i64) == 0 { swp[0] = 0 - 9; return 0 as *u8 }
  let sw: i64 = nxa_find(b, lp[0], nxa_tag4("SKEL" as *u8))
  if sw < 0 { swp[0] = sw; return 0 as *u8 }
  let W: *i64 = b as *i64
  swp[0] = sw
  njp[0] = W[sw]
  return b
694}
695
696func main(argc: i64, argv: *i64) -> i64 {
  if argc >= 2 {
      if hc_streq(argv[1] as *u8, "selftest" as *u8) == 1 { return hc_gate() }
      var mode: i64 = 0
      if hc_streq(argv[1] as *u8, "check" as *u8) == 1 { mode = 1 }
      if hc_streq(argv[1] as *u8, "dump" as *u8) == 1 { mode = 2 }
      if mode > 0 {
          if argc < 3 { hc_puts("{\x22error\x22:\x22usage: nx_handcheck check <file.nxa> | dump <file.nxa> | selftest\x22}\n" as *u8); return 2 }
          let lp: *i64 = sys_mmap(16) as *i64
          let swp: *i64 = sys_mmap(16) as *i64
          let njp: *i64 = sys_mmap(16) as *i64
          swp[0] = 0
          njp[0] = 0
          let b: *u8 = hc_load(argv[2] as *u8, lp, swp, njp)
          if (b as i64) == 0 {
              hc_puts("{\x22organ\x22:\x22nx_handcheck\x22,\x22verdict\x22:\x22REFUSED\x22,\x22why\x22:\x22cannot read the asset or it carries no valid SKEL section\x22,\x22skel_rc\x22:" as *u8)
              hc_pn(swp[0]); hc_puts("}\n" as *u8)
              return 3
          }
          let W: *i64 = b as *i64
          if mode == 2 { return hc_dump(W, swp[0], njp[0]) }
          let out: *i64 = sys_mmap(HC_OUT*8) as *i64
          let rc: i64 = hc_measure(W, swp[0], njp[0], out)
          if rc < 0 {
              hc_puts("{\x22organ\x22:\x22nx_handcheck\x22,\x22verdict\x22:\x22UNOBSERVABLE-no-hand-chain\x22,\x22rc\x22:" as *u8); hc_pn(rc)
              hc_puts(",\x22joints\x22:" as *u8); hc_pn(out[0])
              hc_puts(",\x22digit_hubs\x22:" as *u8); hc_pn(out[1])
              hc_puts(",\x22hand_hubs\x22:" as *u8); hc_pn(out[16])
              hc_puts(",\x22why\x22:\x22no attachment on this rig hosts three or more terminal digit chains above the hip band -- the judge reports NOTHING rather than a hand it never measured\x22}\n" as *u8)
              return 4
          }
          hc_report(out)
          if hc_ok(out) == 1 { return 0 }
          return 1
      }
  }
  hc_puts("{\x22organ\x22:\x22nx_handcheck\x22,\x22usage\x22:\x22nx_handcheck check <file.nxa> | nx_handcheck dump <file.nxa> | nx_handcheck selftest\x22}\n" as *u8)
  return 0
734}
nx_handcheck.nx source

`nx_handcheck.nx` source
