feat: Implement embedding provider resolver and runner; add tests and update execution plan

Author: devlux76

CORTEX-DESIGN-PLAN-TODO.md

@@ -32,10 +32,11 @@ Completed since the prior snapshot:
 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`).
+8. Baseline adaptive provider selection exists with capability filtering + benchmark-based winner choice (`embeddings/ProviderResolver.ts`, `embeddings/EmbeddingRunner.ts`).
 
 Next focus:
 1. Wire resolved model profiles into runtime ingest/query entry points.
-2. Build embedding provider resolver + runner modules and associated tests.
+2. Add real embedding providers (ONNX/Transformers/WebNN/WebGPU/WebGL/WASM) to resolver candidate sets.
 3. Add browser/electron runtime test lanes to match merge-gate policy.
 
 ## 1. Design

PROJECT-EXECUTION-PLAN.md

@@ -31,25 +31,30 @@ Completed in this pass:
 9. Added executable dummy hotpath benchmark harness:
    - `tests/benchmarks/DummyEmbedderHotpath.bench.ts`
    - `npm run benchmark:dummy`
+10. Implemented baseline embedding runtime selection modules:
+   - `embeddings/ProviderResolver.ts`
+   - `embeddings/EmbeddingRunner.ts`
+   - tests: `tests/embeddings/ProviderResolver.test.ts`, `tests/embeddings/EmbeddingRunner.test.ts`
+   - selection now supports capability filtering + benchmark-based winner choice
 
 Open items carried to next pass:
 1. Wire resolved `ModelProfile` into first concrete ingest/query orchestrator path (once those runtime modules are added).
-2. Add embedding provider resolver/runner modules and connect fallback policy to runtime execution.
+2. Add real embedding providers (ONNX/Transformers/WebNN/WebGPU/WebGL/WASM) as candidates for the resolver.
 3. Add browser/electron runtime scripts and CI lanes for non-Node merge gating.
 
 ## Next Session Highest Priority (P0)
 
-Integrate model-profile ownership into runtime flows and start the embedding vertical slice.
+Connect adaptive embedding selection to runtime orchestration and add real provider candidates.
 
 Instruction:
 1. Use `ModelProfileResolver` at runtime boundaries before any policy derivation or embedding execution.
-2. Implement first embedding runner/provider resolver slice with fallback semantics.
+2. Register real embedding providers in `ProviderResolver` candidate lists.
 3. Keep strict TDD (Red -> Green -> Refactor).
 4. If a blocker appears, record it in this document under an error log entry and continue with the next actionable slice.
 
 Definition of done for this pass:
 1. Runtime path resolves model metadata through `ModelProfileResolver` before use.
-2. Embedding provider resolver tests and implementation are present.
+2. At least one non-dummy real provider can be selected by capability + benchmark policy.
 3. Any unresolved blocker is documented with file/symptom/next action.
 
 ## Non-Negotiable Rules
@@ -69,8 +74,8 @@ Definition of done for this pass:
    - `core/ModelDefaults.ts`
 4. ~~Replace hardcoded model-dependent values with `ModelProfile` lookups.~~ ✅ Done for current code paths (2026-03-11)
 5. Implement embedding runner with fallback chain and telemetry:
-   - `embeddings/EmbeddingRunner.ts`
-   - `embeddings/ProviderResolver.ts`
+   - `embeddings/EmbeddingRunner.ts` ✅ baseline done (2026-03-11)
+   - `embeddings/ProviderResolver.ts` ✅ baseline done (2026-03-11)
    - `embeddings/TransformersEmbeddingBackend.ts`
    - `embeddings/OrtWebglEmbeddingBackend.ts`
    - `embeddings/OnnxEmbeddingRunner.ts`
@@ -102,16 +107,17 @@ Available now:
 3. `npm run test:unit -- tests/model/ModelDefaults.test.ts`
 4. `npm run guard:model-derived`
 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`
+6. `npm run test:unit -- tests/embeddings/ProviderResolver.test.ts`
+7. `npm run test:unit -- tests/embeddings/EmbeddingRunner.test.ts`
+8. `npm run benchmark:dummy`
+9. `npm run benchmark`
+10. `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`
+1. `npm run test:unit -- tests/embeddings/OnnxEmbeddingRunner.test.ts`
+2. `npm run test:browser`
+3. `npm run test:electron`
+4. `npm run test:all`
 
 ## Known Hardcoded Hotspots To Clean First
 

embeddings/EmbeddingRunner.ts

@@ -0,0 +1,54 @@
+import type { EmbeddingBackend } from "./EmbeddingBackend";
+import {
+  type ResolveEmbeddingBackendOptions,
+  type ResolvedEmbeddingBackend,
+  resolveEmbeddingBackend,
+} from "./ProviderResolver";
+
+export type ResolveEmbeddingSelection = () => Promise<ResolvedEmbeddingBackend>;
+
+export class EmbeddingRunner {
+  private selectionPromise: Promise<ResolvedEmbeddingBackend> | undefined;
+  private resolvedSelection: ResolvedEmbeddingBackend | undefined;
+
+  constructor(private readonly resolveSelection: ResolveEmbeddingSelection) {}
+
+  static fromResolverOptions(
+    options: ResolveEmbeddingBackendOptions,
+  ): EmbeddingRunner {
+    return new EmbeddingRunner(() => resolveEmbeddingBackend(options));
+  }
+
+  get selectedKind(): string | undefined {
+    return this.resolvedSelection?.selectedKind;
+  }
+
+  async getSelection(): Promise<ResolvedEmbeddingBackend> {
+    return this.ensureSelection();
+  }
+
+  async getBackend(): Promise<EmbeddingBackend> {
+    const selection = await this.ensureSelection();
+    return selection.backend;
+  }
+
+  async embed(texts: string[]): Promise<Float32Array[]> {
+    const backend = await this.getBackend();
+    return backend.embed(texts);
+  }
+
+  private async ensureSelection(): Promise<ResolvedEmbeddingBackend> {
+    if (this.resolvedSelection) {
+      return this.resolvedSelection;
+    }
+
+    if (!this.selectionPromise) {
+      this.selectionPromise = this.resolveSelection().then((selection) => {
+        this.resolvedSelection = selection;
+        return selection;
+      });
+    }
+
+    return this.selectionPromise;
+  }
+}

embeddings/ProviderResolver.ts

@@ -0,0 +1,244 @@
+import {
+  DeterministicDummyEmbeddingBackend,
+  type DeterministicDummyEmbeddingBackendOptions,
+} from "./DeterministicDummyEmbeddingBackend";
+import type { EmbeddingBackend } from "./EmbeddingBackend";
+
+export type EmbeddingProviderKind =
+  | "webnn"
+  | "webgpu"
+  | "webgl"
+  | "wasm"
+  | "dummy"
+  | (string & {});
+
+export interface EmbeddingProviderCandidate {
+  kind: EmbeddingProviderKind;
+  isSupported: () => boolean | Promise<boolean>;
+  createBackend: () => EmbeddingBackend | Promise<EmbeddingBackend>;
+}
+
+export interface EmbeddingProviderBenchmarkPolicy {
+  enabled: boolean;
+  warmupRuns: number;
+  timedRuns: number;
+  sampleTexts: string[];
+}
+
+export interface EmbeddingProviderMeasurement {
+  kind: EmbeddingProviderKind;
+  meanMs: number;
+}
+
+export type EmbeddingProviderResolveReason =
+  | "forced"
+  | "benchmark"
+  | "capability-order";
+
+export interface ResolvedEmbeddingBackend {
+  backend: EmbeddingBackend;
+  selectedKind: EmbeddingProviderKind;
+  reason: EmbeddingProviderResolveReason;
+  supportedKinds: EmbeddingProviderKind[];
+  measurements: EmbeddingProviderMeasurement[];
+}
+
+export const DEFAULT_PROVIDER_ORDER: ReadonlyArray<EmbeddingProviderKind> =
+  Object.freeze([
+  "webnn",
+  "webgpu",
+  "webgl",
+  "wasm",
+  "dummy",
+  ]);
+
+export const DEFAULT_PROVIDER_BENCHMARK_POLICY: EmbeddingProviderBenchmarkPolicy =
+  Object.freeze({
+    enabled: true,
+    warmupRuns: 1,
+    timedRuns: 3,
+    sampleTexts: [
+      "cortex benchmark probe",
+      "routing and coherence warmup",
+      "deterministic provider timing",
+    ],
+  });
+
+export type BenchmarkBackendFn = (
+  backend: EmbeddingBackend,
+  policy: EmbeddingProviderBenchmarkPolicy,
+) => Promise<number>;
+
+export interface ResolveEmbeddingBackendOptions {
+  candidates: EmbeddingProviderCandidate[];
+  preferredOrder?: ReadonlyArray<EmbeddingProviderKind>;
+  forceKind?: EmbeddingProviderKind;
+  benchmark?: Partial<EmbeddingProviderBenchmarkPolicy>;
+  benchmarkBackend?: BenchmarkBackendFn;
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function validateBenchmarkPolicy(
+  policy: EmbeddingProviderBenchmarkPolicy,
+): EmbeddingProviderBenchmarkPolicy {
+  assertPositiveInteger("warmupRuns", policy.warmupRuns);
+  assertPositiveInteger("timedRuns", policy.timedRuns);
+
+  if (policy.sampleTexts.length === 0) {
+    throw new Error("sampleTexts must not be empty");
+  }
+
+  return policy;
+}
+
+function nowMs(): number {
+  const perfNow = globalThis.performance?.now?.bind(globalThis.performance);
+  if (perfNow) {
+    return perfNow();
+  }
+  return Date.now();
+}
+
+async function defaultBenchmarkBackend(
+  backend: EmbeddingBackend,
+  policy: EmbeddingProviderBenchmarkPolicy,
+): Promise<number> {
+  for (let i = 0; i < policy.warmupRuns; i++) {
+    await backend.embed(policy.sampleTexts);
+  }
+
+  let totalMs = 0;
+  for (let i = 0; i < policy.timedRuns; i++) {
+    const start = nowMs();
+    await backend.embed(policy.sampleTexts);
+    totalMs += nowMs() - start;
+  }
+
+  return totalMs / policy.timedRuns;
+}
+
+function orderCandidates(
+  candidates: EmbeddingProviderCandidate[],
+  preferredOrder: ReadonlyArray<EmbeddingProviderKind>,
+): EmbeddingProviderCandidate[] {
+  const orderIndex = new Map<EmbeddingProviderKind, number>();
+  for (let i = 0; i < preferredOrder.length; i++) {
+    orderIndex.set(preferredOrder[i], i);
+  }
+
+  return [...candidates].sort((a, b) => {
+    const aIndex = orderIndex.get(a.kind) ?? Number.MAX_SAFE_INTEGER;
+    const bIndex = orderIndex.get(b.kind) ?? Number.MAX_SAFE_INTEGER;
+    return aIndex - bIndex;
+  });
+}
+
+export async function resolveEmbeddingBackend(
+  options: ResolveEmbeddingBackendOptions,
+): Promise<ResolvedEmbeddingBackend> {
+  const preferredOrder = options.preferredOrder ?? DEFAULT_PROVIDER_ORDER;
+  const benchmarkPolicy = validateBenchmarkPolicy({
+    ...DEFAULT_PROVIDER_BENCHMARK_POLICY,
+    ...options.benchmark,
+  });
+
+  const capabilityChecks = await Promise.all(
+    options.candidates.map(async (candidate) => ({
+      candidate,
+      supported: await candidate.isSupported(),
+    })),
+  );
+
+  if (options.forceKind !== undefined) {
+    const forcedEntry = capabilityChecks.find(
+      (entry) => entry.candidate.kind === options.forceKind,
+    );
+
+    if (!forcedEntry || !forcedEntry.supported) {
+      throw new Error(`Forced provider ${options.forceKind} is not supported`);
+    }
+
+    return {
+      backend: await forcedEntry.candidate.createBackend(),
+      selectedKind: forcedEntry.candidate.kind,
+      reason: "forced",
+      supportedKinds: orderCandidates(
+        capabilityChecks
+          .filter((entry) => entry.supported)
+          .map((entry) => entry.candidate),
+        preferredOrder,
+      ).map((candidate) => candidate.kind),
+      measurements: [],
+    };
+  }
+
+  const supportedCandidates = orderCandidates(
+    capabilityChecks
+      .filter((entry) => entry.supported)
+      .map((entry) => entry.candidate),
+    preferredOrder,
+  );
+
+  if (supportedCandidates.length === 0) {
+    throw new Error("No supported embedding providers are available");
+  }
+
+  const supportedKinds = supportedCandidates.map((candidate) => candidate.kind);
+
+  const benchmarkBackend = options.benchmarkBackend ?? defaultBenchmarkBackend;
+  if (benchmarkPolicy.enabled) {
+    const measurements: {
+      candidate: EmbeddingProviderCandidate;
+      backend: EmbeddingBackend;
+      meanMs: number;
+    }[] = [];
+
+    for (const candidate of supportedCandidates) {
+      const backend = await candidate.createBackend();
+      const meanMs = await benchmarkBackend(backend, benchmarkPolicy);
+      measurements.push({ candidate, backend, meanMs });
+    }
+
+    let winner = measurements[0];
+    for (let i = 1; i < measurements.length; i++) {
+      if (measurements[i].meanMs < winner.meanMs) {
+        winner = measurements[i];
+      }
+    }
+
+    return {
+      backend: winner.backend,
+      selectedKind: winner.candidate.kind,
+      reason: "benchmark",
+      supportedKinds,
+      measurements: measurements.map((m) => ({
+        kind: m.candidate.kind,
+        meanMs: m.meanMs,
+      })),
+    };
+  }
+
+  const selectedCandidate = supportedCandidates[0];
+  return {
+    backend: await selectedCandidate.createBackend(),
+    selectedKind: selectedCandidate.kind,
+    reason: "capability-order",
+    supportedKinds,
+    measurements: [],
+  };
+}
+
+export function createDummyProviderCandidate(
+  options: DeterministicDummyEmbeddingBackendOptions = {},
+): EmbeddingProviderCandidate {
+  return {
+    kind: "dummy",
+    isSupported: () => globalThis.crypto?.subtle !== undefined,
+    createBackend: () => new DeterministicDummyEmbeddingBackend(options),
+  };
+}