@polycode-projects/seonix 0.2.1 → 0.4.0

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-nlp.mjs

@@ -0,0 +1,52 @@
+// prose-nlp.mjs — the OPTIONAL wink-nlp lemma loader behind prose.mjs's LEMMA layer.
+//
+// Deliberately a SEPARATE loader from ask-nlp.mjs (same createRequire pattern, same
+// deps) rather than an import of it: ask-nlp.mjs belongs to the ask-engine surface
+// and is under active concurrent work — the prose pre-pass must not couple its
+// index-build path to that file's export shape. The ~20 duplicated lines are the
+// decoupling fee; the wink model itself is loaded lazily and at most once per
+// process either way.
+//
+// BOUNDARY (same as ask-nlp.mjs, hard): Node-only, never inlined into the viewer
+// bundle. prose.mjs is itself never inlined by viz.mjs's askSource(), so nothing
+// browser-side can reach this module. wink-nlp + wink-eng-lite-web-model are CJS —
+// loaded via createRequire, lazily, with failure cached as null: a checkout without
+// the optional deps simply builds no lemma layer (honestly absent), it never throws.
+//
+// Determinism: wink's lemmatiser is a fixed trained model with no sampling — the
+// same token always yields the same lemma across runs and processes, which is what
+// lets the lemma layer meet the "byte-identical proseIndex across builds" contract.
+
+import { createRequire } from "node:module";
+
+let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+
+/** Lazily build a `lemma(word) -> string` function, or null when wink isn't loadable.
+ *  Results are memoized per token: the layer build lemmatises each unique vocabulary
+ *  token once, not once per posting. */
+export function proseLemma() {
+  if (cached !== undefined) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    const winkNLP = require("wink-nlp");
+    const model = require("wink-eng-lite-web-model");
+    const nlp = winkNLP(model);
+    const its = nlp.its;
+    const memo = new Map();
+    cached = (word) => {
+      const w = String(word || "");
+      if (memo.has(w)) return memo.get(w);
+      let out;
+      try {
+        out = String(nlp.readDoc(w).tokens().out(its.lemma)[0] || w).toLowerCase();
+      } catch {
+        out = w.toLowerCase();
+      }
+      memo.set(w, out);
+      return out;
+    };
+  } catch {
+    cached = null;
+  }
+  return cached;
+}

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/schema-docs.mjs

@@ -49,6 +49,12 @@ export const CLASS_DOCS = Object.freeze([
     "A single recorded git commit. Carries author/date/message attributes and connects " +
     "to the Modules it touched (mgx:touchedByCommit) and, more precisely, the specific " +
     "symbols whose current source span its changed lines intersect (mgx:touchesSymbol)." },
+  { name: "Session", description:
+    "One recorded `seonix chat` session — a runtime observation, not a source " +
+    "derivation. Carries started/ended timestamps (temporal ordering, like a Commit's " +
+    "date), a turn count and the queries asked, and connects to the entities its turns " +
+    "resolved or answered with (mgx:asksAbout). Recorded under .seonix/sessions/ and " +
+    "re-attached on every re-index (sessions.mjs)." },
 ]);
 
 // ---- predicates / attributes (every `prop:` token actually emitted by buildEntities,
@@ -96,6 +102,11 @@ export const PREDICATE_DOCS = Object.freeze([
     "Module → Function/Class. A module's public-API (`__all__`) entry that re-exports a " +
     "symbol defined or imported elsewhere — answers \"where is X importable from,\" not " +
     "just \"where is X defined.\"" },
+  { prop: "mgx:asksAbout", kind: "asksAbout", description:
+    "Session → any entity. A chat session's turn resolved this entity as its subject " +
+    "or cited it in the answer — which parts of the codebase a human actually asked " +
+    "about. A runtime observation (owned term, no SEON equivalent); references that no " +
+    "longer resolve after a re-index are dropped and counted, never guessed." },
   { prop: "mgx:hasProseTokens", kind: "prose", description:
     "Individual → word tokens (an attribute, not a between-individuals edge). The " +
     "decomposed word sequence extracted from an identifier's name (camelCase/snake_case " +
@@ -120,6 +131,20 @@ export const PREDICATE_DOCS = Object.freeze([
   { prop: "mgx:value", kind: "attribute", description:
     "The literal right-hand-side value of a GlobalVariable's assignment, when the AST " +
     "extractor could capture one cheaply (a constant or simple literal)." },
+  { prop: "mgx:sessionStarted", kind: "attribute", description:
+    "A chat Session's start time, ISO-8601 — the timestamp the session enters the " +
+    "timeline at (the Session analogue of a Commit's date)." },
+  { prop: "mgx:sessionEnded", kind: "attribute", description:
+    "A chat Session's end time, ISO-8601 (the /exit, EOF, or last recorded turn)." },
+  { prop: "mgx:sessionTurns", kind: "attribute", description:
+    "How many query turns a chat Session ran (non-empty, non-/exit inputs)." },
+  { prop: "mgx:sessionQueries", kind: "attribute", description:
+    "The queries a chat Session asked, ' | '-joined and length-capped — what the " +
+    "human wanted to know, in their own words." },
+  { prop: "mgx:sessionDroppedEdges", kind: "attribute", description:
+    "How many of a Session's recorded entity references could not be re-resolved " +
+    "against the current graph (renamed/removed code) — those edges are dropped, " +
+    "never guessed, and this attribute keeps the loss honest and visible." },
   { prop: "mgx:commitAuthor", kind: "attribute", description: "A Commit's author name (git %an)." },
   { prop: "mgx:commitDate", kind: "attribute", description:
     "A Commit's author date, ISO-8601 (git %aI)." },
@@ -146,6 +171,10 @@ export const PREDICATE_DOCS = Object.freeze([
   { prop: "seon:isConstant", kind: "attribute", description:
     "An ALL_CAPS module-level GlobalVariable — a naming-convention signal, not enforced " +
     "immutability." },
+  { prop: "seon:subKind", kind: "attribute", description:
+    "The flavour of a Class define when it is not a plain class: interface, enum, struct " +
+    "or record. The graph keeps kind=class for every type declaration; this attribute " +
+    "carries the distinction." },
   { prop: "seon:hasAccessModifier", kind: "attribute", description:
     "Visibility inferred from a leading underscore (private/protected); a public member " +
     "carries no value for this attribute." },

package/src/server.mjs

@@ -90,7 +90,7 @@ export const TOOLS = [
   {
     name: "seonix_ask",
     description:
-      "Ask a structural question in plain English (e.g. \"which functions call X\") — one call, no model, replaces manual search+describe+traversal. A clean miss beats a guess.",
+      "Ask a structural question in plain English: \"which functions call X\", \"what uses X\", \"where is X defined\", \"when did X change\". One call, no model. A clean miss beats a guess.",
     inputSchema: {
       type: "object",
       required: ["query"],
@@ -394,13 +394,36 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   throw new ToolError(`unknown tool: ${name}`);
 }
 
+/** SEONIX_TOOLS (csv of tool names) narrows what the server registers AND serves —
+ *  an unlisted tool is invisible to the client and un-dispatchable, not merely
+ *  un-granted, so a permission layer that auto-denies visible-but-ungranted tools
+ *  (headless `claude -p`) has nothing to deny. Unknown names in the csv throw at
+ *  startup: a typo must fail loudly, not silently serve the full set. */
+export function resolveServedTools(env = process.env) {
+  const csv = (env.SEONIX_TOOLS || "").trim();
+  if (!csv) return TOOLS;
+  const wanted = csv.split(",").map((s) => s.trim()).filter(Boolean);
+  const byName = new Map(TOOLS.map((t) => [t.name, t]));
+  const unknown = wanted.filter((n) => !byName.has(n));
+  if (unknown.length) throw new Error(`SEONIX_TOOLS names unknown tool(s): ${unknown.join(", ")}`);
+  return wanted.map((n) => byName.get(n));
+}
+
 /** Build the MCP server (transport-agnostic — tests connect it in-memory). */
-export function buildServer({ config = loadConfig(), source = defaultSource } = {}) {
+export function buildServer({ config = loadConfig(), source = defaultSource, env = process.env } = {}) {
+  const served = resolveServedTools(env);
+  const servedNames = new Set(served.map((t) => t.name));
+  // The dispatch gate applies ONLY under an active SEONIX_TOOLS filter: unfiltered, the cold
+  // tools stay dispatchable-though-unlisted (the C4 tiered surface); filtered, EVERYTHING
+  // outside the csv — hot siblings and cold tools alike — is un-dispatchable, because the
+  // filter's whole point is a provably single-tool server for the seonix-ask benchmark arm.
+  const filtered = served !== TOOLS;
   const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: served }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
     try {
+      if (filtered && !servedNames.has(name)) throw new ToolError(`unknown tool: ${name}`);
       const text = await dispatchTool(name, args || {}, { config, source });
       return { content: [{ type: "text", text }] };
     } catch (e) {
@@ -416,5 +439,5 @@ export async function startServer() {
   const server = buildServer({ config });
   await server.connect(new StdioServerTransport());
   // stdout belongs to the MCP transport; sign on via stderr.
-  process.stderr.write(`seonix: serving ${TOOLS.length} tools over ${config.graphFile}\n`);
+  process.stderr.write(`seonix: serving ${resolveServedTools().length} tools over ${config.graphFile}\n`);
 }

package/src/sessions.mjs

@@ -0,0 +1,206 @@
+// sessions.mjs — chat sessions as first-class temporal graph data, like commits.
+//
+// A `seonix chat` session leaves two artifacts under the target repo:
+//   .seonix/session-<uuidv7>.log            — the human-readable transcript (chat.mjs)
+//   .seonix/sessions/session-<uuidv7>.jsonl — the STRUCTURED sidecar this module owns:
+//     {"type":"session", id, started, repo, seonixVersion}        (header line)
+//     {"type":"turn", ts, query, resolvedIds, answeredIds, miss}  (one per turn, flushed)
+//     {"type":"end", ts}                                          (clean close marker)
+//
+// From the sidecar the session enters the typed graph twice:
+//   - READ TIME (chat.mjs, per turn): appendSessionToGraph() upserts one `Session`
+//     individual (`session:<uuidv7>`) + `mgx:asksAbout` edges into graph.json —
+//     atomically (temp + rename), re-reading the file first so a re-index that
+//     happened mid-session is tolerated: edges whose targets vanished are dropped,
+//     never left dangling (honest degradation).
+//   - RE-INDEX (extract.mjs single-path mode): readSessionRecords() + foldInSessions()
+//     re-attach every recorded session to the FRESH graph, re-resolving each recorded
+//     entity id (by id first, then by unique label derived from the id shape);
+//     unresolvable references are dropped and counted on the session node
+//     (mgx:sessionDroppedEdges) — never a guessed edge.
+//
+// Sessions are runtime observations, not source derivations: they record what a human
+// asked the graph about and which entities answered, so re-indexing re-attaches them
+// rather than re-deriving them from source.
+
+import { readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const SESSIONS_DIR_REL = join(".seonix", "sessions");
+
+export const SESSION_CLASS = "Session";
+export const ASKS_ABOUT_PREDICATE = "asksAbout";
+export const ASKS_ABOUT_PROP = "mgx:asksAbout";
+
+const QUERIES_ATTR_CAP = 500; // joined-queries attribute cap (mirrors commitMessage's cap idea)
+
+/** Session labels mirror Commit's short-sha convention: the uuid's leading time-ordered hex. */
+const sessionLabel = (id) => String(id).slice(0, 8);
+
+/** Best-effort label a recorded entity id would carry, derived from the id shape —
+ *  the "then by label" tier of fold-in re-resolution (ids are `mod:<path>`,
+ *  `fn:<path>#<name>`, `commit:<sha>`; labels are path / name / short sha). */
+function labelFromId(id) {
+  const s = String(id);
+  if (s.startsWith("mod:")) return s.slice(4);
+  const fn = s.match(/^fn:.*#(.+)$/);
+  if (fn) return fn[1];
+  if (s.startsWith("commit:")) return s.slice(7, 19);
+  return null;
+}
+
+/** Atomic JSON write: temp file in the same directory + rename, so a concurrent
+ *  reader never sees a torn graph.json and a crash never destroys the old one. */
+async function atomicWriteJson(file, obj) {
+  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  await writeFile(tmp, JSON.stringify(obj));
+  await rename(tmp, file);
+}
+
+/**
+ * Upsert one session record into an `entities` payload (mutates; pure of I/O).
+ * Shared by the read-time append AND the re-index fold-in, so both resolve and
+ * degrade identically:
+ *   - a prior copy of the same session (per-turn re-appends) is replaced;
+ *   - every recorded ref resolves by id, else by UNIQUE label (ambiguous → drop);
+ *   - dropped refs are counted on the session node, never guessed into edges.
+ * Record shape: { id, started, ended?, turns: [{ts, query, resolvedIds, answeredIds, miss}] }.
+ * Returns { kept, dropped }.
+ */
+export function upsertSession(entities, record) {
+  const sid = `session:${record.id}`;
+  entities.individuals ||= [];
+  entities.objectProperties ||= [];
+
+  // replace any prior copy of this session (read-time appends run once per turn)
+  entities.individuals = entities.individuals.filter((i) => i?.id !== sid);
+  let group = entities.objectProperties.find((g) => g?.prop === ASKS_ABOUT_PROP);
+  if (group) {
+    group.examples = (group.examples || []).filter((e) => e?.subject !== sid);
+  } else {
+    group = { predicate: ASKS_ABOUT_PREDICATE, prop: ASKS_ABOUT_PROP, count: 0, examples: [] };
+    entities.objectProperties.push(group);
+  }
+
+  // resolve refs against the CURRENT individuals — by id, then by unique label
+  const byId = new Map();
+  const byLabel = new Map(); // label -> id, or null when ambiguous
+  for (const i of entities.individuals) {
+    if (!i?.id) continue;
+    byId.set(i.id, i);
+    if (i.label) byLabel.set(i.label, byLabel.has(i.label) ? null : i.id);
+  }
+  const turns = Array.isArray(record.turns) ? record.turns : [];
+  const refs = [...new Set(turns.flatMap((t) => [...(t?.resolvedIds || []), ...(t?.answeredIds || [])]))];
+  const targets = [];
+  let dropped = 0;
+  for (const ref of refs) {
+    if (byId.has(ref)) { targets.push(ref); continue; }
+    const cand = labelFromId(ref);
+    const viaLabel = cand ? byLabel.get(cand) : undefined;
+    if (viaLabel) { targets.push(viaLabel); continue; }
+    dropped += 1; // vanished or ambiguous — an honest drop, never a dangling/guessed edge
+  }
+
+  const started = record.started || "";
+  const ended = record.ended || turns.at(-1)?.ts || started;
+  const queries = turns.map((t) => String(t?.query || "")).filter(Boolean);
+  const label = sessionLabel(record.id);
+  entities.individuals.push({
+    id: sid, label, class: SESSION_CLASS,
+    derived_from: [], mentions: [],
+    attributes: [
+      { prop: "mgx:sessionStarted", key: "started", value: started },
+      { prop: "mgx:sessionEnded", key: "ended", value: ended },
+      { prop: "mgx:sessionTurns", key: "turns", value: String(turns.length) },
+      ...(queries.length ? [{ prop: "mgx:sessionQueries", key: "queries", value: queries.join(" | ").slice(0, QUERIES_ATTR_CAP) }] : []),
+      ...(dropped ? [{ prop: "mgx:sessionDroppedEdges", key: "dropped", value: String(dropped) }] : []),
+    ],
+  });
+  for (const t of targets) {
+    group.examples.push({ subject: sid, object: t, subjectLabel: label, objectLabel: byId.get(t)?.label || t });
+  }
+  group.count = group.examples.length;
+
+  // classes[] + vocabulary[] entries appear ONLY once a session exists, so a
+  // session-less graph stays byte-identical to what buildEntities always produced.
+  const sessions = entities.individuals.filter((i) => i.class === SESSION_CLASS);
+  if (Array.isArray(entities.classes)) {
+    let cls = entities.classes.find((c) => c?.name === SESSION_CLASS);
+    if (!cls) { cls = { name: SESSION_CLASS, count: 0, sample: [] }; entities.classes.push(cls); }
+    cls.count = sessions.length;
+    cls.sample = sessions.slice(0, 3).map((i) => i.label);
+  }
+  if (Array.isArray(entities.vocabulary) && !entities.vocabulary.some((v) => v?.prop === ASKS_ABOUT_PROP)) {
+    entities.vocabulary.push({
+      prop: ASKS_ABOUT_PROP, predicate: ASKS_ABOUT_PREDICATE,
+      note: "chat Session → entity a turn resolved/answered with; runtime observation, owned (no SEON term)",
+    });
+  }
+  return { kept: targets.length, dropped };
+}
+
+/** Read-time append (chat.mjs, once per turn): re-read graph.json FRESH (a re-index
+ *  may have replaced it mid-session), upsert, write back atomically. Throws on a
+ *  missing/invalid artifact — the caller treats the append as best-effort. */
+export async function appendSessionToGraph(graphFile, record) {
+  const entities = JSON.parse(await readFile(graphFile, "utf8"));
+  const res = upsertSession(entities, record);
+  await atomicWriteJson(graphFile, entities);
+  return res;
+}
+
+/** Parse one sidecar .jsonl into a session record (null if no valid header).
+ *  Torn/partial trailing lines (a killed session) are skipped, not fatal. */
+export function parseSessionJsonl(text) {
+  let header = null;
+  let ended = "";
+  const turns = [];
+  const arr = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+  for (const line of String(text).split("\n")) {
+    const s = line.trim();
+    if (!s) continue;
+    let rec;
+    try { rec = JSON.parse(s); } catch { continue; }
+    if (rec?.type === "session" && !header) header = rec;
+    else if (rec?.type === "turn") {
+      turns.push({
+        ts: String(rec.ts || ""), query: String(rec.query || ""),
+        resolvedIds: arr(rec.resolvedIds), answeredIds: arr(rec.answeredIds), miss: !!rec.miss,
+      });
+    } else if (rec?.type === "end") ended = String(rec.ts || "") || ended;
+  }
+  if (!header?.id) return null;
+  return { id: String(header.id), started: String(header.started || ""), ended, turns };
+}
+
+/** All recorded sessions under <rootDir>/.seonix/sessions/*.jsonl, oldest first
+ *  (uuidv7 filenames sort chronologically). Best-effort: no dir → []. */
+export async function readSessionRecords(rootDir) {
+  const dir = join(rootDir, SESSIONS_DIR_REL);
+  let names;
+  try { names = await readdir(dir); } catch { return []; }
+  const records = [];
+  for (const name of names.filter((n) => n.endsWith(".jsonl")).sort()) {
+    try {
+      const rec = parseSessionJsonl(await readFile(join(dir, name), "utf8"));
+      if (rec) records.push(rec);
+    } catch { /* unreadable sidecar — skip, never fail an index run */ }
+  }
+  return records;
+}
+
+/** Re-index fold-in: attach every recorded session to a FRESH entities payload.
+ *  Sessions are runtime observations, not source derivations — they are re-attached
+ *  after the source-derived build, with every reference re-resolved against the new
+ *  graph (upsertSession's id-then-label tiers; unresolvable → dropped + counted). */
+export function foldInSessions(entities, records) {
+  let kept = 0;
+  let dropped = 0;
+  for (const rec of records || []) {
+    const r = upsertSession(entities, rec);
+    kept += r.kept;
+    dropped += r.dropped;
+  }
+  return { sessions: (records || []).length, kept, dropped };
+}

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;
+}