`nx_job_run.nx` source

↩ module page · 261 lines · 14266 B
1// nx_job_run.nx v3 -- GUARDED ASYNC JOB RUNNER. Eats the async-fetch >15s edge-timeout debt the
2// good-form way: not a cron workaround, not an arbitrary executor.
3// SAFE BY CONSTRUCTION (rule 26 never-brick / rule 12 boundary-defense) -- FOUR fail-closed gates:
4//   (1) CLASS: deny-by-class via nx_job_launch_bound -- WIDENED 2026-07-31, and this is exactly the
5//       "filed rung" the previous line named for itself. The old rule launched ONLY organs whose
6//       name contained *research_fetch*, which meant the ecosystem had NO route to run a general
7//       organ and every generator fell back to shell. Now: generators, rollups, censuses and page
8//       emitters are launchable; DAEMONS and SERVERS are refused (they never exit, so an async
9//       launch wedges the slot forever) and so is the CONTROL PLANE (deploy/promote/restart/kill/
10//       mgmt/hostctl/supervisor). Fail-closed on an empty name. Deny-by-class, not allow-by-one-
11//       substring: a new generator is launchable the day it is allowlisted with no edit here, while
12//       a new daemon is refused by default -- a rule nothing must remember beats a list somebody
13//       must maintain. Proven by nx_job_launch_bound_gate 15/15 GREEN, including back-compat teeth
14//       for every organ the old *research_fetch* rule allowed.
15//   (2) VETTED: the name must resolve to a GREEN elf in tool_allowlist.conf -- the SAME trust
16//       boundary nx_plan_run uses; NEVER an arbitrary caller-supplied path.
17//   (3) NO-PIN-BYPASS: refuses pinned rows -- can never run a pinned elf with non-pinned args.
18//   (4) SCRATCH-ONLY: out-file confined to /tmp/ with no '..' -- writes land only on disposable scratch.
19// Mechanism (mirrors nx_hostctl cmd_buildrun): fork -> child redirects stdout+stderr to out-file via
20// sys_dup3 + execve the resolved elf with the caller's [args...]; PARENT returns IMMEDIATELY with a
21// job handle (does NOT wait4) -> child is orphaned + reaped by init, runs to completion async while
22// /mcp already answered -> a slow research-fetch no longer times out the edge.
23//   nx_job_run <tool-name(*research_fetch*)> <out-file:/tmp/...> [args...]  -> JOB-STARTED pid=.. elf=.. out=..
24// license_tier: ORIGINAL  No hw writes (Rule 26).  expect_exit: 0
25import "nx_syscalls.nx"
26import "nx_itoa_lib.nx"   // shared MSB-first emitter (zero-alloc)
27import "nx_job_launch_bound.nx"
28import "nx_jobcancel_lib.nx"   // ES29 (2026-09-15): the cancel verb -- the launcher is the one surface that can stop what it started
29const JR_MAGIC_1024: i64 = 1024
30const JR_VERB_CANCEL: *u8 = "cancel"
31
32const JR_OMODE: i64 = 0x1a4
33const JR_STDOUT: i64 = 1
34const JR_STDERR: i64 = 2
35const JR_MAXARGV: i64 = 32
36const JR_NL: i64 = 10
37const JR_TAB: i64 = 9
38const JR_HASH: i64 = 35
39
40func jr_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
41func jr_puts(s: *u8) -> i64 { sys_write(JR_STDOUT, s, jr_slen(s)); return 0 }
42func jr_werr(s: *u8) -> i64 { sys_write(JR_STDERR, s, jr_slen(s)); return 0 }
43// append a NUL-terminated string into a buffer; returns the new offset. Pairs with ccz_cat_num from
44// nx_itoa_lib so the journal line is built with ZERO allocation per field.
45func jr_cat(d: *u8, off: i64, s: *u8) -> i64 {
  var o: i64 = off
  var i: i64 = 0
  while s[i] != (0 as u8) { d[o] = s[i]; o = o + 1; i = i + 1 }
  return o
50}
51// MIGRATED to the shared emitter (debt 1785563586). The old body mmapped a scratch buffer
52// per call and never freed it. At PAGE granularity that is 4096B leaked PER CALL -- the
53// defect that took 28.5GB of a 36GB host in nx_ts_lumadiff (2MB input, ~3.66M calls).
54// nxi_* is MSB-first, allocates NOTHING, and emits identical bytes including the sign.
55func jr_putn(v: i64) -> i64 { nxi_out(v); return 0 }
56func jr_slice_eq(buf: *u8, start: i64, end: i64, s: *u8) -> i64 {
  var i: i64 = start
  var j: i64 = 0
  while i < end {
      if s[j] == (0 as u8) { return 0 }
      if buf[i] != s[j] { return 0 }
      i = i + 1
      j = j + 1
  }
  if s[j] != (0 as u8) { return 0 }
  return 1
67}
68func jr_contains(hay: *u8, needle: *u8) -> i64 {
  if needle[0] == (0 as u8) { return 1 }
  var i: i64 = 0
  while hay[i] != (0 as u8) {
      var j: i64 = 0
      var m: i64 = 1
      while m == 1 {
          if needle[j] == (0 as u8) { return 1 }
          if hay[i+j] == (0 as u8) { m = 0 } else { if hay[i+j] != needle[j] { m = 0 } else { j = j + 1 } }
      }
      i = i + 1
  }
  return 0
81}
82func jr_is_tmp(p: *u8) -> i64 {
  if p[0] != (47 as u8) { return 0 }
  if p[1] != (116 as u8) { return 0 }
  if p[2] != (109 as u8) { return 0 }
  if p[3] != (112 as u8) { return 0 }
  if p[4] != (47 as u8) { return 0 }
  return 1
89}
90func jr_has_dotdot(p: *u8) -> i64 {
  var i: i64 = 0
  while p[i] != (0 as u8) {
      if p[i] == (46 as u8) { if p[i+1] == (46 as u8) { return 1 } }
      i = i + 1
  }
  return 0
97}
98
99func main(argc: i64, argv: *i64) -> i64 {
  if argc < 3 { jr_werr("usage: nx_job_run <tool-name(allowlisted GREEN, non-daemon)> <out-file:/tmp/...> [args...]\n" as *u8); sys_exit(1); return 1 }
  let name: *u8 = argv[1] as *u8
  let outp: *u8 = argv[2] as *u8
103
  // ES29 CANCEL VERB (2026-09-15): `nx_job_run cancel <out-file>` stops the job THIS launcher recorded for that
  // out-file and nothing else -- the journal row must exist (REFUSED-ABSENT) and the live pid's argv[0] must be
  // the elf the row names (REFUSED-MISMATCH), so a recycled pid, a stranger or a daemon is never signalled.
  // TERM, a grace from knowledge/jobrun.conf (cancel_grace_ms), then KILL; the outcome is journaled beside the
  // launch. MEASURED NEED: two one-shots held the host at load 27 for 30 h with no sovereign way to stop them.
  if jr_slice_eq(name, 0, jr_slen(name), JR_VERB_CANCEL) == 1 {
      if jr_is_tmp(outp) == 0 { jr_werr("REFUSED: out-file must be under /tmp/ (write-surface defense)\n" as *u8); sys_exit(2); return 2 }
      if jr_has_dotdot(outp) == 1 { jr_werr("REFUSED: out-file must not contain '..'\n" as *u8); sys_exit(2); return 2 }
      let grace: i64 = jc_conf_grace(JC_CONF, JC_GRACE_MS_DEFAULT)
      let cpid: *i64 = sys_mmap(8) as *i64
      let code: i64 = jc_cancel(JC_JRNL, outp, grace, JC_POLL_MS, cpid)
      jr_puts("JOB-CANCEL out=" as *u8); jr_puts(outp)
      jr_puts(" pid=" as *u8); jr_putn(cpid[0])
      jr_puts(" outcome=" as *u8); jr_puts(jc_outcome_name(code))
      jr_puts(" grace_ms=" as *u8); jr_putn(grace)
      jr_puts(" journal=" as *u8); jr_puts(JC_JRNL)
      jr_puts("\n" as *u8)
      sys_exit(code); return code
  }
123
  if jlb_denied(name) == 1 { jr_werr("REFUSED: daemons, servers, supervisors and control-plane organs (deploy/promote/restart/kill/mgmt/hostctl) are never async-launchable -- they outlive the call or mutate the live plane. Generators are launchable once vetted GREEN in tool_allowlist.conf.\n" as *u8); sys_exit(6); return 6 }
  if jr_is_tmp(outp) == 0 { jr_werr("REFUSED: out-file must be under /tmp/ (write-surface defense)\n" as *u8); sys_exit(2); return 2 }
  if jr_has_dotdot(outp) == 1 { jr_werr("REFUSED: out-file must not contain '..'\n" as *u8); sys_exit(2); return 2 }
127
  let lenp: *i64 = sys_mmap(8) as *i64
  lenp[0] = 0
  let buf: *u8 = sys_read_file("tool_allowlist.conf" as *u8, lenp)
  let n: i64 = lenp[0]
  if n <= 0 { jr_werr("REFUSED: tool registry unreadable\n" as *u8); sys_exit(3); return 3 }
133
  let elfbuf: *u8 = sys_mmap(JR_MAGIC_1024)
  var found: i64 = 0
  var was_pinned: i64 = 0
  var i: i64 = 0
  while i < n {
      var le: i64 = i
      var s: i64 = 1
      while s == 1 { if le >= n { s = 0 } else { if buf[le] == (JR_NL as u8) { s = 0 } else { le = le + 1 } } }
      if le > i { if buf[i] != (JR_HASH as u8) {
          var ne: i64 = i
          var s2: i64 = 1
          while s2 == 1 { if ne >= le { s2 = 0 } else { if buf[ne] == (JR_TAB as u8) { s2 = 0 } else { ne = ne + 1 } } }
          if ne > i { if found == 0 { if jr_slice_eq(buf, i, ne, name) == 1 {
              var ps: i64 = ne + 1
              var pe: i64 = ps
              var s3: i64 = 1
              while s3 == 1 { if pe >= le { s3 = 0 } else { if buf[pe] == (JR_TAB as u8) { s3 = 0 } else { pe = pe + 1 } } }
              var gs: i64 = pe + 1
              var ge: i64 = gs
              var s4: i64 = 1
              while s4 == 1 { if ge >= le { s4 = 0 } else { if buf[ge] == (JR_TAB as u8) { s4 = 0 } else { ge = ge + 1 } } }
              if jr_slice_eq(buf, gs, ge, "GREEN" as *u8) == 1 {
                  if ge >= le {
                      if pe > ps {
                          var eo: i64 = 0
                          var k: i64 = ps
                          while k < pe { elfbuf[eo] = buf[k]; eo = eo + 1; k = k + 1 }
                          elfbuf[eo] = 0 as u8
                          found = 1
                      }
                  } else { was_pinned = 1 }
              }
          } } }
      } }
      i = le + 1
  }
170
  if found == 0 {
      if was_pinned == 1 { jr_werr("REFUSED: '" as *u8); jr_werr(name); jr_werr("' is PINNED; nx_job_run only launches UNPINNED GREEN tools (anti-pin-bypass)\n" as *u8); sys_exit(5); return 5 }
      jr_werr("REFUSED: '" as *u8); jr_werr(name); jr_werr("' is not an unpinned GREEN tool in the registry\n" as *u8); sys_exit(4); return 4
  }
175
  // ★EXISTENCE CHECK BEFORE THE FORK (2026-08-01, debt 1785623939). Every guard above validates
  // the NAME -- registered, GREEN, unpinned, not a daemon -- and NOTHING validated that the elf
  // the row points at still EXISTS. After execve fails in the child there is no way to report it:
  // the parent has already returned JOB-STARTED and never wait4's. Reproduced live: a tool row
  // registered against a `.sov.elf.new` STAGING artifact, which /api/promote then consumed,
  // printed a confident `JOB-STARTED pid=8938` and simply never wrote its out-file. ABSENCE OF
  // OUTPUT WAS THE ONLY SIGNAL -- the same reported-green-wrote-nothing shape that cost a whole
  // session elsewhere today.
  // ★★★★★A LAUNCHER THAT VALIDATES THE NAME BUT NOT THE ARTIFACT REPORTS SUCCESS FOR A PROCESS
  // THAT CANNOT START. Fail LOUD here, where a caller can still see it, instead of silently in a
  // child nobody reaps.
  let jr_probe: i64 = sys_openat_rd(elfbuf)
  if jr_probe < 0 {
      jr_werr("REFUSED: registry row for '" as *u8); jr_werr(name)
      jr_werr("' points at a MISSING elf: " as *u8); jr_werr(elfbuf)
      jr_werr("\n  the row is dangling -- most often it was registered against a .sov.elf.new STAGING\n" as *u8)
      jr_werr("  artifact that a later /api/promote consumed. Rebuild the target to regenerate it, or\n" as *u8)
      jr_werr("  re-register the name against the PROMOTED .elf. BUILD -> PROMOTE -> THEN REGISTER.\n" as *u8)
      sys_exit(7); return 7
  }
  sys_close(jr_probe)
197
  let pid: i64 = sys_fork()
  if pid == 0 {
      let of: i64 = sys_openat_wr(outp, JR_OMODE)
      if of >= 0 { sys_dup3(of, JR_STDOUT, 0); sys_dup3(of, JR_STDERR, 0) }
      let av: *i64 = sys_mmap(JR_MAXARGV*8) as *i64
      av[0] = elfbuf as i64
      var a: i64 = 3
      var kk: i64 = 1
      while a < argc { if kk < JR_MAXARGV - 1 { av[kk] = argv[a]; kk = kk + 1 } a = a + 1 }
      av[kk] = 0
      let envp: *i64 = sys_mmap(16) as *i64
      envp[0] = "PATH=/usr/bin:/bin" as *u8 as i64
      envp[1] = 0
      sys_execve(elfbuf, av, envp)
      sys_exit(127)
  }
  // ★★★RECORD THE ORGAN WE RAN, NOT OURSELVES. nx_catalog and nx_wirecensus derive INVOKED from TAB
  // field 2 of actlog.jrnl, and a direct fork logged NOTHING -- so every organ driven the estate's own
  // recommended way (`nx_job_run <tool> /tmp/out`) read REGISTERED-DARK, "never run". MEASURED
  // 2026-08-14: nx_dstate, nx_gateaddr and nx_bodyfit_canon_gate all read never-run while being
  // executed repeatedly in the same session. That made the estate's HEADLINE ADOPTION SIGNAL A FLOOR
  // RATHER THAN A VALUE -- daily-used capability counted as unadopted.
  // nx_wirecensus_lib calls this axis "WEAK BUT POSITIVE ... Seats log", i.e. it depended on a human
  // REMEMBERING to journal. ★A MEASUREMENT THAT DEPENDS ON BEING REMEMBERED IS A MEASUREMENT THAT
  // UNDERCOUNTS; the launcher is the one thing that always knows, so the launcher records it.
  // ★OUTCOME IS `started`, NEVER `ok`: this parent deliberately does NOT wait4 -- that IS the async
  // contract -- so it CANNOT observe the exit. Writing `ok` would fabricate an outcome nobody measured.
  // ★FAIL-SOFT: an unopenable journal NEVER affects the launch. The job is the deliverable; the record
  // is bookkeeping, and bookkeeping must not be able to break the work.
  let lg: i64 = sys_openat_append("knowledge/status/actlog.jrnl" as *u8, JR_OMODE)
  if lg >= 0 {
      let ln: *u8 = sys_mmap(JR_MAGIC_1024)
      var o: i64 = ccz_cat_num(ln, 0, sys_now_realtime_sec())
      ln[o] = JR_TAB as u8; o = o + 1
      o = jr_cat(ln, o, "jobrun" as *u8)
      ln[o] = JR_TAB as u8; o = o + 1
      o = jr_cat(ln, o, name)
      ln[o] = JR_TAB as u8; o = o + 1
      o = jr_cat(ln, o, "launch" as *u8)
      ln[o] = JR_TAB as u8; o = o + 1
      o = jr_cat(ln, o, "started" as *u8)
      ln[o] = JR_TAB as u8; o = o + 1
      o = jr_cat(ln, o, "forked by nx_job_run pid=" as *u8)
      o = ccz_cat_num(ln, o, pid)
      o = jr_cat(ln, o, " -- exit NOT observed (async runner does not wait4)" as *u8)
      ln[o] = JR_NL as u8; o = o + 1
      sys_write(lg, ln, o)
      sys_close(lg)
      sys_munmap(ln, JR_MAGIC_1024)
  }
  // ES29: the launch row the cancel verb resolves; fail-soft like the actlog row above (the job is the deliverable)
  jc_journal(JC_JRNL, JC_KIND_LAUNCH, sys_now_realtime_sec(), pid, elfbuf, outp, name)
  jr_puts("JOB-STARTED pid=" as *u8)
  jr_putn(pid)
  jr_puts(" tool=" as *u8)
  jr_puts(name)
  jr_puts(" elf=" as *u8)
  jr_puts(elfbuf)
  jr_puts(" out=" as *u8)
  jr_puts(outp)
  jr_puts("\n" as *u8)
  sys_exit(0)
  return 0
261}
nx_job_run.nx source

`nx_job_run.nx` source
