@yeaft/webchat-agent 1.0.587 → 1.0.588

package/local-runtime/web/index.html

@@ -17,6 +17,6 @@
 </head>
 <body>
   <div id="app"></div>
-  <script type="module" src="app.bundle.js?v=8e6f87a6"></script>
+  <script type="module" src="app.bundle.js?v=0afa7538"></script>
 </body>
 </html>

package/local-runtime/web/installers/install.ps1

@@ -166,8 +166,19 @@ try {
   $env:PATH = "$NodeDir;$Prefix;$LocalBin;$OriginalPath"
   & $Node $NpmCli --version *> $null
   if ($LASTEXITCODE -ne 0) { Stop-Install 'the selected Node.js does not provide a working npm' }
-  & $Node $NpmCli --prefix $Prefix --global=false install $Package pm2 --registry=$Registry --no-audit --no-fund --loglevel=error
-  if ($LASTEXITCODE -ne 0) { Stop-Install 'npm could not install the Yeaft Agent' }
+  # Default to CPU native dependencies without changing the caller or service environment.
+  $OriginalCuda = Get-Item -LiteralPath 'Env:ONNXRUNTIME_NODE_INSTALL_CUDA' -ErrorAction SilentlyContinue
+  try {
+    if (-not $env:ONNXRUNTIME_NODE_INSTALL_CUDA) { $env:ONNXRUNTIME_NODE_INSTALL_CUDA = 'skip' }
+    & $Node $NpmCli --prefix $Prefix --global=false install $Package pm2 --registry=$Registry --no-audit --no-fund --loglevel=error
+    if ($LASTEXITCODE -ne 0) { Stop-Install 'npm could not install the Yeaft Agent' }
+  } finally {
+    if ($null -ne $OriginalCuda) {
+      Set-Item -LiteralPath 'Env:ONNXRUNTIME_NODE_INSTALL_CUDA' -Value $OriginalCuda.Value
+    } else {
+      Remove-Item -LiteralPath 'Env:ONNXRUNTIME_NODE_INSTALL_CUDA' -ErrorAction SilentlyContinue
+    }
+  }
 
   $Cli = Join-Path $Prefix 'node_modules\@yeaft\webchat-agent\cli.js'
   $Pm2 = Join-Path $Prefix 'node_modules\pm2\bin\pm2'

package/local-runtime/web/installers/install.sh

@@ -124,7 +124,9 @@ fi
 YEAFT_INSTALL_SERVER="$SERVER" "$NODE" -e 'try {const u=new URL(process.env.YEAFT_INSTALL_SERVER);if(!["ws:","wss:"].includes(u.protocol)||!u.hostname||u.username||u.password)process.exit(1)}catch{process.exit(1)}' >/dev/null 2>&1 || fail 'invalid server URL'
 NODE_DIR=$(dirname "$NODE")
 printf 'Installing the Yeaft Agent in %s...\n' "$PREFIX"
-PATH="$NODE_DIR:$PREFIX/bin:$PATH" "$NPM" --prefix "$PREFIX" --global install "$PACKAGE" \
+# Default to CPU native dependencies; scope the policy to npm, not the Agent service.
+ONNXRUNTIME_NODE_INSTALL_CUDA="${ONNXRUNTIME_NODE_INSTALL_CUDA:-skip}" \
+  PATH="$NODE_DIR:$PREFIX/bin:$PATH" "$NPM" --prefix "$PREFIX" --global install "$PACKAGE" \
   --registry="$REGISTRY" --no-audit --no-fund --loglevel=error || fail 'npm could not install the Yeaft Agent'
 CLI_JS=$PREFIX/lib/node_modules/@yeaft/webchat-agent/cli.js
 [ -f "$CLI_JS" ] || fail 'the installed package did not provide yeaft-agent'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.587",
+  "version": "1.0.588",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",
@@ -82,5 +82,8 @@
     "tweetnacl-util": "^0.15.1",
     "uuid": "^11.1.1",
     "ws": "^8.21.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "3.8.1"
   }
 }

package/yeaft/person/bridge.js

@@ -3,7 +3,7 @@ import ctx from '../../context.js';
 import { sendToServer } from '../../connection/buffer.js';
 
 /** Lazy Person transport. Only deployment-local environment supplies database credentials.
- * MongoDB is never contacted at ordinary Agent startup, nor configured by browser messages.
+ * Storage is lazy and instance-local by default; browser messages cannot choose a backend.
  */
 export function createPersonBridge({
   context = ctx, send = sendToServer, env = process.env,
@@ -33,14 +33,6 @@ export function createPersonBridge({
         return true;
       }
       const uri = env.YEAFT_PERSON_MONGODB_URI;
-      if (!uri) {
-        if (response.op === 'status') {
-          await send({ ...response, ok: true, data: { configured: false, reason: 'mongodb_not_configured' } });
-        } else {
-          await send({ ...response, ok: false, errorCode: 'not_configured', error: 'Configure YEAFT_PERSON_MONGODB_URI on the Agent to enable the digital person' });
-        }
-        return true;
-      }
       const agentId = context.agentId || context.AGENT_ID;
       if (!agentId || !context.CONFIG?.yeaftDir) throw new Error('identity');
       // Server+Agent is a storage boundary; a re-registration must not reuse the old runtime.
@@ -54,6 +46,8 @@ export function createPersonBridge({
       if (!servicePromise) {
         servicePromise = Promise.resolve().then(() => createService({
           uri,
+          storage: env.YEAFT_PERSON_STORAGE,
+          embedding: { enabled: env.YEAFT_PERSON_EMBEDDING !== 'off', allowDownload: env.YEAFT_PERSON_EMBEDDING_DOWNLOAD !== '0' },
           dbName: env.YEAFT_PERSON_MONGODB_DB || 'yeaft_person',
           namespace,
           yeaftDir: context.CONFIG.yeaftDir,
@@ -74,10 +68,11 @@ export function createPersonBridge({
         NOT_OPEN: 'Open the digital person first',
         STALE: 'Digital person state changed; refresh and try again',
         IDEMPOTENCY_CONFLICT: 'This message identifier already belongs to a different request',
+        STORAGE_MISMATCH: 'The configured storage differs from the existing Person authority; do not switch without a verified migration',
         UNSUPPORTED: 'This capability is not available in this digital person version',
       };
       const known = Object.hasOwn(safeErrors, error?.code);
-      // A lost Mongo commit acknowledgement or response-send failure is not a
+      // A lost database commit acknowledgement or response-send failure is not a
       // definitive rejection. Preserve the command ID so an explicit retry deduplicates.
       await send({ ...response, ok: false, errorCode: known ? error.code.toLowerCase() : 'outcome_unknown',
         error: known ? safeErrors[error.code] : 'Digital person outcome is unknown; refresh and check Agent database/model configuration' });

package/yeaft/person/capabilities.js

@@ -3,7 +3,7 @@ import { bytes, digest, fail, identifier, object, page, text } from './contracts
 // Versioned read-only methods, not the Agent's full registry. No shell/filesystem/VP side effects.
 const entries = [
   { id: 'Think', version: 1, domain: 'cognition', description: 'Intrinsic deliberate reflection, reorganization, association and reconsideration.', instructions: 'Revisit supplied experiences and current judgments; separate report from hypothesis, propose new concepts or associations, test a counterexample, and record the explicit finding with uncertainty. It is fine to rest. This is a method, not another model call or external action.', args: {} },
-  { id: 'Recall', version: 1, domain: 'memory', description: 'Read a bounded page of your own MongoDB messages or concepts.', instructions: 'args: {kind:"messages"|"concepts",query?:string,cursor?:string|null,limit?:1..5}. Literal text search, not a semantic or exhaustive search. Preserve nextCursor to reach older/lower-ranked records.', args: { kind: 'messages|concepts', query: 'optional literal search text', cursor: 'optional opaque cursor', limit: '1..5' } },
+  { id: 'Recall', version: 1, domain: 'memory', description: 'Recall a bounded page of your own long-term messages or concepts.', instructions: 'args: {kind:"messages"|"concepts",query?:string,cursor?:string|null,limit?:1..5}. SQLite uses local hybrid keyword/semantic recall when available; inspect retrieval mode, coverage and degradation. Legacy storage may use literal matching. Results are not exhaustive or authorization. Preserve nextCursor for the same query; local ranking cursors expire after 5 minutes or restart.', args: { kind: 'messages|concepts', query: 'optional memory search text', cursor: 'optional opaque cursor', limit: '1..5' } },
   { id: 'Skill.reconsider', version: 1, domain: 'method', description: 'Read-only method for revising a previous judgment.', instructions: 'Identify one prior claim, list a concrete counterexample or missing evidence, and decide whether to retain, qualify or revise it. Mark what remains unresolved. Do not present the counterexample as an observed event without evidence.', args: {} },
   { id: 'Skill.associate', version: 1, domain: 'method', description: 'Read-only method for new conceptual associations.', instructions: 'Compare two recalled concepts or experiences. Propose a typed relation and a new question or hypothetical scenario. Co-occurrence is not causation; imagination is not an experience. Keep useful disagreement instead of forcing agreement.', args: {} },
 ];
@@ -16,7 +16,8 @@ export const CAPABILITY_MAP = Object.freeze({
 export const catalogRevision = digest(entries);
 export class PersonCapabilities {
   constructor(repository, ownerId) { this.repository = repository; this.ownerId = ownerId; this.loaded = new Set(['Think']); }
-  async execute({ id, args }) {
+  async execute({ id, args }, { signal } = {}) {
+    signal?.throwIfAborted();
     if (id === 'catalog.search') {
       object(args, ['query', 'cursor', 'limit'], []);
       const query = text(args.query ?? '', 200, true).toLowerCase();
@@ -44,9 +45,10 @@ export class PersonCapabilities {
       text(args.query ?? '', 200, true);
       const limit = args.limit ?? 3;
       if (!Number.isInteger(limit) || limit < 1 || limit > 5) fail('INVALID_REQUEST');
-      const cursor = args.kind === 'messages' ? page({ cursor: args.cursor, limit }).cursor : args.cursor;
-      if (args.kind === 'concepts' && cursor != null) identifier(cursor);
-      const result = await this.repository.recall(this.ownerId, { ...args, cursor, limit });
+      const localCursor = typeof args.cursor === 'string' && /^lm:[a-f0-9]{32}:\d{1,6}$/.test(args.cursor);
+      const cursor = args.kind === 'messages' && !localCursor ? page({ cursor: args.cursor, limit }).cursor : args.cursor;
+      if (cursor != null && (localCursor || args.kind === 'concepts')) identifier(cursor);
+      const result = await this.repository.recall(this.ownerId, { ...args, cursor, limit }, { signal });
       // Pages contain complete accepted records; context assembly may omit whole records later.
       if (bytes(result) > 60000) fail('CONTEXT_LIMIT');
       return { ...result, kind: args.kind, version: entry.version };

package/yeaft/person/contracts.js

@@ -3,8 +3,9 @@ import { createHash } from 'node:crypto';
 // 只允许应用层显式产物；不要求或保存 provider 的隐藏推理。
 export const LIMITS = Object.freeze({ inputBytes: 8192, outputBytes: 65536, contextBytes: 65536, calls: 4, timeoutMs: 120000, leaseMs: 15000 });
 const ERRORS = {
-  INVALID_REQUEST: 'Invalid digital person request.', NOT_CONFIGURED: 'MongoDB is not configured for digital person.',
-  STORAGE_UNAVAILABLE: 'Digital person storage is unavailable; a transaction-capable MongoDB replica set is required.',
+  INVALID_REQUEST: 'Invalid digital person request.', NOT_CONFIGURED: 'Digital person storage configuration is missing.',
+  STORAGE_UNAVAILABLE: 'Digital person storage is unavailable. Check instance storage and database configuration.',
+  STORAGE_MISMATCH: 'Person storage is already bound to another backend; a verified migration is required.',
   NOT_OPEN: 'Open your digital person first.', BUSY: 'The digital person is already active.',
   IDEMPOTENCY_CONFLICT: 'This clientMessageId was already used for a different request.',
   STALE: 'The activity no longer owns the current person revision.', INVALID_PROPOSAL: 'The model returned an invalid cognitive proposal.',

package/yeaft/person/local-memory-cache.js

@@ -0,0 +1,82 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, open, rename, stat, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+async function isComplete(file, { size, sha256 }) {
+  try {
+    if ((await stat(file)).size !== size) return false;
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(file)) hash.update(chunk);
+    return hash.digest('hex') === sha256;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function syncDirectory(dir) {
+  // Windows does not support opening directories for fsync. A lost directory
+  // entry after power failure is still a cache miss, never an accepted partial file.
+  if (process.platform === 'win32') return;
+  const handle = await open(dir, 'r');
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+async function publish(file, url, expected) {
+  const dir = path.dirname(file);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.partial`;
+  let handle;
+  try {
+    const response = await fetch(url);
+    if (response.status !== 200 || !response.body) throw new Error('model_download_failed');
+    handle = await open(temporary, 'wx', 0o600);
+    const hash = createHash('sha256');
+    let size = 0;
+    // Backpressure keeps memory bounded to stream chunks, including the ONNX file.
+    for await (const chunk of response.body) {
+      size += chunk.byteLength;
+      if (size > expected.size) throw new Error('model_integrity_failed');
+      hash.update(chunk);
+      await handle.writeFile(chunk);
+    }
+    if (size !== expected.size || hash.digest('hex') !== expected.sha256) throw new Error('model_integrity_failed');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    // Concurrent publishers have the same pinned digest. Never unlink the final
+    // path: an invalid reader or failed writer must not remove another one's repair.
+    await rename(temporary, file);
+    await syncDirectory(dir);
+  } finally {
+    await handle?.close();
+    await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+}
+
+/**
+ * Prepare an instance-owned, immutable model snapshot before Transformers sees it.
+ * `artifacts` is a trusted manifest of filename -> { size, sha256 }, pinned with
+ * `model` and its commit `revision`. The hashes are the completion markers: legacy
+ * complete files work offline, partial/corrupt files are misses, and SIGKILL leaves
+ * only ignored unique .partial files. No lock or mutable sidecar can become stale.
+ * Returns a local directory; inference must use it with remote access disabled.
+ */
+export async function prepareModelCache({ yeaftDir, model, revision, artifacts, allowDownload = true }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(model) || model.split('/').some(p => p === '.' || p === '..') || !/^[a-f0-9]{40}$/.test(revision)) {
+    throw new Error('invalid_model_identity');
+  }
+  const dir = path.resolve(yeaftDir, 'person', 'models', model, revision);
+  for (const [name, expected] of Object.entries(artifacts)) {
+    if (!name.split('/').every(p => /^[\w.-]+$/.test(p) && p !== '.' && p !== '..') ||
+        !Number.isSafeInteger(expected.size) || expected.size <= 0 || !/^[a-f0-9]{64}$/.test(expected.sha256)) {
+      throw new Error('invalid_model_artifact');
+    }
+    const file = path.join(dir, name);
+    if (await isComplete(file, expected)) continue;
+    if (!allowDownload) throw new Error('model_cache_incomplete');
+    await publish(file, `https://huggingface.co/${model}/resolve/${revision}/${name}`, expected);
+  }
+  return dir;
+}

package/yeaft/person/local-memory-embedding.js

@@ -0,0 +1,54 @@
+import { prepareModelCache } from './local-memory-cache.js';
+
+export const LOCAL_MODEL = 'Xenova/multilingual-e5-small';
+export const LOCAL_REVISION = '761b726dd34fb83930e26aab4e9ac3899aa1fa78';
+// SHA-256 of the exact revision's files (LFS oid for tokenizer/ONNX). Update this
+// manifest with LOCAL_REVISION, never from mutable download response metadata.
+export const LOCAL_ARTIFACTS = Object.freeze({
+  'config.json': Object.freeze({ size: 658, sha256: 'cb99455288675345e1a4f411438d5d0adbba5fbd3a67ea4fb03c015433b996c1' }),
+  'tokenizer_config.json': Object.freeze({ size: 443, sha256: 'a1d6bc8734a6f635dc158508bef000f8e2e5a759c7d92f984b2c86e5ff53425b' }),
+  'tokenizer.json': Object.freeze({ size: 17082730, sha256: '0b44a9d7b51c3c62626640cda0e2c2f70fdacdc25bbbd68038369d14ebdf4c39' }),
+  'onnx/model_quantized.onnx': Object.freeze({ size: 118308185, sha256: 'f80102d3f2a1229f387d3c81909990d8945513e347b0eab049f7de3c6f98c193' }),
+});
+export const VECTOR_DIMENSION = 384;
+export const CHUNK_SIZE = 320;
+export const CHUNK_OVERLAP = 64;
+// Version the complete space, not just the model name. A change invalidates derived chunks.
+export const MODEL_FINGERPRINT = `${LOCAL_MODEL}@${LOCAL_REVISION}:q8:mean:l2:384:e5-prefix:codepoints-${CHUNK_SIZE}-${CHUNK_OVERLAP}:segmenter-v1`;
+
+/** Worker-only lazy adapter. Only model artifacts use the network; text goes to local ONNX. */
+export function createEmbedding({ yeaftDir, allowDownload = true, threads = 2 } = {}) {
+  let extractor;
+  async function load() {
+    if (extractor) return extractor;
+    const modelDir = await prepareModelCache({ yeaftDir, model: LOCAL_MODEL, revision: LOCAL_REVISION, artifacts: LOCAL_ARTIFACTS, allowDownload });
+    const { pipeline, env } = await import('@huggingface/transformers');
+    // Never let Transformers' non-atomic FileCache write model artifacts. The
+    // validated local snapshot is complete, including when restarting offline.
+    env.allowRemoteModels = false;
+    env.allowLocalModels = true;
+    env.localModelPath = '';
+    env.useBrowserCache = false;
+    env.useCustomCache = true;
+    env.customCache = { async match() {}, async put() { throw new Error('unexpected_model_cache_write'); } };
+    // 3.8.1 also uses this flag to pass the ONNX *path* to the native runtime.
+    // The custom cache above prevents its unsafe FileCache from being instantiated.
+    env.useFSCache = true;
+    extractor = await pipeline('feature-extraction', modelDir, {
+      revision: LOCAL_REVISION, dtype: 'q8', device: 'cpu',
+      local_files_only: true,
+      session_options: { intraOpNumThreads: Math.max(1, Math.min(4, threads)), interOpNumThreads: 1 },
+    });
+    return extractor;
+  }
+  return {
+    async embed(texts, type) {
+      const model = await load();
+      const output = await model(texts.map(text => `${type === 'query' ? 'query' : 'passage'}: ${text}`), {
+        pooling: 'mean', normalize: true, truncation: true, max_length: 512,
+      });
+      return output.tolist();
+    },
+    async close() { if (extractor) await extractor.dispose(); extractor = null; },
+  };
+}

package/yeaft/person/local-memory-host.js

@@ -0,0 +1,40 @@
+import { Worker } from 'node:worker_threads';
+import { createEmbedding } from './local-memory-embedding.js';
+
+// ONNX's native addon is not reliably reloadable in replacement Node threads.
+// Keep it in this disposable process; SQLite/tokenization/ranking use a worker
+// thread. The Agent supervises the whole process, including blocked native work.
+let worker;
+let embedder;
+let closing = false;
+process.on('message', message => {
+  if (message.init) {
+    if (worker) return;
+    const options = message.init;
+    worker = new Worker(new URL('./local-memory-worker.js', import.meta.url), { workerData: options });
+    worker.on('message', async response => {
+      if (response.embeddingRequest) {
+        const { id, texts, type } = response.embeddingRequest;
+        try {
+          embedder ??= createEmbedding({ ...options.embedding, yeaftDir: options.yeaftDir });
+          const value = await embedder.embed(texts, type);
+          worker.postMessage({ embeddingResult: { id, value } });
+        } catch {
+          worker.postMessage({ embeddingResult: { id, error: true } });
+        }
+      } else if (response.closed) {
+        closing = true;
+        try { await embedder?.close(); }
+        finally { process.disconnect(); }
+      } else {
+        process.send?.(response);
+      }
+    });
+    worker.on('error', () => process.exit(1));
+    worker.on('exit', code => { if (!closing || code) process.exit(1); });
+    return;
+  }
+  worker?.postMessage(message);
+});
+// Agent crash/IPC teardown must not leave the model process or its thread alive.
+process.on('disconnect', () => process.exit(0));

package/yeaft/person/local-memory-worker.js

@@ -0,0 +1,231 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { parentPort, workerData } from 'node:worker_threads';
+import { CHUNK_SIZE, CHUNK_OVERLAP, MODEL_FINGERPRINT, VECTOR_DIMENSION } from './local-memory-embedding.js';
+
+const { yeaftDir, namespace, embedding = {}, embeddingModule, maxVectorChunks, maxEmbedChunksPerRecall, candidateLimit } = workerData;
+const fingerprint = embeddingModule ? `${MODEL_FINGERPRINT}:injected:${embeddingModule}:${embedding.fingerprint ?? 'test'}` : MODEL_FINGERPRINT;
+let db;
+let embedder;
+let embeddingId = 0;
+const embeddingRequests = new Map();
+function hostEmbedding(texts, type) {
+  return new Promise((resolve, reject) => {
+    const id = ++embeddingId;
+    embeddingRequests.set(id, { resolve, reject });
+    parentPort.postMessage({ embeddingRequest: { id, texts, type } });
+  });
+}
+const segmenter = new Intl.Segmenter('zh', { granularity: 'word' });
+
+function tokens(text) {
+  return [...segmenter.segment(text.normalize('NFKC').toLowerCase())].filter(s => s.isWordLike).map(s => s.segment);
+}
+function chunks(text) {
+  const points = Array.from(text);
+  const result = [];
+  for (let start = 0; start < points.length; start += CHUNK_SIZE - CHUNK_OVERLAP) {
+    result.push(points.slice(start, start + CHUNK_SIZE).join(''));
+    if (start + CHUNK_SIZE >= points.length) break;
+  }
+  return result;
+}
+function transaction(fn) {
+  db.exec('BEGIN IMMEDIATE');
+  try { const result = fn(); db.exec('COMMIT'); return result; }
+  catch (error) { db.exec('ROLLBACK'); throw error; }
+}
+function open() {
+  if (db) return;
+  mkdirSync(path.join(yeaftDir, 'person'), { recursive: true, mode: 0o700 });
+  db = new DatabaseSync(path.join(yeaftDir, 'person', 'recall.db'));
+  try {
+    // Some supported early Node 22 builds omit FTS5. Keep authority usable and
+    // report an explicit literal-only fallback; never start a model on this path.
+    db.exec('CREATE VIRTUAL TABLE temp.person_fts_probe USING fts5(terms); DROP TABLE temp.person_fts_probe;');
+  } catch (error) {
+    db.close(); db = null;
+    if (/no such module: fts5/i.test(error.message)) error.code = 'FTS_UNAVAILABLE';
+    throw error;
+  }
+  db.exec(`PRAGMA busy_timeout=2000; PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;
+    CREATE TABLE IF NOT EXISTS spaces(namespace TEXT PRIMARY KEY, fingerprint TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS checkpoints(namespace TEXT NOT NULL, owner TEXT NOT NULL, seq INTEGER NOT NULL, PRIMARY KEY(namespace,owner));
+    CREATE TABLE IF NOT EXISTS chunks(
+      rowid INTEGER PRIMARY KEY, namespace TEXT NOT NULL, owner TEXT NOT NULL, kind TEXT NOT NULL,
+      id TEXT NOT NULL, revision INTEGER NOT NULL, part INTEGER NOT NULL, seq INTEGER NOT NULL,
+      text TEXT NOT NULL, terms TEXT NOT NULL, vector BLOB,
+      UNIQUE(namespace,owner,kind,id,part));
+    CREATE INDEX IF NOT EXISTS recall_scope ON chunks(namespace,owner,kind,seq DESC);
+    CREATE VIRTUAL TABLE IF NOT EXISTS chunk_fts USING fts5(terms, content='chunks', content_rowid='rowid', tokenize='unicode61');
+    CREATE TRIGGER IF NOT EXISTS chunks_insert AFTER INSERT ON chunks BEGIN
+      INSERT INTO chunk_fts(rowid,terms) VALUES (new.rowid,new.terms); END;
+    CREATE TRIGGER IF NOT EXISTS chunks_delete AFTER DELETE ON chunks BEGIN
+      INSERT INTO chunk_fts(chunk_fts,rowid,terms) VALUES ('delete',old.rowid,old.terms); END;`);
+}
+function ensureSpace() {
+  transaction(() => {
+    const previous = db.prepare('SELECT fingerprint FROM spaces WHERE namespace=?').get(namespace);
+    if (!previous || previous.fingerprint !== fingerprint) {
+      db.prepare('DELETE FROM chunks WHERE namespace=?').run(namespace);
+      db.prepare('DELETE FROM checkpoints WHERE namespace=?').run(namespace);
+      db.prepare('INSERT OR REPLACE INTO spaces VALUES (?,?)').run(namespace, fingerprint);
+    }
+  });
+}
+function checkpoint(owner) {
+  return db.prepare('SELECT seq FROM checkpoints WHERE namespace=? AND owner=?').get(namespace, owner)?.seq ?? 0;
+}
+function assertSpace() {
+  if (db.prepare('SELECT fingerprint FROM spaces WHERE namespace=?').get(namespace)?.fingerprint !== fingerprint) throw new Error('space_changed');
+}
+function apply(owner, items, lastSeq) {
+  return transaction(() => {
+    assertSpace();
+    const before = checkpoint(owner);
+    const remove = db.prepare('DELETE FROM chunks WHERE namespace=? AND owner=? AND kind=? AND id=?');
+    const insert = db.prepare('INSERT INTO chunks(namespace,owner,kind,id,revision,part,seq,text,terms) VALUES (?,?,?,?,?,?,?,?,?)');
+    for (const item of items) {
+      if (item.seq <= before) continue;
+      if (!['messages', 'concepts'].includes(item.kind) || !Number.isSafeInteger(item.seq) || !Number.isSafeInteger(item.revision) || typeof item.id !== 'string') throw new Error('invalid_journal');
+      remove.run(namespace, owner, item.kind, item.id);
+      if (item.record) {
+        const text = item.kind === 'messages' ? item.record.text : item.record.statement;
+        if (typeof text !== 'string') throw new Error('invalid_record');
+        for (const [part, chunk] of chunks(text).entries()) insert.run(namespace, owner, item.kind, item.id, item.revision, part, item.seq, chunk, tokens(chunk).join(' '));
+      }
+    }
+    if (!Number.isSafeInteger(lastSeq) || lastSeq < before || items.some(item => item.seq > lastSeq)) throw new Error('invalid_checkpoint');
+    db.prepare('INSERT INTO checkpoints VALUES (?,?,?) ON CONFLICT(namespace,owner) DO UPDATE SET seq=excluded.seq').run(namespace, owner, lastSeq);
+    return { checkpoint: lastSeq };
+  });
+}
+function vector(value) {
+  if ((!Array.isArray(value) && !ArrayBuffer.isView(value)) || value.length !== VECTOR_DIMENSION || !Array.from(value).every(Number.isFinite)) throw new Error('invalid_embedding');
+  const norm = Math.sqrt(Array.from(value).reduce((sum, n) => sum + n * n, 0));
+  if (!norm) throw new Error('invalid_embedding');
+  return Float32Array.from(value, n => n / norm);
+}
+function encode(v) {
+  const blob = Buffer.alloc(VECTOR_DIMENSION * 4);
+  v.forEach((n, i) => blob.writeFloatLE(n, i * 4));
+  return blob;
+}
+async function embed(texts, type) {
+  // Trusted deterministic fixtures run in this thread. Production inference runs
+  // in its disposable host process to avoid ONNX addon thread reload failures.
+  if (embeddingModule && !embedder) {
+    const module = await import(embeddingModule);
+    embedder = module.createEmbedding({ ...embedding, yeaftDir });
+  }
+  const results = embedder ? await embedder.embed(texts, type) : await hostEmbedding(texts, type);
+  if (!Array.isArray(results) || results.length !== texts.length) throw new Error('invalid_embedding');
+  return results.map(vector);
+}
+async function search(owner, kind, query) {
+  const reasons = [];
+  // Read space identity and vectors in one transaction, including when multiple
+  // local controllers use the same DB. Never accept vectors from an ABA space switch.
+  const { totalChunks, eligible } = transaction(() => {
+    assertSpace();
+    const totalChunks = db.prepare('SELECT count(*) AS n FROM chunks WHERE namespace=? AND owner=? AND kind=?').get(namespace, owner, kind).n;
+    // Exact cosine is deliberately bounded to the newest N chunks. FTS covers all indexed text.
+    const eligible = db.prepare('SELECT rowid,id,revision,seq,text,vector FROM chunks WHERE namespace=? AND owner=? AND kind=? ORDER BY seq DESC,id,part LIMIT ?').all(namespace, owner, kind, maxVectorChunks);
+    return { totalChunks, eligible };
+  });
+  let queryVector;
+  if (embedding.enabled !== false) {
+    try {
+      queryVector = (await embed([query], 'query'))[0];
+      const pending = eligible.filter(row => !row.vector).slice(0, maxEmbedChunksPerRecall);
+      for (let start = 0; start < pending.length; start += 8) {
+        const batch = pending.slice(start, start + 8);
+        const values = await embed(batch.map(row => row.text), 'passage');
+        transaction(() => {
+          assertSpace();
+          const update = db.prepare('UPDATE chunks SET vector=? WHERE rowid=? AND namespace=? AND owner=? AND kind=? AND id=? AND revision=? AND seq=?');
+          batch.forEach((row, i) => {
+            row.vector = encode(values[i]);
+            update.run(row.vector, row.rowid, namespace, owner, kind, row.id, row.revision, row.seq);
+          });
+        });
+      }
+    } catch {
+      queryVector = null;
+      reasons.push('embedding_unavailable');
+      // The controller replaces this process after delivering keyword results:
+      // ONNX itself can cache a rejected native-session initialization promise.
+    }
+  } else reasons.push('semantic_disabled');
+  assertSpace();
+  const terms = [...new Set(tokens(query))].slice(0, 32).map(term => `"${term.replaceAll('"', '""')}"`).join(' OR ');
+  // Group before limiting parents: many matching chunks must not crowd out a
+  // shorter record. MATERIALIZED keeps FTS5 bm25 in its supported row context.
+  const keyword = terms ? db.prepare(`WITH matches AS MATERIALIZED (
+    SELECT c.id,c.revision,bm25(chunk_fts) AS rank FROM chunk_fts JOIN chunks c ON c.rowid=chunk_fts.rowid
+    WHERE chunk_fts MATCH ? AND c.namespace=? AND c.owner=? AND c.kind=?)
+    SELECT id,revision,min(rank) AS rank FROM matches GROUP BY id,revision ORDER BY rank,id LIMIT ?`).all(terms, namespace, owner, kind, candidateLimit) : [];
+  let vectorScannedChunks = 0;
+  const semantic = [];
+  if (queryVector) for (const row of eligible) {
+    if (!row.vector || row.vector.length !== VECTOR_DIMENSION * 4) continue;
+    const bytes = Buffer.from(row.vector);
+    let cosine = 0;
+    for (let i = 0; i < VECTOR_DIMENSION; i++) cosine += queryVector[i] * bytes.readFloatLE(i * 4);
+    vectorScannedChunks++;
+    if (Number.isFinite(cosine)) semantic.push({ id: row.id, revision: row.revision, cosine });
+  }
+  semantic.sort((a, b) => b.cosine - a.cosine || a.id.localeCompare(b.id));
+  const ranks = new Map();
+  // Deduplicate each channel BEFORE RRF: a verbose record does not receive more votes.
+  for (const channel of [keyword, semantic]) {
+    const seen = new Set();
+    for (const ref of channel) {
+      if (seen.has(ref.id)) continue;
+      seen.add(ref.id);
+      const current = ranks.get(ref.id) ?? { id: ref.id, revision: ref.revision, score: 0 };
+      current.score += 1 / (60 + seen.size);
+      ranks.set(ref.id, current);
+      if (seen.size >= candidateLimit) break;
+    }
+  }
+  const refs = [...ranks.values()].sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, candidateLimit).map(({ id, revision }) => ({ id, revision }));
+  const semanticUsed = Boolean(queryVector && vectorScannedChunks);
+  if (queryVector && vectorScannedChunks < totalChunks) reasons.push('semantic_coverage_limited');
+  return { refs, resetWorker: reasons.includes('embedding_unavailable'), retrieval: {
+    mode: semanticUsed ? 'hybrid' : 'keyword', semantic: semanticUsed, degraded: reasons.some(r => r !== 'semantic_disabled'), reasons,
+    fingerprint, ranking: 'rrf-60', bounded: true, candidateLimit,
+    coverage: { totalChunks, vectorEligibleChunks: eligible.length, vectorScannedChunks, maxVectorChunks, maxEmbedChunksPerRecall },
+  } };
+}
+async function dispatch({ op, owner, ...args }) {
+  if (op === 'close') { await embedder?.close?.(); db?.close(); db = null; return null; }
+  if (typeof owner !== 'string' || !owner.length) throw new Error('invalid_owner');
+  open();
+  if (op === 'checkpoint') { ensureSpace(); return checkpoint(owner); }
+  assertSpace();
+  if (op === 'apply') return apply(owner, args.items, args.lastSeq);
+  if (op === 'search') return search(owner, args.kind, args.query);
+  throw new Error('invalid_operation');
+}
+// The controller issues one RPC at a time; serialize defensively inside the worker too.
+let chain = Promise.resolve();
+parentPort.on('message', message => {
+  // Results must bypass the serialized RPC chain, whose search is awaiting them.
+  if (message.embeddingResult) {
+    const { id, value, error } = message.embeddingResult;
+    const pending = embeddingRequests.get(id);
+    embeddingRequests.delete(id);
+    if (error) pending?.reject(new Error('embedding_unavailable'));
+    else pending?.resolve(value);
+    return;
+  }
+  chain = chain.then(async () => {
+    try {
+      const value = await dispatch(message);
+      if (message.op === 'close') { parentPort.postMessage({ closed: true }); return; }
+      parentPort.postMessage({ id: message.id, value });
+    } catch (error) { parentPort.postMessage({ id: message.id, error: { code: error.code || 'INDEX_FAILURE' } }); }
+  });
+});