@polycode-projects/seonix 0.6.0 → 0.7.0

package/src/graph-format.mjs

@@ -0,0 +1,156 @@
+// graph-format.mjs — the on-disk graph wire format (A6: id-interned "v2").
+//
+// SERIALIZATION ONLY. The in-memory `entities` shape every reader/renderer consumes
+// is unchanged: `{ generated_at, prefixes, vocabulary, classes, objectProperties:
+// [{predicate, prop, count, examples:[{subject, object, subjectLabel, objectLabel,
+// weight?}]}], individuals:[{id, label, class, …}], proseIndex, … }`. This module only
+// changes how that object is written to / read back from graph.json.
+//
+// WHY. Every edge stores its endpoints twice (an id string AND that endpoint's label),
+// so a large graph spends most of its bytes re-quoting a few thousand ids/labels that
+// already appear verbatim in `individuals`. v2 interns them: `individuals` order IS the
+// id table (index 0 = individuals[0].id, …), each edge is a flat int pair into that
+// table, and a label is stored ONLY when it diverges from the endpoint node's own label
+// (the "R0" default rule). The bytes an edge no longer carries are exactly the redundant
+// ones. Expansion shares the SAME id/label string reference from `individuals`, so the
+// in-memory graph also dedupes those strings (the interning win realized at read time).
+//
+// EXCEPTION LABELS (the only labels v2 stores, per the graph's edge builders in
+// extract.mjs — see STRATEGY_ADVISOR.log a6-label-exceptions):
+//   - inherits (seon:hasSuperType) objectLabel = the RAW base expression (e.g. `Base[T]`,
+//     `argparse.Action`), which diverges from the resolved base node's label — and the
+//     object may be a NON-NODE `ext:<ident>` endpoint with no individual at all.
+//   - contains (seon:containsCodeEntity) objectLabel = the member short name, vs the
+//     member node's full dotted label.
+//   - callsSymbol (mgx:callsSymbol) objectLabel = the callee's last identifier, which can
+//     diverge from the callee node's full label.
+//   - cochange (mgx:changeCoupledWith) carries a numeric `weight` no id/label can encode.
+// The encoder does not special-case predicates: it stores any label that differs from R0
+// and any weight present, which subsumes all of the above and is correct by construction.
+//
+// SAFETY. A corrupt v2 artifact (an endpoint index past the id table) must NEVER silently
+// mis-resolve to the wrong node — `expandGraphPayload` THROWS, naming the group + offset.
+
+export const GRAPH_FORMAT_CURRENT = 2;
+
+/** Build a Map id → first individual with that id (the id table lookup), and a Map id →
+ *  its array index. Order is authoritative: index N is the Nth individual. */
+function indexIndividuals(individuals) {
+  const byId = new Map();
+  const idToIndex = new Map();
+  for (let i = 0; i < individuals.length; i += 1) {
+    const id = individuals[i]?.id;
+    if (id == null) continue;
+    if (!idToIndex.has(id)) idToIndex.set(id, i);
+    if (!byId.has(id)) byId.set(id, individuals[i]);
+  }
+  return { byId, idToIndex };
+}
+
+/**
+ * Encode an in-memory `entities` payload to the interned v2 wire form.
+ * Pure — does NOT mutate `entities` (shallow-copies the top level, replaces
+ * `objectProperties`, shares the `individuals` array by reference).
+ * `expandGraphPayload(encodeGraphV2(e))` deep-equals `e` BY CONSTRUCTION, and preserves
+ * top-level + group + edge key ORDER (so `JSON.stringify` round-trips byte-for-byte).
+ */
+export function encodeGraphV2(entities) {
+  const individuals = Array.isArray(entities?.individuals) ? entities.individuals : [];
+  const { byId, idToIndex } = indexIndividuals(individuals);
+  const base = individuals.length;
+
+  // Non-node endpoints (the only ones today: `ext:<ident>` inherits bases) get appended
+  // to a side table; their index is base + position. First-seen order is stable.
+  const extIds = [];
+  const extIndex = new Map();
+  const indexOf = (id) => {
+    if (idToIndex.has(id)) return idToIndex.get(id);
+    if (extIndex.has(id)) return extIndex.get(id);
+    const idx = base + extIds.length;
+    extIds.push(id);
+    extIndex.set(id, idx);
+    return idx;
+  };
+
+  const groups = Array.isArray(entities?.objectProperties) ? entities.objectProperties : [];
+  const encodedGroups = groups.map((g) => {
+    const examples = Array.isArray(g?.examples) ? g.examples : [];
+    const pairs = [];
+    const labels = {};
+    const weights = {};
+    examples.forEach((e, i) => {
+      pairs.push(indexOf(e.subject), indexOf(e.object));
+      // R0 default = the endpoint node's own label; store only the divergences.
+      const sDefault = byId.get(e.subject)?.label;
+      const oDefault = byId.get(e.object)?.label;
+      if (e.subjectLabel !== sDefault) labels[`${i}s`] = e.subjectLabel;
+      if (e.objectLabel !== oDefault) labels[`${i}o`] = e.objectLabel;
+      if (e.weight !== undefined) weights[i] = e.weight;
+    });
+    // Preserve group key order (predicate, prop, count) so round-trip is byte-stable;
+    // omit empty label/weight maps so a label-free graph stays lean.
+    const out = { predicate: g.predicate, prop: g.prop, count: g.count, pairs };
+    if (Object.keys(labels).length) out.labels = labels;
+    if (Object.keys(weights).length) out.weights = weights;
+    return out;
+  });
+
+  // Spread first so every existing top-level key keeps its position (and value, except the
+  // two we replace); `format`/`extIds` append. `individuals` re-listed for clarity (same ref).
+  return { ...entities, format: GRAPH_FORMAT_CURRENT, individuals, extIds, objectProperties: encodedGroups };
+}
+
+/**
+ * Expand a parsed graph payload back to the in-memory `entities` shape. PASSTHROUGH for
+ * any payload whose `format` is not the interned current (v1 / legacy artifacts, and store
+ * payloads which are already the in-memory shape) — returns it untouched. For a v2 payload,
+ * reconstructs each edge, sharing the id/label string references from `individuals`.
+ * THROWS (never silently mis-resolves) on an endpoint index outside the id + ext table.
+ */
+export function expandGraphPayload(payload) {
+  if (!payload || payload.format !== GRAPH_FORMAT_CURRENT) return payload;
+
+  const individuals = Array.isArray(payload.individuals) ? payload.individuals : [];
+  const extIds = Array.isArray(payload.extIds) ? payload.extIds : [];
+  const base = individuals.length;
+  const { byId } = indexIndividuals(individuals);
+
+  const idAt = (idx, where) => {
+    if (idx >= 0 && idx < base) return individuals[idx].id;
+    const e = idx - base;
+    if (e >= 0 && e < extIds.length) return extIds[e];
+    throw new Error(
+      `seonix graph-format v2: corrupt endpoint index ${idx} at ${where} `
+      + `(id table has ${base} individuals + ${extIds.length} extIds)`,
+    );
+  };
+
+  const groups = Array.isArray(payload.objectProperties) ? payload.objectProperties : [];
+  const objectProperties = groups.map((g) => {
+    const pairs = Array.isArray(g?.pairs) ? g.pairs : [];
+    const labels = g?.labels || {};
+    const weights = g?.weights || {};
+    const examples = [];
+    for (let i = 0; i < pairs.length; i += 2) {
+      const ei = i / 2;
+      const subject = idAt(pairs[i], `${g.prop} pair ${ei} (subject)`);
+      const object = idAt(pairs[i + 1], `${g.prop} pair ${ei} (object)`);
+      const sKey = `${ei}s`;
+      const oKey = `${ei}o`;
+      const subjectLabel = Object.prototype.hasOwnProperty.call(labels, sKey) ? labels[sKey] : byId.get(subject)?.label;
+      const objectLabel = Object.prototype.hasOwnProperty.call(labels, oKey) ? labels[oKey] : byId.get(object)?.label;
+      // Canonical edge key order (subject, object, subjectLabel, objectLabel, weight?) matches
+      // the writer's, so a re-serialized expanded graph is byte-identical to a v1 write.
+      const edge = { subject, object, subjectLabel, objectLabel };
+      if (Object.prototype.hasOwnProperty.call(weights, String(ei))) edge.weight = weights[ei];
+      examples.push(edge);
+    }
+    return { predicate: g.predicate, prop: g.prop, count: g.count, examples };
+  });
+
+  // Restore the in-memory shape: original top-level keys in order, minus the v2-only ones.
+  const out = { ...payload, individuals, objectProperties };
+  delete out.format;
+  delete out.extIds;
+  return out;
+}

package/src/graph-ops.mjs

@@ -0,0 +1,92 @@
+// graph-ops.mjs (A7) — pure, in-place-free transforms over an assembled `entities`
+// graph. Today: `dropByRepoPrefix`, the removals-only fast path for estate sync.
+//
+// SEMANTIC CAVEAT (why this is a FAST PATH, not the default). buildEntities resolves
+// calls / inherits / bases through a GLOBAL unique-name registry that spans EVERY repo
+// in the merged graph — a callee name defined in exactly one repo resolves; the same
+// name defined in two repos is dropped as ambiguous. So you can NOT reconstruct the
+// full graph by concatenating per-repo sub-graphs, and you can NOT surgically ADD a
+// repo without possibly changing how names resolve elsewhere. REMOVING a repo is the
+// one direction that IS locally safe: dropping a repo's individuals + the edges that
+// touch them yields a graph that is a strict subset of a from-scratch re-index — the
+// only imprecision is that a name which was ambiguous BECAUSE of the removed repo would
+// now resolve, which this function deliberately does NOT re-derive (it only deletes).
+// `syncRepositories` therefore uses the exact union-rebuild by default and reserves
+// this for the removals-only fast path (and future in-place sqlite deltas); a caller
+// choosing it should log that caveat.
+
+/** Escape a string for use as a literal inside a RegExp. */
+const escapeRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Filter dropped ids out of a proseIndex (`word -> [id]`), deleting a word whose
+ *  posting becomes empty. Non-array values (e.g. a nested `seonix:layers` block) pass
+ *  through untouched — this function only prunes the flat verbatim postings. */
+function filterProse(proseIndex, survivingIds) {
+  if (!proseIndex || typeof proseIndex !== "object") return proseIndex;
+  const out = {};
+  for (const [word, posting] of Object.entries(proseIndex)) {
+    if (Array.isArray(posting)) {
+      const kept = posting.filter((id) => survivingIds.has(id));
+      if (kept.length) out[word] = kept;
+    } else {
+      out[word] = posting;
+    }
+  }
+  return out;
+}
+
+/**
+ * Return a NEW `entities` with one repo's contribution removed (the merged-graph
+ * removals-only fast path — see the module caveat). `prefix` is a repo name as assigned
+ * by assignRepoPrefixes.
+ *
+ * Drops:
+ *  - individuals whose id matches `^(mod|fn):<prefix>/` (Module/Function/Method/… nodes);
+ *  - every objectProperties edge whose subject OR object is one of those dropped ids
+ *    (each group's `count` recomputed);
+ *  - a Commit individual ONLY when no surviving `touches`/`touchesSymbol` edge still
+ *    references it — commit ids are `commit:<sha>` (NOT repo-prefixed) and are SHARED
+ *    across repos, so a commit that also touched another repo's modules survives;
+ *  - dropped ids from the proseIndex postings (emptied words deleted).
+ *
+ * Recomputes classes[].count/sample from the survivors; leaves prefixes/vocabulary/
+ * format/generated_at and any other top-level keys untouched. Pure (no mutation of the
+ * input).
+ */
+export function dropByRepoPrefix(entities, prefix) {
+  const re = new RegExp(`^(mod|fn):${escapeRe(prefix)}/`);
+  const individuals = Array.isArray(entities?.individuals) ? entities.individuals : [];
+
+  // 1. Node ids to drop (never a bare commit: — those are shared and handled below).
+  const dropped = new Set();
+  for (const ind of individuals) if (re.test(ind.id)) dropped.add(ind.id);
+
+  // 2. Filter edges; note which commits still have a surviving touches/touchesSymbol.
+  const referencedCommits = new Set();
+  const objectProperties = (entities.objectProperties || []).map((g) => {
+    const examples = (g.examples || []).filter((e) => !dropped.has(e.subject) && !dropped.has(e.object));
+    if (g.predicate === "touches" || g.predicate === "touchesSymbol") {
+      for (const e of examples) {
+        if (typeof e.subject === "string" && e.subject.startsWith("commit:")) referencedCommits.add(e.subject);
+      }
+    }
+    return { ...g, count: examples.length, examples };
+  });
+
+  // 3. Survivors: drop the prefixed nodes, and any Commit no edge references any more.
+  const survivingIndividuals = individuals.filter((ind) => {
+    if (dropped.has(ind.id)) return false;
+    if (ind.class === "Commit") return referencedCommits.has(ind.id);
+    return true;
+  });
+  const survivingIds = new Set(survivingIndividuals.map((i) => i.id));
+
+  // 4. Prose postings + class counts/samples, all recomputed from the survivors.
+  const proseIndex = filterProse(entities.proseIndex, survivingIds);
+  const classes = (entities.classes || []).map((c) => {
+    const members = survivingIndividuals.filter((i) => i.class === c.name);
+    return { ...c, count: members.length, sample: members.slice(0, 3).map((i) => i.label) };
+  });
+
+  return { ...entities, individuals: survivingIndividuals, objectProperties, classes, proseIndex };
+}

package/src/manifest.mjs

@@ -0,0 +1,148 @@
+// manifest.mjs (A7) — the estate manifest: a per-repo fingerprint record that lets
+// `seonix sync` decide which member repos of a multi_root estate actually changed
+// since the last index, so only those are re-extracted.
+//
+// A manifest is `{ format, generated_at, repos: [row] }` written to
+// `<multi_root>/.seonix/manifest.json`. Each row is
+//   { name, path, kind: "git"|"gitparent"|"plain",
+//     fingerprint: { head?, dirty? } | { walk? },
+//     history_depth, indexed_at_head, modules, commits }.
+//
+// FINGERPRINTS (all hashes sha256 via node:crypto):
+//   git       — a child directory with its OWN .git:  { head: rev-parse HEAD,
+//               dirty: sha256(git status --porcelain) }.
+//   gitparent — a plain child of a multi_root that is ITSELF inside a git working
+//               tree (a monorepo subdir): { head: git -C <root> log -1 --format=%H --
+//               <subdir>, dirty: sha256(scoped `git status --porcelain -- <subdir>`) }.
+//   plain     — a child with no git at all: { walk: sha256 of the sorted
+//               "relpath\tsize\tmtimeMs" lines over the INDEXER'S OWN walk (same
+//               walk/loadIgnores → same SKIP_DIRS/.seonixignore, so the fingerprint's
+//               blind spots match the graph's exactly) }.
+//
+// Everything here is pure/deterministic except the fs+git reads a fingerprint needs;
+// `diffManifest` is pure.
+
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { readFile, writeFile, rename, mkdir, stat } from "node:fs/promises";
+import { join, resolve, relative, sep } from "node:path";
+import { walk, loadIgnores } from "./walk.mjs";
+import { LANG_EXTS } from "./extract_lang.mjs";
+
+// Every extension the indexer covers (Python + the multi-language front-end); mirrors
+// extract.mjs's INDEXED_EXTS so the plain-kind walk fingerprint sees the same files the
+// graph is built from.
+const INDEXED_EXTS = [".py", ...LANG_EXTS];
+
+const sha256 = (s) => createHash("sha256").update(String(s)).digest("hex");
+
+/** Run a git subcommand synchronously; never throws. → { code, stdout, stderr }. */
+function git(cwd, args) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return { code: r.status ?? -1, stdout: r.stdout || "", stderr: r.stderr || "" };
+}
+
+/** Classify a candidate estate member. `multiRoot` (optional) enables the "gitparent"
+ *  case: when the member has no .git of its own BUT the estate root is inside a git
+ *  working tree, the member is a tracked subdir of that outer repo. Without a
+ *  `multiRoot`, a non-.git member is always "plain".
+ *  → { kind, root, subdir } where `root` is the git toplevel (git/gitparent) or the
+ *  member path (plain) and `subdir` is the member's path relative to `root` (gitparent). */
+export async function classifyRepo(repoPath, { multiRoot } = {}) {
+  const p = resolve(repoPath);
+  const hasOwnGit = await stat(join(p, ".git")).then(() => true).catch(() => false);
+  if (hasOwnGit) return { kind: "git", root: p, subdir: "" };
+  if (multiRoot) {
+    // Ask git itself for the enclosing repo root + this dir's prefix within it — git
+    // reports canonical (realpath'd) paths, sidestepping the macOS /var → /private/var
+    // symlink mismatch a manual `relative()` would trip over.
+    const top = git(p, ["rev-parse", "--show-toplevel"]);
+    const prefix = git(p, ["rev-parse", "--show-prefix"]);
+    if (top.code === 0 && top.stdout.trim() && prefix.code === 0) {
+      const subdir = prefix.stdout.trim().replace(/\/+$/, "");
+      if (subdir) return { kind: "gitparent", root: top.stdout.trim(), subdir };
+    }
+  }
+  return { kind: "plain", root: p, subdir: "" };
+}
+
+/** Fingerprint one estate member. → { kind, fingerprint } (see the module header). */
+export async function fingerprintRepo(repoPath, { multiRoot, exts = INDEXED_EXTS } = {}) {
+  const { kind, root, subdir } = await classifyRepo(repoPath, { multiRoot });
+
+  if (kind === "git") {
+    const head = git(root, ["rev-parse", "HEAD"]);
+    const porcelain = git(root, ["status", "--porcelain"]);
+    return { kind, fingerprint: { head: head.code === 0 ? head.stdout.trim() : "", dirty: sha256(porcelain.stdout) } };
+  }
+  if (kind === "gitparent") {
+    const head = git(root, ["log", "-1", "--format=%H", "--", subdir]);
+    const porcelain = git(root, ["status", "--porcelain", "--", subdir]);
+    return { kind, fingerprint: { head: head.code === 0 ? head.stdout.trim() : "", dirty: sha256(porcelain.stdout) } };
+  }
+  // plain: hash the indexer's own file surface (relpath + size + mtimeMs).
+  const ignore = await loadIgnores(repoPath);
+  const files = await walk(repoPath, exts, ignore);
+  const rows = [];
+  for (const abs of files) {
+    const st = await stat(abs).catch(() => null);
+    if (!st) continue;
+    const rel = relative(repoPath, abs).split(sep).join("/");
+    rows.push(`${rel}\t${st.size}\t${st.mtimeMs}`);
+  }
+  rows.sort();
+  return { kind, fingerprint: { walk: sha256(rows.join("\n")) } };
+}
+
+/** True when two rows describe the same source state (same kind + fingerprint). Absent
+ *  fingerprint fields compare equal (undefined === undefined), so this works across all
+ *  three kinds without knowing which fields a kind uses. */
+export function sameFingerprint(a, b) {
+  if (!a || !b || a.kind !== b.kind) return false;
+  const fa = a.fingerprint || {};
+  const fb = b.fingerprint || {};
+  return fa.head === fb.head && fa.dirty === fb.dirty && fa.walk === fb.walk;
+}
+
+/**
+ * PURE categorization of a `current` row set against a `previous` one, keyed by `name`.
+ * → { added, changed, removed, unchanged } — arrays of the CURRENT rows (removed carries
+ * the PREVIOUS rows, since those names are gone from current).
+ */
+export function diffManifest(current, previous) {
+  const prevByName = new Map((previous || []).map((r) => [r.name, r]));
+  const curByName = new Map((current || []).map((r) => [r.name, r]));
+  const added = [];
+  const changed = [];
+  const unchanged = [];
+  for (const r of current || []) {
+    const p = prevByName.get(r.name);
+    if (!p) added.push(r);
+    else if (sameFingerprint(r, p)) unchanged.push(r);
+    else changed.push(r);
+  }
+  const removed = (previous || []).filter((r) => !curByName.has(r.name));
+  return { added, changed, removed, unchanged };
+}
+
+/** Read `<artifactDir>/manifest.json` → the manifest object, or an empty manifest when
+ *  absent/unreadable/malformed (so a first sync sees every repo as "added"). */
+export async function readManifest(artifactDir) {
+  try {
+    const m = JSON.parse(await readFile(join(artifactDir, "manifest.json"), "utf8"));
+    return Array.isArray(m?.repos) ? m : { format: 1, repos: [] };
+  } catch {
+    return { format: 1, repos: [] };
+  }
+}
+
+/** Write `<artifactDir>/manifest.json` via temp+rename (a reader never sees a partial
+ *  file). Returns the written path. */
+export async function writeManifest(artifactDir, manifest) {
+  await mkdir(artifactDir, { recursive: true });
+  const path = join(artifactDir, "manifest.json");
+  const tmp = `${path}.tmp-${process.pid}`;
+  await writeFile(tmp, `${JSON.stringify(manifest, null, 2)}\n`);
+  await rename(tmp, path);
+  return path;
+}

package/src/server.mjs

@@ -20,6 +20,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig, ToolError } from "./config.mjs";
+import { createTelemetry } from "./telemetry.mjs";
 import * as defaultSource from "./source.mjs";
 import {
   parseEntities,
@@ -418,13 +419,23 @@ export function buildServer({ config = loadConfig(), source = defaultSource, env
   // 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;
+  // Opt-in telemetry, created ONCE per server (default OFF → null → `tel?.record` is a
+  // no-op and nothing is written). LOG FILE ONLY — stdout belongs to the MCP transport.
+  const tel = createTelemetry({ env, config, surface: "mcp" });
   const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: served }));
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
+    const t0 = Date.now();
     try {
       if (filtered && !servedNames.has(name)) throw new ToolError(`unknown tool: ${name}`);
       const text = await dispatchTool(name, args || {}, { config, source });
+      tel?.record({
+        tool: name,
+        response: { count: text ? text.split("\n").length : 0, truncated: /truncated/i.test(text) },
+        perf: { ms_total: Date.now() - t0 },
+        cost: { returned_chars: text.length, returned_tokens_est: Math.ceil(text.length / 4) },
+      });
       return { content: [{ type: "text", text }] };
     } catch (e) {
       const text = e instanceof ToolError ? e.message : `unexpected error: ${e?.message || e}`;

package/src/sessions.mjs

@@ -25,6 +25,7 @@
 
 import { readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { encodeGraphV2, expandGraphPayload, GRAPH_FORMAT_CURRENT } from "./graph-format.mjs";
 
 export const SESSIONS_DIR_REL = join(".seonix", "sessions");
 
@@ -144,9 +145,13 @@ export function upsertSession(entities, record) {
  *  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 raw = JSON.parse(await readFile(graphFile, "utf8"));
+  // A6: read the on-disk format, expand to the in-memory shape, upsert, then WRITE BACK in
+  // the SAME format it was read as — so a v2-on-disk graph stays v2, a v1 graph stays v1.
+  const wasV2 = raw?.format === GRAPH_FORMAT_CURRENT;
+  const entities = expandGraphPayload(raw);
   const res = upsertSession(entities, record);
-  await atomicWriteJson(graphFile, entities);
+  await atomicWriteJson(graphFile, wasV2 ? encodeGraphV2(entities) : entities);
   return res;
 }
 

package/src/source.mjs

@@ -3,8 +3,9 @@
 // stub it); in production it reads the JSON artifact the deterministic indexer
 // wrote to config.graphFile. No network, no model calls.
 
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { ToolError } from "./config.mjs";
+import { expandGraphPayload } from "./graph-format.mjs";
 
 let cache = null; // { file, payload } — one artifact per process; cheap re-reads.
 
@@ -12,9 +13,34 @@ export function clearCache() {
   cache = null;
 }
 
+/** C12 (opt-in): try the resident node:sqlite store, verifying freshness against the live
+ *  graph.json (bytes+mtimeMs). Returns the payload on success, or null to fall back to the
+ *  JSON read — on a stale/corrupt/absent store (typed throw from readPayload) or when the
+ *  source JSON can't be stat'd. node:sqlite is imported LAZILY here, so a gate-off load
+ *  never touches sqlite (no ExperimentalWarning, no store.mjs sqlite import). */
+async function fetchFromStore(config) {
+  let expectStat;
+  try { expectStat = await stat(config.graphFile); }
+  catch { return null; } // no source JSON to verify against → let the JSON path emit its own error
+  try {
+    const { readPayload, storeFileFor } = await import("./store.mjs");
+    const dbPath = config.storeFile || storeFileFor(config.graphFile);
+    return await readPayload(dbPath, { expectStat });
+  } catch (e) {
+    process.stderr.write(`seonix: sqlite store unavailable (${e?.name || e?.code || e?.message || e}); using graph.json\n`);
+    return null;
+  }
+}
+
 /** Read + parse the local graph artifact. Cached per file for the process. */
 export async function fetchEntities(config) {
   if (cache && cache.file === config.graphFile) return cache.payload;
+  // Gate: config.store (from loadConfig) OR the raw env, so callers that build a config
+  // WITHOUT loadConfig (e.g. cli's configFor) still honour SEONIX_STORE=sqlite.
+  if (config.store === "sqlite" || process.env.SEONIX_STORE === "sqlite") {
+    const payload = await fetchFromStore(config);
+    if (payload) { cache = { file: config.graphFile, payload }; return payload; }
+  }
   let text;
   try {
     text = await readFile(config.graphFile, "utf8");
@@ -26,9 +52,13 @@ export async function fetchEntities(config) {
   }
   let payload;
   try {
-    payload = JSON.parse(text);
-  } catch {
-    throw new ToolError(`graph artifact ${config.graphFile} is not valid JSON`);
+    // expandGraphPayload transparently reconstructs the in-memory shape from the interned
+    // v2 wire form (A6); it is a passthrough for v1 / legacy artifacts. This is the single
+    // load choke point for server / chat / viz / cli, so they all read expanded graphs.
+    payload = expandGraphPayload(JSON.parse(text));
+  } catch (e) {
+    if (e instanceof SyntaxError) throw new ToolError(`graph artifact ${config.graphFile} is not valid JSON`);
+    throw e; // a corrupt-index throw from expandGraphPayload must surface loudly, not masquerade as bad JSON
   }
   cache = { file: config.graphFile, payload };
   return payload;