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

↩ module page · 1099 lines · 72720 B
1// nx_docportal_admin_daemon.nx -- the admin.<domain> DOCUMENT-PORTAL daemon, on the CANONICAL ecosystem auth
2// (the SAME Modern Auth nishifamily.com/status uses: OPAQUE-3DH + Argon2id + NO-COOKIE Ed25519 session). Operator
3// 2026-06-28: "match it to what we have in the nishi ecosystem and team." So this does NOT invent a token scheme --
4// it COMPOSES nx_status_daemon's proven auth (sd_* request parsing + nx_modern_auth_login + nx_sa_validate) and
5// wraps the proven nx_docportal_admin_lib router da_handle:
6//   GET  /admin            -> the no-cookie login + upload SPA shell (public)
7//   POST /admin/login      -> handle+passphrase -> nx_modern_auth_login -> 200 {"token":...} | 401
8//   *    /admin/*  (token)  -> X-Nishi-Session validates (nx_sa_validate) ? da_handle at STAFF level : 401
9// A loopback HTTP daemon the sites daemon reverse-proxies to (behind the SNI router admin.<d> row); the public
10// TLS + cert are the operator-gated deploy step. Pure router dad_handle = bytes-in/bytes-out (the gate drives it
11// in-process, no socket). license_tier: ORIGINAL
12import "nx_docportal_admin_lib.nx"
13import "nx_status_daemon.nx"
14import "hub/nx_modern_auth_flow.nx"
15import "nx_syscalls.nx"
16import "nx_invite_token.nx"   // invite-token store: inv_issue / inv_check / inv_consume
17import "nx_opaque_login.nx"   // olg_register (OPAQUE one-shot over nx_modern_auth_register)
18import "nx_proxy_route.nx"             // L2: pr_lookup_tmo, the per-read window the edge gives this host's /search row, so the heartbeat cadence is derived from the route table and never guessed
19import "nx_docportal_search_serve.nx"   // R2 dss_serve: PUBLIC sovereign seg_store-native /search (no tsv, no derived .idx)
20import "nx_tool_registry.nx"            // API-FIRST: the service self-registers nishi_search/nishi_doc at startup
21import "nx_multipart.nx"                // RFC 7578 multipart/form-data parser (real <input type=file> uploads)
22import "nx_sysload.nx"                  // host sensors (sl_ncpu / sl_loadavg_milli): the concurrency ceiling is DERIVED from the live box, never guessed
23
24// Rule 11: the accept-failure backoff is a named constant, not a number buried in the loop.
25// 50ms is short enough that a transient accept error costs nothing perceptible and long enough that
26// a PERSISTENT one cannot spin a core -- 20 retries/sec instead of millions.
27const DAD_ACCEPT_BACKOFF_MS: i64 = 50
28// Rule 11: how stale the web-shard handle may get, in seconds. The refresh reopens a 1.59GB shard
29// on any manifest change, so it must NOT run per request. 10s bounds index staleness while keeping
30// the reopen off the hot path entirely when the crawler is active.
31// RAISED 10 -> 300 (2026-08-08) after measuring the PUBLIC cost of this gate. dss_web_cache_refresh
32// closes and reopens the whole web shard (94 segments, 1.59GB) whenever the manifest signature moved,
33// and that reopen was measured at 3-8s. This daemon is no longer the loopback admin daemon its
34// comments describe: proxy_routes.conf routes PUBLIC nishifamily.com /search and /doc here, so a
35// 10s gate put a multi-second reopen in front of essentially every human-paced click -- measured
36// from a browser vantage as 0.5s to 40s on /search and /doc while the crawler was committing.
37// 300s bounds index staleness at 5 minutes (fine for a doc/search index) and cuts a browsing user's
38// exposure ~30x. HONEST LIMIT: this is a MITIGATION, not the architectural fix. The reopen still
39// lands on the request path, it just lands 30x less often. The real fix is to refresh on a
40// background beat and swap the handle in when it is ready; the rate-limit state cannot simply move
41// into the forked child because the child exits and last_refresh would never advance, making EVERY
42// request refresh -- strictly worse than today.
43const DAD_REFRESH_MIN_SEC: i64 = 300
44// CEILING ON DEFERRAL (2026-08-14). Derived from DAD_REFRESH_MIN_SEC, not guessed: three refresh
45// intervals. It bounds worst-case index staleness at 15 minutes on a daemon that never goes idle,
46// while leaving ample room for the common case (any gap with zero children in flight refreshes at the
47// normal 300s). Named for exactly ONE purpose -- the deferral ceiling -- so it can never drift into
48// doubling as anything else.
49const DAD_REFRESH_MAX_SEC: i64 = 3 * DAD_REFRESH_MIN_SEC
50const DAD_REQCAP: i64 = 65536
51const DAD_OUTCAP: i64 = 524288
52
53// ---- BOUNDED CONCURRENCY (2026-08-14) -------------------------------------------------------
54// Rule 11: the ceiling is DERIVED from the live host (ncpu - reserve - load) via the incumbent
55// sensor layer nx_sysload, not guessed. Only two policy numbers remain, each named for ONE thing.
56// DAD_CPU_RESERVE: cores deliberately left to the rest of the estate (sites.elf, gallery, crawler)
57// so serving /search can never starve the box -- the same polite-worker-budget shape nx_sysload
58// was written to feed (nx_resource_governor: "ncpu - reserve - load").
59const DAD_CPU_RESERVE: i64 = 2
60// DAD_MIN_WORKERS: the floor. 1 reproduces exactly today's behaviour, so this change can only ever
61// ADD concurrency and never remove it -- the fail-safe direction is "behave as before".
62const DAD_MIN_WORKERS: i64 = 1
63
64// Reap every child that has ALREADY exited, without blocking. Returns how many were reaped.
65// Composes the proven idiom rather than inventing a second reaper: nx_initlive_probe verifies
66// fork + wait4(WNOHANG) works on this host (verdict=GREEN) and nx_init_live supervises with it.
67func dad_reap_done(wst: *i64) -> i64 {
  var n: i64 = 0
  var go: i64 = 1
  while go == 1 {
      let r: i64 = sys_wait4(0 - 1, wst, WNOHANG)
      if r > 0 { n = n + 1 } else { go = 0 }
  }
  return n
75}
76
77// The concurrency ceiling, sensed from the REAL host through nx_sysload's reader.
78// DELIBERATELY NOT "ncpu - reserve - load". That is nx_resource_governor's POLITE BATCH budget, and
79// it is correct for background work that must yield to interactive serving. This daemon IS the
80// interactive serving path, so subtracting instantaneous load is wrong BY CONSTRUCTION: the load it
81// samples INCLUDES the traffic it exists to serve, so it throttles itself hardest exactly when
82// demand is highest. MEASURED 2026-08-14 on this box (AMD Ryzen Embedded V1500B, 4c/8t): ncpu=8,
83// loadavg~6 gave 8 - 2 - 6 = 0 -> clamped to 1 -> the ceiling silently reproduced the very serial
84// behaviour this change exists to remove, and 12 concurrent queries still completed strictly in
85// sequence (1.3s..14.1s).
86// ★A CEILING THAT SUBTRACTS THE DEMAND IT MUST ABSORB IS A SELF-DEFEATING BOUND.
87// CAPACITY is the ceiling; OVERLOAD is handled by the backpressure wait below, which is dynamic and
88// cannot deadlock. sl_ncpu() returns 1 as its safe default on read failure, so ncpu is PRINTED at
89// startup beside the cap -- an unsensed 1 must be visible as such, never mistaken for a measurement.
90func dad_worker_cap() -> i64 {
  let ncpu: i64 = sl_ncpu()
  var capw: i64 = ncpu - DAD_CPU_RESERVE
  if capw < DAD_MIN_WORKERS { capw = DAD_MIN_WORKERS }
  return capw
95}
96
97// the no-cookie admin SPA: log in -> token in sessionStorage -> upload form posts to /admin/upload with the
98// X-Nishi-Session header (NEVER a cookie). Minimal Web-API binding only (fetch/FileReader are JS-only). (public UI)
99func dad_shell(out: *u8) -> i64 {
  // Build the HTML body FIRST into a temp buffer so the header can carry Content-Length. sites.elf's BUFFERED
  // reverse proxy delimits the upstream body by Content-Length; a close-delimited response (no length) makes the
  // proxy hop fail (-4) even though the daemon serves a direct client fine. Mirrors the JSON paths + the mgmt API.
  let body: *u8 = sys_mmap(DAD_OUTCAP)
  var b: i64 = 0
  b = sd_cat(body, b, "<!DOCTYPE html><meta charset=utf-8><meta name=viewport content=\"width=device-width,initial-scale=1\"><title>Nishi document portal</title>" as *u8)
  b = sd_cat(body, b, "<style>body{font-family:-apple-system,Segoe UI,sans-serif;max-width:720px;margin:6vh auto;padding:0 20px;color:#1c1c1e}input,select{width:100%;padding:9px;margin:.4rem 0;box-sizing:border-box;border:1px solid #ccc;border-radius:7px}button{padding:10px 18px;border:0;border-radius:7px;background:#0a6;color:#fff;font-size:1rem}.row{display:flex;gap:14px}.row label{font-size:.9rem}.e{color:#b00;min-height:1.2em}</style>" as *u8)
  // NISHI-FIRST (2026-07-05 doctrine): the login is a REAL <form> -- native POST works with ZERO JS
  // (nishi browser / any no-JS client); the JS below upgrades it to the SPA flow for third-party
  // browsers (the last-mile shim). Hidden ui=1 rides ONLY the native submit -> server answers HTML.
  b = sd_cat(body, b, "<div id=login><h2>&#128274; Nishi document portal</h2><form id=lf method=post action=/admin/login><input type=hidden name=ui value=1><input id=h name=handle placeholder=\"handle\" autocomplete=username autofocus><input id=p name=passphrase type=password placeholder=\"passphrase\" autocomplete=current-password><button type=submit id=b>Sign in</button></form><p id=e class=e></p></div>" as *u8)
  b = sd_cat(body, b, "<div id=up hidden><h2>Upload a document</h2><input id=dom placeholder=\"domain (e.g. andelinwest.com)\"><input id=f type=file>" as *u8)
  b = sd_cat(body, b, "<div class=row><label><input type=radio name=vis value=public checked> Public (visitor-facing)</label><label><input type=radio name=vis value=private> Private (client vault)</label></div>" as *u8)
  b = sd_cat(body, b, "<div class=row><label><input type=checkbox id=ps checked> List in onsite search</label><label><input type=checkbox id=ab> Allow AI to publish blog posts</label></div>" as *u8)
  b = sd_cat(body, b, "<button id=u>Upload</button><p id=r class=e></p></div>" as *u8)
  b = sd_cat(body, b, "<script>var L=document.getElementById('login'),U=document.getElementById('up'),E=document.getElementById('e');" as *u8)
  b = sd_cat(body, b, "document.getElementById('lf').onsubmit=function(){E.textContent='';var b='handle='+encodeURIComponent(h.value)+'&passphrase='+encodeURIComponent(p.value);fetch('/admin/login',{method:'POST',headers:{'Content-Type':'application/x-www-form-urlencoded'},body:b}).then(function(r){if(r.ok){return r.json()}throw 0}).then(function(j){sessionStorage.nx_sess=j.token;L.hidden=true;U.hidden=false}).catch(function(){E.textContent='Wrong handle or passphrase.'});return false};" as *u8)
  b = sd_cat(body, b, "document.getElementById('u').onclick=function(){var R=document.getElementById('r');R.textContent='';var fr=new FileReader();fr.onload=function(){var vis=document.querySelector('input[name=vis]:checked').value;var q='/admin/upload?domain='+encodeURIComponent(dom.value)+'&visibility='+vis+'&pub_search='+(document.getElementById('ps').checked?1:0)+'&ai_blog='+(document.getElementById('ab').checked?1:0);fetch(q,{method:'POST',headers:{'X-Nishi-Session':sessionStorage.nx_sess||''},body:fr.result}).then(function(r){return r.text()}).then(function(t){R.style.color='#0a6';R.textContent=t}).catch(function(){R.textContent='Upload failed.'})};fr.readAsText(document.getElementById('f').files[0])};</script>" as *u8)
  var o: i64 = 0
  o = sd_cat(out, o, "HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nConnection: close\r\nContent-Length: " as *u8)
  o = sd_catn(out, o, b)
  o = sd_cat(out, o, "\r\n\r\n" as *u8)
  var i: i64 = 0
  while i < b { out[o] = body[i]; o = o + 1; i = i + 1 }
  return o
125}
126
127// Per-domain invite-token store path = "<storefile>.invites" (storefile = argv[3], carried on
128// ctx.account_store). Each realm/domain has its OWN storefile, so its invite tokens are isolated
129// by construction (per-domain isolation). DERIVED (not a new argv slot) => the daemon argv contract
130// <port> <keysfile> <storefile> <realm> <budget> stays unchanged (backward-compatible).
131func dad_invite_path(ctx: *NxAuthContext, out: *u8) -> i64 {
  let sp: *u8 = ctx.account_store as *u8
  var i: i64 = 0
  while sp[i] != (0 as u8) { out[i] = sp[i]; i = i + 1 }
  let suf: *u8 = ".invites" as *u8
  var j: i64 = 0
  while suf[j] != (0 as u8) { out[i] = suf[j]; i = i + 1; j = j + 1 }
  out[i] = 0 as u8
  return i
140}
141
142// ==== NISHI-FIRST no-JS session plumbing (2026-07-05 doctrine: nishi os/browser first; JS = the
143// third-party last-mile shim). The no-cookie C1 cardinal is PRESERVED: no Set-Cookie ever -- the no-JS
144// path carries the Ed25519 session token in the ?s= query of same-portal links (short-TTL, realm-scoped,
145// SAME validator). The query-session helpers now live in the SHARED nx_site_auth (nx_sa_validate_qs /
146// nx_sa_qs_raw / nx_sa_tok_urlenc) so mail/siteedit/every surface inherit them -- DRY, one auth home. ====
147
148// the no-JS signed-in LANDING page (HTML answer to a form login): links carry the session in ?s=.
149func dad_landing(out: *u8, b64: *u8, b64n: i64) -> i64 {
  let body: *u8 = sys_mmap(DAD_OUTCAP)
  var b: i64 = 0
  b = sd_cat(body, b, "<!DOCTYPE html><meta charset=utf-8><title>Signed in</title><body style=\"font-family:sans-serif;max-width:720px;margin:6vh auto\"><h2>Signed in</h2><p>No-JS session active (nishi-first). Continue to:</p><p><a href=\"/admin/ui?s=" as *u8)
  b = nx_sa_tok_urlenc(b64, b64n, body, b)
  b = sd_cat(body, b, "\">the document portal</a></p>" as *u8)
  var o: i64 = 0
  o = sd_cat(out, o, "HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nConnection: close\r\nContent-Length: " as *u8)
  o = sd_catn(out, o, b)
  o = sd_cat(out, o, "\r\n\r\n" as *u8)
  var i: i64 = 0
  while i < b { out[o] = body[i]; o = o + 1; i = i + 1 }
  return o
162}
163
164// the no-JS admin UI: shows the authenticated handle + a paste-text upload FORM (multipart file
165// pickers are the next rung; textarea covers the nishi browser + any no-JS client TODAY).
166// ---- session-uid -> handle map (the no-cookie session carries the 32-byte uid HASH, not the plaintext
167// handle; without this the authed page shows binary hash bytes in "Signed in as"). Mirrors the mail portal's
168// .mailmap: login/register append "MAP <64hex-uid> <handle>\n" to "<storefile>.uidmap" (append-only, rule 13),
169// /admin/ui resolves hash->handle. Same OPAQUE realm -> the docportal now shows the handle like the mail portal.
170func dad_hex32(src: *u8, out: *u8) -> i64 {
  let hx: *u8 = "0123456789abcdef" as *u8
  var i: i64 = 0
  while i < 32 { out[i * 2] = hx[((src[i] as i64) >> 4) & 15]; out[i * 2 + 1] = hx[(src[i] as i64) & 15]; i = i + 1 }
  out[64] = 0 as u8
  return 64
176}
177func dad_uidmap_path(ctx: *NxAuthContext, out: *u8) -> i64 {
  let sp: *u8 = ctx.account_store as *u8
  var i: i64 = 0
  while sp[i] != (0 as u8) { out[i] = sp[i]; i = i + 1 }
  let suf: *u8 = ".uidmap" as *u8
  var j: i64 = 0
  while suf[j] != (0 as u8) { out[i] = suf[j]; i = i + 1; j = j + 1 }
  out[i] = 0 as u8
  return i
186}
187func dad_map_put(path: *u8, hexuid: *u8, h: *u8, hn: i64) -> i64 {
  let row: *u8 = sys_mmap(256)
  var o: i64 = sd_cat(row, 0, "MAP " as *u8)
  var i: i64 = 0
  while i < 64 { row[o] = hexuid[i]; o = o + 1; i = i + 1 }
  row[o] = 32 as u8; o = o + 1
  i = 0
  while i < hn { row[o] = h[i]; o = o + 1; i = i + 1 }
  row[o] = 10 as u8; o = o + 1
  let fd: i64 = sys_openat_append(path, 0x1a4)
  if fd < 0 { return 0 - 1 }
  sys_write(fd, row, o)
  sys_close(fd)
  return 0
201}
202func dad_map_get(path: *u8, hexuid: *u8, out: *u8, cap: i64) -> i64 {
  let szp: *i64 = sys_mmap(16) as *i64
  szp[0] = 0
  let b: *u8 = sys_read_file(path, szp)
  if (b as i64) == 0 { sys_munmap(szp as *u8, 16); return 0 }
  let n: i64 = szp[0]
  var best: i64 = 0
  var cur: i64 = 0
  while cur < n {
      var le: i64 = cur
      while le < n && (b[le] as i64) != 10 { le = le + 1 }
      if le - cur > 69 {
          if (b[cur] as i64) == 77 {
              var m: i64 = 1
              var k: i64 = 0
              while k < 64 { if b[cur + 4 + k] != hexuid[k] { m = 0; k = 64 } else { k = k + 1 } }
              if m == 1 {
                  var w: i64 = 0
                  var s: i64 = cur + 69
                  while s < le { if w < cap - 1 { out[w] = b[s]; w = w + 1 } s = s + 1 }
                  out[w] = 0 as u8
                  best = w
              }
          }
      }
      cur = le + 1
  }
  // FREE the buffer sys_read_file mmap'd (cap 4 GiB + 16) -- it is NEVER freed by sys_read_file (the caller owns
  // it), so this per-request map lookup was leaking the whole (append-only, growing) map file resident every call
  // = the measured 27 GB docportal RSS (the F-class sys_read_file pattern). munmap bounds it to zero residual.
  sys_munmap(b, 4294967312)
  sys_munmap(szp as *u8, 16)
  return best
235}
236
237func dad_ui_page(out: *u8, handle: *u8, hn: i64, sraw: *u8, sn: i64) -> i64 {
  let body: *u8 = sys_mmap(DAD_OUTCAP)
  var b: i64 = 0
  b = sd_cat(body, b, "<!DOCTYPE html><meta charset=utf-8><title>Nishi document portal</title><body style=\"font-family:sans-serif;max-width:720px;margin:6vh auto\"><h2>Document portal</h2><p>Signed in as <b>" as *u8)
  var i: i64 = 0
  while i < hn { body[b] = handle[i]; b = b + 1; i = i + 1 }
  b = sd_cat(body, b, "</b> (no-JS mode)</p><form method=post action=\"/admin/uploadtext?s=" as *u8)
  i = 0
  while i < sn { body[b] = sraw[i]; b = b + 1; i = i + 1 }
  b = sd_cat(body, b, "\"><p><input name=domain value=\"andelinwest.com\" style=\"width:100%;padding:8px\"></p><p><select name=visibility><option value=public>Public (visitor-facing)</option><option value=private>Private (client vault)</option></select> <label><input type=checkbox name=pub_search value=1 checked> List in onsite search</label> <label><input type=checkbox name=ai_blog value=1> Allow AI blog</label></p><p><textarea name=text rows=12 style=\"width:100%\" placeholder=\"paste the document text here\"></textarea></p><button type=submit>Upload text</button></form>" as *u8)
  // REAL file upload (multipart/form-data): a standard <input type=file>. Any file, binary-safe.
  b = sd_cat(body, b, "<hr><h3>Or upload a file</h3><form enctype=multipart/form-data method=post action=\"/admin/uploadfile?s=" as *u8)
  i = 0
  while i < sn { body[b] = sraw[i]; b = b + 1; i = i + 1 }
  b = sd_cat(body, b, "\"><p><input name=domain value=\"andelinwest.com\" style=\"width:100%;padding:8px\"></p><p><select name=visibility><option value=public>Public (visitor-facing)</option><option value=private>Private (client vault)</option></select> <label><input type=checkbox name=pub_search value=1 checked> List in onsite search</label></p><p><input type=file name=file></p><button type=submit>Upload file</button></form>" as *u8)
  var o: i64 = 0
  o = sd_cat(out, o, "HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nConnection: close\r\nContent-Length: " as *u8)
  o = sd_catn(out, o, b)
  o = sd_cat(out, o, "\r\n\r\n" as *u8)
  i = 0
  while i < b { out[o] = body[i]; o = o + 1; i = i + 1 }
  return o
259}
260
261// no-JS upload shim: form-urlencoded fields (domain/visibility/pub_search/ai_blog/text) -> the
262// CANONICAL /admin/upload request (query params on the request line + raw text body) -> da_handle.
263// One storage path, two front doors (rule 15/19: same engine, no contract fork).
264func dad_uploadtext(ctx: *NxAuthContext, req: *u8, req_n: i64, subject: *u8, out: *u8) -> i64 {
  let body_off: i64 = sd_body_off(req, req_n)
  let body: *u8 = ((req as i64) + body_off) as *u8
  let body_n: i64 = req_n - body_off
  let f_off: *i64 = sys_mmap(8) as *i64
  let f_len: *i64 = sys_mmap(8) as *i64
  // domain
  let domb: *u8 = sys_mmap(256)
  var dom_n: i64 = 0
  if sd_form_field(body, body_n, "domain" as *u8, 6, f_off, f_len) == 1 {
      dom_n = sd_urldecode(((body as i64) + f_off[0]) as *u8, f_len[0], domb, 255)
  }
  if dom_n < 1 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 14\r\n\r\nmissing domain" as *u8) }
  // visibility (default public)
  let visb: *u8 = sys_mmap(64)
  var vis_n: i64 = 0
  if sd_form_field(body, body_n, "visibility" as *u8, 10, f_off, f_len) == 1 {
      vis_n = sd_urldecode(((body as i64) + f_off[0]) as *u8, f_len[0], visb, 63)
  }
  if vis_n < 1 { visb[0] = 112 as u8; visb[1] = 117 as u8; visb[2] = 98 as u8; visb[3] = 108 as u8; visb[4] = 105 as u8; visb[5] = 99 as u8; vis_n = 6 }
  // checkboxes: present -> 1, absent -> 0
  var ps: i64 = 0
  if sd_form_field(body, body_n, "pub_search" as *u8, 10, f_off, f_len) == 1 { ps = 1 }
  var ab: i64 = 0
  if sd_form_field(body, body_n, "ai_blog" as *u8, 7, f_off, f_len) == 1 { ab = 1 }
  // the document text
  if sd_form_field(body, body_n, "text" as *u8, 4, f_off, f_len) != 1 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 12\r\n\r\nmissing text" as *u8) }
  let txt: *u8 = sys_mmap(DAD_REQCAP)
  let txt_n: i64 = sd_urldecode(((body as i64) + f_off[0]) as *u8, f_len[0], txt, DAD_REQCAP - 1)
  if txt_n < 1 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 10\r\n\r\nempty text" as *u8) }
  // synthesize the canonical upload request
  let syn: *u8 = sys_mmap(DAD_REQCAP + 4096)
  var s: i64 = 0
  s = sd_cat(syn, s, "POST /admin/upload?domain=" as *u8)
  var i: i64 = 0
  while i < dom_n { syn[s] = domb[i]; s = s + 1; i = i + 1 }
  s = sd_cat(syn, s, "&visibility=" as *u8)
  i = 0
  while i < vis_n { syn[s] = visb[i]; s = s + 1; i = i + 1 }
  s = sd_cat(syn, s, "&pub_search=" as *u8)
  if ps == 1 { syn[s] = 49 as u8 } else { syn[s] = 48 as u8 }
  s = s + 1
  s = sd_cat(syn, s, "&ai_blog=" as *u8)
  if ab == 1 { syn[s] = 49 as u8 } else { syn[s] = 48 as u8 }
  s = s + 1
  s = sd_cat(syn, s, " HTTP/1.1\r\n\r\n" as *u8)
  i = 0
  while i < txt_n { syn[s] = txt[i]; s = s + 1; i = i + 1 }
  let dctx: *DaCtx = sys_mmap(16) as *DaCtx
  dctx.user_level = 2
  dctx.subject = subject
  return da_handle(dctx, syn, s, out)
316}
317
318// ===== REAL multipart/form-data FILE upload (standards-correct: what an <input type=file> submits; binary-
319// safe, any file type). Composes the shipped nx_multipart parser + feeds the extracted file bytes into the
320// SAME da_handle /admin/upload store path the paste-text shim uses (one storage engine, three front doors). =====
321
322// extract the boundary token from the request's Content-Type header. returns length (0 if none).
323func dad_ct_boundary(req: *u8, req_n: i64, out: *u8) -> i64 {
  let off: *i64 = sys_mmap(8) as *i64
  let ln: *i64 = sys_mmap(8) as *i64
  if nx_http_header_find(req, req_n, "Content-Type" as *u8, 12, off, ln) != NXHF_FOUND { return 0 }
  let v: *u8 = ((req as i64) + off[0]) as *u8
  let vn: i64 = ln[0]
  let key: *u8 = "boundary=" as *u8
  var bstart: i64 = 0 - 1
  var i: i64 = 0
  while i + 9 <= vn {
      var m: i64 = 1
      var j: i64 = 0
      while j < 9 { if (v[i+j] as i64) != (key[j] as i64) { m = 0; j = 9 } else { j = j + 1 } }
      if m == 1 { bstart = i + 9; i = vn } else { i = i + 1 }
  }
  if bstart < 0 { return 0 }
  var w: i64 = 0
  var k: i64 = bstart
  while k < vn { let c: i64 = v[k] as i64; if c == 59 { k = vn } else { if c != 34 { out[w] = c as u8; w = w + 1 } k = k + 1 } }
  out[w] = 0 as u8
  return w
344}
345
346// extract a `key` value (e.g. name=" or filename=") from a part's header block body[hoff..hoff+hlen).
347// returns value length (0 if absent). key includes the trailing quote char it opens on.
348func dad_cd_extract(body: *u8, hoff: i64, hlen: i64, key: *u8, out: *u8) -> i64 {
  var kl: i64 = 0
  while key[kl] != (0 as u8) { kl = kl + 1 }
  let end: i64 = hoff + hlen
  var start: i64 = 0 - 1
  var i: i64 = hoff
  while i + kl <= end {
      var m: i64 = 1
      var j: i64 = 0
      while j < kl { if (body[i+j] as i64) != (key[j] as i64) { m = 0; j = kl } else { j = j + 1 } }
      if m == 1 { start = i + kl; i = end } else { i = i + 1 }
  }
  if start < 0 { return 0 }
  var w: i64 = 0
  var k: i64 = start
  while k < end { if (body[k] as i64) == 34 { k = end } else { out[w] = body[k]; w = w + 1; k = k + 1 } }
  out[w] = 0 as u8
  return w
366}
367
368const DAD_MAXPARTS: i64 = 16
369
370// parse the multipart body -> pull the `file` part bytes + the domain/visibility/pub_search/ai_blog text
371// parts -> synthesize the canonical /admin/upload request -> da_handle (STAFF). Returns response length.
372func dad_uploadfile(ctx: *NxAuthContext, req: *u8, req_n: i64, subject: *u8, out: *u8) -> i64 {
  let boundary: *u8 = sys_mmap(256)
  let blen: i64 = dad_ct_boundary(req, req_n, boundary)
  if blen <= 0 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 21\r\n\r\nno multipart boundary" as *u8) }
  let body_off: i64 = sd_body_off(req, req_n)
  let body: *u8 = ((req as i64) + body_off) as *u8
  let body_n: i64 = req_n - body_off
  let parts: *MultipartPart = sys_mmap(32 * DAD_MAXPARTS) as *MultipartPart
  let np: i64 = multipart_parse(body, body_n, boundary, blen, parts, DAD_MAXPARTS)
  if np <= 0 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 19\r\n\r\nmalformed multipart" as *u8) }
  let domb: *u8 = sys_mmap(256); var dom_n: i64 = 0
  let visb: *u8 = sys_mmap(64); var vis_n: i64 = 0
  var ps: i64 = 0
  var ab: i64 = 0
  var file_off: i64 = 0 - 1
  var file_len: i64 = 0
  let nmb: *u8 = sys_mmap(128)
  var i: i64 = 0
  while i < np {
      let p: *MultipartPart = ((parts as i64) + i * 32) as *MultipartPart
      let nm_n: i64 = dad_cd_extract(body, p.headers_off, p.headers_len, "name=\"" as *u8, nmb)
      if nm_n == 4 { if sd_starts(nmb, 4, "file" as *u8) == 1 { file_off = p.body_off; file_len = p.body_len } }
      if nm_n == 6 { if sd_starts(nmb, 6, "domain" as *u8) == 1 { var w: i64 = 0; while w < p.body_len { domb[w] = body[p.body_off + w]; w = w + 1 } domb[p.body_len] = 0 as u8; dom_n = p.body_len } }
      if nm_n == 10 { if sd_starts(nmb, 10, "visibility" as *u8) == 1 { var w2: i64 = 0; while w2 < p.body_len { visb[w2] = body[p.body_off + w2]; w2 = w2 + 1 } visb[p.body_len] = 0 as u8; vis_n = p.body_len } }
      if nm_n == 10 { if sd_starts(nmb, 10, "pub_search" as *u8) == 1 { ps = 1 } }
      if nm_n == 7 { if sd_starts(nmb, 7, "ai_blog" as *u8) == 1 { ab = 1 } }
      i = i + 1
  }
  if file_len <= 0 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 18\r\n\r\nno file part found" as *u8) }
  if dom_n <= 0 { return sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: text/plain\r\nConnection: close\r\nContent-Length: 14\r\n\r\nmissing domain" as *u8) }
  if vis_n <= 0 { visb[0] = 112 as u8; visb[1] = 117 as u8; visb[2] = 98 as u8; visb[3] = 108 as u8; visb[4] = 105 as u8; visb[5] = 99 as u8; vis_n = 6 }
  // synthesize the canonical /admin/upload request (query metadata + raw file body) -> the SAME store path
  let syn: *u8 = sys_mmap(body_n + 4096)
  var s: i64 = sd_cat(syn, 0, "POST /admin/upload?domain=" as *u8)
  var q: i64 = 0
  while q < dom_n { syn[s] = domb[q]; s = s + 1; q = q + 1 }
  s = sd_cat(syn, s, "&visibility=" as *u8)
  q = 0
  while q < vis_n { syn[s] = visb[q]; s = s + 1; q = q + 1 }
  s = sd_cat(syn, s, "&pub_search=" as *u8)
  if ps == 1 { syn[s] = 49 as u8 } else { syn[s] = 48 as u8 }
  s = s + 1
  s = sd_cat(syn, s, "&ai_blog=" as *u8)
  if ab == 1 { syn[s] = 49 as u8 } else { syn[s] = 48 as u8 }
  s = s + 1
  s = sd_cat(syn, s, " HTTP/1.1\r\n\r\n" as *u8)
  var f: i64 = 0
  while f < file_len { syn[s] = body[file_off + f]; s = s + 1; f = f + 1 }
  let dctx: *DaCtx = sys_mmap(16) as *DaCtx
  dctx.user_level = 2
  dctx.subject = subject
  return da_handle(dctx, syn, s, out)
424}
425
426// ---- L2 EARLY BYTES (search rung L2, 2026-09-14). The SERP's status line, headers and page shell go out BEFORE the
427// search runs, framed chunked because the length is unknown at that moment, and the socket's owner keeps the edge's
428// per-read window alive with heartbeat chunks while a GRANDCHILD computes the rest of the page into a per-request file.
429// ONE writer per socket by construction (this child); the search process never touches the wire. The heartbeat cadence
430// is DERIVED from proxy_routes.conf's timeout= for this host's /search row (a third of it, so two beats may be lost
431// before the edge gives up); a route with no token gets the edge's default window. A slow query is a slow page, never
432// a 503. dss_serve, the Content-Length page the 49-tooth gate drives, is untouched.
433const DAD_EDGE_READ_TMO_S: i64 = 15      // sites.elf NX_SD2_BACKEND_TIMEOUT_S: the per-read window a route gets when proxy_routes.conf carries no timeout= token
434const DAD_HB_DIV: i64 = 3                // heartbeats at a third of the window
435const DAD_HB_POLL_MS: i64 = 200          // how often the writer asks whether the search process has finished
436const DAD_WNOHANG: i64 = 1               // wait4 flag: poll, never block -- the writer must keep breathing
437const DAD_MS_PER_S: i64 = 1000
438const DAD_BODY_MODE: i64 = 420           // 0644: the grandchild's per-request body file
439static dad_routes_g: *u8
440static dad_routes_n: i64
441func dad_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
442// is this request the HTML SERP (the only route that streams)?
443func dad_is_search(req: *u8, req_n: i64) -> i64 {
  let poff: *i64 = sys_mmap(8) as *i64
  let plen: *i64 = sys_mmap(8) as *i64
  poff[0] = 0
  plen[0] = 0
  sd_find_path(req, req_n, poff, plen)
  let path: *u8 = ((req as i64) + poff[0]) as *u8
  return sd_starts(path, plen[0], "/search" as *u8)
451}
452// heartbeat cadence in ms for this host's /search route: the route's per-read window over DAD_HB_DIV
453func dad_hb_ms(host: *u8) -> i64 {
  if (dad_routes_g as i64) == 0 {
      let nb: *i64 = sys_mmap(16) as *i64
      dad_routes_g = sys_read_file("proxy_routes.conf" as *u8, nb)
      if (dad_routes_g as i64) == 0 { dad_routes_n = 0 } else { dad_routes_n = nb[0] }
  }
  var tmo: i64 = 0
  if dad_routes_n > 0 {
      let port: *i64 = sys_mmap(8) as *i64
      let mode: *i64 = sys_mmap(8) as *i64
      let t: *i64 = sys_mmap(8) as *i64
      t[0] = 0
      pr_lookup_tmo(dad_routes_g, dad_routes_n, host, dad_slen(host), "/search" as *u8, 7, port, mode, t)
      tmo = t[0]
  }
  if tmo <= 0 { tmo = DAD_EDGE_READ_TMO_S }
  return tmo * DAD_MS_PER_S / DAD_HB_DIV
470}
471// L2b GUARD (2026-09-15): early bytes reach a client ONLY through a route the front door STREAMS. The buffered
472// branch of sites.elf reads the backend to EOF before it answers, so a chunked heartbeat stream behind a
473// `buffered` row is a stall for the whole per-read window -- measured: every hourly search journey FAIL at
474// ~15.5 s from epoch 1789418137, the first beat after the E4 rebuild re-shipped the streaming dispatch that L2
475// had rolled back by binary only. The route table is the ONE authority on how the front door forwards, so this
476// reads the SAME row dad_hb_ms reads and streams iff it says `stream`; no row, no table, or any other mode
477// answers whole (the proven Content-Length path). Data-driven: flipping the row to `stream` (hot-reloaded by
478// sites.elf) turns streaming on with no rebuild -- once L2b lands there. The pure form takes the table so the
479// gate can drive both directions without a proxy_routes.conf in its CWD.
480func dad_early_ok_tab(routes: *u8, rn: i64, host: *u8) -> i64 {
  if rn <= 0 { return 0 }
  if (routes as i64) == 0 { return 0 }
  let sp: *u8 = "/search" as *u8
  let port: *i64 = sys_mmap(8) as *i64
  let mode: *i64 = sys_mmap(8) as *i64
  let t: *i64 = sys_mmap(8) as *i64
  port[0] = 0
  mode[0] = PR_MODE_BUFFERED
  t[0] = 0
  pr_lookup_tmo(routes, rn, host, dad_slen(host), sp, dad_slen(sp), port, mode, t)
  if mode[0] == PR_MODE_STREAM { return 1 }
  return 0
493}
494func dad_early_ok(req: *u8, req_n: i64) -> i64 {
  let host: *u8 = sys_mmap(256)
  dsv_host(req, req_n, host, 255)
  if (dad_routes_g as i64) == 0 {
      let nb: *i64 = sys_mmap(16) as *i64
      dad_routes_g = sys_read_file("proxy_routes.conf" as *u8, nb)
      if (dad_routes_g as i64) == 0 { dad_routes_n = 0 } else { dad_routes_n = nb[0] }
  }
  return dad_early_ok_tab(dad_routes_g, dad_routes_n, host)
503}
504func dad_serve_early(cfd: i64, req: *u8, req_n: i64, out: *u8) -> i64 {
  let hostbuf: *u8 = sys_mmap(256)
  dsv_host(req, req_n, hostbuf, 255)
  let t0: i64 = dsv_now_us()
  let q: *u8 = sys_mmap(DSV_MAGIC_1024)
  let effdom: *u8 = sys_mmap(256)
  let box: *i64 = sys_mmap(32) as *i64
  let qn: i64 = dsv_serp_parse(hostbuf, req, req_n, q, effdom, box)
  let body: *u8 = sys_mmap(DSV_BODYCAP)
  let b1: i64 = dsv_serp_prelude(body, q, qn, box[1])
  let o1: i64 = dsv_respond_early(out, body, b1)
  sys_write(cfd, out, o1)   // THE EARLY BYTES: status line, headers and the page shell, before the search runs
  let slow: i64 = dss_serve_slow_ms(req, req_n, "knowledge/search_probe_slow.conf" as *u8)
  // the rest of the page is computed by a grandchild into a per-request file; this process keeps the wire alive
  let path: *u8 = sys_mmap(128)
  var po: i64 = dsv_cat(path, 0, "/tmp/nx_serp_" as *u8)
  po = dsv_catn(path, po, t0)
  po = dsv_cat(path, po, ".body" as *u8)
  let tmp: *u8 = sys_mmap(128)
  var to: i64 = dsv_cat(tmp, 0, path)
  to = dsv_cat(tmp, to, ".tmp" as *u8)
  let kid: i64 = sys_fork()
  if kid == 0 {
      if slow > 0 { sys_sleep_ms(slow) }
      let b2: i64 = dsv_serp_rest(effdom, q, qn, box[1], box[2], body, b1, t0)
      let fd: i64 = sys_openat_wr(tmp, DAD_BODY_MODE)
      if fd >= 0 { sys_write(fd, (body as i64 + b1) as *u8, b2 - b1); sys_close(fd); sys_renameat(tmp, path) }
      sys_exit(0)
  }
  let hb: i64 = dad_hb_ms(hostbuf)
  let hbbuf: *u8 = sys_mmap(64)
  let hbn: i64 = dsv_chunk(hbbuf, 0, "<!-- -->" as *u8, 0, 8)
  let wst: *i64 = sys_mmap(16) as *i64
  var waited: i64 = 0
  var done: i64 = 0
  if kid < 0 { done = 1 }
  while done == 0 {
      let r: i64 = sys_wait4(kid, wst, DAD_WNOHANG)
      if r == kid { done = 1 } else { if r < 0 { done = 1 } else {
          sys_sleep_ms(DAD_HB_POLL_MS)
          waited = waited + DAD_HB_POLL_MS
          if waited >= hb { sys_write(cfd, hbbuf, hbn); waited = 0 }
      } }
  }
  let nb2: *i64 = sys_mmap(16) as *i64
  let rest: *u8 = sys_read_file(path, nb2)
  var o2: i64 = 0
  if (rest as i64) != 0 { o2 = dsv_chunk(out, 0, rest, 0, nb2[0]); sys_unlinkat(path) }
  else { let fail: *u8 = "<p class=meta>search failed to answer; try again</p></main></body></html>" as *u8; o2 = dsv_chunk(out, 0, fail, 0, dad_slen(fail)) }
  o2 = dsv_chunk_end(out, o2)
  sys_write(cfd, out, o2)
  return 0
556}
557
558// ---- THE ROUTER: request bytes -> response bytes (no socket). The gate drives this directly. ----
559func dad_handle(ctx: *NxAuthContext, req: *u8, req_n: i64, out: *u8) -> i64 {
  let poff: *i64 = sys_mmap(8) as *i64; let plen: *i64 = sys_mmap(8) as *i64
  poff[0] = 0; plen[0] = 0
  sd_find_path(req, req_n, poff, plen)
  let path: *u8 = ((req as i64) + poff[0]) as *u8
  let pn: i64 = plen[0]
  let is_post: i64 = (req[0] == 80 as u8) as i64
  var o: i64 = 0
  // PUBLIC sovereign onsite /search (no auth, seg_store-native, NO tsv) -- matched FIRST, before the /admin chain.
  // Domain from the Host header -> dss_serve queries dp-<Host>-pub- (this daemon fronts andelinwest.com).
  if sd_starts(path, pn, "/search" as *u8) == 1 {
      let hostbuf: *u8 = sys_mmap(256)
      dsv_host(req, req_n, hostbuf, 255)
      return dss_serve(hostbuf, req, req_n, out)
  }
  // PUBLIC /doc?cid=<cid> document view (the search loop's click-through; -pub- shard only). Boundary-guarded:
  // exactly "/doc" or "/doc?..." -- a raw prefix would also swallow /doctor-style paths (path includes the query).
  if sd_starts(path, pn, "/doc" as *u8) == 1 {
      var docb: i64 = 0
      if pn == 4 { docb = 1 }
      if pn > 4 { if path[4] == (63 as u8) { docb = 1 } }
      if docb == 1 {
          let hostbuf2: *u8 = sys_mmap(256)
          dsv_host(req, req_n, hostbuf2, 255)
          return dsv_doc_serve(hostbuf2, req, req_n, out)
      }
  }
  // API-FIRST surface: versioned public JSON (CORS, structured errors). Same engine, machine contract --
  // the HTML SERP above is just one client of it. Boundary-guarded like /doc.
  if sd_starts(path, pn, "/api/search" as *u8) == 1 {
      var apib: i64 = 0
      if pn == 11 { apib = 1 }
      if pn > 11 { if path[11] == (63 as u8) { apib = 1 } }
      if apib == 1 {
          let hostbuf3: *u8 = sys_mmap(256)
          dsv_host(req, req_n, hostbuf3, 255)
          return dss_api_search(hostbuf3, req, req_n, out)
      }
  }
  if sd_starts(path, pn, "/api/doc" as *u8) == 1 {
      var apid: i64 = 0
      if pn == 8 { apid = 1 }
      if pn > 8 { if path[8] == (63 as u8) { apid = 1 } }
      if apid == 1 {
          let hostbuf4: *u8 = sys_mmap(256)
          dsv_host(req, req_n, hostbuf4, 255)
          return dss_api_doc(hostbuf4, req, req_n, out)
      }
  }
  if sd_starts(path, pn, "/api/suggest" as *u8) == 1 {
      var apis: i64 = 0
      if pn == 12 { apis = 1 }
      if pn > 12 { if path[12] == (63 as u8) { apis = 1 } }
      if apis == 1 {
          let hostbuf5: *u8 = sys_mmap(256)
          dsv_host(req, req_n, hostbuf5, 255)
          return dss_api_suggest(hostbuf5, req, req_n, out)
      }
  }
  // machine-readable OpenAPI 3.1 contract (enterprise: client codegen / Swagger / contract testing).
  // Exact "/api/openapi.json" or with a query string.
  if sd_starts(path, pn, "/api/openapi.json" as *u8) == 1 {
      var apio: i64 = 0
      if pn == 17 { apio = 1 }
      if pn > 17 { if path[17] == (63 as u8) { apio = 1 } }
      if apio == 1 {
          let hostbuf6: *u8 = sys_mmap(256)
          dsv_host(req, req_n, hostbuf6, 255)
          return dss_api_openapi(hostbuf6, out)
      }
  }
  if sd_starts(path, pn, "/admin/register" as *u8) == 1 {
      // INVITE-GATED OPAQUE self-registration: a remote firm presents a SECRET single-use, expiring
      // invite token (minted out-of-band by inv_issue) instead of a guessable handle. Matched BEFORE
      // the "/admin/" session gate (which is a prefix of this path) and as a sibling of /admin/login.
      // Gate shape mirrors nx_lan_signup_routes.lsd_route POST /register -- swapping its LAN-IP gate
      // for the inv_check token gate. On success: olg_register (OPAQUE) -> inv_consume -> 200 mnemonic.
      if is_post == 1 {
          let body_off: i64 = sd_body_off(req, req_n)
          let body: *u8 = ((req as i64) + body_off) as *u8
          let body_n: i64 = req_n - body_off
          let hoff: *i64 = sys_mmap(8) as *i64; let hn: *i64 = sys_mmap(8) as *i64
          let poff2: *i64 = sys_mmap(8) as *i64; let pnn: *i64 = sys_mmap(8) as *i64
          let ioff: *i64 = sys_mmap(8) as *i64; let inn: *i64 = sys_mmap(8) as *i64
          var got: i64 = 0
          if sd_form_field(body, body_n, "handle" as *u8, 6, hoff, hn) == 1 {
              if sd_form_field(body, body_n, "pw" as *u8, 2, poff2, pnn) == 1 {
                  if sd_form_field(body, body_n, "invite" as *u8, 6, ioff, inn) == 1 { got = 1 }
              }
          }
          var done: i64 = 0
          if got == 1 {
              let hbuf: *u8 = sys_mmap(256); let pbuf: *u8 = sys_mmap(512); let ibuf: *u8 = sys_mmap(128)
              let h_dec: i64 = sd_urldecode(((body as i64) + hoff[0]) as *u8, hn[0], hbuf, 255)
              let p_dec: i64 = sd_urldecode(((body as i64) + poff2[0]) as *u8, pnn[0], pbuf, 511)
              let i_dec: i64 = sd_urldecode(((body as i64) + ioff[0]) as *u8, inn[0], ibuf, 127)
              if h_dec > 0 { if p_dec > 0 { if i_dec > 0 {
                  let invpath: *u8 = sys_mmap(512)
                  dad_invite_path(ctx, invpath)
                  let now_s: i64 = sys_now_realtime_sec()
                  // THE GATE: token must be a live, realm-scoped, unconsumed invite (level > 0).
                  let lvl: i64 = inv_check(invpath, ibuf, i_dec, ctx.realm_id, ctx.realm_id_n, now_s)
                  if lvl <= 0 {
                      o = sd_cat(out, 0, "HTTP/1.1 403 Forbidden\r\nContent-Type: application/json\r\nConnection: close\r\nContent-Length: 37\r\n\r\n{\"error\":\"invalid or expired invite\"}" as *u8)
                      done = 1
                  } else {
                      let mn: *u8 = sys_mmap(512); let mnn: *i64 = sys_mmap(16) as *i64
                      if olg_register(ctx, hbuf, h_dec, pbuf, p_dec, mn, 512, mnn) == NX_MAUTH_OK {
                          // uidmap: record uid-hash -> handle at register so /admin/ui greets by name
                          let uidh2: *u8 = sys_mmap(32)
                          if nx_ncs_derive_user_id_hash(ctx.realm_id, ctx.realm_id_n, hbuf, h_dec, uidh2) == NX_NCS_OK {
                              let uhex2: *u8 = sys_mmap(72); dad_hex32(uidh2, uhex2)
                              let ump2: *u8 = sys_mmap(512); dad_uidmap_path(ctx, ump2)
                              dad_map_put(ump2, uhex2, hbuf, h_dec)
                          }
                          inv_consume(invpath, ibuf, i_dec, now_s)   // single-use: burn the invite
                          o = sd_cat(out, 0, "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nConnection: close\r\nContent-Length: " as *u8)
                          o = sd_catn(out, o, 15 + mnn[0])
                          o = sd_cat(out, o, "\r\n\r\n{\"mnemonic\":\"" as *u8)
                          var z: i64 = 0; while z < mnn[0] { out[o] = mn[z]; o = o + 1; z = z + 1 }
                          o = sd_cat(out, o, "\"}" as *u8)
                          done = 1
                      } else {
                          o = sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: application/json\r\nConnection: close\r\nContent-Length: 27\r\n\r\n{\"error\":\"register failed\"}" as *u8)
                          done = 1
                      }
                  }
              } } }
          }
          if done == 0 { o = sd_cat(out, 0, "HTTP/1.1 400 Bad Request\r\nContent-Type: application/json\r\nConnection: close\r\nContent-Length: 27\r\n\r\n{\"error\":\"register failed\"}" as *u8) }
      } else { o = dad_shell(out) }
  } else { if sd_starts(path, pn, "/admin/login" as *u8) == 1 {
      if is_post == 1 {
          let body_off: i64 = sd_body_off(req, req_n)
          let body: *u8 = ((req as i64) + body_off) as *u8
          let body_n: i64 = req_n - body_off
          let hoff: *i64 = sys_mmap(8) as *i64; let hn: *i64 = sys_mmap(8) as *i64
          let poff2: *i64 = sys_mmap(8) as *i64; let pnn: *i64 = sys_mmap(8) as *i64
          var got: i64 = 0
          if sd_form_field(body, body_n, "handle" as *u8, 6, hoff, hn) == 1 {
              if sd_form_field(body, body_n, "passphrase" as *u8, 10, poff2, pnn) == 1 { got = 1 }
          }
          // ui=1 rides ONLY the native <form> submit (nishi-first no-JS path) -> answer HTML, not JSON.
          var uiflag: i64 = 0
          let uoff: *i64 = sys_mmap(8) as *i64
          let un: *i64 = sys_mmap(8) as *i64
          if sd_form_field(body, body_n, "ui" as *u8, 2, uoff, un) == 1 { uiflag = 1 }
          var ok: i64 = 0
          if got == 1 {
              let hbuf: *u8 = sys_mmap(256); let pbuf: *u8 = sys_mmap(512)
              let h_dec: i64 = sd_urldecode(((body as i64) + hoff[0]) as *u8, hn[0], hbuf, 255)
              let p_dec: i64 = sd_urldecode(((body as i64) + poff2[0]) as *u8, pnn[0], pbuf, 511)
              if h_dec > 0 { if p_dec > 0 {
                  let tok: *u8 = sys_mmap(NX_MAUTH_SESSION_TOKEN_BYTES)
                  let tok_n: *i64 = sys_mmap(8) as *i64; tok_n[0] = 0
                  if nx_modern_auth_login(ctx, hbuf, h_dec, pbuf, p_dec, tok, NX_MAUTH_SESSION_TOKEN_BYTES, tok_n) == NX_MAUTH_OK {
                      // uidmap: the session token carries the uid HASH -> record hash->handle so /admin/ui greets by name
                      let uidh: *u8 = sys_mmap(32)
                      if nx_ncs_derive_user_id_hash(ctx.realm_id, ctx.realm_id_n, hbuf, h_dec, uidh) == NX_NCS_OK {
                          let uhex: *u8 = sys_mmap(72); dad_hex32(uidh, uhex)
                          let ump: *u8 = sys_mmap(512); dad_uidmap_path(ctx, ump)
                          dad_map_put(ump, uhex, hbuf, h_dec)
                      }
                      let b64: *u8 = sys_mmap(256); let b64_n: i64 = b64_encode(tok, NX_MAUTH_SESSION_TOKEN_BYTES, b64)
                      if uiflag == 1 { o = dad_landing(out, b64, b64_n) }
                      else {
                          o = sd_cat(out, o, "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nConnection: close\r\nContent-Length: " as *u8)
                          o = sd_catn(out, o, 12 + b64_n)
                          o = sd_cat(out, o, "\r\n\r\n{\"token\":\"" as *u8)
                          var z: i64 = 0; while z < b64_n { out[o] = b64[z]; o = o + 1; z = z + 1 }
                          o = sd_cat(out, o, "\"}" as *u8)
                      }
                      ok = 1
                  }
              } }
          }
          if ok == 0 {
              if uiflag == 1 { o = sd_cat(out, 0, "HTTP/1.1 401 Unauthorized\r\nContent-Type: text/html; charset=utf-8\r\nConnection: close\r\nContent-Length: 106\r\n\r\n<!DOCTYPE html><meta charset=utf-8><p>Wrong handle or passphrase.</p><p><a href=\"/admin\">Try again</a></p>" as *u8) }
              else { o = sd_emit_401_json(out) }
          }
      } else { o = dad_shell(out) }
  } else { if sd_starts(path, pn, "/admin/ui" as *u8) == 1 {
      // NISHI-FIRST no-JS admin page: session from the ?s= query (same Ed25519 validator) -> the
      // handle-greeting + paste-upload form. Renders + navigates in the nishi browser TODAY.
      let hb: *u8 = sys_mmap(256)
      let hbn: *i64 = sys_mmap(8) as *i64
      let now_ui: i64 = sys_now_realtime_sec()
      if nx_sa_validate_qs(ctx, path, pn, now_ui, hb, 255, hbn) == NX_MAUTH_OK {
          let voff: *i64 = sys_mmap(8) as *i64
          let vlen: i64 = nx_sa_qs_raw(path, pn, voff)
          let sp: *u8 = ((path as i64) + voff[0]) as *u8
          // resolve the session uid HASH -> plaintext handle (else "Signed in as" shows raw hash bytes)
          var disp_h: *u8 = hb
          var disp_n: i64 = hbn[0]
          if hbn[0] == 32 {
              let uhex: *u8 = sys_mmap(72); dad_hex32(hb, uhex)
              let ump: *u8 = sys_mmap(512); dad_uidmap_path(ctx, ump)
              let rhb: *u8 = sys_mmap(128)
              let rhn: i64 = dad_map_get(ump, uhex, rhb, 127)
              if rhn > 0 { disp_h = rhb; disp_n = rhn }
          }
          o = dad_ui_page(out, disp_h, disp_n, sp, vlen)
      } else { o = sd_emit_401_json(out) }
  } else { if sd_starts(path, pn, "/admin/uploadtext" as *u8) == 1 {
      // NISHI-FIRST no-JS upload: auth via ?s= OR the header, then the form->canonical-request shim.
      let now_ut: i64 = sys_now_realtime_sec()
      let hb2: *u8 = sys_mmap(256)
      let hn2: *i64 = sys_mmap(8) as *i64
      hn2[0] = 0
      var authed: i64 = 0
      if nx_sa_validate_qs(ctx, path, pn, now_ut, hb2, 255, hn2) == NX_MAUTH_OK { authed = 1 }
      if authed == 0 { if nx_sa_validate_handle(ctx, req, req_n, now_ut, hb2, 255, hn2) == NX_MAUTH_OK { authed = 1 } }
      if authed == 1 {
          let subhex2: *u8 = sys_mmap(72); subhex2[0] = 0 as u8
          if hn2[0] == 32 { dad_hex32(hb2, subhex2) }
          if is_post == 1 { o = dad_uploadtext(ctx, req, req_n, subhex2, out) }
          else { o = sd_emit_401_json(out) }
      } else { o = sd_emit_401_json(out) }
  } else { if sd_starts(path, pn, "/admin/uploadfile" as *u8) == 1 {
      // REAL multipart/form-data file upload (what an <input type=file> submits): auth via ?s= OR header,
      // then dad_uploadfile parses the parts + feeds the file bytes into the SAME /admin/upload store path.
      let now_uf: i64 = sys_now_realtime_sec()
      let hb3: *u8 = sys_mmap(256)
      let hn3: *i64 = sys_mmap(8) as *i64
      hn3[0] = 0
      var authed_f: i64 = 0
      if nx_sa_validate_qs(ctx, path, pn, now_uf, hb3, 255, hn3) == NX_MAUTH_OK { authed_f = 1 }
      if authed_f == 0 { if nx_sa_validate_handle(ctx, req, req_n, now_uf, hb3, 255, hn3) == NX_MAUTH_OK { authed_f = 1 } }
      if authed_f == 1 {
          let subhex3: *u8 = sys_mmap(72); subhex3[0] = 0 as u8
          if hn3[0] == 32 { dad_hex32(hb3, subhex3) }
          if is_post == 1 { o = dad_uploadfile(ctx, req, req_n, subhex3, out) }
          else { o = sd_emit_401_json(out) }
      } else { o = sd_emit_401_json(out) }
  } else { if sd_starts(path, pn, "/admin/" as *u8) == 1 {
      // session-gated: the /admin/<action> paths (upload/policy/whoami) validate the no-cookie token, then route
      // to da_handle at STAFF level (admin.<d> = the management capability). Unauthenticated -> 401 BEFORE
      // da_handle ever runs (deny-by-default, two layers). Bare /admin falls through to the public login shell.
      let now_s: i64 = sys_now_realtime_sec()
      // P2: emit the session SUBJECT via nx_sa_validate_handle (verified to accept EXACTLY the same sessions as
      // nx_sa_validate -- same sig/MAC + TTL + realm check, computed before + independent of the subject copy).
      // The non-null hb/hbn + hb-cap>=32 are REQUIRED (else deny / null-deref). Same ?s= buffer pattern used above.
      let hb: *u8 = sys_mmap(256)
      let hbn: *i64 = sys_mmap(8) as *i64
      hbn[0] = 0
      if nx_sa_validate_handle(ctx, req, req_n, now_s, hb, 255, hbn) == NX_MAUTH_OK {
          let dctx: *DaCtx = sys_mmap(16) as *DaCtx
          dctx.user_level = 2
          let subhex: *u8 = sys_mmap(72); subhex[0] = 0 as u8
          if hbn[0] == 32 { dad_hex32(hb, subhex) }
          dctx.subject = subhex
          o = da_handle(dctx, req, req_n, out)
      } else { o = sd_emit_401_json(out) }
  } else { o = dad_shell(out) } } } } } }
  return o
814}
815
816func main(argc: i64, argv: *i64) -> i64 {
  if argc < 6 { sys_write(2, "usage: nx_docportal_admin_daemon <port> <keysfile> <storefile> <realm> <budget>\n" as *u8, 79); return 1 }
  let port: i64 = sd_atoi(argv[1] as *u8)
  let keysfile: *u8 = argv[2] as *u8
  let storefile: *u8 = argv[3] as *u8
  let realm: *u8 = argv[4] as *u8
  let budget: i64 = sd_atoi(argv[5] as *u8)
  let realm_n: i64 = sd_len(realm)
824
  // fail-fast: arm the realm context at startup (Rule 20), exactly like nx_status_daemon
  let oprf_seed: *u8 = sys_mmap(32); let akp: *u8 = sys_mmap(32); let akb: *u8 = sys_mmap(33)
  let edp: *u8 = sys_mmap(32); let edb: *u8 = sys_mmap(32)
  sys_write(1, "DBG start: args parsed\n" as *u8, 23)
  if nx_uas_server_keys_load_or_init(keysfile, oprf_seed, akp, akb, edp, edb) != NX_UAS_OK { sys_write(2, "FATAL: server-key bundle\n" as *u8, 24); return 2 }
  sys_write(1, "DBG: server-keys OK\n" as *u8, 20)
  let ctx: *NxAuthContext = sys_mmap(256) as *NxAuthContext
  if nx_auth_context_init(ctx, realm, realm_n, realm, realm_n, storefile as i64, oprf_seed, edp, edb, 900, 8192, 1, 1, 5, 1) != NX_MAUTH_OK { sys_write(2, "FATAL: context init\n" as *u8, 20); return 3 }
  sys_write(1, "DBG: context init OK\n" as *u8, 21)
834
  // API-FIRST: announce the search API in the ecosystem tool registry (idempotent check-first; the NAS
  // CWD is nishihost/, so this writes the LIVE knowledge/toolreg- shard -> /api/tools + MCP tools/list
  // discover nishi_search with zero adapter -- the "services register at their own startup" pattern).
  let trp: *i64 = sys_mmap(16) as *i64
  let trl: *i64 = sys_mmap(16) as *i64
  if tool_get("nishi_search" as *u8, trp, trl) != 1 {
      tool_register("nishi_search" as *u8, "Sovereign nishi search: a domain's docs + site pages, the nishi library (Host nishifamily.com), and the crawled open web (scope=web). Versioned JSON, CORS, structured errors." as *u8, "GET /api/search?q=<terms>[&scope=web] (per-domain via Host)" as *u8, "GREEN" as *u8)
  }
  if tool_get("nishi_doc" as *u8, trp, trl) != 1 {
      tool_register("nishi_doc" as *u8, "Fetch a public document by content id from the nishi search corpus (JSON; text bounded + truncation-flagged)." as *u8, "GET /api/doc?cid=<cid>[&scope=web]" as *u8, "GREEN" as *u8)
  }
846
  let addr: *u8 = sys_mmap(16)
  if nx_http_server_addr_loopback(addr, port) != 16 { sys_write(2, "FATAL: addr_loopback != 16\n" as *u8, 27); return 4 }
  sys_write(1, "DBG: addr_loopback OK\n" as *u8, 22)
  // ⚠LISTEN FIRST IS DELIBERATE -- I TRIED THE OPPOSITE AND MEASURED IT WORSE. DO NOT "FIX" THIS.
  // The cold-start story, fully measured 2026-08-15: this parent spends ~8-12 s pre-warming a 1.59GB
  // web shard. With listen() FIRST that cost is ABSORBED BY THE ACCEPT QUEUE -- connections wait in the
  // 64-deep backlog and the first request completes in ~8.1 s, with NO failures. Moving the pre-warm
  // above listen() closes the port for the whole warm-up instead, and the edge turns ECONNREFUSED into
  // a user-visible 503: MEASURED 503 for 12.09 s, then 200 in 1.11 s. That trades one slow success for
  // twelve seconds of hard failure, which is strictly worse for a visitor and is the exact symptom this
  // daemon was reported for. Reverted.
  // ★★★★★★A FAST FAILURE IS NOT AUTOMATICALLY BETTER THAN A SLOW SUCCESS -- THAT DEPENDS ENTIRELY ON
  // WHETHER THE CALLER CAN DO ANYTHING WITH THE FAILURE. Here it cannot: the visitor sees 503.
  // WHAT WAS GENUINELY WRONG WAS THE MEASUREMENT, NOT THE ORDER. Queue time is invisible to EVERY
  // timer this daemon has -- the parent's starts at accept(), the child's after fork() -- so the daemon
  // honestly reported <=1405 ms per request while curl measured 8144 ms end to end, and I attributed
  // that gap in turn to the search engine, the did-you-mean walk, and the edge proxy before finding it
  // here. ★★★★★A LATENCY NOBODY'S CLOCK STARTS FOR IS BLAMED ON WHOEVER IS MEASURED LAST.
  // The remedy is therefore to make the cost VISIBLE (the warm_ms line below) and eventually CHEAPER --
  // never to hide it behind a closed port.
  // ★ORDER DECIDED BY MATCHED MEASUREMENT, NOT BY ARGUMENT (2026-08-15). Both orders were built,
  // deployed and probed from t=0 with the IDENTICAL protocol (300ms poll, count non-200s, record the
  // first 200 and its duration):
  //     pre-warm BEFORE listen -> first 200 at t=12.09s, that request 1.11s
  //     listen BEFORE pre-warm -> first 200 at t=20.4s,  that request 10.70s
  // Pre-warm-first wins on BOTH axes, so it is what ships. I briefly reverted it after calling it
  // "worse", which was WRONG: I had compared its t=0 probe against a listen-first number taken after a
  // 30s sleep, i.e. against an already-warm daemon. ★★★★★★A COMPARISON BETWEEN TWO CONFIGURATIONS IS
  // ONLY A COMPARISON IF BOTH WERE MEASURED IN THE SAME STATE -- otherwise you are timing the sleep.
  // WHY listen-first is worse despite producing no ECONNREFUSED: the port opens instantly but the
  // parent is then busy warming for ~9.8s, so arriving connections sit in the 64-deep backlog and are
  // served LATE -- one measured at 10.70s, which burns most of the edge's 15s NX_SD2_BACKEND_TIMEOUT_S.
  // Refusing fast during startup is the honest signal: the daemon is not ready, the caller learns in
  // microseconds, and readiness arrives sooner overall.
  // THE REAL FIX IS NEITHER ORDER -- IT IS THE 9.8s ITSELF. STARTUP warm_ms=9796 and, on the refresh
  // path, REQ done parent_us=9783316: the same ~9.8s ss_open2 of the 1.59GB web shard, once at startup
  // and again on whichever accept triggers a refresh (blocking the single-threaded parent, which is why
  // it presents as a RUN of slow requests rather than one). Until that open is incremental, this order
  // is the best available placement of an unavoidable cost, not a solution to it.
  // SERVE-SCALE: pre-warm the web-shard handle in the PARENT so every forked child inherits it COW --
  // per-request ss_open on the bulk-CC shard measured ~0.7s/query without this. Refreshed per accept
  // below (stat-signature check, ~free; reopen only when new segments actually ship).
  let t_warm: i64 = dsv_now_us()
  if dss_web_cache_refresh() == 1 { sys_write(1, "web shard handle pre-warmed\n" as *u8, 28) }
  // Arm the shared query memo HERE -- in the parent, before any fork. sys_mmap_shared's own contract
  // says "allocate in the PARENT before fork", and this daemon forks per request, so a memo armed
  // anywhere else would be COW-private to one child and invisible to every other request.
  if dsq_init() == 1 { sys_write(1, "query memo armed (shared, fixed-capacity)\n" as *u8, 42) }
  // ANNOUNCE THE COLD-START COST. Every request queued behind this warm-up pays it, and no per-request
  // timer can see that, so without this line the number is unobtainable from the daemon's own log --
  // which is precisely how it stayed unexplained. Print it once, at the only place that knows it.
  let wb: *u8 = sys_mmap(96)
  var wn: i64 = dsv_cat(wb, 0, "STARTUP warm_ms=" as *u8)
  wn = dsv_catn(wb, wn, (dsv_now_us() - t_warm) / 1000)
  wn = dsv_cat(wb, wn, " -- the port is opened AFTER this, so nothing queued behind it\n" as *u8)
  sys_write(1, wb, wn)
903
  // ONLY NOW open the port: every resource a request needs is resident and shared, so the backlog can
  // no longer hide a cold-start cost, and the first accepted connection is served at warm speed.
  let lv: *i64 = sys_mmap(8) as *i64
  let lfd: i64 = nx_http_server_listen(addr, 64, lv)
  if lfd < 0 { sys_write(2, "FATAL: listen failed (port busy or denied)\n" as *u8, 43); return 4 }
  sys_write(1, "nx_docportal_admin_daemon listening loopback (READY: warm before listen)\n" as *u8, 73)
910
  let req: *u8 = sys_mmap(DAD_REQCAP)
  let out: *u8 = sys_mmap(DAD_OUTCAP)
  let av: *i64 = sys_mmap(8) as *i64       // HOISTED out of the loop -- reused each accept (was leaking a page/iter)
  let wst: *i64 = sys_mmap(16) as *i64     // HOISTED -- child reap status, reused
  // Seeded from the pre-warm above, not from zero: the shard was JUST opened, so the first
  // request must not immediately reopen it. Without this seed the gate would let exactly one
  // full 1.59GB reopen through on the very first query after every restart -- the slowest
  // possible moment, right when the daemon is already cold.
  var last_refresh: i64 = sys_now_realtime_sec()
  var served: i64 = 0
  // Sensed ONCE, in the parent, then held. Re-sensing per accept would read a load average this
  // daemon is itself creating and ratchet its own ceiling down toward 1 under exactly the load it
  // exists to absorb. PRINT THE VALUE: a ceiling nobody can see is a ceiling nobody can debug.
  let dad_cap: i64 = dad_worker_cap()
  var dad_live: i64 = 0
  let capbuf: *u8 = sys_mmap(96)
  var cbn: i64 = 0
  cbn = dsv_cat(capbuf, cbn, "worker cap=" as *u8)
  cbn = dsv_catn(capbuf, cbn, dad_cap)
  cbn = dsv_cat(capbuf, cbn, " ncpu=" as *u8)
  cbn = dsv_catn(capbuf, cbn, sl_ncpu())
  cbn = dsv_cat(capbuf, cbn, " reserve=" as *u8)
  cbn = dsv_catn(capbuf, cbn, DAD_CPU_RESERVE)
  cbn = dsv_cat(capbuf, cbn, " (capacity bound; load deliberately NOT subtracted)\n" as *u8)
  sys_write(1, capbuf, cbn)
  // HOISTED per-request diagnostic buffer -- reused every iteration, never mmap'd inside the loop
  // (the per-call-allocation law this file has already had to learn twice).
  let logbuf: *u8 = sys_mmap(128)
  while served < budget {
      let cfd: i64 = nx_http_server_accept_one(lfd, av)
      if cfd < 0 {
          // ACCEPT BACKOFF (2026-08-01). This branch retried INSTANTLY, so any persistent accept
          // error became a 100pct-CPU busy loop while the socket stayed LISTENING -- which every
          // port-probe health check reads as a healthy daemon. 50ms costs nothing on the happy
          // path (this branch is not taken when accepts succeed) and turns a spin into a
          // survivable retry. It also stops a failing daemon from eating its 20M `served` budget
          // in minutes.
          sys_sleep_ms(DAD_ACCEPT_BACKOFF_MS)
          served = served + 1
      }
      if cfd >= 0 {
          // PER-REQUEST TRACE (2026-08-01). This daemon emitted NOTHING after `pre-warmed`, so when
          // it wedged there was no way to tell which stage died: accept, refresh, fork, or handle.
          // I spent an hour narrowing it from the outside with CPU counters and fd counts and still
          // could not say. Three cheap writes make the next occurrence self-diagnosing.
          // â˜…â˜…â˜…â˜…â˜…A DAEMON THAT LOGS ONLY ITS STARTUP CAN ONLY EVER TELL YOU IT STARTED.
          sys_write(1, "REQ accepted\n" as *u8, 13)
          // ROOT-CAUSE FIX (2026-08-01), found by the trace two lines above.
          // The wedge was HERE: the log read accepted=52, refresh-ok=51, done=51 -- the daemon
          // accepted a request and never returned from dss_web_cache_refresh(). That call compares
          // a manifest signature and, on ANY change, does ss_close + ss_open2 over the whole web
          // shard: 94 segments, 1.59GB. It ran ON EVERY ACCEPTED REQUEST.
          // WHY IT ONLY BIT NOW: the manifest used to be frozen because the crawler was committing
          // nothing (the segments=0 poisoned-segid bug I root-fixed earlier tonight). With the
          // crawler working the shard grows again -- 87 segments at session start, 94 now -- so the
          // cached handle is invalidated constantly and a full reopen lands on the request path.
          // â˜…â˜…â˜…â˜…â˜…A CORRECT FIX IN ONE ORGAN CAN EXPOSE A LATENT O(N) COST IN ANOTHER.
          // THE GATE: at most one refresh per DAD_REFRESH_MIN_SEC. Freshness is bounded by that
          // interval instead of by request arrival, so a growing shard can no longer put a
          // 1.59GB reopen in front of every query. Serving a few seconds of slightly stale index
          // is strictly better than not serving at all.
          // Reap FIRST so the in-flight count below is current, not left over from a child that has
          // already exited. WNOHANG, so this costs nothing on the happy path.
          // WHY THESE TWO NUMBERS ARE LOGGED (2026-08-15): the refresh gate below fires only on
          // `dad_live == 0`, and the log proved that predicate routinely unreachable -- ~30 consecutive
          // refresh-defer lines before one refresh-ok, exactly spanning a window where every web request
          // measured 9.39-9.80 s while site scope stayed at 0.05-0.08 s. Correlation alone cannot say
          // whether staleness makes requests slow (so they overlap, so dad_live never reaches 0) or the
          // defers are a symptom of slowness caused elsewhere. Those have OPPOSITE remedies, the window
          // cannot be reproduced on demand (it needs the crawler shipping segments), and guessing it is
          // how three attributions went wrong today. Logging dad_live beside each refresh decision and
          // the per-request duration beside each completion makes the NEXT occurrence self-diagnosing
          // instead of requiring the condition to be caught live.
          let t_acc: i64 = dsv_now_us()
          dad_live = dad_live - dad_reap_done(wst)
          let now_s: i64 = sys_now_realtime_sec()
          if now_s - last_refresh >= DAD_REFRESH_MIN_SEC {
              // DEFER THE REOPEN WHILE REQUESTS ARE IN FLIGHT (2026-08-14).
              // dss_refresh_and_invalidate closes and reopens the whole web shard -- 94 segments,
              // 1.59GB -- measured at 3-8s, and worse under swap pressure. On the accept path that
              // makes ONE unlucky visitor per refresh window wear the entire cost.
              // MEASURED TODAY, end to end: a /search?q=test request took 15.038s and the edge
              // returned 503, while the very next request for the SAME query served in 0.25s. That
              // single spike is the last surviving cause of the 503 this daemon was reported for.
              // Deferring until no child is in flight means the reopen can never be charged to a
              // request that is already running; new connections wait in the listen backlog (64)
              // instead of one of them timing out. This is only possible because the accept loop now
              // tracks dad_live -- before the concurrency fix there was no such thing as "idle".
              // HARD CEILING, so bounded staleness never becomes unbounded: if deferral has pushed us
              // past DAD_REFRESH_MAX_SEC we refresh regardless. Without it a permanently busy daemon
              // would never refresh at all, trading a latency spike for an index that silently stops
              // updating -- strictly worse, and invisible.
              if dad_live == 0 {
                  dss_refresh_and_invalidate()
                  last_refresh = now_s
                  sys_write(1, "REQ refresh-ok\n" as *u8, 15)
              } else {
                  if now_s - last_refresh >= DAD_REFRESH_MAX_SEC {
                      dss_refresh_and_invalidate()
                      last_refresh = now_s
                      sys_write(1, "REQ refresh-forced\n" as *u8, 19)
                  } else {
                      var lbd: i64 = dsv_cat(logbuf, 0, "REQ refresh-defer live=" as *u8)
                      lbd = dsv_catn(logbuf, lbd, dad_live)
                      lbd = dsv_cat(logbuf, lbd, "\n" as *u8)
                      sys_write(1, logbuf, lbd)
                  }
              }
          } else {
              sys_write(1, "REQ refresh-skip\n" as *u8, 17)
          }
          // FORK-PER-REQUEST (the durable leak fix): dad_handle mmaps DAD_OUTCAP (512 KB) + boxes INTERNALLY on
          // every request and frees NONE -- the measured ~50 MB/s -> 27 GB RSS leak (budget=20M means it never
          // self-recycles). A child that handles then sys_exit(0) reclaims EVERY page BY CONSTRUCTION; the parent
          // reaps it with a blocking wait4 (no zombies -- the nx_mp_serve leak class avoided). Functionally safe:
          // sessions are file-validated (no in-mem state), upload writes hit shared fds so they persist, and the
          // parent's ctx/req/out stay pristine (the child mutates only COW copies). Leak fixed -> process stays
          // small -> fork stays cheap. Requests serialize, which is fine for a loopback admin daemon.
          let kid: i64 = sys_fork()
          if kid == 0 {
              // TIME THE REQUEST WHERE THE REQUEST ACTUALLY HAPPENS (2026-08-15). The first version of
              // this instrument timed accept->"REQ done" IN THE PARENT and printed ms=0 on every line,
              // because the parent forks and immediately loops -- the child does all the work. That is
              // the estate's own first question about any instrument (does its SUBJECT match the thing
              // it claims to measure?) and I got it wrong on the first cut. A PARENT CANNOT TIME WORK IT
              // HANDED TO A CHILD; the number it produces is real, it is just about a different event.
              let t_kid: i64 = dsv_now_us()
              let om: *i64 = sys_mmap(8) as *i64; let opo: *i64 = sys_mmap(8) as *i64; let opl: *i64 = sys_mmap(8) as *i64
              let ocl: *i64 = sys_mmap(8) as *i64; let obo: *i64 = sys_mmap(8) as *i64; let orn: *i64 = sys_mmap(8) as *i64
              let rrc: i64 = nx_http_server_read_request(cfd, req, DAD_REQCAP, om, opo, opl, ocl, obo, orn)
              if rrc == NXS_OK {
                  // L2: the HTML SERP streams (early bytes + heartbeats) ONLY behind a `stream` route row (L2b guard,
                  // dad_early_ok); a buffered row and every other route answer whole as before
                  var early: i64 = 0
                  if dad_is_search(req, orn[0]) == 1 { early = dad_early_ok(req, orn[0]) }
                  if early == 1 { dad_serve_early(cfd, req, orn[0], out) } else {
                      let oN: i64 = dad_handle(ctx, req, orn[0], out)
                      nx_http_server_send_response_nokeep_close(cfd, out, oN)
                  }
              }
              // Written by the CHILD on its own inherited fd 1, after the response is on the wire, so
              // it covers read+handle+send -- the duration a visitor actually experiences.
              let kb: *u8 = sys_mmap(64)
              var kn: i64 = dsv_cat(kb, 0, "REQ child ms=" as *u8)
              kn = dsv_catn(kb, kn, (dsv_now_us() - t_kid) / 1000)
              kn = dsv_cat(kb, kn, "\n" as *u8)
              sys_write(1, kb, kn)
              sys_close(cfd)
              sys_exit(0)
          }
          sys_close(cfd)
          if kid > 0 { dad_live = dad_live + 1 }
          // NON-BLOCKING REAP + BACKPRESSURE (2026-08-14). What stood here was
          //     if kid > 0 { sys_wait4(kid, wst, 0) }
          // a BLOCKING wait before the next accept -- concurrency EXACTLY 1. The comment above
          // justified that as "fine for a loopback admin daemon", and it WAS true when written.
          // It stopped being true when proxy_routes.conf routed PUBLIC nishifamily.com /search
          // and /doc to this daemon: one 10.5s web query then blocked every other visitor for
          // its whole duration, the buffered proxy queue backed up, and /search served 503.
          // MEASURED 2026-08-14 before this fix: 6 concurrent queries completed at
          // 1.8/3.2/4.6/5.9/6.3/7.2s -- a perfect serialization staircase -- while 6 concurrent
          // STATIC requests stayed flat at 0.035s, proving the edge was never the limit. This box
          // has 20 cores and /search was using exactly one of them at a time.
          // A COMMENT'S ASSUMPTION OUTLIVED THE ARCHITECTURE CHANGE THAT INVALIDATED IT.
          dad_live = dad_live - dad_reap_done(wst)
          // Block ONLY at the ceiling, and only until one slot frees: backpressure, not
          // serialization. It bounds fork depth on a shared box instead of admitting unbounded
          // children. The else-branch resets to 0 because wait4 <= 0 while children are believed
          // live means there is nothing left to reap -- the COUNT was wrong, not the kernel.
          while dad_live >= dad_cap {
              if sys_wait4(0 - 1, wst, 0) > 0 { dad_live = dad_live - 1 } else { dad_live = 0 }
          }
          // NAMED FOR WHAT IT MEASURES, NOT FOR WHAT A READER WANTS IT TO MEAN: this is the PARENT's
          // accept->fork->reap cost in MICROseconds, not the request duration (the child reports that
          // as `REQ child ms=`). Labelled `ms` it printed 0 on every line and read as "every request is
          // instant" -- a fabricated-looking constant in exactly the place someone debugging latency
          // would look first. A COUNTER NAMED FOR AN EVENT IT DOES NOT COVER IS WORSE THAN NO COUNTER.
          var lbz: i64 = dsv_cat(logbuf, 0, "REQ done parent_us=" as *u8)
          lbz = dsv_catn(logbuf, lbz, dsv_now_us() - t_acc)
          lbz = dsv_cat(logbuf, lbz, " live=" as *u8)
          lbz = dsv_catn(logbuf, lbz, dad_live)
          lbz = dsv_cat(logbuf, lbz, "\n" as *u8)
          sys_write(1, logbuf, lbz)
          served = served + 1
      }
  }
  sys_close(lfd)
  return 0
1099}
nx_docportal_admin_daemon.nx source

`nx_docportal_admin_daemon.nx` source
