@polycode-projects/seonix 0.3.0 → 0.5.0

package/src/codegraph.mjs

@@ -1,4 +1,4 @@
-import { lookupByProseTokens } from "./prose.mjs";
+import { lookupByProseTokens, proseLayerHits } from "./prose.mjs";
 import { cosine } from "./embed.mjs";
 
 // Pure (no-network, no-fs) query logic over the typed `entities` payload that the
@@ -467,6 +467,24 @@ const PROSE_PROX_FRAC = 0.2;
 const PROSE_PROX_CAP_FRAC = 0.35;
 const PROSE_LOOKUP_LIMIT = 50; // bounds lookupByProseTokens' scan; the CAP_FRAC bounds the nudge regardless
 
+// Layered prose normalisation (opt-in via proseLayers, 2026-07-02): the prose index now carries
+// NORMALISED layers (spell-corrected / canonical-schema-term / stem / lemma) under
+// proseIndex["seonix:layers"] (built by the prose pre-pass; consumed read-only via prose.mjs's
+// proseLayerHits). Today the locate scorer matches query tokens against a module's path/symbol
+// text VERBATIM, so a task-text word that only reaches a module via its stem/lemma/canonical form
+// scores nothing. With the flag on, a query token that does NOT already match a module lexically,
+// but DOES resolve to one of that module's individuals through a normalised layer, contributes a
+// bounded, DISCOUNTED signal — weaker evidence than a verbatim match by construction (halved, then
+// the shared FRAC/CAP nudge), and, like every proximity family, it only re-ranks modules ALREADY
+// in `scored` — it never invents a zero-match candidate and never overrides an exact hit. NOT a
+// shipped default and NOT wired into any bench arm — an available lever pending its own gate
+// evidence, exactly like proseBoost/beamSearch before it.
+const PROSE_LAYER_FRAC = 0.2;      // bounded nudge — same shape/magnitude as the other proximity families …
+const PROSE_LAYER_CAP_FRAC = 0.35; //  … capped at this × the module's own base score (a nudge; hubs can't run away)
+const PROSE_LAYER_DISCOUNT = 0.5;  // a normalised-layer hit is WEAKER evidence than an exact/component token
+                                   // match — halved before the FRAC/CAP nudge, so a layer hit can never rival
+                                   // a verbatim lexical match (the "a miss beats a guess" discipline).
+
 // PLAN_SEON_TUNING.md §7.5 finding 1 / §7.6(5a) (opt-in via literalMention, 2026-07-02): the query
 // tokenizer split(/[^a-z0-9_]+/) DESTROYS a literal dotted module reference present verbatim in
 // task text — "django.utils.http" scatters into {django,utils,http}, tokens so common across
@@ -545,6 +563,27 @@ const BEAM_OVERFLOW_CAP = 4;     // near-miss safety valve size
 const BEAM_PLIES = 2;            // hops of expansion
 const BEAM_EDGE_GROUPS = [["imports"], ["calls", "callsSymbol"], ["inherits"], ["cochange"]];
 
+// ---- SPIRAL expansion (opt-in, default off; BEAM_RESEARCH.md's "fix #2/#3" made concrete) ------
+// Deterministic bounded-radius ego walk from the lexical seeds, ordered fewest-arcs-first, with a
+// degree-quantile hub gate. UNLIKE beamExpand it MAY introduce modules that had no lexical match
+// (it walks the graph from the seeds), so it can in principle lift a lexically-invisible truth into
+// top-k — the whole point. cochange is dropped (temporal-coupling noise; see the research synthesis).
+//   • spiralDepth          — max hop radius from the seeds (bounded ego expansion). Default 3.
+//   • mostDistinctiveBeams — degree-quantile gate q∈(0,1]: at each expansion step keep only the
+//                            lowest-degree ⌊q·n⌋ candidates (drop the top (1−q) hubs); q=1.0 keeps
+//                            all. Never empties the frontier (keeps ≥1 — the least-connected).
+//   • spiralNodeLimit      — emit budget: how many newly-reached nodes the spiral surfaces. Held at
+//                            12 (MID-tier digest breadth, a KNOWN-DOABLE token budget) — a fixed
+//                            budget, NOT a recall dial.
+const SPIRAL_DEPTH_DEFAULT = 3;
+const SPIRAL_NODE_LIMIT_DEFAULT = 12;
+const SPIRAL_Q_DEFAULT = 0.9;                 // mild hub pruning (drop only the densest 10%) — the centre point
+const SPIRAL_EXPAND_KINDS = ["imports", "calls", "callsSymbol", "inherits"]; // cochange dropped
+const SPIRAL_EMIT_FRAC = 0.5;                 // a newly-surfaced node's base score = maxSeed × this …
+const SPIRAL_HOP_DECAY = 0.6;                 //  … decayed by this per hop from the seeds (bounded < maxSeed, so a walked-in node never dominates rank 1)
+const SPIRAL_PROX_FRAC = 0.2;                 // an ALREADY-matched module the spiral re-reaches gets a bounded nudge …
+const SPIRAL_PROX_CAP_FRAC = 0.35;            //  … capped at this × its own score (same shape as every other proximity family)
+
 /** embedRank: per-module embeddable text — path components + defined symbol names + doc
  *  first-lines, ALL already in the graph (never re-reads source), bounded by the EMB_TEXT_*
  *  caps. Built once per graph and cached alongside the vectors in EMB_CACHE. */
@@ -667,13 +706,106 @@ function beamExpand(graph, scored, beamWidth) {
   }
 }
 
+/** SPIRAL expansion (opt-in; see the SPIRAL_* constants' comment above for the full design).
+ *  A deterministic bounded-radius ego walk from the lexical seeds (`scored`), popped
+ *  fewest-arcs-first via a min-heap keyed (hop ASC, in-graph degree ASC, id ASC), with a
+ *  degree-quantile hub gate at each expansion step. Emits up to `nodeLimit` newly-reached nodes
+ *  in pop order, scoring each seed-relative and bounded so a hub can't dominate rank 1.
+ *  CRITICAL vs beamExpand: it deliberately OMITS the `if (!baseScore.has) continue` guard, so it
+ *  MAY push modules that had NO lexical match into `scored` — the one path to breaking the lexical
+ *  ceiling. Mutates `scored` (nudges re-reached matches in place; APPENDS newly-surfaced modules).
+ *  Pure otherwise (no fs/network); deterministic total ordering throughout. */
+function spiralExpand(graph, scored, { depth = SPIRAL_DEPTH_DEFAULT, q = SPIRAL_Q_DEFAULT, nodeLimit = SPIRAL_NODE_LIMIT_DEFAULT } = {}) {
+  if (!scored.length) return;
+  const byId = new Map(scored.map((s) => [s.ind.id, s]));
+  const seeds = new Set(byId.keys());
+  let maxSeed = 0;
+  for (const s of scored) maxSeed = Math.max(maxSeed, s.score);
+  if (!(maxSeed > 0)) return;
+  // Combined undirected adjacency over the expansion kinds (cochange dropped). In-graph degree =
+  // neighbour count over these kinds — the "arcs" the frontier orders and the quantile gate reads.
+  const adj = adjacencyForKinds(graph, SPIRAL_EXPAND_KINDS);
+  const degree = (id) => (adj.get(id)?.size || 0);
+  // Binary min-heap over the frontier, keyed (hop ASC, degree ASC, id ASC) — pop the closest,
+  // least-connected node first, so expansion fans through the sparse surroundings and fizzles at
+  // hubs. The id tiebreak makes the order a deterministic total order (no RNG, no insertion bias).
+  const heap = [];
+  const less = (a, b) => a.hop !== b.hop ? a.hop < b.hop
+    : a.deg !== b.deg ? a.deg < b.deg
+    : a.id < b.id;
+  const swap = (i, j) => { const t = heap[i]; heap[i] = heap[j]; heap[j] = t; };
+  const push = (node) => {
+    heap.push(node);
+    let i = heap.length - 1;
+    while (i > 0) { const p = (i - 1) >> 1; if (less(heap[i], heap[p])) { swap(i, p); i = p; } else break; }
+  };
+  const pop = () => {
+    const top = heap[0];
+    const last = heap.pop();
+    if (heap.length) {
+      heap[0] = last;
+      let i = 0;
+      for (;;) {
+        const l = 2 * i + 1, r = 2 * i + 2; let m = i;
+        if (l < heap.length && less(heap[l], heap[m])) m = l;
+        if (r < heap.length && less(heap[r], heap[m])) m = r;
+        if (m === i) break;
+        swap(i, m); i = m;
+      }
+    }
+    return top;
+  };
+  const visited = new Set(seeds);
+  for (const id of seeds) push({ id, hop: 0, deg: degree(id) });
+  const defIdx = definesIndex(graph);
+  let emitted = 0;
+  while (heap.length && emitted < nodeLimit) {
+    const node = pop();
+    if (!seeds.has(node.id)) {
+      // Slot this newly-reached node: seed-relative base, hop-decayed and bounded below maxSeed.
+      const emitScore = maxSeed * SPIRAL_EMIT_FRAC * Math.pow(SPIRAL_HOP_DECAY, node.hop - 1);
+      const existing = byId.get(node.id);
+      if (existing) { // already lexically matched (below-k) → bounded nudge, never a replacement
+        existing.score += Math.min(emitScore * SPIRAL_PROX_FRAC, existing.score * SPIRAL_PROX_CAP_FRAC);
+      } else { // lexically INVISIBLE → introduce it (the beam structurally cannot)
+        const ind = graph.byId?.get?.(node.id);
+        if (ind && (ind.class || "") === "Module") {
+          const defines = defIdx.get(ind.id) || [];
+          const entry = { ind, score: emitScore, defineCount: defines.length, matching: [], density: 0 };
+          scored.push(entry);
+          byId.set(node.id, entry);
+        }
+      }
+      emitted++;
+    }
+    if (node.hop >= depth) continue;
+    // This step's candidate set = the popped node's unvisited MODULE neighbours; quantile-gate by
+    // degree, keeping the lowest-degree ⌊q·n⌋ (drop the densest hubs), never fewer than one.
+    const cands = [];
+    for (const nid of adj.get(node.id) || []) {
+      if (visited.has(nid)) continue;
+      const ind = graph.byId?.get?.(nid);
+      if (!ind || (ind.class || "") !== "Module") continue; // no phantom (fn-fallback) module ids
+      cands.push({ id: nid, deg: degree(nid) });
+    }
+    if (!cands.length) continue;
+    cands.sort((a, b) => a.deg - b.deg || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const keep = Math.max(1, Math.floor(q * cands.length)); // lowest-degree q-fraction; never empty
+    for (let i = 0; i < keep; i++) {
+      const c = cands[i];
+      visited.add(c.id);
+      push({ id: c.id, hop: node.hop + 1, deg: c.deg });
+    }
+  }
+}
+
 /** The shared module-ranking core behind renderSearch (text) and searchModulesRanked (path+score).
  *  IDF-weights each query token by rarity across modules (so a whole-problem-statement query is not
  *  swamped by ubiquitous words like template/filter/value), scores path-component + symbol-component
  *  + EXACT-symbol matches, re-ranks with a bounded import-proximity bonus, and breaks ties by
  *  matched-symbol DENSITY (a concrete signal — never ground truth). Pure; deterministic. */
 function scoreModules(graph, tokens, opts = {}) {
-  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, proseBoost = false, literalMention = false, embedRank = false, rawQuery = "" } = opts;
+  const { demoteNonProd = false, callAdjacency = false, implOfInterface = false, beamSearch = false, spiral = false, proseBoost = false, proseLayers = false, literalMention = false, embedRank = false, rawQuery = "" } = opts;
   const beamWidth = Number.isFinite(opts.beamWidth) && opts.beamWidth > 0 ? opts.beamWidth : 8;
   const defIdx = definesIndex(graph);
   // Precompute each module's path components + defined-symbol exact/component sets, once.
@@ -869,6 +1001,41 @@ function scoreModules(graph, tokens, opts = {}) {
       }
     }
   }
+  // Layered prose normalisation (opt-in): a query token that did NOT match a module lexically but
+  // resolves to one of its individuals through a NORMALISED prose layer (stem/lemma/canonical/spell)
+  // adds a bounded, discounted signal — see the PROSE_LAYER_* comment above. One proseLayerHits call
+  // per DISTINCT query token, ids folded to their containing module via moduleIdOfId (same as the
+  // proseBoost/call-adjacency families). Only tokens NOT already matching a module lexically count
+  // for that module (a layer hit is purely ADDITIVE evidence for otherwise-missed words — never
+  // double-counting a token the base score already saw), weighted by the token's own IDF (so a
+  // ubiquitous word contributes almost nothing) and halved (PROSE_LAYER_DISCOUNT: weaker than a
+  // verbatim match), then the shared FRAC/CAP nudge. Only re-ranks modules already in `scored`.
+  if (proseLayers && scored.length && graph.proseIndex) {
+    const scoredById = new Map(scored.map((s) => [s.ind.id, s]));
+    const modById = new Map(modules.map((m) => [m.ind.id, m]));
+    const layerSignal = new Map(); // moduleId -> accumulated discounted, IDF-weighted layer signal
+    for (const t of new Set(tokens)) {
+      const w = idf.get(t) || 0;
+      if (!w) continue;
+      const { ids } = proseLayerHits(graph.proseIndex, t);
+      if (!ids.length) continue;
+      const hitMods = new Set();
+      for (const id of ids) {
+        const modId = moduleIdOfId(graph, id);
+        if (!modId || hitMods.has(modId)) continue;
+        hitMods.add(modId);
+        if (!scoredById.has(modId)) continue;              // never a new zero-match candidate
+        const m = modById.get(modId);
+        if (m && (m.symSet.has(t) || m.symComps.has(t) || m.labelLc.includes(t))) continue; // already matched lexically → not additive
+        layerSignal.set(modId, (layerSignal.get(modId) || 0) + w * PROSE_LAYER_DISCOUNT);
+      }
+    }
+    for (const s of scored) {
+      const signal = layerSignal.get(s.ind.id) || 0;
+      if (!signal) continue;
+      s.score += Math.min(signal * PROSE_LAYER_FRAC, s.score * PROSE_LAYER_CAP_FRAC);
+    }
+  }
   // §7.6(5b) embedRank (opt-in): static-embedding cosine re-rank — see the EMB_* constants'
   // comment above. The embedder is INJECTED (opts.embedder, from embed.mjs's loadEmbedder) so
   // this module stays fs-free; absent embedder → no-op with a one-time stderr note, never a
@@ -903,6 +1070,14 @@ function scoreModules(graph, tokens, opts = {}) {
   }
   // §5.15 beam search (opt-in): multi-ply generalization of the single-hop families above.
   if (beamSearch && scored.length > 1) beamExpand(graph, scored, beamWidth);
+  // SPIRAL (opt-in): bounded-radius ego walk that MAY introduce lexically-invisible modules — runs
+  // last (after every family has finalised the seed scores) so its seed-relative emit scores and
+  // hub gate read the settled ranking, and before the sort so surfaced nodes slot into it.
+  if (spiral && scored.length) spiralExpand(graph, scored, {
+    depth: Number.isFinite(opts.spiralDepth) && opts.spiralDepth > 0 ? opts.spiralDepth : SPIRAL_DEPTH_DEFAULT,
+    q: Number.isFinite(opts.mostDistinctiveBeams) && opts.mostDistinctiveBeams > 0 ? opts.mostDistinctiveBeams : SPIRAL_Q_DEFAULT,
+    nodeLimit: Number.isFinite(opts.spiralNodeLimit) && opts.spiralNodeLimit > 0 ? opts.spiralNodeLimit : SPIRAL_NODE_LIMIT_DEFAULT,
+  });
   // Tie-break: score → matched-symbol DENSITY (concrete, not ground truth) → fewer defines → shorter label.
   scored.sort((a, b) => b.score - a.score || b.density - a.density || a.defineCount - b.defineCount || String(a.ind.label).length - String(b.ind.label).length);
   return scored;

package/src/nlp-bundle.mjs

@@ -0,0 +1,120 @@
+// nlp-bundle.mjs — package wink-nlp + wink-eng-lite-web-model into ONE browser
+// IIFE that self-registers `window.__seonixNlp = {lemma, posTags}`, the same
+// adapter shape ask-nlp.mjs builds for Node. It is the browser path for the
+// viewer's lemma/POS tier (operator override of the earlier "CLI-only" call).
+//
+// WHY a hand-rolled packager and not a bundler: both packages are pure CJS with
+// ONLY static `require('./relative')` calls and NO Node built-ins (verified), so
+// a ~40-line CommonJS-in-the-browser shim that walks the require graph, wraps each
+// file in a module factory, and emits a tiny `require` closure is enough — no
+// esbuild/rollup dependency, in keeping with the repo's lean-deps rule. The model
+// data files are JSON `require`s, inlined as `module.exports=<json>`.
+//
+// BOUNDARY (mirrors ask-nlp.mjs's): this bundle is used ONLY by the SITE build
+// (viz --data-out --nlp writes it as a same-origin sibling the page lazy-loads)
+// or by an explicit `viz --nlp` on a portable file (inlined). The default local
+// single-file viewer never includes it and keeps its no-external-fetch guarantee.
+// The wink model self-loads via the browser `atob` global (it is a WEB model);
+// nothing here touches the DOM, fs, or the network.
+//
+// The lemma/posTags bodies below MIRROR ask-nlp.mjs's Node adapter deliberately;
+// nlp-bundle.test.mjs pins output parity between the two so they can't drift.
+
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+
+// Every internal require in these two packages is a static string literal (checked
+// against the shipped versions); a lexical scan is therefore exact enough to build
+// the graph, and any request that fails to resolve throws loudly rather than
+// silently dropping a module.
+const REQUIRE_RE = /require\(\s*(['"])([^'"]+)\1\s*\)/g;
+
+/** Walk the CJS require graph from `entries` (bare package specifiers), reading
+ *  every reachable .js/.json file, and return {order, deps, idOf, entryPaths}. */
+async function packGraph(entries, fromUrl) {
+  const rootReq = createRequire(fromUrl);
+  const idOf = new Map(); // absPath -> integer id (stable, discovery order)
+  const order = []; // absPath[]
+  const deps = new Map(); // absPath -> { request -> absPath }
+  const isJson = (p) => p.endsWith(".json");
+  const assign = (p) => { if (!idOf.has(p)) { idOf.set(p, idOf.size); order.push(p); } };
+
+  async function walk(absPath) {
+    if (deps.has(absPath)) return; // visited (also breaks require cycles)
+    deps.set(absPath, {});
+    assign(absPath);
+    if (isJson(absPath)) return; // data leaf, no requires
+    const src = await readFile(absPath, "utf8");
+    const localReq = createRequire(absPath);
+    const map = {};
+    REQUIRE_RE.lastIndex = 0;
+    for (let m; (m = REQUIRE_RE.exec(src)); ) {
+      const request = m[2];
+      map[request] = localReq.resolve(request); // throws if unresolvable — loud by design
+    }
+    deps.set(absPath, map);
+    for (const target of Object.values(map)) await walk(target);
+  }
+
+  const entryPaths = entries.map((e) => rootReq.resolve(e));
+  for (const e of entryPaths) await walk(e);
+  return { order, deps, idOf, entryPaths };
+}
+
+/** The adapter body — JS source, MIRRORS ask-nlp.mjs's lemma/posTags. `nlp`/`its`
+ *  are in scope from the IIFE. Self-registers on window|self|globalThis. */
+const ADAPTER_JS = `
+var G=(typeof window!=='undefined')?window:(typeof self!=='undefined')?self:globalThis;
+G.__seonixNlp={
+  lemma:function(word){
+    var w=String(word||'');
+    try{var out=nlp.readDoc(w).tokens().out(its.lemma);return String(out[0]||w).toLowerCase();}
+    catch(e){return w.toLowerCase();}
+  },
+  posTags:function(words){
+    try{
+      var toks=nlp.readDoc(words.join(' ')).tokens();
+      var texts=toks.out(),tags=toks.out(its.pos),out=[],k=0;
+      for(var i=0;i<words.length;i++){
+        var w=words[i];
+        if(k>=texts.length){out.push(null);continue;}
+        out.push(tags[k]);
+        var acc=texts[k];k++;
+        while(acc.length<w.length&&k<texts.length){acc+=texts[k];k++;}
+      }
+      return out;
+    }catch(e){return words.map(function(){return null;});}
+  }
+};`;
+
+/** Build the self-contained browser IIFE (a plain JS string, no <script> wrapper).
+ *  Loading it in a browser sets window.__seonixNlp. Pure w.r.t. installed deps. */
+export async function winkBrowserBundle() {
+  const { order, deps, idOf, entryPaths } = await packGraph(
+    ["wink-nlp", "wink-eng-lite-web-model"],
+    import.meta.url,
+  );
+  const D = {}; // id -> {request -> id}
+  for (const [p, map] of deps) {
+    const from = idOf.get(p);
+    D[from] = {};
+    for (const [req, target] of Object.entries(map)) D[from][req] = idOf.get(target);
+  }
+  const parts = [];
+  parts.push("(function(){\nvar M={},C={};");
+  parts.push("function R(id){if(C[id])return C[id].exports;var m=C[id]={exports:{}};M[id](m,m.exports,function(r){return R(D[id][r]);});return m.exports;}");
+  parts.push("var D=" + JSON.stringify(D) + ";");
+  for (const p of order) {
+    const id = idOf.get(p);
+    const src = await readFile(p, "utf8");
+    parts.push(p.endsWith(".json")
+      ? "M[" + id + "]=function(module,exports,require){module.exports=" + src + "\n};"
+      : "M[" + id + "]=function(module,exports,require){\n" + src + "\n};");
+  }
+  parts.push("var winkNLP=R(" + idOf.get(entryPaths[0]) + ");");
+  parts.push("var model=R(" + idOf.get(entryPaths[1]) + ");");
+  parts.push("var nlp=winkNLP(model),its=nlp.its;");
+  parts.push(ADAPTER_JS);
+  parts.push("})();");
+  return parts.join("\n");
+}

package/src/prose.mjs

@@ -143,3 +143,45 @@ export function lookupByProseTokens(proseIndex, query, { limit = 10 } = {}) {
     .slice(0, limit)
     .map(([id, score]) => ({ id, score }));
 }
+
+/** OPT-IN read accessor for codegraph.mjs's `proseLayers` locate signal (this file's index
+ *  build is unchanged — this only READS the layers the pre-pass already wrote). Given a query
+ *  `token`, return the individual ids reachable through the NORMALISED prose layers
+ *  (spell-corrected / canonical-schema-term / stem / lemma) stored under
+ *  `proseIndex["seonix:layers"]` — the same normalised layers ask.mjs's resolveObject consults,
+ *  here surfaced for the locate SCORER so a task-text word that only overlaps a module via a
+ *  normalised form still resolves.
+ *
+ *  Layer shape consumed (an inverted index keyed by the NORMALISED token, mirroring the verbatim
+ *  top level, just normalised):
+ *    proseIndex["seonix:layers"] = { <layerName>: { <normalisedToken>: [id, …] }, … }
+ *  A posting may be a plain id array or `{ ids: [...] }` — both are tolerated. The raw query
+ *  token is looked up directly against every layer's keys, so a token whose surface form is
+ *  already a canonical/stem/lemma/spell-corrected key hits; the accessor never itself normalises
+ *  the query (it owns no normaliser — those live in the concurrent ask/prose-nlp surface), so it
+ *  can never disagree with the build's normalisation, only under-fire safely.
+ *
+ *  Returns { ids, via }: `ids` a deduped, sorted (stable/deterministic) id list; `via` the
+ *  sorted layer names that produced them, joined with "+", for a scorer's provenance — or null
+ *  when nothing hit. Absent / malformed / pre-layers `proseIndex` → { ids: [], via: null }: a
+ *  safe no-op, so the opt-in flag degrades to nothing on a graph indexed before layers existed.
+ *  Accepts either a `proseIndex` object or a parsed graph (reads its `.proseIndex`). */
+export function proseLayerHits(proseIndex, token) {
+  const src = proseIndex && (proseIndex["seonix:layers"] ? proseIndex : proseIndex.proseIndex);
+  const layers = src && src["seonix:layers"];
+  const t = String(token || "").toLowerCase();
+  const empty = { ids: [], via: null };
+  if (!t || !layers || typeof layers !== "object") return empty;
+  const ids = new Set();
+  const via = new Set();
+  for (const name of Object.keys(layers)) {
+    const layer = layers[name];
+    if (!layer || typeof layer !== "object") continue;
+    const posting = layer[t];
+    const list = Array.isArray(posting) ? posting : Array.isArray(posting?.ids) ? posting.ids : null;
+    if (!list?.length) continue;
+    for (const id of list) ids.add(id);
+    via.add(name);
+  }
+  return ids.size ? { ids: [...ids].sort(), via: [...via].sort().join("+") } : empty;
+}

package/src/temporal.mjs

@@ -557,3 +557,73 @@ export function decodeViewState(search) {
   }
   return out;
 }
+
+// ---- P4: cross-repo awareness ------------------------------------------------------
+// A merged multi-repo index (extract.mjs indexRepositories) prefixes every module id
+// with the repo's directory basename: `mod:<repo>/<path>`, `fn:<repo>/<path>#sym`.
+// Commit individuals are NOT prefixed (one Commit per sha, shared across clones), so a
+// commit's repo is inferred from the prefixes of the modules it touched. These three
+// pure helpers are the shared, node-tested core the timeline (timeline.mjs) and the
+// temporal browser (browser.mjs) both use to become repo-aware WITHOUT a top-level
+// marker at index time. A single-repo graph never trips the detector, so its timeline
+// and temporal-graph output stay byte-identical to the pre-P4 pipeline.
+
+/**
+ * First path component of a prefixed id (`mod:<repo>/<rest>` → `<repo>`), or null when
+ * the id has no `/` after its `type:` prefix (an unprefixed single-repo id such as
+ * `mod:a.py`). Cheap, deterministic; the atom the repo detector counts.
+ * @param {string} id
+ * @returns {string|null}
+ */
+export function repoOfId(id) {
+  const m = String(id).match(/^[a-z]+:([^#]+)/);
+  if (!m) return null;
+  const slash = m[1].indexOf("/");
+  return slash > 0 ? m[1].slice(0, slash) : null;
+}
+
+/**
+ * Attribute one commit to a repo given a `Map<prefix, touchCount>` of the modules it
+ * touched: the majority prefix wins, ties break lexicographically, an empty map → null
+ * (touched nothing tracked). This is how a commit that touches modules from >1 repo
+ * (only possible when two clones share a sha, since git history is per-repo) is
+ * attributed — to the repo it touched most, deterministically.
+ * @param {Map<string, number>} counts
+ * @returns {string|null}
+ */
+export function assignRepo(counts) {
+  let best = null;
+  let bestN = -1;
+  for (const p of [...counts.keys()].sort()) {
+    const n = counts.get(p);
+    if (n > bestN) { best = p; bestN = n; }
+  }
+  return best;
+}
+
+/**
+ * Decide whether a graph is a merged multi-repo index from its commits' touched-module
+ * prefixes. `commitPrefixCounts` is one `Map<prefix,count>` per commit. A graph reads
+ * as multi-repo iff ≥2 distinct prefixes each appear as the SOLE prefix of some commit
+ * AND commits confined to a single prefix are at least as many as cross-prefix commits.
+ * Rationale: a real git history is per-repo, so a genuine merge has each commit land in
+ * exactly one repo; a single monorepo's commits routinely span several top-level dirs,
+ * so the "majority stay confined + ≥2 sole prefixes" test never fires for it — that is
+ * what keeps single-repo output byte-identical. (A monorepo whose every commit happens
+ * to stay within one top-level dir is the one documented ambiguity; it degrades
+ * gracefully to repo-tagged rendering, it does not error.)
+ * @param {Array<Map<string, number>>} commitPrefixCounts
+ * @returns {boolean}
+ */
+export function isMultiRepo(commitPrefixCounts) {
+  let pure = 0;
+  let cross = 0;
+  const sole = new Set();
+  for (const counts of commitPrefixCounts) {
+    const keys = [...counts.keys()];
+    if (!keys.length) continue;
+    if (keys.length === 1) { pure += 1; sole.add(keys[0]); }
+    else cross += 1;
+  }
+  return sole.size >= 2 && pure >= cross;
+}

package/src/timeline.mjs

@@ -10,6 +10,8 @@
 // timeline as `type:"session"` entries at their started timestamp — a graph with
 // zero sessions renders exactly as before.
 
+import { repoOfId, assignRepo, isMultiRepo } from "./temporal.mjs";
+
 const esc = (s) =>
   String(s == null ? "" : s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
 
@@ -17,12 +19,19 @@ export function extractTimeline(graph) {
   const commits = [];
   const sessions = [];
   const churnByShort = new Map(); // short sha -> modules touched
+  const prefixByShort = new Map(); // short sha -> Map<repoPrefix, modules touched> (multi-repo)
   for (const ind of graph.individuals || []) {
     const attr = (key) => ind.attributes?.find((a) => a.key === key)?.value || "";
     if (ind.class === "Module") {
+      const prefix = repoOfId(ind.id);
       for (const ref of ind.derived_from || []) {
         const short = ref.replace(/^git:/, "");
         churnByShort.set(short, (churnByShort.get(short) || 0) + 1);
+        if (prefix) {
+          let m = prefixByShort.get(short);
+          if (!m) { m = new Map(); prefixByShort.set(short, m); }
+          m.set(prefix, (m.get(prefix) || 0) + 1);
+        }
       }
     } else if (ind.class === "Commit") {
       commits.push({
@@ -45,11 +54,27 @@ export function extractTimeline(graph) {
     }
   }
   for (const c of commits) c.touched = churnByShort.get(c.short) || 0;
+  // P4 cross-repo: on a MERGED multi-repo graph, tag every commit with the repo it
+  // belongs to (inferred from its touched modules' id prefixes) so the render can group
+  // by repo on a single global time axis. Single-repo graphs never trip isMultiRepo, so
+  // no `repo` key is added and the output stays byte-identical to before.
+  if (isMultiRepo(commits.map((c) => prefixByShort.get(c.short) || new Map()))) {
+    for (const c of commits) {
+      const r = assignRepo(prefixByShort.get(c.short) || new Map());
+      if (r) c.repo = r;
+    }
+  }
   const entries = [...commits, ...sessions];
   entries.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
   return entries;
 }
 
+// Per-repo badge palette (multi-repo timelines only) — hues distinct from the default
+// commit-bar blue (#3d59a1) and the session amber (#e0af68); assigned by sorted repo
+// order so a repo's colour is stable across renders.
+const REPO_PALETTE = ["#7aa2f7", "#9ece6a", "#bb9af7", "#f7768e", "#2ac3de", "#ff9e64", "#73daca", "#e0af68"];
+const repoColorMap = (repos) => new Map(repos.map((r, i) => [r, REPO_PALETTE[i % REPO_PALETTE.length]]));
+
 /** `nav` is the shared {name: href} nav object the viz CLI computes from the
  *  actual sibling output paths — header links render ONLY from its entries, so
  *  a page generated without siblings never carries dead links. */
@@ -58,14 +83,26 @@ export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", ge
   const sessionCount = commits.filter((c) => c.type === "session").length;
   const commitCount = commits.length - sessionCount;
   const maxTouched = Math.max(1, ...commits.map((c) => c.touched));
+  // P4 cross-repo: extractTimeline tags each commit of a MERGED graph with its `repo`.
+  // When present, entries are labelled and colour-badged by repo on one global time
+  // axis; when absent (single-repo or zero commits) every branch below is byte-for-byte
+  // the pre-P4 render.
+  const repos = [...new Set(commits.filter((c) => c.repo).map((c) => c.repo))].sort();
+  const multi = repos.length > 0;
+  const rc = multi ? repoColorMap(repos) : null;
+  const badgeStyle = (color) => `display:inline-block;padding:0 6px;border-radius:8px;font-size:11px;font-weight:600;color:#16161e;background:${color}`;
   // Bars run oldest→newest left to right; the list reads newest first. Chat
-  // sessions are the visually distinct entries (amber, fixed-height bars).
+  // sessions are the visually distinct entries (amber, fixed-height bars). On a
+  // multi-repo timeline each commit bar is tinted with its repo colour.
   const bars = commits
-    .map((c, i) =>
-      c.type === "session"
-        ? `<a class="bar sess" href="#c${i}" title="chat session ${esc(c.short)} · ${esc(c.date.slice(0, 10))} — ${c.turns} turn(s)"><i style="height:10px"></i></a>`
-        : `<a class="bar" href="#c${i}" title="${esc(c.short)} · ${esc(c.date.slice(0, 10))} — ${esc(c.message)}"><i style="height:${Math.max(6, Math.round((c.touched / maxTouched) * 64))}px"></i></a>`,
-    )
+    .map((c, i) => {
+      if (c.type === "session") {
+        return `<a class="bar sess" href="#c${i}" title="chat session ${esc(c.short)} · ${esc(c.date.slice(0, 10))} — ${c.turns} turn(s)"><i style="height:10px"></i></a>`;
+      }
+      const barRepoTitle = multi && c.repo ? `[${esc(c.repo)}] ` : "";
+      const barRepoBg = multi && c.repo ? `;background:${rc.get(c.repo)}` : "";
+      return `<a class="bar" href="#c${i}" title="${barRepoTitle}${esc(c.short)} · ${esc(c.date.slice(0, 10))} — ${esc(c.message)}"><i style="height:${Math.max(6, Math.round((c.touched / maxTouched) * 64))}px${barRepoBg}"></i></a>`;
+    })
     .join("");
   const rows = commits
     .map((c, i) => {
@@ -75,10 +112,16 @@ export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", ge
       const sha = base
         ? `<a href="${base}/-/commit/${esc(c.sha)}" target="_blank" rel="noopener"><code>${esc(c.short)}</code></a>`
         : `<code>${esc(c.short)}</code>`;
-      return `<li id="c${i}"><span class="d">${esc(c.date.slice(0, 10))}</span> ${sha} <span class="a">${esc(c.author)}</span> <span class="m">${esc(c.message)}</span> <span class="t" title="modules touched">${c.touched}⛁</span></li>`;
+      const rowBadge = multi && c.repo ? `<span style="${badgeStyle(rc.get(c.repo))}">${esc(c.repo)}</span> ` : "";
+      return `<li id="c${i}">${rowBadge}<span class="d">${esc(c.date.slice(0, 10))}</span> ${sha} <span class="a">${esc(c.author)}</span> <span class="m">${esc(c.message)}</span> <span class="t" title="modules touched">${c.touched}⛁</span></li>`;
     })
     .reverse()
     .join("\n");
+  const repoLegend = multi
+    ? repos
+        .map((r) => `<span class="rl"><span style="display:inline-block;width:9px;height:9px;border-radius:2px;margin-right:3px;vertical-align:middle;background:${rc.get(r)}"></span>${esc(r)}</span>`)
+        .join(" ")
+    : "";
   const navLinks = nav
     ? Object.entries(nav)
         .map(([name, href]) => `<a href="${esc(href)}">${name === "home" ? "← home" : esc(name)}</a>`)
@@ -104,7 +147,7 @@ export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", ge
   li.sess{border-left:3px solid #e0af68;padding-left:5px} li.sess code,li.sess .m{color:#e0af68}
 </style></head><body>
 <header>
-  <span><b>seonix</b> commit timeline — ${commitCount} commits${sessionCount ? ` · ${sessionCount} chat session(s)` : ""}</span>
+  <span><b>seonix</b> commit timeline — ${commitCount} commits${sessionCount ? ` · ${sessionCount} chat session(s)` : ""}${multi ? ` · ${repos.length} repos` : ""}</span>${multi ? `\n  <span class="repolegend">${repoLegend}</span>` : ""}
   ${navLinks}
   ${base ? `<a href="${base}" target="_blank" rel="noopener">repository ↗</a>` : ""}
   <span class="meta">bars = modules touched per commit · generated from the seonix graph artifact${generatedAt ? ` (${esc(generatedAt.slice(0, 10))})` : ""}</span>