`nx_fascia.nx` source

↩ module page · 359 lines · 18082 B
1// nx_fascia.nx -- PIPELINE STAGE 3: FASCIA + FAT AS SOFT BODY, bridging muscle to skin.
2//
3// The industry pipeline is skeleton -> muscle -> fascia/fat -> skin, and an audit of our own stack found we
4// had that pipeline's SHAPE and almost none of its PHYSICS: "fat" was a scalar knob attenuating how much
5// muscle relief reached the skin. Nothing lagged, nothing settled, nothing was driven by the layer beneath.
6//
7// It also found that the solver had been built and gated months earlier and NEVER WIRED IN: runtime/
8// nx_softdyn.nx is a spring-damper soft body whose stability envelope is enforced BY CONSTRUCTION (past a
9// damping threshold semi-implicit Euler inverts and amplifies velocity, so SD_CAPC/SD_CAPK make an unstable
10// configuration impossible to REQUEST rather than merely discouraged). It shipped with no soft-tissue
11// geometry to bind to. The layer emitter now emits muscle and fat layers, so this organ is the wiring.
12//
13// THE BINDING, and it is what makes this stage 3 rather than just re-running a solver: a LAYER-AWARE
14// LATTICE. Solver points are seated on a coarse band lattice over the figure; every vertex is displaced by
15// its band's point SCALED BY THE SOFTNESS OF ITS OWN LAYER. Bone scales to ZERO and does not move at all;
16// muscle moves partly; skin and fat move fully. That is fascia doing its actual job -- transmitting motion
17// from the rigid thing inside to the soft thing outside, with each layer lagging by its own amount.
18//
19//   nx_fascia <in.nxmesh> <out.nxmesh> [accel] [K] [C] [steps]
20//   nx_fascia selftest
21// license_tier: ORIGINAL  expect_exit: 0  No hw writes (Rule 26).
22import "nx_gate_verdict.nx"
23import "nx_itoa_lib.nx"   // shared MSB-first emitter (zero-alloc)
24import "nx_softdyn.nx"
25
26const FS2_M8388607: i64 = 8388607
27const FS2_M8388608: i64 = 8388608
28const FS2_HDR: i64 = 16
29const FS2_LAYENT: i64 = 24
30const FS2_TRI: i64 = 84
31const FS2_LID: i64 = 4
32const FS2_BANDS: i64 = 24
33const FS2_MM: i64 = 1000
34const FS2_MODE: i64 = 420
35const FS2_MAXD: i64 = 40
36const FS2_DEFK: i64 = 900
37const FS2_DEFC: i64 = 260
38const FS2_DEFA: i64 = 900
39const FS2_STEPS: i64 = 40
40const FS2_SOFTK: i64 = 120
41// full solver excursion maps to this per-mille of the figure's own height (~2pct = real tissue travel)
42const FS2_EXC: i64 = 20
43const FS2_SCR: i64 = 4096
44
45func fs2_puts(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} sys_write(1,s,n); return 0 }
46// MIGRATED to the shared emitter (debt 1785563586). The old body mmapped a scratch buffer
47// per call and never freed it. At PAGE granularity that is 4096B leaked PER CALL -- the
48// defect that took 28.5GB of a 36GB host in nx_ts_lumadiff (2MB input, ~3.66M calls).
49// nxi_* is MSB-first, allocates NOTHING, and emits identical bytes including the sign.
50func fs2_pn(v: i64) -> i64 { nxi_out(v); return 0 }
51func fs2_rd32(b: *u8, o: i64) -> i64 {
  return (b[o] as i64) | ((b[o+1] as i64)<<8) | ((b[o+2] as i64)<<16) | ((b[o+3] as i64)<<24)
53}
54func fs2_wr32(b: *u8, o: i64, v: i64) -> i64 {
  b[o]=(v & 255) as u8; b[o+1]=((v>>8) & 255) as u8; b[o+2]=((v>>16) & 255) as u8; b[o+3]=((v>>24) & 255) as u8
  return 0
57}
58func fs2_f32mul(b: *u8, o: i64, mul: i64) -> i64 {
  let bits: i64 = fs2_rd32(b, o)
  let sign: i64 = (bits>>31) & 1
  let exp: i64 = (bits>>23) & 255
  let mant: i64 = bits & FS2_M8388607
  if exp == 0 { return 0 }
  let m: i64 = (mant | FS2_M8388608) * mul
  var e: i64 = exp - 127 - 23
  var v: i64 = 0
  if e >= 0 { v = m << e } else { let sh: i64 = 0 - e; v = (m + (1 << (sh-1))) >> sh }
  if sign == 1 { v = 0 - v }
  return v
70}
71// encode a small signed integer back to f32 (mesh positions are whole model units here)
72func fs2_f32of(v: i64) -> i64 {
  if v == 0 { return 0 }
  var s: i64 = 0
  var m: i64 = v
  if m < 0 { s = 1; m = 0 - m }
  var ex: i64 = 0
  var tv: i64 = m
  while tv >= 2 { tv = tv/2; ex = ex + 1 }
  var frac: i64 = 0
  if ex > 0 { frac = (m - (1 << ex)) * (1 << 23) / (1 << ex) }
  return (s << 31) | ((127 + ex) << 23) | frac
83}
84func fs2_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
88}
89func fs2_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
94}
95// ★LAYER SOFTNESS, per-mille. This is the whole point of a layer-aware binding: the SAME lattice motion
96// reaches each layer scaled by what that layer physically is. Our emitter writes 0=skin, 1=muscle, 2=bone.
97// Bone is RIGID -- it returns zero and therefore cannot move, which is the property that makes this fascia
98// rather than a global wobble.
99func fs2_soft(layer: i64) -> i64 {
  if layer == 2 { return 0 }        // bone: rigid by construction
  if layer == 1 { return 520 }      // muscle: bound to bone, moves partly
  return 1000                       // skin / fat: the outermost soft envelope, moves fully
103}
104// out[0]=tris out[1]=layers out[2]=peak_lag out[3]=rest_energy out[4]=max_disp out[5]=moved_soft
105// out[6]=moved_bone (MUST be 0) out[7]=ymin out[8]=yspan
106func fs2_run(inp: *u8, outp: *u8, accel: i64, K: i64, C: i64, steps: i64, out: *i64) -> i64 {
  var z: i64 = 0
  while z < 12 { out[z] = 0; z = z + 1 }
  let szp: *i64 = sys_mmap(16) as *i64
  let mb: *u8 = sys_read_file(inp, szp)
  if (mb as i64) == 0 { return 0-1 }
  let sz: i64 = szp[0]
  if sz < FS2_HDR { return 0-2 }
  if mb[0]!=(78 as u8) { return 0-3 }
  if mb[1]!=(88 as u8) { return 0-3 }
  let nlay: i64 = fs2_rd32(mb, 8)
  let nt: i64 = fs2_rd32(mb, 12)
  if nlay <= 0 { return 0-4 }
  if nt <= 0 { return 0-5 }
  let hdr: i64 = FS2_HDR + nlay*FS2_LAYENT
  if hdr + nt*FS2_TRI + nt*FS2_LID > sz { return 0-6 }
  out[0] = nt
  out[1] = nlay
  // pass 1: y extent, so the lattice bands span the figure
  var ymn: i64 = 0
  var ymx: i64 = 0
  var first: i64 = 1
  var t: i64 = 0
  while t < nt {
      let o: i64 = hdr + t*FS2_TRI
      var k: i64 = 0
      while k < 3 {
          let y: i64 = fs2_f32mul(mb, o + k*12 + 4, 1)
          if first == 1 { ymn=y; ymx=y; first=0 } else {
              if y<ymn { ymn=y }
              if y>ymx { ymx=y }
          }
          k = k + 1
      }
      t = t + 1
  }
  let yspan: i64 = ymx - ymn
  if yspan <= 0 { return 0-7 }
  out[7] = ymn
  out[8] = yspan
  // ---- THE LATTICE: one soft-body point per band, seated at rest, then driven.
  let st: *i64 = sd_alloc(FS2_BANDS)
  var b: i64 = 0
  while b < FS2_BANDS { sd_seat(st, b, 0, 0, 0); b = b + 1 }
  // ★DRIVE: the anchor accelerates upward then stops -- a footfall. Real tissue LAGS behind the skeleton
  // on the way up and OVERSHOOTS when it stops; that lag and overshoot IS the effect being simulated.
  // ★★THE SNAPSHOT, and the bug it fixes is sharper than the units one: the first cut stepped the whole
  // simulation and THEN read each band's displacement to deform the mesh -- by which point the tissue had
  // SETTLED BACK ONTO ITS ANCHOR and the lag was gone. Peak lag read 40 during the motion and the applied
  // displacement read 4, because I was measuring the physics at the moment it had finished happening.
  // ★A transient is only observable while it is transient: capture the state AT PEAK LAG and deform from
  // that, which is also what a renderer wants -- the frame where the tissue is furthest behind the bone.
  let snap: *i64 = sys_mmap(FS2_BANDS*8 + 64) as *i64
  var zs: i64 = 0
  while zs < FS2_BANDS { snap[zs] = 0; zs = zs + 1 }
  var peak: i64 = 0
  var s: i64 = 0
  while s < steps {
      var ay: i64 = 0
      if s < steps/2 { ay = accel * s / (steps/2) }     // driven phase: the bone rises
      if s >= steps/2 { ay = accel }                     // then holds: the tissue must catch up and settle
      var bb: i64 = 0
      while bb < FS2_BANDS {
          sd_step(st, bb, 0, ay, 0, K, C, FS2_MAXD)
          let dd: i64 = sd_disp_y(st, bb, ay)
          let d: i64 = sd_abs(dd)
          if d > peak { peak = d }
          // hold each band's own most-lagged state -- the frame worth rendering
          if d > sd_abs(snap[bb]) { snap[bb] = dd }
          bb = bb + 1
      }
      s = s + 1
  }
  out[2] = peak
  var esum: i64 = 0
  var eb: i64 = 0
  while eb < FS2_BANDS { esum = esum + sd_energy(st, eb); eb = eb + 1 }
  out[3] = esum
  // ---- APPLY: displace every vertex by its band's point, SCALED BY ITS LAYER'S SOFTNESS.
  let obytes: i64 = hdr + nt*FS2_TRI + nt*FS2_LID
  let ob: *u8 = sys_mmap(obytes + 64)
  var c: i64 = 0
  while c < obytes { ob[c] = mb[c]; c = c + 1 }
  var maxd: i64 = 0
  var movsoft: i64 = 0
  var movbone: i64 = 0
  var t2: i64 = 0
  while t2 < nt {
      let o2: i64 = hdr + t2*FS2_TRI
      let lay: i64 = fs2_rd32(mb, hdr + nt*FS2_TRI + t2*FS2_LID)
      let soft: i64 = fs2_soft(lay)
      var k2: i64 = 0
      while k2 < 3 {
          let y2: i64 = fs2_f32mul(mb, o2 + k2*12 + 4, 1)
          var bnd: i64 = (y2 - ymn) * FS2_BANDS / yspan
          if bnd < 0 { bnd = 0 }
          if bnd >= FS2_BANDS { bnd = FS2_BANDS - 1 }
          // ⚠⚠UNITS BUG CAUGHT BY RENDERING IT, NOT BY MEASURING IT. The first cut applied the solver's raw
          // displacement straight to mesh coordinates. The solver works in its own space where a full
          // excursion is FS2_MAXD (tens of units); the mesh is in model units where the figure is tens of
          // THOUSANDS tall. So tissue moved ~5 units on a body ~200,000 units high -- real, measurable,
          // bounded, deterministic, and utterly invisible: the render changed by 26 pixels out of 84,000.
          // ★THIS IS THE BANKED UNITS-TRAP CLASS: an integer scale mismatch does not error, it produces a
          // physically negligible result that passes every numeric test. The gate could not catch it
          // because the gate tests the SOLVER, and the solver was right -- the BINDING was dimensionless.
          // ★THE FIX: a displacement is a FRACTION OF THE FIGURE, not a raw count. Map the solver's full
          // excursion onto FS2_EXC per-mille of the mesh's own height, so tissue moves ~2pct of body
          // height at full lag on ANY figure at ANY scale -- which is roughly what real tissue does.
          let draw: i64 = snap[bnd]
          let dy: i64 = ((draw * yspan / FS2_MAXD) * FS2_EXC / FS2_MM) * soft / FS2_MM
          if dy != 0 {
              if soft > 0 { movsoft = movsoft + 1 } else { movbone = movbone + 1 }
              let ad: i64 = sd_abs(dy)
              if ad > maxd { maxd = ad }
              fs2_wr32(ob, o2 + k2*12 + 4, fs2_f32of(y2 + dy))
          }
          k2 = k2 + 1
      }
      t2 = t2 + 1
  }
  out[4] = maxd
  out[5] = movsoft
  out[6] = movbone
  let fd: i64 = sys_openat_wr(outp, FS2_MODE)
  if fd < 0 { return 0-8 }
  sys_write(fd, ob, obytes)
  sys_close(fd)
  return 0
234}
235func fs2_gate() -> i64 {
  let ctr: *i64 = gv_ctr()
  gv_head("nx_fascia selftest -- fascia as a LAYER-AWARE soft body, not a global wobble" as *u8)
  // the lattice behaviour is testable without a mesh: seat points, drive them, watch them lag and settle.
  let st: *i64 = sd_alloc(4)
  var i: i64 = 0
  while i < 4 { sd_seat(st, i, 0, 0, 0); i = i + 1 }
  var peak: i64 = 0
  var s: i64 = 0
  while s < 20 {
      let ay: i64 = FS2_DEFA * s / 20
      sd_step(st, 0, 0, ay, 0, FS2_DEFK, FS2_DEFC, FS2_MAXD)
      let d: i64 = sd_abs(sd_disp_y(st, 0, ay))
      if d > peak { peak = d }
      s = s + 1
  }
  var t1: i64 = 0
  if peak > 0 { t1 = 1 }
  gv_check("T1 tissue LAGS behind the skeleton it hangs from" as *u8, t1, ctr)
  var s2: i64 = 0
  while s2 < 400 { sd_step(st, 0, 0, FS2_DEFA, 0, FS2_DEFK, FS2_DEFC, FS2_MAXD); s2 = s2 + 1 }
  let rest: i64 = sd_energy(st, 0)
  var t2: i64 = 0
  if rest == 0 { t2 = 1 }
  gv_check("T2 and SETTLES to rest once the motion stops" as *u8, t2, ctr)
  var t3: i64 = 0
  if sd_abs(sd_disp_y(st, 0, FS2_DEFA)) <= FS2_MAXD { t3 = 1 }
  gv_check("T3 displacement BOUNDED -- tissue can never leave the body" as *u8, t3, ctr)
  // ★THE LAYER TOOTH, and it is what makes this fascia rather than a wobble: bone is RIGID by
  // construction. If fs2_soft ever returned non-zero for bone, the skeleton would jiggle.
  var t4: i64 = 0
  if fs2_soft(2) == 0 { if fs2_soft(1) > 0 { if fs2_soft(0) > fs2_soft(1) { t4 = 1 } } }
  gv_check("T4 LAYER-AWARE: bone rigid, muscle partial, skin fullest" as *u8, t4, ctr)
  // ★ANTI-VACUITY: stiffness must CONTROL the response. A solver that always wobbles the same amount
  // would pass every test above and be simulating nothing.
  // ⚠THE FIRST CUT OF THIS TOOTH COMPARED PEAK DISPLACEMENT AND WENT RED, AND THE PHYSICS SAYS IT SHOULD
  // HAVE. A stiff, lightly-damped spring RINGS: its instantaneous peak can EXCEED a soft one's even though
  // it tracks the anchor far better on average. That is the same trap banked when this solver was built --
  // a stiff config read as MORE jiggle, not less. The physically correct statement is about STEADY-STATE
  // lag: under a constant drive the settled offset is proportional to load over stiffness, so a stiffer
  // tissue MUST settle closer to its anchor. Measure after settling, not during ringing.
  // ⚠⚠SECOND RED ON THE SAME TOOTH, AND THE SOLVER'S ACTUAL CONTRACT IS WHY: it is a pure spring-damper to
  // its ANCHOR with no external load, so under a CONSTANT anchor every configuration converges to the
  // anchor exactly and STEADY-STATE LAG IS ZERO FOR BOTH. My assertion could never have been true. The
  // property that genuinely distinguishes stiffness is TRACKING WHILE THE ANCHOR IS STILL MOVING: through
  // a ramp, a stiffer tissue stays closer to the bone it hangs from. Sample the lag at the END of the
  // driven ramp, while there is still something to lag behind.
  // ★LAW: read the solver's contract before asserting a property of it -- twice now the test was wrong
  // rather than the code, and both times the physics was in the source all along.
  let st2: *i64 = sd_alloc(2)
  sd_seat(st2, 0, 0, 0, 0)
  var stifflag: i64 = 0
  var sA: i64 = 0
  while sA < 20 {
      let ay: i64 = FS2_DEFA * sA / 20
      sd_step(st2, 0, 0, ay, 0, SD_CAPK, FS2_DEFC, FS2_MAXD)
      stifflag = sd_abs(sd_disp_y_q8(st2, 0, ay))
      sA = sA + 1
  }
  let st4: *i64 = sd_alloc(2)
  sd_seat(st4, 0, 0, 0, 0)
  var softlag: i64 = 0
  var sB: i64 = 0
  while sB < 20 {
      let ay: i64 = FS2_DEFA * sB / 20
      sd_step(st4, 0, 0, ay, 0, FS2_SOFTK, FS2_DEFC, FS2_MAXD)
      softlag = sd_abs(sd_disp_y_q8(st4, 0, ay))
      sB = sB + 1
  }
  var t5: i64 = 0
  if stifflag < softlag { t5 = 1 }
  gv_check("T5 anti-vacuity: STIFF tissue TRACKS the bone closer than soft tissue mid-motion" as *u8, t5, ctr)
  // ★DETERMINISM: the same drive must produce the same tissue state, or nothing here is reproducible.
  let st3: *i64 = sd_alloc(2)
  sd_seat(st3, 0, 0, 0, 0)
  var peak3: i64 = 0
  var s4: i64 = 0
  while s4 < 20 {
      let ay: i64 = FS2_DEFA * s4 / 20
      sd_step(st3, 0, 0, ay, 0, FS2_DEFK, FS2_DEFC, FS2_MAXD)
      let d: i64 = sd_abs(sd_disp_y(st3, 0, ay))
      if d > peak3 { peak3 = d }
      s4 = s4 + 1
  }
  var t6: i64 = 0
  if peak3 == peak { t6 = 1 }
  gv_check("T6 deterministic: identical drive, identical tissue" as *u8, t6, ctr)
  let o: *i64 = sys_mmap(FS2_SCR) as *i64
  var t7: i64 = 0
  if fs2_run("/tmp/nx_fs2_absent_zz.nxmesh" as *u8, "/tmp/nx_fs2_o.nxmesh" as *u8, FS2_DEFA, FS2_DEFK, FS2_DEFC, FS2_STEPS, o) < 0 { t7 = 1 }
  gv_check("T7 missing input refused, not silently empty" as *u8, t7, ctr)
  return gv_verdict("TISSUE-GATE" as *u8, ctr, "layer-aware fascia; bone rigid by construction" as *u8)
327}
328func main(argc: i64, argv: *i64) -> i64 {
  if argc >= 2 {
      if fs2_streq(argv[1] as *u8, "selftest" as *u8) == 1 { return fs2_gate() }
  }
  if argc < 3 {
      fs2_puts("usage: nx_fascia <in.nxmesh> <out.nxmesh> [accel] [K] [C] [steps] | selftest\n" as *u8)
      return 2
  }
  var accel: i64 = FS2_DEFA
  var K: i64 = FS2_DEFK
  var C: i64 = FS2_DEFC
  var steps: i64 = FS2_STEPS
  if argc > 3 { accel = fs2_atoi(argv[3] as *u8) }
  if argc > 4 { K = fs2_atoi(argv[4] as *u8) }
  if argc > 5 { C = fs2_atoi(argv[5] as *u8) }
  if argc > 6 { steps = fs2_atoi(argv[6] as *u8) }
  let o: *i64 = sys_mmap(FS2_SCR) as *i64
  let rc: i64 = fs2_run(argv[1] as *u8, argv[2] as *u8, accel, K, C, steps, o)
  fs2_puts("{\x22organ\x22:\x22nx_fascia\x22,\x22v\x22:1,\x22stage\x22:\x22pipeline stage 3 -- fascia and fat as soft body, bridging muscle to skin\x22" as *u8)
  fs2_puts(",\x22rc\x22:" as *u8); fs2_pn(rc)
  fs2_puts(",\x22tris\x22:" as *u8); fs2_pn(o[0])
  fs2_puts(",\x22layers\x22:" as *u8); fs2_pn(o[1])
  fs2_puts(",\x22peak_lag\x22:" as *u8); fs2_pn(o[2])
  fs2_puts(",\x22rest_energy\x22:" as *u8); fs2_pn(o[3])
  fs2_puts(",\x22max_disp\x22:" as *u8); fs2_pn(o[4])
  fs2_puts(",\x22verts_moved_soft\x22:" as *u8); fs2_pn(o[5])
  fs2_puts(",\x22verts_moved_bone\x22:" as *u8); fs2_pn(o[6])
  fs2_puts(",\x22binding\x22:\x22layer-aware lattice: solver points on a band lattice, each vertex displaced by its band SCALED BY ITS LAYER SOFTNESS -- bone 0 (rigid by construction), muscle 520, skin/fat 1000. verts_moved_bone MUST read 0.\x22" as *u8)
  fs2_puts(",\x22solver\x22:\x22nx_softdyn spring-damper, stability envelope enforced by construction (an unstable config cannot be requested), displacement hard-clamped so tissue can never leave the body\x22}\n" as *u8)
  if rc < 0 { return 1 }
  return 0
359}
nx_fascia.nx source

`nx_fascia.nx` source
