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

↩ module page · 510 lines · 22409 B
1// nx_ims_monitor.nx -- IMS arc rung A1: READ-ONLY orphan + link-rot MONITOR.
2//
3// PURPOSE (Information Management System health, sovereign):
4//   Given the published page set and each page's OUTBOUND internal links, find
5//     ORPHANS    = published pages with 0 INBOUND internal links, excluding the
6//                  designated front-door root(s) (start.html is the root -- it is
7//                  expected to be reached directly, never linked-to).
8//     DEAD_LINKS = an outbound internal link whose target page is NOT in the
9//                  published set (internal link rot / a 404 waiting to happen).
10//
11// READ-ONLY BY CONSTRUCTION:
12//   This organ NEVER opens a corpus file for write, NEVER deletes, NEVER renames.
13//   It only READS (the live path uses sys_read_file) and computes in memory. The
14//   gate proves the pure logic with in-memory fixtures (no I/O at all).
15//
16// COMPOSES (DRY -- zero new corpus/link substrate invented):
17//   nx_wiki_index_builder  NxWikiDocStore: the page corpus (rowid -> title/url/
18//                          body) + lookup. Fixtures + live both populate this.
19//   nx_wiki_backlinks      nx_wiki_forward_links (the ONE shared [[wikilink]]
20//                          extractor) + nx_wiki_backlink_slug_matches (the ONE
21//                          shared slug resolver) -- so the monitor's notion of
22//                          "a link" agrees byte-for-byte with the backlinks
23//                          panel and the graph edge builder. No 4th scanner.
24//   nx_syscalls            sys_mmap scratch.
25//
26// LINK MODEL -- the monitor recognises BOTH internal-link conventions a Nishi
27// page carries, and folds them into ONE outbound-target list per page:
28//   (a) [[wikilink]]            -- markdown-body cross-refs (reused extractor).
29//   (b) href="/wiki/<x>.html"   -- served-HTML anchors (the live corpus is HTML).
30//   Both are normalised to a bare slug (the "/wiki/" prefix and a trailing
31//   ".html" are stripped) so a body link [[econsim]], an href "/wiki/econsim",
32//   and a stored url "/wiki/econsim.html" all resolve to the same node. [[cite:]]
33//   refs are skipped by the reused extractor (they are sources, not page links).
34//
35// Hygiene: M1 out-params not *T returns; M3 every while has a hard iter cap;
36// M5 every buffer index bounded; M6 no pretend stubs; M7 named constants;
37// M8 verdicts propagated. ("loop" is a reserved word -- never used as an ident.)
38//
39// Status: V1 (IMS arc A1). 2026-06-17. license_tier: ORIGINAL
40import "nx_syscalls.nx"
41import "nx_wiki_index_builder.nx"
42import "nx_wiki_backlinks.nx"
43
44// ===== Sealed verdict surface (codes 2720-2739) ==============================
45const NX_IMS_OK:          i64 = 0
46const NX_IMS_BAD_INPUT:   i64 = 2720
47const NX_IMS_OVERFLOW:    i64 = 2721
48const NX_IMS_LOOP_BUDGET: i64 = 2722
49
50// ===== Named sizing constants (M7) ===========================================
51const NX_IMS_MAX_PAGES:        i64 = 1000     // mirrors doc-store docs cap
52const NX_IMS_MAX_LINKS_PP:     i64 = 512      // outbound links scanned per page
53const NX_IMS_MAX_ROOTS:        i64 = 16       // designated root pages cap
54const NX_IMS_SCAN_BUDGET:      i64 = 8000000  // per-body byte-scan cap (M3)
55const NX_IMS_MAX_SLUG_LEN:     i64 = 256      // a single resolved slug name cap
56const NX_IMS_WIKI_PREFIX_LEN:  i64 = 6        // len("/wiki/")
57const NX_IMS_HTML_SUFFIX_LEN:  i64 = 5        // len(".html")
58
59// Common ASCII (M7)
60const NX_IMS_QUOTE:   i64 = 0x22   // '"'
61const NX_IMS_DOT:     i64 = 0x2E   // '.'
62
63// Truncate (p,n) at the first '#' (fragment) or '?' (query) -- a link to
64// "start.html#tasks" or "edit?p=x" addresses the base resource, so the fragment/
65// query is not part of the page identity. Returns the truncated length.
66func nx_ims_strip_frag_query(p: *u8, n: i64) -> i64 {
  var i: i64 = 0
  while i < n {
      if p[i] == (0x23 as u8) { return i }   // '#'
      if p[i] == (0x3F as u8) { return i }   // '?'
      i = i + 1
  }
  return n
74}
75
76// ===== slug normalisation =====================================================
77//
78// Normalise a raw link/url token (p,n) to its bare slug: strip any #fragment /
79// ?query, then an optional leading "/wiki/" and an optional trailing ".html".
80// Returns the bare length; the bare pointer is handed back via out_ptr.
81// Defensive: never reads OOB; an already-bare slug passes through unchanged.
82func nx_ims_norm_slug(p: *u8, n: i64, out_ptr: *i64) -> i64 {
  out_ptr[0] = p as i64
  var bp: i64 = p as i64
  var bn: i64 = nx_ims_strip_frag_query(p, n)
  if bn < 0 { bn = 0 }
  // strip leading "/wiki/"
  if bn >= NX_IMS_WIKI_PREFIX_LEN {
      let q: *u8 = bp as *u8
      if q[0] == (0x2F as u8) {                 // '/'
          if q[1] == (0x77 as u8) {             // 'w'
              if q[2] == (0x69 as u8) {         // 'i'
                  if q[3] == (0x6B as u8) {     // 'k'
                      if q[4] == (0x69 as u8) { // 'i'
                          if q[5] == (0x2F as u8) {  // '/'
                              bp = bp + NX_IMS_WIKI_PREFIX_LEN
                              bn = bn - NX_IMS_WIKI_PREFIX_LEN
                          }
                      }
                  }
              }
          }
      }
  }
  // strip trailing ".html"
  if bn >= NX_IMS_HTML_SUFFIX_LEN {
      let r: *u8 = bp as *u8
      let base: i64 = bn - NX_IMS_HTML_SUFFIX_LEN
      if r[base]     == (NX_IMS_DOT as u8) {        // '.'
          if r[base + 1] == (0x68 as u8) {          // 'h'
              if r[base + 2] == (0x74 as u8) {      // 't'
                  if r[base + 3] == (0x6D as u8) {  // 'm'
                      if r[base + 4] == (0x6C as u8) {  // 'l'
                          bn = bn - NX_IMS_HTML_SUFFIX_LEN
                      }
                  }
              }
          }
      }
  }
  out_ptr[0] = bp
  return bn
123}
124
125// Do two raw link/url tokens name the SAME page after normalisation?
126// (1 = same, 0 = different). Case-sensitive on the bare name (slugs are
127// canonical lowercase by convention).
128func nx_ims_slug_eq(ap: *u8, an: i64, bp: *u8, bn: i64) -> i64 {
  let aib: *i64 = sys_mmap(8) as *i64
  let bib: *i64 = sys_mmap(8) as *i64
  let ain: i64 = nx_ims_norm_slug(ap, an, aib)
  let bin: i64 = nx_ims_norm_slug(bp, bn, bib)
  if ain != bin { return 0 }
  if ain < 1 { return 0 }
  let aa: *u8 = aib[0] as *u8
  let bb: *u8 = bib[0] as *u8
  var i: i64 = 0
  var eq: i64 = 1
  while i < ain {
      if aa[i] != bb[i] { eq = 0 }
      i = i + 1
  }
  return eq
144}
145
146// ===== href="/wiki/<x>.html" extractor =======================================
147//
148// The served corpus is HTML; its page-to-page links are anchors, not
149// [[wikilinks]]. Walk body (p,n); for each occurrence of   href="/wiki/...."
150// record the inner target (offset,len up to the closing quote) into the caller's
151// parallel offs[]/lens[] (capacity cap). Targets are recorded RAW (still with
152// the "/wiki/" prefix + ".html"); the caller normalises via nx_ims_norm_slug.
153// Only /wiki/ hrefs are recorded -- external/absolute links are not internal
154// link-rot candidates. Returns count (>=0) or -verdict.
155func nx_ims_href_links(body: *u8, n: i64,
                        offs: *i64, lens: *i64, cap: i64,
                        out_count: *i64) -> i64 {
  if (out_count as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  out_count[0] = 0
  if (body as i64) == 0 { return NX_IMS_OK }
  if n < 0 { return 0 - NX_IMS_BAD_INPUT }
  // needle = href="/wiki/   (10 bytes)
  let needle: *u8 = "href=\"/wiki/" as *u8
  let needle_n: i64 = 12
  var i: i64 = 0
  var cnt: i64 = 0
  var iter: i64 = 0
  while i < n {
      if iter >= NX_IMS_SCAN_BUDGET { return 0 - NX_IMS_LOOP_BUDGET }
      iter = iter + 1
      var advanced: i64 = 0
      if i + needle_n <= n {
          // match needle at i ?
          var m: i64 = 0
          var ok: i64 = 1
          while m < needle_n {
              if body[i + m] != needle[m] { ok = 0 }
              m = m + 1
          }
          if ok == 1 {
              // target starts right after  href="  (at the '/wiki/...'), so we
              // keep the /wiki/ prefix in the recorded token for symmetry with
              // stored urls. start = i + 6  (len of  href="  )
              let start: i64 = i + 6
              // scan to the closing double-quote
              var cur: i64 = start
              var done: i64 = 0
              var endq: i64 = start
              var found: i64 = 0
              while done == 0 {
                  if cur >= n { done = 1 }
                  if cur - start >= NX_IMS_MAX_SLUG_LEN { done = 1 }
                  if done == 0 {
                      if body[cur] == (NX_IMS_QUOTE as u8) {
                          endq = cur
                          found = 1
                          done = 1
                      }
                      if found == 0 { cur = cur + 1 }
                  }
              }
              if found == 1 {
                  let tlen: i64 = endq - start
                  if tlen > 0 {
                      if tlen <= NX_IMS_MAX_SLUG_LEN {
                          // Only record genuine internal-PAGE links: after
                          // stripping #fragment/?query the target must end in
                          // ".html". This excludes dynamic routes (/wiki/edit?..,
                          // /wiki/status, /wiki/components) which are NOT static
                          // pages and so are not internal-page link-rot. A
                          // fragment link (start.html#x) keeps its .html and
                          // resolves to the base page.
                          let tp: *u8 = (start + (body as i64)) as *u8
                          let bare_n: i64 = nx_ims_strip_frag_query(tp, tlen)
                          var is_html: i64 = 0
                          if bare_n >= NX_IMS_HTML_SUFFIX_LEN {
                              let base: i64 = bare_n - NX_IMS_HTML_SUFFIX_LEN
                              if tp[base]     == (NX_IMS_DOT as u8) {
                                  if tp[base + 1] == (0x68 as u8) {
                                      if tp[base + 2] == (0x74 as u8) {
                                          if tp[base + 3] == (0x6D as u8) {
                                              if tp[base + 4] == (0x6C as u8) { is_html = 1 }
                                          }
                                      }
                                  }
                              }
                          }
                          if is_html == 1 {
                              if cnt >= cap { return 0 - NX_IMS_OVERFLOW }
                              if cnt >= NX_IMS_MAX_LINKS_PP { return 0 - NX_IMS_OVERFLOW }
                              offs[cnt] = start
                              lens[cnt] = tlen
                              cnt = cnt + 1
                          }
                      }
                  }
                  i = endq + 1
                  advanced = 1
              }
          }
      }
      if advanced == 0 { i = i + 1 }
  }
  out_count[0] = cnt
  return NX_IMS_OK
246}
247
248// ===== unified outbound-target collector =====================================
249//
250// For one page body, collect ALL outbound internal targets -- BOTH [[wikilink]]
251// (reused nx_wiki_forward_links) AND href="/wiki/..." (nx_ims_href_links) -- as
252// (offset,len) pairs into offs[]/lens[] (capacity cap). Returns the total count
253// (>=0) or -verdict. Offsets are byte offsets INTO body.
254func nx_ims_collect_targets(body: *u8, n: i64,
                             offs: *i64, lens: *i64, cap: i64,
                             out_count: *i64) -> i64 {
  if (out_count as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  out_count[0] = 0
  // pass 1: [[wikilink]] (the shared extractor)
  let wc: *i64 = sys_mmap(8) as *i64
  let rc_w: i64 = nx_wiki_forward_links(body, n, offs, lens, cap, wc)
  if rc_w != NX_WBL_OK { return 0 - NX_IMS_OVERFLOW }
  var total: i64 = wc[0]
  // pass 2: href="/wiki/..." appended after the wikilinks
  if total < cap {
      let hoffs: *i64 = (offs as i64 + total * 8) as *i64
      let hlens: *i64 = (lens as i64 + total * 8) as *i64
      let hc: *i64 = sys_mmap(8) as *i64
      let rc_h: i64 = nx_ims_href_links(body, n, hoffs, hlens, cap - total, hc)
      if rc_h != NX_IMS_OK { return rc_h }
      total = total + hc[0]
  }
  out_count[0] = total
  return NX_IMS_OK
275}
276
277// ===== root predicate ========================================================
278//
279// Is page rowid `r` (by its stored url slug) one of the designated roots?
280// roots[] holds root rowids (already resolved by the caller). 1 = root.
281func nx_ims_is_root(r: i64, roots: *i64, nroots: i64) -> i64 {
  var i: i64 = 0
  while i < nroots {
      if i >= NX_IMS_MAX_ROOTS { return 0 }
      if roots[i] == r { return 1 }
      i = i + 1
  }
  return 0
289}
290
291// Resolve a root slug (sp,sn) to a rowid in the store, or -1 if not present.
292func nx_ims_resolve_root(store: *NxWikiDocStore, sp: *u8, sn: i64) -> i64 {
  let dc: i64 = nx_wiki_doc_store_count(store)
  let tp: *i64 = sys_mmap(8) as *i64
  let tn: *i64 = sys_mmap(8) as *i64
  let up: *i64 = sys_mmap(8) as *i64
  let un: *i64 = sys_mmap(8) as *i64
  let bp: *i64 = sys_mmap(8) as *i64
  let bn: *i64 = sys_mmap(8) as *i64
  var r: i64 = 0
  while r < dc {
      if r >= NX_IMS_MAX_PAGES { return 0 - 1 }
      let rc: i64 = nx_wiki_doc_store_lookup(store, r, tp, tn, up, un, bp, bn)
      if rc == NX_WIB_OK {
          if nx_ims_slug_eq(up[0] as *u8, un[0], sp, sn) == 1 { return r }
      }
      r = r + 1
  }
  return 0 - 1
310}
311
312// ===== CORE: inbound-link census =============================================
313//
314// For the whole store, compute inbound[r] = number of DISTINCT published pages
315// that link TO page r (via any outbound convention). A page linking itself does
316// NOT count toward its own inbound (a self-link cannot rescue an orphan). Fills
317// the caller's inbound[] (length >= doc_count). Returns NX_IMS_OK or -verdict.
318func nx_ims_inbound_counts(store: *NxWikiDocStore,
                            inbound: *i64) -> i64 {
  if (store as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  if store.valid != 1 { return 0 - NX_IMS_BAD_INPUT }
  let dc: i64 = nx_wiki_doc_store_count(store)
  var z: i64 = 0
  while z < dc {
      if z >= NX_IMS_MAX_PAGES { return 0 - NX_IMS_LOOP_BUDGET }
      inbound[z] = 0
      z = z + 1
  }
  // per-source scratch
  let offs: *i64 = sys_mmap(NX_IMS_MAX_LINKS_PP * 8) as *i64
  let lens: *i64 = sys_mmap(NX_IMS_MAX_LINKS_PP * 8) as *i64
  let lc: *i64 = sys_mmap(8) as *i64
  // source lookup out-params
  let tp: *i64 = sys_mmap(8) as *i64
  let tn: *i64 = sys_mmap(8) as *i64
  let up: *i64 = sys_mmap(8) as *i64
  let un: *i64 = sys_mmap(8) as *i64
  let bp: *i64 = sys_mmap(8) as *i64
  let bn: *i64 = sys_mmap(8) as *i64
  // target lookup out-params
  let u2p: *i64 = sys_mmap(8) as *i64
  let u2n: *i64 = sys_mmap(8) as *i64
  let t2p: *i64 = sys_mmap(8) as *i64
  let t2n: *i64 = sys_mmap(8) as *i64
  let b2p: *i64 = sys_mmap(8) as *i64
  let b2n: *i64 = sys_mmap(8) as *i64
  // per-source "already credited this target" marks (dedupe distinct sources)
  let credited: *i64 = sys_mmap(NX_IMS_MAX_PAGES * 8) as *i64
349
  var s: i64 = 0
  while s < dc {
      if s >= NX_IMS_MAX_PAGES { return 0 - NX_IMS_LOOP_BUDGET }
      let rc_s: i64 = nx_wiki_doc_store_lookup(store, s, tp, tn, up, un, bp, bn)
      if rc_s == NX_WIB_OK {
          // reset credited marks for this source
          var c0: i64 = 0
          while c0 < dc {
              if c0 >= NX_IMS_MAX_PAGES { c0 = dc }
              if c0 < dc { credited[c0] = 0 }
              c0 = c0 + 1
          }
          let body: *u8 = bp[0] as *u8
          let body_n: i64 = bn[0]
          let rc_c: i64 = nx_ims_collect_targets(body, body_n, offs, lens, NX_IMS_MAX_LINKS_PP, lc)
          if rc_c == NX_IMS_OK {
              var k: i64 = 0
              while k < lc[0] {
                  if k >= NX_IMS_MAX_LINKS_PP { k = lc[0] }
                  if k < lc[0] {
                      let lp: *u8 = (body as i64 + offs[k]) as *u8
                      let ln: i64 = lens[k]
                      // resolve target -> rowid
                      var dst: i64 = 0 - 1
                      var t: i64 = 0
                      while t < dc {
                          if dst < 0 {
                              let rc_t: i64 = nx_wiki_doc_store_lookup(store, t, t2p, t2n, u2p, u2n, b2p, b2n)
                              if rc_t == NX_WIB_OK {
                                  if nx_ims_slug_eq(lp, ln, u2p[0] as *u8, u2n[0]) == 1 { dst = t }
                              }
                          }
                          t = t + 1
                      }
                      if dst >= 0 {
                          if dst != s {                 // self-link does NOT count
                              if credited[dst] == 0 {   // distinct source only once
                                  inbound[dst] = inbound[dst] + 1
                                  credited[dst] = 1
                              }
                          }
                      }
                  }
                  k = k + 1
              }
          }
      }
      s = s + 1
  }
  return NX_IMS_OK
400}
401
402// ===== CORE: orphan census ===================================================
403//
404// ORPHANS = pages with inbound==0, EXCLUDING any rowid in roots[]. Fills
405// out_rowids[] (capacity cap) with the orphan rowids, count via out_count.
406// Returns NX_IMS_OK or -verdict. Pure over the supplied inbound[] + roots[].
407func nx_ims_orphans(store: *NxWikiDocStore,
                     roots: *i64, nroots: i64,
                     out_rowids: *i64, cap: i64,
                     out_count: *i64) -> i64 {
  if (out_count as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  out_count[0] = 0
  if (store as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  if store.valid != 1 { return 0 - NX_IMS_BAD_INPUT }
  let dc: i64 = nx_wiki_doc_store_count(store)
  let inbound: *i64 = sys_mmap(NX_IMS_MAX_PAGES * 8) as *i64
  let rc_in: i64 = nx_ims_inbound_counts(store, inbound)
  if rc_in != NX_IMS_OK { return rc_in }
  var cnt: i64 = 0
  var r: i64 = 0
  while r < dc {
      if r >= NX_IMS_MAX_PAGES { return 0 - NX_IMS_LOOP_BUDGET }
      if inbound[r] == 0 {
          if nx_ims_is_root(r, roots, nroots) == 0 {
              if cnt >= cap { return 0 - NX_IMS_OVERFLOW }
              out_rowids[cnt] = r
              cnt = cnt + 1
          }
      }
      r = r + 1
  }
  out_count[0] = cnt
  return NX_IMS_OK
434}
435
436// ===== CORE: dead-link census ================================================
437//
438// DEAD_LINKS = each outbound internal target that resolves to NO published page.
439// Reported as parallel arrays: out_src[] = source rowid, out_off[]/out_len[] =
440// the offending target token's (offset,len) INTO that source's body (so the
441// caller can print the exact dead href/wikilink). count via out_count.
442// Returns NX_IMS_OK or -verdict.
443func nx_ims_dead_links(store: *NxWikiDocStore,
                        out_src: *i64, out_off: *i64, out_len: *i64, cap: i64,
                        out_count: *i64) -> i64 {
  if (out_count as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  out_count[0] = 0
  if (store as i64) == 0 { return 0 - NX_IMS_BAD_INPUT }
  if store.valid != 1 { return 0 - NX_IMS_BAD_INPUT }
  let dc: i64 = nx_wiki_doc_store_count(store)
  let offs: *i64 = sys_mmap(NX_IMS_MAX_LINKS_PP * 8) as *i64
  let lens: *i64 = sys_mmap(NX_IMS_MAX_LINKS_PP * 8) as *i64
  let lc: *i64 = sys_mmap(8) as *i64
  let tp: *i64 = sys_mmap(8) as *i64
  let tn: *i64 = sys_mmap(8) as *i64
  let up: *i64 = sys_mmap(8) as *i64
  let un: *i64 = sys_mmap(8) as *i64
  let bp: *i64 = sys_mmap(8) as *i64
  let bn: *i64 = sys_mmap(8) as *i64
  let u2p: *i64 = sys_mmap(8) as *i64
  let u2n: *i64 = sys_mmap(8) as *i64
  let t2p: *i64 = sys_mmap(8) as *i64
  let t2n: *i64 = sys_mmap(8) as *i64
  let b2p: *i64 = sys_mmap(8) as *i64
  let b2n: *i64 = sys_mmap(8) as *i64
466
  var cnt: i64 = 0
  var s: i64 = 0
  while s < dc {
      if s >= NX_IMS_MAX_PAGES { return 0 - NX_IMS_LOOP_BUDGET }
      let rc_s: i64 = nx_wiki_doc_store_lookup(store, s, tp, tn, up, un, bp, bn)
      if rc_s == NX_WIB_OK {
          let body: *u8 = bp[0] as *u8
          let body_n: i64 = bn[0]
          let rc_c: i64 = nx_ims_collect_targets(body, body_n, offs, lens, NX_IMS_MAX_LINKS_PP, lc)
          if rc_c == NX_IMS_OK {
              var k: i64 = 0
              while k < lc[0] {
                  if k >= NX_IMS_MAX_LINKS_PP { k = lc[0] }
                  if k < lc[0] {
                      let lp: *u8 = (body as i64 + offs[k]) as *u8
                      let ln: i64 = lens[k]
                      var dst: i64 = 0 - 1
                      var t: i64 = 0
                      while t < dc {
                          if dst < 0 {
                              let rc_t: i64 = nx_wiki_doc_store_lookup(store, t, t2p, t2n, u2p, u2n, b2p, b2n)
                              if rc_t == NX_WIB_OK {
                                  if nx_ims_slug_eq(lp, ln, u2p[0] as *u8, u2n[0]) == 1 { dst = t }
                              }
                          }
                          t = t + 1
                      }
                      if dst < 0 {
                          if cnt >= cap { return 0 - NX_IMS_OVERFLOW }
                          out_src[cnt] = s
                          out_off[cnt] = offs[k]
                          out_len[cnt] = lens[k]
                          cnt = cnt + 1
                      }
                  }
                  k = k + 1
              }
          }
      }
      s = s + 1
  }
  out_count[0] = cnt
  return NX_IMS_OK
510}
nx_ims_monitor.nx source

`nx_ims_monitor.nx` source
