@danielblomma/cortex-mcp 2.1.1 → 2.2.0

package/scaffold/mcp/src/jsonl.ts

@@ -1,24 +1,79 @@
 import fs from "node:fs";
+import { StringDecoder } from "node:string_decoder";
 import type { JsonObject, JsonValue } from "./types.js";
 
-export function readJsonl(filePath: string): JsonObject[] {
+function parseJsonlLine(line: string): JsonObject | null {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(trimmed) as JsonObject;
+  } catch {
+    return null;
+  }
+}
+
+export function* readJsonlRecords(filePath: string): Generator<JsonObject> {
   if (!fs.existsSync(filePath)) {
-    return [];
+    return;
   }
 
-  return fs
-    .readFileSync(filePath, "utf8")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .map((line) => {
-      try {
-        return JSON.parse(line) as JsonObject;
-      } catch {
-        return null;
+  const fd = fs.openSync(filePath, "r");
+  const decoder = new StringDecoder("utf8");
+  const buffer = Buffer.allocUnsafe(64 * 1024);
+  let carry = "";
+
+  try {
+    while (true) {
+      const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) {
+        break;
       }
-    })
-    .filter((value): value is JsonObject => value !== null);
+
+      carry += decoder.write(buffer.subarray(0, bytesRead));
+      let lineStart = 0;
+      let newlineIndex = carry.indexOf("\n", lineStart);
+      while (newlineIndex !== -1) {
+        const parsed = parseJsonlLine(carry.slice(lineStart, newlineIndex));
+        if (parsed) {
+          yield parsed;
+        }
+        lineStart = newlineIndex + 1;
+        newlineIndex = carry.indexOf("\n", lineStart);
+      }
+      carry = carry.slice(lineStart);
+    }
+
+    carry += decoder.end();
+    const parsed = parseJsonlLine(carry);
+    if (parsed) {
+      yield parsed;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+export function readJsonl(filePath: string): JsonObject[] {
+  return Array.from(readJsonlRecords(filePath));
+}
+
+export function writeJsonlRecords(filePath: string, records: Iterable<unknown>): number {
+  const fd = fs.openSync(filePath, "w");
+  let count = 0;
+
+  try {
+    for (const record of records) {
+      fs.writeSync(fd, `${JSON.stringify(record)}\n`, undefined, "utf8");
+      count += 1;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return count;
 }
 
 export function asString(value: JsonValue | undefined, fallback = ""): string {

package/scaffold/mcp/src/loadGraph.ts

@@ -3,9 +3,11 @@ import path from "node:path";
 import ryugraph, { type Connection, type PreparedStatement, type QueryResult, type RyuValue } from "ryugraph";
 import { readJsonl, asString, asNumber, asBoolean } from "./jsonl.js";
 import { CACHE_DIR, CONTEXT_DIR, DB_PATH } from "./paths.js";
+import { CSV_COPY_OPTIONS, writeCsv, toCopyPathLiteral, type CsvValue } from "./graphCsv.js";
 import type { JsonObject } from "./types.js";
 
 const ONTOLOGY_PATH = path.join(CONTEXT_DIR, "ontology.cypher");
+const GRAPH_IMPORT_DIR = path.join(CACHE_DIR, "graph-import");
 const BATCH_SIZE = 50;
 
 async function executeBatch(
@@ -428,25 +430,244 @@ function warnIfOptionalFilesMissing(): void {
   );
 }
 
-async function main(): Promise<void> {
-  const args = new Set(process.argv.slice(2));
-  const reset = !args.has("--no-reset");
+type GraphData = {
+  fileEntities: FileEntity[];
+  ruleEntities: RuleEntity[];
+  adrEntities: AdrEntity[];
+  chunkEntities: ChunkEntity[];
+  moduleEntities: ModuleEntity[];
+  projectEntities: ProjectEntity[];
+  constrains: Relation[];
+  implementsEdges: Relation[];
+  supersedes: Relation[];
+  defines: Relation[];
+  calls: CallRelation[];
+  callsSql: Relation[];
+  usesConfigKey: Relation[];
+  usesResourceKey: Relation[];
+  usesSettingKey: Relation[];
+  imports: ImportRelation[];
+  contains: Relation[];
+  containsModule: Relation[];
+  exports: Relation[];
+  includesFile: Relation[];
+  referencesProject: Relation[];
+  usesResource: Relation[];
+  usesSetting: Relation[];
+  usesConfig: Relation[];
+  transformsConfig: Relation[];
+};
 
-  await ensureRequiredFiles();
-  warnIfOptionalFilesMissing();
+function parseGraphData(): GraphData {
+  return {
+    fileEntities: parseFiles(readEntityFile("entities.file.jsonl")),
+    ruleEntities: parseRules(readEntityFile("entities.rule.jsonl")),
+    adrEntities: parseAdrs(readEntityFile("entities.adr.jsonl")),
+    chunkEntities: parseChunks(readEntityFile("entities.chunk.jsonl")),
+    moduleEntities: parseModules(readEntityFile("entities.module.jsonl")),
+    projectEntities: parseProjects(readEntityFile("entities.project.jsonl")),
+    constrains: parseRelations("relations.constrains.jsonl", "note"),
+    implementsEdges: parseRelations("relations.implements.jsonl", "note"),
+    supersedes: parseRelations("relations.supersedes.jsonl", "reason"),
+    defines: parseSimpleRelations("relations.defines.jsonl"),
+    calls: parseCallRelations("relations.calls.jsonl"),
+    callsSql: parseRelations("relations.calls_sql.jsonl", "note"),
+    usesConfigKey: parseRelations("relations.uses_config_key.jsonl", "note"),
+    usesResourceKey: parseRelations("relations.uses_resource_key.jsonl", "note"),
+    usesSettingKey: parseRelations("relations.uses_setting_key.jsonl", "note"),
+    imports: parseImportRelations("relations.imports.jsonl"),
+    contains: parseSimpleRelations("relations.contains.jsonl"),
+    containsModule: parseSimpleRelations("relations.contains_module.jsonl"),
+    exports: parseSimpleRelations("relations.exports.jsonl"),
+    includesFile: parseSimpleRelations("relations.includes_file.jsonl"),
+    referencesProject: parseRelations("relations.references_project.jsonl", "note"),
+    usesResource: parseRelations("relations.uses_resource.jsonl", "note"),
+    usesSetting: parseRelations("relations.uses_setting.jsonl", "note"),
+    usesConfig: parseRelations("relations.uses_config.jsonl", "note"),
+    transformsConfig: parseRelations("relations.transforms_config.jsonl", "note")
+  };
+}
 
-  if (reset) {
-    fs.rmSync(DB_PATH, { recursive: true, force: true });
-    fs.rmSync(`${DB_PATH}.wal`, { force: true });
-    fs.rmSync(`${DB_PATH}.shm`, { force: true });
+// Mirror the MATCH (...)-CREATE skip semantics of the prepared-statement
+// loader: an edge whose endpoint node was never created is silently dropped.
+// COPY into a rel table instead errors on an unknown primary key, so edges
+// must be pre-filtered against the node-id sets to stay byte-identical.
+function filterEdges<T extends { from: string; to: string }>(
+  edges: Iterable<T>,
+  fromSet: Set<string>,
+  toSet: Set<string>
+): Iterable<T> {
+  return (function* filteredEdges() {
+    for (const edge of edges) {
+      if (fromSet.has(edge.from) && toSet.has(edge.to)) {
+        yield edge;
+      }
+    }
+  })();
+}
+
+function* ids<T extends { id: string }>(items: Iterable<T>): Iterable<string> {
+  for (const item of items) {
+    yield item.id;
   }
-  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+}
 
-  const db = new ryugraph.Database(DB_PATH);
-  const conn = new ryugraph.Connection(db);
+function* csvRows<T>(items: Iterable<T>, toRow: (item: T) => CsvValue[]): Iterable<CsvValue[]> {
+  for (const item of items) {
+    yield toRow(item);
+  }
+}
 
-  const ontologyStatements = parseOntologyStatements(fs.readFileSync(ONTOLOGY_PATH, "utf8"));
-  await executeStatements(conn, ontologyStatements);
+async function copyTable(
+  conn: Connection,
+  table: string,
+  header: string[],
+  rows: Iterable<CsvValue[]>
+): Promise<void> {
+  const csvPath = path.join(GRAPH_IMPORT_DIR, `${table}.csv`);
+  const rowCount = writeCsv(csvPath, header, rows);
+  if (rowCount === 0) {
+    fs.rmSync(csvPath, { force: true });
+    return;
+  }
+  // ryugraph parses COPY's path as a double-quoted literal; toCopyPathLiteral
+  // normalizes separators and escapes any embedded quote so a repo/cache path
+  // containing a double quote still bulk-loads instead of falling back.
+  const csvForCopy = toCopyPathLiteral(csvPath);
+  await conn.query(`COPY ${table} FROM "${csvForCopy}" ${CSV_COPY_OPTIONS};`);
+}
+
+// Bulk path: one COPY per table instead of a prepared statement per row.
+// Only used on the reset path, where the freshly created tables are empty.
+// Produces a byte-identical graph to rowByRowLoad (same parsed arrays, same
+// node-then-edge order, same dangling-edge filtering).
+async function bulkLoad(conn: Connection, data: GraphData): Promise<void> {
+  fs.rmSync(GRAPH_IMPORT_DIR, { recursive: true, force: true });
+  fs.mkdirSync(GRAPH_IMPORT_DIR, { recursive: true });
+
+  try {
+    const fileIds = new Set(ids(data.fileEntities));
+    const ruleIds = new Set(ids(data.ruleEntities));
+    const adrIds = new Set(ids(data.adrEntities));
+    const chunkIds = new Set(ids(data.chunkEntities));
+    const moduleIds = new Set(ids(data.moduleEntities));
+    const projectIds = new Set(ids(data.projectEntities));
+
+  // Nodes first — edges reference them by primary key.
+  await copyTable(
+    conn,
+    "File",
+    ["id", "path", "kind", "excerpt", "checksum", "updated_at", "source_of_truth", "trust_level", "status"],
+    csvRows(data.fileEntities, (e) => [
+      e.id, e.path, e.kind, e.excerpt, e.checksum, e.updated_at, e.source_of_truth, e.trust_level, e.status
+    ])
+  );
+  await copyTable(
+    conn,
+    "Rule",
+    ["id", "title", "body", "scope", "priority", "updated_at", "source_of_truth", "trust_level", "status"],
+    csvRows(data.ruleEntities, (e) => [
+      e.id, e.title, e.body, e.scope, e.priority, e.updated_at, e.source_of_truth, e.trust_level, e.status
+    ])
+  );
+  await copyTable(
+    conn,
+    "ADR",
+    ["id", "path", "title", "body", "decision_date", "supersedes_id", "source_of_truth", "trust_level", "status"],
+    csvRows(data.adrEntities, (e) => [
+      e.id, e.path, e.title, e.body, e.decision_date, e.supersedes_id, e.source_of_truth, e.trust_level, e.status
+    ])
+  );
+  await copyTable(
+    conn,
+    "Chunk",
+    [
+      "id", "file_id", "name", "kind", "signature", "body", "description", "start_line", "end_line",
+      "language", "exported", "checksum", "updated_at", "source_of_truth", "trust_level", "status"
+    ],
+    csvRows(data.chunkEntities, (e) => [
+      e.id, e.file_id, e.name, e.kind, e.signature, e.body, e.description, e.start_line, e.end_line,
+      e.language, e.exported, e.checksum, e.updated_at, e.source_of_truth, e.trust_level, e.status
+    ])
+  );
+  await copyTable(
+    conn,
+    "Module",
+    ["id", "path", "name", "summary", "file_count", "exported_symbols", "updated_at", "source_of_truth", "trust_level", "status"],
+    csvRows(data.moduleEntities, (e) => [
+      e.id, e.path, e.name, e.summary, e.file_count, e.exported_symbols, e.updated_at, e.source_of_truth, e.trust_level, e.status
+    ])
+  );
+  await copyTable(
+    conn,
+    "Project",
+    [
+      "id", "path", "name", "kind", "language", "target_framework", "summary", "file_count",
+      "updated_at", "source_of_truth", "trust_level", "status"
+    ],
+    csvRows(data.projectEntities, (e) => [
+      e.id, e.path, e.name, e.kind, e.language, e.target_framework, e.summary, e.file_count,
+      e.updated_at, e.source_of_truth, e.trust_level, e.status
+    ])
+  );
+
+  // Edges, filtered to existing endpoints. Header names are positional only
+  // (COPY into a rel table reads src key, dst key, then properties in schema
+  // order), but emitting real names keeps the CSVs self-describing.
+  await copyTable(conn, "CONSTRAINS", ["from", "to", "note"],
+    csvRows(filterEdges(data.constrains, ruleIds, fileIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "IMPLEMENTS", ["from", "to", "note"],
+    csvRows(filterEdges(data.implementsEdges, fileIds, ruleIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "SUPERSEDES", ["from", "to", "reason"],
+    csvRows(filterEdges(data.supersedes, adrIds, adrIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "DEFINES", ["from", "to"],
+    csvRows(filterEdges(data.defines, fileIds, chunkIds), (e) => [e.from, e.to]));
+  await copyTable(conn, "CALLS", ["from", "to", "call_type"],
+    csvRows(filterEdges(data.calls, chunkIds, chunkIds), (e) => [e.from, e.to, e.call_type]));
+  await copyTable(conn, "IMPORTS", ["from", "to", "import_name"],
+    csvRows(filterEdges(data.imports, chunkIds, fileIds), (e) => [e.from, e.to, e.import_name]));
+  await copyTable(conn, "CALLS_SQL", ["from", "to", "note"],
+    csvRows(filterEdges(data.callsSql, fileIds, chunkIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "USES_CONFIG_KEY", ["from", "to", "note"],
+    csvRows(filterEdges(data.usesConfigKey, fileIds, chunkIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "USES_RESOURCE_KEY", ["from", "to", "note"],
+    csvRows(filterEdges(data.usesResourceKey, fileIds, chunkIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "USES_SETTING_KEY", ["from", "to", "note"],
+    csvRows(filterEdges(data.usesSettingKey, fileIds, chunkIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "CONTAINS", ["from", "to"],
+    csvRows(filterEdges(data.contains, moduleIds, fileIds), (e) => [e.from, e.to]));
+  await copyTable(conn, "CONTAINS_MODULE", ["from", "to"],
+    csvRows(filterEdges(data.containsModule, moduleIds, moduleIds), (e) => [e.from, e.to]));
+  await copyTable(conn, "EXPORTS", ["from", "to"],
+    csvRows(filterEdges(data.exports, moduleIds, chunkIds), (e) => [e.from, e.to]));
+  await copyTable(conn, "INCLUDES_FILE", ["from", "to"],
+    csvRows(filterEdges(data.includesFile, projectIds, fileIds), (e) => [e.from, e.to]));
+  await copyTable(conn, "REFERENCES_PROJECT", ["from", "to", "note"],
+    csvRows(filterEdges(data.referencesProject, projectIds, projectIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "USES_RESOURCE", ["from", "to", "note"],
+    csvRows(filterEdges(data.usesResource, fileIds, fileIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "USES_SETTING", ["from", "to", "note"],
+    csvRows(filterEdges(data.usesSetting, fileIds, fileIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "USES_CONFIG", ["from", "to", "note"],
+    csvRows(filterEdges(data.usesConfig, fileIds, fileIds), (e) => [e.from, e.to, e.note]));
+  await copyTable(conn, "TRANSFORMS_CONFIG", ["from", "to", "note"],
+    csvRows(filterEdges(data.transformsConfig, fileIds, fileIds), (e) => [e.from, e.to, e.note]));
+  } finally {
+    fs.rmSync(GRAPH_IMPORT_DIR, { recursive: true, force: true });
+  }
+}
+
+// Original loader: clears every table, then inserts each node/edge through a
+// prepared statement in batches. Used for --no-reset and as the fallback when
+// bulk COPY fails. MATCH-based edge inserts skip dangling endpoints silently.
+async function rowByRowLoad(conn: Connection, data: GraphData): Promise<void> {
+  const {
+    fileEntities, ruleEntities, adrEntities, chunkEntities, moduleEntities, projectEntities,
+    constrains, implementsEdges, supersedes, defines, calls, callsSql,
+    usesConfigKey, usesResourceKey, usesSettingKey, imports,
+    contains, containsModule, exports, includesFile, referencesProject,
+    usesResource, usesSetting, usesConfig, transformsConfig
+  } = data;
 
   // Delete all relations first, then all nodes, to avoid orphaned edges
   await conn.query("MATCH (a:ADR)-[r:SUPERSEDES]->(b:ADR) DELETE r;");
@@ -477,32 +698,6 @@ async function main(): Promise<void> {
   await conn.query("MATCH (n:Project) DELETE n;");
   await conn.query("MATCH (n:File) DELETE n;");
 
-  const fileEntities = parseFiles(readEntityFile("entities.file.jsonl"));
-  const ruleEntities = parseRules(readEntityFile("entities.rule.jsonl"));
-  const adrEntities = parseAdrs(readEntityFile("entities.adr.jsonl"));
-  const chunkEntities = parseChunks(readEntityFile("entities.chunk.jsonl"));
-  const constrains = parseRelations("relations.constrains.jsonl", "note");
-  const implementsEdges = parseRelations("relations.implements.jsonl", "note");
-  const supersedes = parseRelations("relations.supersedes.jsonl", "reason");
-  const defines = parseSimpleRelations("relations.defines.jsonl");
-  const calls = parseCallRelations("relations.calls.jsonl");
-  const callsSql = parseRelations("relations.calls_sql.jsonl", "note");
-  const usesConfigKey = parseRelations("relations.uses_config_key.jsonl", "note");
-  const usesResourceKey = parseRelations("relations.uses_resource_key.jsonl", "note");
-  const usesSettingKey = parseRelations("relations.uses_setting_key.jsonl", "note");
-  const imports = parseImportRelations("relations.imports.jsonl");
-  const moduleEntities = parseModules(readEntityFile("entities.module.jsonl"));
-  const projectEntities = parseProjects(readEntityFile("entities.project.jsonl"));
-  const contains = parseSimpleRelations("relations.contains.jsonl");
-  const containsModule = parseSimpleRelations("relations.contains_module.jsonl");
-  const exports = parseSimpleRelations("relations.exports.jsonl");
-  const includesFile = parseSimpleRelations("relations.includes_file.jsonl");
-  const referencesProject = parseRelations("relations.references_project.jsonl", "note");
-  const usesResource = parseRelations("relations.uses_resource.jsonl", "note");
-  const usesSetting = parseRelations("relations.uses_setting.jsonl", "note");
-  const usesConfig = parseRelations("relations.uses_config.jsonl", "note");
-  const transformsConfig = parseRelations("relations.transforms_config.jsonl", "note");
-
   const insertFile = await conn.prepare(`
     CREATE (f:File {
       id: $id,
@@ -725,6 +920,47 @@ async function main(): Promise<void> {
   await executeBatch(conn, insertUsesSetting, usesSetting);
   await executeBatch(conn, insertUsesConfig, usesConfig);
   await executeBatch(conn, insertTransformsConfig, transformsConfig);
+}
+
+async function main(): Promise<void> {
+  const args = new Set(process.argv.slice(2));
+  const reset = !args.has("--no-reset");
+
+  await ensureRequiredFiles();
+  warnIfOptionalFilesMissing();
+
+  if (reset) {
+    fs.rmSync(DB_PATH, { recursive: true, force: true });
+    fs.rmSync(`${DB_PATH}.wal`, { force: true });
+    fs.rmSync(`${DB_PATH}.shm`, { force: true });
+  }
+  fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+
+  const db = new ryugraph.Database(DB_PATH);
+  const conn = new ryugraph.Connection(db);
+
+  const ontologyStatements = parseOntologyStatements(fs.readFileSync(ONTOLOGY_PATH, "utf8"));
+  await executeStatements(conn, ontologyStatements);
+
+  const data = parseGraphData();
+
+  const bulkEnabled = reset && process.env.CORTEX_GRAPH_BULK_LOAD !== "never";
+  let usedBulk = false;
+  if (bulkEnabled) {
+    try {
+      await bulkLoad(conn, data);
+      usedBulk = true;
+      console.log("[graph-load] loaded via COPY bulk import");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(
+        `[graph-load] bulk COPY load failed (${message}); falling back to row-by-row inserts`
+      );
+    }
+  }
+  if (!usedBulk) {
+    await rowByRowLoad(conn, data);
+  }
 
   const fileCount = await rows(await conn.query("MATCH (f:File) RETURN count(*) AS count;"));
   const ruleCount = await rows(await conn.query("MATCH (r:Rule) RETURN count(*) AS count;"));

package/scaffold/mcp/src/lruCache.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal LRU cache on Map insertion order: reads refresh recency, writes
+ * evict the least-recently-used entry once capacity is reached.
+ */
+export class LruCache<K, V> {
+  private readonly capacity: number;
+  private readonly entries = new Map<K, V>();
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new Error(`LruCache capacity must be a positive integer, got ${capacity}`);
+    }
+    this.capacity = capacity;
+  }
+
+  get(key: K): V | undefined {
+    if (!this.entries.has(key)) {
+      return undefined;
+    }
+    const value = this.entries.get(key) as V;
+    this.entries.delete(key);
+    this.entries.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= this.capacity) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) {
+        this.entries.delete(oldest.value);
+      }
+    }
+    this.entries.set(key, value);
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+}

package/scaffold/mcp/src/searchCore.ts

@@ -251,7 +251,7 @@ export function legacyDataAccessBoost(entity: SearchEntity, queryTokens: string[
   return boost;
 }
 
-export function cosineSimilarity(a: number[], b: number[]): number {
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
   if (a.length === 0 || b.length === 0 || a.length !== b.length) {
     return 0;
   }

package/scaffold/mcp/src/searchResults.ts

@@ -23,13 +23,13 @@ export function buildSearchResults(params: {
   includeScores: boolean;
   includeMatchedRules: boolean;
   includeContent: boolean;
-  queryVector: number[] | null;
-  embeddingVectors: Map<string, number[]>;
+  queryVector: Float32Array | null;
+  embeddingVectors: Map<string, Float32Array>;
   topK: number;
   minLexicalRelevance: number;
   minVectorRelevance: number;
   semanticScorer: (queryTokens: string[], queryPhrase: string, text: string) => number;
-  vectorScorer: (a: number[], b: number[]) => number;
+  vectorScorer: (a: Float32Array, b: Float32Array) => number;
   recencyScorer: (isoDate: string) => number;
   legacyDataAccessBooster: (entity: SearchEntity, queryTokens: string[], queryPhrase: string) => number;
 }): Record<string, unknown>[] {

package/scaffold/mcp/src/types.ts

@@ -151,7 +151,12 @@ export type SearchEntity = {
 
 export type EmbeddingIndex = {
   model: string | null;
-  vectors: Map<string, number[]>;
+  // Stored as Float32Array (not number[]): ~4x less memory than boxed
+  // float64 arrays, and a monomorphic typed-array cosine loop. The JSONL on
+  // disk stays canonical 6-decimal text; the float32 re-encode perturbs
+  // values by ~1e-8, far below the rounding already applied and below the
+  // 4-decimal score rounding at the API boundary.
+  vectors: Map<string, Float32Array>;
   warning?: string;
 };