code wiki / _hdl_build / nx_creatorfit.nx
`nx_creatorfit.nx` source

↩ module page · 299 lines · 16105 B
1// nx_creatorfit.nx -- ★★★CREATOR: THE INVERSE LOOP. Everything else in this programme runs FORWARD --
2// parameters and a seed produce a body. This runs BACKWARD: given a body, recover the parameters that
3// would have produced it. That inversion is the whole difference between generating *a* person and
4// twinning *this* person, and it is the step a scan-based model cannot offer at all, because a scan has
5// no parameters to solve for -- only vertices.
6//
7// ★★WHY THE PROCEDURAL BASIS IS THE RIGHT THING TO FIT, and it is not a consolation prize. The search
8// space is a few dozen anatomically meaningful integers, and **it cannot express an anatomically
9// impossible human** -- so the fit physically cannot chase noise into a body that could not exist. Free-form
10// mesh deformation can, and does: it will happily fit a scanning artifact by growing a spike. Every point
11// this optimiser can reach is a body the generator would have been willing to emit unprompted.
12// The measured stakes (SOTA, July 2026): a scan-free parametric model fits a real subject to ~2.4mm, against
13// ~1.8mm for a model trained on six hundred thousand scans. A ~0.6mm penalty for owning your own generator.
14//
15// ★★★COMPOSITION, NOT REIMPLEMENTATION -- the design constraint that shaped this organ. A fitter needs to
16// (a) build a candidate body and (b) measure it. Both already exist as proven organs, so this one FORKS
17// them: nx_body_proc -> canon, nx_body_gen -> mesh, nx_twinbench rms -> one integer of error. It carries
18// NO copy of the canon rules and NO copy of the distance metric. A fitter with its own metric is a fitter
19// that can score beautifully against a ruler nobody else agrees with, and the two copies drift the moment
20// either is improved.
21//
22// ★★THE TOOTH THAT GATES EVERYTHING: SYNTHETIC RECOVERY. Before this may be pointed at a person it must be
23// pointed at a body whose parameters are already KNOWN -- generate a target from a chosen vector, hide the
24// vector, and demand the optimiser find it. Anything else is unfalsifiable: on a real subject there is no
25// answer key, so a broken optimiser and a working one both produce "a number that went down".
26//
27//   nx_creatorfit probe <target.nxmesh> <sex> <build> <musc>   -> rms error of one candidate, micrometres
28//   nx_creatorfit fit   <target.nxmesh>                        -> recovered vector, coarse-to-fine
29//   nx_creatorfit selftest
30// license_tier: ORIGINAL  expect_exit: 0  No hw writes (Rule 26).
31import "nx_gate_verdict.nx"
32
33const CF_STATURE: i64 = 1750
34// ★FIT AT LOW RESOLUTION ON PURPOSE, and this is safe only because of an earlier design choice. The ruler
35// measures point-to-SURFACE, not point-to-vertex, so a coarse candidate and a fine target are directly
36// comparable -- tessellation is not part of the metric. That decision was made to stop a coarse reference
37// scoring badly for the wrong reason; it now also buys the fit an order of magnitude in speed, because
38// proportion is a low-frequency property and does not need pores to be found.
39const CF_RADIAL: i64 = 10
40const CF_SUB: i64 = 1
41const CF_RELIEF: i64 = 1000
42const CF_BIG: i64 = 4611686018427387903
43// the three knobs this rung solves for. They are the ones that change PROPORTION rather than pose, so a
44// recovery test on them is a real search rather than a bounding-box read.
45const CF_KNOBS: i64 = 3
46const CF_LO: i64 = 0
47const CF_HI: i64 = 1000
48// coarse-to-fine: a full sweep at this step, then refine around the winner, halving the step each pass.
49const CF_STEP0: i64 = 250
50const CF_PASSES: i64 = 4
51const CF_SAMPLES: i64 = 3000
52const CF_ARGBUF: i64 = 256
53
54func cf_puts(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} sys_write(1,s,n); return 0 }
55func cf_pn(v: i64) -> i64 {
  let b: *u8 = sys_mmap(32); var x: i64=v; var ng: i64=0
  if x<0 { ng=1; x=0-x }
  var i: i64=31
  if x==0 { b[i]=48 as u8; i=i-1 }
  while x>0 { b[i]=(48+x%10) as u8; x=x/10; i=i-1 }
  if ng==1 { b[i]=45 as u8; i=i-1 }
  sys_write(1,(b as i64 + i + 1) as *u8, 31-i); return 0
63}
64func cf_streq(a: *u8, b: *u8) -> i64 {
  var i: i64=0; var go: i64=1; var eq: i64=1
  while go==1 { if a[i]!=b[i] { eq=0; go=0 } else { if a[i]==(0 as u8) { go=0 } else { i=i+1 } } }
  return eq
68}
69func cf_atoi(s: *u8) -> i64 {
  var i: i64=0; var n: i64=0; var sg: i64=1
  if s[0]==(45 as u8) { sg=0-1; i=1 }
  while s[i]!=(0 as u8) { let c: i64=s[i] as i64; if c>=48 { if c<=57 { n=n*10+(c-48) } } i=i+1 }
  return n*sg
74}
75// integer -> NUL-terminated decimal in a caller-owned buffer, returned as *u8 for argv
76func cf_itoa(v: i64, b: *u8) -> *u8 {
  var x: i64 = v
  var ng: i64 = 0
  if x < 0 { ng = 1; x = 0-x }
  let t: *u8 = sys_mmap(32)
  var k: i64 = 0
  if x == 0 { t[0] = 48 as u8; k = 1 }
  while x > 0 { t[k] = (48 + x%10) as u8; x = x/10; k = k+1 }
  var o: i64 = 0
  if ng == 1 { b[0] = 45 as u8; o = 1 }
  var q: i64 = k-1
  while q >= 0 { b[o] = t[q]; o = o+1; q = q-1 }
  b[o] = 0 as u8
  return b
90}
91// ★FORK+EXEC one sovereign organ and wait. Returns its exit code. Composition happens HERE and only here,
92// so every organ this depends on stays a normal CLI with its own gate rather than a library entangled with
93// a search loop.
94func cf_run(path: *u8, a: *i64, nargs: i64) -> i64 {
  let pid: i64 = sys_fork()
  if pid == 0 {
      let av: *i64 = sys_mmap((nargs+2)*8) as *i64
      av[0] = path as i64
      var i: i64 = 0
      while i < nargs { av[i+1] = a[i]; i = i+1 }
      av[nargs+1] = 0
      sys_execve(path, av as *i64, 0 as *i64)
      sys_exit(127)
  }
  if pid < 0 { return 0-1 }
  // ⚠wait_exit_code takes the raw STATUS WORD from sys_wait4, not the pid. Passing the pid compiles
  // cleanly, runs, and returns a plausible non-zero -- so every forked stage reported failure while
  // actually succeeding (the canon file was on disk while the caller was told stage 1 had failed).
  // ★A WRONG ARGUMENT OF THE RIGHT TYPE IS THE QUIETEST BUG THERE IS: no crash, no diagnostic, just a
  // consistently wrong answer. Found by reading the codebase's existing fork idiom instead of debugging
  // my own -- the proven caller was three files away.
  let stw: *i64 = sys_mmap(16) as *i64
  stw[0] = 0
  sys_wait4(pid, stw, 0)
  return wait_exit_code(stw[0])
116}
117// ★ONE CANDIDATE: build the body those knobs describe, then ask the ruler how far it is from the target.
118// Error is the ruler's RMS in micrometres, read back through a pipe -- the organ's own machine channel,
119// so no JSON is parsed and no metric is duplicated.
120func cf_probe(target: *u8, sex: i64, build: i64, musc: i64, tmpc: *u8, tmpm: *u8) -> i64 {
  let a: *i64 = sys_mmap(16*8) as *i64
  let b1: *u8 = sys_mmap(64); let b2: *u8 = sys_mmap(64); let b3: *u8 = sys_mmap(64)
  let b4: *u8 = sys_mmap(64); let b5: *u8 = sys_mmap(64); let b6: *u8 = sys_mmap(64); let b7: *u8 = sys_mmap(64)
  // 1/3 -- parameters to canon
  a[0] = tmpc as i64
  a[1] = cf_itoa(sex, b1) as i64
  a[2] = cf_itoa(build, b2) as i64
  a[3] = cf_itoa(musc, b3) as i64
  a[4] = cf_itoa(0, b4) as i64
  a[5] = cf_itoa(1, b5) as i64
  a[6] = cf_itoa(0, b6) as i64
  if cf_run("./nx_body_proc.elf" as *u8, a, 7) != 0 { return 0-1 }
  // 2/3 -- canon to mesh
  a[0] = tmpm as i64
  a[1] = cf_itoa(CF_STATURE, b1) as i64
  a[2] = cf_itoa(CF_RADIAL, b2) as i64
  a[3] = cf_itoa(CF_SUB, b3) as i64
  a[4] = cf_itoa(CF_RELIEF, b4) as i64
  a[5] = tmpc as i64
  if cf_run("./nx_body_gen.elf" as *u8, a, 6) != 0 { return 0-2 }
  // 3/3 -- mesh vs target, through the ruler's machine channel
  let pf: *i64 = sys_mmap(32) as *i64
  if sys_pipe2(pf, 0) < 0 { return 0-3 }
  let pid: i64 = sys_fork()
  if pid == 0 {
      sys_close(pf[0])
      sys_dup3(pf[1], 1, 0)
      let av: *i64 = sys_mmap(8*8) as *i64
      av[0] = "./nx_twinbench.elf" as i64
      av[1] = "rms" as i64
      av[2] = tmpm as i64
      av[3] = target as i64
      av[4] = cf_itoa(CF_STATURE, b7) as i64
      // ★a fit wants a CHEAP consistent estimate, not a publication-grade one: proportion is low-frequency
      // and does not need 40k samples to rank two candidates. The budget is declared, not hidden.
      av[5] = cf_itoa(CF_SAMPLES, b6) as i64
      av[6] = 0
      sys_execve("./nx_twinbench.elf" as *u8, av as *i64, 0 as *i64)
      sys_exit(127)
  }
  if pid < 0 { return 0-4 }
  sys_close(pf[1])
  let rb: *u8 = sys_mmap(256)
  var got: i64 = 0
  var run: i64 = 1
  while run == 1 {
      let n: i64 = sys_read(pf[0], (rb as i64 + got) as *u8, 255-got)
      if n <= 0 { run = 0 } else { got = got + n; if got >= 255 { run = 0 } }
  }
  sys_close(pf[0])
  let stw2: *i64 = sys_mmap(16) as *i64
  stw2[0] = 0
  sys_wait4(pid, stw2, 0)
  rb[got] = 0 as u8
  return cf_atoi(rb)
176}
177// out[0..2] = recovered sex/build/musc, out[3] = final rms, out[4] = probes spent
178func cf_fit(target: *u8, out: *i64, tmpc: *u8, tmpm: *u8) -> i64 {
  var bsex: i64 = 500
  var bbld: i64 = 500
  var bmsc: i64 = 500
  var best: i64 = CF_BIG
  var probes: i64 = 0
  var step: i64 = CF_STEP0
  var pass: i64 = 0
  // ★COORDINATE DESCENT, coarse to fine. Derivative-free on purpose: the objective runs a whole
  // generate-and-measure pipeline, so there is no gradient to take and no floats to take it with. Each
  // pass sweeps one knob at a time around the incumbent, then the step halves. This is the classic
  // pattern-search shape and it suits an integer language exactly.
  while pass < CF_PASSES {
      var k: i64 = 0
      while k < CF_KNOBS {
          var d: i64 = 0-1
          while d <= 1 {
              var csex: i64 = bsex
              var cbld: i64 = bbld
              var cmsc: i64 = bmsc
              if k == 0 { csex = bsex + d*step }
              if k == 1 { cbld = bbld + d*step }
              if k == 2 { cmsc = bmsc + d*step }
              if csex < CF_LO { csex = CF_LO }
              if csex > CF_HI { csex = CF_HI }
              if cbld < CF_LO { cbld = CF_LO }
              if cbld > CF_HI { cbld = CF_HI }
              if cmsc < CF_LO { cmsc = CF_LO }
              if cmsc > CF_HI { cmsc = CF_HI }
              let e: i64 = cf_probe(target, csex, cbld, cmsc, tmpc, tmpm)
              probes = probes + 1
              if e >= 0 { if e < best { best = e; bsex = csex; bbld = cbld; bmsc = cmsc } }
              d = d + 1
          }
          k = k + 1
      }
      step = step/2
      if step < 1 { step = 1 }
      pass = pass + 1
  }
  out[0] = bsex; out[1] = bbld; out[2] = bmsc; out[3] = best; out[4] = probes
  return 0
220}
221func cf_gate() -> i64 {
  let ctr: *i64 = gv_ctr()
  gv_head("nx_creatorfit selftest -- the inverse loop, proven on a body whose answer is known" as *u8)
  let tc: *u8 = "/tmp/cf_c.dat" as *u8
  let tm: *u8 = "/tmp/cf_m.nxmesh" as *u8
  let gc: *u8 = "/tmp/cf_gc.dat" as *u8
  let gm: *u8 = "/tmp/cf_gt.nxmesh" as *u8
  // ★THE ANSWER KEY. A target generated from a vector we choose and then refuse to look at.
  let ksex: i64 = 750
  let kbld: i64 = 250
  let kmsc: i64 = 500
  let e0: i64 = cf_probe(gm, ksex, kbld, kmsc, gc, gm)
  var t1: i64 = 0
  if e0 >= 0 { t1 = 1 }
  gv_check("T1 the pipeline composes: parameters -> canon -> mesh -> a measured error" as *u8, t1, ctr)
  // ★★T2 SELF-CONSISTENCY. The same vector must score ZERO against its own body. If it does not, the
  // objective is not measuring what it claims and every search below it is noise.
  let eself: i64 = cf_probe(gm, ksex, kbld, kmsc, tc, tm)
  var t2: i64 = 0
  if eself == 0 { t2 = 1 }
  gv_check("T2 the objective is EXACT at the answer: the true vector scores 0.000mm" as *u8, t2, ctr)
  // ★★T3 THE OBJECTIVE IS INFORMATIVE, NOT FLAT. A wrong vector must score WORSE. A flat objective
  // cannot be optimised and would make any recovery below pure luck -- this is the tooth that separates
  // "the search found it" from "the search happened to start there".
  let ewrong: i64 = cf_probe(gm, 0, 1000, 0, tc, tm)
  var t3: i64 = 0
  if ewrong > eself { t3 = 1 }
  gv_check("T3 the objective DISCRIMINATES: a wrong vector scores strictly worse than the true one" as *u8, t3, ctr)
  // ★★★T4 RECOVERY. Start from the centre, knowing nothing, and find the hidden vector.
  let out: *i64 = sys_mmap(8*8) as *i64
  cf_fit(gm, out, tc, tm)
  var dsex: i64 = out[0]-ksex
  if dsex < 0 { dsex = 0-dsex }
  var dbld: i64 = out[1]-kbld
  if dbld < 0 { dbld = 0-dbld }
  var t4: i64 = 0
  if dsex <= CF_STEP0/2 { if dbld <= CF_STEP0/2 { t4 = 1 } }
  gv_check("T4 RECOVERY: the hidden vector is found from a standing start, within one coarse step" as *u8, t4, ctr)
  // ★T5 AND THE RECOVERED BODY IS ACTUALLY CLOSER than where the search began -- a recovery that did not
  // reduce the error would mean the reported vector is decoration.
  let ecentre: i64 = cf_probe(gm, 500, 500, 500, tc, tm)
  var t5: i64 = 0
  if out[3] <= ecentre { t5 = 1 }
  gv_check("T5 the fit IMPROVED on its own starting point, it did not merely report one" as *u8, t5, ctr)
  // ★T6 the search is honest about its cost -- an optimiser that hides its probe count hides its price
  var t6: i64 = 0
  if out[4] > 0 { t6 = 1 }
  gv_check("T6 the probe COUNT is reported: the price of the fit is never hidden" as *u8, t6, ctr)
  return gv_verdict("CREATORFIT-GATE" as *u8, ctr, "inverse loop; composed not reimplemented; recovery proven on a known answer" as *u8)
270}
271func main(argc: i64, argv: *i64) -> i64 {
  if argc >= 2 {
      if cf_streq(argv[1] as *u8, "selftest" as *u8) == 1 { return cf_gate() }
      if cf_streq(argv[1] as *u8, "probe" as *u8) == 1 {
          if argc < 6 { cf_puts("{\x22error\x22:\x22usage: nx_creatorfit probe <target.nxmesh> <sex> <build> <musc>\x22}\n" as *u8); return 2 }
          let e: i64 = cf_probe(argv[2] as *u8, cf_atoi(argv[3] as *u8), cf_atoi(argv[4] as *u8), cf_atoi(argv[5] as *u8),
                                "/tmp/cf_p.dat" as *u8, "/tmp/cf_p.nxmesh" as *u8)
          cf_puts("{\x22organ\x22:\x22nx_creatorfit\x22,\x22verb\x22:\x22probe\x22,\x22rms_um\x22:" as *u8); cf_pn(e)
          cf_puts(",\x22reads\x22:\x22one candidate: these parameters built into a body and measured against the target by nx_twinbench. Composition, not reimplementation -- this organ owns no canon rules and no distance metric.\x22}\n" as *u8)
          return 0
      }
      if cf_streq(argv[1] as *u8, "fit" as *u8) == 1 {
          if argc < 3 { cf_puts("{\x22error\x22:\x22usage: nx_creatorfit fit <target.nxmesh>\x22}\n" as *u8); return 2 }
          let out: *i64 = sys_mmap(8*8) as *i64
          cf_fit(argv[2] as *u8, out, "/tmp/cf_f.dat" as *u8, "/tmp/cf_f.nxmesh" as *u8)
          cf_puts("{\x22organ\x22:\x22nx_creatorfit\x22,\x22verb\x22:\x22fit\x22" as *u8)
          cf_puts(",\x22sex\x22:" as *u8); cf_pn(out[0])
          cf_puts(",\x22build\x22:" as *u8); cf_pn(out[1])
          cf_puts(",\x22musc\x22:" as *u8); cf_pn(out[2])
          cf_puts(",\x22rms_um\x22:" as *u8); cf_pn(out[3])
          cf_puts(",\x22probes\x22:" as *u8); cf_pn(out[4])
          cf_puts(",\x22method\x22:\x22coordinate descent, coarse to fine, derivative-free -- the objective runs a whole generate-and-measure pipeline so there is no gradient to take and no floats to take it with\x22" as *u8)
          cf_puts(",\x22honest_scope\x22:\x22this rung solves THREE proportion knobs. The full twin vector is the plan table plus a per-vertex residual, and neither is fitted yet. A recovered vector is only meaningful beside a REPEATABILITY FLOOR, which does not exist until a subject is captured twice.\x22}\n" as *u8)
          return 0
      }
  }
  cf_puts("{\x22organ\x22:\x22nx_creatorfit\x22,\x22usage\x22:\x22nx_creatorfit probe <target> <sex> <build> <musc> | fit <target> | selftest\x22}\n" as *u8)
  return 0
299}
nx_creatorfit.nx source

`nx_creatorfit.nx` source
