@danielblomma/cortex-mcp 2.1.0 → 2.1.4

package/scaffold/mcp/tests/graph-bulk-load.test.mjs

@@ -0,0 +1,258 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import ryugraph from "ryugraph";
+
+const MCP_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REPO_ROOT = path.resolve(MCP_DIR, "../..");
+const ONTOLOGY_SRC = path.join(REPO_ROOT, ".context", "ontology.cypher");
+const LOADER = path.join(MCP_DIR, "dist", "loadGraph.js");
+
+// Adversarial bodies: quotes, newlines, CRLF, commas, tabs, unicode,
+// backslashes, and empty strings — the cases CSV escaping must survive
+// while staying byte-identical to the prepared-statement loader.
+const NASTY = 'she said "hi",\nthen \tleft\r\nC:\\tmp åäö 日本語 🚀';
+
+function jsonl(records) {
+  return records.map((r) => JSON.stringify(r)).join("\n") + "\n";
+}
+
+function writeFixture(root) {
+  const cache = path.join(root, ".context", "cache");
+  fs.mkdirSync(cache, { recursive: true });
+  fs.writeFileSync(path.join(root, ".context", "config.yaml"), "source_paths:\n  - .\n", "utf8");
+  fs.copyFileSync(ONTOLOGY_SRC, path.join(root, ".context", "ontology.cypher"));
+
+  const w = (name, records) => fs.writeFileSync(path.join(cache, name), jsonl(records), "utf8");
+
+  w("entities.file.jsonl", [
+    { id: "file:a.ts", path: "src/a.ts", kind: "CODE", excerpt: NASTY, checksum: "c1", updated_at: "2026-01-01T00:00:00Z", source_of_truth: false, trust_level: 80, status: "active" },
+    { id: "file:b.ts", path: "src/b.ts", kind: "CODE", excerpt: "", checksum: "", updated_at: "2026-01-02T00:00:00Z", source_of_truth: false, trust_level: 80, status: "active" }
+  ]);
+  w("entities.rule.jsonl", [
+    { id: "rule:r1", title: 'Rule "one"', body: NASTY, scope: "global", priority: 3, updated_at: "2026-01-01T00:00:00Z", source_of_truth: true, trust_level: 95, status: "active" }
+  ]);
+  w("entities.adr.jsonl", [
+    { id: "adr:first", path: "docs/adr-1.md", title: "First", body: "decided,\nyes", decision_date: "2026-01-01", supersedes_id: "", source_of_truth: true, trust_level: 95, status: "active" },
+    { id: "adr:second", path: "docs/adr-2.md", title: "Second", body: "", decision_date: "2026-02-01", supersedes_id: "adr:first", source_of_truth: true, trust_level: 95, status: "active" }
+  ]);
+  w("entities.chunk.jsonl", [
+    { id: "chunk:a.ts#1", file_id: "file:a.ts", name: "doThing", kind: "function", signature: "doThing(x)", body: NASTY, description: "does, things\n", start_line: 1, end_line: 9, language: "typescript", exported: true, checksum: "k1", updated_at: "2026-01-01T00:00:00Z", source_of_truth: false, trust_level: 80, status: "active" },
+    { id: "chunk:b.ts#1", file_id: "file:b.ts", name: "empty", kind: "function", signature: "", body: "", description: "", start_line: 2, end_line: 2, language: "typescript", exported: false, checksum: "k2", updated_at: "2026-01-02T00:00:00Z", source_of_truth: false, trust_level: 80, status: "active" }
+  ]);
+  w("entities.module.jsonl", [
+    { id: "module:src", path: "src", name: "src", summary: "the, source\nmodule", file_count: 2, exported_symbols: "doThing", updated_at: "2026-01-01T00:00:00Z", source_of_truth: false, trust_level: 75, status: "active" },
+    { id: "module:src.sub", path: "src/sub", name: "sub", summary: "nested", file_count: 0, exported_symbols: "", updated_at: "2026-01-01T00:00:00Z", source_of_truth: false, trust_level: 75, status: "active" }
+  ]);
+  w("entities.project.jsonl", [
+    { id: "project:root", path: ".", name: "root", kind: "project", language: "typescript", target_framework: "", summary: "root proj", file_count: 2, updated_at: "2026-01-01T00:00:00Z", source_of_truth: false, trust_level: 80, status: "active" },
+    { id: "project:sub", path: "sub", name: "sub", kind: "project", language: "typescript", target_framework: "", summary: "sub, \"proj\"", file_count: 0, updated_at: "2026-01-01T00:00:00Z", source_of_truth: false, trust_level: 80, status: "active" }
+  ]);
+
+  // Edges, including dangling references that BOTH loaders must skip:
+  // file:ghost / chunk:ghost do not exist as nodes.
+  w("relations.constrains.jsonl", [
+    { from: "rule:r1", to: "file:a.ts", note: 'constrains, "tightly"' },
+    { from: "rule:r1", to: "file:ghost", note: "dangling" }
+  ]);
+  w("relations.implements.jsonl", [
+    { from: "file:a.ts", to: "rule:r1", note: "implements\nit" }
+  ]);
+  w("relations.supersedes.jsonl", [
+    { from: "adr:second", to: "adr:first", reason: "newer,\nbetter" }
+  ]);
+  w("relations.defines.jsonl", [
+    { from: "file:a.ts", to: "chunk:a.ts#1" },
+    { from: "file:b.ts", to: "chunk:b.ts#1" },
+    { from: "file:a.ts", to: "chunk:ghost" }
+  ]);
+  w("relations.calls.jsonl", [
+    { from: "chunk:a.ts#1", to: "chunk:b.ts#1", call_type: "direct" },
+    { from: "chunk:a.ts#1", to: "chunk:ghost", call_type: "direct" }
+  ]);
+  w("relations.imports.jsonl", [
+    { from: "chunk:a.ts#1", to: "file:b.ts", import_name: "./b" }
+  ]);
+  w("relations.contains.jsonl", [
+    { from: "module:src", to: "file:a.ts" },
+    { from: "module:src", to: "file:b.ts" }
+  ]);
+  w("relations.exports.jsonl", [
+    { from: "module:src", to: "chunk:a.ts#1" }
+  ]);
+  w("relations.includes_file.jsonl", [
+    { from: "project:root", to: "file:a.ts" },
+    { from: "project:root", to: "file:b.ts" }
+  ]);
+  // The remaining relation tables the COPY path also bulk-loads. Each carries a
+  // nasty note and at least one dangling edge so a typo in any single mapping
+  // (wrong endpoint set, wrong note column, missing filter) breaks equivalence.
+  w("relations.calls_sql.jsonl", [
+    { from: "file:a.ts", to: "chunk:b.ts#1", note: 'sql, "ref"\nline2' },
+    { from: "file:a.ts", to: "chunk:ghost", note: "dangling" }
+  ]);
+  w("relations.uses_config_key.jsonl", [
+    { from: "file:a.ts", to: "chunk:a.ts#1", note: "cfg key" }
+  ]);
+  w("relations.uses_resource_key.jsonl", [
+    { from: "file:b.ts", to: "chunk:a.ts#1", note: "res, key" }
+  ]);
+  w("relations.uses_setting_key.jsonl", [
+    { from: "file:a.ts", to: "chunk:b.ts#1", note: "setting\nkey" }
+  ]);
+  w("relations.contains_module.jsonl", [
+    { from: "module:src", to: "module:src.sub" },
+    { from: "module:src", to: "module:ghost" }
+  ]);
+  w("relations.references_project.jsonl", [
+    { from: "project:root", to: "project:sub", note: 'refs, "sub"' },
+    { from: "project:root", to: "project:ghost", note: "dangling" }
+  ]);
+  w("relations.uses_resource.jsonl", [
+    { from: "file:a.ts", to: "file:b.ts", note: "uses res" }
+  ]);
+  w("relations.uses_setting.jsonl", [
+    { from: "file:b.ts", to: "file:a.ts", note: "uses, setting" }
+  ]);
+  w("relations.uses_config.jsonl", [
+    { from: "file:a.ts", to: "file:b.ts", note: "uses cfg" },
+    { from: "file:a.ts", to: "file:ghost", note: "dangling" }
+  ]);
+  w("relations.transforms_config.jsonl", [
+    { from: "file:b.ts", to: "file:a.ts", note: "transforms\nconfig" }
+  ]);
+}
+
+const NODE_LABELS = ["File", "Rule", "ADR", "Chunk", "Module", "Project"];
+const REL_TYPES = [
+  "CONSTRAINS", "IMPLEMENTS", "SUPERSEDES", "DEFINES", "CALLS",
+  "IMPORTS", "CONTAINS", "EXPORTS", "INCLUDES_FILE",
+  "CALLS_SQL", "USES_CONFIG_KEY", "USES_RESOURCE_KEY", "USES_SETTING_KEY",
+  "CONTAINS_MODULE", "REFERENCES_PROJECT", "USES_RESOURCE", "USES_SETTING",
+  "USES_CONFIG", "TRANSFORMS_CONFIG"
+];
+
+function stable(value) {
+  return JSON.stringify(value, (_key, v) =>
+    typeof v === "bigint" ? Number(v) : v
+  );
+}
+
+function stripInternal(obj) {
+  const out = {};
+  for (const key of Object.keys(obj).sort()) {
+    if (key.startsWith("_")) continue;
+    out[key] = obj[key];
+  }
+  return out;
+}
+
+async function getAll(conn, query) {
+  const result = await conn.query(query);
+  const resolved = Array.isArray(result) ? result[result.length - 1] : result;
+  return resolved.getAll();
+}
+
+async function dumpGraph(dbPath) {
+  const db = new ryugraph.Database(dbPath);
+  const conn = new ryugraph.Connection(db);
+  const dump = { nodes: {}, rels: {} };
+
+  for (const label of NODE_LABELS) {
+    const rows = await getAll(conn, `MATCH (n:${label}) RETURN n ORDER BY n.id;`);
+    dump.nodes[label] = rows.map((row) => stripInternal(row.n)).sort((a, b) => a.id.localeCompare(b.id));
+  }
+  for (const type of REL_TYPES) {
+    const rows = await getAll(
+      conn,
+      `MATCH (a)-[r:${type}]->(b) RETURN a.id AS from, b.id AS to, r AS rel ORDER BY a.id, b.id;`
+    );
+    dump.rels[type] = rows
+      .map((row) => ({ from: row.from, to: row.to, props: stripInternal(row.rel) }))
+      .sort((a, b) => (a.from + a.to).localeCompare(b.from + b.to));
+  }
+  return dump;
+}
+
+function runLoader(root, { bulk }) {
+  return execFileSync("node", [LOADER], {
+    cwd: MCP_DIR,
+    env: {
+      ...process.env,
+      CORTEX_PROJECT_ROOT: root,
+      ...(bulk ? {} : { CORTEX_GRAPH_BULK_LOAD: "never" })
+    },
+    encoding: "utf8"
+  });
+}
+
+test("graph bulk COPY load produces a byte-identical graph to row-by-row inserts", async () => {
+  if (!fs.existsSync(ONTOLOGY_SRC)) {
+    // The loader needs a real ontology; skip rather than fail in stripped checkouts.
+    return;
+  }
+
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-graph-eq-"));
+  const rowRoot = path.join(base, "row");
+  // Put the bulk fixture under a directory whose name contains a double quote
+  // (where the OS permits it) so the COPY path literal is exercised against
+  // P3b: if the quote were not escaped, COPY would throw and silently fall back
+  // to row-by-row, failing the "loaded via COPY bulk import" assertion below.
+  const bulkRoot = path.join(base, process.platform === "win32" ? "bulk" : 'bu"lk');
+  fs.mkdirSync(rowRoot, { recursive: true });
+  fs.mkdirSync(bulkRoot, { recursive: true });
+
+  try {
+    writeFixture(rowRoot);
+    writeFixture(bulkRoot);
+
+    const rowOut = runLoader(rowRoot, { bulk: false });
+    const bulkOut = runLoader(bulkRoot, { bulk: true });
+
+    // The two paths must actually have been exercised.
+    assert.doesNotMatch(rowOut, /loaded via COPY bulk import/, "row run should not use bulk");
+    assert.match(bulkOut, /loaded via COPY bulk import/, "bulk run should use COPY");
+
+    const rowDump = await dumpGraph(path.join(rowRoot, ".context", "db", "graph.ryu"));
+    const bulkDump = await dumpGraph(path.join(bulkRoot, ".context", "db", "graph.ryu"));
+
+    for (const label of NODE_LABELS) {
+      assert.equal(
+        stable(bulkDump.nodes[label]),
+        stable(rowDump.nodes[label]),
+        `node table ${label} differs between bulk and row-by-row`
+      );
+    }
+    for (const type of REL_TYPES) {
+      assert.equal(
+        stable(bulkDump.rels[type]),
+        stable(rowDump.rels[type]),
+        `rel table ${type} differs between bulk and row-by-row`
+      );
+    }
+
+    // Spot-check the dangling-edge filtering actually dropped edges across a
+    // spread of the relation tables (node-pair filters of every endpoint kind).
+    assert.equal(bulkDump.rels.DEFINES.length, 2, "ghost DEFINES edge should be filtered");
+    assert.equal(bulkDump.rels.CALLS.length, 1, "ghost CALLS edge should be filtered");
+    assert.equal(bulkDump.rels.CALLS_SQL.length, 1, "ghost CALLS_SQL edge should be filtered");
+    assert.equal(bulkDump.rels.CONTAINS_MODULE.length, 1, "ghost CONTAINS_MODULE edge should be filtered");
+    assert.equal(bulkDump.rels.REFERENCES_PROJECT.length, 1, "ghost REFERENCES_PROJECT edge should be filtered");
+    assert.equal(bulkDump.rels.USES_CONFIG.length, 1, "ghost USES_CONFIG edge should be filtered");
+    // The SUPERSEDES reason and the new note columns must round-trip exactly.
+    assert.equal(bulkDump.rels.SUPERSEDES[0].props.reason, "newer,\nbetter");
+    assert.equal(bulkDump.rels.CALLS_SQL[0].props.note, 'sql, "ref"\nline2');
+    // And that the nasty body survived round-trip exactly.
+    const chunkA = bulkDump.nodes.Chunk.find((n) => n.id === "chunk:a.ts#1");
+    assert.equal(chunkA.body, NASTY, "adversarial chunk body must round-trip exactly");
+    const chunkB = bulkDump.nodes.Chunk.find((n) => n.id === "chunk:b.ts#1");
+    assert.equal(chunkB.body, "", "empty chunk body must stay an empty string, not null");
+  } finally {
+    fs.rmSync(base, { recursive: true, force: true });
+  }
+});

package/scaffold/mcp/tests/graph-csv.test.mjs

@@ -0,0 +1,118 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { toCsvCell, toCsvRow, writeCsv, toCopyPathLiteral, CSV_NULL_SENTINEL, CSV_COPY_OPTIONS } from "../dist/graphCsv.js";
+
+test("toCsvCell: quotes plain strings", () => {
+  assert.equal(toCsvCell("hello"), '"hello"');
+});
+
+test("toCsvCell: doubles internal quotes", () => {
+  assert.equal(toCsvCell('she said "hi"'), '"she said ""hi"""');
+});
+
+test("toCsvCell: preserves newlines, CRLF, commas, and tabs verbatim", () => {
+  assert.equal(toCsvCell("a\nb"), '"a\nb"');
+  assert.equal(toCsvCell("a\r\nb"), '"a\r\nb"');
+  assert.equal(toCsvCell("a,b,,c"), '"a,b,,c"');
+  assert.equal(toCsvCell("x\ty"), '"x\ty"');
+});
+
+test("toCsvCell: empty string becomes an empty quoted field, not the null sentinel", () => {
+  assert.equal(toCsvCell(""), '""');
+});
+
+test("toCsvCell: booleans render as true/false, numbers via String()", () => {
+  assert.equal(toCsvCell(true), '"true"');
+  assert.equal(toCsvCell(false), '"false"');
+  assert.equal(toCsvCell(0), '"0"');
+  assert.equal(toCsvCell(42), '"42"');
+  assert.equal(toCsvCell(-1), '"-1"');
+});
+
+test("toCsvCell: null and undefined collapse to empty field", () => {
+  assert.equal(toCsvCell(null), '""');
+  assert.equal(toCsvCell(undefined), '""');
+});
+
+test("toCsvCell: preserves unicode and backslashes", () => {
+  assert.equal(toCsvCell("åäö 日本語 🚀"), '"åäö 日本語 🚀"');
+  assert.equal(toCsvCell("C:\\path\\n"), '"C:\\path\\n"');
+});
+
+test("toCsvRow: joins cells with commas", () => {
+  assert.equal(toCsvRow(["a", 1, true]), '"a","1","true"');
+  assert.equal(toCsvRow(['a"b', "c,d"]), '"a""b","c,d"');
+});
+
+test("writeCsv: streams iterable rows with byte-equivalent CSV output", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-csv-"));
+  const filePath = path.join(dir, "rows.csv");
+  try {
+    function* rows() {
+      yield ["a", 1, true];
+      yield ['she said "hi"', "a\nb", ""];
+      yield [null, undefined, false];
+    }
+
+    const rowCount = writeCsv(filePath, ["c1", "c2", "c3"], rows());
+    const expected = [
+      toCsvRow(["c1", "c2", "c3"]),
+      toCsvRow(["a", 1, true]),
+      toCsvRow(['she said "hi"', "a\nb", ""]),
+      toCsvRow([null, undefined, false]),
+      ""
+    ].join("\n");
+
+    assert.equal(rowCount, 3);
+    assert.equal(fs.readFileSync(filePath, "utf8"), expected);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeCsv: empty iterables write only the header and return zero rows", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cortex-csv-empty-"));
+  const filePath = path.join(dir, "rows.csv");
+  try {
+    const rowCount = writeCsv(filePath, ["only"], []);
+
+    assert.equal(rowCount, 0);
+    assert.equal(fs.readFileSync(filePath, "utf8"), `${toCsvRow(["only"])}\n`);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("CSV_NULL_SENTINEL is a single NUL byte (impossible in any text-file-derived cell)", () => {
+  assert.equal(CSV_NULL_SENTINEL.length, 1);
+  assert.equal(CSV_NULL_SENTINEL.charCodeAt(0), 0);
+});
+
+test("CSV_COPY_OPTIONS disables parallel reads and empty-as-null", () => {
+  assert.match(CSV_COPY_OPTIONS, /PARALLEL=false/);
+  assert.match(CSV_COPY_OPTIONS, /HEADER=true/);
+  assert.match(CSV_COPY_OPTIONS, /NULL_STRINGS=\[/);
+});
+
+test("toCopyPathLiteral leaves a plain posix path untouched", () => {
+  assert.equal(toCopyPathLiteral("/repo/.context/cache/graph-import/File.csv"), "/repo/.context/cache/graph-import/File.csv");
+});
+
+test("toCopyPathLiteral backslash-escapes embedded double quotes", () => {
+  assert.equal(toCopyPathLiteral('/we"ird/File.csv'), '/we\\"ird/File.csv');
+  assert.equal(toCopyPathLiteral('/a"b"c/File.csv'), '/a\\"b\\"c/File.csv');
+});
+
+test("toCopyPathLiteral normalizes windows separators to forward slashes", () => {
+  assert.equal(toCopyPathLiteral("C:\\repo\\cache\\File.csv"), "C:/repo/cache/File.csv");
+});
+
+test("toCopyPathLiteral normalizes separators before escaping quotes", () => {
+  // The escaping backslash inserted for the quote must survive (not be turned
+  // into a slash): separators are normalized first, then quotes escaped.
+  assert.equal(toCopyPathLiteral('C:\\we"ird\\File.csv'), 'C:/we\\"ird/File.csv');
+});

package/scaffold/mcp/tests/lru-cache.test.mjs

@@ -0,0 +1,37 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { LruCache } from "../dist/lruCache.js";
+
+test("LruCache: stores and retrieves values", () => {
+  const cache = new LruCache(2);
+  cache.set("a", 1);
+  assert.equal(cache.get("a"), 1);
+  assert.equal(cache.get("missing"), undefined);
+});
+
+test("LruCache: evicts the least recently used entry at capacity", () => {
+  const cache = new LruCache(2);
+  cache.set("a", 1);
+  cache.set("b", 2);
+  cache.get("a"); // refresh a; b becomes LRU
+  cache.set("c", 3);
+  assert.equal(cache.get("b"), undefined);
+  assert.equal(cache.get("a"), 1);
+  assert.equal(cache.get("c"), 3);
+  assert.equal(cache.size, 2);
+});
+
+test("LruCache: overwriting a key refreshes it without growing", () => {
+  const cache = new LruCache(2);
+  cache.set("a", 1);
+  cache.set("b", 2);
+  cache.set("a", 9);
+  cache.set("c", 3); // evicts b, not a
+  assert.equal(cache.get("a"), 9);
+  assert.equal(cache.get("b"), undefined);
+});
+
+test("LruCache: rejects invalid capacity", () => {
+  assert.throws(() => new LruCache(0), /positive integer/);
+});

package/scaffold/mcp/tests/vector-index.test.mjs

@@ -0,0 +1,109 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { cosineSimilarity } from "../dist/searchCore.js";
+import { buildSearchResults } from "../dist/searchResults.js";
+
+// Reference cosine over float64 number[] — what the index used to store.
+function cosineFloat64(a, b) {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// Deterministic 384-dim vectors rounded to 6 decimals, mirroring the
+// canonical JSONL form the embedder writes.
+function makeVector(seed, dim = 384) {
+  const out = [];
+  let state = seed;
+  for (let i = 0; i < dim; i += 1) {
+    state = (state * 1103515245 + 12345) & 0x7fffffff;
+    const raw = (state / 0x7fffffff) * 2 - 1; // [-1, 1)
+    out.push(Number(raw.toFixed(6)));
+  }
+  return out;
+}
+
+test("cosineSimilarity (float32) matches the float64 reference within 1e-6 and after 4-decimal rounding", () => {
+  for (let pair = 0; pair < 50; pair += 1) {
+    const a = makeVector(pair * 7 + 1);
+    const b = makeVector(pair * 13 + 2);
+    const ref = cosineFloat64(a, b);
+    const got = cosineSimilarity(Float32Array.from(a), Float32Array.from(b));
+    assert.ok(
+      Math.abs(got - ref) < 1e-6,
+      `pair ${pair}: |${got} - ${ref}| = ${Math.abs(got - ref)} exceeds 1e-6`
+    );
+    // The API rounds embedding_score to 4 decimals — float32 cannot change it.
+    assert.equal(Number(got.toFixed(4)), Number(ref.toFixed(4)), `pair ${pair} differs at 4 decimals`);
+  }
+});
+
+test("cosineSimilarity handles identical and zero vectors", () => {
+  const v = Float32Array.from(makeVector(99));
+  assert.ok(Math.abs(cosineSimilarity(v, v) - 1) < 1e-6);
+  const zero = new Float32Array(384);
+  assert.equal(cosineSimilarity(v, zero), 0);
+  assert.equal(cosineSimilarity(new Float32Array(0), new Float32Array(0)), 0);
+});
+
+function makeEntity(id, overrides = {}) {
+  return {
+    id,
+    entity_type: "Chunk",
+    kind: "function",
+    label: id,
+    path: `src/${id}.ts`,
+    text: `text for ${id}`,
+    status: "active",
+    source_of_truth: false,
+    trust_level: 50,
+    updated_at: "2026-01-01T00:00:00Z",
+    snippet: "",
+    matched_rules: [],
+    ...overrides
+  };
+}
+
+test("buildSearchResults ranks via Float32Array vectors end-to-end", () => {
+  const query = Float32Array.from(makeVector(1));
+  const near = Float32Array.from(makeVector(1)); // identical → cosine 1
+  const far = Float32Array.from(makeVector(500)); // unrelated
+
+  const candidates = [makeEntity("near"), makeEntity("far")];
+  const results = buildSearchResults({
+    candidates,
+    degreeByEntity: new Map(),
+    queryTokens: ["text"],
+    queryPhrase: "text",
+    ranking: { semantic: 0.55, graph: 0.1, trust: 0.2, recency: 0.15 },
+    includeScores: true,
+    includeMatchedRules: false,
+    includeContent: false,
+    queryVector: query,
+    embeddingVectors: new Map([
+      ["near", near],
+      ["far", far]
+    ]),
+    topK: 2,
+    minLexicalRelevance: 0,
+    minVectorRelevance: 0,
+    semanticScorer: () => 0.5,
+    vectorScorer: cosineSimilarity,
+    recencyScorer: () => 0.5,
+    legacyDataAccessBooster: () => 0
+  });
+
+  assert.equal(results.length, 2);
+  assert.equal(results[0].id, "near", "identical-vector entity should rank first");
+  // embedding_score is reported rounded to 4 decimals; near==query → 1.0000.
+  const nearScore = results.find((r) => r.id === "near").embedding_score;
+  assert.equal(nearScore, 1, "identical float32 vectors score 1.0000");
+});

package/scaffold/mcp/tsconfig.json

@@ -9,5 +9,7 @@
     "esModuleInterop": true,
     "skipLibCheck": true
   },
-  "include": ["src/**/*.ts"]
+  "include": [
+    "src/**/*.ts"
+  ]
 }

package/scaffold/scripts/bootstrap.sh

@@ -23,10 +23,42 @@ info "pipeline: deps -> ingest -> embeddings -> graph -> status"
 
 mkdir -p "$MCP_DIR/.npm-cache"
 
+# Runs `npm install` for a prefix only when its package-lock.json changed
+# since the last successful install (or node_modules is missing). A warm
+# no-op install still costs npm tens of seconds per prefix; the lockfile-hash
+# marker makes repeat bootstraps and updates skip it entirely.
+install_deps_if_changed() {
+  local prefix="$1" cache="$2"
+  local lock="$prefix/package-lock.json"
+  local marker="$prefix/node_modules/.cortex-lock-hash"
+  local current=""
+  if [ -f "$lock" ]; then
+    current=$(node -e '
+      const crypto = require("node:crypto");
+      const fs = require("node:fs");
+      // Node version is part of the key: native deps must reinstall after a
+      // runtime switch even when the lockfile is unchanged.
+      const hash = crypto.createHash("sha256");
+      hash.update(process.version);
+      hash.update(fs.readFileSync(process.argv[1]));
+      console.log(hash.digest("hex"));
+    ' "$lock" 2>/dev/null || true)
+  fi
+  if [ -n "$current" ] && [ -d "$prefix/node_modules" ] && [ -f "$marker" ] \
+    && [ "$(cat "$marker" 2>/dev/null)" = "$current" ]; then
+    info "dependencies up to date in $prefix (lockfile unchanged)"
+    return 0
+  fi
+  NPM_CONFIG_CACHE="$cache" npm --prefix "$prefix" install --no-fund --no-update-notifier --loglevel=warn
+  if [ -n "$current" ]; then
+    printf '%s' "$current" > "$marker" || true
+  fi
+}
+
 step "Installing MCP dependencies"
 info "note: upstream RyuGraph dependencies may print deprecation warnings during install"
-NPM_CONFIG_CACHE="$MCP_DIR/.npm-cache" npm --prefix "$MCP_DIR" install --no-fund --no-update-notifier --loglevel=warn
-NPM_CONFIG_CACHE="$REPO_ROOT/.context/scripts/parsers/.npm-cache" npm --prefix "$REPO_ROOT/.context/scripts/parsers" install --no-fund --no-update-notifier --loglevel=warn
+install_deps_if_changed "$MCP_DIR" "$MCP_DIR/.npm-cache"
+install_deps_if_changed "$REPO_ROOT/.context/scripts/parsers" "$REPO_ROOT/.context/scripts/parsers/.npm-cache"
 
 source "$SCRIPT_DIR/lib/enterprise-check.sh"
 

package/scaffold/scripts/dashboard.mjs

@@ -17,7 +17,7 @@ const CONFIG_PATH = path.join(CONTEXT_DIR, "config.yaml");
 const SUPPORTED_TEXT_EXTENSIONS = new Set([
   ".md", ".mdx", ".txt", ".adoc", ".rst",
   ".yaml", ".yml", ".json", ".toml", ".csv",
-  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs",
   ".py", ".go", ".java", ".cs", ".rb", ".rs", ".php", ".swift", ".kt",
   ".sql", ".sh", ".bash", ".zsh", ".ps1",
   ".c", ".h", ".cpp", ".hpp", ".cc", ".hh"