User query 1: "how do I configure rate limiting in Node"
User query 2: "what's the best way to throttle API requests in Express"
User query 3: "Express rate limit middleware options"

MD5 hashes:   completely different → 3 cache misses → 3 LLM calls
Vector cosine similarity: 0.94, 0.91, 0.89 → all above threshold → 2 cache hits

// ✅ Redis semantic cache with XFetch stampede prevention
// file: src/cache/SemanticCache.ts

import { createClient, SchemaFieldTypes, VectorAlgorithms } from 'redis'
import { embedAndNormalise } from '../../packages/db/src/embeddings'

const redis = createClient({ url: process.env.REDIS_URL })
await redis.connect()

const CACHE_INDEX = 'semantic_cache_idx'
const SIMILARITY_THRESHOLD = 0.94  // Tune: 0.92 aggressive, 0.96 conservative
const CACHE_TTL_SECONDS = 60 * 60 * 24 * 7  // 7 days

// Create RediSearch vector index (run once at startup)
async function initIndex(): Promise<void> {
  try {
    await redis.ft.create(CACHE_INDEX, {
      '$.orgId':    { type: SchemaFieldTypes.TAG, AS: 'orgId' },
      '$.embedding': {
        type: SchemaFieldTypes.VECTOR,
        ALGORITHM: VectorAlgorithms.HNSW,
        TYPE: 'FLOAT32',
        DIM: 1536,
        DISTANCE_METRIC: 'COSINE',
        AS: 'embedding',
      },
    }, {
      ON: 'JSON',
      PREFIX: 'cache:',
    })
  } catch (e) {
    if (!(e as Error).message.includes('Index already exists')) throw e
  }
}

export interface CachedResponse {
  query: string
  response: string
  model: string
  similarity: number
}

export async function checkSemanticCache(
  orgId: string,
  query: string,
): Promise<CachedResponse | null> {
  const embedding = await embedAndNormalise(query)
  const embeddingBuffer = Buffer.from(new Float32Array(embedding).buffer)

  const results = await redis.ft.search(
    CACHE_INDEX,
    `(@orgId:{${orgId}}) => [KNN 1 @embedding $vec AS vector_score]`,
    {
      PARAMS: { vec: embeddingBuffer },
      RETURN: ['$.query', '$.response', '$.model', 'vector_score'],
      SORTBY: { BY: 'vector_score', DIRECTION: 'ASC' },
      LIMIT: { from: 0, size: 1 },
      DIALECT: 2,
    }
  )

  if (results.total === 0) return null

  const doc = results.documents[0]
  const cosineSimilarity = 1 - parseFloat(doc.value.vector_score as string)

  if (cosineSimilarity < SIMILARITY_THRESHOLD) return null

  return {
    query: doc.value['$.query'] as string,
    response: doc.value['$.response'] as string,
    model: doc.value['$.model'] as string,
    similarity: cosineSimilarity,
  }
}

export async function writeToSemanticCache(
  orgId: string,
  query: string,
  response: string,
  model: string,
): Promise<void> {
  const embedding = await embedAndNormalise(query)
  const key = `cache:${orgId}:${crypto.randomUUID()}`

  await redis.json.set(key, '$', {
    orgId,
    query,
    response,
    model,
    embedding: Array.from(embedding),
    cachedAt: Date.now(),
  })

  await redis.expire(key, CACHE_TTL_SECONDS)
}

// ✅ XFetch: probabilistic early cache refresh
// file: src/cache/XFetch.ts

/**
 * XFetch formula: refresh if current_time - (beta * delta * log(random())) >= expiry_time
 * beta: how aggressively to refresh early (1.0 = standard)
 * delta: time to compute the value (in seconds)
 */
export function shouldEarlyRefresh(
  cachedAt: number,        // Timestamp when entry was cached (ms)
  ttlSeconds: number,      // TTL of the entry
  computeDurationMs: number, // How long it takes to regenerate (ms)
  beta = 1.0,
): boolean {
  const expiresAt = cachedAt + ttlSeconds * 1000
  const now = Date.now()
  const delta = computeDurationMs / 1000  // Convert to seconds
  const earlyRefreshWindow = -beta * delta * Math.log(Math.random())
  return now >= expiresAt - earlyRefreshWindow * 1000
}

// ✅ Semantic cache middleware in the AI gateway
// file: src/gateway/CachedGateway.ts

import { checkSemanticCache, writeToSemanticCache } from '../cache/SemanticCache'

export class CachedGateway {
  constructor(private readonly gateway: AiGateway) {}

  async *streamResponse(
    request: GatewayRequest,
    signal: AbortSignal,
  ): AsyncGenerator<WorkspaceAction> {
    // Check semantic cache first
    const cached = await checkSemanticCache(request.orgId, request.userQuery)

    if (cached) {
      // Serve from cache — reconstruct as streaming tokens for UI consistency
      for (const char of cached.response) {
        yield {
          type: 'text_reply',
          payload: { content: char, citations: [] },
          confidence: cached.similarity,
        } as WorkspaceAction
      }
      // Add cache metadata header via a synthetic action
      return
    }

    // Cache miss — route to LLM and capture response for caching
    let fullResponse = ''

    for await (const action of this.gateway.streamResponse(request, signal)) {
      if (action.type === 'text_reply') {
        fullResponse += action.payload.content
      }
      yield action
    }

    // Write to cache asynchronously — don't block streaming response
    if (fullResponse.length > 0) {
      writeToSemanticCache(
        request.orgId,
        request.userQuery,
        fullResponse,
        request.model,
      ).catch(err => console.error('[SemanticCache] Write failed:', err))
    }
  }
}