feat: Add DeterministicDummyEmbeddingBackend for SHA-256 embedding and benchmarking; update execution plan and tests

Author: devlux76

CORTEX-DESIGN-PLAN-TODO.md

@@ -30,6 +30,8 @@ Completed since the prior snapshot:
 3. Guard command exists for model-related hardcoded numeric literals (`npm run guard:model-derived`).
 4. Runtime numeric constants are centralized for backend/storage internals (`core/NumericConstants.ts`).
 5. Runtime helper resolves model metadata and derives routing policy in one call (`resolveRoutingPolicyForModel` in `Policy.ts`).
+6. Deterministic dummy SHA-256 embedder exists for pre-model hotpath testing (`embeddings/DeterministicDummyEmbeddingBackend.ts`).
+7. Benchmark harness exists for dummy embedder throughput baselining (`npm run benchmark:dummy`).
 
 Next focus:
 1. Wire resolved model profiles into runtime ingest/query entry points.

PROJECT-EXECUTION-PLAN.md

@@ -24,6 +24,13 @@ Completed in this pass:
 7. Added model-profile-to-policy bridge helper so runtime callers can resolve profile and derive routing in one step:
    - `resolveRoutingPolicyForModel(...)` in `Policy.ts`
    - integration tests in `tests/model/RoutingPolicy.test.ts`
+8. Added deterministic dummy embedder for hotpath benchmarking before real model wiring:
+   - `embeddings/EmbeddingBackend.ts`
+   - `embeddings/DeterministicDummyEmbeddingBackend.ts`
+   - tests: `tests/embeddings/DeterministicDummyEmbeddingBackend.test.ts`
+9. Added executable dummy hotpath benchmark harness:
+   - `tests/benchmarks/DummyEmbedderHotpath.bench.ts`
+   - `npm run benchmark:dummy`
 
 Open items carried to next pass:
 1. Wire resolved `ModelProfile` into first concrete ingest/query orchestrator path (once those runtime modules are added).
@@ -94,15 +101,17 @@ Available now:
 2. `npm run test:unit -- tests/model/ModelProfileResolver.test.ts`
 3. `npm run test:unit -- tests/model/ModelDefaults.test.ts`
 4. `npm run guard:model-derived`
-5. `npm run build && npm run lint`
+5. `npm run test:unit -- tests/embeddings/DeterministicDummyEmbeddingBackend.test.ts`
+6. `npm run benchmark:dummy`
+7. `npm run benchmark`
+8. `npm run build && npm run lint`
 
 Planned commands to add in later passes:
 1. `npm run test:unit -- tests/embeddings/ProviderResolver.test.ts`
 2. `npm run test:unit -- tests/embeddings/OnnxEmbeddingRunner.test.ts`
 3. `npm run test:browser`
 4. `npm run test:electron`
 5. `npm run test:all`
-6. `npm run benchmark`
 
 ## Known Hardcoded Hotspots To Clean First
 

embeddings/DeterministicDummyEmbeddingBackend.ts

@@ -0,0 +1,108 @@
+import type { EmbeddingBackend } from "./EmbeddingBackend";
+
+export const DEFAULT_DUMMY_EMBEDDING_DIMENSION = 1024;
+export const SHA256_BLOCK_BYTES = 64;
+
+const SHA256_DIGEST_BYTES = 32;
+const COUNTER_BYTES = 4;
+const BYTE_TO_UNIT_SCALE = 127.5;
+
+export interface DeterministicDummyEmbeddingBackendOptions {
+  dimension?: number;
+  blockBytes?: number;
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function getSubtleCrypto(): SubtleCrypto {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("SubtleCrypto is required for DeterministicDummyEmbeddingBackend");
+  }
+  return subtle;
+}
+
+function padBytesToBoundary(input: Uint8Array, blockBytes: number): Uint8Array {
+  const remainder = input.byteLength % blockBytes;
+  if (remainder === 0) {
+    return input;
+  }
+
+  const padLength = blockBytes - remainder;
+  const padded = new Uint8Array(input.byteLength + padLength);
+  padded.set(input);
+  return padded;
+}
+
+function byteToUnitFloat(byteValue: number): number {
+  return byteValue / BYTE_TO_UNIT_SCALE - 1;
+}
+
+export class DeterministicDummyEmbeddingBackend implements EmbeddingBackend {
+  readonly kind = "dummy-sha256" as const;
+  readonly dimension: number;
+
+  private readonly blockBytes: number;
+  private readonly subtle = getSubtleCrypto();
+  private readonly encoder = new TextEncoder();
+
+  constructor(options: DeterministicDummyEmbeddingBackendOptions = {}) {
+    this.dimension = options.dimension ?? DEFAULT_DUMMY_EMBEDDING_DIMENSION;
+    this.blockBytes = options.blockBytes ?? SHA256_BLOCK_BYTES;
+
+    assertPositiveInteger("dimension", this.dimension);
+    assertPositiveInteger("blockBytes", this.blockBytes);
+  }
+
+  async embed(texts: string[]): Promise<Float32Array[]> {
+    return Promise.all(texts.map((text) => this.embedOne(text)));
+  }
+
+  private async embedOne(text: string): Promise<Float32Array> {
+    const sourceBytes = padBytesToBoundary(
+      this.encoder.encode(text),
+      this.blockBytes,
+    );
+
+    const embedding = new Float32Array(this.dimension);
+    let counter = 0;
+    let writeIndex = 0;
+
+    while (writeIndex < this.dimension) {
+      const digest = await this.digestWithCounter(sourceBytes, counter);
+      for (
+        let digestIndex = 0;
+        digestIndex < SHA256_DIGEST_BYTES && writeIndex < this.dimension;
+        digestIndex++
+      ) {
+        embedding[writeIndex] = byteToUnitFloat(digest[digestIndex]);
+        writeIndex++;
+      }
+      counter++;
+    }
+
+    return embedding;
+  }
+
+  private async digestWithCounter(
+    sourceBytes: Uint8Array,
+    counter: number,
+  ): Promise<Uint8Array> {
+    const payload = new Uint8Array(sourceBytes.byteLength + COUNTER_BYTES);
+    payload.set(sourceBytes, 0);
+
+    const counterView = new DataView(
+      payload.buffer,
+      payload.byteOffset + sourceBytes.byteLength,
+      COUNTER_BYTES,
+    );
+    counterView.setUint32(0, counter, false);
+
+    const digest = await this.subtle.digest("SHA-256", payload);
+    return new Uint8Array(digest);
+  }
+}

embeddings/EmbeddingBackend.ts

@@ -0,0 +1,6 @@
+export interface EmbeddingBackend {
+  readonly kind: string;
+  readonly dimension: number;
+
+  embed(texts: string[]): Promise<Float32Array[]>;
+}

package.json

@@ -10,7 +10,9 @@
     "test": "vitest run",
     "test:unit": "vitest run",
     "test:watch": "vitest",
-    "guard:model-derived": "node scripts/guard-model-derived.mjs"
+    "guard:model-derived": "node scripts/guard-model-derived.mjs",
+    "benchmark:dummy": "vitest bench --watch=false tests/benchmarks/DummyEmbedderHotpath.bench.ts",
+    "benchmark": "npm run benchmark:dummy"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",

tests/benchmarks/DummyEmbedderHotpath.bench.ts

@@ -0,0 +1,30 @@
+import { bench, describe } from "vitest";
+
+import { DeterministicDummyEmbeddingBackend } from "../../embeddings/DeterministicDummyEmbeddingBackend";
+
+const backend = new DeterministicDummyEmbeddingBackend({ dimension: 1024 });
+
+function buildDeterministicBatch(count: number, tokenSeed: string): string[] {
+  return Array.from({ length: count }, (_, index) => {
+    const suffix = `${tokenSeed}-${index.toString(16).padStart(4, "0")}`;
+    return `${suffix} ${suffix} ${suffix} ${suffix}`;
+  });
+}
+
+const singleShort = ["where is the cache invalidation boundary?"];
+const batch16Medium = buildDeterministicBatch(16, "cortex-medium");
+const batch64Short = buildDeterministicBatch(64, "cortex-short");
+
+describe("Dummy Embedder Hotpath", () => {
+  bench("single short input", async () => {
+    await backend.embed(singleShort);
+  });
+
+  bench("batch 16 medium inputs", async () => {
+    await backend.embed(batch16Medium);
+  });
+
+  bench("batch 64 short inputs", async () => {
+    await backend.embed(batch64Short);
+  });
+});

tests/embeddings/DeterministicDummyEmbeddingBackend.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_DUMMY_EMBEDDING_DIMENSION,
+  SHA256_BLOCK_BYTES,
+  DeterministicDummyEmbeddingBackend,
+} from "../../embeddings/DeterministicDummyEmbeddingBackend";
+
+describe("DeterministicDummyEmbeddingBackend", () => {
+  it("returns 1024 dimensions by default", async () => {
+    const backend = new DeterministicDummyEmbeddingBackend();
+    const [vector] = await backend.embed(["hello cortex"]);
+
+    expect(vector).toHaveLength(DEFAULT_DUMMY_EMBEDDING_DIMENSION);
+  });
+
+  it("is deterministic for identical input", async () => {
+    const backend = new DeterministicDummyEmbeddingBackend();
+
+    const [first] = await backend.embed(["same input"]);
+    const [second] = await backend.embed(["same input"]);
+
+    expect(Array.from(first)).toEqual(Array.from(second));
+  });
+
+  it("produces different vectors for different input", async () => {
+    const backend = new DeterministicDummyEmbeddingBackend();
+
+    const [a, b] = await backend.embed(["alpha", "beta"]);
+
+    const differs = a.some((value, index) => value !== b[index]);
+    expect(differs).toBe(true);
+  });
+
+  it("pads input to SHA-256 block boundary using zero bytes", async () => {
+    const backend = new DeterministicDummyEmbeddingBackend();
+    const base = "abc";
+
+    const inputBytes = new TextEncoder().encode(base).byteLength;
+    const remainder = inputBytes % SHA256_BLOCK_BYTES;
+    const padCount = remainder === 0 ? 0 : SHA256_BLOCK_BYTES - remainder;
+
+    const equivalentExplicitlyPadded = base + "\0".repeat(padCount);
+
+    const [autoPadded] = await backend.embed([base]);
+    const [alreadyPadded] = await backend.embed([equivalentExplicitlyPadded]);
+
+    expect(Array.from(autoPadded)).toEqual(Array.from(alreadyPadded));
+  });
+
+  it("supports custom output dimensions", async () => {
+    const backend = new DeterministicDummyEmbeddingBackend({ dimension: 97 });
+    const [vector] = await backend.embed(["custom-dim"]);
+
+    expect(vector).toHaveLength(97);
+  });
+
+  it("rejects invalid dimensions", () => {
+    expect(() => new DeterministicDummyEmbeddingBackend({ dimension: 0 })).toThrow(
+      /dimension/i,
+    );
+  });
+});