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

↩ module page · 1207 lines · 77255 B
1// nx_clock_sched.nx -- RENAMED FROM nx_clock.nx 2026-07-31 (lib-reconcile). PERMANENT FIX for a
2// two-libraries-one-name collision: runtime/nx_clock.nx is the TIMING library (nx_clock_monotonic_ns,
3// 62 importers); THIS file is an unrelated tickless JOB SCHEDULER (clk_* registry + dispatcher) that
4// only shared the filename. nx_cc binds an import to the IMPORTER'S OWN DIRECTORY FIRST, so every
5// _hdl_build organ importing nx_clock.nx silently got the SCHEDULER -- _clk_probe.nx, whose whole
6// purpose is to prove nx_clock_monotonic_ns works, could not resolve it. The RENAME is the fix.
7// so we avoid issues ... dont have a million pulses and daemons"). Researched (knowledge/fetched/sched_*.raw:
8// clock-distribution = ONE oscillator -> a tree of DIVIDERS; PLL derives every frequency from ONE reference;
9// cron = ONE daemon reads ONE table of timed jobs; tickless = don't burn a constant tick when idle). The S-class
10// pattern is identical: ONE tick source + ONE durable JOB REGISTRY + ONE dispatcher. Every periodic capability
11// REGISTERS a job (name, interval-in-ticks) = a divider off the single clock -- it does NOT spin up its own
12// daemon/pulse loop. So N capabilities cost ONE loop, not N. This library is the registry + dispatcher; the single
13// tick source drives it (one external spark, like a crystal). license_tier: ORIGINAL
14import "nx_syscalls.nx"
15import "nx_store_seed_lib.nx"
16import "nx_clock_caps.nx"
17import "nx_ioadmit_lib.nx"   // ioa_measure / ioa_spawn_budget: THE I/O-storm ruler nx_build_admit uses -- composed here so the clock and the build gate can never disagree about whether the box is in a storm (2026-09-02)
18const CLK_MAGIC_1000000: i64 = 1000000
19
20const CLK_MAXJOBS: i64 = 512       // WAS 128 (2026-08-19): the desired plane hit 128/128 and every
                                 // over-cap path was a SILENT drop -- a beat that vanishes at merge.
                                 // 4x headroom; clk_register now refuses LOUDLY at the cap. Residual,
                                 // named: the inline merge-at-cap skips stay quiet above 512.
24// DUTY-CYCLE CEILING FOR A COST-OVERRUNNING JOB (2026-08-06). Re-arming an overrunning job to exactly
25// its own runtime still leaves it consuming HALF the serial scheduler -- MEASURED: nx_worldgen_gate runs
26// 289s against a declared 120s period, so plain backoff took the blackout from ~96pct to ~50pct and
27// sitecheck stayed frozen through every run. Backing off to runtime*9 caps any single job at ~1/10 of
28// the scheduler. NOT A MAGIC NUMBER: it is the reciprocal of the duty-cycle budget (9 => <=10pct), and
29// it is the ONLY knob here, so raising it loosens the ceiling monotonically and nothing else moves.
30// (STAR)A SERIAL SCHEDULER MUST BOUND WHAT FRACTION OF ITSELF ONE JOB CAN OWN, BECAUSE EVERY OTHER JOB'S
31// LIVENESS IS THAT FRACTION'S COMPLEMENT.
32const CLK_HOGDUTY: i64 = 9
33// ---- PER-DISPATCH DEADLINE (2026-08-06): ADOPTION, NOT INVENTION -------------------------------
34// nx_guarded_run.nx ALREADY solved "fork + wait4 WNOHANG + deadline + SIGKILL" and a dozen organs use
35// it (nx_tool_run, nx_sweep_core, nx_boot_revive, nx_web_crawl_step...). The clock simply never adopted
36// it and kept a bare BLOCKING sys_wait4(pid, st, 0) -- which is why one child could own the scheduler
37// indefinitely (debt 1786056459; proven live: 475s+ stall and the 1800s budget overrun by 42s).
38// (STAR)THE ESTATE HAD ALREADY SOLVED IT AND THE CLOCK DID NOT LOOK -- an ADOPTION gap, not a missing
39// primitive. Inlined rather than imported because nx_guarded_run.nx carries its own main() self-test.
40// nx_kill is the SANCTIONED wrapper: nx_syscalls notes the compiler BAKES bodies BY NAME, so a function
41// literally named sys_kill emits syscall 8; nx_kill passes rv64 129 which the sovereign table maps to
42// x86_64 62. Using the raw x86 62 here would have silently become lseek(8) and never killed anything.
43// DEADLINE = ONE FULL WINDOW: a single dispatch longer than the entire window is starving that window
44// BY DEFINITION, and it reaps nothing measured legitimate (worldgen 289s/286s, segguard ~700s).
45const CLK_SIGKILL:             i64 = 9
46const CLK_DISPATCH_POLL_MS:    i64 = 250
47// PER-JOB KILL DEADLINE. 900000ms = 900s = HALF the 1800s scheduling window (TLN_WINDOW_SECS).
48// WAS 1800000ms = the ENTIRE window, which is not a deadline at all: a single job could legally consume
49// the whole scheduler and the guard could not fire before the window ended anyway. A BOUND EQUAL TO THE
50// BUDGET CANNOT BIND. The call site below sells this as the fix for "the single line that let one child
51// own the clock" -- the bounded wait DID replace a bare blocking wait4, but the bound was then set to the
52// full budget, so the protection was nominal.
53// DERIVED, NOT CHOSEN: half the window means no single job can ever take more than half the scheduler,
54// and it carries 2.2x margin over the largest LEGITIMATE runtime measured on 2026-08-14 (max_exec across
55// three consecutive windows: 41s, 92s, and 408s for nx_compare_beat.elf). If that margin is ever wrong
56// the failure is VISIBLE, not silent: a job killed here is logged by clk_actlog with code 124 (the shell
57// timeout convention), so an over-tight bound surfaces as a named row rather than a mystery.
58// HONEST SCOPE: this bounds the PATHOLOGICAL case only. It does NOT fix the starvation measured that day
59// (b=11 -> 16 -> 23), which is cumulative time on a SERIAL dispatcher -- exec 761s -> 990s -> 1167s of an
60// 1800s window -- not one job monopolising. That needs bounded concurrency in clk_run_edf (debt 3952).
61const CLK_DISPATCH_DEADLINE_MS: i64 = 900000
62const CLK_NAMEW:   i64 = CLK_CMD_CAP   // bytes per name/organ slot -- DERIVED from the ONE shared
                                 // command cap in nx_clock_caps.nx, the SAME const nx_clockjob's
                                 // CJ_ROWCAP is derived from, so the reader can never hold less than
                                 // the writer admits. WAS 128 (2026-08-03..08-22): every command
                                 // longer than 127 bytes was SILENTLY CUT at merge/save/load -- 7
                                 // live rows executed truncated argv (gateroster beat ran with
                                 // deadline 1800 instead of 180000; admit/refusalshape/alertscore
                                 // wrote knowledge/gateroster.c, knowledge/stat and kno). Before
                                 // that it WAS 48 (debt 1784413227): 51/63-char paths fork-failed
                                 // 127 on every tick. A SLOT NARROWER THAN WHAT THE WRITER ADMITS
                                 // IS A SILENT TRUNCATOR WEARING A CONSTANT -- bind both ends to
                                 // ONE imported const, never mirror a number.
74const CLK_ROWW:    i64 = 2*CLK_NAMEW + 64   // per-row serialization budget, DERIVED, not chosen:
                                 // 2 slots + 2 i64 decimals (<=20 bytes each) + 3 tabs + newline
                                 // = 2*CLK_NAMEW + 44, held with 64 so the two numbers can never
                                 // outgrow it (a hand-counted width beside a widened slot is the
                                 // drift class this whole change retires)
79const CLK_REG:     *u8 = "knowledge/sched/jobs.tsv"   // RETIRED LEGACY PATH (2026-08-03, debt 1785792856):
                                 // kept only so old fixtures parse; the live state SSOT is the
                                 // clocksched- seg-store plane (clk_load_state / clk_save_plane below)
82
83// ---- STORM-AWARE DISPATCH FOR HEAVY BEATS (2026-09-02, /compare/loadgov LV14) ----------------------
84// MEASURED THE SAME DAY: procchurn read cpu busy 24.5 percent with blocked >> running (I/O-bound), the
85// D-state roster carried nx_web_crawl_step (706 s), nx_secret_scan and nx_web_shard_compact -- all CLOCK
86// BEATS -- and every seat build was refused by admission for the same storm those beats were feeding.
87// This dispatcher had NO admission at all: a due job forked regardless of the box, so the beats that
88// cause a storm fired INTO it while the one lane that does check admission (the build queue) waited.
89// A SCHEDULER THAT CHECKS NOTHING IS THE STORM'S FEEDER, AND THE POLITE LANE PAYS FOR IT.
90// DESIGN, data-driven and fail-open: a job is HEAVY only if its NAME is listed in CLK_HEAVY_CONF (one
91// exact name per line; an unlisted job dispatches byte-for-byte as before, and an absent conf lists
92// nothing). A heavy job that is due while the shared ruler reports ZERO spawn budget (procs_blocked at
93// the storm line, the same conjunct nx_build_admit refuses on) is DEFERRED: re-armed to now plus a
94// fraction of its own period, counted, and announced on the in-flight beat as deferred-storm. It still
95// runs -- one storm cannot park it past CLK_DEFER_MAX_S per probe -- and EDF's own starvation report
96// still names it if the deferral compounds. An UNREADABLE ruler never defers: an axis that cannot see
97// must abstain, and here abstaining means the pre-change behaviour, never a stalled clock.
98// The instruments themselves (resmon, memvel, procchurn, sitecheck, netobs, tlsprobe, kaprobe) must
99// NEVER be listed: a detector deferred by the storm it detects is the axis-blind defect wearing a conf.
100const CLK_HEAVY_CONF: *u8 = "knowledge/status/clock_heavy.conf"
101const CLK_DEFER_DIV: i64 = 4       // re-arm at interval/4: a 1800 s beat re-checks every 450 s, so a storm costs it at most 3 probes before its own next period
102const CLK_DEFER_MIN_S: i64 = 60    // floor: the shortest re-check that is not a busy loop against /proc/stat
103const CLK_DEFER_MAX_S: i64 = 900   // cap: half a window, the same bound CLK_DISPATCH_DEADLINE_MS already places on one job
104// PURE: exact-whole-line membership of `name` in a newline-separated conf (CR-tolerant), the same
105// grammar the tools daemon's async_only_tools.conf reader uses, so a name with a suffix can never match.
106func clk_heavy_listed(conf: *u8, n: i64, name: *u8) -> i64 {
  if n <= 0 { return 0 }
  var nl: i64 = 0
  while name[nl] != (0 as u8) { nl = nl + 1 }
  if nl == 0 { return 0 }
  var i: i64 = 0
  var hit: i64 = 0
  while i < n {
      var e: i64 = i
      var eol: i64 = 0
      while eol == 0 {
          if e >= n { eol = 1 } else { if conf[e] == (10 as u8) { eol = 1 } else { e = e + 1 } }
      }
      var len: i64 = e - i
      if len > 0 { if conf[i + len - 1] == (13 as u8) { len = len - 1 } }
      if len == nl { if hit == 0 {
          var k: i64 = 0
          var same: i64 = 1
          while k < nl { if conf[i + k] != name[k] { same = 0; k = nl } else { k = k + 1 } }
          if same == 1 { hit = 1 }
      } }
      i = e + 1
  }
  return hit
130}
131// PURE: how long a deferred heavy job waits before EDF may pick it again -- a fraction of its own
132// period, clamped so a 60 s beat is not busy-polled and a daily beat is not parked for hours.
133func clk_defer_secs(interval: i64) -> i64 {
  var d: i64 = interval / CLK_DEFER_DIV
  if d < CLK_DEFER_MIN_S { d = CLK_DEFER_MIN_S }
  if d > CLK_DEFER_MAX_S { d = CLK_DEFER_MAX_S }
  return d
138}
139// PURE: the decision. heavy=1 AND budget==0 -> DEFER. budget<0 is UNOBSERVABLE (the ruler could not
140// read /proc/stat) and must NOT defer: abstain toward the pre-change behaviour. A light job never defers.
141func clk_storm_defer(heavy: i64, budget: i64) -> i64 {
  if heavy != 1 { return 0 }
  if budget == 0 { return 1 }
  return 0
145}
146// The live measurement, composed from the shared ruler with its OWN calibration constants, so the
147// clock refuses on exactly the D-state line the build gate refuses on. ioa[0]=ncpu ioa[1]=procs_blocked.
148func clk_storm_budget(ioa: *i64) -> i64 {
  if ioa_measure(ioa) != 0 { return IOA_UNREADABLE }
  return ioa_spawn_budget(ioa[0], ioa[1], IOA_BLOCKED_PER_CPU, IOA_RESERVE_SLOTS)
151}
152
153func clk_slot(names: *u8, i: i64) -> *u8 { return ((names as i64) + i*CLK_NAMEW) as *u8 }
154func clk_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 }
155
156func clk_find(names: *u8, n: i64, name: *u8) -> i64 { var i: i64=0; while i<n { if clk_streq(clk_slot(names,i), name)==1 { return i } i=i+1 } return 0-1 }
157
158// REGISTER a periodic job = add a divider off the one clock. Idempotent: re-registering the same name is a no-op
159// (so capabilities can declare their job every boot without ever creating a duplicate pulse). returns 1 if added.
160func clk_register(names: *u8, organs: *u8, intervals: *i64, next_due: *i64, np: *i64, name: *u8, organ: *u8, interval: i64) -> i64 {
  let n: i64 = np[0]
  // A re-registration whose ORGAN or INTERVAL differs must LAND. This returned 0 for both
  // "already present, identical" and "already present, DIFFERENT", so every correction was a
  // silent no-op. Measured over the whole clockjobs- plane 2026-08-07: four names carry different
  // commands across rows and the live beat was the OLD one in every case -- segguard still ran
  // nx_segguard.sh while nx_segsweep.elf had been re-registered three times; lmexport, stalesweep
  // and ddqbeat likewise still ran their .cron.sh. A shell-to-organ migration of four beats was
  // written and never took effect, and nothing could see it because 0 was the only signal.
  // An IDENTICAL re-declaration stays a no-op, so capabilities may still declare their job every
  // boot without churn. Returns 0 unchanged, 2 updated.
  // ★★★★★★ IDEMPOTENCE AND IMMUTABILITY ARE NOT THE SAME PROPERTY: AN IDEMPOTENT-BY-NAME
  // REGISTRAR MAKES THE FIRST WRITE PERMANENT AND EVERY LATER CORRECTION A SILENT NO-OP.
  let ex: i64 = clk_find(names, n, name)
  if ex >= 0 {
      var iv0: i64 = interval
      if iv0 < 1 { iv0 = 1 }
      var eo: *u8 = clk_slot(organs, ex)
      var same: i64 = 1
      var q: i64 = 0
      var st: i64 = 0
      while st == 0 {
          let a: i64 = eo[q] as i64
          let b: i64 = organ[q] as i64
          if a != b { same = 0; st = 1 }
          if st == 0 {
              if a == 0 { st = 1 }
              if a != 0 {
                  q = q + 1
                  if q >= CLK_NAMEW { st = 1 }
              }
          }
      }
      if intervals[ex] != iv0 { same = 0 }
      if same == 1 { return 0 }
      var w: i64 = 0
      while w < CLK_NAMEW - 1 {
          if organ[w] == (0 as u8) { eo[w] = 0 as u8; w = CLK_NAMEW } else { eo[w] = organ[w]; w = w + 1 }
      }
      if w == CLK_NAMEW - 1 { eo[w] = 0 as u8 }
      intervals[ex] = iv0
      next_due[ex] = iv0
      return 2
  }
  if n >= CLK_MAXJOBS {
      // A CAP REACHED IN SILENCE BECOMES A REGISTRATION NOBODY KNOWS WAS DROPPED (2026-08-19:
      // measured 128/128 with every over-cap path a quiet return). Say WHICH row was refused.
      let cm: *u8 = "CLOCK-CAP-DROP register refused at CLK_MAXJOBS: " as *u8
      var cl: i64 = 0
      while cm[cl] != (0 as u8) { cl = cl + 1 }
      sys_write(1, cm, cl)
      var nl2: i64 = 0
      while name[nl2] != (0 as u8) { nl2 = nl2 + 1 }
      sys_write(1, name, nl2)
      sys_write(1, "\n" as *u8, 1)
      return 0
  }
  var d: *u8 = clk_slot(names, n); var i: i64=0
  while i<CLK_NAMEW-1 { if name[i]==(0 as u8){ d[i]=0 as u8; i=CLK_NAMEW } else { d[i]=name[i]; i=i+1 } }
  if i==CLK_NAMEW-1 { d[i]=0 as u8 }
  var e: *u8 = clk_slot(organs, n); var j: i64=0
  while j<CLK_NAMEW-1 { if organ[j]==(0 as u8){ e[j]=0 as u8; j=CLK_NAMEW } else { e[j]=organ[j]; j=j+1 } }
  if j==CLK_NAMEW-1 { e[j]=0 as u8 }
  var iv: i64 = interval; if iv < 1 { iv = 1 }
  intervals[n] = iv; next_due[n] = iv; np[0] = n + 1
  return 1
226}
227
228// THE DISPATCHER: advance to logical tick `now`; mark + return how many jobs are DUE (next_due<=now), advancing
229// each due job's next_due by its interval (catch-up safe: a job never fires more than once for a missed window).
230func clk_tick(intervals: *i64, next_due: *i64, n: i64, now: i64, fired: *i64) -> i64 {
  var count: i64 = 0; var i: i64 = 0
  while i < n {
      if next_due[i] <= now {
          fired[i] = 1; count = count + 1
          while next_due[i] <= now { next_due[i] = next_due[i] + intervals[i] }   // re-arm past now (no runaway on a skipped tick)
      } else { fired[i] = 0 }
      i = i + 1
  }
  return count
240}
241
242// THE FUNCTIONAL DISPATCH: advance to `now` and actually RUN each due job by fork+exec of its organ elf path
243// (the same fork+exec idiom nx_god_pulse / nx_aw_hostctl use). One dispatcher runs N jobs at their divided rates;
244// there is NO per-job daemon. Parent waits each child so a slow job can't be lost (a real scheduler can make this
245// bounded-concurrent / fire-and-forget). `organs` is a parallel slot array (organ[i] = an executable path). Returns
246// the number of jobs dispatched this tick.
247func clk_dispatch_run(organs: *u8, intervals: *i64, next_due: *i64, n: i64, now: i64, fired: *i64) -> i64 {
  var count: i64 = 0; var i: i64 = 0
  while i < n {
      if next_due[i] <= now {
          fired[i] = 1
          while next_due[i] <= now { next_due[i] = next_due[i] + intervals[i] }   // re-arm past now (catch-up safe)
          let path: *u8 = clk_slot(organs, i)
          __syscall(90, path as i64, 0x1ed, 0, 0, 0, 0)   // chmod 0755 first: recv-shipped organs aren't reliably +x (HC_MGMT_CMD chmods for the same reason) -> without this execve fails 127 = silent no-dispatch
          let pid: i64 = sys_fork()
          if pid == 0 {
              let argv: *i64 = sys_mmap(32) as *i64; argv[0] = path as i64; argv[1] = 0
              let envp: *i64 = sys_mmap(16) as *i64; envp[0] = "PATH=/usr/bin:/bin" as *u8 as i64; envp[1] = 0
              sys_execve(path, argv, envp)
              sys_exit(127)
          }
          let st: *i64 = sys_mmap(16) as *i64; st[0] = 0
          sys_wait4(pid, st, 0)
          let raw: i64 = st[0]; let sig: i64 = raw & 0x7f; let code: i64 = (raw >> 8) & 0xff
          // HONEST count: a job whose organ failed to exec (child exit 127 = missing/broken organ) did NOT run,
          // so it is not counted as dispatched (it gets fired[]=1 so a caller can flag it, mirroring the
          // publisher's dead-letter). A crash (signalled) or any other exit means the organ DID run.
          // NO JOB NAME ON THIS PATH, BY CONSTRUCTION (2026-09-18): clk_dispatch_run holds no names array and
          // its signature is shared with nx_clock_run and nx_clock_dispatch_gate, so it passes null and its
          // row stays byte-identical to the old shape. The LIVE path (clk_run_edf -> clk_dispatch_one) names the job.
          clk_actlog(path, code, 0 as *u8)
          if sig != 0 { count = count + 1 } else { if code != 127 { count = count + 1 } }
      } else { fired[i] = 0 }
      i = i + 1
  }
  return count
277}
278
279// TICKLESS run (sched_tickless lesson): from start_tick, run up to maxbeats beats, but before each beat SLEEP
280// exactly until the MINIMUM next_due across all jobs -- skipping every idle tick -- then dispatch the due organs.
281// Advances next_due[] in place (the caller persists for resume). out[0..3] = beats, dispatches, skipped_idle,
282// final_tick. ONE implementation, shared by the driver (nx_clock_tickless) and its gate (no parallel copy).
283func clk_run_tickless(organs: *u8, intervals: *i64, next_due: *i64, n: i64, start_tick: i64, maxbeats: i64, tick_ms: i64, out: *i64) -> i64 {
  let fired: *i64 = sys_mmap(CLK_MAXJOBS*8) as *i64
  var T: i64 = start_tick; var beats: i64 = 0; var disp: i64 = 0; var skipped: i64 = 0
  while beats < maxbeats {
      var minnd: i64 = next_due[0]; var i: i64 = 1
      while i < n { if next_due[i] < minnd { minnd = next_due[i] } i = i + 1 }
      if minnd <= T { minnd = T + 1 }
      let skip: i64 = minnd - T
      if skip > 1 { skipped = skipped + (skip - 1) }
      let totms: i64 = skip * tick_ms
      let ts: *i64 = sys_mmap(16) as *i64; ts[0] = totms / 1000; ts[1] = (totms - (totms/1000)*1000) * CLK_MAGIC_1000000
      __syscall(35, ts as i64, 0, 0, 0, 0, 0)             // nanosleep until the next due event (tickless)
      T = minnd
      disp = disp + clk_dispatch_run(organs, intervals, next_due, n, T, fired)
      beats = beats + 1
  }
  out[0] = beats; out[1] = disp; out[2] = skipped; out[3] = T
  return disp
301}
302
303// STATUS helpers (the consolidation payoff: ONE place shows every periodic job). clk_due_in = ticks until a job
304// fires (<=0 means due now). clk_twin_ok = 1 iff the job's organ elf actually exists (a 0 means it is registered
305// but un-blessed -> the dispatcher would honestly report it didn't run -> surface it in status, do not hide it).
306func clk_due_in(next_due_i: i64, now: i64) -> i64 { return next_due_i - now }
307func clk_twin_ok(organ: *u8) -> i64 { let fd: i64 = sys_openat_rd(organ); if fd < 0 { return 0 } sys_close(fd); return 1 }
308
309func clk_itoa(buf: *u8, o: i64, v: i64) -> i64 { var w: i64=o; var m: i64=v; if m==0{buf[w]=48 as u8;return w+1} if m<0{buf[w]=45 as u8;w=w+1;m=0-m} let t:*u8=sys_mmap(24); var k:i64=0; while m>0{t[k]=(48+(m%10)) as u8;m=m/10;k=k+1} var j:i64=0; while j<k{buf[w]=t[k-1-j];w=w+1;j=j+1} return w }
310
311// persist the registry (the ONE crontab): name<TAB>interval<TAB>next_due per line. atomic via tmp+rename.
312func clk_msgcat(d: *u8, o: i64, s: *u8) -> i64 { var x: i64=o; var i: i64=0; while s[i]!=(0 as u8){d[x]=s[i];x=x+1;i=i+1} return x }
313func clk_msgnum(d: *u8, o: i64, v: i64) -> i64 {
  var x: i64 = o
  var m: i64 = v
  if m < 0 { d[x] = 45 as u8; x = x + 1; m = 0 - m }
  if m == 0 { d[x] = 48 as u8; return x + 1 }
  let t: *u8 = sys_mmap(24)
  var k: i64 = 0
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  var j: i64 = 0
  while j < k { d[x] = t[k - 1 - j]; x = x + 1; j = j + 1 }
  sys_munmap(t, 24)
  return x
325}
326// ADOPTION VISIBILITY (2026-08-07). The clock captured per-job stdout to logs/<job>.log but wrote
327// NOTHING to knowledge/status/actlog.jrnl -- the ledger nx_catalog reads to decide INVOKED.
328// MEASURED: 19 REGISTERED TOOLS ARE CLOCK-DRIVEN, so every one of them could ONLY EVER report
329// REGISTERED-DARK, callable and authorised and NEVER RUN, no matter how often it actually ran. The
330// estate adoption headline was structurally blind to its entire scheduled population -- not wrong
331// about a few organs, blind to a whole class.
332// The row carries the ORGAN command, NOT the job name, because nx_catalog matches the ORGAN via a
333// substring scan of the ledger and the two names differ (job raidwatch vs organ nx_raidwatch).
334// FAIL-OPEN BY CONSTRUCTION: if the ledger cannot be opened this returns immediately and the beat is
335// untouched. Telemetry must never be able to stop the clock -- the same rule the per-job log capture
336// already follows. Tabs and newline are written as BYTES so no source escape can be mangled.
337//
338// JOB NAME ON THE ROW (2026-09-18). The row named only the ORGAN, so a clock row that runs
339// `nx_plan_run.elf <plan>` logged nx_plan_run.elf and nothing else, and the close ruler (nx_rungclose) --
340// which judges a rung OPERATED when its agent, a clock ROW NAME such as twincheck or searchship-dry, has
341// run since the rung landed -- could never witness ANY plan-run agent. The row now appends ` job=<row
342// name>` as the LAST token of its LAST field: `... clockjob lane=clock exit=<code> job=<name>`. ADDITIVE:
343// still six TAB fields, the ORGAN column byte-identical, every pre-existing byte in place.
344// THE LINE BUDGET grows by exactly one NAME slot, DERIVED, never chosen: the ORGAN (<= one slot) + the
345// JOB name (<= one slot) + <= 88 fixed bytes (two i64 decimals at <= 20 each, the literal words, five
346// TABs, " job=" and the LF), held with 128 so the fixed part can never outgrow it.
347const CLK_ACTLOGW: i64 = CLK_NAMEW + CLK_NAMEW + 128
348const CLK_TOKEN_MIN_BYTE: i64 = 33    // the first printable ASCII byte that is not a space; every byte below it is a space or a control byte
349const CLK_TOKEN_DEL_BYTE: i64 = 127   // ASCII DEL, the one control byte above the printable range
350
351// A JOB NAME IS WRITTEN ONLY WHEN IT CAN TRAVEL AS ONE TOKEN. Returns its length (1..CLK_NAMEW-1), or 0
352// for a null, empty, slot-overflowing or non-token name -- and on 0 the row carries NO job= field, the
353// pre-2026-09-18 shape byte for byte. WHY ABSENCE AND NOT A PLACEHOLDER: the reader matches `job=<agent>`
354// token-bounded, so an empty value, a value a SPACE splits in two, or a TAB/CR/LF that breaks the row
355// grammar could each hand it a witness for a job that never ran; a missing field can only read as "not
356// witnessed", the direction that under-claims. The scan is BOUNDED BY THE SLOT, so a name with no NUL
357// inside its slot can never run the line past CLK_ACTLOGW. Bytes >= 128 pass (a UTF-8 name is a token).
358func clk_job_token_len(job: *u8) -> i64 {
  if (job as i64) == 0 { return 0 }
  var n: i64 = 0
  var st: i64 = 0
  while st == 0 {
      if n >= CLK_NAMEW - 1 { st = 1 }
      else {
          let c: i64 = job[n] as i64
          if c == 0 { st = 1 }
          else {
              if c < CLK_TOKEN_MIN_BYTE { return 0 }
              if c == CLK_TOKEN_DEL_BYTE { return 0 }
              n = n + 1
          }
      }
  }
  if job[n] != (0 as u8) { return 0 }
  return n
376}
377
378// THE LEDGER ROW, AS A PURE FUNCTION (2026-09-18). Composes one actlog.jrnl row into `ln` (>= CLK_ACTLOGW
379// bytes) and returns its length. Split out of clk_actlog for the reason clk_split_argv was: a gate can
380// prove the row's shape WITHOUT writing the production ledger, and it proves it on the SAME code the
381// dispatcher runs -- one implementation, no mirrored copy to drift.
382// SHAPE: <epoch> TAB clock TAB <organ> TAB run TAB ok|fail TAB clockjob lane=clock exit=<code>[ job=<name>] LF
383func clk_actlog_row(ln: *u8, now: i64, organ: *u8, code: i64, job: *u8) -> i64 {
  var o: i64 = clk_msgnum(ln, 0, now)
  ln[o] = 9 as u8; o = o + 1
  o = clk_msgcat(ln, o, "clock" as *u8)
  ln[o] = 9 as u8; o = o + 1
  o = clk_msgcat(ln, o, organ)
  ln[o] = 9 as u8; o = o + 1
  o = clk_msgcat(ln, o, "run" as *u8)
  ln[o] = 9 as u8; o = o + 1
  if code == 0 { o = clk_msgcat(ln, o, "ok" as *u8) } else { o = clk_msgcat(ln, o, "fail" as *u8) }
  ln[o] = 9 as u8; o = o + 1
  o = clk_msgcat(ln, o, "clockjob lane=clock exit=" as *u8)
  o = clk_msgnum(ln, o, code)
  if clk_job_token_len(job) > 0 {
      o = clk_msgcat(ln, o, " job=" as *u8)
      o = clk_msgcat(ln, o, job)
  }
  ln[o] = 10 as u8; o = o + 1
  return o
402}
403
404// `job` is the clock ROW NAME (clk_slot(names, i)); null or empty writes the row without a job= field.
405func clk_actlog(organ: *u8, code: i64, job: *u8) -> i64 {
  var fd: i64 = sys_openat_append("knowledge/status/actlog.jrnl" as *u8, 420)
  if fd < 0 { fd = sys_openat_append("/volume1/homes/elderwesto/nishihost/knowledge/status/actlog.jrnl" as *u8, 420) }
  if fd < 0 { return 0 }
  let ln: *u8 = sys_mmap(CLK_ACTLOGW)
  let o: i64 = clk_actlog_row(ln, sys_now_realtime_sec(), organ, code, job)
  sys_write(fd, ln, o)
  sys_close(fd)
  sys_munmap(ln, CLK_ACTLOGW)
  return 0
415}
416func clk_save(path: *u8, names: *u8, organs: *u8, intervals: *i64, next_due: *i64, n: i64) -> i64 {
  // ---- RELOAD-MERGE BEFORE SAVE (2026-07-31, id 1785559048) -------------------------------------------
  // PROVEN CLOBBER, by controlled experiment not inference: a well-formed row appended to the registry via
  // the sovereign write path returned OK and read back present IMMEDIATELY -- and was GONE 75 seconds later,
  // with no error, no log and no rejection. Reproduced twice. Cause is right here: this function serialized
  // ONLY the caller's in-memory set, so the registry could contain nothing but what THIS process happened to
  // load, and every row added between our load and our save was erased by the atomic rename below.
  // WHY IT MATTERED: it silently closed what was then the only working extension point for scheduling.
  // (⚠A CLAIM HERE WAS STALE AND IS RETRACTED 2026-08-03: this comment used to assert the clockjobs-
  // plane was "retired/dead". MEASURED FALSE -- the live tickless clock merges that plane every window
  // and rows registered via `nx_store_put knowledge/store/clockjobs- put <actor> <name> <interval>
  // <organ>` demonstrably arm and fire. The plane IS the sanctioned add lane.)
  // THE REMEDY IS THE ONE sts_append_row ALREADY APPLIED TO THE SEG-STORE: re-read the file we are about to
  // overwrite and keep whatever we did not know about. Rows WE hold win outright (ours carry the advanced
  // next_due); a row we have never seen is appended verbatim, keeping its own next_due so it arms exactly
  // when its author intended instead of being silently re-armed or dropped.
  // u00e2u02dcu2026A WRITER THAT SERIALIZES ONLY ITS OWN MEMORY CANNOT COEXIST WITH ANY OTHER WRITER.
  // u00e2u02dcu2026AN EXTENSION POINT THAT SILENTLY DISCARDS EXTENSIONS IS A CLOSED SYSTEM WEARING OPEN DOCUMENTATION.
  var nn: i64 = n
  let rb: *u8 = sys_mmap(CLK_MAXJOBS*CLK_ROWW)
  let nm2: *u8 = sys_mmap(CLK_NAMEW)
  let og2: *u8 = sys_mmap(CLK_NAMEW)
  let rfd: i64 = sys_openat_rd(path)
  if rfd >= 0 {
      var rn: i64 = 0
      var rr: i64 = 1
      while rr > 0 {
          rr = sys_read(rfd, ((rb as i64) + rn) as *u8, CLK_MAXJOBS*CLK_ROWW - rn)
          if rr > 0 { rn = rn + rr }
      }
      sys_close(rfd)
      var p: i64 = 0
      var ls: i64 = 0
      while p <= rn {
          var eol: i64 = 0
          if p == rn { eol = 1 } else { if rb[p] == (10 as u8) { eol = 1 } }
          if eol == 1 {
              if p > ls {
                  var f: i64 = 0
                  var q: i64 = ls
                  var iv2: i64 = 0
                  var nd2: i64 = 0
                  var w2: i64 = 0
                  var g2: i64 = 0
                  while q < p {
                      if rb[q] == (9 as u8) { f = f + 1 } else {
                          if f == 0 { if w2 < CLK_NAMEW - 1 { nm2[w2] = rb[q]; w2 = w2 + 1 } }
                          else { if f == 1 { if rb[q] >= (48 as u8) { if rb[q] <= (57 as u8) { iv2 = iv2*10 + ((rb[q] - (48 as u8)) as i64) } } }
                          else { if f == 2 { if rb[q] >= (48 as u8) { if rb[q] <= (57 as u8) { nd2 = nd2*10 + ((rb[q] - (48 as u8)) as i64) } } }
                          else { if g2 < CLK_NAMEW - 1 { og2[g2] = rb[q]; g2 = g2 + 1 } } } }
                      }
                      q = q + 1
                  }
                  nm2[w2] = 0 as u8
                  og2[g2] = 0 as u8
                  if w2 > 0 { if g2 > 0 { if clk_find(names, nn, nm2) < 0 { if nn < CLK_MAXJOBS {
                      var d2: *u8 = clk_slot(names, nn)
                      var a2: i64 = 0
                      while a2 < w2 { d2[a2] = nm2[a2]; a2 = a2 + 1 }
                      d2[w2] = 0 as u8
                      var e2: *u8 = clk_slot(organs, nn)
                      var b2: i64 = 0
                      while b2 < g2 { e2[b2] = og2[b2]; b2 = b2 + 1 }
                      e2[g2] = 0 as u8
                      if iv2 < 1 { iv2 = 1 }
                      intervals[nn] = iv2
                      next_due[nn] = nd2
                      nn = nn + 1
                  } } } }
              }
              ls = p + 1
          }
          p = p + 1
      }
  }
  let buf: *u8 = sys_mmap(CLK_MAXJOBS*CLK_ROWW); var o: i64 = 0
  var i: i64 = 0
  while i < nn {
      let nm: *u8 = clk_slot(names, i); var k: i64=0; while nm[k]!=(0 as u8){ buf[o]=nm[k]; o=o+1; k=k+1 }
      buf[o]=9 as u8; o=o+1; o = clk_itoa(buf, o, intervals[i]); buf[o]=9 as u8; o=o+1; o = clk_itoa(buf, o, next_due[i]); buf[o]=9 as u8; o=o+1
      let og: *u8 = clk_slot(organs, i); var g: i64=0; while og[g]!=(0 as u8){ buf[o]=og[g]; o=o+1; g=g+1 }
      buf[o]=10 as u8; o=o+1
      i = i + 1
  }
  sys_mkdir("knowledge" as *u8, 0x1ed); sys_mkdir("knowledge/sched" as *u8, 0x1ed)
  let tmp: *u8 = sys_mmap(256); var t: i64=0; let pp: *u8 = path; while pp[t]!=(0 as u8){ tmp[t]=pp[t]; t=t+1 } tmp[t]=46 as u8; tmp[t+1]=116 as u8; tmp[t+2]=109 as u8; tmp[t+3]=112 as u8; tmp[t+4]=0 as u8  // path + ".tmp"
  let fd: i64 = sys_openat_wr(tmp, 0x1a4); if fd<0 { return 0 } sys_write(fd, buf, o); sys_close(fd)
  __syscall(82, tmp as i64, path as i64, 0, 0, 0, 0)   // atomic rename .tmp -> registry
  return nn
505}
506
507// ---- PLANE-NATIVE STATE PERSISTENCE (2026-08-03, debts 1784828927 + 1784868625: the operator law is
508// planes, never tsv). The mutable schedule state (name·interval·next_due·organ per row, the thing the
509// clock resumes from) lives in a seg-store plane, written once per window via sts_seed. The plane is
510// CLOCK-EXCLUSIVE by doctrine (external adds ride the separate clockjobs- ADD plane, which the clock
511// is read-only on) -- but the same reload-merge that saved the tsv from the 1785559048 clobber is kept
512// here: rows we have never seen are preserved with their own next_due, because A WRITER THAT
513// SERIALIZES ONLY ITS OWN MEMORY CANNOT COEXIST WITH ANY OTHER WRITER. --------------------------------
514
515// load schedule state from the plane; same 4-col row grammar as the legacy file. returns #jobs.
516func clk_load_plane(prefix: *u8, names: *u8, organs: *u8, intervals: *i64, next_due: *i64, np: *i64) -> i64 {
  np[0] = 0
  let data: *u8 = sys_mmap(CLK_MAXJOBS*CLK_ROWW)
  let dn: i64 = sts_load(prefix, data, CLK_MAXJOBS*CLK_ROWW)
  if dn <= 0 { return 0 }
  var i: i64=0; var ls: i64=0; var n: i64=0
  while i < dn {
      if data[i] == (10 as u8) {
          if i > ls { if n < CLK_MAXJOBS {
              let line: *u8 = ((data as i64)+ls) as *u8; let ll: i64 = i-ls
              let d: *u8 = clk_slot(names, n); let e: *u8 = clk_slot(organs, n)
              var f: i64=0; var p: i64=0; var iv: i64=0; var nd: i64=0; var w: i64=0; var g: i64=0
              while p < ll {
                  if line[p] == (9 as u8) { f = f + 1 }
                  else {
                      if f == 0 { if w < CLK_NAMEW-1 { d[w]=line[p]; w=w+1 } }
                      else { if f == 3 { if g < CLK_NAMEW-1 { e[g]=line[p]; g=g+1 } }
                      else { if line[p] >= (48 as u8) { if line[p] <= (57 as u8) {
                          let dig: i64 = (line[p]-(48 as u8)) as i64
                          if f == 1 { iv = iv*10 + dig } else { nd = nd*10 + dig }
                      } } } }
                  }
                  p = p + 1
              }
              d[w] = 0 as u8; e[g] = 0 as u8
              if w > 0 { if g > 0 {
                  intervals[n]=iv; next_due[n]=nd; n=n+1
              } }
          } }
          ls = i + 1
      }
      i = i + 1
  }
  np[0] = n
  // B-hunk (2026-08-22): this buffer is per-call and was never freed -- at CLK_ROWW=2112 that is a
  // 1,081,344 B address-space leak per window on a daemon whose life is 120 windows. Everything it
  // held was COPIED into the caller's slot arrays above, so the unmap is safe by construction.
  sys_munmap(data, CLK_MAXJOBS*CLK_ROWW)
  return n
555}
556
557// persist schedule state to the plane (reload-merge first, then ONE whole-plane sts_seed commit).
558// Rows WE hold win (ours carry the advanced next_due); unknown rows are preserved verbatim.
559func clk_save_plane(prefix: *u8, names: *u8, organs: *u8, intervals: *i64, next_due: *i64, n: i64) -> i64 {
  var nn: i64 = n
  let rnames: *u8 = sys_mmap(CLK_MAXJOBS*CLK_NAMEW)
  let rorgs: *u8 = sys_mmap(CLK_MAXJOBS*CLK_NAMEW)
  let riv: *i64 = sys_mmap(CLK_MAXJOBS*8) as *i64
  let rnd: *i64 = sys_mmap(CLK_MAXJOBS*8) as *i64
  let rnp: *i64 = sys_mmap(8) as *i64
  clk_load_plane(prefix, rnames, rorgs, riv, rnd, rnp)
  var ri: i64 = 0
  while ri < rnp[0] {
      if clk_find(names, nn, clk_slot(rnames, ri)) < 0 { if nn < CLK_MAXJOBS {
          var d2: *u8 = clk_slot(names, nn); let sm: *u8 = clk_slot(rnames, ri)
          var a2: i64 = 0
          while a2 < CLK_NAMEW-1 { if sm[a2]==(0 as u8){ d2[a2]=0 as u8; a2=CLK_NAMEW } else { d2[a2]=sm[a2]; a2=a2+1 } }
          if a2 == CLK_NAMEW-1 { d2[a2]=0 as u8 }
          var e2: *u8 = clk_slot(organs, nn); let so: *u8 = clk_slot(rorgs, ri)
          var b2: i64 = 0
          while b2 < CLK_NAMEW-1 { if so[b2]==(0 as u8){ e2[b2]=0 as u8; b2=CLK_NAMEW } else { e2[b2]=so[b2]; b2=b2+1 } }
          if b2 == CLK_NAMEW-1 { e2[b2]=0 as u8 }
          intervals[nn] = riv[ri]; next_due[nn] = rnd[ri]; nn = nn + 1
      } }
      ri = ri + 1
  }
  let buf: *u8 = sys_mmap(CLK_MAXJOBS*CLK_ROWW); var o: i64 = 0
  var i: i64 = 0
  while i < nn {
      let nm: *u8 = clk_slot(names, i); var k: i64=0; while nm[k]!=(0 as u8){ buf[o]=nm[k]; o=o+1; k=k+1 }
      buf[o]=9 as u8; o=o+1; o = clk_itoa(buf, o, intervals[i]); buf[o]=9 as u8; o=o+1; o = clk_itoa(buf, o, next_due[i]); buf[o]=9 as u8; o=o+1
      let og: *u8 = clk_slot(organs, i); var g: i64=0; while og[g]!=(0 as u8){ buf[o]=og[g]; o=o+1; g=g+1 }
      buf[o]=10 as u8; o=o+1
      i = i + 1
  }
  sts_seed(prefix, buf, o)
  // B-hunk (2026-08-22): free the per-call buffers -- at the widened CLK_NAMEW/CLK_ROWW these
  // mappings are ~3.2 MB per save (1-2 saves/window) of address space the GC-free substrate
  // otherwise leaks until the 120-window life recycle. All contents are already committed/copied.
  sys_munmap(rnames, CLK_MAXJOBS*CLK_NAMEW)
  sys_munmap(rorgs, CLK_MAXJOBS*CLK_NAMEW)
  sys_munmap(riv as *u8, CLK_MAXJOBS*8)
  sys_munmap(rnd as *u8, CLK_MAXJOBS*8)
  sys_munmap(rnp as *u8, 8)
  sys_munmap(buf, CLK_MAXJOBS*CLK_ROWW)
  return nn
602}
603
604// THE ONE STATE LOADER for the live clock: plane first; if the plane is empty AND a legacy tsv
605// exists, load it (the one-time migration path) -- the caller's next clk_save_plane completes the
606// cutover. Returns 0=loaded-from-plane, 1=migrated-from-legacy, -1=nothing anywhere.
607func clk_load_state(prefix: *u8, legacy: *u8, names: *u8, organs: *u8, intervals: *i64, next_due: *i64, np: *i64) -> i64 {
  if clk_load_plane(prefix, names, organs, intervals, next_due, np) > 0 { return 0 }
  if clk_load(legacy, names, organs, intervals, next_due, np) > 0 { return 1 }
  return 0 - 1
611}
612
613// MERGE new job declarations from an nx_store PLANE (off-tsv, additive) into the in-memory registry.
614// THE CLOBBER FIX: the clock is READ-ONLY on this plane -- external adds go via
615// `nx_store_put <plane> put <actor> <name> <interval> <organ>` (upsert-by-name, additive) and can NEVER be
616// clobbered by the clock's own (now clock-private) tsv save. Plane row cols (TAB): 0=name 1=interval(sec) 2=organ.
617// A job already present (by name) is skipped (idempotent -- re-merge is a no-op). New jobs arm at base_tick+interval.
618// Returns the number of NEW jobs added this call.
619func clk_merge_store(prefix: *u8, names: *u8, organs: *u8, intervals: *i64, next_due: *i64, np: *i64, base_tick: i64) -> i64 {
  let buf: *u8 = sys_mmap(CLK_MAXJOBS*CLK_ROWW)
  let dn: i64 = sts_load(prefix, buf, CLK_MAXJOBS*CLK_ROWW)
  if dn <= 0 { return 0 }
  // HOISTED: allocating this inside the row loop would leak a page per row (the nx_ts_lumadiff scar).
  let msg: *u8 = sys_mmap(CLK_ROWW)
  // DESIRED interval per job index, 0 = not declared this pass. mmap returns zeroed pages.
  let want: *i64 = sys_mmap(CLK_MAXJOBS*8) as *i64
  // DESIRED ORGAN per job index (2026-08-07). This reconciler recorded only the desired INTERVAL, so a
  // declaration could re-PERIOD a job but never re-TARGET it. MEASURED: I declared segguard 600s ->
  // nx_segsweep.elf and the plane came back interval=600 organ=nx_segguard.sh -- the cadence moved and the
  // command did not, which is strictly WORSE than either alone: it put the 717s shell script back on a
  // 600s period it cannot meet. Caught only because I read the organ column back instead of trusting the
  // interval that DID change.
  // (STAR)A RECONCILER THAT SYNCS ONE FIELD OF A ROW WILL SILENTLY DESYNC THE OTHERS -- AND A PARTIAL
  // RECONCILE IS MORE DANGEROUS THAN NONE, BECAUSE THE FIELD THAT MOVED PROVES IT WORKED.
  let worg: *u8 = sys_mmap(CLK_MAXJOBS*CLK_NAMEW)
  // B-hunk: ONE pair of row-scratch buffers for the whole scan (see the hoist note at `msg` above).
  let nmrow: *u8 = sys_mmap(CLK_NAMEW)
  let ogrow: *u8 = sys_mmap(CLK_NAMEW)
  var added: i64 = 0
  var reper: i64 = 0
  var i: i64=0; var ls: i64=0
  while i < dn {
      if buf[i] == (10 as u8) {
          if i > ls {
              let line: *u8 = ((buf as i64)+ls) as *u8; let ll: i64 = i-ls
              let nm: *u8 = nmrow; let og: *u8 = ogrow   // B-hunk: hoisted buffers (were per-row mmaps = a page per desired row per window; the HOISTED note at `msg` above already names the class)
              var f: i64=0; var p: i64=0; var iv: i64=0; var w: i64=0; var g: i64=0
              while p < ll {
                  if line[p]==(9 as u8) { f=f+1 }
                  else {
                      if f==0 { if w<CLK_NAMEW-1 { nm[w]=line[p]; w=w+1 } }
                      else { if f==1 { if line[p]>=(48 as u8) { if line[p]<=(57 as u8) { iv=iv*10+((line[p]-(48 as u8)) as i64) } } }
                      else { if f==2 { if g<CLK_NAMEW-1 { og[g]=line[p]; g=g+1 } } } }
                  }
                  p=p+1
              }
              nm[w]=0 as u8; og[g]=0 as u8
              // MALFORMED-ROW GUARD (2026-08-03, debt 1784604739): a row lacking a name or an organ
              // (e.g. a put that dropped an arg) must be SEEN, never silently skipped -- but never
              // registered either (a nameless job / organless exec is garbage in the dispatcher).
              if w == 0 { sts_werr("clk_merge_store: MALFORMED plane row (empty name) SKIPPED\n" as *u8) }
              if w > 0 { if g == 0 { sts_werr("clk_merge_store: MALFORMED plane row (no organ) SKIPPED\n" as *u8) } }
              if w > 0 { if g > 0 {
                  if iv < 1 { iv = 1 }
                  let n: i64 = np[0]
                  // ---- RECONCILE, NOT JUST ADD (2026-08-06) ----------------------------------------
                  // MEASURED DEFECT: this merge was ADD-ONLY -- a row whose name already existed was
                  // silently skipped -- and clocksched- (the runtime state) is rewritten by the clock
                  // every window. So there was NO SUPPORTED PATH TO RE-PERIOD OR REMOVE A CLOCK JOB:
                  // you could add one and never change it again. That is not a hypothetical. Three jobs
                  // were stuck at pathological cadences -- bootstrap-gate at 60s and worldgen-gate at
                  // 120s are GATES (test suites) running 60-360x more often than every other gate in the
                  // plane (p384kat/tls12prf 21600, uigensitegate 86400), and together with intakekeep
                  // they are 60 of the ~273 dispatches/window = 22pct of ALL demand on a clock measured
                  // at 51 completed vs 273 demanded (5.4x oversubscribed, 31 jobs STARVED per window).
                  // Whoever added them could not fix them, and the starvation was blamed on scheduling
                  // policy for days while EDF was working exactly as designed.
                  // THE FIX IS THE ESTATE'S OWN PATTERN, USED TWICE ALREADY: cron.reg -> crontab via
                  // nx_cron_reconcile, and edge443 -> iptables via nx_edge443_reconcile.sh. The declared
                  // registry is the SSOT and the runtime state is RECONCILED toward it every window.
                  // clockjobs- is now DESIRED STATE, not an append-only inbox.
                  // SAFETY: re-arm to base_tick+iv rather than leaving the old deadline, so a re-period
                  // can never fire a herd (shortening) nor strand a job past its new period (lengthening).
                  // ★A REGISTRY YOU CAN ONLY APPEND TO IS A REGISTRY THAT ACCUMULATES ITS OWN MISTAKES.
                  let ex: i64 = clk_find(names, n, nm)
                  // RECORD the intent; do not apply it here. See the apply loop after this scan.
                  if ex >= 0 { want[ex] = iv
                      var wd: *u8 = clk_slot(worg, ex); var wk: i64 = 0
                      while wk < CLK_NAMEW-1 { if og[wk]==(0 as u8){wd[wk]=0 as u8;wk=CLK_NAMEW} else {wd[wk]=og[wk];wk=wk+1} }
                      if wk == CLK_NAMEW-1 { wd[wk] = 0 as u8 }
                  }
                  if ex < 0 { if n < CLK_MAXJOBS {
                      var d: *u8=clk_slot(names,n); var k: i64=0; while k<CLK_NAMEW-1 { if nm[k]==(0 as u8){d[k]=0 as u8;k=CLK_NAMEW} else {d[k]=nm[k];k=k+1} } if k==CLK_NAMEW-1 {d[k]=0 as u8}
                      var e: *u8=clk_slot(organs,n); var j: i64=0; while j<CLK_NAMEW-1 { if og[j]==(0 as u8){e[j]=0 as u8;j=CLK_NAMEW} else {e[j]=og[j];j=j+1} } if j==CLK_NAMEW-1 {e[j]=0 as u8}
                      if iv<1 { iv=1 }
                      intervals[n]=iv; next_due[n]=base_tick+iv; np[0]=n+1; added=added+1
                  } }
              } }
          }
          ls=i+1
      }
      i=i+1
  }
  // APPLY ONCE PER JOB, AFTER EVERY ROW IS READ -- LAST DECLARATION WINS.
  // Applying inside the row loop was the first cut and it was wrong: this plane ACCUMULATES rows
  // (pubreconcile appears THREE times in it today), so a name carrying two differing declarations
  // would flip-flop -- two writes and two log lines every window, forever, converging on exactly
  // the same last-row-wins answer this loop reaches quietly. Collecting the intent and applying it
  // once is both quieter and identical in outcome.
  var wi: i64 = 0
  while wi < np[0] {
      if want[wi] > 0 { if intervals[wi] != want[wi] {
          var mo: i64 = clk_msgcat(msg, 0, "clk_merge_store: REPERIOD " as *u8)
          mo = clk_msgcat(msg, mo, clk_slot(names, wi))
          mo = clk_msgcat(msg, mo, " " as *u8)
          mo = clk_itoa(msg, mo, intervals[wi])
          mo = clk_msgcat(msg, mo, "s -> " as *u8)
          mo = clk_itoa(msg, mo, want[wi])
          mo = clk_msgcat(msg, mo, "s (declared in clockjobs-; re-armed at now+interval)\n" as *u8)
          msg[mo] = 0 as u8
          sts_werr(msg)
          intervals[wi] = want[wi]
          next_due[wi] = base_tick + want[wi]
          reper = reper + 1
      } }
      // RE-TARGET: the organ is a field of the row too, and a declaration that names a different
      // binary must MOVE the job, not just its cadence. Separate from the interval branch so a
      // pure re-target (same period, new organ) is honoured.
      if wi < np[0] { let wo: *u8 = clk_slot(worg, wi)
      if wo[0] != (0 as u8) { if clk_streq(wo, clk_slot(organs, wi)) == 0 {
          var mo2: i64 = clk_msgcat(msg, 0, "clk_merge_store: RETARGET " as *u8)
          mo2 = clk_msgcat(msg, mo2, clk_slot(names, wi))
          mo2 = clk_msgcat(msg, mo2, " -> " as *u8)
          mo2 = clk_msgcat(msg, mo2, wo)
          mo2 = clk_msgcat(msg, mo2, " (declared in clockjobs-)\n" as *u8)
          msg[mo2] = 0 as u8
          sts_werr(msg)
          var od: *u8 = clk_slot(organs, wi); var ok2: i64 = 0
          while ok2 < CLK_NAMEW-1 { if wo[ok2]==(0 as u8){od[ok2]=0 as u8;ok2=CLK_NAMEW} else {od[ok2]=wo[ok2];ok2=ok2+1} }
          if ok2 == CLK_NAMEW-1 { od[ok2] = 0 as u8 }
          reper = reper + 1
      } } }
      wi = wi + 1
  }
  // RETURN ADDS *AND* RE-PERIODS (2026-08-06). This returned only `added`, so a caller could not tell
  // that a RECONCILE had occurred -- reper was counted, logged and then dropped on the floor. The single
  // caller discarded the value entirely, so widening it is safe and makes the reconcile actionable.
  // (STAR)A COUNTER THAT IS COMPUTED, LOGGED AND NOT RETURNED IS A FACT THE CALLER CANNOT ACT ON.
  // B-hunk: free the per-call transients (buf/msg/want/worg + the hoisted row scratch); everything
  // they held was applied to the caller's arrays above.
  sys_munmap(buf, CLK_MAXJOBS*CLK_ROWW)
  sys_munmap(msg, CLK_ROWW)
  sys_munmap(want as *u8, CLK_MAXJOBS*8)
  sys_munmap(worg, CLK_MAXJOBS*CLK_NAMEW)
  sys_munmap(nmrow, CLK_NAMEW)
  sys_munmap(ogrow, CLK_NAMEW)
  return added + reper
758}
759
760// ============================================================================================
761// EDF / WALL-CLOCK SCHEDULING (2026-08-04, debt 1785872141 -- operator: "get the clock to sota")
762//
763// THE MEASURED DEFECT clk_run_tickless has BY CONSTRUCTION: its logical tick T advances ONLY by the
764// sleep amount (T = minnd), while REAL time also advances by however long the dispatched children
765// took (clk_dispatch_run forks and sys_wait4s EVERY job, serially, inside the beat). So logical time
766// drifts behind wall-clock time in proportion to dispatch load, and EVERY job's period silently
767// STRETCHES: measured 2026-08-04, evidencebeat (interval 21600 = "6 hours") fired ONCE in 21 HOURS
768// while the clock was demonstrably alive (tick current, window-end a=30 b=132). Even 60s netobs
769// slipped to 243s. The fast jobs pay the drift too, but a 6h job pays it 360x over.
770// u2605u2605u2605u2605u2605u2605 A SCHEDULER THAT ADVANCES ITS OWN CLOCK BY WHAT IT SLEPT -- NOT BY WHAT ELAPSED --
771// MEASURES ITS OWN IDLENESS AND CALLS IT TIME. Every deadline it derives is then a lie under load.
772//
773// THE SOTA SHAPE (what real schedulers do; cron/systemd-timers/EDF literature all agree):
774//   1. deadlines are ABSOLUTE WALL-CLOCK instants, never a self-advanced counter
775//   2. re-read the clock AFTER every dispatch, so job runtime cannot be lost
776//   3. dispatch EARLIEST-DEADLINE-FIRST so the most-overdue job goes first (EDF is optimal for
777//      meeting deadlines on one resource -- and it is exactly what stops slow-job starvation)
778//   4. catch-up without runaway: re-arm past now by WHOLE intervals, and REPORT missed periods
779//      instead of pretending they happened
780// The decision math is factored into PURE functions below precisely so a gate can prove a 6-hour
781// period behaves correctly in MILLISECONDS with fabricated clock values -- a scheduler you can only
782// test by waiting 6 hours is a scheduler nobody tests.
783
784// deadlines below this are LEGACY LOGICAL TICKS (the old counter ran ~3e6; epochs are ~1.78e9), so the
785// one-time migration is unambiguous and needs no flag day. NEVER compare an epoch against a tick.
786const CLK_EPOCH_FLOOR: i64 = 1000000000
787
788// PURE: index of the overdue job with the EARLIEST deadline (EDF), or -1 if nothing is due.
789// Ties break toward the lower index = stable, so a tie can never rotate two jobs into each other's slot.
790// DEMAND vs CAPACITY (2026-08-06, measured on the live plane). EDF decides WHO runs next; it can never
791// decide HOW MANY CAN RUN. If the registry asks for more dispatches per window than the window can
792// complete, then EVERY ordering starves someone and the scheduler is merely choosing the victim -- so
793// the deficit has to be a NUMBER the clock PUBLISHES, not something inferred from a late heartbeat days
794// later. MEASURED THE DAY THIS SHIPPED: 45 jobs demanded ~273 dispatches per 1800s window while the
795// window completed 51 (~35s of real child time per dispatch) = ~5.4x oversubscribed, and 273 exceeds even
796// TLN_MAXDISPATCH=240, so the set could not be served at INFINITE speed. That is why netobs (60s period)
797// was firing at 284s+ intervals with its registry row and its elf both perfectly healthy.
798// CONSERVATIVE BY CONSTRUCTION: integer division FLOORS, and any job whose period exceeds the window
799// contributes 0. So this is a LOWER BOUND on demand -- if even this floor exceeds capacity,
800// oversubscription is PROVEN, never merely suspected.
801func clk_demand_per_window(intervals: *i64, n: i64, window_secs: i64) -> i64 {
  var need: i64 = 0
  var i: i64 = 0
  while i < n {
      if intervals[i] > 0 { need = need + (window_secs / intervals[i]) }
      i = i + 1
  }
  return need
809}
810
811// PARALLEL-SAFE PICK (2026-08-06): identical to clk_edf_pick except it SKIPS jobs already IN FLIGHT.
812// THE HAZARD IT EXISTS FOR, and it is not hypothetical: a job is re-armed only AFTER its child is reaped,
813// so while a run is in progress its deadline is still in the past -- and a job whose runtime EXCEEDS its
814// period (worldgen: 289s measured against a 120s declared period) is overdue for the WHOLE of its own run.
815// Under bounded-parallel dispatch a picker without this mask would immediately dispatch a SECOND copy of
816// the exact organ already saturating the box, then a third, up to the slot cap. Two concurrent four-world
817// renders is strictly WORSE than the serial starvation parallelism was introduced to fix.
818// (STAR)PARALLELISM TURNS "ALWAYS OVERDUE" FROM A STARVATION BUG INTO A FORK BOMB -- THE BUSY MASK IS NOT
819// AN OPTIMISATION, IT IS THE CORRECTNESS CONDITION. Kept as a SEPARATE pure function so it is gate-provable
820// on fabricated inputs (T10/T11) before it is ever wired to a live dispatcher.
821func clk_edf_pick_free(deadlines: *i64, n: i64, now: i64, busy: *i64) -> i64 {
  var best: i64 = 0 - 1
  var bestd: i64 = 0
  var i: i64 = 0
  while i < n {
      if busy[i] == 0 {
          if deadlines[i] <= now {
              if best < 0 { best = i; bestd = deadlines[i] }
              else { if deadlines[i] < bestd { best = i; bestd = deadlines[i] } }
          }
      }
      i = i + 1
  }
  return best
835}
836
837func clk_edf_pick(deadlines: *i64, n: i64, now: i64) -> i64 {
  var best: i64 = 0 - 1
  var bestd: i64 = 0
  var i: i64 = 0
  while i < n {
      if deadlines[i] <= now {
          if best < 0 { best = i; bestd = deadlines[i] }
          else { if deadlines[i] < bestd { best = i; bestd = deadlines[i] } }
      }
      i = i + 1
  }
  return best
849}
850
851// PURE: soonest deadline across all jobs (what a tickless sleeper must sleep until). -1 if n==0.
852func clk_edf_next(deadlines: *i64, n: i64) -> i64 {
  if n <= 0 { return 0 - 1 }
  var m: i64 = deadlines[0]
  var i: i64 = 1
  while i < n { if deadlines[i] < m { m = deadlines[i] } i = i + 1 }
  return m
858}
859
860// PURE: how many whole periods job i has MISSED at `now` (0 = on time / early). This is the honest
861// starvation measure -- a job 3 periods late is a 3, not a "fired".
862func clk_edf_missed(deadlines: *i64, intervals: *i64, i: i64, now: i64) -> i64 {
  if deadlines[i] > now { return 0 }
  var iv: i64 = intervals[i]
  if iv < 1 { iv = 1 }
  return (now - deadlines[i]) / iv
867}
868
869// PURE: re-arm job i past `now` by WHOLE intervals (catch-up safe: never fires twice for one missed
870// window, never drifts off-phase). Returns the periods skipped so the caller can REPORT them.
871func clk_edf_rearm(deadlines: *i64, intervals: *i64, i: i64, now: i64) -> i64 {
  var iv: i64 = intervals[i]
  if iv < 1 { iv = 1 }
  var skipped: i64 = 0
  while deadlines[i] <= now { deadlines[i] = deadlines[i] + iv; skipped = skipped + 1 }
  if skipped > 0 { skipped = skipped - 1 }   // the first advance is the fire itself, not a miss
  return skipped
878}
879
880// PURE: one-time migration of legacy logical-tick deadlines to wall-clock instants. A tick value can
881// never be a valid epoch, so this is exact. Jobs arm at now+interval (their author's intent) rather
882// than firing a thundering herd at now. Returns how many rows were converted.
883func clk_edf_migrate(deadlines: *i64, intervals: *i64, n: i64, now: i64) -> i64 {
  var c: i64 = 0
  var i: i64 = 0
  while i < n {
      if deadlines[i] < CLK_EPOCH_FLOOR {
          var iv: i64 = intervals[i]
          if iv < 1 { iv = 1 }
          deadlines[i] = now + iv
          c = c + 1
      }
      i = i + 1
  }
  return c
896}
897
898// THE EDF WINDOW: wall-clock anchored, EDF-ordered, starvation-reporting. Runs until `maxdispatch`
899// jobs have been dispatched or `budget_secs` of REAL time is gone, sleeping only when nothing is due.
900// out[0]=dispatched out[1]=slept_secs out[2]=final_now out[3]=starved_jobs out[4]=max_lateness_secs
901// out[5]=exec_secs (real time inside children -- the number the old design silently threw away).
902// ---- IN-FLIGHT BEAT (2026-08-06) -------------------------------------------------------------
903// PROVEN LIVE THIS SESSION, NOT HYPOTHESISED: the clock overran its own 1800s budget by 42s and
904// stopped dispatching for 475s+ while one child held it, because clk_dispatch_one waits with NO
905// deadline (debt 1786056459). sitecheck (30s period) froze; every beat in the estate went dead.
906// THE INSTRUMENT PROBLEM THAT INCIDENT EXPOSED: max_exec, starved, and the entire window-end report
907// are written AFTER clk_run_edf RETURNS. So the one failure mode that prevents returning is exactly
908// the one the report can never describe -- during the stall the newest window-end beat was 1800s old
909// and named a completely different window.
910// (STAR)AN INSTRUMENT THAT REPORTS ONLY AT COMPLETION CANNOT REPORT WHAT PREVENTS COMPLETION.
911// This beat is written BEFORE every dispatch and overwritten AFTER it, so a hang is visible the
912// moment it starts and NAMES the organ holding the scheduler. Cost is 2 file writes per dispatch,
913// negligible beside the fork+execve it brackets.
914func clk_ifw(s: *u8, dst: *u8, o: i64) -> i64 { var x: i64=o; var i: i64=0; while s[i]!=(0 as u8){dst[x]=s[i];x=x+1;i=i+1} return x }
915func clk_ifn(dst: *u8, o: i64, v: i64) -> i64 { var x: i64=o; var mm: i64=v; if mm<0{dst[x]=45 as u8;x=x+1;mm=0-mm} if mm==0{dst[x]=48 as u8;return x+1} let t:*u8=sys_mmap(24); var k:i64=0; while mm>0{t[k]=(48+(mm%10)) as u8;mm=mm/10;k=k+1} var j:i64=0; while j<k{dst[x]=t[k-1-j];x=x+1;j=j+1} return x }
916func clk_inflight(tag: *u8, organ: *u8, a: i64, b: i64) -> i64 {
  let st: *u8 = sys_mmap(CLK_NAMEW + 128); var o: i64 = 0   // composes the ORGAN slot + <=97 fixed bytes; DERIVED from the slot (1024 was safe only by mmap page rounding once the slot widened)
  o = clk_ifw("CLOCKBEAT " as *u8, st, o); o = clk_ifw(tag, st, o)
  o = clk_ifw(" organ=" as *u8, st, o); o = clk_ifw(organ, st, o)
  o = clk_ifw(" a=" as *u8, st, o); o = clk_ifn(st, o, a)
  o = clk_ifw(" b=" as *u8, st, o); o = clk_ifn(st, o, b)
  o = clk_ifw(" t=" as *u8, st, o); o = clk_ifn(st, o, sys_now_realtime_sec())
  st[o]=10 as u8; o=o+1; st[o]=0 as u8
  let fd: i64 = sys_openat_wr("sites/nishifamily/clock_inflight.txt" as *u8, 0x1a4)
  if fd >= 0 { sys_write(fd, st, o); sys_close(fd) }
  return 0
927}
928
929func clk_run_edf(organs: *u8, names: *u8, intervals: *i64, deadlines: *i64, n: i64, maxdispatch: i64, budget_secs: i64, tick_ms: i64, out: *i64) -> i64 {
  let fired: *i64 = sys_mmap(CLK_MAXJOBS*8) as *i64
  let t0: i64 = sys_now_realtime_sec()
  var disp: i64 = 0
  var slept: i64 = 0
  var starved: i64 = 0
  var maxlate: i64 = 0
  var execs: i64 = 0
  var maxexec: i64 = 0
  var maxidx: i64 = 0 - 1
  // STARVED AXIS, NAMED (2026-08-14). Mirrors maxexec/maxidx below, which already record the worst
  // single dispatch AND which job owned it. That law was applied to the SLOW axis and never to the
  // STARVED axis, so out[3] shipped as a bare count.
  var maxmissed: i64 = 0
  var starvidx: i64 = 0 - 1
  // STORM-AWARE DISPATCH state (2026-09-02): the heavy list is read ONCE per window (sys_read_file sizes
  // from the file, cannot short-read; an absent conf -> hn=0 -> nothing is heavy), the ruler's scratch is
  // allocated ONCE, and the deferral count is published in out[10].
  var deferred: i64 = 0
  let ioa: *i64 = sys_mmap(16) as *i64
  let hlen: *i64 = sys_mmap(16) as *i64
  hlen[0] = 0
  let hconf: *u8 = sys_read_file(CLK_HEAVY_CONF, hlen)
  var hn: i64 = 0
  if (hconf as i64) != 0 { hn = hlen[0] }
  var run: i64 = 1
  while run == 1 {
      // RE-READ THE CLOCK EVERY ITERATION -- this single line is the fix: child runtime is now
      // observed, not assumed away.
      let now: i64 = sys_now_realtime_sec()
      if now - t0 >= budget_secs { run = 0 }
      if disp >= maxdispatch { run = 0 }
      if run == 1 {
          var k: i64 = clk_edf_pick(deadlines, n, now)
          // STORM-AWARE DISPATCH (2026-09-02): a HEAVY job (listed in CLK_HEAVY_CONF) that is due while the
          // shared I/O-storm ruler reports zero spawn budget is re-armed to now + clk_defer_secs(interval)
          // and NOT forked this pass; k becomes -1 so the else-branch below sleeps until the next real
          // deadline exactly as if nothing were due. Light jobs, an absent conf and an UNREADABLE ruler
          // take the pre-change path byte-for-byte. The deferral is announced on the in-flight beat with
          // b = procs_blocked, so the docroot witness names the storm that caused it.
          if k >= 0 { if clk_heavy_listed(hconf, hn, clk_slot(names, k)) == 1 {
              let bud: i64 = clk_storm_budget(ioa)
              if clk_storm_defer(1, bud) == 1 {
                  deferred = deferred + 1
                  deadlines[k] = now + clk_defer_secs(intervals[k])
                  clk_inflight("deferred-storm" as *u8, clk_slot(organs, k), ioa[1], k)
                  k = 0 - 1
              }
          } }
          if k >= 0 {
              let missed: i64 = clk_edf_missed(deadlines, intervals, k, now)
              let late: i64 = now - deadlines[k]
              if late > maxlate { maxlate = late }
              if missed > 0 {
                  starved = starved + 1
                  // NAME THE STARVER, DO NOT MERELY COUNT IT. A window reported "STARVED 3" and nothing
                  // anywhere said WHICH 3, so a job persistently losing EDF was undiagnosable.
                  // MEASURED 2026-08-14: a window published b=3 STARVED while nx_resmon's leak axis was
                  // flipping to UNOBSERVABLE off a stale memvel snapshot -- and there was no way to tell
                  // whether memvel was one of the three. A COUNT WITHOUT A WORKLIST IS NOT ACTIONABLE.
                  // Worst-offender (most periods missed) rather than a list: it needs no allocation, it
                  // matches the maxexec/maxidx idiom already proven here, and the worst starver is the
                  // one whose period is actually unschedulable.
                  if missed > maxmissed { maxmissed = missed; starvidx = k }
              }
              clk_edf_rearm(deadlines, intervals, k, now)
              let e0: i64 = now
              clk_inflight("in-flight" as *u8, clk_slot(organs, k), e0, k)
              let ran: i64 = clk_dispatch_one(organs, names, k)
              let e1: i64 = sys_now_realtime_sec()
              clk_inflight("idle" as *u8, clk_slot(organs, k), e1 - e0, k)
              // ---- COST-ADAPTIVE BACKOFF (2026-08-06) --------------------------------------
              // PROVEN LIVE, NAMED BY THE IN-FLIGHT BEAT ABOVE: nx_worldgen_gate.sov.elf holds a
              // 120s-period slot for 500s+ per run. A job whose RUNTIME EXCEEDS ITS PERIOD is always
              // overdue, so EDF correctly picks it again immediately, and on a SERIAL dispatcher with
              // no deadline that is a PERMANENT DENIAL OF SERVICE to every other job -- sitecheck (30s)
              // and netobs (60s) both froze behind it and every beat in the estate went dead.
              // (STAR)A JOB WHOSE RUNTIME EXCEEDS ITS PERIOD CANNOT BE SCHEDULED AT THAT PERIOD -- THE
              // REGISTRY IS ASSERTING A COST NOBODY EVER MEASURED. So MEASURE IT AND BELIEVE THE
              // MEASUREMENT: re-arm such a job to now + its OWN observed runtime instead of now +
              // its declared interval. It still runs, it still makes progress, but it can never again
              // starve the whole registry, and the declared interval becomes a FLOOR not a fiction.
              // Chosen over SIGKILL deliberately: killing needs a raw signal syscall inside a forking
              // scheduler, and this tree has a live trap where literal syscall numbers are rv64->x86
              // translated. This fix needs NO new syscall and cannot mis-target a pid.
              if e1 - e0 > intervals[k] { deadlines[k] = e1 + (e1 - e0) * CLK_HOGDUTY }   // dt is declared BELOW this point; use the operands already in scope
              let dt: i64 = e1 - e0
              execs = execs + dt
              // ★PUBLISH A MAX BEFORE YOU ACT ON A MEAN (2026-08-06). Aggregate exec_secs cannot separate
              // 'every child is a bit slow' from 'ONE child hung for most of the window' -- both produce the
              // same dispatch count and the same mean, and they have OPPOSITE remedies (raise capacity vs
              // kill one hog). clk_dispatch_one waits on the child with NO deadline (debt 1786056459), so the
              // hung case is not hypothetical. Record the worst SINGLE dispatch and WHICH job owned it.
              if dt > maxexec { maxexec = dt; maxidx = k }
              if ran == 1 { disp = disp + 1; fired[k] = 1 }
          } else {
              let nd: i64 = clk_edf_next(deadlines, n)
              if nd < 0 { run = 0 } else {
                  var wait: i64 = nd - now
                  if wait < 1 { wait = 1 }
                  let left: i64 = budget_secs - (now - t0)
                  if wait > left { wait = left }
                  if wait < 1 { run = 0 } else {
                      let ts: *i64 = sys_mmap(16) as *i64
                      ts[0] = wait
                      ts[1] = 0
                      __syscall(35, ts as i64, 0, 0, 0, 0, 0)
                      slept = slept + wait
                  }
              }
          }
      }
  }
  out[0] = disp; out[1] = slept; out[2] = sys_now_realtime_sec()
  out[3] = starved; out[4] = maxlate; out[5] = execs
  out[6] = maxexec; out[7] = maxidx   // worst single dispatch, and the job index that owned it
  out[8] = starvidx; out[9] = maxmissed   // WORST STARVER: job index, and how many of its periods it missed
  out[10] = deferred   // STORM-DEFERRED (2026-09-02): heavy dispatches this window declined on the shared I/O-storm ruler; the caller allocates 16 slots (128 bytes), so slot 10 is inside the mapping
  // CALLER CONTRACT: `out` must now be at least 10 i64 slots (80 bytes). nx_clock_tickless allocated
  // exactly 64 bytes = 8 slots, so writing out[8] there would have run off the end of the mapping --
  // the caller was widened in the same change. Any new caller must allocate >= 80 bytes.
  return disp
1051}
1052
1053// THE ARGV SPLIT, AS A PURE FUNCTION (2026-08-22, command-slot truncation fix). Copies the organ
1054// slot into `buf` (>= CLK_NAMEW+8 bytes), splits on single spaces IN PLACE, fills `argv`
1055// (>= 8*(CLK_ARGV_MAX+1) bytes) and returns the token count; argv[ac] is NULL. Factored out of
1056// clk_dispatch_one for the same reason the EDF math is factored into pure functions above: so a gate
1057// can prove an 18-token, 300-byte command survives the split WITHOUT a fork, and so the mutation
1058// site (CLK_NAMEW) is reachable from a tooth.
1059// OVERFLOW IS ANNOUNCED, NEVER SILENT: a command carrying more than CLK_ARGV_MAX tokens keeps the
1060// first CLK_ARGV_MAX and reports ARGV-OVERFLOW naming the job and the dropped count -- the old
1061// `if ac < 16` cap dropped every token past 15 with NO diagnostic, the same silent class as the
1062// 127-byte cut this change retires. Token-accept logic is otherwise byte-identical to the old code.
1063func clk_split_argv(raw0: *u8, buf: *u8, argv: *i64, label: *u8) -> i64 {
  var bl: i64 = 0
  var cdone: i64 = 0
  while cdone == 0 {
      if bl >= CLK_NAMEW - 1 { cdone = 1 }
      else { if raw0[bl] == (0 as u8) { cdone = 1 } else { buf[bl] = raw0[bl]; bl = bl + 1 } }
  }
  buf[bl] = 0 as u8
  argv[0] = buf as i64
  var ac: i64 = 1
  var dropped: i64 = 0
  var sp: i64 = 0
  while sp < bl {
      if buf[sp] == (32 as u8) {
          buf[sp] = 0 as u8
          if buf[sp+1] != (0 as u8) {
              if ac < CLK_ARGV_MAX { argv[ac] = ((buf as i64) + sp + 1); ac = ac + 1 } else { dropped = dropped + 1 }
          }
      }
      sp = sp + 1
  }
  argv[ac] = 0
  if dropped > 0 {
      let om: *u8 = sys_mmap(CLK_ROWW)
      var oo: i64 = clk_msgcat(om, 0, "clk_split_argv: ARGV-OVERFLOW job=" as *u8)
      oo = clk_msgcat(om, oo, label)
      oo = clk_msgcat(om, oo, " kept=" as *u8)
      oo = clk_itoa(om, oo, ac)
      oo = clk_msgcat(om, oo, " dropped=" as *u8)
      oo = clk_itoa(om, oo, dropped)
      oo = clk_msgcat(om, oo, " tail arguments NOT passed (CLK_ARGV_MAX in nx_clock_caps.nx bounds the vector; the bound is NAMED and this line is its announcement)\n" as *u8)
      om[oo] = 0 as u8
      sts_werr(om)
      sys_munmap(om, CLK_ROWW)
  }
  return ac
1099}
1100
1101// dispatch EXACTLY ONE job by index (the EDF loop picks the victim; this just runs it). Split out of
1102// clk_dispatch_run so ordering policy and exec mechanics are separable -- and so the EDF loop can
1103// re-read the clock between jobs. Returns 1 if the organ really ran, 0 if exec failed (127).
1104func clk_dispatch_one(organs: *u8, names: *u8, i: i64) -> i64 {
  // ARGV SUPPORT (2026-08-07). This built argv[0]=path, argv[1]=0 -- an organ could take NO ARGUMENTS.
  // (STAR)A DISPATCHER THAT CANNOT PASS ARGUMENTS MANUFACTURES SHELL SCRIPTS -- THE WRAPPERS ARE A
  // SYMPTOM OF THE CALLING CONVENTION, NOT OF LAZINESS.
  // The organ field is SPLIT ON SPACES into a real argv, so a row may read
  //   fallbackharden<TAB>600<TAB>nx_actlog.elf harden knowledge/status/fallback.jrnl
  // BACK-COMPATIBLE BY CONSTRUCTION: a field with no space yields argv[0] only, and the slot is
  // CLK_NAMEW = CLK_CMD_CAP (nx_clock_caps.nx, shared with the writer nx_clockjob), so a command the
  // writer admits ALWAYS fits. The split itself is clk_split_argv above -- pure, gate-provable,
  // and it announces ARGV-OVERFLOW instead of silently dropping tokens.
  let buf: *u8 = sys_mmap(CLK_NAMEW + 8)
  let argv: *i64 = sys_mmap(8*(CLK_ARGV_MAX+1)) as *i64
  clk_split_argv(clk_slot(organs, i), buf, argv, clk_slot(names, i))
  let path: *u8 = buf
  let path: *u8 = buf
  __syscall(90, path as i64, 0x1ed, 0, 0, 0, 0)   // chmod +x the EXECUTABLE only, after the split
  let pid: i64 = sys_fork()
  if pid == 0 {
      // PER-JOB OUTPUT CAPTURE (2026-08-07). The SECOND service the .sh wrappers rendered, after argv:
      // nx_fallback_harden.cron.sh appends to logs/fallback_harden.log and its own header calls that
      // "the trend IS the telemetry". Replacing a wrapper with a bare organ row would have SILENTLY
      // LOST that log -- stripping a feature (rule 25) to remove a shell script.
      // (STAR)BEFORE REPLACING A WRAPPER, ENUMERATE EVERYTHING IT PROVIDES -- THE ARGUMENT YOU NOTICED
      // IS RARELY THE ONLY SERVICE IT RENDERS.
      // Every clock organ now gets, for free, the capture each wrapper hand-rolled: stdout AND stderr
      // append to logs/<jobname>.log. Named by JOB, not organ, so two jobs sharing a binary stay
      // distinguishable (clobbertest and frontdoor both run nx_atlas_frontdoor.elf). Fail-open: if the
      // log cannot be opened the child still execs -- telemetry must never be able to stop the beat.
      // Uses the sys_dup3 redirect idiom already proven in nx_guarded_run.
      let lp: *u8 = sys_mmap(CLK_NAMEW + 16); var lo: i64 = 0   // "logs/" + NAME slot + ".log" + NUL; DERIVED from the slot
      lo = clk_msgcat(lp, lo, "logs/" as *u8)
      lo = clk_msgcat(lp, lo, clk_slot(names, i))
      lo = clk_msgcat(lp, lo, ".log" as *u8)
      lp[lo] = 0 as u8
      let ofd: i64 = sys_openat_append(lp, 0x1a4)
      if ofd >= 0 { sys_dup3(ofd, 1, 0); sys_dup3(ofd, 2, 0) }
      let envp: *i64 = sys_mmap(16) as *i64; envp[0] = "PATH=/usr/bin:/bin" as *u8 as i64; envp[1] = 0
      sys_execve(path, argv, envp)
      sys_exit(127)
  }
  let st: *i64 = sys_mmap(16) as *i64; st[0] = 0
  // BOUNDED WAIT (was a bare blocking wait4 -- the single line that let one child own the clock).
  let t0ms: i64 = sys_now_ms()
  var reaped: i64 = 0
  var timedout: i64 = 0
  while reaped == 0 {
      let w: i64 = sys_wait4(pid, st, 1)
      if w == pid { reaped = 1 }
      else { if w < 0 { reaped = 1 }
      else { if sys_now_ms() - t0ms >= CLK_DISPATCH_DEADLINE_MS { nx_kill(pid, CLK_SIGKILL); sys_wait4(pid, st, 0); reaped = 1; timedout = 1 } else { sys_sleep_ms(CLK_DISPATCH_POLL_MS) } } }
  }
  // A REAPED-ON-DEADLINE CHILD DID EXECUTE -- report it as dispatched so the duty ceiling above backs
  // it off from its OWN measured cost. Reporting 0 here would hide the hog from the very rule that tames it.
  // LIVE-PATH TELEMETRY (2026-08-07). clk_actlog was first added to clk_dispatch_run -- which is the
  // DEAD path: nx_clock_tickless calls clk_run_edf (it REPLACES clk_run_tickless), and clk_run_edf
  // dispatches through THIS function. The instrumented binary was verifiably the one running, and it
  // still logged nothing, because I had checked WHICH BINARY IS LIVE and never WHICH CODE PATH IS.
  // Logged on EVERY exit including the deadline kill, since a job that had to be killed is exactly
  // the one a reader needs to see. 124 mirrors the shell timeout convention.
  // Both rows carry the job's clock ROW NAME (2026-09-18): the organ column keeps argv[0], the name
  // rides as the last token, so a reader can tell WHICH row ran when many rows share one organ.
  if timedout == 1 { clk_actlog(path, 124, clk_slot(names, i)); return 1 }
  let raw: i64 = st[0]; let sig: i64 = raw & 0x7f; let code: i64 = (raw >> 8) & 0xff
  clk_actlog(path, code, clk_slot(names, i))
  if sig != 0 { return 1 }
  if code != 127 { return 1 }
  return 0
1171}
1172
1173// load the registry into the arrays. returns #jobs (also written to np[0]).
1174func clk_load(path: *u8, names: *u8, organs: *u8, intervals: *i64, next_due: *i64, np: *i64) -> i64 {
  np[0] = 0
  let lenp: *i64 = sys_mmap(8) as *i64
  let data: *u8 = sys_read_file(path, lenp)
  if (data as i64) == 0 { return 0 }
  let dn: i64 = lenp[0]; var i: i64=0; var ls: i64=0; var n: i64=0
  while i < dn {
      if data[i] == (10 as u8) {
          if i > ls { if n < CLK_MAXJOBS {
              let line: *u8 = ((data as i64)+ls) as *u8; let ll: i64 = i-ls
              let d: *u8 = clk_slot(names, n); let e: *u8 = clk_slot(organs, n)
              var f: i64=0; var p: i64=0; var iv: i64=0; var nd: i64=0; var w: i64=0; var g: i64=0   // f: 0=name 1=interval 2=next_due 3=organ
              while p < ll {
                  if line[p] == (9 as u8) { f = f + 1 }
                  else {
                      if f == 0 { if w < CLK_NAMEW-1 { d[w]=line[p]; w=w+1 } }
                      else { if f == 3 { if g < CLK_NAMEW-1 { e[g]=line[p]; g=g+1 } }
                      else { if line[p] >= (48 as u8) { if line[p] <= (57 as u8) {
                          let dig: i64 = (line[p]-(48 as u8)) as i64
                          if f == 1 { iv = iv*10 + dig } else { nd = nd*10 + dig }
                      } } } }
                  }
                  p = p + 1
              }
              d[w] = 0 as u8; e[g] = 0 as u8
              intervals[n]=iv; next_due[n]=nd; n=n+1
          } }
          ls = i + 1
      }
      i = i + 1
  }
  np[0] = n
  return n
1207}
nx_clock_sched.nx source

`nx_clock_sched.nx` source
