thumbgate 1.29.2 → 1.31.0

package/scripts/tier-budget-guard.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * Hard cost + latency budgets for model tier routing.
+ *
+ * Complements FrontierBudget (session token cap) with:
+ *   - per-request max cost (cents)
+ *   - per-request max latency budget (ms) for planning/degrade
+ *   - max frontier invocations per day (process-local counter)
+ *
+ * Env (optional):
+ *   THUMBGATE_MAX_COST_CENTS_PER_REQUEST
+ *   THUMBGATE_MAX_LATENCY_MS
+ *   THUMBGATE_MAX_FRONTIER_PER_DAY
+ */
+
+const { TIERS, classifyTask, FrontierBudget } = require('./model-tier-router');
+
+const DEFAULTS = Object.freeze({
+  maxCostCentsPerRequest: 25, // $0.25
+  maxLatencyMs: 30_000,
+  maxFrontierPerDay: 50,
+});
+
+/** @type {Map<string, number>} dayKey → frontier invocation count */
+const frontierDayCounts = new Map();
+
+function dayKey(now = Date.now()) {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function readEnvNumber(name, fallback) {
+  const raw = process.env[name];
+  if (raw == null || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function getBudgetConfig(overrides = {}) {
+  return {
+    maxCostCentsPerRequest: overrides.maxCostCentsPerRequest
+      ?? readEnvNumber('THUMBGATE_MAX_COST_CENTS_PER_REQUEST', DEFAULTS.maxCostCentsPerRequest),
+    maxLatencyMs: overrides.maxLatencyMs
+      ?? readEnvNumber('THUMBGATE_MAX_LATENCY_MS', DEFAULTS.maxLatencyMs),
+    maxFrontierPerDay: overrides.maxFrontierPerDay
+      ?? readEnvNumber('THUMBGATE_MAX_FRONTIER_PER_DAY', DEFAULTS.maxFrontierPerDay),
+  };
+}
+
+/**
+ * Estimate request cost cents from tier + token budget.
+ * @param {string} tier
+ * @param {number} estimatedTokens
+ */
+function estimateTierCostCents(tier, estimatedTokens = 4000) {
+  const t = TIERS[tier] || TIERS.mini;
+  // Base: ~$3/M input + $15/M out blended as ~$6/M total for coding
+  const basePerM = 6;
+  const usd = (estimatedTokens / 1e6) * basePerM * (t.costMultiplier ?? 1);
+  return Number((usd * 100).toFixed(4));
+}
+
+/**
+ * Enforce hard budgets on a classification result.
+ *
+ * @param {object} task — same shape as classifyTask
+ * @param {object} [options]
+ * @param {object} [options.classification] — precomputed classifyTask result
+ * @param {FrontierBudget} [options.frontierBudget]
+ * @param {number} [options.estimatedTokens]
+ * @param {number} [options.nowMs]
+ * @returns {{
+ *   allowed: boolean,
+ *   tier: string,
+ *   action: 'allow'|'degrade'|'deny',
+ *   reasons: string[],
+ *   classification: object,
+ *   estimatedCostCents: number,
+ *   budget: object,
+ * }}
+ */
+function enforceTierBudgets(task = {}, options = {}) {
+  const config = getBudgetConfig(options);
+  const classification = options.classification || classifyTask(task);
+  let tier = classification.tier;
+  const reasons = [];
+  const estimatedTokens = Number(options.estimatedTokens) || 4000;
+  let estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+  let action = 'allow';
+
+  // Daily frontier cap (process-local)
+  if (tier === 'frontier') {
+    const key = dayKey(options.nowMs);
+    const used = frontierDayCounts.get(key) || 0;
+    if (used >= config.maxFrontierPerDay) {
+      reasons.push(`frontier_daily_cap:${used}/${config.maxFrontierPerDay}`);
+      tier = 'mini';
+      action = 'degrade';
+      estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+    }
+  }
+
+  // Per-request cost cap → degrade tier then deny if still over
+  if (estimatedCostCents > config.maxCostCentsPerRequest) {
+    if (tier === 'frontier') {
+      reasons.push(`cost_over_cap_degrade:${estimatedCostCents}>${config.maxCostCentsPerRequest}`);
+      tier = 'mini';
+      action = 'degrade';
+      estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+    }
+  }
+  if (estimatedCostCents > config.maxCostCentsPerRequest && tier !== 'nano' && tier !== 'localFrontier') {
+    reasons.push(`cost_over_cap_degrade_nano:${estimatedCostCents}>${config.maxCostCentsPerRequest}`);
+    tier = 'nano';
+    action = 'degrade';
+    estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+  }
+  if (estimatedCostCents > config.maxCostCentsPerRequest && (TIERS[tier]?.costMultiplier || 0) > 0) {
+    reasons.push(`cost_deny:${estimatedCostCents}>${config.maxCostCentsPerRequest}`);
+    action = 'deny';
+  }
+
+  // Session frontier token budget
+  const frontierBudget = options.frontierBudget || null;
+  if (frontierBudget && tier === 'frontier' && typeof frontierBudget.canSpend === 'function') {
+    const check = frontierBudget.canSpend(estimatedTokens, task.reason || classification.reason || 'routed_frontier');
+    if (!check.allowed) {
+      reasons.push(`frontier_session_budget:${check.reason}`);
+      tier = 'mini';
+      action = action === 'deny' ? 'deny' : 'degrade';
+      estimatedCostCents = estimateTierCostCents(tier, estimatedTokens);
+    }
+  }
+
+  // Latency budget is advisory for planning (caller may still enforce timeouts)
+  if (Number(task.expectedLatencyMs) > config.maxLatencyMs) {
+    reasons.push(`latency_budget_exceeded_plan:${task.expectedLatencyMs}>${config.maxLatencyMs}`);
+    if (tier === 'frontier') {
+      tier = 'mini';
+      action = action === 'deny' ? 'deny' : 'degrade';
+    }
+  }
+
+  const allowed = action !== 'deny';
+  return {
+    allowed,
+    tier,
+    action,
+    reasons,
+    classification,
+    estimatedCostCents,
+    budget: {
+      ...config,
+      estimatedTokens,
+    },
+  };
+}
+
+/**
+ * Record a frontier invocation against the daily counter (call only when actually used).
+ */
+function recordFrontierInvocation(nowMs = Date.now()) {
+  const key = dayKey(nowMs);
+  frontierDayCounts.set(key, (frontierDayCounts.get(key) || 0) + 1);
+  return frontierDayCounts.get(key);
+}
+
+/** Test helper */
+function _resetFrontierDayCounts() {
+  frontierDayCounts.clear();
+}
+
+function getFrontierDayUsage(nowMs = Date.now()) {
+  const key = dayKey(nowMs);
+  return { day: key, count: frontierDayCounts.get(key) || 0 };
+}
+
+module.exports = {
+  DEFAULTS,
+  getBudgetConfig,
+  estimateTierCostCents,
+  enforceTierBudgets,
+  recordFrontierInvocation,
+  getFrontierDayUsage,
+  _resetFrontierDayCounts,
+};

package/scripts/tool-kpi-tracker.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveFeedbackDir } = require('./feedback-paths');
+const { readJsonl } = require('./fs-utils');
+
+function getKpiLogPath(options = {}) {
+  return path.join(
+    options.feedbackDir ? path.resolve(options.feedbackDir) : resolveFeedbackDir(),
+    'tool-kpi.jsonl',
+  );
+}
+
+function recordToolCall({
+  toolName,
+  serverName,
+  latencyMs,
+  success,
+  agentId,
+  metadata,
+  feedbackDir,
+} = {}) {
+  const logPath = getKpiLogPath({ feedbackDir });
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const entry = {
+    id: `kpi_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`,
+    timestamp: new Date().toISOString(),
+    toolName: toolName || 'unknown',
+    serverName: serverName || 'default',
+    latencyMs: typeof latencyMs === 'number' ? latencyMs : 0,
+    success: success !== false,
+    agentId: agentId || 'unknown',
+    metadata: metadata || {},
+  };
+  fs.appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
+  return entry;
+}
+
+function percentile(sorted, quantile) {
+  if (sorted.length === 0) return 0;
+  const index = Math.ceil((quantile / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, index)];
+}
+
+function computeToolKpis({ periodHours = 24, feedbackDir } = {}) {
+  const entries = readJsonl(getKpiLogPath({ feedbackDir }));
+  const cutoff = Date.now() - periodHours * 60 * 60 * 1000;
+  const recent = entries.filter((entry) => new Date(entry.timestamp).getTime() > cutoff);
+  const byTool = {};
+  for (const entry of recent) {
+    const key = entry.toolName;
+    if (!byTool[key]) {
+      byTool[key] = {
+        toolName: key,
+        calls: [],
+        successes: 0,
+        failures: 0,
+      };
+    }
+    byTool[key].calls.push(entry.latencyMs);
+    if (entry.success) byTool[key].successes += 1;
+    else byTool[key].failures += 1;
+  }
+  const tools = Object.values(byTool)
+    .map((tool) => {
+      const sorted = tool.calls.slice().sort((left, right) => left - right);
+      const total = tool.successes + tool.failures;
+      return {
+        toolName: tool.toolName,
+        requestCount: total,
+        successRate: total > 0 ? Math.round((tool.successes / total) * 1000) / 10 : 100,
+        p50: Math.round(percentile(sorted, 50)),
+        p90: Math.round(percentile(sorted, 90)),
+        p95: Math.round(percentile(sorted, 95)),
+        successes: tool.successes,
+        failures: tool.failures,
+      };
+    })
+    .sort((left, right) => right.requestCount - left.requestCount);
+
+  const byServer = {};
+  for (const entry of recent) {
+    const key = entry.serverName;
+    if (!byServer[key]) byServer[key] = { serverName: key, total: 0, successes: 0 };
+    byServer[key].total += 1;
+    if (entry.success) byServer[key].successes += 1;
+  }
+  const servers = Object.values(byServer).map((server) => ({
+    serverName: server.serverName,
+    totalCalls: server.total,
+    successRate: server.total > 0
+      ? Math.round((server.successes / server.total) * 1000) / 10
+      : 100,
+  }));
+  return {
+    periodHours,
+    totalCalls: recent.length,
+    evidenceStatus: recent.length > 0 ? 'measured' : 'insufficient_evidence',
+    tools,
+    servers,
+  };
+}
+
+function getAtRiskTools({
+  successRateThreshold = 90,
+  p95Threshold = 500,
+  periodHours = 24,
+  feedbackDir,
+} = {}) {
+  const { tools } = computeToolKpis({ periodHours, feedbackDir });
+  return tools.filter((tool) => tool.requestCount >= 3
+    && (tool.successRate < successRateThreshold || tool.p95 > p95Threshold));
+}
+
+module.exports = {
+  computeToolKpis,
+  getAtRiskTools,
+  getKpiLogPath,
+  percentile,
+  recordToolCall,
+};

package/scripts/tool-registry.js

@@ -133,8 +133,20 @@ const TASK_OUTCOME_INPUT_SCHEMA = {
   },
 };
 
+const MEMORY_SCOPE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['entityId', 'projectId', 'processId', 'sessionId'],
+  properties: {
+    entityId: { type: 'string', minLength: 1 },
+    projectId: { type: 'string', minLength: 1 },
+    processId: { type: 'string', minLength: 1 },
+    sessionId: { type: 'string', minLength: 1 },
+  },
+};
+
 const TOOLS = [
-  readOnlyTool({
+  destructiveTool({
     name: 'capture_feedback',
     description: 'Capture an up/down signal plus one line of why. Vague feedback is logged, then returned with a clarification prompt instead of memory promotion.',
     inputSchema: {
@@ -218,6 +230,9 @@ const TOOLS = [
         limit: { type: 'number', description: 'Maximum results to return (default 10)' },
         category: { type: 'string', enum: ['error', 'learning', 'preference'] },
         tags: { type: 'array', items: { type: 'string' }, description: 'Require all tags to be present on a lesson' },
+        scope: MEMORY_SCOPE_SCHEMA,
+        requireScope: { type: 'boolean', description: 'Fail closed unless a complete four-field scope is supplied.' },
+        includeShared: { type: 'boolean', description: 'Include explicitly shared memories with scoped results. Defaults true.' },
       },
     },
   }),
@@ -230,6 +245,23 @@ const TOOLS = [
         toolName: { type: 'string', description: 'The tool being called (e.g., Bash, Edit, Read)' },
         actionContext: { type: 'string', description: 'Description of what the tool call is doing' },
         maxResults: { type: 'number', description: 'Max lessons to return (default 5)' },
+        scope: MEMORY_SCOPE_SCHEMA,
+        requireScope: { type: 'boolean', description: 'Fail closed unless a complete four-field scope is supplied.' },
+        includeShared: { type: 'boolean', description: 'Include explicitly shared memories with scoped results. Defaults true.' },
+        filters: {
+          type: 'object',
+          description: 'Pre-filter the candidate corpus before lexical or vector ranking.',
+          properties: {
+            domain: { type: ['string', 'array'], items: { type: 'string' } },
+            signal: { type: ['string', 'array'], items: { type: 'string' } },
+            source: { type: ['string', 'array'], items: { type: 'string' } },
+            toolsUsed: { type: ['string', 'array'], items: { type: 'string' } },
+            tags: { type: 'array', items: { type: 'string' } },
+            requireAllTags: { type: 'boolean' },
+          },
+        },
+        queryRewrite: { type: 'boolean', description: 'Enable bounded deterministic synonym expansion when the original lexical match is weak. Defaults true.' },
+        includeRetrievalMeta: { type: 'boolean', description: 'Include path provenance such as lexical/dense pools and query variants.' },
       },
       required: ['toolName'],
     },
@@ -258,6 +290,17 @@ const TOOLS = [
         limit: { type: 'number', description: 'Maximum results to return (default 10)' },
         source: { type: 'string', enum: ['all', 'feedback', 'context', 'rules', 'documents'], description: 'Restrict search to a single ThumbGate source.' },
         signal: { type: 'string', enum: ['up', 'down', 'positive', 'negative'], description: 'Optional feedback-signal filter when searching feedback data.' },
+        filters: {
+          type: 'object',
+          description: 'Pre-filter imported documents before chunk ranking.',
+          properties: {
+            tags: { type: 'array', items: { type: 'string' } },
+            requireAllTags: { type: 'boolean' },
+            sourceFormat: { type: 'string' },
+            sourceType: { type: 'string' },
+          },
+        },
+        queryRewrite: { type: 'boolean', description: 'Enable bounded deterministic synonym expansion. Defaults true.' },
       },
     },
   }),
@@ -904,6 +947,10 @@ const TOOLS = [
           items: { type: 'string' },
           description: 'Optional protected-file globs that require explicit approval before editing or publishing',
         },
+        ttlMs: {
+          type: 'number',
+          description: 'Optional lease length in milliseconds. With it the scope becomes time-bounded authority (e.g. 90000 for "write under ./src for 90 seconds") and FAILS CLOSED on expiry: a lapsed lease authorises nothing until renewed. Omit for a permanent scope. Clamped to 60s..24h.',
+        },
         workflowContract: {
           type: 'object',
           description: 'Optional deterministic workflow run contract. Supports workflowId, allowedBranches, blockedActions, requiredEvidence, and completionGate.',
@@ -1047,6 +1094,16 @@ const TOOLS = [
     title: 'Record Verified Task Outcome',
     description: 'Record an idempotent task-level outcome with verification evidence, tool correctness, policy behavior, latency, cost, and business KPI movement. A completed response without evidence is recorded as not working.',
     inputSchema: TASK_OUTCOME_INPUT_SCHEMA,
+    outputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['recorded', 'duplicate', 'receipt'],
+      properties: {
+        recorded: { type: 'boolean' },
+        duplicate: { type: 'boolean' },
+        receipt: { type: 'object', additionalProperties: true },
+      },
+    },
   }),
   readOnlyTool({
     name: 'get_task_outcomes',
@@ -1070,6 +1127,22 @@ const TOOLS = [
       additionalProperties: false,
       properties: {},
     },
+    outputSchema: {
+      type: 'object',
+      additionalProperties: true,
+      required: ['generatedAt', 'sampleSize', 'evidenceStatus', 'task', 'tools', 'safety', 'escalation', 'efficiency', 'businessOutcomes'],
+      properties: {
+        generatedAt: { type: 'string', format: 'date-time' },
+        sampleSize: { type: 'integer', minimum: 0 },
+        evidenceStatus: { type: 'string', enum: ['measured', 'insufficient_evidence'] },
+        task: { type: 'object', additionalProperties: true },
+        tools: { type: 'object', additionalProperties: true },
+        safety: { type: 'object', additionalProperties: true },
+        escalation: { type: 'object', additionalProperties: true },
+        efficiency: { type: 'object', additionalProperties: true },
+        businessOutcomes: { type: 'array' },
+      },
+    },
   }),
   destructiveTool({
     name: 'request_human_escalation',
@@ -1237,6 +1310,27 @@ const TOOLS = [
       },
     },
   }),
+  readOnlyTool({
+    name: 'gate_check',
+    // Harnesses with a native pre-tool hook (Claude Code, Codex, Gemini, Forge) get hard
+    // enforcement and never need this. MCP-only harnesses (Cline, Cursor, OpenCode) have no
+    // interception point, so this exposes the SAME gates engine as a tool the agent calls
+    // before acting. adapters/cline/.clinerules has instructed agents to call
+    // `thumbgate.gate_check` since the adapter shipped — but the tool did not exist, so
+    // that enforcement was inert. This makes the documented contract real.
+    description: 'Evaluate a proposed tool call against ThumbGate policy BEFORE executing it. Returns decision "block" (do not run the action; surface the reason) or "allow". Use this when about to run a shell command, write/edit a file, or take any irreversible action.',
+    inputSchema: {
+      type: 'object',
+      required: ['tool_name'],
+      properties: {
+        tool_name: { type: 'string', description: 'The tool about to be invoked (e.g. Bash, Write, Edit)' },
+        tool_input: {
+          type: 'object',
+          description: 'The proposed arguments, e.g. { "command": "rm -rf /" } for Bash or { "file_path": "..." } for Write',
+        },
+      },
+    },
+  }),
   readOnlyTool({
     name: 'gate_stats',
     description: 'Get gate enforcement statistics -- blocked count, warned count, top gates',

package/scripts/vector-store.js

@@ -80,6 +80,42 @@ function hasLocalTransformerProvider() {
   }
 }
 
+function getOllamaEmbeddingConfig() {
+  const model = String(process.env.THUMBGATE_OLLAMA_EMBED_MODEL || '').trim();
+  let endpoint = String(
+    process.env.THUMBGATE_OLLAMA_ENDPOINT
+    || process.env.OLLAMA_HOST
+    || 'http://127.0.0.1:11434',
+  ).trim();
+  if (endpoint && !/^https?:\/\//i.test(endpoint)) endpoint = `http://${endpoint}`;
+  while (endpoint.endsWith('/')) endpoint = endpoint.slice(0, -1);
+  return {
+    enabled: Boolean(model),
+    model,
+    endpoint,
+    timeoutMs: Math.max(
+      250,
+      Math.min(30_000, Number(process.env.THUMBGATE_OLLAMA_TIMEOUT_MS) || 10_000),
+    ),
+  };
+}
+
+/**
+ * Synchronous capability check used by hot-path routing. This reports only
+ * semantic providers, never the deterministic feature-hash degradation.
+ */
+function hasSemanticEmbeddingProvider() {
+  if (process.env.THUMBGATE_VECTOR_STUB_EMBED === 'true') return true;
+  if (getOllamaEmbeddingConfig().enabled) return true;
+  if (hasLocalTransformerProvider()) return true;
+  try {
+    const config = resolveGeminiEmbeddingConfig();
+    return config.provider === 'coreai' || Boolean(config.enabled && config.apiKey);
+  } catch {
+    return false;
+  }
+}
+
 function fnv1a32(value) {
   let hash = 0x811c9dc5;
   const bytes = Buffer.from(String(value), 'utf8');
@@ -98,7 +134,7 @@ function addHashedFeature(vector, feature, weight) {
 }
 
 function embedWithFeatureHash(text) {
-  const vector = Array(FEATURE_HASH_DIMENSIONS).fill(0);
+  const vector = new Array(FEATURE_HASH_DIMENSIONS).fill(0);
   const tokens = String(text || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [];
 
   for (let index = 0; index < tokens.length; index += 1) {
@@ -249,6 +285,43 @@ async function embedWithCoreAI(text, options = {}) {
   throw new Error('Core AI local service did not return a valid embedding');
 }
 
+async function embedWithOllama(text, options = {}) {
+  const config = getOllamaEmbeddingConfig();
+  if (!config.enabled) {
+    throw new Error('Ollama embeddings require THUMBGATE_OLLAMA_EMBED_MODEL');
+  }
+  if (typeof fetch !== 'function') {
+    throw new Error('Ollama embeddings require global fetch. Use Node 18.18+.');
+  }
+
+  let response;
+  try {
+    response = await fetch(`${config.endpoint}/api/embed`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: config.model,
+        input: String(text || ''),
+        truncate: true,
+        dimensions: options.outputDimensionality || undefined,
+      }),
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+  } catch (error) {
+    throw new Error(`Ollama embedding service unavailable: ${error.message}`);
+  }
+
+  if (!response.ok) {
+    throw new Error(`Ollama embedding request failed: ${response.status} ${response.statusText}`);
+  }
+  const payload = await response.json();
+  const vector = Array.isArray(payload.embeddings) ? payload.embeddings[0] : null;
+  if (!Array.isArray(vector) || vector.length === 0) {
+    throw new Error('Ollama embedding response did not include vector values');
+  }
+  return vector.map(Number);
+}
+
 async function embed(text, options = {}) {
   if (process.env.THUMBGATE_VECTOR_STUB_EMBED === 'true') {
     // Deterministic 384-dim unit vector: first element = 1.0, rest = 0.0
@@ -277,6 +350,28 @@ async function embed(text, options = {}) {
       console.warn(`Core AI embedding failed, falling back to local: ${coreaiError.message}`);
     }
   }
+  const ollamaConfig = getOllamaEmbeddingConfig();
+  if (ollamaConfig.enabled) {
+    try {
+      const vector = await embedWithOllama(text, options);
+      _lastEmbeddingProfile = {
+        generatedAt: new Date().toISOString(),
+        source: 'local-ollama',
+        activeProfile: {
+          id: 'ollama',
+          model: ollamaConfig.model,
+          outputDimensionality: vector.length,
+          task: options.task || 'code retrieval',
+          rationale: 'Explicit local Ollama semantic embedding provider.',
+          qualityTier: 'production',
+        },
+        fallbackUsed: false,
+      };
+      return vector;
+    } catch (ollamaError) {
+      console.warn(`Ollama embedding failed, falling back: ${ollamaError.message}`);
+    }
+  }
   if (geminiConfig.enabled) {
     try {
       const vector = await embedWithGemini(text, options);
@@ -297,7 +392,9 @@ async function embed(text, options = {}) {
       if (!geminiConfig.fallbackToLocal) {
         throw geminiError;
       }
-      console.warn(`Gemini embedding fallback: ${geminiError.message}`);
+      // Do not log raw provider/user-controlled error text (Sonar jssecurity:S5145).
+      const code = geminiError && (geminiError.code || geminiError.name || 'Error');
+      console.warn(`Gemini embedding fallback: ${code}`);
     }
   }
   if (hasLocalTransformerProvider()) {
@@ -314,6 +411,8 @@ async function embed(text, options = {}) {
   }
 
   const vector = embedWithFeatureHash(text);
+  // Feature-hash is a last-resort degrade, not production semantic quality.
+  // Callers (prove/eval/chat health) must treat quality_tier=degraded.
   _lastEmbeddingProfile = {
     generatedAt: new Date().toISOString(),
     source: 'built-in',
@@ -322,9 +421,11 @@ async function embed(text, options = {}) {
       model: 'ThumbGate feature hashing',
       outputDimensionality: FEATURE_HASH_DIMENSIONS,
       task: options.task || 'code retrieval',
-      rationale: 'Deterministic zero-dependency local text embedding.',
+      rationale: 'DEGRADED: deterministic zero-dependency hash embedding — not semantic. Configure Gemini or local transformers for production retrieval quality.',
+      qualityTier: 'degraded',
     },
-    fallbackUsed: false,
+    fallbackUsed: true,
+    fallbackReason: 'no_managed_or_transformer_embedder',
   };
   return vector;
 }
@@ -440,4 +541,7 @@ module.exports = {
   setGeminiEmbedderForTests,
   truncateForEmbedding,
   embedWithFeatureHash,
+  embedWithOllama,
+  getOllamaEmbeddingConfig,
+  hasSemanticEmbeddingProvider,
 };