HologramAgent-DSH-Memory-Port/lib/embed/http.js

/**
 * HTTP embedding adapter — the ONLY file allowed to know a transport.
 *
 * Group G's `G5` guard enforces that: no other file under `lib/` may contain
 * `fetch(`, `Authorization`, `Bearer`, `http(s)://`, `model_dir`, or `api_key`.
 * Keeping the transport confined here is what makes "swap HTTP for a local ONNX
 * runner" a one-file change instead of an audit of the whole plugin.
 *
 * ## Protocol
 *
 * Deliberately identical to HologramAgent's `http` provider
 * (`internal/memory/vector/http_embedder.go:72-87`) so an existing HA sidecar can
 * be pointed at without a shim:
 *
 * ```jsonc
 * // request
 * { "model": "...", "modality": "text", "side": "query",
 *   "text": "...", "data": "<base64>", "mime": "image/png" }
 * // response — either shape is accepted
 * { "embedding": [ ... ] }
 * { "data": [ { "embedding": [ ... ] } ] }
 * ```
 *
 * ## Fingerprint
 *
 * `http:<model>:<dim>:<sha256(normalised endpoint)[:8]>`
 *
 * HA derives `http:<model>:<dim>` (`http_embedder.go:99`) — model and dimension
 * only. That is unsafe once an endpoint is configurable: two deployments of the
 * same model name at the same dimension produce **the same fingerprint but
 * different vectors** (different weights, different hardware, a different
 * region), so blocks from both spaces compare silently and wrongly. Adding the
 * endpoint hash closes that hole. The digest is truncated to 8 hex chars: it
 * only needs to distinguish a handful of configured endpoints, not to resist an
 * attacker.
 *
 * Normalisation happens **before** hashing so that cosmetic differences in the
 * configuration string do not each trigger a full re-embed:
 *
 *   - strip surrounding whitespace
 *   - lowercase the scheme and the host
 *   - drop a trailing `/` from the path
 *   - drop an explicit default port (`:80` for http, `:443` for https)
 *
 * It deliberately does NOT reorder query strings or resolve `..` in paths:
 * those differences are usually real, and hiding them would mask a genuine
 * misconfiguration.
 *
 * @module dsh-memory/embed/http
 */

import { createHash } from 'node:crypto'

/** Request timeout; HA's default is 30s (`http_embedder.go:95-97`). */
const DEFAULT_TIMEOUT_MS = 30_000

/** Response body cap. HA uses 4 MiB (`http_embedder.go:136`). */
const MAX_RESPONSE_BYTES = 4 * 1024 * 1024

/**
 * Normalise an endpoint string for fingerprinting.
 *
 * @param {string} endpoint
 * @returns {string} the normalised form (empty string when input is unusable)
 */
export function normalizeEndpoint(endpoint) {
  const raw = String(endpoint ?? '').trim()
  if (raw === '') return ''

  let url
  try {
    url = new URL(raw)
  } catch {
    // Not a parseable URL: fall back to the trimmed string so the fingerprint is
    // still stable, and let the request itself fail loudly later.
    return raw
  }

  // URL already lowercases protocol and host; be explicit about it so the
  // behaviour survives a switch away from WHATWG URL.
  const scheme = url.protocol.toLowerCase()
  const host = url.hostname.toLowerCase()
  const defaultPort = scheme === 'https:' ? '443' : scheme === 'http:' ? '80' : ''
  const port = url.port === defaultPort ? '' : url.port
  const path = url.pathname.replace(/\/+$/, '')
  const search = url.search

  return `${scheme}//${host}${port === '' ? '' : `:${port}`}${path}${search}`
}

/**
 * Derive the vector-space fingerprint.
 *
 * @param {object} input
 * @param {string} input.endpoint configured endpoint (normalised internally)
 * @param {string} [input.model]
 * @param {number} input.dimension
 * @param {string} [input.fingerprint] explicit override (HA has the same escape hatch)
 * @returns {string}
 */
export function deriveFingerprint({ endpoint, model = '', dimension, fingerprint }) {
  if (typeof fingerprint === 'string' && fingerprint !== '') return fingerprint
  const normalised = normalizeEndpoint(endpoint)
  const digest = createHash('sha256').update(normalised, 'utf8').digest('hex').slice(0, 8)
  return `http:${model}:${dimension}:${digest}`
}

/**
 * Build an embedder over an HTTP endpoint.
 *
 * Returns the same three-member shape `recallBlocksHybrid` expects — nothing
 * here leaks into scoring, storage, or grouping.
 *
 * @param {object} config
 * @param {string} config.endpoint
 * @param {number} config.dimension
 * @param {string} [config.model]
 * @param {string} [config.apiKey]
 * @param {string} [config.fingerprint] override
 * @param {number} [config.timeoutMs]
 * @returns {{ embedText: (text: string) => Promise<number[]>,
 *             info: () => {fingerprint: string, dimension: number},
 *             close: () => Promise<void> }}
 */
export function createHttpEmbedder(config) {
  const {
    endpoint,
    dimension,
    model = '',
    apiKey = '',
    fingerprint,
    timeoutMs = DEFAULT_TIMEOUT_MS,
  } = config ?? {}

  if (typeof endpoint !== 'string' || endpoint.trim() === '') {
    throw new Error('dsh-memory: http embedder requires an endpoint')
  }
  if (!Number.isInteger(dimension) || dimension <= 0) {
    throw new Error(`dsh-memory: http embedder requires a positive integer dimension, got ${dimension}`)
  }

  const normalisedEndpoint = normalizeEndpoint(endpoint)
  // ★ Computed ONCE and reused. The same string must reach both
  // `memory_blocks.fingerprint` and `graph_centroid.fingerprint`; deriving it
  // per call risks two tables holding two spellings, which makes
  // `LoadCentroid` miss silently (no error, centering just never applies).
  const fp = deriveFingerprint({ endpoint: normalisedEndpoint, model, dimension, fingerprint })

  let closed = false
  const info = () => ({ fingerprint: fp, dimension })

  async function embedText(text) {
    if (closed) throw new Error('dsh-memory: http embedder closed')
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), timeoutMs)
    try {
      const response = await fetch(normalisedEndpoint, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          ...(apiKey === '' ? {} : { Authorization: `Bearer ${apiKey}` }),
        },
        body: JSON.stringify({
          model,
          modality: 'text',
          side: 'query',
          text: String(text ?? ''),
        }),
        signal: controller.signal,
      })

      if (!response.ok) {
        const body = await response.text().catch(() => '')
        throw new Error(`dsh-memory: embed endpoint returned ${response.status}: ${body.slice(0, 200)}`)
      }

      const raw = await response.text()
      if (raw.length > MAX_RESPONSE_BYTES) {
        throw new Error(`dsh-memory: embed response exceeds ${MAX_RESPONSE_BYTES} bytes`)
      }
      const payload = JSON.parse(raw)

      // Both shapes are accepted (HA: http_embedder.go:81-87).
      const vector = Array.isArray(payload?.embedding)
        ? payload.embedding
        : Array.isArray(payload?.data?.[0]?.embedding)
          ? payload.data[0].embedding
          : undefined

      if (!Array.isArray(vector)) {
        throw new Error('dsh-memory: embed response carries no embedding array')
      }
      if (vector.length !== dimension) {
        // Hard error, never truncate or pad: a silently mis-sized vector is a
        // meaningless score that looks plausible (HA: block_recall.go:135-138).
        throw new Error(`dsh-memory: embed dimension ${vector.length}, want ${dimension}`)
      }
      return vector
    } finally {
      clearTimeout(timer)
    }
  }

  return {
    embedText,
    info,
    async close() {
      closed = true
    },
  }
}