dsh-memu-memory 1.1.1 → 1.1.3

package/lib/local-embedding-entry.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { startEmbeddingWorker } from './local-embedding-worker.js'
+import { LocalEmbeddingError } from './local-embedding-protocol.js'
+
+// §14.5: the worker runs in its own child process so a native crash cannot take
+// the host down. The port and the random token travel over the process
+// environment (never argv, never a shared config file, never a log line), and the
+// parent learns the real port from a single ready line on stdout.
+export const ENTRY_ENV = Object.freeze({
+  modelDir: 'DSH_MEMU_EMBED_MODEL_DIR',
+  manifest: 'DSH_MEMU_EMBED_MANIFEST',
+  manifestFile: 'DSH_MEMU_EMBED_MANIFEST_FILE',
+  runtimeDir: 'DSH_MEMU_EMBED_RUNTIME_DIR',
+  token: 'DSH_MEMU_EMBED_TOKEN',
+  host: 'DSH_MEMU_EMBED_HOST',
+  port: 'DSH_MEMU_EMBED_PORT',
+  maxBodyBytes: 'DSH_MEMU_EMBED_MAX_BODY_BYTES',
+  maxBatch: 'DSH_MEMU_EMBED_MAX_BATCH',
+})
+
+function readManifest(env) {
+  const inline = String(env[ENTRY_ENV.manifest] || '').trim()
+  if (inline.startsWith('{')) {
+    try {
+      return JSON.parse(inline)
+    } catch (error) {
+      throw new LocalEmbeddingError('manifest env is not valid JSON', 'LOCAL_VECTOR_MANIFEST_INVALID', 503, String((error && error.message) || error))
+    }
+  }
+  const file = inline || String(env[ENTRY_ENV.manifestFile] || '').trim()
+  if (!file) throw new LocalEmbeddingError('a manifest path or inline manifest is required', 'LOCAL_VECTOR_MANIFEST_INVALID', 503)
+  let raw = ''
+  try {
+    raw = fs.readFileSync(path.resolve(file), 'utf8')
+  } catch (error) {
+    throw new LocalEmbeddingError('manifest file ' + path.basename(file) + ' could not be read', 'LOCAL_VECTOR_MANIFEST_INVALID', 503, String((error && error.code) || error))
+  }
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new LocalEmbeddingError('manifest file ' + path.basename(file) + ' is not valid JSON', 'LOCAL_VECTOR_MANIFEST_INVALID', 503, String((error && error.message) || error))
+  }
+}
+
+function readInteger(value, label, fallback) {
+  const text = String(value || '').trim()
+  if (!text) return fallback
+  const number = Number(text)
+  if (!Number.isInteger(number) || number < 0) {
+    throw new LocalEmbeddingError(label + ' must be a non-negative integer', 'LOCAL_VECTOR_BAD_CONFIG', 400)
+  }
+  return number
+}
+
+export function parseEmbeddingEntryConfig(env = process.env) {
+  const token = String(env[ENTRY_ENV.token] || '')
+  if (!token) throw new LocalEmbeddingError('a worker token is required', 'LOCAL_VECTOR_TOKEN_INVALID', 400)
+  const modelDir = String(env[ENTRY_ENV.modelDir] || '').trim()
+  if (!modelDir) throw new LocalEmbeddingError('modelDir is required', 'LOCAL_VECTOR_MODEL_DIR_MISSING', 503)
+  const runtimeDir = String(env[ENTRY_ENV.runtimeDir] || '').trim()
+  return {
+    modelDir,
+    manifest: readManifest(env),
+    runtimeDir: runtimeDir || undefined,
+    token,
+    host: String(env[ENTRY_ENV.host] || '127.0.0.1').trim() || '127.0.0.1',
+    port: readInteger(env[ENTRY_ENV.port], 'port', 0),
+    maxBodyBytes: readInteger(env[ENTRY_ENV.maxBodyBytes], 'maxBodyBytes', undefined),
+    maxBatch: readInteger(env[ENTRY_ENV.maxBatch], 'maxBatch', undefined),
+  }
+}
+
+/**
+ * Starts the worker and emits exactly one ready line. Kept separate from main()
+ * so a test can drive it with a stub worker and never listen on a socket.
+ */
+export async function runEmbeddingEntry({ env = process.env, stdout = process.stdout, logger = console, startWorker = startEmbeddingWorker } = {}) {
+  const config = parseEmbeddingEntryConfig(env)
+  const worker = await startWorker({ ...config, logger })
+  const ready = {
+    type: 'ready',
+    baseUrl: worker.baseUrl,
+    url: worker.url,
+    model: worker.model,
+    dimension: worker.dimension,
+    pid: process.pid,
+  }
+  stdout.write(JSON.stringify(ready) + '\n')
+  return { worker, ready }
+}
+
+function stderrLogger(stderr) {
+  const write = (level) => (message) => {
+    try { stderr.write('[local-embedding ' + level + '] ' + String(message) + '\n') } catch {}
+  }
+  return { info: write('info'), warn: write('warn'), error: write('error'), log: write('info') }
+}
+
+function isEntryPoint() {
+  const invoked = process.argv[1]
+  if (!invoked) return false
+  try {
+    return pathToFileURL(fs.realpathSync(invoked)).href === pathToFileURL(fs.realpathSync(new URL(import.meta.url))).href
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const stdout = process.stdout
+  const stderr = process.stderr
+  let worker = null
+  let stopping = false
+  const stop = async (code) => {
+    if (stopping) return
+    stopping = true
+    try { await worker?.close() } catch {}
+    process.exit(code)
+  }
+  const failAndExit = (error) => {
+    const code = String((error && error.code) || 'LOCAL_VECTOR_ERROR')
+    const message = String((error && error.message) || error || 'embedding worker failed')
+    try { stderr.write(JSON.stringify({ type: 'error', code, message }) + '\n') } catch {}
+    void stop(1)
+  }
+
+  // The parent owns the lifetime: stdin EOF, SIGTERM/SIGINT or an IPC disconnect
+  // all mean "release the native session now" (§14.5: no leaked processes).
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => { void stop(0) })
+  process.on('disconnect', () => { void stop(0) })
+  process.on('uncaughtException', failAndExit)
+  process.on('unhandledRejection', failAndExit)
+  try { process.stdin.on('end', () => { void stop(0) }); process.stdin.on('close', () => { void stop(0) }); process.stdin.resume() } catch {}
+
+  try {
+    const result = await runEmbeddingEntry({ stdout, logger: stderrLogger(stderr) })
+    worker = result.worker
+  } catch (error) {
+    failAndExit(error)
+  }
+}
+
+if (isEntryPoint()) main()

package/lib/local-embedding-manager.js

@@ -0,0 +1,249 @@
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { assertProfileVerified } from './vector-profile.js'
+import { manifestModelId } from './local-embedding-worker.js'
+
+const entry = fileURLToPath(new URL('./local-embedding-entry.js', import.meta.url))
+const failure = (code, message) => Object.assign(new Error(message), { code, fallback: 'lexical' })
+
+const LOOPBACK = '127.0.0.1'
+const EMBEDDINGS_PATH = '/v1/embeddings'
+const READY_LIMIT = 16_384
+const TOKEN_BYTES = 32
+const DEFAULT_WINDOW_MS = 60_000
+
+// The worker needs the OS basics and nothing else. An inherited proxy variable can
+// reroute the loopback call (§14.6: MEMU_HTTP_PROXY does exist), an inherited
+// *_API_KEY would hand a cloud credential to a process whose whole point is that it
+// never talks to anyone, and a stale DSH_MEMU_EMBED_* value would replace the fresh
+// per-process token or point the child at another model directory.
+const DENIED_ENV_NAMES = Object.freeze(['http_proxy', 'https_proxy', 'all_proxy', 'no_proxy', 'node_options'])
+const DENIED_ENV_PREFIXES = Object.freeze(['memu_', 'dsh_memu_embed_', 'openai_', 'azure_openai_', 'anthropic_', 'gemini_', 'google_', 'cohere_'])
+
+function childEnvironment(extra) {
+  const env = {}
+  for (const [name, value] of Object.entries(process.env)) {
+    if (typeof value !== 'string') continue
+    const lower = name.toLowerCase()
+    if (DENIED_ENV_NAMES.includes(lower) || lower.includes('proxy')) continue
+    if (DENIED_ENV_PREFIXES.some(prefix => lower.startsWith(prefix))) continue
+    env[name] = value
+  }
+  return { ...env, ...extra }
+}
+
+// One isolated native process per immutable profile. Tokens live only in memory and
+// in the child environment: never in argv, never in a log line, never in status().
+// A failed boot counts toward the fuse too; recall never triggers installation.
+export function createEmbeddingWorkerManager({ spawnImpl = spawn, executable = process.execPath, logger = console, now = Date.now, timeoutMs = 60_000, maxRestarts = 3, restartWindowMs = 60_000, verifyProfile = assertProfileVerified } = {}) {
+  const records = new Map()
+  const crashes = new Map()
+  const windowMs = Number.isFinite(restartWindowMs) && restartWindowMs > 0 ? restartWindowMs : DEFAULT_WINDOW_MS
+  const fuseLimit = Number.isInteger(maxRestarts) && maxRestarts > 0 ? maxRestarts : 0
+  let disposed = false
+
+  const warn = message => { try { logger?.warn?.(message) } catch {} }
+
+  // The fuse counts failed boots and unexpected exits only: a worker that served
+  // requests is not a restart storm. Timestamps older than the window are dropped so
+  // a crash loop stays bounded while a single later retry is not blocked forever.
+  const recentCrashes = key => {
+    const list = (crashes.get(key) || []).filter(at => now() - at < windowMs)
+    if (list.length) crashes.set(key, list)
+    else crashes.delete(key)
+    return list
+  }
+  const noteCrash = key => {
+    const list = recentCrashes(key)
+    list.push(now())
+    crashes.set(key, list)
+    return list.length
+  }
+
+  // stdin EOF is the worker's graceful "release the native session" signal; the kill
+  // only guarantees it for a child that is wedged. Both are best effort by design —
+  // stopping must never throw during disposal.
+  const stopChild = record => {
+    record.stopping = true
+    const child = record.child
+    if (!child) return
+    try { child.stdin?.end() } catch {}
+    try { child.kill() } catch {}
+  }
+
+  // Readiness is the only thing the parent believes about the child, so it is checked
+  // against the requested profile instead of trusted: right model id, right dimension,
+  // and a bare http loopback base URL with a real port. Anything else degrades to
+  // lexical recall rather than pointing MemU at an unexpected endpoint.
+  function checkReady(ready, expected) {
+    if (!ready || typeof ready !== 'object' || Array.isArray(ready)) return { error: 'worker readiness is not an object' }
+    if (ready.type !== 'ready') return { error: 'worker readiness is not a ready message' }
+    if (!expected.model) return { error: 'the requested profile has no stable model id' }
+    if (ready.model !== expected.model) return { error: 'worker readiness names a model other than the requested profile' }
+    if (!Number.isInteger(expected.dimension) || expected.dimension <= 0) return { error: 'the requested profile has no embedding dimension' }
+    if (ready.dimension !== expected.dimension) return { error: 'worker readiness reports a dimension other than the requested profile' }
+    let base = null
+    try { base = new URL(String(ready.baseUrl || '')) } catch { base = null }
+    if (!base) return { error: 'worker readiness carries no usable endpoint' }
+    if (base.protocol !== 'http:') return { error: 'worker endpoint must speak http on loopback' }
+    if (base.hostname !== LOOPBACK) return { error: 'worker endpoint must be ' + LOOPBACK }
+    const port = Number(base.port)
+    if (!Number.isInteger(port) || port < 1 || port > 65535) return { error: 'worker endpoint must carry a real port' }
+    if (base.username || base.password || base.search || base.hash) return { error: 'worker endpoint must be a bare loopback base URL' }
+    if (base.pathname !== '/v1') return { error: 'worker endpoint path must be /v1' }
+    if (ready.url !== undefined && ready.url !== null && String(ready.url) !== new URL(EMBEDDINGS_PATH, base).href) {
+      return { error: 'worker embeddings URL does not belong to its base URL' }
+    }
+    return { endpoint: Object.freeze({ baseUrl: base.href, model: expected.model, dimension: expected.dimension }) }
+  }
+
+  function boot(profile, key, modelDir, runtimeDir) {
+    const token = crypto.randomBytes(TOKEN_BYTES).toString('hex')
+    const expected = { model: manifestModelId(profile.manifest), dimension: Number(profile.dimension) }
+    const record = { key, child: null, stopping: false, settled: false, endpoint: null, reject: null }
+    // Registered before the spawn so a concurrent acquire joins this boot instead of
+    // starting a second child for the same profile.
+    records.set(key, record)
+    record.ready = new Promise((resolve, reject) => {
+      let buffer = ''
+      let timer = null
+      const clearTimer = () => { if (timer) { clearTimeout(timer); timer = null } }
+      const forget = () => { if (records.get(key) === record) records.delete(key) }
+      const abort = (code, message) => {
+        if (record.settled) return
+        record.settled = true
+        clearTimer()
+        forget()
+        reject(failure(code, message))
+      }
+      // close() rejects an in-flight acquire through this hook, so a caller waiting on
+      // a child that never reports ready fails immediately instead of hanging.
+      record.reject = abort
+      const fail = (code, message) => {
+        noteCrash(key)
+        abort(code, message)
+        stopChild(record)
+      }
+      timer = setTimeout(() => fail('LOCAL_VECTOR_START_TIMEOUT', 'the local embedding worker did not become ready in time'), timeoutMs)
+      timer.unref?.()
+      let child = null
+      try {
+        child = spawnImpl(executable, [entry], {
+          windowsHide: true,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: childEnvironment({
+            ELECTRON_RUN_AS_NODE: '1',
+            DSH_MEMU_EMBED_MODEL_DIR: modelDir,
+            DSH_MEMU_EMBED_RUNTIME_DIR: runtimeDir,
+            DSH_MEMU_EMBED_MANIFEST: JSON.stringify({ ...profile.manifest, verified: true }),
+            DSH_MEMU_EMBED_TOKEN: token,
+            DSH_MEMU_EMBED_HOST: LOOPBACK,
+            DSH_MEMU_EMBED_PORT: '0',
+            MEMU_TELEMETRY: '0',
+            DO_NOT_TRACK: '1',
+            MEMU_EVENTS_BASE_URL: '',
+          }),
+        })
+      } catch {
+        fail('LOCAL_VECTOR_SPAWN_FAILED', 'the local embedding worker could not be started')
+        return
+      }
+      record.child = child
+      // A worker that died turns the next stdin write into EPIPE. An unhandled 'error'
+      // event on a child pipe is an uncaught exception in the host process, so every
+      // pipe gets a sink: semantic recall degrades, the host does not go down with it.
+      for (const pipe of [child?.stdin, child?.stdout, child?.stderr]) {
+        try { pipe?.on?.('error', () => {}) } catch {}
+      }
+      child?.on?.('error', () => {
+        if (record.settled) { warn('the local embedding worker reported an error; semantic recall will degrade to lexical'); return }
+        fail('LOCAL_VECTOR_SPAWN_FAILED', 'the local embedding worker could not be started')
+      })
+      child?.on?.('close', () => {
+        forget()
+        record.endpoint = null
+        // A shutdown this manager asked for is not a crash and must stay quiet.
+        if (record.stopping) return
+        noteCrash(key)
+        warn('the local embedding worker exited; semantic recall will degrade to lexical')
+        abort('LOCAL_VECTOR_WORKER_EXITED', 'the local embedding worker exited before it became ready')
+      })
+      // Native stderr may quote request text, so it is read and discarded.
+      child?.stderr?.on?.('data', () => {})
+      child?.stdout?.on?.('data', chunk => {
+        if (record.settled) return
+        buffer += String(chunk)
+        if (buffer.length > READY_LIMIT) { fail('LOCAL_VECTOR_BAD_READY', 'the worker readiness message exceeded the limit'); return }
+        const newline = buffer.indexOf(String.fromCharCode(10))
+        if (newline < 0) return
+        const line = buffer.slice(0, newline).replace(/\r+$/, '')
+        buffer = ''
+        let ready = null
+        try { ready = JSON.parse(line) } catch { fail('LOCAL_VECTOR_BAD_READY', 'the worker returned an unreadable readiness line'); return }
+        const checked = checkReady(ready, expected)
+        if (checked.error) { fail('LOCAL_VECTOR_BAD_READY', checked.error); return }
+        record.settled = true
+        clearTimer()
+        record.endpoint = Object.freeze({ ...checked.endpoint, token })
+        resolve(record.endpoint)
+      })
+    })
+    return record
+  }
+
+  async function acquire(profile) {
+    if (disposed) throw failure('LOCAL_VECTOR_MANAGER_CLOSED', 'the embedding worker manager is closed')
+    verifyProfile(profile)
+    const modelDir = typeof profile?.modelDir === 'string' ? profile.modelDir.trim() : ''
+    const runtimeDir = typeof profile?.runtimeDir === 'string' ? profile.runtimeDir.trim() : ''
+    if (!modelDir || !runtimeDir) throw failure('LOCAL_VECTOR_RUNTIME_UNAVAILABLE', 'install the verified model and runtime before enabling local embeddings')
+    if (!manifestModelId(profile.manifest)) throw failure('LOCAL_VECTOR_MANIFEST_INCOMPLETE', 'the vector profile has no stable model id')
+    const dimension = Number(profile.dimension)
+    if (!Number.isInteger(dimension) || dimension <= 0) throw failure('LOCAL_VECTOR_MANIFEST_INCOMPLETE', 'the vector profile has no embedding dimension')
+    const key = JSON.stringify([String(profile.fingerprint || ''), modelDir, runtimeDir])
+    const existing = records.get(key)
+    if (existing) return existing.ready
+    if (fuseLimit && recentCrashes(key).length >= fuseLimit) throw failure('LOCAL_VECTOR_RESTART_FUSED', 'the local embedding worker keeps failing; retry after the cooldown')
+    return boot(profile, key, modelDir, runtimeDir).ready
+  }
+
+  function close() {
+    disposed = true
+    const pending = [...records.values()]
+    records.clear()
+    crashes.clear()
+    for (const record of pending) {
+      // Reject first: a caller blocked in acquire() must fail on the shutdown it was
+      // told about, not on the "worker exited" symptom of our own kill.
+      record.reject?.('LOCAL_VECTOR_MANAGER_CLOSED', 'the embedding worker manager is closed')
+      stopChild(record)
+    }
+    return pending.length
+  }
+
+  // Deliberately shallow: no token, no endpoint, no model directory, no fingerprint.
+  function status() {
+    let running = 0
+    let booting = 0
+    for (const record of records.values()) {
+      if (record.settled) running += 1
+      else booting += 1
+    }
+    let tripped = 0
+    if (fuseLimit) for (const key of [...crashes.keys()]) if (recentCrashes(key).length >= fuseLimit) tripped += 1
+    return { running, booting, closed: disposed, tripped }
+  }
+
+  return { acquire, close, status }
+}
+
+let singleton
+export function embeddingWorkerManager() {
+  return singleton ||= createEmbeddingWorkerManager()
+}
+export function closeEmbeddingWorkers() {
+  const manager = singleton
+  singleton = null
+  try { manager?.close() } catch {}
+}

package/lib/local-embedding-protocol.js

@@ -0,0 +1,173 @@
+// §14 local vector: the wire contract shared by the managed embedding worker,
+// its child-process entry and their tests. MemU's OpenAI-compatible SDK posts
+// {model, input, encoding_format} and expects object=list with data ordered like
+// the input plus a usage block; float arrays and base64 float32 little-endian
+// payloads are both real client shapes (probe in §14.3 saw base64), so both are
+// implemented here and nothing else invents a private array protocol.
+//
+// All request/response validation lives in this file on purpose: the worker only
+// moves bytes, so a test can pin the contract without opening a socket.
+
+export const EMBEDDINGS_PATH = '/v1/embeddings'
+export const HEALTH_PATH = '/health'
+
+// MemU commits in batches of 64 by default; the body cap still leaves room for
+// 64 long strings while refusing a whole document in one shot.
+export const DEFAULT_MAX_BODY_BYTES = 1_048_576
+export const DEFAULT_MAX_BATCH = 64
+export const MAX_VECTOR_DIMENSION = 8192
+export const MAX_INPUT_CHARS = 65_536
+export const ENCODINGS = Object.freeze(['float', 'base64'])
+
+export class LocalEmbeddingError extends Error {
+  constructor(message, code = 'LOCAL_VECTOR_ERROR', status = 500, detail = null) {
+    super(message)
+    this.name = 'LocalEmbeddingError'
+    this.code = code
+    this.status = status
+    if (detail !== null && detail !== undefined) this.detail = detail
+  }
+}
+
+export function errorStatus(error) {
+  const status = Number(error && error.status)
+  return Number.isInteger(status) && status >= 400 && status <= 599 ? status : 500
+}
+
+// Mirrors the OpenAI error envelope the SDKs already understand, without echoing
+// the request body (an error response must never replay a secret or raw text).
+export function errorBody(error) {
+  const status = errorStatus(error)
+  return {
+    error: {
+      message: String((error && error.message) || 'local embedding request failed'),
+      type: status >= 500 ? 'server_error' : 'invalid_request_error',
+      code: String((error && error.code) || 'LOCAL_VECTOR_ERROR'),
+    },
+  }
+}
+
+function badRequest(message, code) {
+  return new LocalEmbeddingError(message, code, 400)
+}
+
+function plainNumbers(value) {
+  if (Array.isArray(value)) return value
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) return Array.from(value)
+  return null
+}
+
+export function encodeVectorBase64(vector) {
+  const numbers = plainNumbers(vector)
+  if (!numbers) throw new LocalEmbeddingError('cannot encode a non-numeric vector', 'LOCAL_VECTOR_INVALID_VECTOR', 500)
+  const buffer = Buffer.allocUnsafe(numbers.length * 4)
+  for (let index = 0; index < numbers.length; index++) buffer.writeFloatLE(Number(numbers[index]), index * 4)
+  return buffer.toString('base64')
+}
+
+export function decodeVectorBase64(text, dimension = 0) {
+  const buffer = Buffer.from(String(text || ''), 'base64')
+  if (buffer.length === 0 || buffer.length % 4 !== 0) {
+    throw new LocalEmbeddingError('base64 payload is not a whole float32 array', 'LOCAL_VECTOR_INVALID_VECTOR', 500)
+  }
+  const out = new Array(buffer.length / 4)
+  for (let index = 0; index < out.length; index++) out[index] = buffer.readFloatLE(index * 4)
+  if (Number.isInteger(dimension) && dimension > 0 && out.length !== dimension) {
+    throw new LocalEmbeddingError('base64 payload decoded to ' + out.length + ' values, expected ' + dimension, 'LOCAL_VECTOR_DIMENSION_MISMATCH', 500)
+  }
+  return out
+}
+
+// One vector from the model, checked the way §14.6 demands: finite values,
+// exactly the manifest dimension, and not the all-zero vector a broken session
+// returns when its inputs never reach the graph.
+export function assertVector(vector, dimension, index = 0) {
+  const label = index >= 0 ? 'embedding ' + index : 'embedding'
+  const numbers = plainNumbers(vector)
+  if (!numbers) throw new LocalEmbeddingError(label + ' is not a numeric array', 'LOCAL_VECTOR_INVALID_VECTOR', 500)
+  if (!Number.isInteger(dimension) || dimension <= 0) {
+    throw new LocalEmbeddingError('the manifest declares no usable embedding dimension', 'LOCAL_VECTOR_MANIFEST_INCOMPLETE', 503)
+  }
+  if (numbers.length !== dimension) {
+    throw new LocalEmbeddingError(label + ' has ' + numbers.length + ' values, expected ' + dimension, 'LOCAL_VECTOR_DIMENSION_MISMATCH', 500)
+  }
+  let squared = 0
+  for (let position = 0; position < numbers.length; position++) {
+    const value = numbers[position]
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new LocalEmbeddingError(label + ' contains a non-finite value at ' + position, 'LOCAL_VECTOR_INVALID_VECTOR', 500)
+    }
+    squared += value * value
+  }
+  if (!(squared > 0)) throw new LocalEmbeddingError(label + ' is all zeros', 'LOCAL_VECTOR_ZERO_VECTOR', 500)
+  return numbers
+}
+
+function normalizeInputText(value, index, maxChars) {
+  if (typeof value !== 'string') {
+    throw badRequest('input[' + index + '] must be a string; token-id arrays are not accepted', 'LOCAL_VECTOR_BAD_REQUEST')
+  }
+  if (!value.trim()) throw badRequest('input[' + index + '] is empty', 'LOCAL_VECTOR_BAD_REQUEST')
+  if (value.length > maxChars) {
+    throw badRequest('input[' + index + '] is longer than ' + maxChars + ' characters', 'LOCAL_VECTOR_INPUT_TOO_LONG')
+  }
+  return value
+}
+
+// Accepts exactly what the SDK sends: one string or an array of strings. Anything
+// else (token ids, nested arrays, non-string items) is a client bug, not something
+// to coerce, because a silent coercion would embed the wrong text.
+export function parseEmbeddingRequest(body, { model, maxBatch = DEFAULT_MAX_BATCH, maxChars = MAX_INPUT_CHARS } = {}) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw badRequest('request body must be a JSON object', 'LOCAL_VECTOR_BAD_REQUEST')
+  }
+  const expected = String(model || '')
+  const requested = body.model
+  if (typeof requested !== 'string' || !requested.trim()) {
+    throw badRequest('model is required', 'LOCAL_VECTOR_BAD_REQUEST')
+  }
+  if (!expected || requested !== expected) {
+    throw badRequest('unknown model; this worker serves ' + (expected || '(none)'), 'LOCAL_VECTOR_MODEL_MISMATCH')
+  }
+  const encoding = body.encoding_format === undefined || body.encoding_format === null ? 'float' : body.encoding_format
+  if (typeof encoding !== 'string' || !ENCODINGS.includes(encoding)) {
+    throw badRequest('encoding_format must be one of ' + ENCODINGS.join(', '), 'LOCAL_VECTOR_BAD_ENCODING')
+  }
+  const raw = body.input
+  const list = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : null
+  if (!list) throw badRequest('input must be a string or an array of strings', 'LOCAL_VECTOR_BAD_REQUEST')
+  if (list.length === 0) throw badRequest('input must not be empty', 'LOCAL_VECTOR_BAD_REQUEST')
+  const batchLimit = Number.isInteger(maxBatch) && maxBatch > 0 ? maxBatch : DEFAULT_MAX_BATCH
+  if (list.length > batchLimit) {
+    throw badRequest('batch of ' + list.length + ' exceeds the limit of ' + batchLimit, 'LOCAL_VECTOR_BATCH_TOO_LARGE')
+  }
+  const inputs = list.map((value, index) => normalizeInputText(value, index, maxChars))
+  return { inputs, encoding }
+}
+
+// Token counts are only used for the usage block; the worker never claims a real
+// tokenizer count when the adapter cannot supply one.
+export function estimateUsage(inputs) {
+  let count = 0
+  for (const input of inputs) count += Math.max(1, Math.ceil(String(input).length / 4))
+  return { prompt_tokens: count, total_tokens: count }
+}
+
+export function buildEmbeddingResponse({ model, vectors, encoding = 'float', usage = null }) {
+  const list = Array.isArray(vectors) ? vectors : []
+  const data = list.map((vector, index) => ({
+    object: 'embedding',
+    index,
+    embedding: encoding === 'base64' ? encodeVectorBase64(vector) : Array.from(vector, Number),
+  }))
+  const tokens = usage && typeof usage === 'object' ? usage : estimateUsage(new Array(list.length).fill(''))
+  return {
+    object: 'list',
+    data,
+    model,
+    usage: {
+      prompt_tokens: Number.isFinite(tokens.prompt_tokens) ? tokens.prompt_tokens : 0,
+      total_tokens: Number.isFinite(tokens.total_tokens) ? tokens.total_tokens : 0,
+    },
+  }
+}