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

↩ module page · 466 lines · 20924 B
1// nx_capgraph_edges.nx -- DERIVES the capability graph's prerequisite edges FROM THE IMPORT CLOSURE.
2//
3// WHY (debt 1785518444, filed by me 2026-07-31): nx_capgraph_derive shipped reading a HAND-DECLARED
4// edge file. Declared edges are a seed, not a measurement, and a MISSING edge is the dangerous case --
5// it lets a dependent read healthier than the layer it stands on. This organ replaces the declaration
6// with a measurement.
7//
8// THE MEASUREMENT, end to end, no taste anywhere in it:
9//   1. OWNERSHIP comes from knowledge/compare/<domain>.matrix, which already maps every domain to the
10//      real organ SOURCE PATHS backing each of its capabilities (field2), with field3 = the symbol.
11//      Rows whose symbol is _ABSENT_ are declared GAPS -- skipped, they own nothing.
12//   2. DEPENDENCY comes from the source itself: every `import "<module>.nx"` in an owned source.
13//   3. EDGE: if a source owned by domain A imports a module owned by domain B (B != A), then B is a
14//      PREREQUISITE of A. That is a fact about the build, not an opinion about the architecture.
15//
16// ⚠THE MEASURED GRAPH IS NOT ACYCLIC. Probed 2026-07-31: search>webscraping, browser>webscraping AND
17// webscraping>browser, search>deepresearch AND deepresearch>search, comms>videoops AND videoops>comms.
18// Mutually-importing domains are REAL. This is not a defect in the measurement and must not be
19// "cleaned up" by dropping edges: a cycle is a genuine finding -- it names a CO-DEPENDENT CLUSTER that
20// can only be raised together. The consumer's min-relaxation is a fixpoint iteration bounded by node
21// count, so it converges on a general digraph; the cycle members simply share a floor.
22//
23// HONEST ENVELOPE, emitted into the file itself so no reader has to trust this comment:
24//   - coverage is bounded by the matrices, not by this organ: a domain with few matrix rows yields few
25//     edges. That is a matrix-completeness gap, and it is REPORTED, never silently treated as "no deps".
26//   - matrix rows pointing at sources that do not exist on disk are COUNTED and reported (missing=N).
27//   - first-wins ownership when two domains claim the same module; ambiguity is COUNTED and reported.
28//
29// nx_capgraph_edges [outfile]     exit 0 ok | 4 capture-fail | 5 write-fail
30// license_tier: ORIGINAL   No hw writes (Rule 26).   expect_exit: 0
31import "nx_capgraph_edges_lib.nx"
32import "nx_matrix_sym_lib.nx"
33
34func main(argc: i64, argv: *i64) -> i64 {
  ce_init()
  ce_depthscan = 0
  ce_load_depth()
  var outp: *u8 = CE_OUTDEF
  var ai2: i64 = 1
  while ai2 < argc {
      let a: *u8 = argv[ai2] as *u8
      if cg_streq(a, "--transitive" as *u8) == 1 { ce_trans = 1 }
      else {
          if cg_streq(a, "--direct" as *u8) == 1 { ce_trans = 0 }
          else {
              if cg_streq(a, "--depthscan" as *u8) == 1 { ce_depthscan = 1 }
              else { outp = a }
          }
      }
      ai2 = ai2 + 1
  }
52
  // ---- domain list, from the live honesty gate (never a hardcoded roster) ----
  let sout: *u8 = sys_mmap(CE_CAP + 16)
  let solen: *i64 = sys_mmap(16) as *i64
  let rc: i64 = tr_run1(CE_SOTA, 0 as *u8, sout, CE_CAP, solen)
  let sn: i64 = solen[0]
  if rc == 127 { return 4 }
  if sn <= 0 { return 4 }
  var ls: i64 = 0
  var i: i64 = 0
  while i <= sn {
      var isend: i64 = 0
      if i == sn { isend = 1 }
      else { if sout[i] == (10 as u8) { isend = 1 } }
      if isend == 1 {
          var covp: i64 = 0 - 1
          var j: i64 = ls
          while j < i {
              if j + 4 <= i {
                  if sout[j] == (99 as u8) {
                      if sout[j + 1] == (111 as u8) {
                          if sout[j + 2] == (118 as u8) {
                              if sout[j + 3] == (61 as u8) {
                                  covp = j
                                  j = i
                              }
                          }
                      }
                  }
              }
              j = j + 1
          }
          if covp > 0 {
              var start: i64 = ls
              var found: i64 = 0
              var s: i64 = ls
              while s < i {
                  if found == 0 {
                      if sout[s] != (32 as u8) {
                          start = s
                          found = 1
                      }
                  }
                  s = s + 1
              }
              if found == 1 {
                  var w: i64 = 0
                  var q: i64 = start
                  var d2: i64 = 0
                  while d2 == 0 {
                      if q >= i { d2 = 1 }
                      else {
                          if sout[q] == (32 as u8) { d2 = 1 }
                          else {
                              if w < CE_NAMEW - 1 {
                                  ce_scr2[w] = sout[q]
                                  w = w + 1
                              }
                              q = q + 1
                          }
                      }
                  }
                  ce_scr2[w] = 0 as u8
                  if w > 0 { ce_dom_add(ce_scr2) }
              }
          }
          ls = i + 1
      }
      i = i + 1
  }
122
  // ---- PHASE 1: ownership from the matrices ----
  var d: i64 = 0
  while d < ce_ndom {
      ce_cpy(ce_path, "knowledge/compare/" as *u8, CE_PATHW)
      var pl: i64 = 0
      while ce_path[pl] != (0 as u8) { pl = pl + 1 }
      let dn: *u8 = ce_dom_name(d)
      var k: i64 = 0
      while dn[k] != (0 as u8) {
          if pl < CE_PATHW - 8 {
              ce_path[pl] = dn[k]
              pl = pl + 1
          }
          k = k + 1
      }
      ce_path[pl] = 46 as u8
      ce_path[pl + 1] = 109 as u8
      ce_path[pl + 2] = 97 as u8
      ce_path[pl + 3] = 116 as u8
      ce_path[pl + 4] = 114 as u8
      ce_path[pl + 5] = 105 as u8
      ce_path[pl + 6] = 120 as u8
      ce_path[pl + 7] = 0 as u8
      let mn: i64 = ce_read_into_buf(ce_path, CE_CAP)
      if mn > 0 {
          var mls: i64 = 0
          var m: i64 = 0
          while m <= mn {
              var me: i64 = 0
              if m == mn { me = 1 }
              else { if ce_buf[m] == (10 as u8) { me = 1 } }
              if me == 1 {
                  var skip: i64 = 0
                  if mls >= m { skip = 1 }
                  else {
                      if ce_buf[mls] == (35 as u8) { skip = 1 }
                      if ce_buf[mls] == (64 as u8) { skip = 1 }
                  }
                  if skip == 0 {
                      let plen: i64 = ce_field(mls, m, 1)
                      if plen > 0 {
                          ce_cpy(ce_path, ce_scr, CE_PATHW)
                          let slen: i64 = ce_field(mls, m, 2)
                          var absent: i64 = 0
                          if slen == 0 { absent = 1 }
                          // ONE reader of the symbol format (nx_matrix_sym_lib). The exact-equality
                          // test that stood here knew only the bare "_ABSENT_", so a WATCH CONTRACT
                          // "_ABSENT_:<future_symbol>" -- a DECLARED GAP that owns nothing -- was
                          // read as a real symbol and given an OWNERSHIP EDGE over its organ.
                          // A DECLARED GAP THAT OWNS A SOURCE FILE POISONS EVERY REACHABILITY
                          // QUESTION ASKED OVER THE GRAPH, because the invented edge is
                          // indistinguishable from a real one at every later hop.
                          if msym_is_declared_gap_z(ce_scr) == 1 { absent = 1 }
                          if absent == 0 {
                              ce_basename(ce_path)
                              ce_own_add(ce_scr2, d)
                              ce_src_add(d, ce_path)
                          }
                      }
                  }
                  mls = m + 1
              }
              m = m + 1
          }
      }
      d = d + 1
  }
190
  // ---- PHASE 2: edges from the import closure ----
  var scan_lo: i64 = ce_maxdepth
  var scan_hi: i64 = ce_maxdepth
  if ce_depthscan == 1 {
      scan_lo = 1
      scan_hi = CE_DEPTH_SCANMAX
      cax_puts("=== DEPTH CURVE: edges per transitive depth -- the cut must be MEASURED, not chosen ===\n" as *u8)
      cax_puts("   depth 1 == the strict one-hop (direct) subset. Pick the depth where the curve FLATTENS.\n\n" as *u8)
  }
  var dcur: i64 = scan_lo
  while dcur <= scan_hi {
      ce_maxdepth = dcur
      ce_ne = 0
      ce_nie = 0
      ce_transedges = 0
      ce_scanned = 0
      ce_nonnx = 0
      ce_altres = 0
      ce_missing = 0
      ce_nenc = 0
  var si: i64 = 0
  while si < ce_nsrc {
      let sd: i64 = ce_srcd[si]
      let sp: *u8 = ((ce_srcp as i64) + si * CE_PATHW) as *u8
      // RESOLUTION IS MULTI-ROOT BY MEASUREMENT: matrix paths are relative to buildroot/ for sources
      // but to the SERVING ROOT for site/knowledge artifacts, and two rows are stale renames that
      // still exist under the other source dir. A single-prefix probe reported 23 "missing" files
      // that were mostly PRESENT -- the tool was wrong, not the corpus.
      var fn2: i64 = 0 - 1
      if ce_is_nx(sp) == 0 {
          ce_nonnx = ce_nonnx + 1
      } else {
          ce_join("buildroot/" as *u8, sp)
          fn2 = ce_read_into_buf(ce_path, CE_HEAD)
          if fn2 >= 0 { ce_res_bld = ce_res_bld + 1 }
          if fn2 < 0 {
              ce_join("\x00" as *u8, sp)
              fn2 = ce_read_into_buf(ce_path, CE_HEAD)
              if fn2 >= 0 {
                  ce_altres = ce_altres + 1
                  ce_res_srv = ce_res_srv + 1
              }
          }
          if fn2 < 0 {
              ce_basename(sp)
              ce_join("buildroot/runtime/" as *u8, ce_scr2)
              fn2 = ce_read_into_buf(ce_path, CE_HEAD)
              if fn2 >= 0 {
                  ce_altres = ce_altres + 1
                  ce_res_base = ce_res_base + 1
              }
          }
          if fn2 < 0 {
              ce_basename(sp)
              ce_join("buildroot/runtime/_hdl_build/" as *u8, ce_scr2)
              fn2 = ce_read_into_buf(ce_path, CE_HEAD)
              if fn2 >= 0 {
                  ce_altres = ce_altres + 1
                  ce_res_base = ce_res_base + 1
              }
          }
          if fn2 < 0 { ce_missing = ce_missing + 1 }
      }
      if fn2 >= 0 {
          ce_scanned = ce_scanned + 1
          ce_qh = 0
          ce_qt = 0
          ce_nseen = 0
          ce_scan_buf_imports(sd, 1, fn2)
          while ce_qh < ce_qt {
              let qi: i64 = ce_qh
              ce_qh = ce_qh + 1
              let qdep: i64 = ce_qd[qi]
              ce_cpy(ce_scr, ((ce_q as i64) + qi * CE_NAMEW) as *u8, CE_NAMEW)
              let qn: i64 = ce_resolve_base(ce_scr)
              if qn > 0 { ce_scan_buf_imports(sd, qdep, qn) }
          }
      }
      si = si + 1
  }
      if ce_depthscan == 1 {
          cax_puts("  " as *u8)
          cax_kv("depth" as *u8, dcur)
          cax_kv("domain_edges" as *u8, ce_ne)
          cax_kv("infra_edges" as *u8, ce_nie)
          cax_kv("via_infra" as *u8, ce_transedges)
          cax_puts("\n" as *u8)
      }
      dcur = dcur + 1
  }
  if ce_depthscan == 1 {
      cax_puts("\nDEPTH-SCAN done -- set transitive_depth=<d> in knowledge/status/capgraph.conf.\n" as *u8)
      return 0
  }
285
  // ---- PHASE 3: emit ----
  ce_fd = sys_openat_wr(outp, 0x1A4)
  if ce_fd < 0 {
      cax_puts("CAPGRAPH-EDGES verdict=WRITE-FAIL\n" as *u8)
      return 5
  }
  ce_w("# capgraph_edges.conf -- MEASURED prerequisite edges. GENERATED by nx_capgraph_edges.\n" as *u8)
  ce_w("# DO NOT HAND-EDIT: regenerate instead, or the file stops being a measurement.\n" as *u8)
  ce_w("#\n# METHOD: ownership from knowledge/compare/<domain>.matrix field2 (source path), rows whose\n" as *u8)
  ce_w("# field3 symbol is _ABSENT_ skipped as declared gaps; dependency from each owned source's\n" as *u8)
  ce_w("# `import \"<module>.nx\"` lines; edge B>A when a source owned by A imports a module owned by B.\n" as *u8)
  ce_w("# That is a fact about the build, not an opinion about the architecture.\n#\n" as *u8)
  ce_w("# ENVELOPE (read this before trusting the graph):\n" as *u8)
  ce_w("#   domains=" as *u8)
  ce_wi(ce_ndom)
  ce_w("  owned_modules=" as *u8)
  ce_wi(ce_nown)
  ce_w("  sources_scanned=" as *u8)
  ce_wi(ce_scanned)
  ce_w("\n#   non_source_rows=" as *u8)
  ce_wi(ce_nonnx)
  ce_w("  (rows citing .js/.tsv/.md/.html evidence -- carry no imports, can never yield an edge;\n" as *u8)
  ce_w("#     counted SEPARATELY because 'not a source' is not the same defect as 'absent')\n" as *u8)
  ce_w("#   resolved_via_alt_root=" as *u8)
  ce_wi(ce_altres)
  ce_w("  (found at the serving root or under the other source dir, not buildroot/)\n" as *u8)
  ce_w("#   sources_missing=" as *u8)
  ce_wi(ce_missing)
  ce_w("  (.nx rows genuinely absent from every root -- a real matrix-quality gap)\n" as *u8)
  ce_w("#   shared_modules_EXCLUDED=" as *u8)
  ce_wi(ce_ambig)
  ce_w("  (claimed by >1 domain = SHARED INFRA, not owned: importing one implies\n" as *u8)
  ce_w("#     NO directional dependency, so they derive no edge. Including them made edge DIRECTION\n" as *u8)
  ce_w("#     order-dependent -- both llm>modelwright and modelwright>llm were derivable. Excluding\n" as *u8)
  ce_w("#     them makes this file DETERMINISTIC. Under-counts edges; never fabricates one.)\n" as *u8)
  ce_w("#   OWNERSHIP COVERAGE = " as *u8)
  ce_wi(ce_enc_owned())
  ce_w(" owned of " as *u8)
  ce_wi(ce_nenc)
  ce_w(" modules the closure actually touches. THIS IS THE REAL BOUND ON THIS GRAPH:\n" as *u8)
  ce_w("#     an UNOWNED module is where dependency information DIES -- the walk passes through it and\n" as *u8)
  ce_w("#     can attribute nothing on the far side. Every edge below is real; the edge SET is a FLOOR.\n" as *u8)
  ce_w("#     Raising this number is purely a matter of adding matrix rows -- no code change.\n" as *u8)
  ce_w("#   edges=" as *u8)
  ce_wi(ce_ne)
  ce_w("\n#\n# COVERAGE IS BOUNDED BY THE MATRICES, not by this organ: a domain with few matrix rows\n" as *u8)
  ce_w("# yields few edges. A missing edge lets a dependent read healthier than what it stands on.\n" as *u8)
  ce_w("# ⚠THE MEASURED GRAPH IS NOT ACYCLIC -- mutually-importing domains are real and must NOT be\n" as *u8)
  ce_w("# pruned: a cycle names a CO-DEPENDENT CLUSTER that can only be raised together.\n\n" as *u8)
  var e: i64 = 0
  while e < ce_ne {
      ce_w(ce_dom_name(ce_ef[e]))
      ce_w(">" as *u8)
      ce_w(ce_dom_name(ce_et[e]))
      ce_w("\n" as *u8)
      e = e + 1
  }
  ce_w("\n# SHARED INFRASTRUCTURE as FIRST-CLASS NODES (infra:<module>). A module claimed by more\n" as *u8)
  ce_w("# than one domain is a prerequisite of every domain that imports it -- direction is never\n" as *u8)
  ce_w("# ambiguous here, so nothing is discarded. A node many domains stand on IS the chokepoint.\n" as *u8)
  ce_w("# These carry NO measured level yet, and UNMEASURED never drags a dependent down (L3).\n" as *u8)
  var g: i64 = 0
  while g < ce_nie {
      ce_w("infra:" as *u8)
      ce_w(((ce_ownname as i64) + ce_if[g] * CE_NAMEW) as *u8)
      ce_w(">" as *u8)
      ce_w(ce_dom_name(ce_it[g]))
      ce_w("\n" as *u8)
      g = g + 1
  }
  sys_close(ce_fd)
  ce_fd = 1
358
  cax_puts("=== CAPGRAPH-EDGES: prerequisite edges MEASURED from the import closure ===\n" as *u8)
  cax_kv("domains" as *u8, ce_ndom)
  cax_kv("owned_modules" as *u8, ce_nown)
  cax_kv("sources_scanned" as *u8, ce_scanned)
  cax_kv("non_source_rows" as *u8, ce_nonnx)
  cax_kv("alt_root_resolved" as *u8, ce_altres)
  cax_puts("\n" as *u8)
  // A resolver that silently absorbs TWO path conventions makes the corpus drift INVISIBLE -- the
  // exact "papers over the defect" pattern this arc keeps finding. Robust resolution is right; hiding
  // WHICH root won is not. Two nonzero buckets = the matrices disagree about how to write a path.
  cax_kv("resolved_via_buildroot" as *u8, ce_res_bld)
  cax_kv("resolved_via_serving_root" as *u8, ce_res_srv)
  cax_kv("resolved_via_basename_search" as *u8, ce_res_base)
  var conv: i64 = 0
  if ce_res_bld > 0 { conv = conv + 1 }
  if ce_res_srv > 0 { conv = conv + 1 }
  if ce_res_base > 0 { conv = conv + 1 }
  if conv > 1 {
      cax_puts("\n  ⚠PATH-CONVENTION DRIFT: the matrices do NOT agree on how to write a source path.\n" as *u8)
      cax_puts("   Resolution succeeds anyway, which is precisely why this must be REPORTED and not\n" as *u8)
      cax_puts("   absorbed -- a tolerant reader is how a corpus drifts apart without anyone noticing.\n" as *u8)
  }
  cax_kv("sources_missing" as *u8, ce_missing)
  cax_kv("shared_modules" as *u8, ce_ambig)
  cax_kv("domain_edges" as *u8, ce_ne)
  cax_kv("infra_edges" as *u8, ce_nie)
  cax_kv("transitive_mode" as *u8, ce_trans)
  cax_kv("depth" as *u8, ce_maxdepth)
  if ce_depthsrc == 1 { cax_puts("(from capgraph.conf) " as *u8) }
  else { cax_puts("(FALLBACK -- capgraph.conf absent, run --depthscan then set it) " as *u8) }
  cax_kv("edges_found_via_infra" as *u8, ce_transedges)
  cax_puts("\n" as *u8)
  let seen_tot: i64 = ce_nenc
  let seen_own: i64 = ce_enc_owned()
  var cov_permil: i64 = 0
  if seen_tot > 0 { cov_permil = seen_own * 1000 / seen_tot }
  cax_kv("modules_touched" as *u8, seen_tot)
  cax_kv("owned_by_a_domain" as *u8, seen_own)
  cax_kv("ownership_coverage_permil" as *u8, cov_permil)
  cax_puts("<- THE REAL BOUND: an UNOWNED module is where dependency info dies\n" as *u8)
399
  // Turn the coverage debt from "add 548 rows" into a RANKED worklist. An unowned module imported many
  // times is carrying the most invisible dependency; claiming it in a matrix converts the most surface
  // per row. This is the cheapest possible ordering of a pure-content task, and it is measured.
  var substrate: i64 = 0
  var sz: i64 = 0
  while sz < ce_nenc {
      if ce_encown[sz] == 0 {
          if ce_encdom[sz] == CE_SHARED { substrate = substrate + 1 }
      }
      sz = sz + 1
  }
  cax_kv("unowned_SUBSTRATE" as *u8, substrate)
  cax_puts("(imported by MANY domains -- leave unowned; claiming one would fabricate edges to all)\n" as *u8)
  cax_puts("\n-- CLAIM THESE FIRST: unowned modules imported by EXACTLY ONE domain --\n" as *u8)
  cax_puts("   single-domain => unambiguously that domain's to claim, so a matrix row here is SAFE and\n" as *u8)
  cax_puts("   converts invisible surface into measurable edges. Ranked by import hits.\n\n" as *u8)
  let picked: *i64 = sys_mmap(CE_MAXOWN * 8 + 64) as *i64
  var pz: i64 = 0
  while pz < ce_nenc {
      picked[pz] = 0
      pz = pz + 1
  }
  var pshown: i64 = 0
  while pshown < 15 {
      var pb: i64 = 0 - 1
      var pi: i64 = 0
      while pi < ce_nenc {
          if picked[pi] == 0 {
              if ce_encown[pi] == 0 {
                  if ce_encdom[pi] >= 0 {
                      if pb < 0 { pb = pi }
                      else { if ce_enccnt[pi] > ce_enccnt[pb] { pb = pi } }
                  }
              }
          }
          pi = pi + 1
      }
      if pb < 0 { pshown = 15 }
      else {
          picked[pb] = 1
          cax_puts("  " as *u8)
          cax_puts(((ce_enc as i64) + pb * CE_NAMEW) as *u8)
          cax_puts("  " as *u8)
          cax_kv("import_hits" as *u8, ce_enccnt[pb])
          cax_puts("claim_for=" as *u8)
          cax_puts(ce_dom_name(ce_encdom[pb]))
          cax_puts("\n" as *u8)
          pshown = pshown + 1
      }
  }
  cax_puts("\n" as *u8)
  var p: i64 = 0
  while p < ce_ne {
      cax_puts("  " as *u8)
      cax_puts(ce_dom_name(ce_ef[p]))
      cax_puts(" > " as *u8)
      cax_puts(ce_dom_name(ce_et[p]))
      cax_puts("\n" as *u8)
      p = p + 1
  }
  cax_puts("\nwrote " as *u8)
  cax_puts(outp)
  cax_puts("\nenvelope: ownership=matrix field2 (_ABSENT_ rows skipped) dependency=import lines;\n" as *u8)
  cax_puts("  modules claimed by >1 domain are SHARED INFRA and derive NO edge (deterministic by\n" as *u8)
  cax_puts("  construction, under-counts rather than fabricates); coverage bounded by matrix completeness.\n" as *u8)
  return 0
466}
nx_capgraph_edges.nx source

`nx_capgraph_edges.nx` source
