groove-dev 0.27.102 → 0.27.103

package/moe-training/test/server/verifier.test.js

@@ -225,6 +225,100 @@ describe('EnvelopeVerifier', () => {
     assert.equal(result.valid, false);
     assert.ok(result.reason.includes('HMAC'));
   });
+
+  // --- verifyFeedback ---
+
+  it('verifyFeedback accepts valid USER_FEEDBACK envelope', () => {
+    const envelope = {
+      envelope_id: 'env_fb_1',
+      session_id: sessionId,
+      type: 'USER_FEEDBACK',
+      feedback: {
+        signal: 'accepted',
+        timestamp: Date.now() / 1000,
+        context: 'completed with no interventions',
+        target_step: 10,
+        revision_rounds: 0,
+        delta_summary: null,
+      },
+    };
+
+    const forHmac = { ...envelope };
+    const envelopeBytes = JSON.stringify(forHmac);
+    const hmac = signEnvelope(sharedSecret, envelopeBytes, 0);
+    envelope.attestation = { session_hmac: hmac, sequence: 0, app_version_hash: VALID_APP_HASH };
+
+    const result = verifier.verifyFeedback(envelope);
+    assert.equal(result.valid, true);
+  });
+
+  it('verifyFeedback rejects unknown session_id', () => {
+    const envelope = {
+      envelope_id: 'env_fb_2',
+      session_id: 'sess_nonexistent',
+      type: 'USER_FEEDBACK',
+      feedback: { signal: 'accepted', timestamp: Date.now() / 1000 },
+      attestation: { session_hmac: 'a'.repeat(64), sequence: 0, app_version_hash: VALID_APP_HASH },
+    };
+    const result = verifier.verifyFeedback(envelope);
+    assert.equal(result.valid, false);
+    assert.ok(result.reason.includes('unknown session_id'));
+  });
+
+  it('verifyFeedback rejects missing attestation', () => {
+    const envelope = {
+      envelope_id: 'env_fb_3',
+      session_id: sessionId,
+      type: 'USER_FEEDBACK',
+      feedback: { signal: 'accepted', timestamp: Date.now() / 1000 },
+    };
+    const result = verifier.verifyFeedback(envelope);
+    assert.equal(result.valid, false);
+    assert.ok(result.reason.includes('attestation'));
+  });
+
+  it('verifyFeedback rejects tampered HMAC', () => {
+    const envelope = {
+      envelope_id: 'env_fb_4',
+      session_id: sessionId,
+      type: 'USER_FEEDBACK',
+      feedback: { signal: 'accepted', timestamp: Date.now() / 1000 },
+      attestation: { session_hmac: 'f'.repeat(64), sequence: 0, app_version_hash: VALID_APP_HASH },
+    };
+    const result = verifier.verifyFeedback(envelope);
+    assert.equal(result.valid, false);
+    assert.ok(result.reason.includes('HMAC'));
+  });
+
+  it('verifyFeedback rejects invalid signal via schema', () => {
+    const envelope = {
+      envelope_id: 'env_fb_5',
+      session_id: sessionId,
+      type: 'USER_FEEDBACK',
+      feedback: { signal: 'thumbs_up', timestamp: Date.now() / 1000 },
+    };
+
+    const forHmac = { ...envelope };
+    const envelopeBytes = JSON.stringify(forHmac);
+    const hmac = signEnvelope(sharedSecret, envelopeBytes, 0);
+    envelope.attestation = { session_hmac: hmac, sequence: 0, app_version_hash: VALID_APP_HASH };
+
+    const result = verifier.verifyFeedback(envelope);
+    assert.equal(result.valid, false);
+    assert.ok(result.reason.includes('schema'));
+  });
+
+  it('verifyFeedback rejects missing session_id', () => {
+    const envelope = {
+      envelope_id: 'env_fb_6',
+      type: 'USER_FEEDBACK',
+      feedback: { signal: 'accepted', timestamp: Date.now() / 1000 },
+      attestation: { session_hmac: 'a'.repeat(64), sequence: 0, app_version_hash: VALID_APP_HASH },
+    };
+    const result = verifier.verifyFeedback(envelope);
+    assert.equal(result.valid, false);
+    assert.ok(result.reason.includes('session_id'));
+  });
 });
 
 function verifyClose(verifier, envelope) {

package/moe-training/test/shared/envelope-schema.test.js

@@ -3,6 +3,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { validateEnvelope, STEP_TYPES } from '../../shared/envelope-schema.js';
+import { TRAINING_EXCLUSION_REASONS } from '../../shared/constants.js';
 
 const VALID_HMAC = 'a'.repeat(64);
 const VALID_APP_HASH = 'b'.repeat(64);
@@ -89,6 +90,17 @@ describe('envelope-schema', () => {
     }
   });
 
+  it('edit step type is valid', () => {
+    const env = validEnvelope();
+    env.trajectory_log = [{
+      step: 1, type: 'edit', timestamp: Date.now() / 1000,
+      file_path: 'index.html', edit_type: 'create', content: '<html></html>',
+      token_count: 5,
+    }];
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
   // --- New security tests ---
 
   it('rejects trajectory_log with > 500 steps', () => {
@@ -348,4 +360,283 @@ describe('envelope-schema', () => {
     assert.equal(result.valid, false);
     assert.ok(result.errors.some(e => e.includes('session_hmac')));
   });
+
+  // --- Observation truncation fields ---
+
+  it('accepts observation step with truncated and original_token_count', () => {
+    const env = validEnvelope();
+    env.trajectory_log.push({
+      step: 3, type: 'observation', timestamp: Date.now() / 1000,
+      content: 'output', token_count: 100, truncated: false, original_token_count: 100,
+    });
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('accepts observation step with truncated=true', () => {
+    const env = validEnvelope();
+    env.trajectory_log.push({
+      step: 3, type: 'observation', timestamp: Date.now() / 1000,
+      content: 'output...', token_count: 4096, truncated: true, original_token_count: 9000,
+    });
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('rejects non-boolean truncated field', () => {
+    const env = validEnvelope();
+    env.trajectory_log[0].truncated = 'yes';
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('truncated')));
+  });
+
+  it('rejects negative original_token_count', () => {
+    const env = validEnvelope();
+    env.trajectory_log[0].original_token_count = -5;
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('original_token_count')));
+  });
+
+  it('steps without truncation fields still validate (backward compat)', () => {
+    const env = validEnvelope();
+    assert.equal(env.trajectory_log[0].truncated, undefined);
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  // --- domain_tags ---
+
+  it('accepts null domain_tags in metadata', () => {
+    const env = validEnvelope();
+    env.metadata.domain_tags = null;
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('accepts absent domain_tags in metadata (backward compat)', () => {
+    const env = validEnvelope();
+    assert.equal(env.metadata.domain_tags, undefined);
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('accepts valid domain_tags object', () => {
+    const env = validEnvelope();
+    env.metadata.domain_tags = {
+      primary: { domain: 'python', confidence: 0.42 },
+      secondary: { domain: 'data_science_ml', confidence: 0.23 },
+      tertiary: { domain: 'devops_docker', confidence: 0.11 },
+    };
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('rejects domain_tags with invalid confidence', () => {
+    const env = validEnvelope();
+    env.metadata.domain_tags = {
+      primary: { domain: 'python', confidence: 1.5 },
+      secondary: { domain: 'rust', confidence: 0.2 },
+      tertiary: { domain: 'react_frontend', confidence: 0.1 },
+    };
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('confidence')));
+  });
+
+  it('rejects domain_tags missing tertiary', () => {
+    const env = validEnvelope();
+    env.metadata.domain_tags = {
+      primary: { domain: 'python', confidence: 0.4 },
+      secondary: { domain: 'rust', confidence: 0.2 },
+    };
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('tertiary')));
+  });
+
+  // --- leaf_context ---
+
+  it('accepts null leaf_context in metadata', () => {
+    const env = validEnvelope();
+    env.metadata.leaf_context = null;
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('accepts absent leaf_context in metadata (backward compat)', () => {
+    const env = validEnvelope();
+    assert.equal(env.metadata.leaf_context, undefined);
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('accepts valid leaf_context object', () => {
+    const env = validEnvelope();
+    env.metadata.leaf_context = {
+      leaf_id: 'python_expert_v3', leaf_version: '1.2.0',
+      confidence_at_route: 0.42, chassis_model: 'Qwen/Qwen3-0.6B',
+    };
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, true);
+  });
+
+  it('rejects leaf_context with invalid confidence_at_route', () => {
+    const env = validEnvelope();
+    env.metadata.leaf_context = {
+      leaf_id: 'test', leaf_version: '1.0', confidence_at_route: 1.5, chassis_model: 'test',
+    };
+    const result = validateEnvelope(env);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('confidence_at_route')));
+  });
+
+  // --- Quality tier in SESSION_CLOSE ---
+
+  it('SESSION_CLOSE accepts quality_tier and training fields', () => {
+    const close = {
+      envelope_id: 'env_close-qt',
+      session_id: 'sess_test-qt',
+      type: 'SESSION_CLOSE',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      outcome: {
+        status: 'SUCCESS', total_steps: 10, total_chunks: 1,
+        quality_tier: 'TIER_A', quality_tier_reason: 'high_quality_no_errors',
+        training_eligible: true, training_exclusion_reason: null,
+      },
+    };
+    const result = validateEnvelope(close);
+    assert.equal(result.valid, true);
+  });
+
+  it('SESSION_CLOSE rejects invalid quality_tier', () => {
+    const close = {
+      envelope_id: 'env_close-qt2',
+      session_id: 'sess_test-qt2',
+      type: 'SESSION_CLOSE',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      outcome: {
+        status: 'SUCCESS', total_steps: 10, total_chunks: 1,
+        quality_tier: 'TIER_Z',
+      },
+    };
+    const result = validateEnvelope(close);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('quality_tier')));
+  });
+
+  it('SESSION_CLOSE rejects invalid training_exclusion_reason', () => {
+    const close = {
+      envelope_id: 'env_close-te',
+      session_id: 'sess_test-te',
+      type: 'SESSION_CLOSE',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      outcome: {
+        status: 'SUCCESS', total_steps: 10, total_chunks: 1,
+        training_eligible: false, training_exclusion_reason: 'bad_vibes',
+      },
+    };
+    const result = validateEnvelope(close);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('training_exclusion_reason')));
+  });
+
+  it('SESSION_CLOSE rejects non-boolean training_eligible', () => {
+    const close = {
+      envelope_id: 'env_close-te2',
+      session_id: 'sess_test-te2',
+      type: 'SESSION_CLOSE',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      outcome: {
+        status: 'SUCCESS', total_steps: 10, total_chunks: 1,
+        training_eligible: 'yes',
+      },
+    };
+    const result = validateEnvelope(close);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('training_eligible')));
+  });
+
+  it('SESSION_CLOSE without new fields still validates (backward compat)', () => {
+    const close = {
+      envelope_id: 'env_close-bc',
+      session_id: 'sess_test-bc',
+      type: 'SESSION_CLOSE',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      outcome: { status: 'SUCCESS', total_steps: 10, total_chunks: 1 },
+    };
+    const result = validateEnvelope(close);
+    assert.equal(result.valid, true);
+  });
+
+  // --- USER_FEEDBACK validation ---
+
+  it('valid USER_FEEDBACK passes', () => {
+    const feedback = {
+      envelope_id: 'env_fb_1',
+      session_id: 'sess_fb_1',
+      type: 'USER_FEEDBACK',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      feedback: {
+        signal: 'accepted', timestamp: Date.now() / 1000,
+        context: 'user ran code without modifications',
+        target_step: 10, revision_rounds: 0, delta_summary: null,
+      },
+    };
+    const result = validateEnvelope(feedback);
+    assert.equal(result.valid, true);
+  });
+
+  it('USER_FEEDBACK rejects invalid signal', () => {
+    const feedback = {
+      envelope_id: 'env_fb_2',
+      session_id: 'sess_fb_2',
+      type: 'USER_FEEDBACK',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      feedback: { signal: 'thumbs_up', timestamp: Date.now() / 1000 },
+    };
+    const result = validateEnvelope(feedback);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('signal')));
+  });
+
+  it('USER_FEEDBACK rejects missing feedback object', () => {
+    const feedback = {
+      envelope_id: 'env_fb_3',
+      session_id: 'sess_fb_3',
+      type: 'USER_FEEDBACK',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+    };
+    const result = validateEnvelope(feedback);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('feedback')));
+  });
+
+  it('USER_FEEDBACK accepts all valid signal types', () => {
+    for (const signal of ['accepted', 'modified', 'rejected', 'iterated']) {
+      const feedback = {
+        envelope_id: `env_fb_${signal}`,
+        session_id: `sess_fb_${signal}`,
+        type: 'USER_FEEDBACK',
+        attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+        feedback: { signal, timestamp: Date.now() / 1000 },
+      };
+      const result = validateEnvelope(feedback);
+      assert.equal(result.valid, true, `Signal "${signal}" should be valid`);
+    }
+  });
+
+  it('USER_FEEDBACK rejects negative revision_rounds', () => {
+    const feedback = {
+      envelope_id: 'env_fb_neg',
+      session_id: 'sess_fb_neg',
+      type: 'USER_FEEDBACK',
+      attestation: { session_hmac: VALID_HMAC, sequence: 0, app_version_hash: VALID_APP_HASH },
+      feedback: { signal: 'iterated', timestamp: Date.now() / 1000, revision_rounds: -1 },
+    };
+    const result = validateEnvelope(feedback);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('revision_rounds')));
+  });
 });

package/node_modules/@groove-dev/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/cli",
-  "version": "0.27.102",
+  "version": "0.27.103",
   "description": "GROOVE CLI — manage AI coding agents from your terminal",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/@groove-dev/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/daemon",
-  "version": "0.27.102",
+  "version": "0.27.103",
   "description": "GROOVE daemon — agent orchestration engine",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/@groove-dev/gui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/gui",
-  "version": "0.27.102",
+  "version": "0.27.103",
   "description": "GROOVE GUI — visual agent control plane",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/node_modules/moe-training/client/domain-tagger.js

@@ -0,0 +1,205 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+const DEFAULT_DOMAINS = [
+  'python', 'typescript_node', 'react_frontend', 'postgresql_database',
+  'devops_docker', 'rust', 'data_science_ml', 'security_pentest',
+  'mobile_swift', 'system_design',
+];
+
+const DEFAULT_MODEL = 'sentence-transformers/all-MiniLM-L6-v2';
+const DEFAULT_TOP_K = 3;
+
+const DOMAIN_KEYWORDS = {
+  python: ['python', 'pip', 'pytest', 'django', 'flask', 'fastapi', '.py', 'pandas', 'numpy', 'venv', 'poetry', 'pyproject', '__init__', 'def ', 'import '],
+  typescript_node: ['typescript', 'node', 'npm', 'express', '.ts', 'tsconfig', 'package.json', 'nestjs', 'prisma', 'tsc', 'deno', 'bun'],
+  react_frontend: ['react', 'jsx', 'tsx', 'component', 'hook', 'usestate', 'useeffect', 'tailwind', 'css', 'vite', 'nextjs', 'styled', 'frontend', 'dom', 'html'],
+  postgresql_database: ['postgresql', 'postgres', 'sql', 'database', 'query', 'schema', 'migration', 'table', 'index', 'select', 'insert', 'join', 'foreign key', 'sequelize', 'knex'],
+  devops_docker: ['docker', 'kubernetes', 'k8s', 'ci/cd', 'github actions', 'deployment', 'terraform', 'ansible', 'nginx', 'dockerfile', 'compose', 'helm', 'aws', 'gcp', 'pipeline'],
+  rust: ['rust', 'cargo', 'ownership', 'lifetime', 'borrow', '.rs', 'impl ', 'fn ', 'struct ', 'enum ', 'trait ', 'crate', 'tokio'],
+  data_science_ml: ['machine learning', 'pytorch', 'tensorflow', 'ml', 'training', 'dataset', 'neural', 'deep learning', 'transformer', 'huggingface', 'sklearn', 'prediction', 'epoch', 'loss'],
+  security_pentest: ['security', 'vulnerability', 'cve', 'authentication', 'authorization', 'encryption', 'xss', 'sql injection', 'pentest', 'exploit', 'firewall', 'oauth', 'csrf'],
+  mobile_swift: ['swift', 'ios', 'swiftui', 'xcode', 'cocoapod', 'uikit', 'storyboard', 'watchos', 'macos', 'apple', 'carthage', 'spm'],
+  system_design: ['architecture', 'system design', 'scalability', 'microservice', 'distributed', 'load balancer', 'cache', 'message queue', 'api gateway', 'monorepo', 'design pattern', 'event driven'],
+};
+
+export class DomainTagger {
+  constructor(options = {}) {
+    this._serviceUrl = options.serviceUrl || process.env.EMBEDDING_SERVICE_URL || null;
+    this._model = options.model || DEFAULT_MODEL;
+    this._topK = options.topK || DEFAULT_TOP_K;
+    this._domains = options.domains || DEFAULT_DOMAINS;
+    this._ready = false;
+    this._mode = null;
+    this._centroids = null;
+    this._lastError = null;
+  }
+
+  async init() {
+    this._lastError = null;
+
+    if (this._serviceUrl) {
+      try {
+        const res = await fetch(this._serviceUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ input: 'health check', model: this._model }),
+          signal: AbortSignal.timeout(5_000),
+        });
+        if (res.ok) {
+          this._mode = 'http';
+          await this._buildCentroids();
+          this._ready = true;
+          return;
+        }
+      } catch {
+        // HTTP service unavailable
+      }
+    }
+
+    this._mode = 'keyword';
+    this._ready = true;
+  }
+
+  async tag(routingText) {
+    if (!this._ready || !routingText || typeof routingText !== 'string') return null;
+
+    this._lastError = null;
+    try {
+      if (this._mode === 'http') {
+        return await this._tagWithEmbeddings(routingText);
+      }
+      return this._tagWithKeywords(routingText);
+    } catch (err) {
+      this._lastError = err.message || String(err);
+      return null;
+    }
+  }
+
+  get lastError() {
+    return this._lastError;
+  }
+
+  get ready() {
+    return this._ready;
+  }
+
+  get mode() {
+    return this._mode;
+  }
+
+  static buildRoutingText(taskTitle, firstPrompt, thoughtSteps = []) {
+    const parts = [];
+    if (taskTitle) parts.push(taskTitle);
+    if (firstPrompt) parts.push(firstPrompt);
+    for (const step of thoughtSteps.slice(0, 2)) {
+      if (step?.content) parts.push(step.content);
+    }
+    return parts.join('\n');
+  }
+
+  async _tagWithEmbeddings(routingText) {
+    const embedding = await this._embed(routingText);
+    if (!embedding) return null;
+
+    const scores = [];
+    for (const [domain, centroid] of Object.entries(this._centroids)) {
+      scores.push({ domain, confidence: cosineSimilarity(embedding, centroid) });
+    }
+
+    scores.sort((a, b) => b.confidence - a.confidence);
+    const top = scores.slice(0, this._topK);
+
+    if (top.length < 3) return null;
+
+    return {
+      primary: { domain: top[0].domain, confidence: round4(top[0].confidence) },
+      secondary: { domain: top[1].domain, confidence: round4(top[1].confidence) },
+      tertiary: { domain: top[2].domain, confidence: round4(top[2].confidence) },
+    };
+  }
+
+  _tagWithKeywords(routingText) {
+    const text = routingText.toLowerCase();
+    const scores = [];
+
+    for (const domain of this._domains) {
+      const keywords = DOMAIN_KEYWORDS[domain];
+      if (!keywords) {
+        scores.push({ domain, confidence: 0 });
+        continue;
+      }
+
+      let hits = 0;
+      for (const kw of keywords) {
+        if (text.includes(kw.toLowerCase())) hits++;
+      }
+      scores.push({ domain, confidence: keywords.length > 0 ? hits / keywords.length : 0 });
+    }
+
+    scores.sort((a, b) => b.confidence - a.confidence);
+
+    if (scores[0].confidence === 0) return null;
+
+    const top = scores.slice(0, this._topK);
+    return {
+      primary: { domain: top[0].domain, confidence: round4(top[0].confidence) },
+      secondary: { domain: top[1].domain, confidence: round4(top[1].confidence) },
+      tertiary: { domain: top[2].domain, confidence: round4(top[2].confidence) },
+    };
+  }
+
+  async _buildCentroids() {
+    this._centroids = {};
+    for (const domain of this._domains) {
+      const kws = DOMAIN_KEYWORDS[domain];
+      const description = kws ? `${domain}: ${kws.join(', ')}` : domain;
+      const embedding = await this._embed(description);
+      if (embedding) {
+        this._centroids[domain] = embedding;
+      }
+    }
+  }
+
+  async _embed(text) {
+    try {
+      const res = await fetch(this._serviceUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ input: text, model: this._model }),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!res.ok) {
+        this._lastError = `Embedding service returned ${res.status}`;
+        return null;
+      }
+
+      const data = await res.json();
+      const embedding = data?.data?.[0]?.embedding;
+      if (!Array.isArray(embedding)) {
+        this._lastError = 'Invalid embedding response format';
+        return null;
+      }
+      return embedding;
+    } catch (err) {
+      this._lastError = err.message || String(err);
+      return null;
+    }
+  }
+}
+
+export function cosineSimilarity(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+function round4(n) {
+  return Math.round(n * 10000) / 10000;
+}