@yeaft/webchat-agent 1.0.587 → 1.0.589

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' } }); }
+  });
+});

package/yeaft/person/local-memory.js

@@ -0,0 +1,294 @@
+import { fork } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+
+const fault = code => Object.assign(new Error(code), { code });
+function integer(value, fallback, min, max) {
+  return Number.isSafeInteger(value) ? Math.max(min, Math.min(max, value)) : fallback;
+}
+
+/**
+ * Owner-scoped, disposable search projection; repository is always authoritative.
+ * No I/O, model import or inference until a nonempty recall. The repository must
+ * expose searchChanges/resolveMemories plus the ORIGINAL literal recall function
+ * (capture it before decorating repository.recall; alternatively pass literalRecall).
+ *
+ * Defaults: exact scan newest 10k chunks, embed at most 256 missing chunks/recall,
+ * return a stable bounded top-200 snapshot (5 minute/32 snapshot cache). FTS covers
+ * all journal-indexed text. Coverage/catch-up limits are explicit in retrieval.
+ * embeddingModule is a trusted worker-module injection seam for tests, NOT wire input.
+ */
+export class LocalPersonMemory {
+  constructor({ repository, yeaftDir, namespace, literalRecall, embedding = {}, embeddingModule,
+    maxQueue = 8, timeoutMs = 120000, shutdownTimeoutMs = 5000,
+    journalBatchSize = 100, maxJournalPages = 50, maxVectorChunks = 10000,
+    maxEmbedChunksPerRecall = 256, candidateLimit = 200, snapshotTtlMs = 300000, maxSnapshots = 32 } = {}) {
+    if (!repository || !yeaftDir || typeof namespace !== 'string' || !namespace.trim()) throw new TypeError('repository, yeaftDir and namespace are required');
+    if (repository.namespace && repository.namespace !== namespace) throw new TypeError('repository namespace mismatch');
+    this.repository = repository;
+    this.literalRecall = literalRecall ?? repository.recall.bind(repository);
+    this.options = {
+      yeaftDir: path.resolve(yeaftDir), namespace, embedding: { enabled: true, allowDownload: true, ...embedding, threads: integer(embedding.threads, 2, 1, 4) }, embeddingModule,
+      maxVectorChunks: integer(maxVectorChunks, 10000, 1, 50000),
+      maxEmbedChunksPerRecall: integer(maxEmbedChunksPerRecall, 256, 1, 2048),
+      candidateLimit: integer(candidateLimit, 200, 1, 1000),
+    };
+    this.maxQueue = integer(maxQueue, 8, 1, 32);
+    this.timeoutMs = integer(timeoutMs, 120000, 20, 600000);
+    this.shutdownTimeoutMs = integer(shutdownTimeoutMs, 5000, 20, 10000);
+    this.journalBatchSize = integer(journalBatchSize, 100, 1, 500);
+    this.maxJournalPages = integer(maxJournalPages, 50, 1, 1000);
+    this.snapshotTtlMs = integer(snapshotTtlMs, 300000, 1, 3600000);
+    this.maxSnapshots = integer(maxSnapshots, 32, 1, 128);
+    this.snapshots = new Map();
+    this.queue = [];
+    this.active = null;
+    this.worker = null;
+    this.rpc = null;
+    this.nextId = 0;
+    this.closed = false;
+  }
+
+  status() {
+    return { enabled: this.options.embedding.enabled !== false, workerStarted: Boolean(this.worker), queued: this.queue.length, closed: this.closed };
+  }
+
+  async recall(ownerId, { kind = 'messages', query = '', cursor = null, limit = 5 } = {}, { signal } = {}) {
+    if (typeof ownerId !== 'string' || !ownerId.trim()) throw new TypeError('ownerId is required');
+    if (!['messages', 'concepts'].includes(kind) || typeof query !== 'string' || query.length > 4000) throw fault('INVALID_RECALL');
+    if (this.closed) throw fault('MEMORY_CLOSED');
+    if (signal?.aborted) throw fault('RECALL_CANCELLED');
+    limit = integer(limit, 5, 1, 50);
+    if (!query.trim()) return this.literalRecall(ownerId, { kind, query, cursor, limit });
+    const request = { ownerId, kind, query, cursor, limit };
+    return this._schedule(token => this._recall(request, token), error => {
+      if (signal?.aborted) throw fault('RECALL_CANCELLED');
+      if (['INVALID_CURSOR', 'MEMORY_CLOSED', 'RECALL_BUSY', 'RECALL_CANCELLED'].includes(error.code)) throw error;
+      // A failed continuation must never silently restart ranking or expose a foreign cursor.
+      if (cursor) throw fault('RECALL_RETRY');
+      return this._literal(request, error.code || 'INDEX_FAILURE', undefined, signal);
+    }, signal);
+  }
+
+  _alive(token) {
+    if (this.closed) throw fault('MEMORY_CLOSED');
+    if (token.cancelled) throw fault(token.reason || 'RECALL_TIMEOUT');
+  }
+  _schedule(fn, onError, signal) {
+    if (this.queue.length + Number(Boolean(this.active)) >= this.maxQueue) return Promise.reject(fault('RECALL_BUSY'));
+    return new Promise((resolve, reject) => {
+      const token = { cancelled: false };
+      const job = { fn, onError, token, resolve, reject };
+      job.abort = new Promise((_, fail) => { job.fail = fail; });
+      // Queued time counts too. Attach a handler before the job becomes active.
+      job.abort.catch(() => {});
+      const abort = code => {
+        if (token.cancelled) return;
+        token.cancelled = true;
+        token.reason = code;
+        const error = fault(code);
+        job.fail(error);
+        if (this.active !== job) {
+          this.queue = this.queue.filter(item => item !== job);
+          clearTimeout(job.timer);
+          job.cleanup();
+          reject(error);
+        }
+      };
+      const onAbort = () => abort('RECALL_CANCELLED');
+      job.cleanup = () => signal?.removeEventListener('abort', onAbort);
+      job.timer = setTimeout(() => abort('RECALL_TIMEOUT'), this.timeoutMs);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      this.queue.push(job);
+      if (signal?.aborted) onAbort();
+      void this._pump();
+    });
+  }
+  async _pump() {
+    if (this.active || this.closed) return;
+    const job = this.queue.shift();
+    if (!job) return;
+    this.active = job;
+    try { job.resolve(await Promise.race([job.fn(job.token), job.abort])); }
+    catch (error) {
+      clearTimeout(job.timer);
+      if (job.token.cancelled) await this._stopWorker(false);
+      // Fallback occupies the same admission slot; index failure cannot turn a
+      // bounded recall queue into unbounded concurrent authoritative reads.
+      try { job.resolve(await job.onError(error)); }
+      catch (fallbackError) { job.reject(fallbackError); }
+    }
+    finally {
+      clearTimeout(job.timer);
+      job.cleanup();
+      if (job.token.cancelled) await this._stopWorker(false);
+      this.active = null;
+      void this._pump();
+    }
+  }
+
+  _getWorker() {
+    if (this.worker) return this.worker;
+    // onnxruntime-node cannot reliably reload its native addon in a replacement
+    // worker_thread. A managed process also makes blocked native inference killable.
+    const worker = fork(new URL('./local-memory-host.js', import.meta.url), [], {
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'], serialization: 'advanced',
+      // Older supported Node 22 requires this flag; do not inherit --input-type or test loaders.
+      execArgv: process.execArgv.filter(arg => arg === '--experimental-sqlite'),
+    });
+    this.worker = worker;
+    worker.send({ init: this.options });
+    worker.unref();
+    worker.channel?.unref();
+    worker.on('message', message => {
+      if (this.worker !== worker || this.rpc?.id !== message.id) return;
+      const rpc = this.rpc;
+      this.rpc = null;
+      worker.unref();
+      worker.channel?.unref();
+      if (message.error) rpc.reject(fault(message.error.code));
+      else rpc.resolve(message.value);
+    });
+    const failed = () => {
+      if (this.worker !== worker) return;
+      this.worker = null;
+      this.rpc?.reject(fault('INDEX_WORKER_FAILED'));
+      this.rpc = null;
+      worker.unref();
+      worker.kill('SIGKILL');
+    };
+    worker.on('error', failed);
+    worker.on('exit', failed);
+    return worker;
+  }
+  _call(token, op, owner, args = {}) {
+    this._alive(token);
+    const worker = this._getWorker();
+    return new Promise((resolve, reject) => {
+      const id = ++this.nextId;
+      this.rpc = { id, resolve, reject };
+      worker.ref();
+      worker.channel?.ref();
+      worker.send({ id, op, owner, ...args }, error => { if (error) reject(fault('INDEX_WORKER_FAILED')); });
+    });
+  }
+  async _catchUp(owner, token) {
+    let after = await this._call(token, 'checkpoint', owner);
+    for (let page = 0; page < this.maxJournalPages; page++) {
+      this._alive(token);
+      const changes = await this.repository.searchChanges(owner, { after, limit: this.journalBatchSize });
+      this._alive(token);
+      if (!changes || !Array.isArray(changes.items) || changes.items.length > this.journalBatchSize || !Number.isSafeInteger(changes.lastSeq)) throw fault('INVALID_JOURNAL');
+      if (changes.items.length || changes.lastSeq !== after) await this._call(token, 'apply', owner, changes);
+      if (!changes.hasMore) return { checkpoint: changes.lastSeq, caughtUp: true };
+      if (changes.lastSeq <= after) throw fault('INVALID_JOURNAL');
+      after = changes.lastSeq;
+    }
+    return { checkpoint: after, caughtUp: false };
+  }
+  _prune() {
+    for (const [id, snapshot] of this.snapshots) if (snapshot.expires <= Date.now()) this.snapshots.delete(id);
+    while (this.snapshots.size >= this.maxSnapshots) this.snapshots.delete(this.snapshots.keys().next().value);
+  }
+  _save(snapshot, position) {
+    this._prune();
+    const id = randomBytes(16).toString('hex');
+    this.snapshots.set(id, { ...snapshot, expires: Date.now() + this.snapshotTtlMs });
+    return `lm:${id}:${position}`;
+  }
+  _cursor(request) {
+    if (typeof request.cursor !== 'string' || request.cursor.length > 128) throw fault('INVALID_CURSOR');
+    const match = /^lm:([a-f0-9]{32}):(\d{1,6})$/.exec(request.cursor);
+    const snapshot = match && this.snapshots.get(match[1]);
+    if (!snapshot || snapshot.expires <= Date.now() || snapshot.ownerId !== request.ownerId || snapshot.kind !== request.kind || snapshot.query !== request.query) throw fault('INVALID_CURSOR');
+    const position = Number(match[2]);
+    if (!Number.isSafeInteger(position) || position > (snapshot.refs?.length ?? 0)) throw fault('INVALID_CURSOR');
+    return { snapshot, position, id: match[1] };
+  }
+  async _recall(request, token) {
+    let snapshot, position = 0, id;
+    if (request.cursor) {
+      ({ snapshot, position, id } = this._cursor(request));
+      if (snapshot.literal) return this._literal({ ...request, cursor: snapshot.rawCursor }, snapshot.reason, token);
+    } else {
+      const journal = await this._catchUp(request.ownerId, token);
+      const result = await this._call(token, 'search', request.ownerId, { kind: request.kind, query: request.query });
+      this._alive(token);
+      if (result.resetWorker) await this._stopWorker(false);
+      this._alive(token);
+      snapshot = { ...request, refs: result.refs, retrieval: { ...result.retrieval, journal } };
+      if (!journal.caughtUp) {
+        snapshot.retrieval.degraded = true;
+        snapshot.retrieval.reasons.push('journal_catchup_limited');
+      }
+    }
+    const items = [];
+    // Resolve every page against current authority. Stale/deleted revisions are omitted,
+    // never replaced with text from a newer, unranked revision.
+    while (position < snapshot.refs.length && items.length < request.limit) {
+      const refs = snapshot.refs.slice(position, position + request.limit - items.length);
+      const records = await this.repository.resolveMemories(request.ownerId, request.kind, refs);
+      this._alive(token);
+      const current = new Map(records.map(record => [record.id, record]));
+      for (const ref of refs) {
+        const record = current.get(ref.id);
+        if (record?.revision === ref.revision) items.push(record);
+      }
+      position += refs.length;
+    }
+    const nextCursor = position < snapshot.refs.length ? (id ? `lm:${id}:${position}` : this._save(snapshot, position)) : null;
+    return { items, nextCursor, retrieval: { ...snapshot.retrieval, snapshot: true, expiresInMs: this.snapshotTtlMs } };
+  }
+  async _literal(request, reason, token, signal) {
+    if (this.closed) throw fault('MEMORY_CLOSED');
+    if (signal?.aborted) throw fault('RECALL_CANCELLED');
+    let timer, onAbort;
+    try {
+      const result = await Promise.race([
+        this.literalRecall(request.ownerId, { kind: request.kind, query: request.query, cursor: request.cursor, limit: request.limit }),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(fault('RECALL_TIMEOUT')), Math.min(this.timeoutMs, 10000)); }),
+        new Promise((_, reject) => {
+          onAbort = () => reject(fault('RECALL_CANCELLED'));
+          signal?.addEventListener('abort', onAbort, { once: true });
+          if (signal?.aborted) onAbort();
+        }),
+      ]);
+      if (token) this._alive(token);
+      if (signal?.aborted) throw fault('RECALL_CANCELLED');
+      if (this.closed) throw fault('MEMORY_CLOSED');
+      const nextCursor = result.nextCursor ? this._save({ ...request, literal: true, rawCursor: result.nextCursor, reason }, 0) : null;
+      return { ...result, nextCursor, retrieval: { mode: 'literal', semantic: false, degraded: true, reasons: [reason], bounded: true, snapshot: false } };
+    } finally { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); }
+  }
+  async _stopWorker(graceful = true) {
+    const worker = this.worker;
+    if (!worker) return;
+    this.worker = null;
+    this.rpc?.reject(fault('INDEX_WORKER_STOPPED'));
+    this.rpc = null;
+    worker.ref();
+    let timer;
+    try {
+      await new Promise(resolve => {
+        worker.once('exit', resolve);
+        timer = setTimeout(() => { worker.kill('SIGKILL'); resolve(); }, this.shutdownTimeoutMs);
+        if (graceful && worker.connected) worker.send({ id: -1, op: 'close' }, () => {});
+        else worker.kill('SIGKILL');
+      });
+    } finally { clearTimeout(timer); worker.unref(); worker.channel?.unref(); }
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.snapshots.clear();
+    for (const job of [...this.queue, ...(this.active ? [this.active] : [])]) {
+      clearTimeout(job.timer);
+      job.cleanup();
+      job.token.cancelled = true;
+      job.fail(fault('MEMORY_CLOSED'));
+      job.reject(fault('MEMORY_CLOSED'));
+    }
+    this.queue = [];
+    await this._stopWorker();
+  }
+}

package/yeaft/person/repository.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { bytes, digest, fail, LIMITS, PersonError, safeError } from './contracts.js';
+import { capabilityExperienceView, recordCapabilityExperience } from './capability-experience.js';
 
 const COLLECTIONS = ['persons', 'messages', 'episodes', 'states', 'concepts', 'concept_revisions', 'state_commits', 'traces'];
 const txOptions = { readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' }, readPreference: 'primary', maxCommitTimeMS: 5000, timeoutMS: 10000 };
@@ -172,7 +173,9 @@ export class MongoPersonRepository {
     });
   }
   fence(episode, withLease = true) {
-    return { ...this.scope(episode.ownerId), activeEpisodeId: episode.id, epoch: episode.epoch, leaseOwner: episode.workerId,
+    const scope = this.scope(episode.ownerId);
+    if (episode.namespace !== scope.namespace || episode.personId !== scope.personId) fail('STALE');
+    return { ...scope, activeEpisodeId: episode.id, epoch: episode.epoch, leaseOwner: episode.workerId,
       stateVersion: episode.baseStateVersion, controlVersion: episode.controlVersion, inputWatermark: episode.inputWatermark, ...(withLease ? fresh() : {}) };
   }
   async heartbeat(episode) {
@@ -186,6 +189,11 @@ export class MongoPersonRepository {
     return this.transaction(async session => {
       const p = await this.collections.persons.findOneAndUpdate(this.fence(episode), { $inc: { writeSerial: 1 } }, { session, returnDocument: 'after' });
       if (!p) fail('STALE');
+      const scope = this.scope(episode.ownerId);
+      const record = await this.collections.episodes.findOne({ ...scope, id: episode.id, status: 'running' }, { session });
+      if (!record) fail('STALE');
+      const experience = recordCapabilityExperience(p.capabilityExperience, record, kind, data, new Date().toISOString());
+      if (experience) await this.collections.persons.updateOne(scope, { $set: { capabilityExperience: experience } }, { session });
       return this.trace(session, p, episode.id, kind, data);
     });
   }
@@ -242,7 +250,8 @@ export class MongoPersonRepository {
       this.collections.concepts.find(scope).sort({ updatedAt: -1, id: 1 }).limit(12).toArray(),
     ]);
     const concepts = [...new Map([...focused, ...recent].map(c => [c.id, publicDoc(c)])).values()];
-    return { person: this.personView(p), state: publicDoc(state), messages: messages.reverse().map(publicDoc), concepts };
+    return { person: this.personView(p), capabilityExperience: capabilityExperienceView(p.capabilityExperience),
+      state: publicDoc(state), messages: messages.reverse().map(publicDoc), concepts };
   }
   async recall(ownerId, { kind = 'messages', query = '', cursor = null, limit = 5 }) {
     const scope = this.scope(ownerId);