@sigloch/se-engine 1.0.0

package/dist/topology.js

@@ -0,0 +1,383 @@
+/** Locale-independent id order — the canonical walk order of every primitive here. */
+const byIdCanonical = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Build adjacency maps from a graph. Traces referencing unknown nodes are
+ * dropped. `nodeWeight` (e.g. LOC per node, see layer.ts `weightNodes`) sets
+ * node masses; edge weight = mean of endpoint masses.
+ *
+ * ORDER-INVARIANT (CR-SM-240): `nodes` and every neighbour set come back in
+ * canonical id order, so the SAME graph in a different element/trace order
+ * yields a bit-identical Adjacency — and therefore bit-identical metrics.
+ */
+export function buildAdjacency(graph, nodeWeight) {
+    // CR-SM-240: CANONICAL order, not the caller's element order. Every primitive
+    // in this file walks `nodes` and the neighbour sets, so the caller's ordering
+    // used to leak into (a) the community ids and the CNM tie-break — moving
+    // `modifiability` and `coherence` by ~1e-2 on a real graph — and (b) the float
+    // summation order of degrees/betweenness, worth ~1e-15 in `scalability`.
+    // Sorting HERE fixes both at the single place where the order enters, instead
+    // of at each of the five consumers.
+    //
+    // Plain `<`/`>` on purpose, NOT `localeCompare`: the comparison must not depend
+    // on the runtime's locale — an invariant that holds only on the developer's
+    // machine is not an invariant.
+    const nodes = graph.elements.map((e) => e.id).sort(byIdCanonical);
+    const known = new Set(nodes);
+    const undirected = new Map();
+    const out = new Map();
+    const inn = new Map();
+    const w = new Map();
+    const mass = new Map(nodes.map((id) => [id, nodeWeight?.get(id) ?? 1]));
+    for (const id of nodes) {
+        undirected.set(id, new Set());
+        out.set(id, new Set());
+        inn.set(id, new Set());
+        w.set(id, new Map());
+    }
+    for (const t of graph.traces) {
+        if (!known.has(t.source) || !known.has(t.target) || t.source === t.target)
+            continue;
+        out.get(t.source).add(t.target);
+        inn.get(t.target).add(t.source);
+        undirected.get(t.source).add(t.target);
+        undirected.get(t.target).add(t.source);
+        const ew = (mass.get(t.source) + mass.get(t.target)) / 2;
+        w.get(t.source).set(t.target, ew);
+        w.get(t.target).set(t.source, ew);
+    }
+    // The sets were filled in TRACE order; re-lay them in canonical id order so the
+    // neighbour walks (BFS in betweenness, the CNM aggregate build) are invariant too.
+    // Sorting only `nodes` would leave the second half of the leak open.
+    for (const id of nodes) {
+        undirected.set(id, new Set([...undirected.get(id)].sort(byIdCanonical)));
+        out.set(id, new Set([...out.get(id)].sort(byIdCanonical)));
+        inn.set(id, new Set([...inn.get(id)].sort(byIdCanonical)));
+    }
+    return { nodes, undirected, out, in: inn, w, mass };
+}
+/**
+ * Betweenness centrality (Brandes' algorithm, unweighted undirected), normalized
+ * to [0,1] by the number of ordered node pairs (n-1)(n-2). Returns 0 for all
+ * nodes when n < 3. Higher = more of the shortest paths route through the node
+ * (structural bottleneck).
+ *
+ * CR-SM-228: index-based typed arrays instead of a fresh Map<string,X> per BFS
+ * source. The algorithm and its output are unchanged (bit-identical to the
+ * prior Map-based version) -- only the per-source scratch state changes from
+ * "allocate 4 new Maps" (O(V) allocation repeated V times = O(V^2) overhead
+ * on top of Brandes' own O(V*E), dominant on sparse graphs) to "reset 4
+ * preallocated typed arrays via .fill()" (same O(V) work, without the
+ * allocation/hashing cost). Measured A/B (1910-node graph, 3915 edges,
+ * cloned from graphcode's own SSOT):
+ *   OLD per-source Map allocation : ~610 ms
+ *   NEW indexed typed arrays      : ~93 ms   (6.6x faster, max diff 0)
+ * Root cause + measurement: sigloch-modules/docs/cr/open/CR-SM-228-*.md.
+ */
+export function betweenness(adj) {
+    const { nodes, undirected } = adj;
+    const n = nodes.length;
+    const cb = new Map(nodes.map((id) => [id, 0]));
+    if (n < 3)
+        return cb;
+    const indexOf = new Map(nodes.map((id, i) => [id, i]));
+    // Neighbour lists as index arrays, built once (not per BFS source).
+    const neighbours = nodes.map((id) => Int32Array.from(undirected.get(id), (w) => indexOf.get(w)));
+    const dist = new Int32Array(n);
+    const sigma = new Float64Array(n);
+    const delta = new Float64Array(n);
+    const queue = new Int32Array(n);
+    const stack = new Int32Array(n);
+    const cbArr = new Float64Array(n);
+    // Predecessor lists, reused across sources (length reset to 0, not reallocated).
+    const pred = Array.from({ length: n }, () => []);
+    for (let s = 0; s < n; s++) {
+        dist.fill(-1);
+        sigma.fill(0);
+        delta.fill(0);
+        for (let i = 0; i < n; i++)
+            pred[i].length = 0;
+        dist[s] = 0;
+        sigma[s] = 1;
+        let qHead = 0;
+        let qTail = 0;
+        let sTop = 0;
+        queue[qTail++] = s;
+        while (qHead < qTail) {
+            const v = queue[qHead++];
+            stack[sTop++] = v;
+            const dv = dist[v];
+            for (const w2 of neighbours[v]) {
+                if (dist[w2] < 0) {
+                    dist[w2] = dv + 1;
+                    queue[qTail++] = w2;
+                }
+                if (dist[w2] === dv + 1) {
+                    sigma[w2] += sigma[v];
+                    pred[w2].push(v);
+                }
+            }
+        }
+        while (sTop > 0) {
+            const w2 = stack[--sTop];
+            for (const v of pred[w2]) {
+                delta[v] += (sigma[v] / sigma[w2]) * (1 + delta[w2]);
+            }
+            if (w2 !== s)
+                cbArr[w2] += delta[w2];
+        }
+    }
+    // Each shortest path counted twice on an undirected graph → divide by 2,
+    // then normalize by the number of ordered pairs (n-1)(n-2).
+    const norm = (n - 1) * (n - 2);
+    nodes.forEach((id, i) => cb.set(id, cbArr[i] / norm));
+    return cb;
+}
+/** Max betweenness over all nodes (the worst bottleneck), in [0,1]. */
+export function maxBetweenness(adj) {
+    let max = 0;
+    for (const v of betweenness(adj).values())
+        if (v > max)
+            max = v;
+    return max;
+}
+/** Weighted degree (strength) per node and 2m (sum of strengths). */
+function degrees(adj) {
+    const deg = new Map();
+    let twoM = 0;
+    for (const id of adj.nodes) {
+        let s = 0;
+        for (const ww of adj.w.get(id).values())
+            s += ww;
+        deg.set(id, s);
+        twoM += s;
+    }
+    return { deg, twoM };
+}
+/**
+ * Newman modularity Q for a given community assignment, over weighted edges.
+ * Q = (1/2m) Σ_ij [A_ij − k_i k_j / 2m] δ(c_i,c_j) ∈ [-0.5, 1]. 0 when edgeless.
+ * Unweighted graphs (all edge weights 1) reproduce the classic unweighted Q.
+ */
+export function modularityOf(adj, community) {
+    const { nodes, undirected } = adj;
+    const { deg, twoM } = degrees(adj);
+    if (twoM === 0)
+        return 0;
+    let intra = 0; // Σ A_ij over same-community ordered pairs (= 2 × internal edge weight)
+    for (const v of nodes) {
+        for (const w2 of undirected.get(v)) {
+            if (community.get(v) === community.get(w2))
+                intra += adj.w.get(v).get(w2);
+        }
+    }
+    const sumDegByComm = new Map();
+    for (const v of nodes) {
+        const c = community.get(v);
+        sumDegByComm.set(c, (sumDegByComm.get(c) ?? 0) + deg.get(v));
+    }
+    let degTerm = 0;
+    for (const s of sumDegByComm.values())
+        degTerm += (s / twoM) * (s / twoM);
+    return intra / twoM - degTerm;
+}
+/** Newman modularity Q of the graph under greedy CNM communities. */
+export function modularityQ(adj) {
+    return modularityOf(adj, detectCommunities(adj));
+}
+/**
+ * Greedy agglomerative community detection (Clauset–Newman–Moore, weighted):
+ * start each node in its own community, repeatedly merge the edge-linked pair
+ * that most increases Q, until no merge helps. Returns node→community-id.
+ * Edgeless graph → singletons.
+ *
+ * DETERMINISM (CR-SM-240) — the claim used to be "ties broken by community-id
+ * order", which was only half true: the ids are `buildAdjacency`'s node indices,
+ * and those were the CALLER's element order. A tie then went to whoever came
+ * first in the input, so a permuted graph produced a different partition (and
+ * with it different `modifiability`/`coherence`). The ids are canonical since
+ * CR-SM-240, so the sentence now holds: `alive` iterates ascending (built 0..n-1,
+ * deletions preserve order), each `e[i]` row was filled in canonical node order,
+ * and the strict `dq > best` therefore keeps the FIRST maximum in ascending
+ * (i, k) order. The invariant lives in `buildAdjacency`; do not re-derive it here.
+ */
+export function detectCommunities(adj) {
+    const { nodes, undirected } = adj;
+    const community = new Map(nodes.map((id, i) => [id, i]));
+    const { deg, twoM } = degrees(adj);
+    if (twoM === 0)
+        return community;
+    // Incremental CNM state (CR-231): each merge selects the pair with maximum
+    // modularity gain ΔQ = 2·(e_ij − a_i·a_j), computed in O(1) from maintained
+    // aggregates instead of re-scoring the whole partition.
+    //   a[c]    = fraction of edge-endpoint weight in community c (Σ strength / 2m)
+    //   e[c][k] = fraction of edge weight between communities c and k
+    const a = new Map();
+    const members = new Map();
+    const e = new Map();
+    nodes.forEach((id, i) => {
+        a.set(i, deg.get(id) / twoM);
+        members.set(i, [id]);
+        e.set(i, new Map());
+    });
+    for (const v of nodes) {
+        const cv = community.get(v);
+        for (const w2 of undirected.get(v)) {
+            const cw = community.get(w2);
+            if (cv === cw)
+                continue;
+            const row = e.get(cv);
+            row.set(cw, (row.get(cw) ?? 0) + adj.w.get(v).get(w2) / twoM); // each direction adds w/2m → edge total w/m
+        }
+    }
+    const alive = new Set(members.keys());
+    for (;;) {
+        // Best merge = max ΔQ over adjacent community pairs (ascending id order → deterministic).
+        let best = 1e-12;
+        let bi = -1;
+        let bj = -1;
+        for (const i of alive) {
+            const ai = a.get(i);
+            for (const [k, eik] of e.get(i)) {
+                if (k <= i)
+                    continue; // unordered pair once
+                const dq = 2 * (eik - ai * a.get(k));
+                if (dq > best) {
+                    best = dq;
+                    bi = i;
+                    bj = k;
+                }
+            }
+        }
+        if (bi < 0)
+            break;
+        // Merge bj into bi (keep the lower id).
+        const ei = e.get(bi);
+        const ej = e.get(bj);
+        a.set(bi, a.get(bi) + a.get(bj));
+        for (const [k, ejk] of ej) {
+            if (k === bi)
+                continue;
+            ei.set(k, (ei.get(k) ?? 0) + ejk);
+            const ek = e.get(k);
+            ek.set(bi, (ek.get(bi) ?? 0) + ejk);
+            ek.delete(bj);
+        }
+        ei.delete(bj);
+        e.delete(bj);
+        for (const id of members.get(bj))
+            community.set(id, bi);
+        members.get(bi).push(...members.get(bj));
+        members.delete(bj);
+        a.delete(bj);
+        alive.delete(bj);
+    }
+    return community;
+}
+/** Weakly-connected components (undirected reachability), as node-id groups. */
+export function components(adj) {
+    const { nodes, undirected } = adj;
+    const seen = new Set();
+    const groups = [];
+    for (const start of nodes) {
+        if (seen.has(start))
+            continue;
+        const group = [];
+        const stack = [start];
+        seen.add(start);
+        while (stack.length) {
+            const v = stack.pop();
+            group.push(v);
+            for (const w2 of undirected.get(v))
+                if (!seen.has(w2)) {
+                    seen.add(w2);
+                    stack.push(w2);
+                }
+        }
+        groups.push(group);
+    }
+    return groups;
+}
+/** Weakly-connected component sizes (node counts). */
+export function componentSizes(adj) {
+    return components(adj).map((g) => g.length);
+}
+/**
+ * Cyclomatic redundancy density = (m − n + c) / n, where m = undirected edges,
+ * n = nodes, c = components. Counts independent cycles per node — the redundant
+ * paths that survive a single edge/node failure. 0 for a forest. Unweighted.
+ */
+export function redundancyDensity(adj) {
+    const { nodes, undirected } = adj;
+    const n = nodes.length;
+    if (n === 0)
+        return 0;
+    let m = 0;
+    for (const nb of undirected.values())
+        m += nb.size;
+    m /= 2;
+    const c = components(adj).length;
+    return (m - n + c) / n;
+}
+/**
+ * Coupling/cohesion: the fraction of edge WEIGHT that stays INSIDE a community
+ * of the given partition (vs crossing between communities). ∈ [0,1]; higher =
+ * more cohesive / less coupled. Community-based, so non-trivial on the
+ * near-bipartite, layered SE ontology graph (CR-229). 0 when edgeless.
+ */
+export function intraEdgeFraction(adj, community) {
+    const { nodes, undirected } = adj;
+    let internal = 0;
+    let total = 0;
+    for (const v of nodes) {
+        for (const w2 of undirected.get(v)) {
+            // Each undirected edge is counted twice (v→w and w→v); the ratio is unaffected.
+            const ww = adj.w.get(v).get(w2);
+            total += ww;
+            if (community.get(v) === community.get(w2))
+                internal += ww;
+        }
+    }
+    return total === 0 ? 0 : internal / total;
+}
+/**
+ * Mean shortest directed path length from sources (in-degree 0) to sinks
+ * (out-degree 0), over reachable source→sink pairs only. Returns
+ * { meanLength, reachableFraction }. When no source→sink pair is reachable,
+ * meanLength is 0 and reachableFraction is 0. Unweighted.
+ */
+export function sourceSinkPaths(adj) {
+    const { nodes, out, in: inn } = adj;
+    const sources = nodes.filter((id) => inn.get(id).size === 0 && out.get(id).size > 0);
+    const sinks = new Set(nodes.filter((id) => out.get(id).size === 0 && inn.get(id).size > 0));
+    if (sources.length === 0 || sinks.size === 0)
+        return { meanLength: 0, reachableFraction: 0 };
+    let total = 0;
+    let lengthSum = 0;
+    let reached = 0;
+    for (const s of sources) {
+        // BFS shortest directed path lengths from s.
+        const dist = new Map([[s, 0]]);
+        const queue = [s];
+        while (queue.length) {
+            const v = queue.shift();
+            for (const w2 of out.get(v)) {
+                if (!dist.has(w2)) {
+                    dist.set(w2, dist.get(v) + 1);
+                    queue.push(w2);
+                }
+            }
+        }
+        for (const sink of sinks) {
+            total += 1;
+            const d = dist.get(sink);
+            if (d !== undefined && d > 0) {
+                lengthSum += d;
+                reached += 1;
+            }
+        }
+    }
+    return {
+        meanLength: reached === 0 ? 0 : lengthSum / reached,
+        reachableFraction: total === 0 ? 0 : reached / total,
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sigloch/se-engine",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "license": "MIT",
+  "description": "SE analysis over a governed graph — metric vector, layer projection, rule apply/suggest, readiness computation",
+  "author": "sigloch-consulting",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andreassigloch/sigloch-modules.git",
+    "directory": "packages/se-engine"
+  },
+  "homepage": "https://github.com/andreassigloch/sigloch-modules#readme",
+  "bugs": {
+    "url": "https://github.com/andreassigloch/sigloch-modules/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@sigloch/contracts": ">=5 <6"
+  },
+  "devDependencies": {
+    "@sigloch/contracts": "^5.0.1"
+  }
+}