@yeaft/webchat-agent 1.0.587 → 1.0.588

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/runtime.js

@@ -6,7 +6,7 @@ import { bytes, fail, LIMITS, PersonError, PROPOSAL_INSTRUCTIONS, reportedLineag
 const messageRef = m => `message:${m.id}:${m.revision}`;
 const conceptRef = c => `concept:${c.id}:${c.revision}`;
 
-/** Assemble bounded request copies. Omitting a record never deletes or truncates its MongoDB original. */
+/** Assemble bounded request copies. Omitting a record never deletes or truncates its durable original. */
 export function assembleContext({ snapshot, episode, provider, selection, previous, capabilityResult, remainingCalls, dependencyRefs = [] }) {
   const model = validateSelection(selection, provider.catalog);
   // UTF-8 bytes is a conservative text-token bound; reserve explicit envelope/output overhead.
@@ -21,7 +21,7 @@ export function assembleContext({ snapshot, episode, provider, selection, previo
     budget: { remainingCalls, maxOutputBytes: LIMITS.outputBytes },
     previousProposal: previous ?? null, capabilityResult: capabilityResult ?? null,
     messages: [], concepts: [], sourceRefs: [triggerRef], inheritedSourceRefs: dependencyRefs,
-    contextNotice: 'This is bounded short-term context, not all memory. Omitted records remain in MongoDB. Recall pages are scoped to this Person. A previous proposal is not committed state. Inherited source refs were read by an earlier call of this episode, not necessarily rendered here; recall again to check their content.',
+    contextNotice: 'This is bounded short-term context, not all memory. Omitted records remain in long-term storage. Recall pages are scoped to this Person. A previous proposal is not committed state. Inherited source refs were read by an earlier call of this episode, not necessarily rendered here; recall again to check their content.',
   };
   const sourceRefs = new Set([triggerRef, ...dependencyRefs]);
   const renderedRefs = new Set([triggerRef]);
@@ -158,7 +158,7 @@ export class PersonRuntime {
           await this.repository.append(episode, 'capability_started', { callId, capability: invocation, access: 'read-only' });
           try {
             signal.throwIfAborted();
-            capabilityResult = await abortable(capabilities.execute(invocation), signal);
+            capabilityResult = await abortable(capabilities.execute(invocation, { signal }), signal);
             await this.repository.append(episode, 'capability_result', { callId, capability: invocation, result: capabilityResult });
           } catch (error) {
             const safe = safeError(error, 'UNSUPPORTED');
@@ -170,7 +170,7 @@ export class PersonRuntime {
     } catch (error) {
       const safe = safeError(signal.aborted ? signal.reason : error, 'PROVIDER_FAILED');
       const status = safe.code === 'CANCELLED' ? 'cancelled' : safe.code === 'INTERRUPTED' || safe.code === 'STALE' ? 'interrupted' : 'failed';
-      // On database outage no local fallback is possible. Expired leases become durable interrupted records on next access.
+      // On authority failure no alternate memory store is used. Expired leases become durable interrupted records on next access.
       await this.repository.finish(episode, status, safe.code).catch(() => {});
     } finally {
       clearTimeout(timeout); clearInterval(heartbeat);

package/yeaft/person/service.js

@@ -1,28 +1,46 @@
 import { MongoPersonRepository } from './repository.js';
+import { SqlitePersonRepository } from './sqlite-repository.js';
+import { LocalPersonMemory } from './local-memory.js';
+import { selectPersonStorage, bindPersonStorage } from './storage.js';
 import { PersonRuntime } from './runtime.js';
 import { createPersonProvider } from './provider.js';
 import { fail, identifier, LIMITS, object, page, safeError, text } from './contracts.js';
 
 /**
- * One Mongo-backed Person per (namespace, authenticated ownerId). The transport MUST
+ * One durable Person per (namespace, authenticated ownerId). The transport MUST
  * supply authenticated ownerId, never accept it from a browser payload. URI/provider
  * secrets stay inside this Agent. Constructor and status never initiate model calls.
  * Native provider configuration is read from yeaftDir only (no Session initialization).
- * Inject MongoClient/config/adapter for isolated integration tests; no persistence fallback.
+ * SQLite is the local default; an existing Mongo URI retains Mongo. No authority fallback.
  */
 export function createPersonService(options = {}) {
   const { uri, dbName = 'yeaft_person', namespace = 'default', yeaftDir, MongoClient, config, adapter, allowedModels } = options;
   identifier(namespace);
   if (typeof dbName !== 'string' || !/^[a-zA-Z0-9_-]{1,63}$/.test(dbName)) fail('INVALID_REQUEST');
   if (uri != null && typeof uri !== 'string') fail('INVALID_REQUEST');
-  const configured = Boolean(uri?.trim());
+  const { storage, configured } = selectPersonStorage({ ...options, yeaftDir });
   const calls = options.maxCalls ?? LIMITS.calls;
   const timeoutMs = options.timeoutMs ?? LIMITS.timeoutMs;
   const leaseMs = options.leaseMs ?? LIMITS.leaseMs;
   if (!Number.isInteger(calls) || calls < 1 || calls > 8 || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 300000 ||
       !Number.isInteger(leaseMs) || leaseMs < 300 || leaseMs > 60000) fail('INVALID_REQUEST');
   if (allowedModels != null && (!Array.isArray(allowedModels) || !allowedModels.length || allowedModels.length > 8 || allowedModels.some(m => typeof m !== 'string'))) fail('INVALID_REQUEST');
-  const repository = new MongoPersonRepository({ uri, dbName, namespace, MongoClient, leaseMs });
+  const repository = !configured ? null : storage === 'mongodb'
+    ? new MongoPersonRepository({ uri, dbName, namespace, MongoClient, leaseMs })
+    : new SqlitePersonRepository({ yeaftDir, namespace, leaseMs });
+  const initialize = repository?.init.bind(repository);
+  let binding;
+  if (repository) repository.init = async () => {
+    if (!binding) binding = bindPersonStorage(yeaftDir, namespace, storage).catch(error => { binding = null; throw error; });
+    await binding;
+    return initialize();
+  };
+  const literalRecall = repository?.recall.bind(repository);
+  const memory = repository && storage === 'sqlite' ? new LocalPersonMemory({
+    repository, literalRecall, yeaftDir, namespace, embedding: options.embedding,
+  }) : null;
+  if (memory) repository.recall = (ownerId, args = {}, { signal } = {}) => args.query?.trim()
+    ? memory.recall(ownerId, args, { signal }) : literalRecall(ownerId, args);
   // Config/adapter are loaded per explicit episode, not a permanent stale cache.
   const getProvider = () => createPersonProvider({ yeaftDir, config, adapter, allowedModels, effortEnabled: options.effortEnabled });
   const runtime = new PersonRuntime({ repository, getProvider, budget: { calls, timeoutMs } });
@@ -34,13 +52,13 @@ export function createPersonService(options = {}) {
     if (typeof op !== 'string') fail('INVALID_REQUEST');
     if (op === 'status') {
       object(payload, []);
-      if (!configured) return { configured: false, reason: 'MongoDB is not configured for digital person.', storageReady: false, modelReady: false };
+      if (!configured) return { configured: false, storage, reason: 'Digital person storage configuration is missing.', storageReady: false, modelReady: false };
       try { await repository.init(); }
-      catch { return { configured: true, reason: 'Digital person storage is unavailable; a transaction-capable MongoDB replica set is required.', storageReady: false, modelReady: false }; }
+      catch (error) { return { configured: true, storage, reason: safeError(error).message, storageReady: false, modelReady: false }; }
       try {
         const provider = await getProvider();
-        return { configured: true, reason: null, storageReady: true, modelReady: true, models: provider.catalog, autonomySupported: false };
-      } catch { return { configured: true, reason: 'No permitted native model is configured for digital person.', storageReady: true, modelReady: false }; }
+        return { configured: true, storage, reason: null, storageReady: true, modelReady: true, models: provider.catalog, autonomySupported: false };
+      } catch { return { configured: true, storage, reason: 'No permitted native model is configured for digital person.', storageReady: true, modelReady: false }; }
     }
     if (!configured) fail('NOT_CONFIGURED');
     switch (op) {
@@ -93,7 +111,8 @@ export function createPersonService(options = {}) {
       closed = true;
       await Promise.allSettled([...requests]);
       await runtime.close();
-      await repository.close().catch(() => {});
+      await memory?.close();
+      await repository?.close().catch(() => {});
     },
   };
 }

package/yeaft/person/sqlite-repository.js

@@ -0,0 +1,123 @@
+import { Worker } from 'node:worker_threads';
+import { join, resolve } from 'node:path';
+import { digest, fail, identifier, PersonError, text } from './contracts.js';
+
+const storageError = code => {
+  const error = new PersonError(code);
+  // Keep transport errors independent of backend topology, SQL and local paths.
+  if (error.code === 'STORAGE_UNAVAILABLE') error.message = 'Digital person storage is unavailable.';
+  return error;
+};
+
+/** One worker/connection per repository, shared WAL authority across processes.
+ * ownerId must come from the authenticated transport, never a request payload.
+ * A worker crash/timeout fails this instance closed: pending outcomes may have
+ * committed, so callers reconcile with a NEW instance and the same idempotency key.
+ * No automatic retry, takeover, model dispatch or local-memory fallback occurs.
+ */
+export class SqlitePersonRepository {
+  constructor({ yeaftDir, namespace = 'default', leaseMs = 15000, busyTimeoutMs = 1000, requestTimeoutMs = 30000, maxPending = 256 } = {}) {
+    text(yeaftDir, 4096); identifier(namespace);
+    if (!Number.isInteger(leaseMs) || leaseMs < 1 || leaseMs > 60000 || !Number.isInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > 5000 ||
+        !Number.isInteger(requestTimeoutMs) || requestTimeoutMs < busyTimeoutMs + 100 || requestTimeoutMs > 120000 ||
+        !Number.isInteger(maxPending) || maxPending < 1 || maxPending > 4096) fail('INVALID_REQUEST');
+    this.namespace = namespace; this.leaseMs = leaseMs;
+    this.dbPath = join(resolve(yeaftDir), 'person', 'person.db');
+    this.options = { dbPath: this.dbPath, namespace, leaseMs, busyTimeoutMs };
+    this.requestTimeoutMs = requestTimeoutMs; this.maxPending = maxPending;
+    this.pending = new Map(); this.requests = new Set(); this.nextId = 0; this.closed = false; this.failed = false;
+  }
+  scope(ownerId) {
+    text(ownerId, 256);
+    return { ownerId, namespace: this.namespace, personId: `person-${digest([this.namespace, ownerId]).slice(0, 32)}` };
+  }
+  async init() {
+    if (this.closed) fail('CLOSED');
+    if (this.failed) throw storageError('STORAGE_UNAVAILABLE');
+    if (!this.initializing) this.initializing = new Promise((resolveReady, rejectReady) => {
+      const timer = setTimeout(() => this.breakWorker(), this.requestTimeoutMs); timer.unref();
+      this.rejectReady = error => { clearTimeout(timer); rejectReady(error); };
+      try {
+        this.worker = new Worker(new URL('./sqlite-worker.js', import.meta.url), { workerData: this.options });
+        this.worker.on('message', message => {
+          if (message.ready) { clearTimeout(timer); this.rejectReady = null; this.worker.unref(); resolveReady(); return; }
+          if (message.startupError) { this.breakWorker(); return; }
+          const pending = this.pending.get(message.id);
+          if (!pending) return;
+          this.pending.delete(message.id); clearTimeout(pending.timer);
+          if (!this.pending.size) this.worker.unref();
+          if (message.error) pending.reject(storageError(message.error)); else pending.resolve(message.result);
+        });
+        this.worker.on('error', () => this.breakWorker());
+        this.worker.on('exit', () => {
+          if (!this.closingWorker || this.pending.size) this.breakWorker();
+        });
+      } catch { this.breakWorker(); }
+    });
+    return this.initializing;
+  }
+  breakWorker() {
+    if (this.failed) return;
+    this.failed = true;
+    const error = storageError('STORAGE_UNAVAILABLE');
+    this.rejectReady?.(error); this.rejectReady = null;
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); }
+    this.pending.clear();
+    this.terminating = this.worker?.terminate().catch(() => {});
+  }
+  send(method, args) {
+    if (this.failed) return Promise.reject(storageError('STORAGE_UNAVAILABLE'));
+    return new Promise((resolveResult, reject) => {
+      const id = ++this.nextId;
+      const timer = setTimeout(() => this.breakWorker(), this.requestTimeoutMs); timer.unref();
+      this.pending.set(id, { resolve: resolveResult, reject, timer });
+      this.worker.ref();
+      try { this.worker.postMessage({ id, method, args }); }
+      catch { this.breakWorker(); }
+    });
+  }
+  async request(method, args) {
+    if (this.closed) fail('CLOSED');
+    if (this.requests.size >= this.maxPending) fail('BUSY');
+    const promise = (async () => { await this.init(); return this.send(method, args); })();
+    this.requests.add(promise);
+    try { return await promise; } finally { this.requests.delete(promise); }
+  }
+  async open(ownerId, name) { return this.request('open', [ownerId, name]); }
+  async getPerson(ownerId) { return this.request('getPerson', [ownerId]); }
+  async recover(ownerId) { return this.request('recover', [ownerId]); }
+  async admit(ownerId, input) { return this.request('admit', [ownerId, input]); }
+  async heartbeat(episode) { return this.request('heartbeat', [episode]); }
+  async append(episode, kind, data) { return this.request('append', [episode, kind, data]); }
+  async startCall(episode, data) { return this.request('startCall', [episode, data]); }
+  async finalizeCall(episode, data) { return this.request('finalizeCall', [episode, data]); }
+  async context(episode) { return this.request('context', [episode]); }
+  async recall(ownerId, options) { return this.request('recall', [ownerId, options]); }
+  async commit(episode, proposal, selection, callId, reportedSources = new Map()) { return this.request('commit', [episode, proposal, selection, callId, reportedSources]); }
+  async finish(episode, status, code) { return this.request('finish', [episode, status, code]); }
+  async cancel(ownerId, episodeId) { return this.request('cancel', [ownerId, episodeId]); }
+  async settings(ownerId, settings) { return this.request('settings', [ownerId, settings]); }
+  async list(ownerId, collection, options, filter) { return this.request('list', [ownerId, collection, options, filter]); }
+  async snapshot(ownerId) { return this.request('snapshot', [ownerId]); }
+  /** Ascending durable journal, scoped before paging. Empty pages retain after. */
+  async searchChanges(ownerId, options) { return this.request('searchChanges', [ownerId, options]); }
+  /** kind is 'messages'|'concepts'; returns a deduplicated array of current public records. */
+  async resolveMemories(ownerId, kind, refs) { return this.request('resolveMemories', [ownerId, kind, refs]); }
+  async close() {
+    if (!this.closing) {
+      this.closed = true;
+      this.closing = (async () => {
+        await Promise.allSettled([...this.requests]);
+        await this.initializing?.catch(() => {});
+        if (this.worker && !this.failed) {
+          this.closingWorker = true;
+          await this.send('close', []).catch(() => {});
+          // terminate also joins the worker if it already completed its normal exit.
+          await this.worker.terminate().catch(() => {});
+        }
+        await this.terminating;
+      })();
+    }
+    return this.closing;
+  }
+}

package/yeaft/person/sqlite-schema.js

@@ -0,0 +1,80 @@
+// Identifiers below are static application schema, never request-controlled SQL.
+export const TABLES = Object.freeze({
+  persons: { keys: [], columns: [] },
+  states: { keys: [], columns: ['version'] },
+  episodes: { keys: ['id'], columns: ['clientMessageId', 'inputWatermark', 'status', 'callFinalizeUntil'] },
+  messages: { keys: ['id'], columns: ['seq', 'revision', 'text'] },
+  concepts: { keys: ['id'], columns: ['revision', 'updatedAt', 'statement'] },
+  concept_revisions: { keys: ['id', 'revision'], columns: [] },
+  state_commits: { keys: ['version'], columns: ['id'] },
+  traces: { keys: ['id'], columns: ['seq'] },
+});
+
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS persons (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  record TEXT NOT NULL CHECK(json_valid(record)), PRIMARY KEY(namespace, ownerId, personId)
+) STRICT;
+CREATE TABLE IF NOT EXISTS states (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  version INTEGER NOT NULL, record TEXT NOT NULL CHECK(json_valid(record)),
+  PRIMARY KEY(namespace, ownerId, personId),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE TABLE IF NOT EXISTS episodes (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  id TEXT NOT NULL, clientMessageId TEXT NOT NULL, inputWatermark INTEGER NOT NULL,
+  status TEXT NOT NULL, callFinalizeUntil INTEGER,
+  record TEXT NOT NULL CHECK(json_valid(record)), PRIMARY KEY(namespace, ownerId, personId, id),
+  UNIQUE(namespace, ownerId, personId, clientMessageId),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE INDEX IF NOT EXISTS episodes_watermark ON episodes(namespace, ownerId, personId, inputWatermark DESC);
+CREATE INDEX IF NOT EXISTS episodes_drain ON episodes(namespace, ownerId, personId, status, callFinalizeUntil)
+  WHERE json_type(record, '$.openCall') IS NOT NULL;
+CREATE TABLE IF NOT EXISTS messages (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  id TEXT NOT NULL, seq INTEGER NOT NULL, revision INTEGER NOT NULL, text TEXT NOT NULL,
+  record TEXT NOT NULL CHECK(json_valid(record)), PRIMARY KEY(namespace, ownerId, personId, id),
+  UNIQUE(namespace, ownerId, personId, seq),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE UNIQUE INDEX IF NOT EXISTS messages_revision ON messages(namespace, ownerId, personId, id, revision);
+CREATE TABLE IF NOT EXISTS concepts (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  id TEXT NOT NULL, revision INTEGER NOT NULL, updatedAt INTEGER NOT NULL, statement TEXT NOT NULL,
+  record TEXT NOT NULL CHECK(json_valid(record)), PRIMARY KEY(namespace, ownerId, personId, id),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE UNIQUE INDEX IF NOT EXISTS concepts_revision ON concepts(namespace, ownerId, personId, id, revision);
+CREATE INDEX IF NOT EXISTS concepts_recent ON concepts(namespace, ownerId, personId, updatedAt DESC, id);
+CREATE TABLE IF NOT EXISTS concept_revisions (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  id TEXT NOT NULL, revision INTEGER NOT NULL, record TEXT NOT NULL CHECK(json_valid(record)),
+  PRIMARY KEY(namespace, ownerId, personId, id, revision),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE TABLE IF NOT EXISTS state_commits (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  version INTEGER NOT NULL, id TEXT NOT NULL, record TEXT NOT NULL CHECK(json_valid(record)),
+  PRIMARY KEY(namespace, ownerId, personId, version),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE TABLE IF NOT EXISTS traces (
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  id TEXT NOT NULL, seq INTEGER NOT NULL, record TEXT NOT NULL CHECK(json_valid(record)),
+  PRIMARY KEY(namespace, ownerId, personId, id), UNIQUE(namespace, ownerId, personId, seq),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+-- This journal is authority data, not a disposable search index. A committed seq is
+-- never reused, including after reopening; gaps between owners are intentional.
+CREATE TABLE IF NOT EXISTS memory_changes (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  namespace TEXT NOT NULL, ownerId TEXT NOT NULL, personId TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK(kind IN ('messages', 'concepts')), id TEXT NOT NULL,
+  revision INTEGER NOT NULL, record TEXT NOT NULL CHECK(json_valid(record)),
+  UNIQUE(namespace, ownerId, personId, kind, id, revision),
+  FOREIGN KEY(namespace, ownerId, personId) REFERENCES persons(namespace, ownerId, personId)
+) STRICT;
+CREATE INDEX IF NOT EXISTS memory_changes_scope ON memory_changes(namespace, ownerId, personId, seq);
+`;