@polycode-projects/seonix 0.2.0 → 0.3.0

package/src/java_treesitter.mjs

@@ -36,10 +36,12 @@ const clip = (s, n) => (s.length <= n ? s : s.slice(0, n));
 const fieldText = (n, f) => n.childForFieldName(f)?.text || "";
 
 const TYPE_DECLS = new Set(["class_declaration", "interface_declaration", "enum_declaration", "record_declaration"]);
+const SUBKIND = { interface_declaration: "interface", enum_declaration: "enum", record_declaration: "record" };
 const BASE_WRAPPERS = new Set(["superclass", "super_interfaces", "extends_interfaces", "interfaces"]);
 const TYPE_NODES = new Set(["type_identifier", "generic_type", "scoped_type_identifier"]);
 
-/** Callee names within a node (syntax-level; unresolved). */
+/** Callee names within a node (syntax-level; unresolved). Object creations count as
+ *  call edges to the created type: `new X(...)` → bare "X" (generics/scope stripped). */
 function collectCalls(node) {
   const out = new Set();
   const stack = [node];
@@ -48,6 +50,10 @@ function collectCalls(node) {
     if (n.type === "method_invocation") {
       const nm = fieldText(n, "name");
       if (nm) out.add(clip(nm, 80));
+    } else if (n.type === "object_creation_expression") {
+      const t = n.childForFieldName("type");
+      const nm = t ? oneLine(t.text).replace(/<.*$/s, "").split(".").pop().trim() : "";
+      if (nm) out.add(clip(nm, 80));
     }
     for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
   }
@@ -104,6 +110,79 @@ function bodyContainer(typeNode) {
     || null;
 }
 
+/** Emit one type declaration (and, recursively, its nested types as Outer.Inner —
+ *  matching the JavaParser backend's qualified names). kind stays "class"; the
+ *  flavour (interface/enum/record) lands in `subkind`. */
+function emitType(n, prefix, defines, exports) {
+  const simple = fieldText(n, "name");
+  if (!simple) return;
+  const cname = prefix ? `${prefix}.${simple}` : simple;
+  const mods = modifiersNode(n);
+  defines.push({
+    name: cname, kind: "class", lineno: line(n), end_lineno: endLine(n),
+    bases: basesOf(n), decorators: decoratorsFrom(mods),
+    ...(SUBKIND[n.type] ? { subkind: SUBKIND[n.type] } : {}),
+    ...(visFrom(mods) ? { visibility: visFrom(mods) } : {}),
+  });
+  if (isPublic(mods)) exports.add(cname);
+
+  // record components (formal params) surface as attributes (match JavaParser)
+  if (n.type === "record_declaration") {
+    const fp = n.childForFieldName("parameters");
+    if (fp) for (let i = 0; i < fp.namedChildCount; i++) {
+      const fpc = fp.namedChild(i);
+      if (fpc.type !== "formal_parameter") continue;
+      const pn = fieldText(fpc, "name");
+      if (pn) defines.push({ name: `${cname}.${pn}`, kind: "attribute", lineno: line(fpc), end_lineno: endLine(fpc), decorators: [] });
+    }
+  }
+
+  const body = bodyContainer(n);
+  if (!body) return;
+  // enum bodies keep constants at the top and wrap the rest in enum_body_declarations
+  const members = [];
+  for (let i = 0; i < body.namedChildCount; i++) {
+    const mem = body.namedChild(i);
+    if (mem.type === "enum_body_declarations") {
+      for (let j = 0; j < mem.namedChildCount; j++) members.push(mem.namedChild(j));
+    } else {
+      members.push(mem);
+    }
+  }
+  for (const mem of members) {
+    if (TYPE_DECLS.has(mem.type)) {
+      emitType(mem, cname, defines, exports); // nested type → Outer.Inner
+    } else if (mem.type === "enum_constant") {
+      const en = fieldText(mem, "name");
+      if (en) defines.push({ name: `${cname}.${en}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem), decorators: [], is_constant: true });
+    } else if (mem.type === "method_declaration" || mem.type === "constructor_declaration") {
+      const mn = fieldText(mem, "name") || cname;
+      const mmods = modifiersNode(mem);
+      const returns = mem.type === "method_declaration"
+        ? clip(oneLine(mem.childForFieldName("type")?.text || ""), 80) : "";
+      defines.push({
+        name: `${cname}.${mn}`, kind: "method", lineno: line(mem), end_lineno: endLine(mem),
+        decorators: decoratorsFrom(mmods), params: paramsText(mem),
+        ...(returns ? { returns } : {}), calls: collectCalls(mem),
+        ...(isStatic(mmods) ? { is_static: true } : {}),
+        ...(visFrom(mmods) ? { visibility: visFrom(mmods) } : {}),
+      });
+    } else if (mem.type === "field_declaration") {
+      const fmods = modifiersNode(mem);
+      for (let j = 0; j < mem.namedChildCount; j++) {
+        const vd = mem.namedChild(j);
+        if (vd.type !== "variable_declarator") continue;
+        const fn = fieldText(vd, "name");
+        if (fn) defines.push({
+          name: `${cname}.${fn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem),
+          decorators: decoratorsFrom(fmods),
+          ...(visFrom(fmods) ? { visibility: visFrom(fmods) } : {}),
+        });
+      }
+    }
+  }
+}
+
 export async function extractFile(absPath, root) {
   const text = await readFile(absPath, "utf8").catch(() => null);
   const path = relPath(root, absPath);
@@ -132,61 +211,9 @@ export async function extractFile(absPath, root) {
         if (nm) imports.add(oneLine(nm));
       }
     } else if (TYPE_DECLS.has(n.type)) {
-      const cname = fieldText(n, "name");
-      if (cname) {
-        const mods = modifiersNode(n);
-        defines.push({
-          name: cname, kind: "class", lineno: line(n), end_lineno: endLine(n),
-          bases: basesOf(n), decorators: decoratorsFrom(mods),
-          ...(visFrom(mods) ? { visibility: visFrom(mods) } : {}),
-        });
-        if (isPublic(mods)) exports.add(cname);
-
-        // record components (formal params) surface as attributes (match JavaParser)
-        if (n.type === "record_declaration") {
-          const fp = n.childForFieldName("parameters");
-          if (fp) for (let i = 0; i < fp.namedChildCount; i++) {
-            const fpc = fp.namedChild(i);
-            if (fpc.type !== "formal_parameter") continue;
-            const pn = fieldText(fpc, "name");
-            if (pn) defines.push({ name: `${cname}.${pn}`, kind: "attribute", lineno: line(fpc), end_lineno: endLine(fpc), decorators: [] });
-          }
-        }
-
-        const body = bodyContainer(n);
-        if (body) {
-          for (let i = 0; i < body.namedChildCount; i++) {
-            const mem = body.namedChild(i);
-            if (mem.type === "method_declaration" || mem.type === "constructor_declaration") {
-              const mn = fieldText(mem, "name") || cname;
-              const mmods = modifiersNode(mem);
-              const returns = mem.type === "method_declaration"
-                ? clip(oneLine(mem.childForFieldName("type")?.text || ""), 80) : "";
-              defines.push({
-                name: `${cname}.${mn}`, kind: "method", lineno: line(mem), end_lineno: endLine(mem),
-                decorators: decoratorsFrom(mmods), params: paramsText(mem),
-                ...(returns ? { returns } : {}), calls: collectCalls(mem),
-                ...(isStatic(mmods) ? { is_static: true } : {}),
-                ...(visFrom(mmods) ? { visibility: visFrom(mmods) } : {}),
-              });
-            } else if (mem.type === "field_declaration") {
-              const fmods = modifiersNode(mem);
-              for (let j = 0; j < mem.namedChildCount; j++) {
-                const vd = mem.namedChild(j);
-                if (vd.type !== "variable_declarator") continue;
-                const fn = fieldText(vd, "name");
-                if (fn) defines.push({
-                  name: `${cname}.${fn}`, kind: "attribute", lineno: line(mem), end_lineno: endLine(mem),
-                  decorators: decoratorsFrom(fmods),
-                  ...(visFrom(fmods) ? { visibility: visFrom(fmods) } : {}),
-                });
-              }
-            }
-          }
-        }
-      }
+      emitType(n, "", defines, exports);
     }
-    // descend, but not back into a type body (members handled above)
+    // descend, but not back into a type body (emitType recurses for nested types)
     if (!TYPE_DECLS.has(n.type)) for (let i = 0; i < n.namedChildCount; i++) stack.push(n.namedChild(i));
   }
 

package/src/jsts_tsc.mjs

@@ -1,11 +1,17 @@
-// JS/TS extractor — TypeScript compiler API (via ts-morph's re-exported `ts`
-// namespace; no separate `typescript` dep). PICKED candidate for JS/TS.
+// JS/TS extractor — TypeScript compiler API (direct `typescript` dep; the
+// 2026-07-02 library review swapped ts-morph out — we only ever used its
+// re-exported `ts` namespace, so importing the compiler directly is byte-identical
+// output for −12.4 MB of install). PICKED candidate for JS/TS.
 //
 // Uses ts.createSourceFile per file (no Program / no type-checker) — the fast,
 // deterministic, offline structural pass. Covers .ts/.tsx/.js/.jsx (allowJs is
 // implicit: JS is just parsed with the JS script-kind). Emits the SAME
 // `{path,dotted,imports,defines,calls,exports}` contract extract_ast.py prints,
 // so extract.mjs/buildEntities + codegraph.mjs/digest consume it unchanged.
+// Both module systems are read: ESM import/export declarations AND a CommonJS
+// pass (top-level require() with literal specifiers → imports; module.exports /
+// exports.name assignments → exports) — express-style repos are CJS-only and
+// were producing edge-empty graphs before the 2026-07-02 pass.
 //
 // Fidelity note (honest): params/returns are ANNOTATION strings (Group-A
 // mechanical), exactly like the Python path's "returns = annotation only". A
@@ -13,7 +19,7 @@
 // promoting Group-B→A) is the documented ceiling, NOT run here.
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { ts } from "ts-morph";
+import ts from "typescript";
 import { walk, relPath } from "./walk.mjs";
 
 const EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
@@ -98,6 +104,27 @@ export async function extractFile(absPath, root) {
     imports.add(`${base}/index`); // dir-import fallback (./foo → ./foo/index)
   };
 
+  // ---- CommonJS pass (2026-07-02): express-style repos are require()/module.exports only,
+  // which left their graphs edge-empty (js-express: imports 0 — five of six ask families
+  // structurally impossible). Top-level statements only, same resolveSpecifier as the ESM
+  // specifiers (relative paths resolve to modules, bare ones stay as-is), and STRICTLY
+  // literal arguments — a require(expr) is skipped, never guessed (house "no wrong edge").
+  /** `require("x")` / require(`x`) with a single literal arg → its specifier, else null. */
+  const requireSpecifier = (node) =>
+    node && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require" &&
+    node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])
+      ? node.arguments[0].text
+      : null;
+  /** Peel `require("x").member` / parens down to the require call (never enters functions). */
+  const requireIn = (expr) => {
+    let e = expr;
+    while (e && (ts.isPropertyAccessExpression(e) || ts.isParenthesizedExpression(e) || ts.isNonNullExpression?.(e))) e = e.expression;
+    return requireSpecifier(e);
+  };
+  const isModuleExports = (e) =>
+    ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && e.expression.text === "module" && e.name.text === "exports";
+  const isExportsRef = (e) => isModuleExports(e) || (ts.isIdentifier(e) && e.text === "exports");
+
   const addFn = (name, node, kind, extra = {}) => {
     defines.push({
       name, kind, lineno: lineOf(sf, node), end_lineno: endLineOf(sf, node),
@@ -155,6 +182,11 @@ export async function extractFile(absPath, root) {
     } else if (ts.isVariableStatement(stmt)) {
       const isConst = (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0;
       for (const d of stmt.declarationList.declarations) {
+        // CJS import: const X = require('spec') / const {a, b} = require('spec') /
+        // const Y = require('spec').member — BEFORE the identifier-only gate so a
+        // destructuring binding still records the import edge.
+        const reqSpec = requireIn(d.initializer);
+        if (reqSpec != null) resolveSpecifier(reqSpec);
         if (!ts.isIdentifier(d.name)) continue;
         const vn = d.name.text;
         const init = d.initializer;
@@ -173,6 +205,21 @@ export async function extractFile(absPath, root) {
       }
     } else if (ts.isExportAssignment?.(stmt)) {
       exports.add("default");
+    } else if (ts.isExpressionStatement(stmt)) {
+      // CJS exports + side-effect/re-export requires. Walk `=` chains so
+      // `exports = module.exports = X` records one default export, and
+      // `module.exports = require('./lib')` records both the export and the import.
+      let expr = stmt.expression;
+      while (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+        const lhs = expr.left;
+        if (isExportsRef(lhs)) exports.add("default");                       // module.exports = X / exports = X
+        else if (ts.isPropertyAccessExpression(lhs) && isExportsRef(lhs.expression)) {
+          exports.add(lhs.name.text);                                        // module.exports.name = / exports.name =
+        }
+        expr = expr.right;
+      }
+      const reqSpec = requireIn(expr); // covers bare `require('./side-effect')` too
+      if (reqSpec != null) resolveSpecifier(reqSpec);
     }
   }
 
@@ -208,4 +255,4 @@ export async function ingest(root, { ignore = null } = {}) {
   return { modules, failures, fileCount: files.length };
 }
 
-export const meta = { id: "tsc", language: "js/ts", lib: "typescript compiler API (via ts-morph)", exts: EXTS };
+export const meta = { id: "tsc", language: "js/ts", lib: "typescript compiler API", exts: EXTS };

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