dsh-memu-memory 1.1.2 → 1.1.3

package/lib/engine.js

@@ -5,7 +5,7 @@ import path from 'node:path'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import {
-  dataDir, engineDir, downloadsDir, logsDir, librariesDir, ensureDir, readJson, writeJson, stamp,
+  dataDir, engineDir, downloadsDir, logsDir, librariesDir, ensureDir, readJson, writeJson, stamp, windowsSystemEnv,
 } from './paths.js'
 import { getSettings, globalDbPath } from './state.js'
 import { ensureManagedPython } from './managed-runtime.js'
@@ -158,7 +158,7 @@ function run(cmd, args, opts = {}) {
   return new Promise((resolve) => {
     const child = spawn(cmd, args, {
       cwd: opts.cwd,
-      env: { ...process.env, ...(opts.env || {}) },
+      env: { ...windowsSystemEnv(), ...process.env, ...(opts.env || {}) },
       windowsHide: true,
       stdio: ['ignore', 'pipe', 'pipe'],
     })

package/lib/index.js

@@ -6,6 +6,9 @@ import { registerCycle } from './cycle.js'
 import { syncPromptDefaults } from './prompts.js'
 import { ensureEngine, engineStatus, ENGINE_VERSION } from './engine.js'
 import { getSettings, getMemoryBackend, backupDatabases, flushState } from './state.js'
+import { closeEmbeddingWorkers } from './local-embedding-manager.js'
+import { bootstrapLocalVector } from './local-vector-service.js'
+import { vectorStatus } from './vector-profile.js'
 import { setWarnSink } from './paths.js'
 
 export const name = 'dsh-memu-memory'
@@ -15,6 +18,29 @@ export const inject = ['tools', 'timer']
 
 const applied = new WeakSet()
 
+// 首用引导（§14.13）：本地向量模式且已有（或待切换）受管模型时，启动后把受管运行时复用起来、
+// 拉起 loopback worker 并健康检查 /v1/embeddings。这里不下载：没有确认的联网动作留给她在
+// 设置页点按钮，启动路径只做 reuse + 健康检查。失败只 warn（召回照旧退词法）。
+function startLocalVectorBootstrap(ctx) {
+  try {
+    if (getMemoryBackend() !== 'api') return
+    if (getSettings().vectorSource !== 'local') return
+    const state = vectorStatus()
+    const catalogId = state?.active?.profile?.catalogId || state?.requested?.catalogId || null
+    if (!catalogId) return
+    const timer = setTimeout(() => {
+      void bootstrapLocalVector({ confirmed: false }).then((ready) => {
+        try { ctx.logger?.info?.(`dsh-memu-memory: managed local embedding runtime ready (${String(ready?.model || catalogId)} ${Number(ready?.dimension) || '?'}d)`) } catch {}
+      }).catch((error) => {
+        try { ctx.logger?.warn?.(`dsh-memu-memory: local embedding bootstrap skipped: ${error?.message || error}`) } catch {}
+      })
+    }, 2500)
+    timer.unref?.()
+  } catch (error) {
+    try { ctx.logger?.warn?.(`dsh-memu-memory: local embedding bootstrap skipped: ${error?.message || error}`) } catch {}
+  }
+}
+
 function startEngineBootstrap(ctx) {
   try {
     const settings = getSettings()
@@ -94,6 +120,16 @@ export function apply(ctx, config) {
   if (!inPreset) {
     registerRpc(ctx)
     startEngineBootstrap(ctx)
+    startLocalVectorBootstrap(ctx)
+  }
+
+  // The embedding worker is a process-global singleton, so it outlives any single
+  // acquire() and would keep a native session and a loopback port alive after this
+  // instance is unloaded. Preset mounts share that same worker, so only the instance
+  // that owns the process-global surfaces may close it. Recall degrades to lexical
+  // afterwards instead of failing.
+  if (!inPreset && typeof ctx.effect === 'function') {
+    ctx.effect(() => () => { closeEmbeddingWorkers() }, 'dsh-memu-memory: embedding workers')
   }
 
   const disposeCycle = inPreset ? null : registerCycle(ctx, {

package/lib/inject.js

@@ -9,9 +9,10 @@ import {
 import {
   decayStrength, privateRecall, globalRecall, appliesToDomain, domainOf,
   relativeTime, daysSince, dueOpenLoops, noteInjected, noteGlobalInjected, visibleToSession,
-  cueCandidates, isTipOfTongue, isMemoryEligible,
+  cueCandidates, isTipOfTongue, isMemoryEligible, sessionIdOf,
   salientDateFires, isDatedSalientDate, salientDaysAhead,
 } from './memory.js'
+import { record, clipQuery } from './activity-log.js'
 import { readMood } from './mood.js'
 import { loadPromptForDomain } from './prompts.js'
 import { estTokens, packToBudget, truncateToTokens } from './budget.js'
@@ -605,6 +606,31 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
   const pieces = []
   const errors = []
   let candidateCount = 0
+  let privateRoute = null
+  let globalRoute = null
+  // 每个回合都留一条召回记录：走了哪条路、召回/注入的是什么 id、哪些腿降级了。
+  // 这是"为什么这台机器上的召回从来不出来"唯一能在 UI 里自查的证据。
+  const finish = (payload) => {
+    record({
+      kind: 'recall',
+      scope: null,
+      sessionId: sessionId || sessionIdOf(exec) || null,
+      libraryId: binding.libraryId || null,
+      ok: (payload.errors || []).length === 0,
+      message: `召回 ${payload.ids.length} 条注入 / ${candidateCount} 候选` + ((payload.errors || []).length ? ` · ${payload.errors.length} 个错误` : ''),
+      detail: {
+        query: clipQuery(query),
+        turn,
+        privateRoute,
+        globalRoute,
+        ids: payload.ids,
+        candidateCount,
+        errors: payload.errors || [],
+      },
+      refs: payload.ids,
+    })
+    return payload
+  }
 
   // Compare against the history first, then record this message into it.
   const switched = topicShifted(binding, query, settings)
@@ -618,7 +644,12 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
       // The turn's settings snapshot decides the cutoff, so a caller that runs with
       // different settings (tests, per-turn overrides) sees matching behaviour.
       const result = await privateRecall({ exec, query, topK: settings.privateTopK, relevanceThreshold: settings.relevanceThreshold, purpose: 'automatic' })
+      // A degraded hybrid recall is not a failed turn: the lexical leg still
+      // answered. The error must still reach lastRecallError so the next healthy
+      // recall clears it instead of the degradation disappearing.
+      for (const warning of result.errors || []) errors.push(warning)
       candidateCount += result.files?.length || 0
+      privateRoute = result.recallRoute || null
       const fresh = (result.files || [])
         .filter((f) => !seenRecently(binding, f.name, turn, settings.dedupeTurns))
       if (fresh.length > 0) {
@@ -645,6 +676,7 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
     try {
       const result = await globalRecall({ exec, query, topK: settings.globalTopK, relevanceThreshold: settings.relevanceThreshold })
       candidateCount += result.files?.length || 0
+      globalRoute = result.recallRoute || null
       if (result.unbound) errors.push('global recall ran without a session binding; results are limited to the general domain')
       const fresh = (result.files || [])
         .filter((f) => !seenRecently(binding, f.name, turn, settings.dedupeTurns))
@@ -656,7 +688,7 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
     }
   }
 
-  if (pieces.length === 0) return { text: '', ids: [], errors, outcome: errors.length ? 'error' : candidateCount ? 'deduped' : 'no-match', candidateCount }
+  if (pieces.length === 0) return finish({ text: '', ids: [], errors, outcome: errors.length ? 'error' : candidateCount ? 'deduped' : 'no-match', candidateCount })
   const budget = Math.max(0, Number(settings.turnTokens ?? 640))
   const blocks = []
   for (const piece of pieces) {
@@ -681,7 +713,7 @@ export async function buildRecall(binding, query, turn, settings = getSettings()
   }
   const text = blocks.join('\n\n')
   if (!text) errors.push('recall omitted: token budget cannot fit a memory entry')
-  return { text, ids, errors, outcome: text ? 'injected' : 'budget', candidateCount }
+  return finish({ text, ids, errors, outcome: text ? 'injected' : 'budget', candidateCount })
 }
 
 export function createMemoryMessage(text) {
@@ -691,6 +723,46 @@ export function createMemoryMessage(text) {
   })
 }
 
+// Every part of the first-step message is built from one binding snapshot, but
+// retrieval awaits an external engine. During that window the conversation can be
+// switched to another library, moved to another channel/character, or have a layer
+// turned off. A snapshot that no longer matches must be discarded whole: catching
+// the recall error alone would still ship the pre-switch anchor and other parts.
+function injectionSnapshot(binding) {
+  return {
+    libraryId: binding?.libraryId || null,
+    scopeKey: binding?.scopeKey || null,
+    memoryContext: JSON.stringify(binding?.memoryContext || {}),
+    useLibrary: binding?.useLibrary !== false,
+    useGlobal: binding?.useGlobal !== false,
+  }
+}
+
+function injectionSnapshotIsCurrent(sessionId, snapshot, autoInject) {
+  const current = getSessionBinding(sessionId)
+  if (!current) return false
+  if ((current.libraryId || null) !== snapshot.libraryId) return false
+  if ((current.scopeKey || null) !== snapshot.scopeKey) return false
+  if (JSON.stringify(current.memoryContext || {}) !== snapshot.memoryContext) return false
+  if (getSettings().autoInject !== autoInject) return false
+  const scope = effectiveScope(current)
+  return scope.enabled
+    && scope.useLibrary === snapshot.useLibrary
+    && scope.useGlobal === snapshot.useGlobal
+}
+
+// Both the ordinary first-step injection and the guide message must pass the same
+// admission. A guide that ignores the switches tells a disabled conversation to use
+// memory tools it is not supposed to use, and consumes the once-only flag while doing
+// it — so re-enabling later would never deliver the rules.
+function admissionFor(binding) {
+  const settings = getSettings()
+  if (settings.autoInject === 'off') return null
+  const scope = effectiveScope(binding)
+  if (!scope.enabled) return null
+  return { settings, scope }
+}
+
 /**
  * Deliver the memory rules as a message when the system prompt cannot hold them.
  *
@@ -708,6 +780,7 @@ function withGuideMessage(ctx, payload, decision) {
     if (typeof payload?.step === 'number' && payload.step !== 1) return decision
     const binding = getSessionBinding(sessionId)
     if (!binding || binding.guideMessageAt) return decision
+    if (!admissionFor(binding)) return decision
     if (!decision || !Array.isArray(decision.messages)) return decision
     const rules = sectionText(ctx, 'system-guide', payload)
     const text = [
@@ -758,33 +831,38 @@ async function injectInboundForStep({ agent, decision, turn, signal, log, ctx })
   const imageCount = images.length
   setSessionBinding(sessionId, { lastImageCount: imageCount })
   const anchorNeeded = effective.reinjectPending || !(effective.injectedIds || []).includes(ANCHOR_SENTINEL)
-  const budget = Math.max(0, Number(settings.turnTokens ?? 640))
+  // turnTokens remains the recall block's own ceiling, but injectionTotalTokens is
+  // the ceiling for the whole plugin message. The two must be applied together:
+  // otherwise a 160-token total with an 800-token recall budget injects ~786.
+  const turnBudget = Math.max(0, Number(settings.turnTokens ?? 640))
+  const totalBudget = Math.max(0, Number(settings.injectionTotalTokens ?? 2000))
+  const totalRoom = () => Math.max(0, totalBudget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0))
   const appendBounded = (text, candidateIds = []) => {
     if (!text) return
-    const room = budget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0)
-    if (room <= 0) return
-    if (estTokens(text) > room) return
+    if (estTokens(text) > totalRoom()) return
     const clipped = text
     parts.push(clipped)
     ids.push(...candidateIds.filter(id => clipped.includes(`[${id}]`)))
   }
-  if (anchorNeeded && budget >= 160) {
-    const anchor = buildAnchor(effective, { ...settings, anchorTokens: Math.min(Number(settings.anchorTokens || 700), Math.floor(budget / 2)) }, sessionId)
+  if (anchorNeeded && totalRoom() >= 160) {
+    const anchor = buildAnchor(effective, { ...settings, anchorTokens: Math.min(Number(settings.anchorTokens || 700), Math.floor(turnBudget / 2), totalRoom()) }, sessionId)
     appendBounded(anchor.text, anchor.ids)
   }
   if (media.length) {
     const lines = media.map(item => `${item.sha256} · ${item.captionBy}: ${clip(item.caption || '[图片]', 35)}${item.missing ? ' · missing' : ''}`).join('\n')
-    const text = ['<memory-media>', truncateToTokens(lines, Math.min(140, Math.floor(budget / 3))), '图片引用不是视觉证据；attachments 只接受 sha256。', '</memory-media>'].join('\n')
-    if (estTokens(text) + estTokens(parts.join('\n\n')) + 2 <= budget) parts.push(text)
+    const text = ['<memory-media>', truncateToTokens(lines, Math.min(140, Math.floor(totalRoom() / 3))), '图片引用不是视觉证据；attachments 只接受 sha256。', '</memory-media>'].join('\n')
+    appendBounded(text)
   }
   let outcome = 'anchor-only'
   let errors = []
   if (settings.autoInject !== 'anchor-only' && (imageCount || query.length >= Number(settings.minUserChars ?? 6))) {
-    const remaining = Math.max(0, budget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0))
-    const recall = await buildRecall(effective, query, clock, { ...settings, turnTokens: remaining }, { agent }, sessionId)
-    if (recall.text) { parts.push(recall.text); ids.push(...recall.ids) }
-    errors = recall.errors
-    outcome = recall.outcome || 'no-match'
+    const recallBudget = Math.max(0, Math.min(turnBudget, totalRoom()))
+    if (recallBudget > 0) {
+      const recall = await buildRecall(effective, query, clock, { ...settings, turnTokens: recallBudget }, { agent }, sessionId)
+      appendBounded(recall.text, recall.ids)
+      errors = recall.errors
+      outcome = recall.outcome || 'no-match'
+    }
   }
   if (signal?.aborted) return decision
   const current = getSessionBinding(sessionId)
@@ -798,6 +876,13 @@ async function injectInboundForStep({ agent, decision, turn, signal, log, ctx })
     return decision
   } else setRecallError(sessionId, null)
   const text = parts.join('\n\n')
+  // Final assertion: every block above is individually bounded, so exceeding the
+  // whole-message ceiling here means the accounting drifted. Drop the batch rather
+  // than publish an over-budget message.
+  if (estTokens(text) > totalBudget) {
+    setRecallError(sessionId, 'inbound injection exceeded injectionTotalTokens')
+    return decision
+  }
   if (text) {
     const pushed = [...new Set(ids)]
     markInjected(sessionId, pushed, clock)
@@ -854,13 +939,14 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
   // Advance the idle clock even when injection is off, so sleep consolidation
   // still knows when this conversation last did anything.
   touchSession(sessionId)
-  const settings = getSettings()
-  if (settings.autoInject === 'off') return decision
   // The folder policy is the ceiling: a conversation cannot opt into a memory
-  // layer its folder has switched off.
-  const scope = effectiveScope(binding)
-  if (!scope.enabled) return decision
+  // layer its folder has switched off. The guide message shares this admission.
+  const admitted = admissionFor(binding)
+  if (!admitted) return decision
+  const { settings, scope } = admitted
   const effective = { ...binding, useLibrary: scope.useLibrary, useGlobal: scope.useGlobal }
+  // Captured before any await below; re-checked immediately before the splice.
+  const snapshot = injectionSnapshot(effective)
 
   const query = contextualQuery(decision.messages, lastUser)
   const imageCount = imageTurn(lastUser).imageCount
@@ -874,18 +960,27 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
 
   const parts = []
   const ids = []
+  // The sub-budgets (anchorTokens, turnTokens, the hint's own cap) are ceilings for
+  // their own blocks; injectionTotalTokens is the ceiling for the whole plugin
+  // message. Without this outer gate the sub-budgets can add up past the configured
+  // total even when each one individually looks fine.
+  const injectionBudget = Math.max(0, Number(settings.injectionTotalTokens ?? 2000))
+  const totalRoom = () => Math.max(0, injectionBudget - estTokens(parts.join('\n\n')) - (parts.length ? 2 : 0))
   if (imageCount && effective.useLibrary) {
     const current = getSessionBinding(sessionId)
     const pending = (current?.pendingMedia || []).slice(-8)
     if (pending.length) {
       const details = pending.map(item => `${item.sha256} · ${item.captionBy}: ${clip(item.caption || '[图片]', 35)}${item.missing ? ' · missing' : ''}`).join('\n')
-      parts.push(['<memory-media>', truncateToTokens(details, 150), current.stickerHint ? '同图反复出现，可以用 track=habit 聚合表达习惯，不必逐次写记忆。' : '', '只知道描述与引用，不能凭空声称看过像素。attachments 只接受 sha256。', '</memory-media>'].filter(Boolean).join('\n'))
+      const mediaText = ['<memory-media>', truncateToTokens(details, 150), current.stickerHint ? '同图反复出现，可以用 track=habit 聚合表达习惯，不必逐次写记忆。' : '', '只知道描述与引用，不能凭空声称看过像素。attachments 只接受 sha256。', '</memory-media>'].filter(Boolean).join('\n')
+      if (estTokens(mediaText) <= totalRoom()) parts.push(mediaText)
     }
   }
 
   if (anchorNeeded) {
-    const anchor = buildAnchor(effective, settings, sessionId)
-    if (anchor.text) {
+    const anchor = totalRoom() >= 160
+      ? buildAnchor(effective, { ...settings, anchorTokens: Math.min(Number(settings.anchorTokens || 800), totalRoom()) }, sessionId)
+      : { text: '', ids: [] }
+    if (anchor.text && estTokens(anchor.text) <= totalRoom()) {
       parts.push(anchor.text)
       ids.push(ANCHOR_SENTINEL, ...anchor.ids)
     }
@@ -893,7 +988,7 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     // the only moment the pre-compaction memories are missing from the window.
     if (reinject) {
       const replay = buildReplay(effective, settings, sessionId)
-      if (replay.text) {
+      if (replay.text && estTokens(replay.text) <= totalRoom()) {
         parts.push(replay.text)
         ids.push(...replay.ids)
       }
@@ -902,7 +997,7 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
 
   if (!reinject) {
     const anniversary = buildAnniversary(sessionId, effective)
-    if (anniversary.text) {
+    if (anniversary.text && estTokens(anniversary.text) <= totalRoom()) {
       parts.push(anniversary.text)
       ids.push(...anniversary.ids)
       for (const id of anniversary.fired) markAnniversaryShown(sessionId, id, anniversary.dayKey)
@@ -913,7 +1008,7 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     // Independent of retrieval: a loop can be worth raising in a conversation that
     // shares no vocabulary with it, which is exactly the case lexical recall misses.
     const nudge = buildOpenLoopNudge(effective, settings, sessionId)
-    if (nudge.text) {
+    if (nudge.text && estTokens(nudge.text) <= totalRoom()) {
       parts.push(nudge.text)
       ids.push(...nudge.ids)
     }
@@ -923,7 +1018,8 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     // The recall path takes the host's exec shape, where the session lives under
     // `.agent`; passing the Agent itself made sessionIdOf return null and turned
     // every per-turn recall into a silent no-op (P0-1).
-    const recall = await buildRecall(effective, query, memoryClock, settings, { agent }, sessionId)
+    const recallBudget = Math.max(0, Math.min(Number(settings.turnTokens ?? 800), totalRoom()))
+    const recall = await buildRecall(effective, query, memoryClock, { ...settings, turnTokens: recallBudget }, { agent }, sessionId)
     setSessionBinding(sessionId, { lastRecallOutcome: { reason: recall.outcome || 'no-match', candidateCount: recall.candidateCount || 0, injectedCount: recall.ids.length, at: new Date().toISOString() } })
     if (recall.text) {
       parts.push(recall.text)
@@ -939,14 +1035,14 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
 
   if (!reinject) {
     const cue = await maybeCue({ sessionId, turn, settings, binding: effective, exec: { agent } })
-    if (cue) {
+    if (cue && estTokens(cue.text) <= totalRoom()) {
       parts.push(cue.text)
       // The related pointers reached the window, so they count towards habituation and
       // dedupe exactly like the recall block's ids.
       ids.push(...cue.ids)
     }
     const texture = maybeTexture(sessionId, settings)
-    if (texture) parts.push(texture)
+    if (texture && estTokens(texture) <= totalRoom()) parts.push(texture)
   }
 
   if (parts.length === 0) {
@@ -954,6 +1050,11 @@ export async function injectForStep({ agent, decision, turn, step, signal, log =
     return decision
   }
 
+  // This is the last point before the message enters decision.messages. Recall,
+  // cue and texture all awaited above; a library/context/switch change during any
+  // of them invalidates every part built from the old snapshot, not just recall.
+  if (!injectionSnapshotIsCurrent(sessionId, snapshot, settings.autoInject)) return decision
+
   const text = parts.join('\n\n')
   const message = createMemoryMessage(text)
   const rewritten = [...decision.messages]

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()