@polycode-projects/seonix 0.6.0 → 0.7.0

package/src/store.mjs

@@ -0,0 +1,282 @@
+// store.mjs — OPT-IN resident node:sqlite store for the graph artifact (C12).
+//
+// The graph.json artifact is always authoritative; this store is a DERIVED,
+// rebuildable, machine-local companion (`.seonix/graph.db`) that a reader can
+// load instead of parsing the whole JSON blob. It is gated behind
+// `SEONIX_STORE=sqlite` at BOTH ends (build + load): unset, nothing here runs,
+// no `node:sqlite` is imported, and no graph.db is written — so the default
+// (benchmark) path is byte-identical.
+//
+// Correctness contract (the reason for every column below): the payload
+// reconstructed by `readPayload` must be DEEP-EQUAL to the JSON-loaded payload
+// AND JSON.stringify to the same bytes — because the digest byte-identity the
+// benchmark measures depends on exact ARRAY ORDER (individuals, relation groups,
+// per-group edges) and on the LABEL EXCEPTIONS that are not derivable from the
+// endpoints (an `inherits` edge's objectLabel is the raw base expression, and
+// its object can be an `ext:<Base>` id that is NOT a node; reexports/callsSymbol/
+// touchesSymbol carry non-derivable labels too). Hence: `ord` columns everywhere,
+// per-edge slabel/olabel stored verbatim, and an `ids` interning table that
+// covers non-node endpoints.
+//
+// node:sqlite is imported LAZILY (`await import("node:sqlite")`) only inside the
+// functions below, so merely importing this module (config.mjs does, eagerly)
+// never triggers the SQLite ExperimentalWarning on a default path.
+//
+// C13 (deferred) will add indexed query handles (getNode / edgesFor / searchProse)
+// that read individual rows/edges without materializing the whole graph; this pass
+// only implements the full load path + the transactional rebuild.
+
+import { createHash } from "node:crypto";
+import { readFile, rename, rm } from "node:fs/promises";
+
+export const FORMAT = "seonix-store";
+export const SCHEMA_VERSION = 1; // bump → old stores read as stale → JSON fallback → rebuild
+
+// Typed load failures — callers (source.mjs) catch these and silently fall back to
+// graph.json, emitting a one-line stderr hint. Never thrown on a gate-off path.
+export class StoreStale extends Error { constructor(m) { super(m); this.name = "StoreStale"; } }
+export class StoreCorrupt extends Error { constructor(m) { super(m); this.name = "StoreCorrupt"; } }
+
+// Edge keys with dedicated columns; anything else on an edge is round-tripped via `extra`.
+const STD_EDGE_KEYS = new Set(["subject", "object", "subjectLabel", "objectLabel", "weight"]);
+// Top-level payload keys that are DECOMPOSED into their own tables; every other
+// top-level key is stored verbatim in the meta `envelope` blob.
+const DECOMPOSED_KEYS = new Set(["individuals", "objectProperties", "proseIndex"]);
+
+/** Derive the store path from the JSON artifact path: `<...>.json` → `<...>.db`
+ *  (any other suffix just gains `.db`). Single source of truth for the mapping. */
+export function storeFileFor(graphFile) {
+  return /\.json$/i.test(graphFile) ? graphFile.replace(/\.json$/i, ".db") : `${graphFile}.db`;
+}
+
+const DDL = `
+CREATE TABLE meta (k TEXT PRIMARY KEY, v TEXT);
+CREATE TABLE ids (sid INTEGER PRIMARY KEY, id TEXT UNIQUE NOT NULL);
+CREATE TABLE nodes (sid INTEGER PRIMARY KEY, ord INTEGER NOT NULL, class TEXT, label TEXT, json TEXT NOT NULL);
+CREATE TABLE relations (rel INTEGER PRIMARY KEY, ord INTEGER NOT NULL, predicate TEXT, prop TEXT, count INTEGER);
+CREATE TABLE edges (rel INTEGER NOT NULL, ord INTEGER NOT NULL, s INTEGER NOT NULL, o INTEGER NOT NULL, slabel TEXT, olabel TEXT, w INTEGER, extra TEXT);
+CREATE INDEX edges_by_rel ON edges(rel, ord);
+`;
+
+async function unlinkQuiet(...paths) {
+  for (const p of paths) { try { await rm(p, { force: true }); } catch { /* best effort */ } }
+}
+
+/**
+ * Build the store from an in-memory `entities` payload, transactionally, and swap it
+ * into place atomically. Writes to `<dbPath>.tmp-<pid>-<rand>` under one BEGIN/COMMIT,
+ * checkpoints the WAL into the main file, then renames over `dbPath`.
+ *
+ * @param {string} dbPath
+ * @param {object} payload  the entities object (exactly as written to graph.json)
+ * @param {{sourceStat?: import("node:fs").Stats, sourceText?: string}} [opts]
+ *   sourceStat = fs.stat of the graph.json just written (freshness = bytes+mtimeMs);
+ *   sourceText = the exact JSON bytes (used for source_sha256; else JSON.stringify(payload)).
+ */
+export async function writeStore(dbPath, payload, { sourceStat, sourceText } = {}) {
+  const json = sourceText ?? JSON.stringify(payload);
+  const sha = createHash("sha256").update(json).digest("hex");
+  const sourceBytes = sourceText !== undefined ? Buffer.byteLength(sourceText) : (sourceStat?.size ?? Buffer.byteLength(json));
+  const sourceMtimeMs = sourceStat ? Math.round(sourceStat.mtimeMs) : 0;
+
+  const keyOrder = Object.keys(payload);
+  const envelope = {};
+  for (const k of keyOrder) if (!DECOMPOSED_KEYS.has(k)) envelope[k] = payload[k];
+  const individuals = Array.isArray(payload.individuals) ? payload.individuals : [];
+  const groups = Array.isArray(payload.objectProperties) ? payload.objectProperties : [];
+  const proseIndex = payload.proseIndex ?? {};
+
+  // Intern every id: node ids first (individuals order), then any edge endpoint not yet
+  // seen — this is what covers non-node endpoints like `ext:<Base>` inherits targets.
+  const idMap = new Map();
+  const sidOf = (id) => {
+    let sid = idMap.get(id);
+    if (sid === undefined) { sid = idMap.size + 1; idMap.set(id, sid); }
+    return sid;
+  };
+  for (const ind of individuals) sidOf(ind.id);
+  for (const g of groups) for (const e of (g.examples || [])) { sidOf(e.subject); sidOf(e.object); }
+
+  const tmp = `${dbPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  await unlinkQuiet(tmp, `${tmp}-wal`, `${tmp}-shm`);
+
+  const { DatabaseSync } = await import("node:sqlite");
+  const db = new DatabaseSync(tmp);
+  try {
+    db.exec("PRAGMA page_size = 8192");
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA synchronous = NORMAL");
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    db.exec(DDL);
+
+    db.exec("BEGIN");
+
+    const metaStmt = db.prepare("INSERT INTO meta(k, v) VALUES(?, ?)");
+    metaStmt.run("format", FORMAT);
+    metaStmt.run("version", String(SCHEMA_VERSION));
+    metaStmt.run("source_sha256", sha);
+    metaStmt.run("source_bytes", String(sourceBytes));
+    metaStmt.run("source_mtime_ms", String(sourceMtimeMs));
+    metaStmt.run("envelope", JSON.stringify(envelope));
+    metaStmt.run("key_order", JSON.stringify(keyOrder));
+    metaStmt.run("prose_index", JSON.stringify(proseIndex));
+
+    const idStmt = db.prepare("INSERT INTO ids(sid, id) VALUES(?, ?)");
+    for (const [id, sid] of idMap) idStmt.run(sid, id);
+
+    const nodeStmt = db.prepare("INSERT INTO nodes(sid, ord, class, label, json) VALUES(?, ?, ?, ?, ?)");
+    individuals.forEach((ind, ord) => {
+      nodeStmt.run(idMap.get(ind.id), ord, ind.class ?? null, ind.label ?? null, JSON.stringify(ind));
+    });
+
+    const relStmt = db.prepare("INSERT INTO relations(rel, ord, predicate, prop, count) VALUES(?, ?, ?, ?, ?)");
+    const edgeStmt = db.prepare("INSERT INTO edges(rel, ord, s, o, slabel, olabel, w, extra) VALUES(?, ?, ?, ?, ?, ?, ?, ?)");
+    groups.forEach((g, gord) => {
+      const rel = gord;
+      relStmt.run(rel, gord, g.predicate ?? null, g.prop ?? null,
+        Number.isFinite(g.count) ? g.count : (g.examples || []).length);
+      (g.examples || []).forEach((e, eord) => {
+        const extraKeys = Object.keys(e).filter((k) => !STD_EDGE_KEYS.has(k));
+        const extra = extraKeys.length
+          ? JSON.stringify(Object.fromEntries(extraKeys.map((k) => [k, e[k]])))
+          : null;
+        edgeStmt.run(rel, eord, idMap.get(e.subject), idMap.get(e.object),
+          e.subjectLabel ?? null, e.objectLabel ?? null,
+          e.weight ?? null, extra);
+      });
+    });
+
+    db.exec("COMMIT");
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  } finally {
+    db.close();
+  }
+
+  // Swap into place: drop any stale destination WAL sidecars (a reader must never apply
+  // an old -wal to the new main file), then rename. Derived + rebuildable, so the tiny
+  // non-atomic window is acceptable — a torn read throws StoreCorrupt → JSON fallback.
+  await unlinkQuiet(`${dbPath}-wal`, `${dbPath}-shm`);
+  await rename(tmp, dbPath);
+  await unlinkQuiet(`${tmp}-wal`, `${tmp}-shm`);
+  return dbPath;
+}
+
+function readMeta(db) {
+  const meta = {};
+  for (const row of db.prepare("SELECT k, v FROM meta").all()) meta[row.k] = row.v;
+  return meta;
+}
+
+/**
+ * Load and reconstruct the payload from the store. Throws StoreStale (schema bump or
+ * source-file drift) or StoreCorrupt (bad/absent file, malformed rows) — the caller
+ * catches either and falls back to graph.json.
+ *
+ * @param {string} dbPath
+ * @param {{expectStat?: import("node:fs").Stats}} [opts]  expectStat = fs.stat of the
+ *   live graph.json; freshness requires bytes + mtimeMs to match what writeStore stamped.
+ * @returns {Promise<object>} the reconstructed entities payload (deep-equal + stringify-equal).
+ */
+export async function readPayload(dbPath, { expectStat } = {}) {
+  const { DatabaseSync } = await import("node:sqlite");
+  let db;
+  try { db = new DatabaseSync(dbPath, { readOnly: true }); }
+  catch (e) { throw new StoreCorrupt(`cannot open store ${dbPath}: ${e?.message || e}`); }
+  try {
+    // A single guard: schema/freshness gates throw StoreStale/StoreCorrupt to signal
+    // "fall back to JSON"; any RAW error (e.g. sqlite "file is not a database" from a
+    // clobbered file, a malformed row) is normalized to StoreCorrupt so the caller's
+    // catch treats it identically.
+    let out;
+    try {
+      const meta = readMeta(db);
+      if (meta.format !== FORMAT) throw new StoreCorrupt(`not a ${FORMAT} database`);
+      let userVersion;
+      try { userVersion = Number(db.prepare("PRAGMA user_version").get().user_version); }
+      catch { userVersion = NaN; }
+      if (Number(meta.version) !== SCHEMA_VERSION || userVersion !== SCHEMA_VERSION) {
+        throw new StoreStale(`store schema v${meta.version}/${userVersion} != v${SCHEMA_VERSION}`);
+      }
+      if (expectStat) {
+        if (Number(meta.source_bytes) !== expectStat.size ||
+            Number(meta.source_mtime_ms) !== Math.round(expectStat.mtimeMs)) {
+          throw new StoreStale("graph.json changed since the store was built");
+        }
+      }
+
+      const idById = new Map();
+      for (const row of db.prepare("SELECT sid, id FROM ids").all()) idById.set(row.sid, row.id);
+      const idOf = (sid) => {
+        const id = idById.get(sid);
+        if (id === undefined) throw new StoreCorrupt(`edge endpoint sid ${sid} missing from ids table`);
+        return id;
+      };
+
+      const individuals = db.prepare("SELECT json FROM nodes ORDER BY ord").all()
+        .map((r) => JSON.parse(r.json));
+
+      const edgeStmt = db.prepare("SELECT s, o, slabel, olabel, w, extra FROM edges WHERE rel = ? ORDER BY ord");
+      const objectProperties = db.prepare("SELECT rel, predicate, prop, count FROM relations ORDER BY ord").all()
+        .map((g) => ({
+          predicate: g.predicate,
+          prop: g.prop,
+          count: g.count,
+          examples: edgeStmt.all(g.rel).map((e) => {
+            // Key order MUST match the builder: subject, object, subjectLabel, objectLabel,
+            // then weight (cochange only), then any extra keys.
+            const edge = { subject: idOf(e.s), object: idOf(e.o), subjectLabel: e.slabel, objectLabel: e.olabel };
+            if (e.w !== null && e.w !== undefined) edge.weight = e.w;
+            if (e.extra) Object.assign(edge, JSON.parse(e.extra));
+            return edge;
+          }),
+        }));
+
+      const envelope = JSON.parse(meta.envelope ?? "{}");
+      const proseIndex = JSON.parse(meta.prose_index ?? "{}");
+      const keyOrder = JSON.parse(meta.key_order ?? "[]");
+
+      out = {};
+      for (const k of keyOrder) {
+        if (k === "individuals") out.individuals = individuals;
+        else if (k === "objectProperties") out.objectProperties = objectProperties;
+        else if (k === "proseIndex") out.proseIndex = proseIndex;
+        else out[k] = envelope[k];
+      }
+    } catch (e) {
+      if (e instanceof StoreStale || e instanceof StoreCorrupt) throw e;
+      throw new StoreCorrupt(`store reconstruction failed: ${e?.message || e}`);
+    }
+    return out;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Verify a store is intact AND matches the current graph.json at `sourcePath`: schema
+ * version ok, `source_sha256` equals the live file's hash, and a full readPayload
+ * succeeds. Best-effort boolean (never throws) — used by `cli store_rebuild` to report.
+ */
+export async function verifyStore(dbPath, sourcePath) {
+  try {
+    const text = await readFile(sourcePath, "utf8");
+    const sha = createHash("sha256").update(text).digest("hex");
+    const { DatabaseSync } = await import("node:sqlite");
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+      const meta = readMeta(db);
+      if (meta.format !== FORMAT) return false;
+      if (Number(meta.version) !== SCHEMA_VERSION) return false;
+      const uv = Number(db.prepare("PRAGMA user_version").get().user_version);
+      if (uv !== SCHEMA_VERSION) return false;
+      if (meta.source_sha256 !== sha) return false;
+    } finally {
+      db.close();
+    }
+    // structural integrity: a full reconstruction round-trips without throwing
+    await readPayload(dbPath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/summary.mjs

@@ -0,0 +1,241 @@
+// Post-index summary (A1): a deterministic, human- AND machine-readable account of
+// what an index run actually ingested — repos, per-class individual counts, edge
+// counts, the language/extension mix, per-repo × per-extension MODULE counts, hub
+// modules, history depth, and graph size vs the V8 string cap.
+//
+// The point is to stop the "misread 7,345 Functions as the symbol total" failure:
+// SUMMARY.md/summary.json spell out the real totals next to the class breakdown, and
+// the B9 verify-loop consumes summary.json (esp. the per-repo × per-ext counts) to
+// compute indexing coverage.
+//
+// `buildSummary(entities, stats)` is a PURE function (no fs/process/Date) → a plain
+// object (format:1). `renderSummaryMd` turns that object into markdown.
+// `writeSummaryArtifacts` is the only IO — it writes summary.json + SUMMARY.md via
+// temp+rename. These are NEW files; nothing here touches graph.json bytes.
+
+import { writeFile, rename, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+// V8's hard maximum string length (chars). A graph.json larger than this can't be
+// JSON.parse'd back into one string — the failure mode the wh estate hit at 80%.
+// chars ≈ bytes for the ASCII-dominant graph, so we report the ratio labelled "~".
+export const V8_STRING_CAP = 536_870_888;
+
+// Module-level git history is collected to this depth by default (mirrors
+// extract.mjs GIT_LOG_COMMITS). Used only to classify the history tier for the
+// summary — kept local so summary.mjs has no import cycle back into extract.mjs.
+const HISTORY_FULL_DEPTH = 300;
+
+/** The file extension of a module path/label ("repo-a/pkg/a.py" → ".py"), lower-cased.
+ *  A leading-dot basename (".env") or an extension-less path → "" (rendered "(none)"). */
+function extOf(path) {
+  const s = String(path || "");
+  const slash = s.lastIndexOf("/");
+  const base = slash >= 0 ? s.slice(slash + 1) : s;
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+
+/** A deterministic tier label from the effective module-history depth. */
+function historyTier(nameDepth) {
+  if (!nameDepth) return "NONE";
+  return nameDepth < HISTORY_FULL_DEPTH ? "SHALLOW" : "FULL";
+}
+
+/** A new object with keys sorted ascending (stable JSON / MD output). */
+const sortObj = (o) =>
+  Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+
+/** Thousands-separated integer, locale-independent (deterministic). */
+const fmt = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+
+/**
+ * Undirected degree over the module-coarse import+call edges, restricted to modules
+ * under `mod:<prefix>/` (or all `mod:` nodes when `prefix` is empty). Returns the top
+ * `top` as [{id, label, degree}], deterministic tiebreak = degree DESC then id ASC.
+ */
+export function hubModules(entities, { prefix = "", top = 5 } = {}) {
+  const want = prefix ? `mod:${prefix}/` : "mod:";
+  const labelById = new Map();
+  for (const i of entities.individuals || []) {
+    if (i.class === "Module") labelById.set(i.id, i.label);
+  }
+  const degree = new Map();
+  const bump = (id) => degree.set(id, (degree.get(id) || 0) + 1);
+  for (const g of entities.objectProperties || []) {
+    if (g.predicate !== "imports" && g.predicate !== "calls") continue;
+    for (const e of g.examples || []) { bump(e.subject); bump(e.object); }
+  }
+  const rows = [];
+  for (const [id, deg] of degree) {
+    if (!id.startsWith(want)) continue;
+    rows.push({ id, label: labelById.get(id) ?? id.slice(4), degree: deg });
+  }
+  rows.sort((a, b) => (b.degree - a.degree) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return rows.slice(0, top);
+}
+
+/**
+ * Build the summary object (format:1) — PURE and deterministic (same inputs →
+ * deep-equal output every time). `entities` is the assembled graph payload;
+ * `stats` carries the run-level facts the graph itself doesn't record:
+ *   { mode:'single'|'multi',
+ *     repos:  [{ name, modules, commits, historyDepth:{name,symbol}, gitErrors:[{pass,message}] }],
+ *     skipped:[{ name, reason }],
+ *     languages:{ <lang>:{files,modules,symbols,…} },
+ *     graphBytes: number }
+ */
+export function buildSummary(entities, stats) {
+  const {
+    mode = "single", repos = [], skipped = [], languages = {}, graphBytes = 0,
+  } = stats || {};
+
+  // per-class individual counts (the fix for the "7,345 = total?" misread)
+  const classes = {};
+  for (const c of entities.classes || []) classes[c.name] = c.count;
+
+  // edge counts by predicate + grand total
+  const byPredicate = {};
+  let edgeTotal = 0;
+  for (const g of entities.objectProperties || []) {
+    byPredicate[g.predicate] = g.count;
+    edgeTotal += g.count;
+  }
+
+  // module → extension attribution, both overall and per-repo. In multi mode a
+  // module's owning repo is the leading `<name>/` path component; in single mode
+  // every module belongs to the one repo.
+  const repoNames = repos.map((r) => r.name);
+  const topExt = {};
+  const perRepoExt = new Map(); // name -> { ext -> count }
+  const ensure = (n) => { if (!perRepoExt.has(n)) perRepoExt.set(n, {}); return perRepoExt.get(n); };
+  for (const m of entities.individuals || []) {
+    if (m.class !== "Module") continue;
+    const label = m.label || m.id.slice(4);
+    const ext = extOf(label) || "(none)";
+    topExt[ext] = (topExt[ext] || 0) + 1;
+    const owner = mode === "single"
+      ? (repoNames[0] ?? null)
+      : (repoNames.find((n) => label.startsWith(`${n}/`)) ?? null);
+    if (owner != null) { const b = ensure(owner); b[ext] = (b[ext] || 0) + 1; }
+  }
+
+  // language mix — the stable {files,modules,symbols} subset of perLang
+  const languageMix = {};
+  for (const [lang, s] of Object.entries(languages)) {
+    languageMix[lang] = {
+      files: s.files || 0, modules: s.modules || 0, symbols: s.symbols || 0,
+    };
+  }
+
+  // effective history depth for the run = the deepest pass across repos
+  const depths = repos.map((r) => r.historyDepth || { name: 0, symbol: 0 });
+  const nameDepth = depths.length ? Math.max(...depths.map((d) => d.name || 0)) : 0;
+  const symbolDepth = depths.length ? Math.max(...depths.map((d) => d.symbol || 0)) : 0;
+
+  const repoRows = repos.map((r) => ({
+    name: r.name,
+    modules: r.modules || 0,
+    commits: r.commits || 0,
+    historyDepth: r.historyDepth || { name: 0, symbol: 0 },
+    gitErrors: (r.gitErrors || []).map((e) => ({ pass: e.pass, message: e.message })),
+    hubs: hubModules(entities, { prefix: mode === "multi" ? r.name : "", top: 5 }),
+    // per-repo × per-extension MODULE counts — the coverage unit B9 consumes
+    extensions: sortObj(perRepoExt.get(r.name) || {}),
+  }));
+
+  return {
+    format: 1,
+    mode,
+    graph: {
+      bytes: graphBytes,
+      capChars: V8_STRING_CAP,
+      capPct: `~${((graphBytes / V8_STRING_CAP) * 100).toFixed(1)}%`,
+    },
+    history: { tier: historyTier(nameDepth), depth: { name: nameDepth, symbol: symbolDepth } },
+    classes,
+    edges: { total: edgeTotal, byPredicate },
+    languages: languageMix,
+    extensions: sortObj(topExt),
+    repos: repoRows,
+    skipped: skipped.map((s) => ({ name: s.name, reason: s.reason })),
+  };
+}
+
+/** Render the summary object as human markdown. Includes one row per ingested repo
+ *  and one per skipped dir (with its reason); a repo whose git history failed shows a
+ *  FAILED history cell. */
+export function renderSummaryMd(summary) {
+  const lines = [];
+  lines.push("# seonix index summary", "");
+  lines.push(`- mode: ${summary.mode}`);
+  lines.push(`- graph: ${fmt(summary.graph.bytes)} bytes (${summary.graph.capPct} of the V8 string cap)`);
+  lines.push(`- history: tier=${summary.history.tier} depth name=${summary.history.depth.name} symbol=${summary.history.depth.symbol}`);
+  const totalInds = Object.values(summary.classes).reduce((a, b) => a + b, 0);
+  lines.push(`- individuals: ${fmt(totalInds)} total`);
+  const classBits = Object.entries(summary.classes).map(([k, v]) => `${k} ${fmt(v)}`).join(", ");
+  lines.push(`- classes: ${classBits || "(none)"}`);
+  lines.push(`- edges: ${fmt(summary.edges.total)} total`);
+  lines.push("");
+
+  lines.push("## Repositories", "");
+  lines.push("| repo | modules | commits | history |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const r of summary.repos) {
+    const hist = r.gitErrors.length
+      ? `FAILED: ${r.gitErrors.map((e) => e.message).join("; ")}`
+      : (r.historyDepth.name ? `ok (name=${r.historyDepth.name} symbol=${r.historyDepth.symbol})` : "none");
+    lines.push(`| ${r.name} | ${fmt(r.modules)} | ${fmt(r.commits)} | ${hist} |`);
+  }
+  for (const s of summary.skipped) {
+    lines.push(`| ${s.name} (skipped) | — | — | reason: ${s.reason} |`);
+  }
+  lines.push("");
+
+  if (Object.keys(summary.extensions).length) {
+    lines.push("## Module extensions", "");
+    for (const [ext, n] of Object.entries(summary.extensions)) lines.push(`- ${ext}: ${fmt(n)}`);
+    lines.push("");
+  }
+
+  lines.push("## Modules by repo × extension", "");
+  for (const r of summary.repos) {
+    const bits = Object.entries(r.extensions).map(([e, n]) => `${e} ${fmt(n)}`).join(", ") || "(none)";
+    lines.push(`- ${r.name}: ${bits}`);
+  }
+  lines.push("");
+
+  lines.push("## Hub modules", "");
+  for (const r of summary.repos) {
+    const bits = r.hubs.map((h) => `${h.label} (${h.degree})`).join(", ") || "(none)";
+    lines.push(`- ${r.name}: ${bits}`);
+  }
+  lines.push("");
+
+  if (Object.keys(summary.languages).length) {
+    lines.push("## Languages", "");
+    for (const [lang, s] of Object.entries(summary.languages)) {
+      lines.push(`- ${lang}: ${fmt(s.modules)} modules, ${fmt(s.symbols)} symbols, ${fmt(s.files)} files`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/** Write summary.json + SUMMARY.md into `artifactDir` (the `.seonix` dir), each via a
+ *  temp file + atomic rename so a reader never sees a half-written artifact. */
+export async function writeSummaryArtifacts(artifactDir, summary) {
+  await mkdir(artifactDir, { recursive: true });
+  const jsonPath = join(artifactDir, "summary.json");
+  const mdPath = join(artifactDir, "SUMMARY.md");
+  await writeViaTmp(jsonPath, `${JSON.stringify(summary, null, 2)}\n`);
+  await writeViaTmp(mdPath, renderSummaryMd(summary));
+  return { jsonPath, mdPath };
+}
+
+async function writeViaTmp(path, content) {
+  const tmp = `${path}.tmp-${process.pid}`;
+  await writeFile(tmp, content);
+  await rename(tmp, path);
+}

package/src/telemetry.mjs

@@ -0,0 +1,90 @@
+// telemetry.mjs — OPT-IN, fire-and-forget query telemetry (PLAN_SEONIX_TELEMETRY.md).
+//
+// The measurement contract is absolute: telemetry is OFF by default and the OFF path
+// must be BYTE-IDENTICAL — no file, no stdout/stderr change, ~zero cost. createTelemetry
+// returns NULL when disabled, so every call site is a single falsy check: `tel?.record(…)`.
+//
+// When enabled it appends ONE JSONL line per event to `<graphDir>/seonix-<id>.log`
+// (i.e. next to graph.json, in the repo's `.seonix/` artifact dir). Writes are
+// fire-and-forget with a swallowed catch: telemetry must NEVER throw, block, or write
+// to stdout/stderr (stdout is the MCP transport). A structural redact() keeps file
+// CONTENTS out of the log — it records only ids/paths/scores/sizes/counts.
+
+import { appendFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { uuidv7 } from "./uuid.mjs";
+
+/** Field names whose VALUES are (or embed) raw source and must never be logged. */
+const DROP_KEYS = new Set(["text", "content", "snippet"]);
+/** String fields longer than this are truncated — except query.raw (the user's own
+ *  question, which is the correlation key and is not file content). */
+const MAX_STR = 500;
+
+/** Enabled iff `SEONIX_TELEMETRY==="1"` OR `[telemetry] enabled=true` in the toml.
+ *  The env wins BOTH directions: `SEONIX_TELEMETRY==="0"` force-disables even when the
+ *  toml turns it on. Default OFF (anything but "1"/"0" in the env falls through to toml). */
+export function telemetryEnabled(env = process.env, toml = null) {
+  const e = env?.SEONIX_TELEMETRY;
+  if (e === "1") return true;
+  if (e === "0") return false;
+  return toml?.telemetry?.enabled === true;
+}
+
+/** The invocation id that correlates a log ↔ a host process. A host (the bench rig,
+ *  a wrapping agent) may stamp `SEONIX_INVOCATION_ID` so its trace/record and this log
+ *  share one id; absent, we mint a fresh time-sortable uuidv7. */
+export function invocationId(env = process.env) {
+  return (env?.SEONIX_INVOCATION_ID && String(env.SEONIX_INVOCATION_ID)) || uuidv7();
+}
+
+/** Structural redaction: drop any field named text/content/snippet at any depth, and
+ *  truncate string fields longer than MAX_STR — EXCEPT `query.raw`. Records only
+ *  ids/paths/scores/sizes/counts, never file contents. Pure; returns a fresh value. */
+export function redact(value, path = "") {
+  if (typeof value === "string") {
+    if (path === "query.raw") return value; // the correlation key — kept whole
+    return value.length > MAX_STR ? value.slice(0, MAX_STR) : value;
+  }
+  if (Array.isArray(value)) return value.map((v) => redact(v, path));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (DROP_KEYS.has(k)) continue;
+      out[k] = redact(v, path ? `${path}.${k}` : k);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Build a telemetry sink for one surface, or NULL when telemetry is disabled (the
+ * common OFF path — the caller's `tel?.record(…)` then costs one falsy check).
+ *
+ * When enabled, returns { id, file, record(fields) }. `record` stamps the schema-v1
+ * envelope ({v, id, seq, ts, surface}) onto the redacted, sparse caller fields and
+ * appends ONE JSONL line, fire-and-forget with a swallowed catch. `seq` is strictly
+ * increasing per sink. Record schema v1 fields (all sparse/optional — only include
+ * what a surface actually has):
+ *   { v, id, seq, ts, surface, tool,
+ *     query:    { raw, family, ambiguous, candidates },
+ *     response: { node_ids, scores, count, truncated, tier, topup },
+ *     perf:     { ms_total, ms_load, cold_load, graph_modules, graph_edges },
+ *     quality:  {},
+ *     cost:     { returned_chars, returned_tokens_est, cache_channel } }
+ */
+export function createTelemetry({ env = process.env, config, toml = null, surface } = {}) {
+  if (!telemetryEnabled(env, toml)) return null;
+  const id = invocationId(env);
+  const file = join(dirname(config.graphFile), `seonix-${id}.log`);
+  let seq = 0;
+  const record = (fields = {}) => {
+    try {
+      const line = { v: 1, id, seq: seq++, ts: new Date().toISOString(), surface, ...redact(fields) };
+      // Fire-and-forget: never await, never let a write error surface. Telemetry must
+      // not block a query or corrupt the MCP stdout transport.
+      appendFile(file, JSON.stringify(line) + "\n").catch(() => {});
+    } catch { /* redaction/serialisation must never throw a caller's turn */ }
+  };
+  return { id, file, record };
+}

package/src/timeline.mjs

@@ -15,7 +15,7 @@ import { repoOfId, assignRepo, isMultiRepo } from "./temporal.mjs";
 const esc = (s) =>
   String(s == null ? "" : s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
 
-export function extractTimeline(graph) {
+export function extractTimeline(graph, { limit = 0 } = {}) {
   const commits = [];
   const sessions = [];
   const churnByShort = new Map(); // short sha -> modules touched
@@ -66,7 +66,9 @@ export function extractTimeline(graph) {
   }
   const entries = [...commits, ...sessions];
   entries.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
-  return entries;
+  // limit > 0 keeps only the newest N entries (the tail of the oldest→newest sort);
+  // 0 (the default) returns everything. The ARRAY return type is unchanged either way.
+  return limit > 0 ? entries.slice(-limit) : entries;
 }
 
 // Per-repo badge palette (multi-repo timelines only) — hues distinct from the default
@@ -78,10 +80,16 @@ const repoColorMap = (repos) => new Map(repos.map((r, i) => [r, REPO_PALETTE[i %
 /** `nav` is the shared {name: href} nav object the viz CLI computes from the
  *  actual sibling output paths — header links render ONLY from its entries, so
  *  a page generated without siblings never carries dead links. */
-export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", generatedAt = "", nav = null } = {}) {
+export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", generatedAt = "", nav = null, totalCommits = null } = {}) {
   const base = repoUrl.replace(/\/+$/, "");
   const sessionCount = commits.filter((c) => c.type === "session").length;
   const commitCount = commits.length - sessionCount;
+  // When the timeline was truncated (extractTimeline {limit}), the caller passes the
+  // TRUE Commit total so the header reads "newest <n> of <total> commits". Absent, or
+  // not actually a truncation (total ≤ rendered), the header is byte-unchanged.
+  const commitLabel = totalCommits != null && totalCommits > commitCount
+    ? `newest ${commitCount} of ${totalCommits} commits`
+    : `${commitCount} commits`;
   const maxTouched = Math.max(1, ...commits.map((c) => c.touched));
   // P4 cross-repo: extractTimeline tags each commit of a MERGED graph with its `repo`.
   // When present, entries are labelled and colour-badged by repo on one global time
@@ -147,7 +155,7 @@ export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", ge
   li.sess{border-left:3px solid #e0af68;padding-left:5px} li.sess code,li.sess .m{color:#e0af68}
 </style></head><body>
 <header>
-  <span><b>seonix</b> commit timeline — ${commitCount} commits${sessionCount ? ` · ${sessionCount} chat session(s)` : ""}${multi ? ` · ${repos.length} repos` : ""}</span>${multi ? `\n  <span class="repolegend">${repoLegend}</span>` : ""}
+  <span><b>seonix</b> commit timeline — ${commitLabel}${sessionCount ? ` · ${sessionCount} chat session(s)` : ""}${multi ? ` · ${repos.length} repos` : ""}</span>${multi ? `\n  <span class="repolegend">${repoLegend}</span>` : ""}
   ${navLinks}
   ${base ? `<a href="${base}" target="_blank" rel="noopener">repository ↗</a>` : ""}
   <span class="meta">bars = modules touched per commit · generated from the seonix graph artifact${generatedAt ? ` (${esc(generatedAt.slice(0, 10))})` : ""}</span>