Phase 1: OPFSVectorStore, MemoryVectorStore, IndexedDbMetadataStore + persistence tests

- core/types.ts: canonical entity types (Page, Book, Volume, Shelf, Edge,
  MetroidNeighbor, MetroidSubgraph) and VectorStore / MetadataStore interfaces
- storage/OPFSVectorStore.ts: append-only OPFS binary vector file with
  serialised write queue and byte-offset semantics
- storage/MemoryVectorStore.ts: in-memory VectorStore (identical semantics,
  used in tests and as a safe fallback)
- storage/IndexedDbMetadataStore.ts: full MetadataStore backed by IndexedDB –
  CRUD for all entities, reverse-index maintenance (page→book, book→volume,
  volume→shelf), Metroid NN neighbour index with bounded BFS subgraph
  expansion, and dirty-volume recalc flags
- tests/Persistence.test.ts: 34 round-trip tests covering VectorStore
  contract via MemoryVectorStore, OPFSVectorStore with stubbed OPFS, and
  IndexedDbMetadataStore via fake-indexeddb
- tsconfig.json: extend include to cover core/** and storage/**
- package.json: add fake-indexeddb devDependency
- CORTEX-DESIGN-PLAN-TODO.md: mark completed P1 items

Author: devlux76

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run build
+
+      - name: Test
+        run: npm test

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+coverage/
+*.log

BackendKind.ts

@@ -0,0 +1,40 @@
+export type BackendKind = "webnn" | "webgpu" | "webgl" | "wasm";
+
+function hasWebGpuSupport(): boolean {
+  return (
+    typeof navigator !== "undefined" &&
+    typeof (navigator as Navigator & { gpu?: unknown }).gpu !== "undefined"
+  );
+}
+
+function hasWebGl2Support(): boolean {
+  if (typeof document === "undefined") {
+    return false;
+  }
+
+  const canvas = document.createElement("canvas");
+  return canvas.getContext("webgl2") !== null;
+}
+
+function hasWebNnSupport(): boolean {
+  return (
+    typeof navigator !== "undefined" &&
+    typeof (navigator as Navigator & { ml?: unknown }).ml !== "undefined"
+  );
+}
+
+export function detectBackend(): BackendKind {
+  if (hasWebGpuSupport()) {
+    return "webgpu";
+  }
+
+  if (hasWebGl2Support()) {
+    return "webgl";
+  }
+
+  if (hasWebNnSupport()) {
+    return "webnn";
+  }
+
+  return "wasm";
+}

CORTEX-DESIGN-PLAN-TODO.md

@@ -254,17 +254,17 @@ Priority legend:
 10. Add smoke test that instantiates each backend or cleanly falls back.
 
 ### P1 (v1 core)
-1. Implement `OPFSVectorStore.appendVector` and `readVector`.
-2. Implement `IndexedDbMetadataStore` entity CRUD methods.
-3. Implement metadata helper indexes (`page->book`, `book->volume`, `volume->shelf`).
-4. Implement `putMetroidNeighbors` and `getMetroidNeighbors`.
-5. Implement `getInducedMetroidSubgraph` with bounded BFS.
+1. ~~Implement `OPFSVectorStore.appendVector` and `readVector`.~~ ✅ Done (Phase 1, 2026-03-11)
+2. ~~Implement `IndexedDbMetadataStore` entity CRUD methods.~~ ✅ Done (Phase 1, 2026-03-11)
+3. ~~Implement metadata helper indexes (`page->book`, `book->volume`, `volume->shelf`).~~ ✅ Done (Phase 1, 2026-03-11)
+4. ~~Implement `putMetroidNeighbors` and `getMetroidNeighbors`.~~ ✅ Done (Phase 1, 2026-03-11)
+5. ~~Implement `getInducedMetroidSubgraph` with bounded BFS.~~ ✅ Done (Phase 1, 2026-03-11)
 6. Implement page chunking utility and deterministic page ID generation.
 7. Implement page signature creation and verification helpers.
 8. Implement Hippocampus ingest orchestration.
 9. Implement fast Metroid insert path for newly ingested pages.
 10. Implement reverse neighbor update path with bounded degree.
-11. Implement dirty-volume recalc flagging in metadata.
+11. ~~Implement dirty-volume recalc flagging in metadata.~~ ✅ Done (Phase 1, 2026-03-11)
 12. Implement Shelf/Volume/Book/Page ranking in Cortex query.
 13. Implement query seed selection threshold logic.
 14. Implement `findOpenTSPPath` with dummy-node open-path strategy.
@@ -275,7 +275,7 @@ Priority legend:
 19. Implement full neighborhood recalc for dirty volumes.
 20. Implement split/merge hooks for unstable clusters.
 21. Add end-to-end test: ingest -> query -> coherent ordered response.
-22. Add restart persistence test for vectors + metadata.
+22. ~~Add restart persistence test for vectors + metadata.~~ ✅ Done (Phase 1, 2026-03-11)
 23. Add regression tests for neighbor symmetry and bounded degree.
 24. Add benchmark harness and first baseline capture.
 

CreateVectorBackend.ts

@@ -1,3 +1,10 @@
+import { detectBackend } from "./BackendKind";
+import type { VectorBackend } from "./VectorBackend";
+import { WasmVectorBackend } from "./WasmVectorBackend";
+import { WebGlVectorBackend } from "./WebGLVectorBackend";
+import { WebGpuVectorBackend } from "./WebGPUVectorBackend";
+import { WebNnVectorBackend } from "./WebNNVectorBackend";
+
 export async function createVectorBackend(
   wasmBytes: ArrayBuffer
 ): Promise<VectorBackend> {

TopK.ts

@@ -0,0 +1,28 @@
+import type { DistanceResult, ScoreResult } from "./VectorBackend";
+
+export function topKByScore(scores: Float32Array, k: number): ScoreResult[] {
+  const limit = Math.max(0, Math.min(k, scores.length));
+  const indices = Array.from({ length: scores.length }, (_, i) => i);
+
+  indices.sort((a, b) => scores[b] - scores[a]);
+
+  return indices.slice(0, limit).map((index) => ({
+    index,
+    score: scores[index]
+  }));
+}
+
+export function topKByDistance(
+  distances: Uint32Array | Int32Array | Float32Array,
+  k: number
+): DistanceResult[] {
+  const limit = Math.max(0, Math.min(k, distances.length));
+  const indices = Array.from({ length: distances.length }, (_, i) => i);
+
+  indices.sort((a, b) => Number(distances[a]) - Number(distances[b]));
+
+  return indices.slice(0, limit).map((index) => ({
+    index,
+    distance: Number(distances[index])
+  }));
+}

VectorBackend.ts

@@ -1,32 +1,49 @@
-// TS side
+import type { BackendKind } from "./BackendKind";
+
+export interface ScoreResult {
+  index: number;
+  score: number;
+}
+
+export interface DistanceResult {
+  index: number;
+  distance: number;
+}
+
 export interface VectorBackend {
-  kind: BackendKind; // "wasm" | "webgl" | "webgpu" | "webnn"
+  kind: BackendKind;
 
-  // ---- float space (exact or high-precision cosine) ----
+  // Exact or high-precision dot-product scoring over row-major matrices.
   dotMany(
-    query: Float32Array,      // length = dim
-    matrix: Float32Array,     // length = dim * count, row-major
+    query: Float32Array,
+    matrix: Float32Array,
     dim: number,
     count: number
-  ): Promise<Float32Array>;   // scores[length = count]
+  ): Promise<Float32Array>;
 
-  topKFromScores(
-    scores: Float32Array,
-    k: number
-  ): Promise<{ index: number; score: number }[]>;
+  // Projection helper used to reduce dimensionality for routing tiers.
+  project(
+    vector: Float32Array,
+    projectionMatrix: Float32Array,
+    dimIn: number,
+    dimOut: number
+  ): Promise<Float32Array>;
+
+  topKFromScores(scores: Float32Array, k: number): Promise<ScoreResult[]>;
 
-  // ---- binary space (approximate, XOR / popcnt) ----
+  // Random-hyperplane hash from projected vectors into packed binary codes.
   hashToBinary(
-    vector: Float32Array,     // original embedding (e.g. 768-d)
-    dim: number,              // same as vector.length
-    bits: number              // e.g. 64, 128
-  ): Promise<Uint32Array>;    // packed bits (words = ceil(bits/32))
+    vector: Float32Array,
+    projectionMatrix: Float32Array,
+    dimIn: number,
+    bits: number
+  ): Promise<Uint32Array>;
 
   hammingTopK(
-    queryCode: Uint32Array,   // packed bits
-    codes: Uint32Array,       // concatenated codes for N items
+    queryCode: Uint32Array,
+    codes: Uint32Array,
     wordsPerCode: number,
-    count: number,            // N
+    count: number,
     k: number
-  ): Promise<{ index: number; distance: number }[]>;
+  ): Promise<DistanceResult[]>;
 }

WasmVectorBackend.ts

@@ -1,13 +1,35 @@
+import type {
+  DistanceResult,
+  ScoreResult,
+  VectorBackend
+} from "./VectorBackend";
+
+interface WasmVectorExports {
+  mem: WebAssembly.Memory;
+  dot_many(qPtr: number, mPtr: number, outPtr: number, dim: number, count: number): void;
+  project(vecPtr: number, pPtr: number, outPtr: number, dimIn: number, dimOut: number): void;
+  hash_binary(vecPtr: number, pPtr: number, codePtr: number, dimIn: number, bits: number): void;
+  hamming_scores(
+    queryCodePtr: number,
+    codesPtr: number,
+    outPtr: number,
+    wordsPerCode: number,
+    count: number
+  ): void;
+  topk_i32(scoresPtr: number, outPtr: number, count: number, k: number): void;
+  topk_f32(scoresPtr: number, outPtr: number, count: number, k: number): void;
+}
+
 export class WasmVectorBackend implements VectorBackend {
   readonly kind = "wasm" as const;
-  private exports!: Record<string, Function>;
+  private exports!: WasmVectorExports;
   private mem!: WebAssembly.Memory;
   private bump = 1024; // first 1KB reserved as guard
 
   static async create(wasmBytes: ArrayBuffer): Promise<WasmVectorBackend> {
     const b = new WasmVectorBackend();
     const { instance } = await WebAssembly.instantiate(wasmBytes);
-    b.exports = instance.exports as Record<string, Function>;
+    b.exports = instance.exports as unknown as WasmVectorExports;
     b.mem = instance.exports.mem as WebAssembly.Memory;
     return b;
   }
@@ -49,25 +71,27 @@ export class WasmVectorBackend implements VectorBackend {
   }
 
   async project(
-    vec: Float32Array, P: Float32Array,
+    vec: Float32Array,
+    projectionMatrix: Float32Array,
     dimIn: number, dimOut: number
   ): Promise<Float32Array> {
     this.reset();
     const v_ptr   = this.writeF32(vec);
-    const P_ptr   = this.writeF32(P);
+    const P_ptr   = this.writeF32(projectionMatrix);
     const out_ptr = this.alloc(dimOut * 4);
     this.exports.project(v_ptr, P_ptr, out_ptr, dimIn, dimOut);
     return new Float32Array(this.mem.buffer.slice(out_ptr, out_ptr + dimOut * 4));
   }
 
   async hashToBinary(
-    vec: Float32Array, P: Float32Array,
+    vec: Float32Array,
+    projectionMatrix: Float32Array,
     dimIn: number, bits: number
   ): Promise<Uint32Array> {
     this.reset();
     const wordsPerCode = Math.ceil(bits / 32);
     const v_ptr    = this.writeF32(vec);
-    const P_ptr    = this.writeF32(P);
+    const P_ptr    = this.writeF32(projectionMatrix);
     const code_ptr = this.alloc(wordsPerCode * 4);
     this.exports.hash_binary(v_ptr, P_ptr, code_ptr, dimIn, bits);
     return new Uint32Array(this.mem.buffer.slice(code_ptr, code_ptr + wordsPerCode * 4));
@@ -76,7 +100,7 @@ export class WasmVectorBackend implements VectorBackend {
   async hammingTopK(
     queryCode: Uint32Array, codes: Uint32Array,
     wordsPerCode: number, count: number, k: number
-  ): Promise<{ index: number; distance: number }[]> {
+  ): Promise<DistanceResult[]> {
     this.reset();
     const q_ptr       = this.writeU32(queryCode);
     const codes_ptr   = this.writeU32(codes);
@@ -98,7 +122,7 @@ export class WasmVectorBackend implements VectorBackend {
 
   async topKFromScores(
     scores: Float32Array, k: number
-  ): Promise<{ index: number; score: number }[]> {
+  ): Promise<ScoreResult[]> {
     this.reset();
     // copy: topk_f32 mutates in-place
     const copy_ptr = this.writeF32(new Float32Array(scores));

WebGLVectorBackend.ts

@@ -1,3 +1,10 @@
+import { topKByDistance, topKByScore } from "./TopK";
+import type {
+  DistanceResult,
+  ScoreResult,
+  VectorBackend
+} from "./VectorBackend";
+
 const VERT_SRC = /* glsl */`#version 300 es
 out vec2 v_uv;
 void main() {
@@ -204,12 +211,13 @@ export class WebGlVectorBackend implements VectorBackend {
   }
 
   async hashToBinary(
-    vec: Float32Array, P: Float32Array,
+    vec: Float32Array,
+    projectionMatrix: Float32Array,
     dimIn: number, bits: number
   ): Promise<Uint32Array> {
     const dimPacked = Math.ceil(dimIn / 4);
     const vTex = this.packF32Texture(vec, 1);
-    const hTex = this.packF32Texture(P, bits);
+    const hTex = this.packF32Texture(projectionMatrix, bits);
 
     const pixels = this.drawToFramebuffer(this.hashProg, bits, (prog) => {
       this.bindTex(prog, "u_vec",         vTex, 0);
@@ -239,7 +247,7 @@ export class WebGlVectorBackend implements VectorBackend {
   async hammingTopK(
     queryCode: Uint32Array, codes: Uint32Array,
     wordsPerCode: number, count: number, k: number
-  ): Promise<{ index: number; distance: number }[]> {
+  ): Promise<DistanceResult[]> {
     const distances = new Uint32Array(count);
     for (let i = 0; i < count; i++) {
       let dist = 0;
@@ -253,12 +261,12 @@ export class WebGlVectorBackend implements VectorBackend {
       }
       distances[i] = dist;
     }
-    return topKCpu(distances, k, false);
+    return topKByDistance(distances, k);
   }
 
   async topKFromScores(
     scores: Float32Array, k: number
-  ): Promise<{ index: number; score: number }[]> {
-    return topKCpu(scores, k, true);
+  ): Promise<ScoreResult[]> {
+    return topKByScore(scores, k);
   }
 }